how do you get ai agents to actually use your design system?
put it all in one place the agent can query. the component library, with the metadata, examples and automated enforcement inside it. for us that's storybook. a giant agents.md plus a separate markdown on how to use the components doesn't hold up.
what went wrong first
on one project the agent said it was using the right data grid component. the designer looked at the result and said no, that's not it. the grid wasn't documented well in the storybook, which was probably the reason. a teammate's read was simple: the main problem is that the design system is incomplete.
so before blaming the model, ask. is the design system amazing and the ai just got it wrong? what can be improved in the design system? does it have metadata? are the components properly described?
one place, not three
design.md is how components should look. storybook is which components the agent must use, with examples and automated enforcement.
it doesn't make much logical sense to have a component library, which can embed the metadata, plus a markdown on how to use it. if it can all be done in one place, do it all in the storybook. scalable, reliable, without reinventing the wheel.
and please no super long agents.md. that pollutes the context for every engineer working in the repo.
it's not just mcp
an mcp on top of the design system lets the agent query the component list, its metadata and the actual component code, so it doesn't have to guess how the components look. useful.
but it's not just mcp. it's the metadata and the tests that come with it. the goal is to make the design system knowledge discoverable and testable for any agent.
put the check in ci
visual review runs in ci. when you approve the changes in chromatic, the ci check passes and then you can merge. no approval, no merge.
how to know it works
take the old setup and the new one. same prompt, compare results