On this page
1Four principles
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.
2The 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.
3Six properties
Six properties. Most design systems have one or two.
An agent reads a repository literally. Each property is scored 0 to 10 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 ship with the code, and every component says what it's not for.Guidance an agent must leave the repository it works in 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 that ships with the code.
The reference system →
4Four shapes
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.
5Anyone can run it
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.
6What each score means
What each score means.
Each property reduces its evidence to an index between 0 and 1, and the index maps onto one of eleven bands. Five words carry the meaning; each is split in two, so a 9 and a 10 are both systematic and the gap between them is real but small.
0
1
2
3
4
5
6
7
8
9
10
9, 10Systematic
The property holds by construction. Index of 0.85 and above; 10 from 0.925.
7, 8Strong
The property holds almost everywhere, with named exceptions. Index of 0.70 and above.
5, 6Substantial
The property holds in most of the system, and is absent in a measurable share. Index of 0.50 and above.
3, 4Partial
The property holds in places. An agent cannot rely on it. Index of 0.30 and above.
1, 2Incidental
Traces of the property exist, by accident of a good component rather than by design. Index of 0.10 and above.
0Absent
Nothing measurable holds the property. Index below 0.10.
A property the instrument cannot measure in a given repository is not measured, with the reason, and never a band. The mean shown for a system is the mean of its measured properties only. How each property's index is computed is stated on the index, with the readers it uses and their limits.
7What a count turned up
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.
8What 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.
9Cite it
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 Plinth.
How to cite
Learey, C. (2026). Correct by Design: six properties of a design system a coding agent can build with. Version 1.1.https://correctby.design/thesis.html
Changelog
1.1 · September 2026 · “The repository” now reads “the repository it works in”, and legibility reads “the rules ship with the code”. The six properties are unchanged.
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.