Skip to content

Components: Add missing descriptions for design system components#79460

Merged
aduth merged 8 commits into
trunkfrom
add/missing-ds-component-descriptions
Jun 25, 2026
Merged

Components: Add missing descriptions for design system components#79460
aduth merged 8 commits into
trunkfrom
add/missing-ds-component-descriptions

Conversation

@aduth

@aduth aduth commented Jun 23, 2026

Copy link
Copy Markdown
Member

What?

Adds JSDoc descriptions for all components which are surfaced as design system components through the Storybook manifest file, which in turn are used by the @wordpress/design-system-mcp package.

In doing so, it also fixes missing component props for three components: ColorPicker, DataViews, and Navigator.

Why?

Descriptions are useful in order to understand what a component does and whether it's usage is applicable to a given use-case.

With AI agent workflows leveraging the @wordpress/design-system-mcp, descriptions are a particularly important part of the agent workflow, since an AI agent is instructed to get a list of components via the get_components tools before diving into individual component details with get_component_details. Since the only information surfaced on get_components listing is the component name and description, the description is a pivotal detail to cue an agent to retrieve more information if it would understand it to be relevant for a given request.

How?

Adds missing JSDoc documentation to components.

For a few of these, I had to employ the same workaround as in #77382 to ensure that the docgen tool correctly parses these components, via inline render configuration in the component stories. This should be temporary and may already be resolved upstream. Worth noting that this fixes a preexisting issue with these components props not being surfaced in the manifest (see "3/66 prop type errors" on live components HTML manifest).

Testing Instructions

Verify that built Storybook manifest parses all components successfully and all components have descriptions:

  1. Run npm run storybook:build
  2. Run open storybook/build/manifests/components.html
  3. Observe "66 components okay" (compare to "3/66 prop type errors" on live components HTML manifest)
  4. Observe every listed component has a description (compare to live components HTML manifest missing descriptions for affected components like ColorPicker, DataViews, etc.)

Verify that descriptions appear in live Storybook site:

  1. Run npm run storybook:dev
  2. In the launched Storybook site at http://localhost:50240/, navigate to a Storybook page for one of the affected components (e.g. ColorPicker)
  3. Observe that the Storybook shows a description

Screenshots or screencast

Screenshot 2026-06-23 at 4 29 18 PM

Use of AI Tools

Assessment and initial implementation (including descriptions themselves) with Claude Opus 4.8. Manual review and edits of most of the descriptions for readability and conciseness.

aduth added 3 commits June 23, 2026 16:13
The already-documented rationale for this override isn't specific to these few packages and should apply for any `.tsx` file throughout the project.
@aduth aduth added the [Type] Developer Documentation Documentation for developers label Jun 23, 2026
@aduth aduth requested review from a team and ajitbohra as code owners June 23, 2026 20:31
@aduth aduth added the Storybook Storybook and its stories for components label Jun 23, 2026
@aduth aduth requested a review from manzoorwanijk as a code owner June 23, 2026 20:31
@github-actions github-actions Bot added [Package] Components /packages/components [Package] DataViews /packages/dataviews labels Jun 23, 2026
@github-actions

github-actions Bot commented Jun 23, 2026

Copy link
Copy Markdown

Size Change: 0 B

Total Size: 7.51 MB

compressed-size-action

aduth added 2 commits June 23, 2026 16:42
… reuqire-param

Not all of these files are `.tsx`, so the pattern simplification inadvertently started checking some files previously overridden to ignore
@github-actions

github-actions Bot commented Jun 23, 2026

Copy link
Copy Markdown

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: ntsekouras <ntsekouras@git.wordpress.org>
Co-authored-by: ciampo <mciampini@git.wordpress.org>

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

@aduth

aduth commented Jun 23, 2026

Copy link
Copy Markdown
Member Author

Worth noting that this fixes a preexisting issue with these components props not being surfaced in the manifest (see "3/66 prop type errors" on live components HTML manifest).

Note that I'm actively working on a solution for better detection of this kind of problem through the issue tracked at #79415.

@aduth

aduth commented Jun 23, 2026

Copy link
Copy Markdown
Member Author

I'm not sure why the CHANGELOG CI check is failing for the theme package 🤔 I'm not touching the theme package.

Comment thread packages/components/src/color-picker/component.tsx Outdated
Comment thread tools/eslint/config.mjs
Comment thread packages/components/src/custom-select-control/index.tsx Outdated
Comment thread packages/components/src/number-control/index.tsx Outdated
aduth and others added 3 commits June 24, 2026 09:32
Co-Authored-By: Nik Tsekouras <16275880+ntsekouras@users.noreply.github.com>
Co-Authored-By: Marco Ciampini <1083581+ciampo@users.noreply.github.com>
Co-Authored-By: Marco Ciampini <1083581+ciampo@users.noreply.github.com>
@aduth

aduth commented Jun 25, 2026

Copy link
Copy Markdown
Member Author

I'm not sure why the CHANGELOG CI check is failing for the theme package 🤔 I'm not touching the theme package.

Found the issue and fixed separately: #79548

@ciampo ciampo left a comment

Copy link
Copy Markdown
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

LGTM 🚀

I don't have further feedback

@aduth aduth merged commit 3edd458 into trunk Jun 25, 2026
47 of 51 checks passed
@aduth aduth deleted the add/missing-ds-component-descriptions branch June 25, 2026 14:43
@github-actions github-actions Bot added this to the Gutenberg 23.6 milestone Jun 25, 2026
SainathPoojary pushed a commit to SainathPoojary/gutenberg that referenced this pull request Jun 29, 2026
…rdPress#79460)

* Components: Add missing descriptions for design system components

* Components: Add missing descriptions for design system components

* Automated Testing: Disable require-param for tsx files project-wide

The already-documented rationale for this override isn't specific to these few packages and should apply for any `.tsx` file throughout the project.

* Automated Testing: Restore Storybook wildcard extension for disabling reuqire-param

Not all of these files are `.tsx`, so the pattern simplification inadvertently started checking some files previously overridden to ignore

* Add CHANGELOG notes

* Components: Fix duplicate "by"

Co-Authored-By: Nik Tsekouras <16275880+ntsekouras@users.noreply.github.com>

* Use code formatting for component name in description

Co-Authored-By: Marco Ciampini <1083581+ciampo@users.noreply.github.com>

* Components: Clarify that NumberControl is an input

Co-Authored-By: Marco Ciampini <1083581+ciampo@users.noreply.github.com>

---------

Co-authored-by: Nik Tsekouras <16275880+ntsekouras@users.noreply.github.com>
Co-authored-by: Marco Ciampini <1083581+ciampo@users.noreply.github.com>

Co-authored-by: aduth <aduth@git.wordpress.org>
Co-authored-by: ntsekouras <ntsekouras@git.wordpress.org>
Co-authored-by: ciampo <mciampini@git.wordpress.org>
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

[Package] Components /packages/components [Package] DataViews /packages/dataviews Storybook Storybook and its stories for components [Type] Developer Documentation Documentation for developers

Projects

None yet

Development

Successfully merging this pull request may close these issues.

3 participants