typographic-hierarchy

name: typographic-hierarchy description: Adjusts font sizes, weights, line-heights, spacing, and color contrast to create distinct, intentional visual hierarchy in any UI or document. Use this skill whenever the user mentions typography, font sizing, heading contrast, text hierarchy, readability, type scale, or visual weight — even if they don't use the word "hierarchy" explicitly. Trigger when the user says things like "make the headings stand out more", "improve readability", "the text feels flat", "adjust font sizes", "text doesn't look structured", "tune the type", or "create a clear visual flow through the text". Also use when reviewing or generating any design artifact where text structure matters: landing pages, dashboards, editorial layouts, design systems, README files, or component libraries. category: "Design"

This skill establishes clear, intentional typographic hierarchy — using scale, weight, spacing, color contrast, and rhythm to guide the reader's eye and communicate structure at a glance.

Typographic hierarchy works across six levers. You rarely need all six — pick the fewest levers that achieve the contrast needed:

| Lever | Effect | |---|---| | Size | The primary signal. Double the size = double the dominance. | | Weight | Bold reads first. 700+ for dominant labels, 300–400 for supporting copy. | | Color / Opacity | Muted gray for secondary text. High-contrast black/white for focal points. | | Letter-spacing | Tight for large display text. Wide (0.05–0.2em) for ALL-CAPS labels. | | Line-height | Looser (1.6–1.8) for body. Tighter (1.0–1.2) for large headings. | | Space (margin/padding) | Space above a heading = visual importance. Use generously. |

Rule of thumb: Each level of the hierarchy should be unmistakably different from the next. If you squint and two levels look similar, increase the contrast.

Pick a ratio and a base size, then multiply up and divide down.

Common ratios:

• 1.25 — Major Third (subtle, compact)
• 1.333 — Perfect Fourth (balanced, versatile)
• 1.414 — Augmented Fourth (editorial, dramatic)
• 1.5 — Perfect Fifth (loud, impactful)
• 1.618 — Golden Ratio (classic, organic feel)

xs:   10px  (0.625rem)   — captions, meta
sm:   12px  (0.75rem)    — labels, tags
base: 16px  (1rem)       — body
md:   21px  (1.333rem)   — subheadings
lg:   28px  (1.777rem)   — section headings
xl:   37px  (2.369rem)   — page headings
2xl:  50px  (3.157rem)   — hero / display

--text-xs:   0.75rem;   /* 12px */
--text-sm:   0.875rem;  /* 14px */
--text-base: 1rem;      /* 16px */
--text-lg:   1.25rem;   /* 20px */
--text-xl:   1.5rem;    /* 24px */
--text-2xl:  2rem;      /* 32px */
--text-3xl:  2.5rem;    /* 40px */
--text-4xl:  3.5rem;    /* 56px */

| Role | Weight | Notes | |---|---|---| | Display / Hero | 800–900 | Black or ExtraBold — for maximum punch | | H1 / Page title | 700 | Bold | | H2 / Section heading | 600–700 | SemiBold–Bold | | H3 / Subheading | 500–600 | Medium–SemiBold | | Body | 400 | Regular | | Caption / Meta | 300–400 | Light or Regular; often muted color | | Labels / Tags | 500–600 + uppercase | Uppercase + tracking lifts small text |

Anti-pattern: Never use the same weight for two adjacent levels of hierarchy. Even one step (e.g., 400→500) matters when combined with size contrast.

Use opacity or gray tones to create a foreground/midground/background for text:

/* Dark theme example */
--text-primary:   rgba(255, 255, 255, 1.00);   /* headings, key labels */
--text-secondary: rgba(255, 255, 255, 0.70);   /* body, descriptions */
--text-tertiary:  rgba(255, 255, 255, 0.45);   /* captions, timestamps */
--text-disabled:  rgba(255, 255, 255, 0.25);   /* placeholders */

/* Light theme example */
--text-primary:   rgba(0, 0, 0, 0.92);
--text-secondary: rgba(0, 0, 0, 0.60);
--text-tertiary:  rgba(0, 0, 0, 0.38);
--text-disabled:  rgba(0, 0, 0, 0.20);

Accent color for hierarchy: Use a brand or accent color sparingly — only for one level (usually links, CTAs, or key labels). Overusing accent color flattens hierarchy.

Vertical rhythm is as important as size. Space above a heading signals a new section; space below links it to what follows.

/* Heading spacing pattern */
h1 { margin-top: 0;      margin-bottom: 0.5em; }
h2 { margin-top: 2.5em;  margin-bottom: 0.4em; }
h3 { margin-top: 2em;    margin-bottom: 0.3em; }
p  { margin-top: 0;      margin-bottom: 1em;   }

