Contracts instead of essays: describing components in a machine-readable way

Storybook pages and Markdown documents are written for people. A language model first has to extract the rule from a large amount of text and encounters wording that leaves room for interpretation.

“The button supports variants such as primary, secondary, and danger. Please use danger sparingly” is a clear instruction to a person. An agent, however, may conclude from it that there are probably more variants and that “sparingly” is a matter of interpretation.

What belongs in a component contract

1. Fixed value lists. Only primary, secondary, ghost, and danger are allowed. An invented variant="warning" is detected as soon as the value list is stored as a TypeScript type or schema and checked.
2. The purpose of each value. danger: only for actions that can't be undone.
3. Prohibited combinations. What must not occur together is explicitly recorded.
4. Binding to tokens and accessibility. The contract specifies which semantic variables the component uses and which ARIA states it sets.

Whether this exists as a JSON Schema, as TypeScript types, or as a structured header in a Markdown file is secondary. What counts is that values and combinations can be checked by machine and that the purpose is stated unambiguously. The list is intended as a recommendation and is not a standard.

Looking things up selectively

The second question is how the agent obtains this description. Atlassian has published a direct comparison. The same design system was provided once as a single file in the context (DESIGN.md, an open format from Google), and once via its own MCP server and its own skills, where the agent retrieves only what it needs at the moment.

As a result, for a production code task, a login screen, the file needed about 92 percent more tokens and more runs than the MCP server. The team gives three reasons for this. First, the file loads all content at once. Second, condensing everything into one file meant dropping a large share of the usage rules for more than 50 components. Third, agents more often rebuilt existing components when there was no pointer to the available building blocks.

For quick prototypes, the same team explicitly rates the file as useful. This does not amount to a blanket verdict in favor of the MCP server. The closer a task is to production code, the more selective lookup pays off.

This, too, is one team's measurement on one system, and the team itself explicitly describes the results as not conclusive. They nevertheless show what to pay attention to.

From the series “Design Systems and AI”. Previous: Three design systems that have opened up to agents. Next: Tokens instead of guessed color values.