Adoption checkpoints
How much of the codebase uses the design system: tokens instead of raw values, presets instead of manual props, and declared patterns for common compositions.
Each checkpoint reports pass, warning, fail or skipped. A finding for a checkpoint links its section on this page.
Token adoption
Token usage rate
adoption.token_adoption.usage_rate
The share of style values in the codebase that come from a design token: values marked as tokens, given a token name, or written as token references such as var(--color-text). A literal that happens to equal a token value does not count.
| Result | When |
|---|---|
| Pass | At least 80% of style values come from tokens. |
| Warning | Between 50% and 80%. |
| Fail | Below 50%. |
| Skipped | No codebase style values were provided. |
How to improve. Replace hardcoded values with references to existing tokens, starting with the ones repeated most.
No hardcoded colors
adoption.token_adoption.no_hardcoded_colors
Color values in the codebase written as raw hex, rgb() or hsl(). A raw color counts even when it equals a registered token value, as raw spacing and typography values do.
| Result | When |
|---|---|
| Pass | No raw color values. |
| Warning | Some raw color values, up to 30% of all color values. |
| Fail | More than 30% of color values are raw. |
| Skipped | No color style values were found, or no color tokens are registered. Tokens with no category count as color tokens. |
How to improve. Use semantic color tokens such as var(--foreground) instead of hex, rgb or hsl values.
No hardcoded spacing
adoption.token_adoption.no_hardcoded_spacing
Spacing values written as raw px, rem or em numbers rather than a token reference, including literals that happen to equal a token value.
| Result | When |
|---|---|
| Pass | No hardcoded spacing values. |
| Warning | Some, up to 30% of all spacing values. |
| Fail | More than 30% of spacing values are hardcoded. |
| Skipped | No spacing style values were found, or no spacing tokens are registered. |
How to improve. Use spacing scale tokens instead of arbitrary px or rem values.
No hardcoded typography
adoption.token_adoption.no_hardcoded_typography
Font values written as raw px, rem, em or pt numbers rather than a token reference, including literals that happen to equal a token value.
| Result | When |
|---|---|
| Pass | No hardcoded typography values. |
| Warning | Some, up to 30% of all typography values. |
| Fail | More than 30% of typography values are hardcoded. |
| Skipped | No typography style values were found, or no typography tokens are registered. |
How to improve. Use typography scale tokens, for font size, weight and line height, instead of raw values.
Token coverage by category
adoption.token_adoption.coverage_completeness
Whether registered tokens cover the three required categories: color, spacing and typography. If no token declares a category, categories are inferred from token names; for example, a name containing font counts as typography.
| Result | When |
|---|---|
| Pass | All three categories have tokens. |
| Warning | One category is missing. |
| Fail | Two or more categories are missing, or no tokens are registered. |
| Skipped | Not reported by this checkpoint. |
How to improve. Add tokens for the missing categories.
Adoption of presets
Share of components using presets
adoption.preset_adoption.usage_rate
The share of component instances in the codebase that use a preset.
| Result | When |
|---|---|
| Pass | At least 60% of instances use a preset. |
| Warning | Between 30% and 60%. |
| Fail | Below 30%. |
| Skipped | No component instances were provided. |
How to improve. Replace manual prop combinations with preset references where a preset exists.
No manual props where a preset exists
adoption.preset_adoption.no_manual_when_exists
Instances of components that have at least one preset but are configured with manual props instead.
| Result | When |
|---|---|
| Pass | Every instance of a component that has presets uses one. |
| Warning | Some do not, up to 30% of those instances. |
| Fail | More than 30% of those instances use manual props. |
| Skipped | No component instances or no presets were provided. |
How to improve. Switch those instances to a preset. The result lists the components with the most manual uses.
Components with at least one preset
adoption.preset_adoption.variant_coverage
Components used in the codebase that have no preset at all.
| Result | When |
|---|---|
| Pass | Every component in use has at least one preset. |
| Warning | Some do not, up to half of the components in use. |
| Fail | More than half of the components in use have no preset. |
| Skipped | No component instances were provided. |
How to improve. Create presets for the uncovered components, starting with the most used.
No repeated manual prop patterns
adoption.preset_adoption.no_duplicate_props
Manual instances (not using a preset) that repeat exactly the same component and prop combination. Each repeated combination is a candidate for a new preset.
| Result | When |
|---|---|
| Pass | No combination repeats, or every instance already uses a preset. |
| Warning | 1 to 5 repeated combinations. |
| Fail | More than 5 repeated combinations. |
| Skipped | No component instances were provided. |
How to improve. Turn each repeated combination into a preset.
Pattern adherence
Pattern compliance rate
adoption.pattern_adherence.compliance_rate
The share of compositions in the codebase that are linked to a declared pattern.
| Result | When |
|---|---|
| Pass | At least 50% of compositions follow a pattern. |
| Warning | Between 25% and 50%. |
| Fail | Below 25%. |
| Skipped | No compositions were provided. |
How to improve. Link common compositions to their patterns, and document the patterns so they get used.
No unlinked matches of declared patterns
adoption.pattern_adherence.no_adhoc_matches
Compositions not linked to any pattern that still contain at least 70% of a declared pattern's components, so they probably should use that pattern.
| Result | When |
|---|---|
| Pass | No such compositions, or every composition is linked to a pattern. |
| Warning | Some, up to 30% of the unlinked compositions. |
| Fail | More than 30% of the unlinked compositions match a pattern. |
| Skipped | No compositions or no patterns were provided. |
How to improve. Link each matching composition to the pattern it follows.
Patterns with descriptions
adoption.pattern_adherence.documentation_coverage
Declared patterns that have a non-empty description.
| Result | When |
|---|---|
| Pass | Every pattern has a description. |
| Warning | Some do not, up to half. |
| Fail | More than half of the patterns have no description. |
| Skipped | No patterns are registered. |
How to improve. Add a description to each undocumented pattern.