Repository navigation
Design System: Serve pattern guidance documents through the MCP server #82547
Description
What problem does this address?
The design system MCP server answers which component to use, but not when to use it. The cross-cutting pattern guidance that answers the second question already exists in the Storybook, and no tool serves it.
Two concrete cases:
1. A destructive action flow. I built an account settings screen with an agent, outside WordPress, with the MCP server as the only allowed source. The screen needed a delete-account flow. The MCP returned ConfirmDialog, but nothing about when to use it versus a Modal with a destructive button, so the agent guessed. The decision tree that answers exactly that already exists in destructive-actions.mdx.
2. Tooltip usage guidelines. Raised by @aduth in #80649 (comment): the author uses the MCP server, but since the Tooltip usage guidelines are not surfaced there, the agent missed the pattern.
Current state. packages/design-system-mcp registers three tools: get_components and get_component_details, which read the Storybook components manifest, and get_design_tokens, which reads packages/theme/docs/tokens.md. The pattern documents under storybook/stories/design-system/patterns/ are not reachable by any of them, and as a client-rendered application, the Storybook is not scrapeable by agents.
What is your proposed solution?
Publish the existing pattern documents in a manifest generated by the Storybook build, next to the components manifest it already publishes, and serve them through the MCP server:
get_patterns: list the available patterns with a short description each.get_pattern_details: return one pattern document as markdown.
Source of truth stays the existing .mdx files, with each entry's title and description taken from the document's own heading and introduction. No documentation is duplicated: the same document serves humans in the Storybook and agents through the MCP, and a new pattern is discovered automatically rather than registered by hand.
The server instructions should also tell clients to consult patterns before implementing a flow, since a tool that is never called does not close the gap.
Today that covers destructive-actions, error-messages and save-and-submit.
Follow-up, out of scope here
Per-component guidance (packages/ui/src/*/stories/usage-guidelines.mdx and best-practices.mdx) has the same problem, and is case 2 above. It fits better as an addition to get_component_details, since it is scoped to a component rather than cross-cutting. Worth a separate issue once the pattern case lands.
Activity
aduth commentedon Sep 15, 2026
#82984 surfaces a question about how we might want to think about differentiating skills and patterns:
Personally, in my own mental model of how we're employing "MCP = available resources, Skills = workflow descriptions", I think it could be reasonable to think of these as distinct things, even if they both generally answer the question of "how to use the design system". Patterns would describe specific combinations of components and guidance around how they should be used, and skills would describe steps to accomplish a particular task.