Skip to main content

An official website of the United States government

Here's how you know

An official website of the United States government

Here's how you know


Design system switcher


Design system switcher


Design system switcher


Design system switcher


Headings help to provide a quick, organized way to organize the main sections of a website.


Typography sizing updates!

We've updated typography sizing variables and class names to separate semantics from presentation. Read about how you can update.

The design system doesn't style base HTML typography elements (like h1, h2, p, etc) unless they're inside an element with the ds-content class. Instead, it provides heading classes (available on this page) corresponding to visual sizes. These classes can be applied to any heading elements, irrespective of their semantic heading level (h1 to h6). This approach allows teams to first choose the semantic heading level that make the most sense for the document and its accessibility and then choose a visual heading size class that fits the page's visual hierarchy.



Example heading (5xl)


Example heading (4xl)


Example heading (3xl)


Example heading (2xl)


Example heading (xl)


Example heading (lg)


Example heading (md)


Example heading (sm)

On dark background

Example heading on dark background

Example link heading on dark background



First and last children

The design system heading styles have alternate margins for headings that are the first or last child of their parent element. Headings that are the first child have no top margin, and headings that are last children have no bottom margin. Some examples of what we mean:

  <h1>I'm the first child of my parent.</h1>
  <h2>I'm not the first child of my parent</h2>
      I'm actually the first child of my parent even though I'm not the first heading on the page
    <h2>I'm the last child of my parent</h2>
  <h2>I'm also the last child of my parent</h2>

The ds-content class

For pages that are mainly about written content or places where you want to use a standard mapping of heading-level styles to semantic heading levels, consider using the ds-content class.

Responsive typography

.ds-text-heading-5xl, ds-text-heading-4xl, and ds-text-heading-3xl classes are responsive by default.

Font class545px and below545px to 768px768px and above
Scale: 0.22

To apply responsive typography elsewhere, use the font size utility class. Since the base typography margins and line height is measured in em units, they'll automatically adjust as you change the font size.

Style customization

The following CSS variables can be overridden to change the type sizes:

  • --font-size-5xl
  • --font-size-4xl
  • --font-size-3xl
  • --font-size-2xl
  • --font-size-xl
  • --font-size-lg
  • --font-size-md, uses --font-size-base
  • --font-size-sm