UI: Add component status notes to Storybook by aduth · Pull Request #77988 · WordPress/gutenberg

aduth · 2026-05-05T21:09:18Z

What?

Related: #76135

Updates Storybook stories in @wordpress/ui to add status indicators introduced in #74815.

Why?

To make it clearer which components are ready to use in Gutenberg, and what blockers remain for the components that are not ready yet.

Also serves as a good nudge to ourselves what remains before we can mark a component as stable, or even instances where there's no good reason for a component not to be stable already (e.g. "Icon").

This could also potentially allow us to surface some more nuance through the design system MCP (e.g. use X component for now, but Y component from @wordpress/ui will soon be available for use).

How?

Add componentStatus entry for each component story in @wordpress/ui:

Use 'stable' if already allowed via @wordpress/use-recommended-components allowlist
For every other component, use 'use-with-caution', cautioning use in Gutenberg with component-specific warnings based on blockers highlighted in Components: Add usage guidance for agents and Storybook #74815.

Use whereUsed: 'global' for every component, since all of these components are meant to be globally usable.

Testing Instructions

Verify in Storybook:

Run npm run storybook:dev
Go to http://localhost:50240/
Verify every "Docs" under "Design System" > "Components" components has a status indicator at the top

Review the individual component status notes. Do they make sense? If you disagree with a component's status, do we have the actual blockers tracked anywhere?

Screenshots or screencast

Examples:

Stable:

Use with caution:

Use of AI Tools

Implemented using Claude Code and Opus 4.7, pre-prompted with logic described in "How?" and iterations on specific status notes.

cc @grbicsanja

