Typography health audit

Understand your typography system's health with actionable insights.

What is the typography audit?

The typography audit analyzes your design system's typography configuration and provides:

• Health score (0-100): overall typography quality
• Grade (A, F): quick assessment
• Category breakdown: detailed scores per area
• Recommendations: specific improvements to make

Categories

Your typography is evaluated across six categories.

Foundations (25%)

The building blocks: type scale, font families, and base settings. A weak foundation affects everything else.

Key checks:

• Is there a base font size?
• Are font families defined?
• Is the type scale mathematical?

Tokens (15%)

How well your tokens are defined and structured.

Key checks:

• Are size, weight, and line-height tokens defined?
• Are tokens actually being used?
• Is naming consistent?

Semantic (20%)

Whether your typography has clear meaning and purpose.

Key checks:

• Are roles defined (heading, body, caption)?
• Is usage documented?
• Do tokens cover common UI needs?

Responsive (10%)

How typography adapts across screen sizes.

Key checks:

• Does typography adapt to breakpoints?
• Are scaling rules defined (fluid or breakpoints)?
• Is mobile styling consistent?

Accessibility (20%)

Critical for users with visual impairments or reading difficulties.

Key checks:

• Are minimum text sizes respected (14px body, 12px caption)?
• Is body text line-height readable (≥ 1.5)?
• Is letter-spacing not too tight?

Usage (10%)

Governance and documentation quality.

Key checks:

• Do tokens have descriptions/guidance?
• Are arbitrary values avoided?
• Is the system documented?

Understanding your score

Common issues and fixes

"No typographic scale detected"

Problem: Font sizes don't follow a mathematical ratio.

Fix: Use a scale ratio like 1.25 (Major Third) or 1.333 (Perfect Fourth):

base: 16px
lg:   16 * 1.25 = 20px
xl:   20 * 1.25 = 25px

"Body text line-height too tight"

Problem: Line-height under 1.5 makes long text hard to read.

Fix: Set body text line-height to at least 1.5:

--line-height-normal: 1.5;

"Arbitrary values detected"

Problem: Code uses hardcoded values like text-[14px] instead of tokens.

Fix:

1. Identify commonly used arbitrary values
2. Create tokens for them
3. Replace hardcoded values with tokens
4. Consider lint rules to prevent future arbitrary values

"Missing token guidance"

Problem: Tokens lack descriptions explaining when to use them.

Fix: Add descriptions to tokens:

fontSize: {
  base: {
    value: '1rem',
    description: 'Default body text size',
    usage: ['Paragraphs', 'List items', 'Table cells'],
  },
}

"Too many font sizes"

Problem: More than 12-15 font sizes creates inconsistency.

Fix:

1. Audit which sizes are actually used
2. Consolidate similar sizes
3. Remove unused sizes
4. Stick to 8-12 sizes for most systems

Improving your score

Quick wins

1. Add descriptions to your most-used tokens
2. Document your scale ratio in config
3. Set minimum sizes for body (14px) and caption (12px)
4. Use line-height 1.5+ for body text

Medium effort

1. Implement fluid typography with clamp()
2. Define semantic roles (heading, body, caption, etc.)
3. Create governance docs for adding new tokens
4. Audit arbitrary values in codebase

Structural improvements

1. Establish a type scale with consistent ratios
2. Integrate with the scanner to track actual usage
3. Create onboarding docs for new team members
4. Set up lint rules to enforce token usage

Running an audit

In the dashboard

Navigate to Health → Typography to see your current score and recommendations.

Via API

import { runTypographyAudit } from '@preset/health'

const result = runTypographyAudit(yourConfig)
console.log(result.score, result.grade)

Quick check

For a fast assessment of just critical checks:

import { runQuickTypographyAudit } from '@preset/health'

const quick = runQuickTypographyAudit(yourConfig)

FAQ

Why is accessibility weighted so heavily (20%)?

Typography accessibility directly affects users with visual impairments, dyslexia, and cognitive disabilities. Small text and tight spacing make content unreadable for many users.

What's the ideal score to aim for?

Aim for 75+ (B grade) for a production-ready system. 90+ (A grade) represents industry-leading typography.

Does this check color contrast?

Not yet. Color contrast requires integration with your color tokens. Run the color audit separately for contrast checking.

How often should I run the audit?

Run after any typography changes. Consider adding to CI/CD to catch regressions.

Can I skip certain checks?

Yes. Pass checkOptions: { skip: ['checkpoint-id'] } to skip specific checks.