AI readiness checkpoints
How well an AI coding tool can read the design system: intent-based names, written guidance, coverage of common components and intents, and stated constraints.
Each checkpoint reports pass, warning, fail or skipped. A finding for a checkpoint links its section on this page.
Semantic expressiveness
Intent-based names for presets
ai_readiness.semantic.preset_names
Whether preset names describe intent, such as primary-action, rather than appearance, such as big-blue-button. Each name is scored from its words: intent words raise the score, appearance words such as colors and sizes lower it.
| Result | When |
|---|---|
| Pass | No name scores below 0.4 and the average is at least 0.7. |
| Warning | The average is 0.4 or higher, but some names score low or the average is under 0.7. |
| Fail | The average is below 0.4, or no presets are defined. |
| Skipped | Not reported by this checkpoint. |
How to improve. Rename appearance-based presets to say what they are for.
Semantic token names
ai_readiness.semantic.token_names
Whether token names avoid encoding a raw value: a hex-like segment, a pixel value, or only appearance words and numbers such as blue-500.
| Result | When |
|---|---|
| Pass | At least 80% of token names are semantic. |
| Warning | Between 50% and 80%. |
| Fail | Below 50%. |
| Skipped | No tokens were provided. |
How to improve. Name tokens after their role, such as surface, text or border, rather than their value.
Machine-readable pattern descriptions
ai_readiness.semantic.pattern_descriptions
Whether each pattern description is long enough for an AI tool to use: at least 10 characters and 3 words.
| Result | When |
|---|---|
| Pass | Every pattern description qualifies. |
| Warning | At least half do. |
| Fail | Fewer than half do. |
| Skipped | No patterns were provided. |
How to improve. Write a full sentence for each pattern: what it is and when to use it.
Documentation completeness
When to use, and when not to
ai_readiness.documentation.preset_guidance
Presets that have both whenToUse and whenNotToUse guidance. Coverage is weighted 55% for whenToUse and 45% for whenNotToUse.
| Result | When |
|---|---|
| Pass | Every preset has both. |
| Warning | Some guidance is missing, and weighted coverage is 40% or more. |
| Fail | Weighted coverage is below 40%, or no presets are defined. |
| Skipped | Not reported by this checkpoint. |
How to improve. Add whenToUse and whenNotToUse to each preset. whenNotToUse is what lets an AI tool choose between similar presets.
Patterns with rules
ai_readiness.documentation.pattern_rules
Patterns that define at least one must, mustNot or should rule.
| Result | When |
|---|---|
| Pass | Every pattern has rules. |
| Warning | At least half do. |
| Fail | Fewer than half do. |
| Skipped | No patterns were provided. |
How to improve. Add must, mustNot or should rules to each pattern.
Token descriptions and usage context
ai_readiness.documentation.token_descriptions
Tokens with a description and with usage context. Coverage is weighted 60% for descriptions and 40% for usage.
| Result | When |
|---|---|
| Pass | Every token has a description and at least 80% have usage context. |
| Warning | Otherwise, while weighted coverage is 40% or more. |
| Fail | Weighted coverage is below 40%. |
| Skipped | No tokens were provided. |
How to improve. Describe each token and say where it applies.
Coverage breadth
Presets for common component types
ai_readiness.coverage.component_presets
Which common component types have at least one preset, read from each preset's component or inferred from its name. With 10 or more presets the expected types are button, input, badge, card, dropdown, select, dialog, modal, alert, toast, table and tabs; with fewer, only button, input and badge.
| Result | When |
|---|---|
| Pass | Every expected type has a preset. |
| Warning | At least 40% of the expected types do. |
| Fail | Fewer than 40% do, or no presets are defined. |
| Skipped | Not reported by this checkpoint. |
How to improve. Add presets for the missing component types.
Common intents covered
ai_readiness.coverage.intent_coverage
Which intents presets cover, from each preset's intent or its name. With fewer than 10 presets the expected intents are primary, secondary and destructive; with 10 or more, also success, warning, info, default, ghost and outline.
| Result | When |
|---|---|
| Pass | Every expected intent is covered. |
| Warning | At least 40% are. |
| Fail | Fewer than 40% are, or no presets are defined. |
| Skipped | Not reported by this checkpoint. |
How to improve. Add presets for the missing intents.
Edge cases documented
ai_readiness.coverage.edge_cases
Whether preset and pattern names, descriptions, whenToUse text and rules mention nine edge-case terms: empty, error, loading, disabled, skeleton, placeholder, fallback, overflow and truncation.
| Result | When |
|---|---|
| Pass | At least 60% of the terms appear. |
| Warning | Between 30% and 60%. |
| Fail | Below 30%, or there are no presets or patterns. |
| Skipped | Not reported by this checkpoint. |
How to improve. Document empty, error and loading states for the presets and patterns that have them.
Disambiguation quality
Similar presets are told apart
ai_readiness.disambiguation.similar_presets
Pairs of presets whose names are at least 60% similar, and whether each pair is differentiated by clearly different descriptions or whenToUse guidance.
| Result | When |
|---|---|
| Pass | No similar pairs, or every similar pair is differentiated. |
| Warning | Some pairs are not differentiated, but at least half are. |
| Fail | More than half of the similar pairs are not differentiated. |
| Skipped | Fewer than 2 presets were provided. |
How to improve. Give each similar pair distinct descriptions or whenToUse guidance.
Distinct whenToUse guidance
ai_readiness.disambiguation.overlapping_guidance
Pairs of presets whose whenToUse text is at least 50% similar, which leaves an AI tool unable to choose between them.
| Result | When |
|---|---|
| Pass | No overlapping pairs. |
| Warning | 1 to 3 overlapping pairs. |
| Fail | More than 3 overlapping pairs. |
| Skipped | Fewer than 2 presets have whenToUse guidance. |
How to improve. Rewrite the overlapping guidance so each preset covers a different situation.
Unambiguous intent routing
ai_readiness.disambiguation.intent_routing
For each component with two or more presets, whether those presets declare distinct intents. A group is ambiguous when two presets share an intent, or when none declares an intent and not all have whenToUse guidance.
| Result | When |
|---|---|
| Pass | No group is ambiguous. When no component has two or more presets, it passes if at least 70% of presets declare an intent. |
| Warning | Some groups are ambiguous, but no more than half. With no multi-preset components, fewer than 70% of presets declare an intent. |
| Fail | More than half of the groups are ambiguous, or no presets are defined. |
| Skipped | Not reported by this checkpoint. |
How to improve. Give each preset of the same component its own intent.
Forbidden primitives
Negative constraints defined
ai_readiness.forbidden.negative_constraints
Whether the design system tells AI tools what not to do. Forbidden primitives score 40 points for existing, up to 30 more for having reasons and up to 30 for having alternatives. Without forbidden primitives, mustNot rules on patterns earn partial credit.
| Result | When |
|---|---|
| Pass | Forbidden primitives score 80 or more. |
| Warning | They score below 80, or there are none but patterns have mustNot rules. |
| Fail | No forbidden primitives and no mustNot rules. |
| Skipped | Not reported by this checkpoint. |
How to improve. Define forbidden primitives, each with a reason and an alternative.
Anti-patterns documented
ai_readiness.forbidden.anti_patterns
How much the design system documents what goes wrong, across three sources: forbidden primitives, mustNot rules on patterns and whenNotToUse on presets. The score is up to 50 for using all three sources plus 5 per rule, up to 50.
| Result | When |
|---|---|
| Pass | A score of 80 or more. |
| Warning | Between 40 and 80. |
| Fail | Below 40, or nothing is documented in any source. |
| Skipped | Not reported by this checkpoint. |
How to improve. Cover all three sources, and add specific rules for common mistakes.
Escape hatches documented
ai_readiness.forbidden.escape_hatches
Whether constraints say what to do instead, or when an exception is acceptable. A rule documents an escape when a clause names an exception (except, unless, exempt, an escape hatch) without denying it, or grants a permission (allow, permit, override, bypass, opt out) without negating it, so "Disallow custom colors" and "No exceptions are allowed" do not count. A negation inside a when or if condition belongs to the condition ("except when no component fits" still counts), and "allows users to confirm" describes what a component does, not a permission. Every rule is read, mustNot included. With forbidden primitives: 40 points for a documented escape plus up to 60 for the share with an alternative. Without any, a documented escape scores 100.
| Result | When |
|---|---|
| Pass | A score of 70 or more. |
| Warning | Between 30 and 70. |
| Fail | Below 30. |
| Skipped | No forbidden primitives or mustNot rules exist. |
How to improve. Give every forbidden primitive an alternative, and say when exceptions are acceptable.