TheDSDS rubric

The grade measures what one agent did on one run. It can be pulled down by a bad question or a bad answer. The machine-readability percentage asks a steadier question instead: are the facts a coding agent needs actually present, and reachable as data, regardless of who asks or how?

We keep the two deliberately separate rather than folding them into one number. A score that also encodes readability hides which of two very different problems you have. Is it an agent that behaved badly, or documentation that never gave it a chance?

The rubric is abstracted from DSDS, the Design System Documentation Schema. It’s a young, evolving spec for describing a design system as structured data. Almost nobody has published a DSDS document yet, so a real conformance run against a crawled site would come back “not applicable” for nearly every field, on nearly every system.

What survives the format is the reasoning behind it. Every field in DSDS exists because some consumer (in this case, a coding agent) needs a specific fact in a retrievable place. Restate each field as a plain question about that fact, is it here, and is it reachable as data?, and it applies to a Storybook site, a Notion page, a bespoke docs app, or zeroheight, without anyone writing a line of DSDS. We cite the DSDS field each guideline came from throughout, so it stays legible to anyone who does know the schema, and doubles as a map of how to express the same fact there.

A guideline that cannot be measured on a system (no token table to read, say) is marked not applicable on that report and left out of its score, so a report can say “11 of 12 guidelines apply”.

Each guideline is checked against your crawled text: a props table with a type/default column, a listed set of allowed values next to the word your team uses for them, key-by-key keyboard behaviour rather than “keyboard accessible”, a component page that separates when to use it from how. A guideline with nothing to check against is reported as failing outright rather than excluded, because that’s what an agent hits too.

The score is a weighted average across every guideline that applied. It is a readiness measure, not a conformance claim: we are not validating a DSDS document.

Every report names how the content actually reached us: fetched HTML, a documentation API, an uploaded file, a GitHub repository, a linked token file or API contract. That channel is never part of the percentage. A design system can serve its documentation through an MCP server or an internal API, and what a public crawler couldn’t fetch is evidence about what was exposed to the test, not about the documentation itself.

So we ask, rather than infer: every submission can name another channel, an MCP endpoint, a docs API, a token file, and the report says plainly whether a particular channel came up in our test or not. That way you know exactly what we’re testing against.

The percentage measures whether your documentation could support any agent. It doesn’t tell you what a specific run actually did with it, which is the battery. See what the battery tests, or run the check.