Components: Add missing descriptions for design system components#79460
Conversation
The already-documented rationale for this override isn't specific to these few packages and should apply for any `.tsx` file throughout the project.
|
Size Change: 0 B Total Size: 7.51 MB |
… reuqire-param Not all of these files are `.tsx`, so the pattern simplification inadvertently started checking some files previously overridden to ignore
|
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 If you're merging code through a pull request on GitHub, copy and paste the following into the bottom of the merge commit message. To understand the WordPress project's expectations around crediting contributors, please review the Contributor Attribution page in the Core Handbook. |
Note that I'm actively working on a solution for better detection of this kind of problem through the issue tracked at #79415. |
|
I'm not sure why the CHANGELOG CI check is failing for the |
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>
Found the issue and fixed separately: #79548 |
ciampo
left a comment
There was a problem hiding this comment.
LGTM 🚀
I don't have further feedback
…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>
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-mcppackage.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 theget_componentstools before diving into individual component details withget_component_details. Since the only information surfaced onget_componentslisting 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
renderconfiguration 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:
npm run storybook:buildopen storybook/build/manifests/components.htmlVerify that descriptions appear in live Storybook site:
npm run storybook:devScreenshots or screencast
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.