Replies: 2 comments 3 replies
|
Hi 👋🏼 At Trackunit, we've recently built tooling on top of Storybook that solves some of the challenges outlined in this RFC. Since we use our component library internally and also expose an SDK for external developers, we needed a way for AI agents like Cursor to easily discover and understand our public components. Our Evolution:
Current Implementation:
Our hosted MCP server exposes two tools that use these endpoints:
Props to @mta-trackunit for making v2 possible by hacking together the build time scripts :) |
|
This looks awesome, and is very close to what we're envisioning! I'd love to hear more about your work, your iterations, what have worked and what haven't - ie. if you have insights into specific structures/information that the LLM understand better than others. I'd also love to understand how you're achieving some this, how the Would you be open to a call where you demonstrate you work? This would be highly valuable to us and the Storybook community, as we're closing in on this. If so, you can book something here, or message me on Discord (JReinhold) or at jeppe@chromatic.com |
|
I work primarily with web components and I’ve found that the web component analyzer is a little better at providing valuable context to the agent than the custom elements manifest you have linked to above. I think if efforts were made to structure the manifest more closely to the output wca produces then you could have something there |
|
Oh that's interesting, I haven't heard of that before. Do you have any ideas on why it's better? Is it because the output is markdown, or is it getting other information that CEM isn't? |
|
i believe its the structure of the json object. its linguistically more logical to a language based llm if the structure of the output makes more sense in terms of words that it already uses to describe certain features of a component then it stands to reason that it would understand that structure much better than one that is only meant to serve the creation of storybook more effectively |
Uh oh!
There was an error while loading. Please reload this page.
🤖 Problem
A challenge today when using agents to build UI, is that they will often not use the appropriate design system correctly, but generate its own component or styling solution, not matching existing components. Your team has invested person years designing and building a beautiful and solid design system, but the LLM is constantly throwing all that away to use shadcn and Tailwind instead, because that’s all it knows.
Storybook is the preferred tool to build and document design systems in many teams, but it lacks a proper integration that exposes all the information to LLMs. Teams are also not able to build this themselves, because Storybook doesn’t expose this information in a raw format either.
Note
We’ve identified two separate uses of Storybook in relation to LLMs.
This experiment and RFC focuses on consumers of Storybook. That is not necessarily users that are building with Storybook (although they could be), but they are building UI and using a Storybook as documentation.
The other use case focuses on improving the development experience when using Storybook in a project - it is focused on the users that are building components with Storybook. We think that is a separate workflow to investigate, and we’re discussing it in the Agentic Workflow RFC
🧩 Proposed Solution
We propose a solution where Storybook exposes structured metadata about components that can serve as the basis for documentation in other tools. This metadata includes (but is not limited to):
We call this metadata Component Manifests, and it would be exposed as JSON endpoints on a Storybook dev server, and built as static JSON-files when building a Storybook.
Along with this metadata we propose a Design System MCP Server than consumes these Component Manifests and exposes them to the LLM in an LLM-friendly way. This could be a reference MCP server that advanced design system teams could use and distribute as it, or get inspiration from and fork as necessary.
The MCP server is intended for consumers of the Storybook, not the builders (although they could use it too if they want to). Therefore it doesn’t directly depend on Storybook, eg. an Applications Team that uses a design system but doesn’t use Storybook, can use the MCP server just fine, as long as the design system is built with Storybook.
📐 Proposed Architecture
An architecture for this workflow could be implemented like this:
components-manifest.json.localhost:6006/manifest/components.json./node_modules/my-design-system/manifest/components.json- For when the the DS distributes the manifest alongside the dist in the npm package../storybook-static/manifest/components.json- For when the user has the Storybook built locallyhttp://localhost:6006/manifest/components.json- For when running the Storybook dev server locallyhttps://my-storybook.chromatic.com/manifest/components.json- For when a DS’s Storybook is published to Chromatic or elsewhere.Our research shows that LLMs usages of design systems improve greatly when they have structured knowledge about what’s available. Just providing a list of components with short descriptions makes the final output better. As you add more details like listed above, the LLM (unsurprisingly perhaps) produces better and better results, and gets a better understanding of how to compose components and use the props correctly.
However we also saw improved output by just providing the LLM with flattened TypeScript types, that it referenced to use props correctly.
🔮 How Do We Get There?
The proposed solution requires a lot of effort to implement. We would need to make big architectural changes to Storybook’s core for this to work. That’s because 95 % of the metadata we want to expose is only available on the client today, and we need it on the server for this to work.
The following is a plan for how we can incrementally get to the solution, while still getting early validation that the solution is actually valuable in the end.
v0.0.1 - “Manifests” are just LLM-generated markdown
The first version of this doesn’t have to require Storybook at all. We can just get an LLM to generate these “manifests”, as plain markdown files, and consume them with the MCP server. The MCP server and architecture doesn’t do much more than just forward the markdown files.
And this is exactly what this repository is!
We’ve built this v0.0.1 as an experiment in this repository: We’ve prompted an LLM (Claude 4 Sonnet) to generate detailed documentation for all exports of the Reshaped design system package. We’ve then built a tiny MCP server that makes a list of all exports available, as well details for any component/utility that the LLM requests.
The generated documentation is not accurate, it’s not consistent, and it’s not exhaustive. It was both slow and costly to generate - 26 min wall time (using parallel sub-agents) and costing about $15. But our initial experiments indicates that it worked! An LLM that used the MCP server produced significantly better components than one that didn’t.
We’d love for you to try this out as well, and report what you find. You can find detailed instructions in the readme.
v0.0.2 - Manifests are LLM-generated structured JSON
We can take this a step further, and instead of generating plain-text markdown files as documentation, we can define a structured JSON output that the LLM must adhere to, as LLMs are generally good at following instructions on structure for the output. This won’t solve the problems of inaccuracy and inconsistency, but it will allow us to experiment with and iterate on the Component Manifest structure without having to go through the complexity of extracting real data.
The MCP server would then be close to the proposed solution, as it isn’t concerned with the quality of the metadata, just the structure.
v0.1.0 - Manifests are component list only, generated by Storybook
The minimal first version of Component Manifest as generated by Storybook could be just about the top-level component list itself. For all meta definitions in stories-files, we would:
This allows us to work on the fundamental Component Manifest generation, starting with the metadata that is the most easy to extract.
v0.2.0 - Add prop types and descriptions to components
The next iteration could be about getting component’s prop types, as a combination of users’ manual
argTypesand inferred via docgen. Today docgen - the process of automatically extracting prop types from components - runs in the builders (Vite, Webpack) and outputs the result to the rendered stories in the preview. We need to migrate the docgen to be server-side so the client isn’t necessary, and (statically) extractargTypesfrom stories-files.v1.0.0 - Add examples based on stories
The next iteration would be about providing examples of component usage, as described in stories. Story data like args, decorators would need to be extracted and converted to snippets (eg. for React it would be JSX), similar to what we generate for the “Show Code” panel in docs canvases today. Again, all this data and the code snippets are all generated in the browser, and we need to do that on the server instead.
v1.1.0 - Add MDX docs
We’d also want to collect users’ manually written MDX docs. Including them as-is might not be beneficial, as they could include complex components and imports that would make them invalid when read without the necessary context. We might need to render them to HTML or markdown first.
Attached MDX docs would have a natural place in the Component Manifest structure, but it’s unclear how unattached MDX docs would fit in here.
💬 Request For Comments
We’re asking for input and feedback here. We hope you’ll try the current experiment out even though it’s not useful in a real scenario yet. Please share thoughts and ideas on what could be improved, or other strategies that you’d like to see explored, etc. 🙏
🔍 Related Work
All reactions