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.

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 used in 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; 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 was 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 only existed 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. But 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. That's why I don't think of this as a tidiness problem.

Here's how it goes. An agent that can't find the token scale invents a color, and an invented color has never been graded for contrast. So it fails 1.4.3 Contrast (Minimum) 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. 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 reasoning, because that belongs in the design document.

Say what's enforced, and by what. Naming npm run check:tokens turns a principle into a consequence.

Say where the tokens end and a human decision starts, because a reader with no judgment has to be told where judgment is needed.

And leave out anything you wouldn't enforce. A file full of hopes teaches a reader that the file is decoration.

A design system has always had two audiences it served badly: the person who joins on a Monday, and the person who's in a hurry. Now it has a third, one with no memory and no way to ask.

And whatever makes the system clear to that reader makes it clear to the other two. Written-down rules help the new starter, and 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. So ask each person on the team what they'd correct a new starter on, and write those down first.