What makes a design system AI-ready

AI-readiness is not a layer you add to a design system. It is a test that reveals whether your decisions were ever explicit in the first place.

Every team I talk to about AI and design systems starts from the same question: what do we need to add? A new documentation format, a metadata layer, an MCP server, an agent file at the root of the repo. The premise is that the system is fine and the machine needs an adapter.

The premise is wrong. AI-readiness is a quality standard, not a feature. It describes system decisions that are clear enough for three audiences at once: the people using the system, the code implementing it, and the AI assisting the work. Clear enough, too, for the accessibility requirements that have to survive all three. If a decision is only legible to one of them, it was never really a decision. It was a habit.

AI guessing is a diagnostic, not a defect

When an assistant invents a spacing value, picks the wrong variant, or writes a component that ignores your focus conventions, the instinct is to blame the model. It is more useful to treat it as instrumentation.

An AI has no institutional memory, no hallway to walk down, no sense of who to ask. It has exactly what you gave it. So when it guesses, it is telling you something precise: at this point in the system, the decision was not written down anywhere it could reach. A human on your team would have guessed too; they would just have guessed better, because they were in the meeting.

The reflex is measurable outside design systems too. Across 576,000 generated code samples, a USENIX Security study found that at least 5.2% of the packages commercial models suggested did not exist, and 21.7% of the ones open-source models suggested: 205,474 distinct names, invented, plausible, and confidently written into an install command. Nothing in the output marks the difference between a real dependency and a fabricated one. That is the same failure mode as a wrong variant, and it has the same cause: fluency where grounding was missing.

That is the reframe worth holding onto. The AI is not a new consumer with unusual requirements. It is the first consumer that cannot fill in your gaps with context you never wrote down, and it fails loudly enough that you notice.

The loop matters more than any single artifact. System work produces shared context. Context constrains what the AI reaches for. A human reviews the output. The reviewed output feeds back into the system. Break the last link and you get drift at machine speed: output that looks plausible, ships, and quietly becomes the new precedent nobody agreed to.

Three ways a decision fails to reach the machine

Not all gaps are the same, and they do not have the same fix.

Missing

The decision was never made. There is no rule about when to use a modal versus a drawer; each team improvised and the improvisations mostly agree. This is the honest case, and the least common in mature systems; you usually find it fast, because humans ask about it too.

Disconnected

The decision exists but lives somewhere the machine cannot reach: a Figma comment, a Slack thread, a closed pull request, someone’s head. This is the most common failure by far, and the most misdiagnosed. Teams look at their documentation site, see it is thorough, and conclude they are covered. The documentation is thorough about what. The reasoning is in the thread.

Stale

The decision was written down, then superseded, and the old version is still the most findable one. This is the most dangerous of the three, because the AI will apply it confidently and correctly, to a rule you abandoned eighteen months ago. Nothing in the artifact says it expired.

The practical consequence: an audit that counts coverage will miss two of the three. You need to ask not “is this documented?” but “could someone with no access to us apply this correctly?”

Documentation is not context

This distinction does more work than any tooling choice.

Documentation is written for a reader who can ask a follow-up question. It can be partial, because the gaps get closed in conversation. It can assume shared vocabulary, because the reader works here. It can describe the happy path and leave the edge cases to judgment, because the reader has judgment.

Context has to be self-sufficient. It carries the decision, the reasoning behind it, the trade-off it resolves, the cases where it does not apply, and its relationship to the decisions around it. No follow-up question is coming.

Most design system documentation is genuinely good documentation and genuinely poor context. A component page that shows every variant with a clean API table and no statement of when to choose which is complete by documentation standards and useless by context standards. The AI will pick a variant. It has to pick something.

Four stages, and the order is not decorative

It helps to organise the work into four stages: Define, Create, Adopt, Evolve. What makes the sequence useful is that each stage produces the context the next one consumes.

