Wayfinding
A design system is signage. Each file points to a more specific file, and the agent reading the repository is bound to follow the arrows. Disclosure is progressive: nothing is shown before it is needed, nothing needed is left unsaid.
↓ README
→ AGENTS.md
→ Tokens
→ Components
■ Build
1
Four principles.
1.1
Design lives in the code, not downstream of it.
1.2
Wrong output is impossible, not discouraged.
1.3
The agent is the user. The human is the judge.
1.4
Everything is measured, never asserted.
2
The distinction
Two questions.
Reading finds the cause. Building finds the gap.
1
Read
Is it capable of guiding an agent?
Scattered tokens. Permissive APIs.
Documentation outside the repo.
Blind to what is missing.
2
Write
What happens when an agent uses it?
A gap exists only against something someone actually tried to build.
Blind to why it happened.
3
Six properties. Most design systems have one or two.
An agent reads a repository literally. Each property is scored 0 to 5 with the evidence attached.
3.1Constraint
Wrong output is impossible, not discouraged.The component API and the type system make illegal output fail at build time. Nothing relies on anyone reading a guideline, and nothing can decay when attention moves on.
3.2Single source
Every visual decision lives in exactly one place.One definition, one place. Change it once and it propagates. Anything that still needs hand-editing was never a source of truth.
3.3Legibility
The rules are in the repository, and every component says what it's not for.Guidance an agent must leave the repository to find is guidance it will not read. The line that matters most is the boundary: what each thing is not for.
3.4Fidelity
The documentation cannot drift from the code.Not should not. When the docs and the code disagree, the build fails. Intent is not a mechanism.
3.5Adherence
The system is the easiest way to build.What sits in the application is what an agent treats as precedent.
3.6Completeness
The system knows what it's missing.Gaps are recorded when something needed does not exist, not improvised into one-offs. That demand data becomes the roadmap.
One system is built to all six, by construction. Tokens defined once, components where the wrong build won't compile, documentation an agent reads without leaving the repository.
The reference system →
4
Four shapes a system can land in.
The score isn't the point. The shape it makes is, because the shape says what kind of change would move it.
What the assessment findsWhat it meansWhat follows
Low constraint, low legibilityA component library, not infrastructure.→ A rebuild
Good docs, low constraintIt holds by convention and goodwill.→ Harden the API
Good system, low adherenceAdoption and ownership are the problem.→ An owner in the code
Good everything, many gapsMature, and still incomplete.→ A gap roadmap
Whatever the shape, the through-line is the same: the design moves into the code, and someone owns it there. That's what turns a component library into infrastructure.
5
Anyone can run it.
The assessment is the thesis applied to one repository, in two passes and a separation.
5.1Count
Read the repository against each property.Write down what's there: token definitions and where they're duplicated, component APIs and what they permit, documentation and where it lives, hardcoded values and one-off components in the application. Every count carries a file reference. Nothing is estimated.
5.2Run
Give a coding agent one real screen to build with the system, cold.No instructions beyond the task. Before it runs, write down what it's expected to reach for and not find, and what it's expected to get wrong. Then compare.
5.3Separate
Every wrong output has one of three causes, and they look identical from the outside.The documentation didn't say (legibility). The components allowed it (constraint). The thing it needed doesn't exist (completeness). Confusing them is how rebuilds get scoped wrong, and the third kind is why the run exists: it leaves no trace to read.
Where a property can't be measured in a given repository, it's recorded as not measured, with the reason. That is never rendered as a failure.
6
What each score means.
Each property is scored 0 to 5. The band definitions are being prepared for publication alongside the index, so that any system can be self-assessed against the same rubric the index uses.
0
1
2
3
4
5
Band definitions to follow
7
What a count turned up, and what it led to.
Nivoda, a global B2B jewellery marketplace running Material UI. The count found:
81per-component override files fighting Material's defaults
723inline style escapes, every one a place a token could be ignored
32component-specific token files maintained by hand
…and 89 separate styleOverrides passes underneath them. The team was paying, continuously, to make Material UI not look like Material UI.
Nobody had decided to do that. It had accreted over years. And until it was counted, nobody could argue about it.
That count became the rebuild: a token pipeline, sixty-three components, agent-readable documentation, and a design team that moved into the codebase and stopped handing pictures to engineers.
The drift-checking didn't get faster. It stopped being necessary. The build could no longer disagree with the design. What was left for the team to judge was whether the design was right.
The system is running in production.
Read the case in full →
8
What this will not tell you
Three honest limits.
It doesn't say whether the design is any good.
It measures whether the build can disagree with the design, and whether an agent can follow the system. Whether the design is the right design stays with the team.
It doesn't score what it can't see.
If it can't be measured, it comes back as not measured, with the reason. That never renders as a failure.
It isn't a certification and there is no badge.
The output is a measurement with the working attached. Anyone can disagree with any part of it and check it themselves.
9
Cite it, build to it, argue with it.
The definition, the six properties and the diagrams on this site are published under CC BY 4.0. Use them with attribution. A reference implementation built to all six is at agent-ready-design-system.
How to cite
Learey, C. (2026). Correct by Design: six properties of a design system a coding agent can build with. Version 1.0.https://correctby.design/thesis.html
Changelog
1.0 · September 2026 · First versioned text. The six properties as ratified 27 July 2026.
Assessments are also run for organisations that want one against their own repository.