Typography Tokens Explained

Typography tokens explained in practical terms means understanding how design systems encode typographic decisions into reusable values. Typography involves multiple interconnected properties including font families, sizes, weights, line heights, and letter spacing. Managing these properties through tokens creates consistency while enabling systematic updates across an entire product.

What Are Typography Tokens

Typography tokens are design tokens that store values related to text styling. Unlike simpler tokens that contain single values, typography often requires compound tokens that group related properties together. A heading style involves not just a font size but also an appropriate line height, font weight, and potentially letter spacing adjustments.

Typography tokens can exist at two levels. Primitive typography tokens define individual values like specific font sizes or weight numbers. Composite typography tokens combine multiple primitives into complete text styles ready for application.

How Typography Tokens Work

Typography token systems typically begin with scales for each individual property.

Font size scales establish the available text sizes:

fontSize.xs: 12px
fontSize.sm: 14px
fontSize.md: 16px
fontSize.lg: 18px
fontSize.xl: 20px
fontSize.2xl: 24px
fontSize.3xl: 30px
fontSize.4xl: 36px

Line height tokens define vertical spacing, often as unitless multipliers:

lineHeight.tight: 1.25
lineHeight.base: 1.5
lineHeight.relaxed: 1.75

Font weight tokens map to standard weight values:

fontWeight.normal: 400
fontWeight.medium: 500
fontWeight.semibold: 600
fontWeight.bold: 700

Font family tokens specify typeface stacks:

fontFamily.sans: "Inter, system-ui, sans-serif"
fontFamily.mono: "JetBrains Mono, monospace"

Composite tokens combine these primitives into complete styles:

typography.body.md:
  fontFamily: {ref: fontFamily.sans}
  fontSize: {ref: fontSize.md}
  lineHeight: {ref: lineHeight.base}
  fontWeight: {ref: fontWeight.normal}

typography.heading.lg:
  fontFamily: {ref: fontFamily.sans}
  fontSize: {ref: fontSize.2xl}
  lineHeight: {ref: lineHeight.tight}
  fontWeight: {ref: fontWeight.bold}

These composite tokens provide complete typographic recipes that maintain proportional relationships between properties.

Key Considerations

• Font size scales should follow a mathematical ratio for visual harmony
• Line heights should adjust relative to font size, tighter for large text
• Letter spacing may need adjustment at different sizes, especially for headings
• Font family tokens should include complete fallback stacks
• Variable fonts enable weight and width tokens along a continuous range
• Responsive typography may require different scales at different viewports
• Accessibility requires minimum font sizes and adequate line heights
• Platform differences in font rendering affect how tokens translate

Common Questions

How should font size scales be constructed?

Font size scales work best when based on mathematical ratios that produce harmonious relationships. Common ratios include the major second (1.125), minor third (1.2), major third (1.25), and perfect fourth (1.333). A base size multiplied by the ratio repeatedly generates the scale.

Starting with 16px as the base and using a 1.25 ratio produces: 16, 20, 25, 31, 39, and so on. These sizes can be rounded to practical values. The mathematical foundation ensures visual relationships hold together.

Custom scales that pick arbitrary sizes often produce inconsistent results. While such scales might hit specific desired values, the relationships between sizes lack coherent logic, producing subtle visual disharmony.

Practical considerations sometimes override pure mathematics. If a scale produces sizes that are too similar to be meaningfully distinct, adjustments make sense. The goal is a scale where each step serves a clear purpose.

Should typography tokens be composite or individual?

Both approaches have valid applications, and most systems use both. Individual tokens for font size, weight, and line height provide flexibility for edge cases where a complete style does not apply. Composite tokens for heading styles, body text, and captions enforce the intended combinations.

Composite tokens reduce errors by packaging related values together. When developers use typography.body.md, they receive all the properties that constitute medium body text. Without composite tokens, developers might pair font sizes with inappropriate line heights.

The recommended approach defines both layers. Individual property tokens provide the vocabulary. Composite tokens combine that vocabulary into the common patterns. Documentation emphasizes composite tokens for typical usage while making individual tokens available for justified exceptions.

How should responsive typography be handled?

Responsive typography adjusts text sizing based on viewport dimensions. Several implementation approaches exist.

Fluid typography uses CSS clamp or viewport-relative units to scale smoothly between minimum and maximum sizes. Tokens can express these ranges:

fontSize.fluid.md: clamp(16px, 4vw, 20px)

This approach provides smooth scaling but limits control over exact breakpoint behavior.

Breakpoint-specific tokens define different values for different viewport ranges:

fontSize.md.mobile: 16px
fontSize.md.desktop: 18px

Build processes or CSS custom property overrides apply the appropriate values.

Some systems maintain a single token set and apply a scaling factor at the application level. The base typography scale remains constant, but a multiplier adjusts all sizes proportionally for different contexts.

Summary

Typography tokens systematize the multiple properties that constitute text styling. Effective systems define scales for individual properties like font size and line height, then combine these into composite tokens representing complete text styles. This layered approach provides flexibility while enforcing the proportional relationships that make typography feel cohesive and intentional.