WebinsaneDesign systems
Write the reason next to the number.
Design systems have a new reader. It follows every rule and none of the reasons.
For most of the twenty-two years we have been building design systems, they had two readers. The designer extended them and the developer implemented them, and everything the system could not say in a token was said in a meeting. Somewhere in the last year a third reader arrived, and on many teams it now writes more code than the other two: the AI coding agent.
Agents are extraordinary at following a system. They are just as good at following it off a cliff. Building an AI-ready design system, it turns out, is mostly about that second sentence.
Agents follow the what and miss the why.
Give an agent a token file and it will use the tokens. Ask it to fix a layout bug and it will, very reasonably, add a breakpoint at 768 pixels, because that is what most of the code it has ever read does. It has no way of knowing that your system has one breakpoint on purpose, that the stylesheets and the scripts both test the same width, and that a second breakpoint opens a band of screen sizes where the two disagree.
The agent is not wrong about the code. It is wrong about the intent, and the intent was never written down where it could be read. What changed in our practice this season was simple to state and slow to do: every load-bearing decision now lives in the same place as its value. In the token file, in the config, beside the number. That way whatever reads the value reads the reason with it.
Fewer numbers, each of them load-bearing.
Our own site is a useful example because it is an extreme one. The whole of webinsane.com turns on two values. Every measurement is written in a single unit, one pixel of a 1672 by 900 reference frame, clamped so the composition scales as one picture and never becomes absurd at the edges. And there is one breakpoint, at 900 pixels: above it, each heavy section builds itself as a scroll-driven drawing; below it, each becomes a flat page. The stylesheets state that boundary as 899.98 pixels, the exact complement of the script’s test, and the token file explains why it is neither 899 nor 900.
A system with fifteen spacing values and five breakpoints offers an agent fifteen ways to be slightly wrong. A system with a handful of values, each one explained, offers it very few. Restraint used to be an aesthetic preference. It is now also a safety property.
The most valuable sentence is the alternative you rejected.
The line in a design system that saves the most time is usually some version of we tried this, and it was wrong, because of that. People pass it on in reviews and corridors. Agents were not in the corridor.
Our palette notes say that the paper is not pure white and the darkest type is not pure black, so the page never gains contrast it did not have. Without that sentence, an agent asked to improve legibility reaches for black on white and flattens the visual language in a single commit. With it, the agent either asks a better question or finds the improvement inside the restraint. The note costs one line. The absence of the note costs a redesign.
Reuse is a design decision, not a refactor.
Every place on our site where one section hands over to the next uses the same curved edge: three shapes, flat, bowed and full, morphed point for point. The second transition imports the first one’s paths instead of drawing its own, and the file says why. Two edges moving at two speeds would read as two effects, rather than as one thing the site does.
That is a design-system rule hiding inside a transition file. Written as one, it means the agent building the next transition reuses the gesture instead of inventing a nicer one. The same logic applies to configuration. We keep everything a designer might want to change, such as timings, copy and curve shapes, in per-section config files, separate from the code that runs them, so a request to make the hero faster becomes one documented number in one obvious place.
Explain the system in the system.
None of this replaces the fundamentals. A good AI-ready design system still has tokens for colour, type, space and motion, as few as the design can bear. What it adds is reasons beside values, rejected alternatives stated plainly, one home for each decision, and at least one reference component built properly for the agent to imitate. For client systems there is one more thing: a rollout plan. Most systems are introduced into products that are already live, so the system has to say which parts can be migrated gradually and which must change in a single move.
The reason this matters goes beyond code. Brands are about to produce far more than people can review line by line: generated pages, variants, whole campaigns. A system only humans can interpret becomes the bottleneck. A system that explains itself becomes the guardrail. That is what we mean, practically, by design for agents, and it is now part of every design-system engagement we take on.
The agent will follow every rule you give it. The work is making sure it can also read why.
Asked often.
What is an AI-ready design system?
A design system that documents its reasons alongside its tokens and rules, so AI coding agents as well as human designers and developers can extend it without breaking its intent.
Do AI coding agents follow design tokens?
Reliably, when the tokens exist. Where they fail is intent: without written reasons, an agent falls back on common patterns, such as extra breakpoints or pure-black text, that contradict the system.
How many breakpoints should a design system have?
As few as the design allows. Each breakpoint is a boundary that scripts and styles must agree on. Our own site uses one, at 900 pixels, stated identically in CSS and JavaScript.