aduth · 2026-05-05T21:13:15Z

 import * as EmptyState from '../';

 const meta: Meta< typeof EmptyState.Root > = {
+	tags: [ 'manifest' ],


@retrofox Per #77765 (comment), I went ahead and added the tag here, as part of marking this "stable".

Thanks for letting me know. I've just started addressing it.

github-actions · 2026-05-05T21:13:27Z

The following accounts have interacted with this PR and/or linked issues. I will continue to update these lists as activity occurs. You can also manually ask me to refresh this list by adding the props-bot label.

If you're merging code through a pull request on GitHub, copy and paste the following into the bottom of the merge commit message.

Co-authored-by: aduth <aduth@git.wordpress.org>
Co-authored-by: retrofox <retrofox@git.wordpress.org>
Co-authored-by: ciampo <mciampini@git.wordpress.org>
Co-authored-by: mirka <0mirka00@git.wordpress.org>

To understand the WordPress project's expectations around crediting contributors, please review the Contributor Attribution page in the Core Handbook.

github-actions · 2026-05-05T21:49:06Z

Flaky tests detected in 7a9eaa7.
Some tests passed with failed attempts. The failures may not be related to this commit but are still reported for visibility. See the documentation for more information.

🔍 Workflow run URL: https://github.com/WordPress/gutenberg/actions/runs/25402465006
📝 Reported issues:

[Flaky Test] post title and content are editable and blocks can be inserted #77720 in /test/e2e/specs/editor/various/post-content-focus-mode.spec.js
[Flaky Test] should show correct homepage actions based on current homepage or posts page #77385 in /test/e2e/specs/site-editor/homepage-settings.spec.js
[Flaky Test] should update the HTML only for the latest navigation #77197 in /test/e2e/specs/interactivity/router-navigate.spec.ts

ciampo

LGTM 🚀

Maybe better to get a quick look also from @mirka who originally worked on adding statues for @wordpress/components too?

ciampo · 2026-05-06T09:50:54Z

+		componentStatus: {
+			status: 'use-with-caution',
+			whereUsed: 'global',
+			notes: 'Not yet recommended for use in Gutenberg core, pending review of popover compatibility. See [WordPress/gutenberg#76135](https://github.com/WordPress/gutenberg/issues/76135).',


Nit on the wording (here and everywhere else in the PR):

Suggested change

notes: 'Not yet recommended for use in Gutenberg core, pending review of popover compatibility. See [WordPress/gutenberg#76135](https://github.com/WordPress/gutenberg/issues/76135).',

notes: 'Not yet recommended for use in Gutenberg core, pending review of overlays compatibility. See [WordPress/gutenberg#76135](https://github.com/WordPress/gutenberg/issues/76135).',

Good reminder, I'll try to use "overlay" consistently for this purpose.

mirka · 2026-05-06T11:48:37Z

+		componentStatus: {
+			status: 'use-with-caution',
+			whereUsed: 'global',
+			notes: 'Not yet recommended for use in Gutenberg core, pending review of popover compatibility. See [WordPress/gutenberg#76135](https://github.com/WordPress/gutenberg/issues/76135).',


Good reminder, I'll try to use "overlay" consistently for this purpose.

mirka · 2026-05-06T11:49:38Z

+		componentStatus: {
+			status: 'stable',
+			whereUsed: 'global',
+		},


Is this necessary on this file?

mirka · 2026-05-06T11:51:22Z

 	component: Badge,
+	parameters: {
+		componentStatus: {
+			status: 'stable',


I've been wanting to change the word "stable" as is it doesn't apply to the @wordpress/ui package like it does to @wordpress/components. Can we change it (throughout the entire Storybook) to "recommended" or something?

mirka · 2026-05-06T11:52:39Z

+		componentStatus: {
+			status: 'use-with-caution',
+			whereUsed: 'global',
+			notes: 'Not yet recommended for use in Gutenberg core, pending review of style consistency with `@wordpress/components`, popover compatibility, and component set completeness. See [WordPress/gutenberg#76135](https://github.com/WordPress/gutenberg/issues/76135).',


Suggested change

notes: 'Not yet recommended for use in Gutenberg core, pending review of style consistency with `@wordpress/components`, popover compatibility, and component set completeness. See [WordPress/gutenberg#76135](https://github.com/WordPress/gutenberg/issues/76135).',

notes: 'Not yet recommended for use in Gutenberg core, pending review of style consistency with `@wordpress/components`. See [WordPress/gutenberg#76135](https://github.com/WordPress/gutenberg/issues/76135).',

mirka · 2026-05-06T11:53:07Z

+		componentStatus: {
+			status: 'use-with-caution',
+			whereUsed: 'global',
+			notes: 'Not yet recommended for use in Gutenberg core, pending review of style consistency with `@wordpress/components`, popover compatibility, and component set completeness. See [WordPress/gutenberg#76135](https://github.com/WordPress/gutenberg/issues/76135).',


Suggested change

notes: 'Not yet recommended for use in Gutenberg core, pending review of style consistency with `@wordpress/components`, popover compatibility, and component set completeness. See [WordPress/gutenberg#76135](https://github.com/WordPress/gutenberg/issues/76135).',

notes: 'Not yet recommended for use in Gutenberg core, pending review of style consistency with `@wordpress/components`, and component set completeness. See [WordPress/gutenberg#76135](https://github.com/WordPress/gutenberg/issues/76135).',

mirka · 2026-05-06T11:53:20Z

+		componentStatus: {
+			status: 'use-with-caution',
+			whereUsed: 'global',
+			notes: 'Not yet recommended for use in Gutenberg core, pending review of style consistency with `@wordpress/components`, popover compatibility, and component set completeness. See [WordPress/gutenberg#76135](https://github.com/WordPress/gutenberg/issues/76135).',


Suggested change

notes: 'Not yet recommended for use in Gutenberg core, pending review of style consistency with `@wordpress/components`, popover compatibility, and component set completeness. See [WordPress/gutenberg#76135](https://github.com/WordPress/gutenberg/issues/76135).',

notes: 'Not yet recommended for use in Gutenberg core, pending review of style consistency with `@wordpress/components`, and component set completeness. See [WordPress/gutenberg#76135](https://github.com/WordPress/gutenberg/issues/76135).',

mirka · 2026-05-06T11:58:11Z

+		componentStatus: {
+			status: 'use-with-caution',
+			whereUsed: 'global',
+			notes: 'Not yet recommended for use in Gutenberg core, pending review of popover compatibility. See [WordPress/gutenberg#76135](https://github.com/WordPress/gutenberg/issues/76135).',


Suggested change

notes: 'Not yet recommended for use in Gutenberg core, pending review of popover compatibility. See [WordPress/gutenberg#76135](https://github.com/WordPress/gutenberg/issues/76135).',

notes: 'Not yet recommended for use alongside components from `@wordpress/components`, pending review of popover compatibility. See [WordPress/gutenberg#76135](https://github.com/WordPress/gutenberg/issues/76135).',

Would it be confusing if we worded it something like this? To be precise, it's not a "Gutenberg core" problem but a "mixed use with @wordpress/components" problem.

aduth added 3 commits May 5, 2026 16:12

UI: Add component status indicators

71b8008

UI: Mark EmptyState as stable

09bac05

UI: Update component status to reflect cautionary use with note

7a9eaa7

aduth requested a review from a team as a code owner May 5, 2026 21:09

aduth added [Type] Developer Documentation Documentation for developers [Package] UI /packages/ui labels May 5, 2026

aduth commented May 5, 2026

View reviewed changes

ciampo approved these changes May 6, 2026

View reviewed changes

mirka reviewed May 6, 2026

View reviewed changes

	notes: 'Not yet recommended for use in Gutenberg core, pending review of popover compatibility. See [WordPress/gutenberg#76135](https://github.com/WordPress/gutenberg/issues/76135).',
	notes: 'Not yet recommended for use in Gutenberg core, pending review of overlays compatibility. See [WordPress/gutenberg#76135](https://github.com/WordPress/gutenberg/issues/76135).',

	notes: 'Not yet recommended for use in Gutenberg core, pending review of popover compatibility. See [WordPress/gutenberg#76135](https://github.com/WordPress/gutenberg/issues/76135).',
	notes: 'Not yet recommended for use alongside components from `@wordpress/components`, pending review of popover compatibility. See [WordPress/gutenberg#76135](https://github.com/WordPress/gutenberg/issues/76135).',

Conversation

aduth commented May 5, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

What?

Why?

How?

Testing Instructions

Screenshots or screencast

Use of AI Tools

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

github-actions Bot commented May 5, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Uh oh!

github-actions Bot commented May 5, 2026

Uh oh!

ciampo left a comment

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

4 participants

aduth commented May 5, 2026 •

edited

Loading

github-actions Bot commented May 5, 2026 •

edited

Loading