define-typography

Define Typography Command

Design a comprehensive typography system with scales, styles, and responsive rules.

Usage

/cms:define-typography --scale modular --ratio 1.25
/cms:define-typography --scale musical --base-size 18
/cms:define-typography --scale custom

Scale Options

• modular: Mathematical scale with consistent ratio
• musical: Based on musical intervals (perfect fourth, major third)
• custom: User-defined sizes

Common Ratios

Name	Ratio	Use Case
Minor Second	1.067	Subtle, minimal
Major Second	1.125	Subtle hierarchy
Minor Third	1.200	Body-friendly
Major Third	1.250	Versatile (default)
Perfect Fourth	1.333	Strong hierarchy
Augmented Fourth	1.414	Bold, dramatic
Perfect Fifth	1.500	Very dramatic
Golden Ratio	1.618	Classic, elegant

Workflow

Step 1: Parse Arguments

Extract scale type, base size, and ratio from command.

Step 2: Gather Requirements

Use AskUserQuestion to understand:

• What is the primary reading context (blog, app, marketing)?
• What devices are being targeted?
• Are there existing brand fonts to incorporate?
• What is the desired visual personality?

Step 3: Invoke Skills

Invoke design-token-management skill for token generation.

Step 4: Generate Type Scale

Modular Scale (1.25 ratio, 16px base):

typography:
  base_size: 16
  ratio: 1.25
  unit: rem

  scale:
    # Calculated: base * ratio^n
    xs:     # 16 / 1.25^2 = 10.24 → 0.64rem
      size: 0.64rem
      line_height: 1.5

    sm:     # 16 / 1.25 = 12.8 → 0.8rem
      size: 0.8rem
      line_height: 1.5

    base:   # 16 = 1rem
      size: 1rem
      line_height: 1.5

    lg:     # 16 * 1.25 = 20 → 1.25rem
      size: 1.25rem
      line_height: 1.4

    xl:     # 16 * 1.25^2 = 25 → 1.563rem
      size: 1.563rem
      line_height: 1.3

    2xl:    # 16 * 1.25^3 = 31.25 → 1.953rem
      size: 1.953rem
      line_height: 1.3

    3xl:    # 16 * 1.25^4 = 39.06 → 2.441rem
      size: 2.441rem
      line_height: 1.2

    4xl:    # 16 * 1.25^5 = 48.83 → 3.052rem
      size: 3.052rem
      line_height: 1.1

    5xl:    # 16 * 1.25^6 = 61.04 → 3.815rem
      size: 3.815rem
      line_height: 1.1

Step 5: Define Text Styles

Semantic Text Styles:

text_styles:
  # Headings
  display:
    font_family: "{fonts.heading}"
    font_size: "{scale.5xl}"
    font_weight: 800
    line_height: 1.1
    letter_spacing: -0.02em
    text_transform: none
    responsive:
      mobile:
        font_size: "{scale.3xl}"

  h1:
    font_family: "{fonts.heading}"
    font_size: "{scale.4xl}"
    font_weight: 700
    line_height: 1.2
    letter_spacing: -0.02em
    margin_bottom: "{spacing.4}"
    responsive:
      mobile:
        font_size: "{scale.2xl}"

  h2:
    font_family: "{fonts.heading}"
    font_size: "{scale.3xl}"
    font_weight: 700
    line_height: 1.2
    letter_spacing: -0.01em
    margin_bottom: "{spacing.3}"
    responsive:
      mobile:
        font_size: "{scale.xl}"

  h3:
    font_family: "{fonts.heading}"
    font_size: "{scale.2xl}"
    font_weight: 600
    line_height: 1.3
    margin_bottom: "{spacing.2}"

  h4:
    font_family: "{fonts.heading}"
    font_size: "{scale.xl}"
    font_weight: 600
    line_height: 1.3
    margin_bottom: "{spacing.2}"

  h5:
    font_family: "{fonts.heading}"
    font_size: "{scale.lg}"
    font_weight: 600
    line_height: 1.4

  h6:
    font_family: "{fonts.heading}"
    font_size: "{scale.base}"
    font_weight: 600
    line_height: 1.4
    text_transform: uppercase
    letter_spacing: 0.05em

  # Body text
  body:
    font_family: "{fonts.body}"
    font_size: "{scale.base}"
    font_weight: 400
    line_height: 1.6
    color: "{colors.text.primary}"

  body_large:
    font_family: "{fonts.body}"
    font_size: "{scale.lg}"
    font_weight: 400
    line_height: 1.5
    color: "{colors.text.primary}"

  body_small:
    font_family: "{fonts.body}"
    font_size: "{scale.sm}"
    font_weight: 400
    line_height: 1.5
    color: "{colors.text.secondary}"

  # Special text
  lead:
    font_family: "{fonts.body}"
    font_size: "{scale.xl}"
    font_weight: 400
    line_height: 1.5
    color: "{colors.text.secondary}"

  caption:
    font_family: "{fonts.body}"
    font_size: "{scale.xs}"
    font_weight: 400
    line_height: 1.4
    color: "{colors.text.tertiary}"
    text_transform: uppercase
    letter_spacing: 0.05em

  label:
    font_family: "{fonts.body}"
    font_size: "{scale.sm}"
    font_weight: 500
    line_height: 1.4

  code:
    font_family: "{fonts.mono}"
    font_size: 0.875em
    font_weight: 400
    background: "{colors.bg.code}"
    padding: 0.125em 0.25em
    border_radius: "{radii.sm}"

  blockquote:
    font_family: "{fonts.body}"
    font_size: "{scale.lg}"
    font_style: italic
    line_height: 1.6
    border_left: 4px solid "{colors.brand.primary}"
    padding_left: "{spacing.4}"
    margin: "{spacing.6} 0"

