name: typography
description: Apply professional typography principles to create readable, hierarchical, and aesthetically refined interfaces. Use when setting type scales, choosing fonts, adjusting spacing, designing text-heavy layouts, implementing dark mode typography, or when asked about readability, font pairing, line height, measure, typographic hierarchy, variable fonts, font loading, or OpenType features.

Typography

Professional typography for user interfaces, grounded in principles from the masters.

"Typography exists to honor content." — Robert Bringhurst

Reference Files

For detailed guidance on specific topics, consult these references:

Output Formats

Type System Recommendations

## Type System

### Scale
- Base: [size, e.g., 16px]
- Ratio: [e.g., Minor Third 1.200]
- Rationale: [why this ratio]

### Hierarchy
| Level | Size | Weight | Line Height | Letter Spacing | Use |
|-------|------|--------|-------------|----------------|-----|
| Display | ... | ... | ... | ... | Hero, marketing |
| H1 | ... | ... | ... | ... | Page titles |
| H2 | ... | ... | ... | ... | Section heads |
| Body | ... | ... | ... | ... | Paragraphs |
| Small | ... | ... | ... | ... | Captions, labels |

### Fonts
- Primary: [font] — [rationale]
- Secondary: [font, if applicable]
- Mono: [font, if applicable]

### Implementation
[Ready-to-use CSS/Tailwind]

Typography Audits

## Typography Audit

### Issues
| Element | Problem | Recommendation |
|---------|---------|----------------|
| ... | ... | ... |

### Quick Wins
- [Immediate improvement 1]
- [Immediate improvement 2]

Core Principles

The Four Fundamentals (Bringhurst)

The most important typographic considerations for body text:

1. Point size — 16px minimum for body; 14px absolute floor for secondary text
2. Line spacing — 1.5-1.7 for body; 1.1-1.3 for headings
3. Line length — 45-75 characters (66 ideal); use max-w-prose (~65ch)
4. Font choice — Match typeface to content and context

Hierarchy Through Contrast

Establish hierarchy using multiple dimensions:

"Use one typeface per design. Avoid italics and bold—rely on gradations of scale instead." — Massimo Vignelli

Restraint

• 1-2 font families maximum — One serif, one sans if pairing
• 3-4 heading levels in practice — Deeper nesting usually signals structure problems
• Stick to your type scale — Resist arbitrary sizes
• Let whitespace work — Don't fill every gap

"In the new computer age, the proliferation of typefaces represents a new level of visual pollution." — Massimo Vignelli

Type Scales

Modular Scale Ratios

Practical Scale (Minor Third @ 16px)

--text-xs:   12px;  /* 0.75rem */
--text-sm:   14px;  /* 0.875rem */
--text-base: 16px;  /* 1rem */
--text-lg:   18px;  /* 1.125rem — not in pure scale */
--text-xl:   20px;  /* 1.25rem */
--text-2xl:  24px;  /* 1.5rem */
--text-3xl:  30px;  /* 1.875rem */
--text-4xl:  36px;  /* 2.25rem */
--text-5xl:  48px;  /* 3rem */

When to Deviate

• Marketing/hero: Larger jumps allowed
• Dense data interfaces: Tighter scale
• Mobile: Slightly larger base (17-18px)

Spacing Guidelines

Line Height by Context

"The eye does not read letters, but the space between them." — Adrian Frutiger

Letter Spacing

All-caps rule: Always add tracking. Keep short (1-3 words).

Paragraph Spacing

• Between paragraphs: 1em to 1.5em (equal to or slightly more than line-height)
• After headings: Reduced top margin on first paragraph
• Between sections: 2-3× paragraph spacing

Font Selection

System Font Stacks

/* Sans-serif (modern) */
font-family: ui-sans-serif, system-ui, sans-serif, "Apple Color Emoji", "Segoe UI Emoji";

/* Serif */
font-family: ui-serif, Georgia, Cambria, "Times New Roman", serif;

/* Monospace */
font-family: ui-monospace, SFMono-Regular, Menlo, Monaco, Consolas, monospace;

Safe Web Font Recommendations

Pairing Principles

• Pair by contrast — Serif + sans-serif
• Match x-height — For visual harmony when mixed
• Ensure weight availability — Both need needed weights/styles

"A father should not have a favorite among his daughters." — Hermann Zapf (on his typefaces)

