Home

Headings

Usage

Start with these tokens when customizing headings:

  • --heading-font-family and --heading-color for global type tone

  • --heading-font-size and --heading-font-size-ratio for hierarchy scale

  • --heading-font-weight and --heading-font-weight-decrement for weight progression

  • --heading-spacing-top, --heading-spacing-bottom, and --heading-spacing-ratio for rhythm

  • --heading-numbering when you need numbered headings

The heading scale is driven by --heading-font-size with --heading-font-size-ratio, and weights are driven by --heading-font-weight with --heading-font-weight-decrement. Spacing uses --heading-spacing-* and scales with --content-spacing.

Use zone helpers (--heading-upper-*, --heading-lower-*) for quick adjustments, or per-level overrides like --heading-h1-* and --heading-h2-* when you need finer control. Decorative styling is handled by --heading-border-*, --heading-background-*, and --heading-padding.

Tokens

Design tokens for headings use a modular scale system with base values and ratios to automatically calculate font sizes, weights, and spacing across all heading levels.

TokenDescriptionDefault Value
--heading-font-familyFont family for all heading levelsvar(--font-family-serif)
--heading-font-sizeFont size for <h1> (largest heading)calc(var(--text-font-size) * 2.0)
--heading-font-size-printFont size for <h1> in printcalc(var(--text-font-size-print) * 1.75)
--heading-font-size-ratioMultiplier for scaling font sizes between levels0.85
--heading-font-weightFont weight for <h1>var(--font-weight-bold)
--heading-font-weight-decrementAmount to reduce font weight per level50
--heading-line-heightLine height for all headingsvar(--line-height-tight)
--heading-letter-spacingBase letter spacing (can be overridden per level)-0.025em
--heading-spacing-topTop spacing for <h1> - scales with content rhythmcalc(var(--content-spacing) * 1.5)
--heading-spacing-bottomBottom spacing for <h1> - scales with content rhythmcalc(var(--content-spacing) * 0.5)
--heading-spacing-ratioRatio for scaling spacing between levels0.8
--heading-spacing-adjacent-ratioRatio for spacing between adjacent headings0.5
--heading-colorText color for all headingsvar(--text-color-primary)
--heading-color-darkText color for headings in dark modevar(--text-color-primary)
--heading-color-opacity-decrementAmount to reduce opacity per level (0 = no change)0
--heading-upper-colorColor helper for h1-h3var(--heading-color)
--heading-lower-colorColor helper for h4-h6var(--heading-color)
--heading-h1-colorColor override for h1var(--heading-upper-color)
--heading-h2-colorColor override for h2var(--heading-upper-color)
--heading-h3-colorColor override for h3var(--heading-upper-color)
--heading-h4-colorColor override for h4var(--heading-lower-color)
--heading-h5-colorColor override for h5var(--heading-lower-color)
--heading-h6-colorColor override for h6var(--heading-lower-color)
--heading-numberingHeading numbering mode (none, decimal)none
--heading-upper-font-styleFont style for h1-h3 (zone-based helper)normal
--heading-lower-font-styleFont style for h4-h6 (zone-based helper)normal
--heading-h1-font-styleFont style override for h1var(--heading-upper-font-style)
--heading-h2-font-styleFont style override for h2var(--heading-upper-font-style)
--heading-h3-font-styleFont style override for h3var(--heading-upper-font-style)
--heading-h4-font-styleFont style override for h4var(--heading-lower-font-style)
--heading-h5-font-styleFont style override for h5var(--heading-lower-font-style)
--heading-h6-font-styleFont style override for h6var(--heading-lower-font-style)
--heading-h1-font-variantFont variant for h1 (normal, small-caps, etc.)normal
--heading-h2-font-variantFont variant for h2 (normal, small-caps, etc.)normal
--heading-h3-font-variantFont variant for h3 (normal, small-caps, etc.)normal
--heading-h4-font-variantFont variant for h4 (normal, small-caps, etc.)normal
--heading-h5-font-variantFont variant for h5 (normal, small-caps, etc.)normal
--heading-h6-font-variantFont variant for h6 (normal, small-caps, etc.)normal
--heading-h1-letter-spacingLetter spacing override for h1var(--heading-letter-spacing)
--heading-h2-letter-spacingLetter spacing override for h2var(--heading-letter-spacing)
--heading-h3-letter-spacingLetter spacing override for h3var(--heading-letter-spacing)
--heading-h4-letter-spacingLetter spacing override for h4var(--heading-letter-spacing)
--heading-h5-letter-spacingLetter spacing override for h5var(--heading-letter-spacing)
--heading-h6-letter-spacingLetter spacing override for h6var(--heading-letter-spacing)
--heading-h1-font-weightFont weight override for h1var(--heading-font-weight)
--heading-h2-font-weightFont weight override for h2Calculated from decrement
--heading-h3-font-weightFont weight override for h3Calculated from decrement
--heading-h4-font-weightFont weight override for h4Calculated from decrement
--heading-h5-font-weightFont weight override for h5Calculated from decrement
--heading-h6-font-weightFont weight override for h6Calculated from decrement
--heading-border-widthBorder width for all headings (default: bottom border)0
--heading-border-styleBorder style for all headingssolid
--heading-border-colorBorder color for all headingsvar(--color-gray-300)
--heading-border-color-darkBorder color for headings in dark modevar(--color-gray-700)
--heading-upper-border-widthBorder width for h1-h3 (zone-based helper)var(--heading-border-width)
--heading-upper-border-styleBorder style for h1-h3 (zone-based helper)var(--heading-border-style)
--heading-upper-border-colorBorder color for h1-h3 (zone-based helper)var(--heading-border-color)
--heading-lower-border-widthBorder width for h4-h6 (zone-based helper)var(--heading-border-width)
--heading-lower-border-styleBorder style for h4-h6 (zone-based helper)var(--heading-border-style)
--heading-lower-border-colorBorder color for h4-h6 (zone-based helper)var(--heading-border-color)
--heading-h1-border-widthBorder width override for h1var(--heading-upper-border-width)
--heading-h1-border-styleBorder style override for h1var(--heading-upper-border-style)
--heading-h1-border-colorBorder color override for h1var(--heading-upper-border-color)
--heading-h2-border-widthBorder width override for h2var(--heading-upper-border-width)
--heading-h2-border-styleBorder style override for h2var(--heading-upper-border-style)
--heading-h2-border-colorBorder color override for h2var(--heading-upper-border-color)
--heading-h3-border-widthBorder width override for h3var(--heading-upper-border-width)
--heading-h3-border-styleBorder style override for h3var(--heading-upper-border-style)
--heading-h3-border-colorBorder color override for h3var(--heading-upper-border-color)
--heading-h4-border-widthBorder width override for h4var(--heading-lower-border-width)
--heading-h4-border-styleBorder style override for h4var(--heading-lower-border-style)
--heading-h4-border-colorBorder color override for h4var(--heading-lower-border-color)
--heading-h5-border-widthBorder width override for h5var(--heading-lower-border-width)
--heading-h5-border-styleBorder style override for h5var(--heading-lower-border-style)
--heading-h5-border-colorBorder color override for h5var(--heading-lower-border-color)
--heading-h6-border-widthBorder width override for h6var(--heading-lower-border-width)
--heading-h6-border-styleBorder style override for h6var(--heading-lower-border-style)
--heading-h6-border-colorBorder color override for h6var(--heading-lower-border-color)
--heading-background-colorBackground color for all headingstransparent
--heading-background-color-darkBackground color for headings in dark modetransparent
--heading-upper-background-colorBackground color for h1-h3 (zone-based helper)var(--heading-background-color)
--heading-lower-background-colorBackground color for h4-h6 (zone-based helper)var(--heading-background-color)
--heading-h1-background-colorBackground color override for h1var(--heading-upper-background-color)
--heading-h2-background-colorBackground color override for h2var(--heading-upper-background-color)
--heading-h3-background-colorBackground color override for h3var(--heading-upper-background-color)
--heading-h4-background-colorBackground color override for h4var(--heading-lower-background-color)
--heading-h5-background-colorBackground color override for h5var(--heading-lower-background-color)
--heading-h6-background-colorBackground color override for h6var(--heading-lower-background-color)
--heading-paddingPadding for all headings0
--heading-upper-paddingPadding for h1-h3 (zone-based helper)var(--heading-padding)
--heading-lower-paddingPadding for h4-h6 (zone-based helper)var(--heading-padding)
--heading-h1-paddingPadding override for h1var(--heading-upper-padding)
--heading-h2-paddingPadding override for h2var(--heading-upper-padding)
--heading-h3-paddingPadding override for h3var(--heading-upper-padding)
--heading-h4-paddingPadding override for h4var(--heading-lower-padding)
--heading-h5-paddingPadding override for h5var(--heading-lower-padding)

