Should a design system have a file written for machines?

Every repository has a README. It is written for a person arriving for the first time, and it assumes that person can ask a colleague whatever it fails to explain.

I put a second file above it in this repository, called AGENTS.md, and I wrote it for a reader who cannot ask anybody anything.

What goes in a file like that?

Rules, stated as rules, with no room for interpretation.

Ours says the design language lives in one document and the token values in another, and that both must be read before any CSS is written. It says every color resolves to a semantic token. It says the raw palette is internal to one file and must not be referenced from a component. It says color literals are not allowed anywhere in src/, and names the two scripts that will fail the build if they appear.

None of that is new policy. All of it was already true. What was new was writing it somewhere a machine would read it before touching anything, in language that does not require knowing which conversations happened last year.

Why is that harder than it sounds?

Because writing for a reader who cannot ask a follow-up question exposes how much of a design system is not written down.

Most of ours was fine. But the exercise kept surfacing rules I had never written down, the ones that existed only as habit and that no document said out loud. The accent marks selection and nothing else. Never put a color in a component. If the spacing you want is not in the scale, the answer is not a new value.

A person absorbs those by osmosis and by being corrected in review. An agent gets corrected by nobody, absorbs nothing, and proceeds. So every unwritten rule is a gap, and it will be filled with something plausible.

This is the part I would press on for any team with a design system: the file is not the deliverable, the audit is. Sitting down to write instructions for a reader with no context is the fastest way I have found to discover what a system actually assumes.

Who pays when the rules are unwritten?

The same people as always, which is why this is not a tidiness problem.

An agent that cannot find the token scale invents a color. An invented color has never been graded for contrast, so it fails 1.4.3 for someone with low vision, and it fails silently because no test in most repositories checks a hex code. An agent that cannot find the focus convention writes a focus style that looks fine and is two pixels of low-contrast outline.

The path from this rule was in someone's head to this interface excludes someone is short and entirely undramatic. Nobody decided it. The information simply was not reachable at the moment it was needed.

We both believe UX professionals do not intentionally exclude people from their work. Unwritten rules are one of the main ways it happens anyway, and the new reader has made the cost of them visible.

What belongs in the file, concretely?

• The rule, not the rationale. Rationale belongs in the design document. The machine-readable file says what is and is not allowed, in short sentences.
• What is enforced, and by what. Naming npm run check:tokens turns a principle into a consequence. A rule with a gate behind it gets followed; a rule without one gets weighed against the deadline.
• What must be read first, and where it is. Point at the documents rather than summarizing them, so there is one source of truth rather than two that drift.
• The things everyone knows. These are the highest-value lines in the file and the hardest to notice you are missing. Ask each person what they would correct a new starter on.
• The boundaries of the system. Where the tokens end, what is deliberately not covered, what requires a human decision. A reader with no judgment needs to be told where judgment is required.
• Nothing you would not enforce. A file full of aspirations teaches a reader that the file is decorative.

What I took from writing it

A design system has always had two audiences it served badly: the person who joins on a Monday, and the person who is in a hurry. It has now acquired a third that has no patience, no memory, and no way to ask.

The good news is that everything that makes a system legible to that reader makes it legible to the other two. Written-down rules help the new starter. Enforced rules help the person in a hurry. Nothing here is a concession to machines; it is the work we always said we would get to.

Open your design system and try to write the one-page version for a reader who cannot ask you anything. Whatever you find yourself unable to write down is the thing your system has been relying on people to already know. Let's write those down first.