Hierarchy

The hierarchy of heading levels available. In a design, headings won't always start from the largest and descend incrementally to the smallest, but semantically headings should be ordered this way. See the accessibility section for more info.

<Heading level="1">Heading 1</Heading>
<Heading level="2">Heading 2</Heading>
<Heading level="3">Heading 3</Heading>
<Heading level="4">Heading 4</Heading>
<Heading level="5">Heading 5</Heading>

Best practices

1. Avoid manually applying a className to override the color, text-align, font-weight, or font-size. All of these parameters are handled by the component's props.
2. Heading components do not contain any inherent spacing. It's recommended to use the layout to determine spacing. Rather than applying a className and applying a margin or padding to the text, use the containing element with display: flex; or display: grid; and gap to determine spacing.

Element

Determines the underlying HTML element rendered by the component. By default headings will render an element matching the level prop. So <Heading level="1"> will render an <h1>. Be careful to use the correct element for the page context. See the accessibility section for more info.

<Heading level="5" element="h1">This heading looks like a level 5 heading, but uses an h1 tag</Heading>

Secondary

Secondary headings should be used to reduce emphasis on the heading with a fainter text color.

<Heading secondary level="4">A secondary heading</Heading>

Strong

Use the strong prop to make headings appear bolder for emphasis. Note that this does not change the rendered HTML element to a <strong> tag.

<Heading strong level="4">Bolder heading</Heading>

Alignment

Alignment can be set using the align prop. Defaults to left aligned.

<Heading align="center" level="4">Center aligned heading</Heading>

Theme

Change the theme for headings to match their context.

<Card theme={CardTheme.Dark}>
  <div className="space-inset-m">
    <Heading theme="dark" level="3">Dark themed heading</Heading>
    <Heading secondary theme="dark" level="4">Dark themed secondary heading</Heading>
  </div>
</Card>

Accessibility

• Headings should always start from <h1> and descend in a logical order for each level down in the hierarchy without skipping any levels. That means even if a design has a level="2" heading as the first and largest heading on the page, it should be set to render an <h1> element with element="h1". If the design then steps down to a level="3" heading for headings below that level, they should be set to element="h2". This makes it easier for users of assistive technology to jump between sections of the page using the heading hierarchy.
• If a heading is not intended to act as a descriptor for a section of the page (i.e. is being used cosmetically and not semantically) switch out the element to match its lack of semantics e.g. element="div"
• Avoid manually overriding the text color and instead use the secondary prop to dim less important text and the theme prop to use appropriate colors for a light or dark theme. The default colors assigned for each of these props have been chosen to meet the WCAG AA minimum contrast ratio.

Figma text styles

There's an explicit mapping of text styles to React components for the standard and strong variants. Figma doesn't store text color or alignment in text styles though, so those variants need to be inferred. Rule of thumb is if the heading color is Slate in Figma, it should be the secondary variant.