Step 6: Generate CSS

CSS Output:

/* Typography Scale */
:root {
  --font-size-xs: 0.64rem;
  --font-size-sm: 0.8rem;
  --font-size-base: 1rem;
  --font-size-lg: 1.25rem;
  --font-size-xl: 1.563rem;
  --font-size-2xl: 1.953rem;
  --font-size-3xl: 2.441rem;
  --font-size-4xl: 3.052rem;
  --font-size-5xl: 3.815rem;

  --font-family-heading: 'Inter', system-ui, sans-serif;
  --font-family-body: 'Inter', system-ui, sans-serif;
  --font-family-mono: 'JetBrains Mono', monospace;
}

/* Text Style Classes */
.text-display {
  font-family: var(--font-family-heading);
  font-size: var(--font-size-5xl);
  font-weight: 800;
  line-height: 1.1;
  letter-spacing: -0.02em;
}

.text-h1 {
  font-family: var(--font-family-heading);
  font-size: var(--font-size-4xl);
  font-weight: 700;
  line-height: 1.2;
  letter-spacing: -0.02em;
  margin-bottom: 1rem;
}

.text-body {
  font-family: var(--font-family-body);
  font-size: var(--font-size-base);
  font-weight: 400;
  line-height: 1.6;
}

.text-lead {
  font-family: var(--font-family-body);
  font-size: var(--font-size-xl);
  font-weight: 400;
  line-height: 1.5;
  color: var(--color-text-secondary);
}

/* Responsive Typography */
@media (max-width: 768px) {
  .text-display {
    font-size: var(--font-size-3xl);
  }

  .text-h1 {
    font-size: var(--font-size-2xl);
  }
}

/* Prose (long-form content) */
.prose {
  font-family: var(--font-family-body);
  font-size: var(--font-size-lg);
  line-height: 1.7;
  max-width: 65ch;
}

.prose h1, .prose h2, .prose h3, .prose h4 {
  font-family: var(--font-family-heading);
  margin-top: 2em;
  margin-bottom: 0.5em;
}

.prose p {
  margin-bottom: 1.25em;
}

.prose code {
  font-family: var(--font-family-mono);
  font-size: 0.875em;
  background: var(--color-bg-code);
  padding: 0.125em 0.25em;
  border-radius: 0.25rem;
}

Step 7: Font Loading Strategy

Font Configuration:

fonts:
  strategy: swap  # font-display value

  families:
    - name: Inter
      source: google  # or self-hosted, adobe
      weights: [400, 500, 600, 700, 800]
      styles: [normal, italic]
      subsets: [latin, latin-ext]
      preload: true
      variable: true

    - name: JetBrains Mono
      source: google
      weights: [400, 700]
      styles: [normal]
      subsets: [latin]
      preload: false

  loading:
    preload_critical: true
    preconnect: true
    subset_critical: "ABCDEFGHIJKLMNOPQRSTUVWXYZabcdefghijklmnopqrstuvwxyz0123456789"

  fallbacks:
    sans: "system-ui, -apple-system, sans-serif"
    serif: "Georgia, Times New Roman, serif"
    mono: "Menlo, Monaco, Consolas, monospace"

HTML Head:

<!-- Preconnect to font sources -->
<link rel="preconnect" href="https://fonts.googleapis.com">
<link rel="preconnect" href="https://fonts.gstatic.com" crossorigin>

<!-- Preload critical fonts -->
<link rel="preload" href="/fonts/inter-var.woff2" as="font" type="font/woff2" crossorigin>

<!-- Load fonts with display swap -->
<link href="https://fonts.googleapis.com/css2?family=Inter:wght@400;500;600;700;800&display=swap" rel="stylesheet">

Accessibility

Typography must meet WCAG requirements:

Requirement	Guideline
Minimum body size	16px (1rem)
Line height	1.5 minimum for body text
Line length	45-75 characters optimal
Contrast ratio	4.5:1 for normal text, 3:1 for large
Resize support	Text must scale up to 200%

Related Skills

• design-token-management - Token architecture
• multi-site-theming - Theme integration