Write Your Design System for Two Readers: People and AI Agents

Design system documentation used to be the part nobody read. Now a growing share of the code in a product is written by tools that read it every single time. Here's how I'd change the way a design system gets written, and what I'd stop putting in it.

‍

For as long as I've worked on design systems, the quiet complaint on every team has been the same: the documentation exists, and almost nobody opens it. People build from memory, from the last screen they saw, or from whatever component sits closest to hand. Writing the guidelines felt like the least rewarding part of the job.

That's shifting. Michael Coté made the point recently that design systems are worth more now precisely because AI agents read the documentation every time, which is something human developers have never reliably done. I think he's right, and the consequences are bigger than they first look.

Your documentation just got a second reader

A coding agent starts each task with whatever context it has been given. If your design system documentation is part of that context, it gets read in full, every time, without anyone skimming to the code samples.

That changes what documentation is for. It used to be a reference you hoped people would consult when they got stuck. Now it behaves more like a brief that is attached to a growing amount of the work, and the quality of what ships starts to track the quality of what you wrote.

The catch is that an agent follows vague guidance just as faithfully as precise guidance. "Use sparingly" and "keep layouts clean" give it nothing to act on, so it fills the gap with whatever is most common in its training data. That's usually the generic version of your product, which is the opposite of why you have a design system.

What a second reader needs that the first one didn't

Human readers forgive gaps because they ask a colleague. An agent can't, so the gaps need to be written down. These are the parts I'd look at first.

When not to use a component. Most documentation explains what a component is. Far fewer say when it's the wrong choice. "Use a modal for confirmations that block the flow, and never for content the user needs to compare against the page behind it" is something both a new designer and an agent can act on.

What the data looks like at the edges. On data-heavy products, the happy path in the demo is rarely the real one. Say what a table does with zero rows, with ten thousand rows, with a value that's missing, and with a value that's absurdly long. These are the situations where generated screens quietly diverge from each other.

Which of two similar patterns wins. Every mature system has overlaps, such as two ways to filter or two ways to show status. If the documentation doesn't name the preferred one, every session will make its own choice, and you'll see the inconsistency later as a product that feels slightly off.

The reason behind each rule. A rule with a reason can be applied to a case you didn't anticipate. A rule without one gets followed rigidly or ignored. I try to write a single sentence of why next to anything that isn't obvious.

What I'd stop putting in

There's a temptation to treat this as a reason to write more. I'd go the other way. Marketing language about the brand's personality, long histories of why the system exists, and screenshots with no explanation add length without adding anything either reader can use. If a sentence can't change a decision someone makes while building, it probably belongs somewhere else.

I'd also be careful about duplicating the same rule in several places. A person can reconcile two slightly different versions of a guideline. An agent will pick one, and you won't know which.

A test I'd run this week

Pick one component and read its documentation as if you knew nothing else about the product. Then ask three questions. Could you tell when not to use it? Could you tell what happens when the data is empty or enormous? Could you tell which similar component to use instead in a close call?

If the answer to any of those is no, a human has been filling that gap from memory and an agent has been filling it with a guess. Writing it down helps both.

The documentation pass most teams keep postponing is worth scheduling now. It used to be a deliverable for later, and it's turning into an input to the build. Which rule in your system do people break most often, and have you written down why it exists?

‍

Gytis Markevičius
Founder, GytisMark Studio — gytismark.com