Your design system has a new reader

A design system used to have two readers. Designers used it in Figma, and engineers used it in code. Now it has a third: the AI tools that write code and build screens.

At Bliss Point, I built our design system from scratch. It has about 100 components, built with engineering in Storybook, and engineers reuse them to ship first versions of tools without design help. Now I’m leading the work to make it readable by AI. We’re designing a feature where people describe the dashboard they need and AI builds it from our own components. That only works if the AI knows which components exist and when to use each one.

AI guesses when it can’t read the rules

In my last post I said to assume nobody reads. AI is the exception. It reads everything you give it, and it guesses at everything you don’t.

In 2024, researchers at UNSW, CSIRO’s Data61 and HKUST checked 20 projects built with Vercel’s v0 against Google’s Material Design 3 guidelines. They found about 9.8 broken guidelines per project. Code from six popular GitHub projects had about 1.7. When they gave the model the right guidelines for each component and asked it to fix the page, it caught about 9 in 10 of the problems. Twenty-six people rated the fixed pages more attractive, 3.9 out of 5 compared with 3.0 before (Yuan et al., DesignRepair, ICSE 2025).

An earlier study found the same thing for code in general. When a model looked up the relevant documentation before writing code, its first answers worked about 52% more often (Zhou et al., DocPrompting, ICLR 2023). Models do better work when the rules are in front of them at the moment they need them.

What AI-readable means

Tokens named for what they do. color-text-danger tells a model when to use it. red-500 doesn’t. The W3C Design Tokens Community Group released the first stable version of its token format in October 2025, and Figma, Penpot, Sketch and Framer are among the tools that support it or are adding support (W3C). When tokens follow the shared format, any tool or agent can read the same file.

The same names everywhere. If a button’s size is small, medium or large in Figma, it’s the same in code. An AI matching a design to code shouldn’t have to translate.

Metadata for every component. Each component says what it’s for, its props and defaults, and an example. Storybook can now generate a component manifest, a JSON file that lists each component’s name, description, props and usage examples. Storybook says it’s designed to help AI agents understand which components are available and how to use them. It’s still in preview (Storybook docs).

Usage rules in plain words. Write down when to use a component and when not to. For example: “Use a toast to confirm an action. Don’t use one for an error people need to fix.” People skim these notes. AI follows them.

Accessibility built into the components. Our components come with contrast checks and keyboard navigation, so anything built from them starts out accessible. A rule that lives in the component doesn’t depend on anyone, person or AI, remembering it.

Where to start

1. Start small. Pick the 10 components your team uses most.
2. Rename tokens by purpose. Swap names like blue-600 for names like color-action-primary.
3. Write one line per component on when to use it and one line on when not to.
4. Test it. Ask an AI tool to build a screen using only your system and watch where it guesses. Each guess marks a rule you haven’t written down yet.