Tight-to-loose rhythm: Large display text → tight line-height (1.0–1.2). Body copy → comfortable (1.5–1.7). Long-form prose → generous (1.7–1.9).

:root {
  /* Scale */
  --type-display: clamp(2.5rem, 6vw, 5rem);
  --type-h1:      clamp(1.75rem, 4vw, 3rem);
  --type-h2:      clamp(1.25rem, 2.5vw, 2rem);
  --type-h3:      1.125rem;
  --type-body:    1rem;
  --type-small:   0.875rem;
  --type-caption: 0.75rem;

  /* Weights */
  --weight-display: 800;
  --weight-heading: 700;
  --weight-subhead: 600;
  --weight-body:    400;
  --weight-caption: 400;

  /* Leading */
  --leading-tight:  1.1;
  --leading-snug:   1.35;
  --leading-normal: 1.6;
  --leading-loose:  1.8;

  /* Tracking */
  --tracking-tight:  -0.03em;
  --tracking-normal:  0em;
  --tracking-wide:    0.06em;
  --tracking-wider:   0.12em;
}

Display:    text-5xl md:text-7xl font-black tracking-tight leading-none
H1:         text-3xl md:text-5xl font-bold tracking-tight leading-tight
H2:         text-2xl md:text-3xl font-semibold leading-snug
H3:         text-xl font-semibold leading-snug
Body:       text-base font-normal leading-relaxed text-gray-700
Caption:    text-sm font-normal text-gray-400 leading-normal
Label/tag:  text-xs font-semibold uppercase tracking-widest text-gray-500

const typeStyles = {
  display: 'text-6xl font-black tracking-tight leading-none',
  h1:      'text-4xl font-bold tracking-tight leading-tight',
  h2:      'text-2xl font-semibold leading-snug',
  h3:      'text-xl font-semibold leading-snug',
  body:    'text-base leading-relaxed',
  small:   'text-sm leading-normal',
  caption: 'text-xs text-gray-400',
  label:   'text-xs font-semibold uppercase tracking-widest',
};

const Text = ({ as: Tag = 'p', variant = 'body', className = '', ...props }) => (
  <Tag className={`${typeStyles[variant]} ${className}`} {...props} />
);

When asked to review or fix existing type hierarchy, check these in order:

1. Squint test — Blur your eyes. Can you read the structure? If not, contrast is insufficient.
2. Size gap — Is there at least a 1.25× difference between adjacent levels? If heading and body look close in size, bump the heading.
3. Weight flattening — Are multiple levels using font-weight: 400? Add weight variation.
4. Color sameness — Is all text the same darkness? Introduce secondary/tertiary tones.
5. Spacing starvation — Do headings have enough breathing room above them? Tighten the bond between heading and its following content; open space above.
6. Responsive collapse — Does hierarchy survive on mobile? Use clamp() or responsive variants to preserve ratios at small sizes.

| Mistake | Fix | |---|---| | H1 and H2 look almost identical | Increase H1 size by at least 1.5× H2; add extra weight or tighter tracking | | Body text too light/thin | Set body to 400 weight; avoid 300 for long-form copy | | Uppercase headings feel heavy | Reduce weight to 600; increase letter-spacing to 0.08–0.12em | | Display text looks cramped | Set line-height: 0.95–1.1 and letter-spacing: -0.03em | | All text is same color | Apply 3-tier opacity system (100%, 65%, 40%) | | Mobile hierarchy collapses | Use clamp() for fluid scaling; test at 375px width | | Too many font sizes | Collapse to 4–5 levels max; enforce the scale |

When font selection is in scope:

• Display + Body: Pair a high-contrast serif (for display) with a clean sans (for body). E.g., Playfair Display + Source Sans, Fraunces + Inter.
• Weight contrast within one family: Use a variable font (e.g., Satoshi, Cabinet Grotesk, Geist) and span weights 300–900.
• Monospace accent: Use a mono font for labels/code/metadata — creates instant visual separation from prose.

See references/font-pairs.md for curated pairings with Google Fonts import snippets.

• Minimum body text: 16px (never go below 14px for readable content)
• WCAG AA contrast: 4.5:1 for body text, 3:1 for large text (18px+ or 14px bold)
• Never rely on color alone to establish hierarchy — always pair with size or weight
• Use semantic HTML (h1–h6, p, small) even when visual styles differ

• [ ] Each heading level is unmistakably different from the next (size + weight)
• [ ] Body text is 400 weight, 15–17px, line-height 1.5–1.7
• [ ] Secondary/caption text is visually subordinate (lighter color or smaller)
• [ ] Headings have appropriate space above them
• [ ] Hierarchy survives on mobile (375px viewport)
• [ ] Contrast ratios pass WCAG AA
• [ ] No more than 5 distinct type sizes in use