The AI Readiness score answers one question: can an AI agent discover, understand and correctly use this design system. It is a weighted average across eight dimensions, calculated per component and then rolled up to the system.
The dimensions and their weights#
| Dimension | Weight | What it measures |
|---|---|---|
| Semantics | 20% | Whether the system says what a component is for |
| Discoverability | 15% | Whether the component can be found at all |
| Design and code mapping | 15% | Whether the Figma component has a matching implementation |
| Constraints | 10% | Whether anything says when not to use it |
| API clarity | 10% | Props, variants, defaults, required values, valid combinations |
| Token compliance | 10% | Whether the implementation uses tokens or literal values |
| Examples | 10% | Whether there is at least one correct usage to imitate |
| Accessibility | 10% | Whether keyboard, labelling and role expectations are written down |
The weights are public on purpose. A score nobody can reason about is a dashboard decoration, not a product. Semantics carries the most weight because it is the dimension whose absence causes the most wrong output: an agent that does not know what a component is for will still use it, just in the wrong place.
From component to system#
Each dimension produces a value from 0 to 100 for a component, from the findings recorded against it. The component score is the weighted average of its eight dimension values.
The system score is the average of the component scores, weighted by how often each component is used in the codebase. A neglected component that nothing imports drags the score down less than the button on every screen, because an agent is far more likely to reach for the button.
A worked example#
A Button component with a documented purpose, a Storybook entry, three
examples, a Figma match, full prop documentation, tokens throughout, but no
guidance on when to use Button over Link, and no accessibility notes:
Semantics 90 x 0.20 = 18.0
Discoverability 100 x 0.15 = 15.0
Design and code mapping 100 x 0.15 = 15.0
Constraints 0 x 0.10 = 0.0
API clarity 90 x 0.10 = 9.0
Token compliance 100 x 0.10 = 10.0
Examples 100 x 0.10 = 10.0
Accessibility 0 x 0.10 = 0.0
-----
77.0
Two gaps in an otherwise well documented component cost 23 points. That is the intended behaviour: for an agent, the missing 20% is what causes the wrong output, not the 80% that is already written down.
Every score has evidence behind it#
No dimension value exists without the findings that produced it. A Constraints value of 0 is not an opinion, it is the absence of any usage guidance in the component's documentation, its stories, or its Figma description, and the report links to each place it looked. The number is the summary. The evidence is the part you act on.
What the score does not tell you#
- Whether your design system is good. It measures whether it is legible to a machine, which is related but not the same thing.
- Whether your UI is accessible. The Accessibility dimension measures whether expectations are documented, not whether the implementation meets them.
- How you compare to other companies. There is no benchmark and no industry average, because the same number over different systems means different things.
To raise a score, see improving a low readiness score.
Last updated
Related
Improving a low readiness score
The changes that move an AI Readiness score most, in order of effect, and roughly what each one costs in time.
What AI agents need from a design system
The four failure modes that show up when a coding agent builds UI against a design system, and what each one is actually caused by.
Something wrong, missing or out of date in this article? Email onefold@pitsch.me and it gets fixed. Or start at the help center.