design-typography

Design and implement typography systems for web and brand projects. Covers font pairing, type scales, variable fonts, web font loading strategies (font-display, subsetting), CSS typography best practi

SKILL.md

GitHub

Typography Systems

Use this skill when designing or implementing typography for brands, websites, or design projects.

Note: Typography is primarily a design-theory and CSS-implementation skill. MCP tools support the visual side — use the Gemini image tool in your tool list (agent-prefixed or bare) to create typographic posters and mood boards, and analyze_image to identify fonts from screenshots. For cross-site font management, use remote_wp_connection to push typography settings from Hub to spoke sites.

WP-CLI Commands

Key mcp-ai WP-CLI commands for design workflows. Run via terminal:

Command Use for
wp mcp-ai health Verify tool and provider availability
wp mcp-ai provider Check configured AI providers

When to use this skill

Trigger when ANY of the following is true:

  • Selecting or pairing fonts for a brand or website.
  • Implementing a type scale in CSS.
  • Loading web fonts with optimal performance.
  • Working with variable fonts.
  • The task mentions "font", "typography", "type scale", "heading styles", or "font pairing".
  • Configuring WordPress theme typography (theme.json or customizer).

Font pairing principles

Contrast with harmony

Pair fonts that differ in ONE key dimension while sharing others:

Display (headlines)  +  Body (paragraphs)
─────────────────────────────────────────
Serif                +  Sans-serif          ← Classic pairing
Sans-serif           +  Serif               ← Modern, clean
Geometric sans       +  Grotesk sans        ← Subtle contrast
Script/display       +  Simple sans         ← Statement + readability
Monospace            +  Proportional         ← Code/tech aesthetic

Proven pairings

Headings Body Vibe
Playfair Display Source Sans 3 Editorial, elegant
DM Serif Display DM Sans Modern luxury
Bebas Neue Roboto Bold, urban
Cormorant Garamond Proza Libre Literary, classic
Inter Inter (single family) Clean, tech
Space Grotesk Space Grotesk Contemporary
Fraunces Commissioner Creative, warm
Cabinet Grotesk Satoshi Modern brand

Type scales

Major Third (1.250) — most common

:root {
  --text-xs:     0.75rem;   /* 12px */
  --text-sm:     0.875rem;  /* 14px */
  --text-base:   1rem;      /* 16px */
  --text-lg:     1.125rem;  /* 18px */
  --text-xl:     1.25rem;   /* 20px */
  --text-2xl:    1.5rem;    /* 24px */
  --text-3xl:    1.875rem;  /* 30px */
  --text-4xl:    2.25rem;   /* 36px */
  --text-5xl:    3rem;      /* 48px */
  --text-6xl:    3.75rem;   /* 60px */
}

Perfect Fourth (1.333) — dramatic, editorial

:root {
  --text-base:   1rem;      /* 16px */
  --text-lg:     1.333rem;  /* 21px */
  --text-xl:     1.777rem;  /* 28px */
  --text-2xl:    2.369rem;  /* 38px */
  --text-3xl:    3.157rem;  /* 51px */
  --text-4xl:    4.209rem;  /* 67px */
}

Fluid type (clamp)

/* Scales smoothly between mobile and desktop without breakpoints */
h1 {
  font-size: clamp(2rem, 1rem + 5vw, 4rem);
}

h2 {
  font-size: clamp(1.5rem, 0.8rem + 3vw, 2.5rem);
}

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

Web font loading

Font face declaration

@font-face {
  font-family: 'Inter';
  src: url('/fonts/Inter-Variable.woff2') format('woff2-variations');
  font-weight: 100 900;
  font-style: normal;
  font-display: swap;         /* Critical for performance */
  unicode-range: U+0000-00FF; /* Subset to Latin if applicable */
}

font-display strategies

Value Behavior Best For
swap Show fallback immediately, swap when loaded Body text, UI (no FOIT)
block Invisible for 3s, then fallback Minimal — avoid
fallback Invisible for 100ms, then fallback Headings (brief FOIT ok)
optional Use fallback if font isn't cached Non-critical text, perf-first

Golden rule: font-display: swap for body text. Only use optional for truly non-essential decorative fonts.

Performance checklist

✅ Use WOFF2 format (30% smaller than WOFF)
✅ Subset to needed characters (Latin, no Cyrillic if not needed)
✅ Preload critical fonts: <link rel="preload" as="font" crossorigin />
✅ Self-host fonts (no Google Fonts CDN for privacy + performance)
✅ Use variable fonts (one file instead of 4–6 weights)
✅ Cache fonts with long max-age (1 year)

