What agents get wrong about design systems

Every failure listed here looks like a model failure. None of them are.

The agent did what it was asked, with what it was given. The file was the problem.

Seven failure modes. Each one has a fix, and every fix is a field in a file.

The invented token

Ask an agent for the disabled state of your secondary button.

If your file does not define one, you will get a hex code anyway. It will be plausible. It will be named like your other tokens. It will be wrong.

That is the default failure of this entire category. Not refusal. Confident invention.

It happens because absence and omission look identical. A file that stops at six colours never says whether the seventh was cut on purpose or forgotten.

DESIGN.md fixes this with a field. omitted is an array in the frontmatter. Declare a section there and the spec lets you drop it. The only thing you cannot omit is the primary palette.

Declared absence is not a gap. It is an instruction.

The drift

The grey in screen one is not the grey in screen nine.

Nobody notices until the screens sit side by side. Then there are two greys.

This happens when the value only ever lived in prose. An agent reading "a warm neutral background" rebuilds a hex every time it needs one. Reconstruction is not recall.

DESIGN.md splits the file for exactly this. YAML frontmatter carries the tokens. The markdown body carries the rationale. The spec's own line: "The tokens are the normative values; the prose provides context for how to apply them."

A named token gets copied. A described colour gets re-invented.

The blank slate

Every session starts from nothing.

Your agent has no memory of the greys you settled yesterday. The system is only as present as whatever you pasted into the window.

Most teams answer this by pasting more. That runs out of room, and it puts your design system in competition with the actual work for context.

SKILL.md answers it with progressive disclosure. Name and description load at startup for every installed skill, at roughly 100 tokens each. The full body loads only when the skill activates, and the spec recommends keeping that under 5000 tokens. Anything bigger sits in references/ and is read on demand.

The load-bearing field is description. The spec asks it to say what the skill does and when to use it. That second half is what makes an agent reach for the file without being told.

The system stops being something you remember to paste.

The median

Give an agent nothing specific and you get the page everyone else gets.

Purple gradient. Inter. A hero with gradient text. Four rounded cards in a grid.

Developers have named it. "AI slop" is the common label, and the colour has its own: the Purple Problem. It traces to Tailwind UI's bg-indigo-500, the default button colour from years ago. Tailwind's own creator has since apologised for it, half-joking that it made every AI-generated UI on earth indigo.

The mechanism is simpler than the naming. A model with no constraint returns the median of what it has seen. The median of web design since about 2019 is that page.

The fix is not a better prompt. It is a defined value. DESIGN.md requires the primary palette and nothing else. That one required field is what displaces the median.

The adjective

Hand an agent adjectives and it hands you adjectives back.

"Confident and approachable" produces nothing you can check. Neither does "clean and modern". The agent will agree with you and then build the median page.

Descriptions are written for humans who already share the context. Agents share no context.

SKILL.md is built the other way round. The body is instructions, not description. The spec caps it at 500 lines, keeps file references one level deep, and puts anything runnable in scripts/.

Adjectives describe the outcome. Procedure produces it.

The stale rule

An agent will apply your deprecated button rule with total confidence.

Nothing in a normal design system says when a rule was last true. No fetch date, no status, no expiry. A rule written three years ago reads exactly like one written last week.

Humans route around this. Someone in the channel says we do not do that any more. An agent has no channel.

This is the one thing I built into skill-kit from the first file. All 577 files carry fetched_at and status. Status takes one of four values: enriched, downloaded, vendor-only, stub-no-source. The build is written up here.

A stub that says it is a stub beats a page of confident prose.

DESIGN.md does the same thing to itself. Its spec header reads version: alpha. The format tells you it is a draft.

The missing don't

Design systems document what to do. Agents fail on what nobody thought to forbid.

Nobody wrote down that the brand purple is never a background. Everyone on the team knows. It has never been typed anywhere.

So the agent uses it as a background. Nothing said not to, and it is the strongest colour in the file.

DESIGN.md ends every file with a section for this. Its heading order runs Overview, Colors, Typography, Layout, Elevation, Shapes, Components, then Do's and Don'ts.

Last section, and the one most teams leave empty. It is the one carrying every rule your team has never had to say out loud.

The reframe

None of these are model failures.

The agent that invented a token was asked for a token that did not exist. The agent that drifted was given a description instead of a value. The agent that shipped the purple gradient was given no constraint at all.

Each one did exactly what was asked, with exactly what was given.

That moves the work. You are not prompting better. You are writing a file that answers the questions an agent will ask, including the ones about absence.

Most of that is not writing. It is finding the rules your team has never typed out.

If you want to know which of these seven your system already fails, that is the audit. If you want the long version of the fix, start with agent-ready design systems.

Nothing here needs a smarter model.