Examples

Default Headings

Standard heading hierarchy with automatic scaling and responsive spacing:

:root {
  /* No design token overrides */
}

Heading One

Heading Two

Heading Three

Heading Four

Heading Five
Heading Six

Compact Headings

Ideal for documentation, technical content, or high-density information:

:root {
  --heading-font-size: 1.875rem;
  --heading-font-size-ratio: 0.833; /* Minor Third inverted - subtle differences */
  --heading-spacing-top: calc(var(--content-spacing) * 0.75);
  --heading-spacing-bottom: calc(var(--content-spacing) * 0.25);
  --heading-font-weight: 600;
  --heading-color: var(--color-blue-900);
}

Heading One

Heading Two

Heading Three

Heading Four

Heading Five
Heading Six

Spacious Headings

Better for presentations, marketing content, and editorial layouts:

:root {
  --heading-font-size: 3rem;
  --heading-font-size-ratio: 0.75; /* Perfect Fourth inverted - noticeable hierarchy */
  --heading-spacing-top: calc(var(--content-spacing) * 2);
  --heading-spacing-bottom: calc(var(--content-spacing) * 0.75);
  --heading-letter-spacing: -0.03em;
  --heading-color: var(--color-green-800);
}

Heading One

Heading Two

Heading Three

Heading Four

