Skip to main content
Kaleidoscope

Heading

A typographic component for titles that describe the main sections of an interface and how they hierarchically relate to each other.

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 for more info.

Editable example

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 for more info.

Editable example

Secondary

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

Editable example

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.

Editable example

Alignment

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

Editable example

Theme

Change the theme for headings to match their context.

Editable example

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.

Figma text styleReact component
Heading/Level 1<Heading level="1">
Heading/Level 2<Heading level="2">
Heading/Level 3<Heading level="3">
Heading/Level 4<Heading level="4">
Heading/Level 5<Heading level="5">
Heading/Strong/Level 1<Heading strong level="1">
Heading/Strong/Level 2<Heading strong level="2">
Heading/Strong/Level 3<Heading strong level="3">
Heading/Strong/Level 4<Heading strong level="4">
Heading/Strong/Level 5<Heading strong level="5">