design-system-mcp: Improve README overview and setup instructions#79238
Conversation
|
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. |
| <div class="callout callout-alert"> | ||
| <p class="callout callout-alert"> | ||
| This package is still experimental. “Experimental” means this is an early implementation subject to drastic and breaking changes. | ||
| </div> | ||
| </p> |
There was a problem hiding this comment.
<div> doesn't format very well on GitHub previews, which results in the description being hard to see and read, since it ends up looking like it's part of the same paragraph as the experimental notice.
| Before | After |
|---|---|
 |
 |
The specific element and class is relevant for how this ends up showing on the developer.wordpress.org package reference page, which appears to work just as well with a <p> tag when testing with some manual DevTools inspector manipulation:
There was a problem hiding this comment.
We should probably open a follow-up PR to update all markdown docs with similar callouts?
There was a problem hiding this comment.
We should probably open a follow-up PR to update all markdown docs with similar callouts?
Yeah, I think that makes sense. I'll confirm first that it looks okay on the developer site after merge.
| Install link: [cursor://anysphere.cursor-deeplink/mcp/install?name=wordpress-design-system&config=eyJjb21tYW5kIjoibnB4IC15IC0taWdub3JlLXNjcmlwdHMgLS1taW4tcmVsZWFzZS1hZ2U9MiBAd29yZHByZXNzL2Rlc2lnbi1zeXN0ZW0tbWNwQGxhdGVzdCJ9](cursor://anysphere.cursor-deeplink/mcp/install?name=wordpress-design-system&config=eyJjb21tYW5kIjoibnB4IC15IC0taWdub3JlLXNjcmlwdHMgLS1taW4tcmVsZWFzZS1hZ2U9MiBAd29yZHByZXNzL2Rlc2lnbi1zeXN0ZW0tbWNwQGxhdGVzdCJ9) | ||
|
|
There was a problem hiding this comment.
This link causes some weird layout issues in some environments that don't handle line wrapping as well, like the npm package preview:
It's also one more thing to maintain with the config being embedded as base64 in the URL. The install button should be fine for most people, I don't know if there's a particular advantage why someone would want to use this style of link instead.
|
Flaky tests detected in dd939ae. 🔍 Workflow run URL: https://github.com/WordPress/gutenberg/actions/runs/27640578551
|
ciampo
left a comment
There was a problem hiding this comment.
LGTM 🚀
Feel free to merge once feedback is addressed
| <div class="callout callout-alert"> | ||
| <p class="callout callout-alert"> | ||
| This package is still experimental. “Experimental” means this is an early implementation subject to drastic and breaking changes. | ||
| </div> | ||
| </p> |
There was a problem hiding this comment.
We should probably open a follow-up PR to update all markdown docs with similar callouts?
| </p> | ||
|
|
||
| An [MCP (Model Context Protocol)](https://modelcontextprotocol.io/) server for the WordPress Design System. Provides AI coding agents with component documentation, prop definitions, usage examples, and design tokens. | ||
| An [MCP (Model Context Protocol)](https://modelcontextprotocol.io/) server for the WordPress Design System. Provides AI agents with component documentation, usage examples, and design tokens. |
There was a problem hiding this comment.
Was the removal of "prop definitions" on purpose?
| An [MCP (Model Context Protocol)](https://modelcontextprotocol.io/) server for the WordPress Design System. Provides AI agents with component documentation, usage examples, and design tokens. | |
| An [MCP (Model Context Protocol)](https://modelcontextprotocol.io/) server for the WordPress Design System. Provides AI agents with component documentation, prop definitions, usage examples, and design tokens. |
There was a problem hiding this comment.
Was the removal of "prop definitions" on purpose?
It was on purpose, yes. I added some rationale to the extended commit description of 4132c54:
Largely covered through "component documentation" and not everyone would be familiar with (or frankly care about) React technical implementation specifics
Happy to revisit or refine if you have ideas. I think the main thing for me was "props" being a bit jargon-y to people not intimately familiar with the implementation details of the components (since the audience for the package includes non-engineers), and we could perhaps replace with "options" or "configuration" or something like that.
There was a problem hiding this comment.
No strong opinions, happy to omit
| - What components you should use for a certain type of interaction or user interface, like a button or a dropdown | ||
| - How to implement those components in code, following sample code from the design system documentation | ||
| - How to implement new components following the design system styling standards with design tokens |
There was a problem hiding this comment.
Very nitty, but the leading sentence to the bullet points sets up questions. We could therefore rephrase the bullet points as such, for example "Which components to use for a given interaction or UI element, like a button or dropdown"
Feel free to ignore, though.
There was a problem hiding this comment.
Good call. The first in particular didn't really flow seamlessly from the preceding sentence. Updated in rebased dd939ae. I think the rest are question-y enough to not seem out of place?
Clarify that the package is a self-contained MCP server
Avoid the text bumping into eachother in GitHub and npm previews
This doesn't format very well in every environment (e.g. npm detail)
The design system MCP server isn't only useful for coding, but also design and product development
Largely covered through "component documentation" and not everyone would be familiar with (or frankly care about) React technical implementation specifics
Co-Authored-By: Marco Ciampini <[email protected]>
5e6440e to
dd939ae
Compare
What?
Applies a handful of general improvements to the README instructions for the
@wordpress/design-system-mcppackage, each implemented as its own standalone commit with extended commit description for additional context.Why?
Testing Instructions
Review updated document for legibility and accuracy.
Use of AI Tools
No AI was used.