Typography checkpoints
The typography audit checks a design system's type foundations, tokens, semantic styles, responsive behaviour, accessibility and documentation.
Each checkpoint reports pass, warning, fail or skipped. A finding for a checkpoint links its section on this page.
Foundations
Base Font Size
foundations-base-font-size · High risk
Checks that a base font size is defined: a size named base, md, default or 16. If there is none, it reports whether any font sizes exist at all.
| Reported as | What it means | How to fix it |
|---|---|---|
no-explicit-base | Font sizes exist, but none is named as the base. | Add a base or md font size token to anchor the scale. |
no-font-sizes | No font sizes are defined. | Define a base font size (typically 16px, or 1rem) and a scale around it. |
Why it matters. Every other size is chosen relative to the base. Without a named base, the scale has no anchor and sizes drift.
Font Families
foundations-font-families · Low risk
Checks that font family tokens are defined, that they are not only system defaults, and that each font stack ends in a generic family (sans-serif, serif, monospace, cursive, fantasy or system-ui).
| Reported as | What it means | How to fix it |
|---|---|---|
no-font-families | No font family tokens are defined. | Define font family tokens for sans, serif and mono. |
empty-font-families | The font family config exists but is empty. | Add font family definitions. |
missing-fallbacks | A font stack has only one font, with no fallback. | Add at least one fallback font to each stack. |
system-defaults-only | Every font family is a system default. | Consider a custom font for brand differentiation. System fonts are acceptable but may lack visual distinction. |
no-generic-fallback | A font stack does not end in a generic family. | End each font stack with a generic family, such as sans-serif, serif or monospace. |
Why it matters. A font stack that ends in a generic family still renders readable text when a custom font fails to load.
Letter Spacing Tokens
foundations-letter-spacing · Medium risk
Checks that letter-spacing tokens are defined, with at least 3 values (for example tight, normal and wide).
| Reported as | What it means | How to fix it |
|---|---|---|
no-letter-spacing | No letter-spacing tokens are defined. | Define letter-spacing tokens, for example tighter, tight, normal, wide and wider. |
empty-letter-spacing | The letter-spacing config exists but is empty. | Add letter-spacing values. |
insufficient-letter-spacing | Fewer than 3 letter-spacing values are defined. | Add at least 3 values: tight, normal and wide. |
Why it matters. Letter spacing tunes readability at different sizes: large text usually needs tightening, small text needs room.
Line Height Tokens
foundations-line-height · Medium risk
Checks that line-height tokens are defined, that at least one is unitless rather than in a fixed unit, and that there are at least 3 (for example tight, normal and relaxed).
| Reported as | What it means | How to fix it |
|---|---|---|
no-line-height | No line-height tokens are defined. | Define line-height tokens: tight, normal and relaxed. |
empty-line-height | The line-height config exists but is empty. | Add line-height values. |
fixed-unit-line-height | No line height is unitless; all use fixed units such as px. | Use unitless values (for example 1.5 instead of 24px) so line height scales with the font size. |
insufficient-line-height | Fewer than 3 line-height values are defined. | Add at least tight for headings, normal for body and relaxed for large text. |
Why it matters. Line height directly affects readability. Too tight makes text hard to scan; too loose breaks the connection between lines.
Type Scale Ratio
foundations-scale-documented · High risk
Checks that the type scale ratio is documented in the config. When it is not, it looks for a consistent ratio between the font sizes: a consistent but undocumented ratio warns, and an inconsistent one fails.
| Reported as | What it means | How to fix it |
|---|---|---|
undocumented-ratio | The font sizes follow a consistent ratio, but it is not documented. | Document the ratio, for example as a scale.ratio property. |
inconsistent-ratio | The ratios between font sizes vary. | Define a consistent type scale using a ratio such as 1.125, 1.2, 1.25 or 1.333, and document it. |
no-scale-documentation | There is no documented scale and no ratio can be detected. | Choose a type scale ratio (common choices: 1.125, 1.2, 1.25) and document it. |
Why it matters. A documented ratio makes size decisions predictable. Without it, designers make arbitrary choices that fragment the visual language.
Number of Font Sizes
foundations-limited-font-sizes · Low risk
Checks how many font sizes are defined. More than the maximum (10 by default, set with thresholds.maxFontSizes) warns, and fewer than 5 warns. Skipped when no font sizes are defined.
| Reported as | What it means | How to fix it |
|---|---|---|
too-many-font-sizes | More font sizes are defined than the maximum. | Consolidate to the maximum or fewer. A typical scale is xs, sm, base, lg, xl, 2xl and 3xl. |
too-few-font-sizes | Fewer than 5 font sizes are defined. | Add sizes for flexibility; 5 to 8 is typical. |
Why it matters. Too many sizes create decision fatigue and inconsistency; too few force one-off values.
Typographic Scale
foundations-typographic-scale · High risk
Checks that a font size scale exists, uses semantic names (xs, sm, md, lg, xl) rather than pixel values, has at least 3 sizes, and that no two sizes have the same value. It compares sizes by value, not by name, so names that are out of order are not detected.
| Reported as | What it means | How to fix it |
|---|---|---|
no-typographic-scale | No font size scale is defined. | Define a font size scale with semantic names, including at least xs, sm, base or md, lg and xl. |
empty-typographic-scale | The font size config exists but is empty. | Add font size values to the scale. |
non-semantic-names | Font sizes are named by pixel value rather than by size. | Use semantic size names (xs, sm, md, lg, xl) instead of pixel values. |
incomplete-scale | Fewer than 3 sizes in the scale could be read. | Add sizes to complete the scale. |
non-monotonic-scale | Two sizes in the scale have the same value. | Give each scale step a distinct size. |
Why it matters. A named, ordered scale is what makes sizes reusable. Pixel names and out-of-order steps lead to guesswork.
Tokens
Font Size Tokens
tokens-font-size-defined · High risk
Checks that font-size tokens are defined, with at least 4 values.
| Reported as | What it means | How to fix it |
|---|---|---|
no-font-size-tokens | No font-size tokens are defined. | Define font-size tokens on a scale such as xs, sm, md, lg and xl. |
empty-font-size-tokens | The font-size config exists but has no values. | Add font-size token values. |
insufficient-font-size-tokens | Fewer than 4 font-size tokens are defined. | Add more font-size tokens; 5 to 8 is typical. |
Why it matters. Without font-size tokens, every size is a hardcoded value that cannot be changed in one place.
Line Height Token Set
tokens-line-height-defined · Medium risk
Checks that line-height tokens are defined, with at least 3 values.
| Reported as | What it means | How to fix it |
|---|---|---|
no-line-height-tokens | No line-height tokens are defined. | Define line-height tokens for a consistent vertical rhythm, for example tight (1.25), normal (1.5) and relaxed (1.625). |
empty-line-height-tokens | The line-height config exists but has no values. | Add line-height token values. |
insufficient-line-height-tokens | Fewer than 3 line-height tokens are defined. | Add at least tight, normal and relaxed. |
Why it matters. Line-height tokens keep vertical rhythm consistent across components.
Font Weight Tokens
tokens-font-weight-defined · Medium risk
Checks that font-weight tokens are defined, with at least 3 values.
| Reported as | What it means | How to fix it |
|---|---|---|
no-font-weight-tokens | No font-weight tokens are defined. | Define font-weight tokens for consistent emphasis, for example normal (400), medium (500), semibold (600) and bold (700). |
empty-font-weight-tokens | The font-weight config exists but has no values. | Add font-weight token values. |
insufficient-font-weight-tokens | Fewer than 3 font-weight tokens are defined. | Add at least normal, medium and bold. |
Why it matters. Weight tokens keep emphasis consistent and stop one-off weights the font may not include.
No Pixel Naming
tokens-no-px-naming · Medium risk
Checks token names and values for pixel units. A token named like a pixel value (for example 14px) fails. Raw px font-size values, or line heights in px, warn.
| Reported as | What it means | How to fix it |
|---|---|---|
px-naming-violations | A token is named after a pixel value. | Use semantic names such as sm, md and lg instead of 14px or 16px. |
px-value-warnings | Tokens use raw px values. | Use rem or em for font sizes so they respect user preferences, and unitless values for line height. |
Why it matters. A name like 16px stops being true the moment the value changes, and px values ignore the reader's text size settings.
Token Reuse
tokens-reused-across-styles · Medium risk
Needs usage data from a codebase scan, and is skipped without it. Divides the number of tokens the scan found in use by the number of tokens defined: 80% or more passes, 50% or more warns, and less fails. Used tokens are not matched by name against the defined ones, so any token in use counts.
| Reported as | What it means | How to fix it |
|---|---|---|
low-token-reuse | Between 50% and 80% of tokens are used. | Review unused tokens; remove them or document why they exist. |
very-low-token-reuse | Fewer than half of the tokens are used. | Remove unused tokens, or check that the codebase is using the design system. |
Why it matters. Unused tokens add maintenance work and suggest the codebase is not using the system.
Token Naming Consistency
tokens-logical-grouping · Low risk
Checks how tokens are named. Mixing conventions (kebab-case, camelCase, snake_case) warns, more than 8 different name prefixes warns, and names without a size or semantic indicator warn.
| Reported as | What it means | How to fix it |
|---|---|---|
mixed-naming-conventions | Token names mix naming conventions. | Use one naming convention; kebab-case is recommended. |
too-many-prefixes | More than 8 different name prefixes are used. | Consolidate prefixes so the token set is easier to navigate. |
unclear-naming | Token names lack a size or semantic indicator. | Use size-based (xs, sm, md, lg) or semantic (heading, body) names. |
Why it matters. Consistent naming makes tokens discoverable. Inconsistent naming leads to misuse and duplicate tokens.
Semantic
Semantic Text Roles
semantic-roles-defined · Medium risk
Checks that typography token names map to semantic roles such as heading, body, caption, label and code. No tokens, or no semantic names, fails. Missing heading or body roles, or fewer than 4 role categories, warns.
| Reported as | What it means | How to fix it |
|---|---|---|
no-tokens | No typography tokens are defined. | Define semantic text roles: heading, body, caption and so on. |
no-semantic-roles | Token names describe sizes, not roles. | Use semantic names such as heading-1, body and caption instead of lg, md and sm. |
incomplete-semantic-roles | Heading or body roles are missing. | Add heading styles (heading-1, heading-2 ...) and body styles (body, body-large, body-small). |
limited-semantic-roles | Fewer than 4 role categories are defined. | Consider adding roles such as caption, label and code. |
Why it matters. Semantic names encode intent, so the same size can be styled differently for headings and body text later.
Style Use Cases
semantic-use-case-documented · High risk
Checks that composite text styles have names that say what they are for. 80% or more with semantic names passes, 50% or more warns, and less fails. Skipped when no textStyles are defined. An empty textStyles map is not skipped: it scores 0% and fails.
| Reported as | What it means | How to fix it |
|---|---|---|
partial-documentation | Between 50% and 80% of text styles have names that state their use. | Use descriptive names that indicate the use case. |
poor-documentation | Fewer than half of the text styles state their use. | Rename styles to say what they are for, such as heading-page, body-article or caption-image. |
Why it matters. A style whose name states its use is chosen correctly without a lookup.
Style Adoption
semantic-styles-applied · High risk
Needs usage data from a codebase scan, and is skipped without it. Divides the number of tokens the scan found in use by the number of font sizes and text styles defined: 80% or more passes, 50% or more warns, and less fails. Used tokens are not matched by name against the defined styles, so any token in use counts.
| Reported as | What it means | How to fix it |
|---|---|---|
low-style-adoption | Between 50% and 80% of styles are used. | Review unused styles: remove them, or document why they exist. |
very-low-style-adoption | Fewer than half of the styles are used. | Remove unused styles or make them easier to discover. |
Why it matters. Styles that are defined but never used point to unclear naming or missing documentation.
No Duplicate Styles
semantic-no-duplicates · Medium risk
Checks for text styles with the same definition. Duplicates that look like intentional aliases pass with a note; other duplicates warn.
| Reported as | What it means | How to fix it |
|---|---|---|
duplicate-styles | Two or more styles have the same definition. | Consolidate duplicate styles, or document the relationship if they are intentional aliases. |
Why it matters. Duplicate styles split usage and drift apart over time.
UI Text Coverage
semantic-ui-coverage · Medium risk
Checks that text styles cover the main UI needs: at least 3 heading styles, 2 body styles and 2 utility styles (such as caption, label and small).
| Reported as | What it means | How to fix it |
|---|---|---|
no-tokens | No typography tokens are defined. | Define text styles that cover headings, body and utility text. |
incomplete-coverage | Some categories have fewer styles than recommended. | Add the missing heading, body or utility styles. |
poor-coverage | Most categories are under-covered. | A complete system needs heading, body and utility styles. |
Why it matters. When every common text context has a style, there is no reason to invent one.
Responsive
Responsive Font Sizes
responsive-breakpoint-adaptation · High risk
Checks for typography that adapts to screen size: font sizes using clamp() or viewport units, responsive token variants, or responsive classes in the codebase. None of these fails; partial adaptation warns.
| Reported as | What it means | How to fix it |
|---|---|---|
no-responsive-adaptation | No responsive typography was found; font sizes are fixed. | Use clamp() for fluid sizes, for example clamp(1rem, 2vw + 1rem, 2rem), or responsive tokens with breakpoint prefixes. |
partial-responsive-adaptation | Some typography adapts, but not consistently. | Consider clamp() for smoother scaling across viewports. |
Why it matters. Fixed sizes that suit a desktop are often too large or too small elsewhere.
Scaling Rules
responsive-scaling-rules · High risk
Checks for a defined scaling strategy, looking for fluid sizes, a scale ratio, a responsive config and breakpoint tokens. None of these fails; only one warns.
| Reported as | What it means | How to fix it |
|---|---|---|
no-scaling-rules | No responsive scaling rules were found. | Define a scaling strategy (fluid with clamp, or breakpoint-based) and document the scale ratio and base size. |
limited-scaling-rules | Only one scaling indicator was found. | Add more complete responsive rules and document how typography should scale. |
Why it matters. Without written scaling rules, each screen size gets ad hoc adjustments.
No Mobile-Only Overrides
responsive-no-mobile-chaos · Medium risk
Checks for mobile-only typography. With usage data from a codebase scan, a responsive token used without its base token, or sm: overrides heavily outnumbering base usage, fails. Without usage data it only warns, on mobile-specific token names or an sm: token with no base token.
| Reported as | What it means | How to fix it |
|---|---|---|
mobile-chaos-detected | Usage data shows a responsive token used without its base token, or sm: overrides heavily outnumbering base usage. | Give each responsive token a base token, avoid excessive mobile overrides, and design mobile-first. |
potential-mobile-chaos | Mobile-specific token names, or an sm: token with no base token, were found in the config. | Review mobile-specific tokens for consistency. |
Why it matters. A separate mobile type system doubles the work and drifts from the main one.
Accessibility
Minimum Text Sizes
accessibility-minimum-text-sizes · High risk
Checks every font size against a minimum: 14px for body text and 12px for caption or small text. Fluid clamp() sizes are checked at their minimum; sizes that cannot be read, such as calc(), are skipped. Warns when no font sizes are defined, since nothing can be checked.
| Reported as | What it means | How to fix it |
|---|---|---|
no-font-sizes | No font sizes are defined, so minimums cannot be checked. | Define font size tokens. |
small-text-<name> | A font size is below its minimum. | Raise it to at least 14px for body text or 12px for captions. |
Why it matters. Text below these sizes is hard to read for many people, especially on small screens.
Text Contrast
accessibility-contrast-requirements · High risk
Not measured yet. This check always reports skipped: contrast needs the color tokens, so it points to the color audit instead.
| Reported as | What it means | How to fix it |
|---|---|---|
requires-color-integration | Contrast cannot be checked without color tokens. | Run the color audit, and make sure text meets WCAG AA: 4.5:1 for normal text and 3:1 for large text. |
Why it matters. Insufficient contrast makes text unreadable for many people, including those with low vision or in bright light.
Body Text Line Height
accessibility-long-text-readable · Low risk
Checks body text line heights: each must be at least 1.5 (WCAG 1.4.12). Warns when no line-height tokens are defined.
| Reported as | What it means | How to fix it |
|---|---|---|
no-line-height-tokens | No line-height tokens are defined, so body text cannot be checked. | Define line-height tokens for body text. |
tight-line-height-<name> | A body text line height is below 1.5. | Set body text line height to at least 1.5. |
Why it matters. Tight line height makes long passages hard to follow, especially for readers with dyslexia or low vision.
Letter Spacing Not Too Tight
accessibility-spacing-not-tight · Low risk
Checks letter-spacing values against -0.05em: one or two tighter values warn, and three or more fail. Passes when no letter-spacing tokens are defined, since browser default spacing applies.
| Reported as | What it means | How to fix it |
|---|---|---|
tight-spacing-<name> | A letter-spacing value is tighter than -0.05em. | Loosen it to -0.05em or wider. WCAG 1.4.12 asks that text still works at 0.12 times the font size. |
Why it matters. Very tight letter spacing reduces readability, especially for readers with dyslexia.
Usage
Usage Guidance
usage-guidance-exists · High risk
Checks how many font-size tokens have a description or usage guidance: 50% or more passes, 25% or more warns, and less fails. Text style guidance is reported but does not change the result. Warns when no font-size tokens are defined.
| Reported as | What it means | How to fix it |
|---|---|---|
no-tokens-defined | No font-size tokens are defined, so guidance cannot be checked. | Define font size tokens with descriptions and usage guidance. |
partial-guidance-coverage | Between 25% and 50% of font-size tokens have guidance. | Add descriptions to more tokens, including aiGuidance for AI coding tools. |
insufficient-guidance | Fewer than 25% of font-size tokens have guidance. | Add descriptions explaining when to use each size, and what to avoid. |
Why it matters. Undocumented tokens are hard to find and easy to misuse, so people create duplicates instead.
No Arbitrary Values
usage-no-arbitrary-values · High risk
Needs usage data from a codebase scan, and is skipped without it. Measures the share of typography usage that is arbitrary values rather than tokens: under 5% passes, under 15% warns, and more fails.
| Reported as | What it means | How to fix it |
|---|---|---|
no-usage-data | No usage data was provided. | Provide a usage graph from a codebase scan. |
no-typography-usage | No typography token usage was found in the codebase. | Make sure typography tokens are used in the codebase. |
some-arbitrary-values | Between 5% and 15% of typography usage is arbitrary. | Convert arbitrary values to design system tokens where possible. |
arbitrary-<token> | 15% or more of typography usage is arbitrary. Each code names one arbitrary class, such as text-[14px] (up to 5). | Replace each arbitrary class with a design system token. |
Why it matters. Arbitrary values bypass the system, so changes to tokens never reach them.
Rules for New Styles
usage-addition-rules-exist · Medium risk
Needs design system metadata, and is skipped without it. Looks for governance indicators, such as a contributing guide: 2 or more passes, 1 warns, and none fails.
| Reported as | What it means | How to fix it |
|---|---|---|
no-metadata | No design system metadata was provided. | Provide design system metadata to enable governance checks. |
partial-governance | Only one governance indicator was found. | Add a CONTRIBUTING.md with typography token guidelines, a proposal process and review requirements. |
no-governance-docs | No governance documentation was found. | Create a contributing guide for adding typography tokens and say who approves changes. |
Why it matters. Without rules for adding styles, new styles appear ad hoc and the system fragments.
Typography Onboarding
usage-onboarding-exists · Low risk
Needs design system metadata, and is skipped without it. Looks for onboarding indicators, such as typography documentation: 2 or more passes, 1 warns, and none fails.
| Reported as | What it means | How to fix it |
|---|---|---|
no-metadata | No design system metadata was provided. | Provide design system metadata to enable onboarding checks. |
partial-onboarding | Only one onboarding indicator was found. | Add a typography section to onboarding and a quick-start guide. |
no-onboarding | No typography onboarding material was found. | Create onboarding documentation with typography practices and examples. |
Why it matters. New team members follow the system only if they learn it early.
System Documentation
usage-system-documented · Medium risk
Checks documentation indicators in the design system metadata (such as a description, the scale ratio, token descriptions and a changelog). 70% or more passes, 40% or more warns, and less fails. Warns when no indicators are available.
| Reported as | What it means | How to fix it |
|---|---|---|
no-doc-indicators | No documentation indicators were available. | Provide design system metadata for a documentation assessment. |
partial-documentation | Between 40% and 70% of documentation indicators are present. | Fill in the missing documentation. |
insufficient-documentation | Fewer than 40% of documentation indicators are present. | Add a system description, document the scale ratio, describe individual tokens and keep a changelog. |
Why it matters. A documented system can be used and changed without asking its authors.
When a check cannot run
Any checkpoint can report this instead of its own result.
| Reported as | What it means | How to fix it |
|---|---|---|
check-error | The check could not run on this config, usually because a value has an unexpected type (for example a font stack given as a list instead of a comma-separated string). The evidence names the error. | Correct the value the evidence names, then run the audit again. |