Define sets direction: goals, principles, scope, architecture, ownership. This is the stage teams skip, because it produces no artifact you can screenshot. It is also the stage whose absence is most visible downstream. When principles are slogans rather than trade-off guidance, every decision after them gets re-litigated.

Create turns direction into decisions and implementation: foundations, tokens, components, design-code alignment, documentation. This is where most teams start, and starting here is why so many systems end up as well-built component libraries that nobody can explain.

Adopt puts the system into use: release, communication, enablement, contribution, governance. Adoption failures are almost never quality failures. They are context failures: teams cannot tell whether the system covers their case.

Evolve closes the loop: metrics, feedback, maintenance, deprecation, prioritisation. Deprecation is the one to watch. Mature systems give it a published window: eighteen months at Salesforce, three to six at the Financial Times. An undeprecated pattern is a stale decision waiting to be confidently applied.

Tokens are where AI-readiness pays first

If you only fix one area, fix token semantics. Not the values. The naming.

A token called --gray-400 tells a machine one thing: a colour. A token called --color-border-subtle tells it where the value belongs, what it means, and what happens when the palette changes. The first is a variable. The second is a decision.

:root {
  /* One value today. Two decisions, so two names. */
  --color-border-subtle: var(--gray-400);
  --color-separator: var(--gray-400);
}

One token pointing at another is not a workaround, it is the shape the format settled on: the Design Tokens Community Group calls it an alias in its Format Module, which reached its first stable version in October 2025.

Merging those two is the tempting mistake. The day the separator needs more contrast, one name changes and nothing else moves. Had they been a single token, you would be auditing every usage by hand to work out which ones meant separator. The name is not a label on the value. It is the only place the decision lives.

The payoff compounds because tokens are the most-referenced surface in the system. Every component, every generated snippet, every review touches them. Ambiguity there is ambiguity everywhere, and clarity there propagates for free.

The same logic applies to component APIs. A prop named variant accepting "primary" | "secondary" requires the machine to already know your hierarchy. A prop named emphasis accepting "high" | "low" carries its own semantics.

The readiness test

The most transferable tool here is a test rather than a checklist. For any area of the system, give an assistant the context you believe is sufficient, then ask it to make a decision that requires applying that context, not recalling it.

The instruction that makes the test work is the second one: flag missing context, do not invent it. Without that, the model fills gaps silently and the test always passes.

A reliable answer applies your stated rule, explains the trade-off in your terms, and names what it could not determine. An unreliable answer is fluent, generic, and confident; it reaches for what most design systems do, because that is all it had.

Run this against your own system on a real decision you argued about last quarter. The result is usually uncomfortable and always specific.

Clarity before completeness

The position most likely to be ignored is that coverage is not the goal.

Adding documentation to an ambiguous system multiplies the ambiguity; now there are more places for the machine to find a partial answer and stop looking. Expanding a token set with unclear semantics produces more variables with the same problem. Volume amplifies whatever quality is already there.

The order that works: make the decisions you already have explicit, connected, and current. Then expand. A system with forty well-specified components beats one with two hundred that need a translator.

This is also the answer to “we do not have time for this”. You are not being asked to document everything. You are being asked to pick the three to five gaps that are hurting you now, name an owner and a next action for each, and leave the rest alone until it hurts.

What this actually asks of a design system team

Nothing new, which is the point, and also the difficulty.

Every practice AI-readiness demands was already good practice: state your principles as trade-offs, name tokens for meaning, write down why a pattern was deprecated, keep design and code in agreement about semantics. Teams skipped them because the cost of skipping was diffuse and deferred. Someone would ask, someone would know, the system would hold.

What changed is the feedback loop. The cost is no longer diffuse. It shows up as a wrong component in a pull request on a Tuesday, traceable to a decision nobody wrote down. That is not a new problem. It is an old problem with a much shorter delay between cause and effect.

Which, if you build design systems, is the most useful thing that could have happened to the discipline.