Variable fonts

@font-face {
  font-family: 'InterVariable';
  src: url('/fonts/Inter-Variable.woff2') format('woff2-variations');
  font-weight: 100 900;
  font-stretch: 75% 125%;
  font-style: oblique 0deg 12deg;
}

h1 {
  font-family: 'InterVariable', sans-serif;
  font-weight: 800;
  font-variation-settings: 'opsz' 32; /* Optical size for large text */
}

.caption {
  font-family: 'InterVariable', sans-serif;
  font-weight: 400;
  font-variation-settings: 'opsz' 12; /* Optical size for small text */
}

Popular variable fonts (all on Google Fonts)

Inter            → UI, body, general purpose
Fraunces         → Editorial, brand, display
Recursive        → Mono to sans axis, playful
Newsreader       → Long-form reading, news
Roboto Flex      → Full axis range, highly customizable
Source Serif 4   → Body copy, reading comfort

WordPress typography (theme.json)

{
  "settings": {
    "typography": {
      "fontFamilies": [
        {
          "fontFamily": "'InterVariable', sans-serif",
          "name": "Inter",
          "slug": "inter"
        },
        {
          "fontFamily": "'FrauncesVariable', serif",
          "name": "Fraunces",
          "slug": "fraunces"
        }
      ],
      "fontSizes": [
        { "name": "Small", "slug": "small", "size": "0.875rem" },
        { "name": "Base", "slug": "base", "size": "1rem" },
        { "name": "Large", "slug": "large", "size": "1.25rem" },
        { "name": "XL", "slug": "xl", "size": "1.5rem" },
        { "name": "2XL", "slug": "2-xl", "size": "2rem" },
        { "name": "3XL", "slug": "3-xl", "size": "3rem" }
      ]
    }
  }
}

Typography visualization with AI (MCP)

While typography implementation is CSS-driven, MCP tools can help visualize type choices:

  • Generate type specimen posters: Use the Gemini image tool in your tool list to create posters showing font pairings in context.
  • Analyze font usage: Use analyze_image to identify fonts in screenshots or reference images.
  • Create mood boards: Use the Gemini image tool in your tool list to generate typographic mood boards showing text hierarchy examples.
# Generate a type specimen for a font pairing
prompt: "Typography specimen poster showing 'Playfair Display' for headings
and 'Source Sans 3' for body text. Include sample headings, paragraph text,
and pull quotes. Elegant editorial layout, black text on cream background."

What This Skill Does NOT Cover

  • Color system design and palette generation → design-color-systems
  • Full brand identity definition (logos, imagery, voice) → design-brand-kit
  • Logo design, mark creation, or iconography
  • Layout and grid system design (CSS Grid, Flexbox patterns)
  • Icon font selection and icon-set curation
  • Print typography specifications (ink traps, paper stock, imposition)
  • Font licensing and commercial usage rights

Critical rules

  • Maximum 2 font families — one for headings, one for body. Three is pushing it; more is a mess.
  • Line-height: 1.5–1.75 for body — tighter for headings (1.1–1.3), looser for long-form reading.
  • Max line length: 60–75 characters — use max-width: 65ch on text containers.
  • Use relative units — rem for font-size, em for spacing within components, avoid px.
  • Optical sizing matters — variable fonts with opsz axis improve readability at small sizes and elegance at large sizes.

Common mistakes

/* WRONG — px-based, no fallback, multiple families */
body { font-size: 16px; font-family: 'Playfair Display', 'Lato', 'Open Sans', serif; }

/* RIGHT — rem-based, 2-family max, system fallback */
body { font-size: 1rem; font-family: 'InterVariable', -apple-system, BlinkMacSystemFont, sans-serif; }
h1, h2, h3 { font-family: 'FrauncesVariable', Georgia, serif; }

/* WRONG — no fluid scaling */
h1 { font-size: 48px; } /* giant on mobile */

/* RIGHT — fluid clamp */
h1 { font-size: clamp(2rem, 1rem + 5vw, 3.75rem); }

Cross-references

  • Run design-color-systems to pair colors with typography choices.
  • Run design-brand-kit to define the full brand identity.
  • Run wp-plugin-assets-loading to properly enqueue web fonts in WordPress.
  • Run design-image-generation to create typographic visuals — check your tool list for the Gemini image tool.
  • Run mcp-ai-wpoos-plugin for remote_wp_connection — push typography config from Hub to spoke sites.

References