Stories

Your design system is already readable. Your judgment is not.

Exporting tokens is the easy half, and every vendor in the category sells it. What decides whether a generated screen belongs to your product is the set of rules your team keeps in its head. Here is how to get those out.

This post is for teams who already have a design system. You have a token pipeline, a component library, a docs site somebody maintains, and a Figma file that mostly matches the code. You point Cursor or Claude Code at all of it, and the output comes back close. Close, and still not yours.

The instinct at that moment is that the system needs to be more machine-readable. Usually it is already readable enough. What is missing is not the assets. It is everything your team decided and never wrote down.

What survives the move

Start with the good news, because most of it survives intact. Tokens move cleanly: they are already named values in a file, and an agent reads a tokens.css or a Style Dictionary export without any help from you. Components move too, as long as they are real code with real props rather than a Figma library with a code story attached. Documentation moves in the sense that matters, which is that an agent will read your MDX faster and more completely than any new hire ever has.

This layer is the one every vendor in the category already addresses, and they are right to. Figma’s argument for design systems and MCP is that components, tokens, variables, and Code Connect mappings should reach the agent directly instead of being described to it. That is correct as far as it goes. The number in the same piece is the part worth sitting with: 68% of developers now use AI to write code, and 32% of designers and developers trust what comes out. Serving the assets faster does not close a trust gap that size, because the assets were never what the trust was about.

What has to be written down for the first time

Here is the test. Open your library and ask which of these it answers in a form something other than a person can act on. When does a destructive action need a confirm step, and when is undo enough. When does a table beat a card grid. When does a side panel beat a modal. Which variant does a secondary action take when it sits beside a primary one. What does the empty state say before any data exists, and who writes that sentence.

Your team answers these consistently. That consistency is why the product feels like one product. But the answers live in review comments, in a designer’s head, and in the tenth message of a thread from March. None of that is readable at generation time, so the agent decides for itself, on every screen, forever. That is what design system drift actually is. Not a broken token. A thousand small decisions made by something that never learned yours.

Writing them down is unglamorous, and it is the whole job. A usable rule is one sentence with a condition and a consequence: destructive and irreversible takes a confirm step, destructive and undoable takes a toast with undo. Anything vaguer than that is a preference, and an agent will treat it like one.

The audit: where your system is already ambiguous

Before writing rules, find where you do not have one. The fastest audit is adversarial. Give an agent your system and ask it for six screens your library does not obviously cover: a bulk destructive action, a partial failure, a permissions-denied state, a long-running job, a first-run surface with no data, a settings page with one dangerous switch. Then read what it chose. Every place it had to invent something is a decision your system never made, and inventing is exactly what it will keep doing in production.

Expect to find more than you would like. zeroheight’s Design Systems Report 2026 found 44% of teams describing their own system as unstable, and only 38% reporting moderate to widespread adoption across their organization. A system that most of the company has not adopted is usually a system whose rules were never explicit enough to adopt.

The failure has a measured shape on the code side too. GitClear’s 2026 maintainability research found duplicated code blocks up 81% against 2023, while properly moved or refactored code fell from 21% of changed lines to 3.8%. Agents approximate a component far more readily than they reuse one, and an ambiguous library hands them the excuse.

Running both until the agent stops guessing

Do not migrate. Migration implies your system is the thing that has to change, and it mostly does not. Keep it as the source of truth for what exists, and add the rules beside it as a second layer your agent reads at the same time. Nothing in your pipeline has to move for that to work.

Then close the loop, because a rule nobody checks is still a preference. The difference between a system an agent reads and a system an agent obeys is a verification step: something that looks at the generated screen and fails when it used a palette value directly, invented a component that already exists, or skipped the confirm step on a destructive action. That is the line between a readable design system and an agentic one.

This is where Aestheria, the design context layer, is useful to a team that already has a system, and it is not the part most people expect. You do not need our tokens, and you should keep your palette. What you can take is a worked example of the layer you are missing: rules written with conditions, patterns that document when not to use them, and checks that actually fail. Diff yours against it, keep what is yours, and steal the structure. That is the honest version of the pitch to a team who did the work already.

The agent stops guessing at the point where your judgment is as available to it as your hex values always were. Everything before that point is a faster way to produce screens nobody signed off on.

Read the MCP docs

Questions

How do I make my existing design system AI-readable?

Tokens and coded components are usually readable already: an agent parses a token export or a component with real props without extra work. The missing layer is the decision rules, written as conditions and consequences, such as when a destructive action needs a confirm step or when a side panel beats a modal. Publish those alongside the library and point the agent at both.

Do I have to replace my design system to use a design context layer?

No. The design system stays the source of truth for what exists, and the context layer adds the rules for when to use it. Both can be read by the same agent at generation time, so nothing in an existing token pipeline or component library has to move.

Why does an AI agent ignore my design system even when it can see it?

Seeing a component library tells an agent what exists, not which option is correct in a given situation. When a system leaves that ambiguous, the agent decides for itself and often builds a near-copy of a component rather than reusing the real one. GitClear measured duplicated code blocks rising 81% against 2023 while refactored code fell from 21% of changed lines to 3.8%.

How do I find the gaps in my design system before writing rules?

Run an adversarial audit. Ask an agent for six screens the library does not obviously cover, such as a bulk destructive action, a partial failure, a permissions-denied state, a long-running job, a first-run empty surface, and a settings page with one dangerous switch. Every choice it had to invent marks a decision the system never made explicit.

What makes a design rule usable by an agent?

A condition and a consequence in one sentence, specific enough to be checked. "Destructive and irreversible takes a confirm step; destructive and undoable takes a toast with undo" is usable. "Be careful with destructive actions" is a preference, and an agent will treat it as optional.