The agent-readiness audit

You can find out how agent-ready your design system is in one afternoon.

This is the checklist I run. Six sections, twenty-two questions, every one a yes or a no.

Write the answers down. The noes are the work.

Answer for the system as it is written today, not as you intend it. A rule that lives in someone's head is a no. A rule in a Figma comment is a no.

An agent reads files.

If you want the argument behind the checklist rather than the checklist itself, that is in agent-ready design systems.

Before you start

Pick one screen your team has already shipped. Something real, with a form, a table and an empty state.

Set it aside. You need it for the last section.

Then open your design system.

The tokens

Does every colour have a semantic name? color-surface-raised is a yes. grey-200 is a no. Ask an agent for a card background and it reaches for a raw value. Next screen, it reaches for a different one.

Is there one path to each raw value? If both #1B1B1B and color-fg-default sit in your docs, the agent uses whichever it read last.

Are foreground and background stated as pairs? A list of colours is not a palette. color-fg-onBrand on color-bg-brand is a pairing. An agent cannot work out which of your nine greys survives on your brand blue.

Is there a declared contrast minimum, written as a number? WCAG 2.2 success criterion 1.4.3 sets 4.5:1 for normal text and 3:1 for large text at Level AA. If your system names no bar, the agent has nothing to check its own output against.

Do you say what to do when no token fits? Every system runs out. The ones that do not admit it get invented tokens.

The components

Is each rule written as an instruction? "Buttons feel confident" is a description. "Use the primary button once per screen" is an instruction. Only one of them survives translation.

Are the states enumerated? Default, hover, focus, active, disabled, loading, empty, error. Any state you leave off the list is a state the agent designs from scratch.

Are the do-nots written down? The DESIGN.md spec gives them their own heading, alongside Overview, Colors, Typography, Layout, Elevation, Shapes and Components. A system with no don'ts is a system with no edges.

Does each component have exactly one name? The docs say Card, the Figma library says Surface, the codebase says Panel. The agent picks one and your review picks another.

Is the variant list closed? Say whether those are all the variants or the common ones. An open list is an invitation to invent.

The behaviour

Is there any procedural instruction at all? Search your docs for a numbered list of steps. Description is not instruction. A system can be complete on how things look and silent on how to work.

Is there an ordered path for one common task? Build a settings page. Add a field to a form. Numbered, in order, start to finish.

Is there a check the agent can run on its own output? A rule with no test is a preference.

Is it stated when the agent should stop? Name the cases it hands back. A new component, a new colour, anything touching consent or payment.

Does your entry point say when to use it, not only what it covers? The SKILL.md spec asks the description field to carry both. The name and the description are the only parts loaded at startup, at around 100 tokens. Get them wrong and the body never loads.

The provenance

Does anything in your system carry a date? One date, on one file, saying when it was last true.

Does each imported rule name where it came from? A URL, a spec, a ticket. Something a person can open.

Is there a version on the system as a whole? The DESIGN.md spec puts its own version in frontmatter. Its current value is alpha, which is itself useful information.

Is there a named owner? Not a team. A person who decides.

A design system with no dates is a design system an agent will confidently misapply. It has no way to know that your radius changed in March.

The gaps

Are the missing parts declared as missing? DESIGN.md carries an omitted array in frontmatter, where you list what you left out. Its only required key is name, and its only required content is the primary colour palette. Everything else may be absent, as long as the absence is declared.

Is an unfinished file marked unfinished? skill-kit uses a status field with four values. enriched, downloaded, vendor-only, stub-no-source. A stub with no source behind it says so in its own frontmatter.

Is the marking queryable? A note in prose helps a reader. A field in frontmatter gives you a work list you can filter.

Is deprecated content marked deprecated, and dated? Old rules that read as current are worse than missing rules.

Those two, the omitted array and status: stub-no-source, are the honest precedents. An agent cannot tell a gap from an omission. Silence reads as complete.

The test

Now take the screen you set aside.

Hand your design system to the agent your team already uses. Ask it to build that screen. Give it nothing else.

No clarifying prompt, no correction, no nudge when you see it going wrong.

Then put its output next to the real one.

What it gets wrong is your audit result. Not what the checklist said. This.

The checklist tells you what is missing on paper. The test tells you what the absence costs. They are rarely the same list, and when they disagree, the test is right.

Run it twice if you have two agents in the building. Where they diverge is where your system is ambiguous rather than incomplete.

After

You now have a list of noes and one screen that came back wrong.

That is the easy half. The checklist finds the gaps. Closing them is the judgment call, and judgment is the part that does not download.

Which rules survive translation into a file an agent reads. What to cut, because the SKILL.md spec recommends holding the body under 5,000 tokens.

Which of your don'ts are real constraints and which are taste. How to write a rule so that two agents read it the same way.

That is what the audit is for. 2 to 3 days. Your system comes back as SKILL.md and DESIGN.md files, tested against the agents your team already uses.

If your team would rather do the writing, the workshop is half a day. They leave with a draft of their own. Talks are the third option, for when the room needs the argument before the work.

None of that is urgent. The checklist is yours either way, and it works without me.

If your design system needs to work with agents, say hello.