Heading Five
Heading Six

Editorial Headings

Classic typography for articles, blogs, and long-form content:

:root {
  --heading-font-family: Georgia, serif;
  --heading-font-size: 2.25rem;
  --heading-font-size-ratio: 0.8; /* Major Third inverted - traditional harmony */
  --heading-font-weight: 400;
  --heading-font-weight-decrement: 0;
  --heading-line-height: 1.3;
  --heading-color: var(--color-amber-800);
}

Heading One

Heading Two

Heading Three

Heading Four

Heading Five
Heading Six

Minimal Headings

Clean, modern styling with subtle hierarchy:

:root {
  --heading-font-size: 2rem;
  --heading-font-size-ratio: 0.87; /* Subtle scale */
  --heading-font-weight: 500;
  --heading-font-weight-decrement: 100;
  --heading-color-opacity-decrement: 0.08; /* Subtle opacity reduction */
  --heading-letter-spacing: 0;
  --heading-color: var(--color-gray-700);
  --heading-color-dark: var(--color-gray-100); /* Lighter for dark mode */
}

Heading One

Heading Two

Heading Three

Heading Four

Heading Five
Heading Six

Opacity Hierarchy

Create visual hierarchy through opacity changes while maintaining consistent color:

:root {
  --heading-font-size: 2.5rem;
  --heading-font-size-ratio: 0.85;
  --heading-font-weight: 600;
  --heading-font-weight-decrement: 0; /* Keep same weight */
  --heading-color-opacity-decrement: 0.12; /* Progressive opacity reduction */
  --heading-color: var(--color-indigo-800);
}

Heading One

Heading Two

Heading Three

Heading Four

Heading Five
Heading Six

Dramatic Headings

High contrast for landing pages and marketing materials:

:root {
  --heading-font-size: 4rem;
  --heading-font-size-ratio: 0.618; /* Golden Ratio for maximum contrast */
  --heading-font-weight: 800;
  --heading-letter-spacing: -0.04em;
  --heading-spacing-ratio: 0.6;
  --heading-color: var(--color-red-900);
}

