Heading

Headings are words or phrases that are intended to introduce sections of content. Headings are often used for page headings, as well as content subsections within the page.

Headings should allow users to easily distinguish content sections on the page.

• Headings can have multiple levels of depth to help organize content.
• Heading types provide specific styles to the font-size, font-weight, and line-height of the text to create hierarchy that allow users to easily scan pages and content.
• Headings should be used with intention that maintains a coherent document outline.
• Don’t use heading tags to resize text. Instead use the <Text> primitive.
• Don’t skip headline levels. Always start with <h1>, <h2>, and so on. In other words, don't use an <h3> unless preceded by an <h2>.
• There can only be one <h1> tag per page.
• Always use sentence case when writing headings, for more information read the product style guide.

It is important to not skip one or more heading levels as it is common for screen readers to build an outline of the page and assist users as they navigate a page. Skipping a heading level could cause confusion as the user navigating the page may not know why a heading is missing.

• Heading text should meet AA requirements (4.5:1) for color contrast from itself and the background color.
• Headings should have clear hierarchies of content and subsections.

Headings should capture the most important information contained in the content beneath it. A user should be able to scan just the headers and understand the flow of information on the page.

Keep headings concise. You can omit articles ("a", "the") depending on the context. If the user would be prioritizing efficiency, leave out articles. If the content is more casual, include articles.

Use sentence case.

Visual hierarchy doesn't always follow document hierarchy. For this reason, we've decoupled the visual appearance (the variant prop) from the semantic hierarchy (the as prop) of the element.

For accessibility reasons we want to create a nice clean document hierarchy where:

• We only have one h1
• We don't skip levels as we travel the DOM:

h1
  h2
    h3
    h3
  h2
  h2
    h3
      h4
    h3
      h4

Sometimes, the appropriate document level doesn't match the visual design, because, for example, the third section of content is less important than the previous two, but at the same logical level of document hierarchy.

By decoupling visual appearance from hierarchy, we enable designers and engineers to create visual and semantic hierarchy correctly for all users.

Headings should be used for page headings or content subsections. Headings are broken into six levels, where h1 is the highest level and h6 is the lowest. Avoid skipping heading levels. Use the next lowest heading level to maintain a coherent document outline.