Expose your design system to LLMs
1. Why do LLMs keep breaking design systems?
AI coding agents initially produce a fairly convincing UI, but as sessions repeat, the design gradually drifts.
- The reason is that LLMs do not really “understand” the design system; rather, they estimate plausible values each time.
- Card padding is 16px, elsewhere it is 12px
- Link colors are similar, but different blues
- Button radii also vary slightly from screen to screen
- Each individual choice does not seem very wrong, but when hundreds of small guesses accumulate, the result increasingly looks like a “strangely different product.”
- The bigger problem is that each new session cannot remember the previous judgment.
2. The solution is an “LLM-readable design system”
The key is not to let AI guess freely, but to provide a closed set of rules it can refer to every time.
- The original text organizes this into three layers.
- Spec files: Markdown documents that structure component usage, states, exceptions, and patterns
- Closed token layer: A structure that allows only `tokens.css` variables for colors, spacing, typography, radius, and so on
- Audit script: A verification script that catches AI hardcoding values in CI
- In other words, instead of making AI wonder, “Which blue should I use?”, you make it find and use `var(--color-link)`.
3. Practical application proceeds in 6 steps
This approach is closer to organizing an existing project in an LLM-friendly way than to a grand redesign.
- First, scan all CSS/SCSS files for hardcoded colors, spacing, font sizes, radii, and so on.
- Then create `tokens.css` and build a three-step structure that flows from higher-level design system tokens → project aliases → actual component usage.
- In the `specs/` folder, write separate documents for foundations, tokens, components, and patterns.
- Connect a verification script such as `token-audit.js` so that raw values cause a failure.
- Finally, add guidance to `CLAUDE.md` or `.cursorrules` such as, “Before modifying UI code, read the relevant spec, use only `tokens.css`, and pass the audit before committing.”
4. Good design systems are no longer read by humans alone
What is interesting in the original text is that it no longer sees the design system only as a document for people or a Figma library.
- In the AI era, a design system becomes both a component library and an execution specification that the model refers to each session.
- If documentation is missing, the LLM guesses, and when the guesses accumulate, the visual consistency of the product collapses.
- Conversely, when spec, token, and audit are connected, the results of the first AI session and the tenth AI session can maintain the same quality.