Heading One

Heading Two

Heading Three

Heading Four

Heading Five
Heading Six

Classical Book Typography

Traditional book design with italic lower-level headings and small-caps:

:root {
  /* h1-h2: Bold roman */
  --heading-h1-font-style: normal;
  --heading-h2-font-style: normal;
  --heading-h2-font-variant: small-caps;
  --heading-h2-letter-spacing: 0.05em; /* Small-caps need extra tracking */

  /* h3: Bold roman */
  --heading-h3-font-style: normal;

  /* h4-h6: Italic with normal weight */
  --heading-lower-font-style: italic;
  --heading-h4-font-weight: 400;
  --heading-h5-font-weight: 400;
  --heading-h6-font-weight: 400;

  /* Typography settings */
  --heading-font-family: 'Crimson Pro', Georgia, serif;
  --heading-font-size: 2rem;
  --heading-font-size-ratio: 0.85;
  --heading-color: var(--color-gray-900);
}

Heading One

Heading Two

Heading Three

Heading Four

Heading Five
Heading Six

Bottom Border Headings

Documentation-style with subtle bottom borders on upper-level headings:

:root {
  /* Borders on h1 and h2 only */
  --heading-h1-border-width: 2px;
  --heading-h1-border-color: var(--color-blue-500);
  --heading-h2-border-width: 1px;
  --heading-h2-border-color: var(--color-gray-300);

  /* Add padding-bottom for spacing between text and border */
  --heading-h1-padding: 0 0 0.5rem 0;
  --heading-h2-padding: 0 0 0.375rem 0;

  /* Typography */
  --heading-font-size: 2rem;
  --heading-font-weight: 600;
  --heading-color: var(--color-gray-900);
}

Heading One

Heading Two

Heading Three

Heading Four

Heading Five
Heading Six

Callout-Style Headings

Headings with background colors and padding for visual emphasis:

:root {
  /* Background colors for upper headings */
  --heading-h1-background-color: var(--color-purple-100);
  --heading-h2-background-color: var(--color-purple-50);

  /* Padding to create space around text */
  --heading-h1-padding: 0.75rem 1rem;
  --heading-h2-padding: 0.5rem 0.875rem;

  /* Optional: add subtle borders */
  --heading-h1-border-width: 0 0 0 4px;
  --heading-h1-border-color: var(--color-purple-600);

  /* Typography */
  --heading-font-size: 2rem;
  --heading-font-weight: 600;
  --heading-color: var(--color-gray-900);
}

Heading One

Heading Two

Heading Three

Heading Four

Heading Five
Heading Six

Mixed Border Styles

Combining different border approaches for unique designs:

:root {
  /* h1: Thick bottom border with color */
  --heading-h1-border-width: 3px;
  --heading-h1-border-color: var(--color-teal-500);
  --heading-h1-padding: 0 0 0.5rem 0;

  /* h2: Subtle gray background with no border */
  --heading-h2-background-color: var(--color-gray-50);
  --heading-h2-padding: 0.375rem 0.75rem;
  --heading-h2-border-width: 0;

  /* h3: Thin bottom border */
  --heading-h3-border-width: 1px;
  --heading-h3-border-color: var(--color-gray-200);

  /* Typography */
  --heading-font-size: 2.25rem;
  --heading-font-size-ratio: 0.85;
  --heading-color: var(--color-gray-900);
}

Heading One

Heading Two

Heading Three

Heading Four

Heading Five
Heading Six

Tips

Scale control: Use --heading-font-size with --heading-font-size-ratio to set the hierarchy in one place.

Weight progression: Use --heading-font-weight and --heading-font-weight-decrement to tune level-to-level contrast.

Zone vs level: Use --heading-upper-*/--heading-lower-* for grouped styling, and override with --heading-h1-*…--heading-h6-* only when needed.

Decorative treatments: Use --heading-border-*, --heading-background-*, and --heading-padding for callout-style headings without custom CSS.

Opacity hierarchy: Use --heading-color-opacity-decrement to soften lower levels without changing the base color.
Edit on GitHub
© 2026 Stencila