Modern CSS Typography

Text Wrapping

/* Balanced line lengths for headings (≤6 lines) */
h1, h2, h3, blockquote, figcaption {
  text-wrap: balance;
}

/* Prevent orphans in body text */
p, li {
  text-wrap: pretty;
}

Caveat: Don't use balance inside bordered containers—creates visual imbalance.

Fluid Typography

/* Font scales smoothly between breakpoints */
h1 {
  font-size: clamp(2rem, 1rem + 4vw, 4rem);
  line-height: clamp(1.1, 1.3 - 0.1vw, 1.3);
}

body {
  font-size: clamp(1rem, 0.95rem + 0.25vw, 1.125rem);
}

See fluid-typography.md for complete scale.

Text Truncation

/* Single line */
.truncate {
  white-space: nowrap;
  overflow: hidden;
  text-overflow: ellipsis;
}

/* Multi-line (2 lines) */
.line-clamp-2 {
  display: -webkit-box;
  -webkit-line-clamp: 2;
  -webkit-box-orient: vertical;
  overflow: hidden;
}

Dark Mode Typography

Weight Adjustment

Text appears heavier on dark backgrounds. Reduce weight slightly:

@media (prefers-color-scheme: dark) {
  body {
    font-weight: 350; /* Instead of 400 */
  }
  h1, h2, h3 {
    font-weight: 600; /* Instead of 700 */
  }
}

Font Smoothing

Apply antialiasing on dark backgrounds to counter perceived boldness:

.dark-bg {
  -webkit-font-smoothing: antialiased;
  -moz-osx-font-smoothing: grayscale;
}

Color Contrast

• Avoid pure white (#fff) on pure black (#000)—too harsh
• Use off-white (#f5f5f5) and near-black (#1a1a1a)
• Aim for 10:1 to 15:1 contrast in dark mode

Typographic Details

Quotation Marks

Use curly quotes, not straight:
- Correct: "Hello" and 'world'
- Incorrect: "Hello" and 'world'

Dashes

Numbers

See opentype-features.md for complete reference.

Accessibility

Minimums

User Preferences

/* Use relative units so users can scale */
body {
  font-size: 1rem; /* Not 16px */
}

/* Respect reduced motion */
@media (prefers-reduced-motion: reduce) {
  * {
    transition: none !important;
  }
}

Dyslexia Considerations

• Avoid justified text
• Prefer sans-serif with distinct letterforms (a vs α, l vs 1 vs I)
• Generous line height and paragraph spacing
• Consider offering OpenDyslexic as option

Common Mistakes

Avoid

• All-caps body text or long headings
• Centered body paragraphs
• Line length over 80 characters
• Insufficient contrast for "aesthetic" reasons
• Mixing too many font families (>2)
• Decorative fonts for UI text
• Justified text on the web
• Tiny gray text on white backgrounds
• Letter-spacing on Arabic text

Watch For

• Orphans and widows in prominent text
• Inconsistent heading hierarchy
• Missing font fallbacks
• Layout shift from web font loading
• Underlined text that isn't a link

Quick Implementation

Minimal Professional Setup

:root {
  --font-sans: Inter, ui-sans-serif, system-ui, sans-serif;
  --font-mono: 'JetBrains Mono', ui-monospace, monospace;
}

body {
  font-family: var(--font-sans);
  font-size: clamp(1rem, 0.95rem + 0.25vw, 1.125rem);
  line-height: 1.6;
  font-feature-settings: "kern" 1, "liga" 1, "calt" 1;
}

h1, h2, h3 {
  line-height: 1.2;
  text-wrap: balance;
  letter-spacing: -0.02em;
}

p {
  text-wrap: pretty;
  max-width: 65ch;
}

code {
  font-family: var(--font-mono);
  font-variant-numeric: tabular-nums slashed-zero;
}

@media (prefers-color-scheme: dark) {
  body {
    -webkit-font-smoothing: antialiased;
    -moz-osx-font-smoothing: grayscale;
  }
}

Tailwind Quick Start

<article class="
  prose prose-gray lg:prose-lg
  prose-headings:text-balance
  prose-p:text-pretty
  dark:prose-invert
  max-w-prose mx-auto
">
  <!-- Content -->
</article>

See tailwind-integration.md for complete patterns.