What makes design system rules for AI checkable

A design system rule for an AI agent is a line with an id, a level (must, should or never) and, where it can, an incorrect and a correct snippet. A guideline written as prose has none of those parts, so an agent can read it, but no lint error or review can cite it by name.

Quartz writes the rules in its docs in that shape, and it is the right shape for an agent to work from.

Each Quartz rule has an id, a level and its text. Quartz's docs hold 605 rules across 67 pages, and 507 of them carry both an incorrect and a correct code snippet. Quartz's anti-slop page has 26 rules, 1 must and 25 never, with 18 carrying incorrect and correct code.

One of its never rules is anti-slop-no-arrow-links:

<a>Learn more →</a>

<Link href="/docs/keys">Rotating API keys</Link>

The rule bans link text that ends in an arrow or reads Learn more, and asks the link to name where it goes. Its reason is that a screen reader listing links hears ten Learn mores and no destination. The incorrect snippet is <a>Learn more →</a>. The correct snippet is a Link to /docs/keys whose text reads Rotating API keys. The pair gives the agent the exact string to avoid and the text to write in its place, which the sentence alone does not.

Quartz lint has 35 rules, and Quartz pairs each one with the docs rule it enforces. quartz/no-arrow-link enforces anti-slop-no-arrow-links. Run on its planted fixture, it printed this:

// Planted: quartz/no-arrow-link. Link text that ends in an arrow.
export function Docs() {
  return <a href="/docs/keys" className="type-body-sm text-text-1 underline">Rotating API keys →</a>;
}

registry/quartz/lint/fixtures/bad/no-arrow-link.tsx
  3:10  error  "Rotating API keys →" ends in an arrow; a screen reader reads it aloud, so drop it and let the text name where the link goes.  quartz/no-arrow-link

1 problem

The output has one error at 3:10, on the link text "Rotating API keys →". It tells the agent that a screen reader reads the arrow aloud, and to drop it and let the text name where the link goes. The run ends at 1 problem.

The lint rule name and the docs id are separate strings, singular quartz/no-arrow-link against plural anti-slop-no-arrow-links. The published pairing is what ties an error back to the docs rule and its reason.

Reviews use the same names. The ui-review skill cites each finding by number or by the installed design system's rule id, so a lint error and a review finding can name the same rule.

A guideline such as "write clear link text" gives an agent intent with no snippet to compare against and no name to cite. An agent can agree with it and still ship Learn more with an arrow on the end.

The component-docs skill holds rules to the stricter format. It writes each usage rule with an id, a condition, an action, a reason, its evidence and a "Don't" line with real code that breaks it. It cuts a rule it cannot break with a snippet. That cut is the right default, because a rule nobody can break in code is a guideline with an id attached. The AI slop UI page goes through each tell with the rule that bans it and the lint error an agent reads.

The one mistake is reading a never rule's text as an instruction. A never rule's text names the thing to avoid, and the docs page prints it after the word Never. The text of anti-slop-no-arrow-links opens with "End link text in an arrow or write Learn more", which is the habit it bans. Copy that text into a prompt without its level and it reads as an order to do the banned thing, so the level belongs to a rule as much as its id does.