Skip to main content
  • Created:
  • Updated:
  • Author:
    Takeshi Takatsudo

Typography Token Patterns

The Problem​

Tailwind CSS ships with 13 font-size steps (text-xs through text-9xl), 9 font-weight values (font-thin through font-black), 6+ line-height values, and multiple font-family options. Teams end up using text-sm, text-base, and text-lg interchangeably for body text, and font-semibold in one component while another uses font-bold for the same visual emphasis.

This typography drift is harder to spot than spacing or color drift because the differences are subtle — 14px vs 16px body text, or font-medium vs font-semibold — but they accumulate into an interface that feels inconsistent without anyone being able to pinpoint why.

The Solution​

Reset all default typography tokens and define a small semantic set:

  • Font sizes: 5 sizes — caption, body, subheading, heading, display
  • Font weights: 3 weights — normal, medium, bold
  • Line heights: 3 values — tight, normal, relaxed
  • Font families: 2 families — sans, mono

The @theme Typography Block​

@theme {
  /* Reset ALL default typography */
  --font-size-*: initial;
  --font-weight-*: initial;
  --line-height-*: initial;
  --font-family-*: initial;
  --letter-spacing-*: initial;

  /* ── Font sizes (5 steps) ── */
  --font-size-caption: 0.75rem;    /* 12px */
  --font-size-body: 1rem;          /* 16px */
  --font-size-subheading: 1.25rem; /* 20px */
  --font-size-heading: 1.75rem;    /* 28px */
  --font-size-display: 2.5rem;     /* 40px */

  /* ── Font weights (3 steps) ── */
  --font-weight-normal: 400;
  --font-weight-medium: 500;
  --font-weight-bold: 700;

  /* ── Line heights (3 steps) ── */
  --line-height-tight: 1.25;
  --line-height-normal: 1.5;
  --line-height-relaxed: 1.75;

  /* ── Font families (2 families) ── */
  --font-family-sans: "Inter", system-ui, sans-serif;
  --font-family-mono: "JetBrains Mono", ui-monospace, monospace;
}

After this configuration:

  • text-sm — build error (no --font-size-sm token exists)
  • font-semibold — build error (no --font-weight-semibold token exists)
  • text-body — works (resolves to font-size: 1rem)
  • font-bold — works (resolves to font-weight: 700)
  • leading-normal — works (resolves to line-height: 1.5)

Demos​

Default Font Sizes vs Semantic Typography Tokens​

The left column shows Tailwind's 13 default font-size steps — from text-xs to text-9xl. The right column shows the 5 semantic sizes that replace them. Each semantic token maps to a specific role in the type hierarchy.

13 Default Sizes vs 5 Semantic Sizes

Typography Scale Card​

A visual hierarchy card showing all 5 semantic sizes with their corresponding weights and line-heights. This is the complete typographic vocabulary of the project.

Typography Scale — All 5 Sizes in Hierarchy

Article Layout with Semantic Typography​

A complete article layout using only the 5 semantic font sizes, 3 weights, and 3 line-heights. No numeric Tailwind classes like text-lg or font-semibold are used — everything maps to a semantic token.

Article Layout with Semantic Typography Tokens

When to Use​

Typography tokens pair naturally with color tokens and the spacing strategy from the parent article. Together, they form the core of a tight design token system that constrains the three most common sources of visual drift.

Apply typography tokens when:

  • The project uses more than 3 font sizes in practice — constrain them to exactly 5
  • Multiple developers write markup and each reaches for different text sizes
  • The design system defines a type scale by name (e.g., "body," "heading") rather than by pixel value

References​

Last updated on by Takeshi Takatsudo