Heading

Heading Variants

Semantic Levels

Visual Size Variants (Decoupled from Semantic Level)

Generate precise clamp() values with the Clamp Calculator. The formula clamp(min, preferred, max) ensures headings scale smoothly from mobile (320px) to desktop (1440px) without media query breakpoints.

Weight Variants

Additional Variants

• With Overline: Small uppercase label above the heading ("CHAPTER 3" → "The Journey Begins")
• With Underline/Accent: Decorative bottom border or brand-colored accent line
• Gradient: CSS gradient text (background-clip: text) for marketing/hero contexts
• Truncated: Single-line truncation with text-overflow: ellipsis for constrained layouts

Heading Properties

The level vs size distinction is the key design decision. Setting level={3} renders an <h3> element; setting size="h1" makes it look like an h1. This decoupling is essential when a component (e.g., a Card title) always uses <h3> semantically but may appear in different visual contexts.

Design Token Mappings

Choose your heading typeface with the Font Explorer. For fluid sizes, generate clamp() values with the Clamp Calculator. A common pattern: use a display/serif font for h1 and a sans-serif for h2–h6, or maintain a single family and rely on size/weight for hierarchy.

Heading States

Headings are primarily static content elements, so their "states" are contextual rather than interactive:

Scroll-Margin for Fixed Headers

When using anchor links with fixed/sticky navigation bars, headings need scroll-margin-top to prevent them from hiding behind the fixed element:

[id] {
  scroll-margin-top: calc(var(--navbar-height, 64px) + 1rem);
}

This ensures that clicking a table-of-contents link scrolls the heading into view below the fixed nav, not behind it.

Accessibility

Headings are the primary mechanism screen-reader users rely on for page navigation. A well-structured heading hierarchy is arguably the single highest-impact accessibility improvement you can make.

Semantic Hierarchy (WCAG 1.3.1 Info and Relationships):

• Every page must have exactly one <h1>, representing the page's primary topic.
• Headings must follow a logical descending order: <h1> → <h2> → <h3>. Never skip levels (e.g., <h2> → <h4>).
• The heading hierarchy creates an implicit document outline. Screen-reader users navigate this outline directly — JAWS, NVDA, and VoiceOver all support "next heading" (H key) and "heading level N" (1–6 keys) shortcuts.
• When visual design requires a heading to look different from its semantic level, use the size prop to decouple appearance from semantics. A <Heading level={3} size="h1"> renders an <h3> that looks like an h1.

Heading-Level Audit: Run a heading-level audit on every page. Tools: axe DevTools, WAVE, or the HeadingsMap browser extension. Common violations:

• Multiple <h1> elements (often: site logo in <h1> plus page title in <h1>)
• Skipped levels (often: <h1> then <h3> because h2 "looked too big")
• Headings used for visual styling, not structure (a bold line that isn't a heading)
• Non-heading text used where a heading is needed (a <div class="title"> instead of <h2>)

Color Contrast (WCAG 1.4.3 Contrast Minimum):

• Heading text must achieve at least 4.5:1 contrast against its background for text under 24px, and 3:1 for text at or above 24px (18.66px bold). Since headings are typically large and bold, most qualify for the 3:1 large-text threshold — but verify with the Contrast Checker.
• Gradient text (background-clip: text) must maintain contrast across the entire gradient range, not just at one point.

Landmark Labeling: Headings frequently serve as labels for landmarks. For example:

<section aria-labelledby="features-heading">
  <h2 id="features-heading">Features</h2>
  …
</section>

This connects the heading to its section landmark, allowing screen readers to announce "Features, region" when navigating by landmark (WCAG 1.3.1).

Reading Order: Ensure headings appear in the DOM in the correct reading order, not just visually via CSS positioning. Screen readers follow DOM order, not visual order (WCAG 1.3.2 Meaningful Sequence).

Usage Guidelines

Do:

• Use exactly one <h1> per page, matching the page's primary topic
• Follow a strict descending hierarchy: h1 → h2 → h3 (no skipping)
• Decouple visual size from semantic level when needed (level={3} size="h1")
• Use fluid typography with clamp() for responsive scaling — configure via the Clamp Calculator
• Add id attributes to headings that serve as anchor link targets
• Set scroll-margin-top to offset fixed headers when using anchor links
• Choose heading fonts that complement body text — explore with the Font Explorer
• Use tighter line-height (1.1–1.2) for large headings and looser (1.3–1.4) for small headings
• Apply negative letter-spacing (-0.01em to -0.03em) for large display sizes

Don't:

• Don't use headings purely for visual styling — if it's not a section title, use Text
• Don't skip heading levels for visual reasons — use the size prop instead
• Don't put interactive elements inside headings (buttons, links) — place them adjacent
• Don't use more than 3–4 heading levels on a typical page — deep nesting signals IA problems
• Don't rely solely on font size to distinguish headings from body text — combine size, weight, and spacing
• Don't set heading margins to zero without providing spacing via parent layout — headings need vertical breathing room

Typography Pairing: A common pattern is pairing a display/serif font for h1/h2 with a sans-serif for h3–h6. This creates visual distinction without relying solely on size. The Font Explorer helps you preview pairings. Ensure both fonts share similar x-heights for visual harmony.

Design System Implementations

Material Design (MUI) uses a <Typography> component with variant prop for both headings and body text. Heading variants: h1 through h6, plus subtitle1, subtitle2. The component prop decouples the rendered element from the visual variant — <Typography variant="h1" component="h3"> renders an <h3> with h1 styling. MUI's default type scale uses Roboto with sizes from 6rem (h1) down to 1.25rem (h6), with decreasing letter-spacing at larger sizes.

Ant Design provides heading via <Typography.Title> with a level prop (1–5). Sizes are predefined and follow Ant's 14px base scale. The component supports copyable, editable, ellipsis (with configurable rows and expandable toggle), and type for semantic coloring (secondary, success, warning, danger). No built-in decoupling of visual size from semantic level.

Chakra UI offers a <Heading> component with as prop for semantic level and size prop (4xl, 3xl, 2xl, xl, lg, md, sm, xs) for visual size. This cleanly decouples semantics from appearance. Chakra's heading inherits from Box, supporting all style props. Sizes use responsive array syntax: size={["lg", "xl", "2xl"]} for viewport-based scaling.

Bootstrap styles headings via .h1–.h6 classes (applicable to any element) and .display-1–.display-6 for larger display headings. This CSS-class approach inherently decouples visual style from semantics. Bootstrap 5 uses $font-size-base * multiplier for heading sizes, with responsive scaling via $enable-rfs (Responsive Font Sizes) which applies calc() scaling similar to clamp().

Apple Human Interface Guidelines specifies Dynamic Type styles: Large Title, Title 1–3, Headline, Subheadline. These map to semantic roles rather than HTML levels. In SwiftUI, .font(.largeTitle) etc. iOS heading styles automatically respond to the user's preferred text size (accessibility setting), scaling from the default 34pt (Large Title) to significantly larger or smaller based on the Dynamic Type slider.

Tailwind CSS provides heading sizing through utility classes: text-4xl, text-3xl, etc. Combined with font-bold, tracking-tight, and leading-tight, developers compose heading styles directly. Tailwind doesn't provide a heading component — it's utility-first, leaving component abstraction to the developer or to component libraries like Shadcn/ui that use <h1 className="scroll-m-20 text-4xl font-extrabold tracking-tight lg:text-5xl">.