A design system is ready for AI when it is written down

A design system can hold hundreds of components and still leave the real questions open. Which value is the source? Which rule wins when two disagree? Who may change it?

People fill those gaps from memory and conversation. An AI tool fills them from whatever it has just read. If the system does not say, the tool guesses, and the guess looks plausible.

This is the position we hold, and the way we built our own site follows from it. AI can apply explicit decisions, relationships and constraints. It cannot replace missing context or human authority.

What we mean by ready

Ready does not mean controlled by AI. It does not mean a library of prompts either.

It means the decisions that matter are written in a place, in a form, that a person, a build script and an agent can all read. The team keeps the authority. The system keeps the reasons.

How our own system is written

This site is the example. Everything below is in the repository. These are observations about our setup, not results.

Values live in one file, and code is generated from it. Colours, type sizes, spacing, radii and motion durations are defined once, in a token file. A script turns that file into the CSS variables the site reads. The generated CSS is not edited by hand. A new value enters the token file first, then everything else follows.

Tokens carry roles, not only values. A colour is not "orange". It is the signal: one action per screen, or one data series. Text on it is ink. A grey is the muted label colour, darkened once so it passes the contrast threshold. The reason sits next to the value.

Rules are numbered, and each one names its source. Our design rules are short sentences with an identifier: one orange per viewport, no text under 14px, a title takes at most one serif accent. Each cites where it came from, whether a decision record, the tokens or a direction from the founder. A rule with a source can be questioned. A rule without one is just a preference.

Some rules are checked by machine. A script scans the code on every build. It fails on a raw colour value outside the generated tokens, on a placeholder left in public content, and on a radius that is not a token. That is the extent of it today. The one-orange and 14px rules are in the review checklist and listed as candidates for automated checks. They are not built yet. We would rather say that than imply the whole system is enforced.

A skill gives agents the short version. The repository holds a skill file that agents load before they design, build or review anything. It summarises the rules, lists what to read first, and ends with a do and don't table. It says plainly that the numbered rules and the token file win if it disagrees with them. The summary points to the source instead of replacing it.

Code leads and Paper mirrors. For this site the shipped code is the source. The design file is redrawn from the code after review. A new value goes into the token file first, then into the design tool. When the two drift, the drift goes into a conflicts log instead of being fixed without a record. That answers the question every team eventually asks: what happens when the design file and the code disagree?

The site is readable by agents on purpose. It publishes a Markdown brief and a short facts file built only from the same content files as the pages. They state what we do, how work starts and who to contact. They also state what an agent must not infer: no client results, no delivery times, no sending or booking on a person's behalf.

What changes with AI in the loop

Nothing about the system is new. What changes is the cost of vagueness.

A person who meets an unclear rule asks a colleague. A model applies the nearest pattern it has seen. If the system gives it a role, a source and a limit, it has something to apply and something its output can be checked against. If it gives it a screenshot, the model has to infer intent.

Our own conflicts log shows the same thing in small. The token file once said the display serif was for quotes only. A later decision allowed one accent per title. Both lines existed, and an agent reading only the older one would have been right by the book and wrong by the decision. We recorded the conflict and the order of precedence: decision records over the rules, the rules over older notes. Precedence is context too.

What the system cannot do for you

It cannot decide your priorities. It cannot say which trade-off your brand accepts. It cannot grant an agent the right to approve a change.

In our setup that line is explicit. Agents work on review branches. The founder merges and deploys. A taste question goes to him as two options and a recommendation. The skill file states this in its last section.

If a rule is missing, the right behaviour is to flag the gap, not to invent a rule. The same applies to facts. Where a value is unknown, our content layer holds an empty value and the page does not render it. Nothing in brackets ships.

What to look at in your own system

Take one real screen and ask five questions.

1. Where is the value defined, and is anything else generated from it?
2. Does each token say what it is for, not only what it is?
3. Does each rule name a source, so someone can challenge it?
4. Which rules does a machine check, and which depend on someone remembering?
5. When two sources disagree, which wins, and where is that written?

The answers show where the system depends on context that lives in people's heads. That is the part an AI cannot read, and the part a new colleague also cannot read.

How we work on this

We start with an audit of the decisions ↗, not the components. We list what is stated, what is implied and what is open. Then we choose the few gaps that affect current work, write those down with an owner, and leave the rest for later. The aim is a system that makes decisions easy to find, apply, review and change, for people first, and for AI as a result.