Should a design system have a file written for machines?

I put a second file above the README in this repository. It's called AGENTS.md, and I wrote it for a reader who can't ask anybody anything.

A README assumes the opposite. It's written for a person arriving for the first time, and whatever it leaves out, that person can ask a colleague about.

What's in mine is rules, written as rules, with as little room for interpretation as I could manage. The design language lives in one document and the token values in another, and both must be read before any CSS is written.

Every color resolves to a semantic token. The raw palette is internal to one file and must not be referenced from a component. Color literals aren't allowed anywhere in src/, and the file names the two scripts that will fail the build if one appears.

None of that was new policy, because all of it was already true. What was new was writing it where a machine would read it before touching anything, in language that doesn't depend on knowing which conversations happened last year.

That second part is where it got harder than it sounds. Most of our system was fine. But the exercise kept turning up rules I had never written down, the ones that existed only as habit.

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 picks those up by being around the work and by being corrected in review. An agent is corrected by nobody, so it carries on, and it fills each gap with something plausible.

Then somebody pays for it, and it's the same people as always, which is why I don't think of this as a tidiness problem.

An agent that can't 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. It fails silently too, because no test in most repositories checks a hex code.

Focus goes the same way. An agent that can't find the focus convention writes a focus style that looks fine and is two pixels of low-contrast outline.

It's a short path from this rule was in someone's head to this interface excludes someone, and nobody decides anything along the way. The information wasn't 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 this new reader has made their cost visible.

So if your team has a design system, the audit is worth more than the file that comes out of it. Writing instructions for a reader with no context is the fastest way I've found to learn what a system assumes.

The file itself can be short. The rule goes in without the rationale, which belongs in the design document. Say what's enforced and by what, because naming npm run check:tokens turns a principle into a consequence.

Say where the tokens end and a human decision starts, since a reader with no judgment has to be told where judgment is required. And leave out anything you wouldn't enforce. A file full of aspirations teaches a reader that the file is decorative.

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. Now it has a third, with no memory and no way to ask.

Whatever makes the 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). So I don't see this as a concession to machines. It's the work we always said we would get to.

The hardest lines to find are the things everyone knows. Ask each person on the team what they would correct a new starter on, and write those down first.