import { Meta, Story, Canvas } from '@storybook/addon-docs/blocks';
import { Text, Link, Box, Head1, SectionHeader, PageTitle } from '../../index';

<Meta title="Components/Typography/Accessibility Tips" />

# Accessible Headers

Screen readers like Apple Voice Over scan your screen's DOM for `h1` ... `h6` level headers. These are used to generate a kind of "table of contents" that low-vision users can use to navigate around the different sections of your page.

Typically our design team's designs are well structured visually with titles for the different sets of UI on the page. As long as you use the correct patchwork components to implement them, the screen reader functionality descrived above should "just work".

We export several components that generate semantic headers in React's DOM output:

`Head1` ... `Head5`: These components render h1 and h5 headers with default typographic styling. Make sure that all the elements on a given screen come together in an overall outline structure that makes sense. If you need visual size to be different than the organizational importance, the `HeadN` compontents accept a `fontSize` property that lets you override the visual importance without changing the header's place in the document's conceptual outline.

`SectionHeader`: SectionHeader is available in small and large variants. By default, the small variant renders a level 3 header (`h3`) and the large variant renders a level 2 header (`h2`). You can override this using the `headerLevel` prop from the `SemanticHeaderLevel` mixin:

<Canvas>
  <SectionHeader headerLevel={5}>L5 SectionHeader</SectionHeader>
</Canvas>

`PageTitle`: By default, PageTitle acts semantically as a level 1 header (`h1`). However, it too supports the `SemanticHeaderLevel` mixin, for cases where you need the same visual impact but a lower semantic level:

<Canvas>
  <PageTitle headerLevel={5}>L5 PageTitle</PageTitle>
</Canvas>

`Text`: Text is our general purpose typography component. By default it is semantically equivalent to a `p`, but you can "promote" it semantically:

<Canvas>
  <Text headerLevel={2}>Really important text!</Text>
</Canvas>

Finally, for rare cases where you want the visual impact of a header but want to exclude it from the semantic page outline, you can use `headerLevel={none}`:

<Canvas>
  <PageTitle headerLevel="none">Non-title PageTitle</PageTitle>
  <PageTitle headerLevel="none">Non-title SectionHeader</PageTitle>
</Canvas>