import { Meta, Canvas, Source } from '@storybook/addon-docs/blocks';
import { Bulb } from '@transferwise/icons';
import ListItem from '../listItem';
import * as stories from './Header.story';

<Meta title="Typography/Header/Accessibility" />

# Accessibility

Given the `Header` is a key component for structuring content and conveying hierarchy, ensuring its accessibility is crucial for an inclusive experience.

<ListItem
  title="Design guidance"
  subtitle="Before you start, familiarise yourself with the provided guidance."
  control={<ListItem.Navigation href="https://wise.design/components/section-header" />}
  media={
    <ListItem.AvatarView>
      <Bulb />
    </ListItem.AvatarView>
  }
/>

<br />
<br />

## Semantic headings

The `Header` component should always use semantic HTML heading tags (`<h1>` to `<h6>`) to convey the document structure. Avoid using non-semantic tags unless absolutely necessary.

<Source dark code={`
// ✅ semantic heading
<Header as="h1">Main heading</Header>

// ⚠️ use with care

<Header as="div">Non-semantic heading</Header>
`}/>

**Additional resources:**

1. [Deque: Headings must follow a logical order](https://dequeuniversity.com/rules/axe/4.2/heading-order)
2. [MDN: Using headings](https://developer.mozilla.org/en-US/docs/Web/HTML/Element/Heading_Elements)

<br />

## ARIA roles

If the `Header` is used in a non-semantic context, ensure it is accessible by applying appropriate ARIA roles, such as `role="heading"`, and providing a `aria-level` attribute to indicate its level in the hierarchy.

<Source
  dark
  code={`
// ⚠️ use with care
<Header as="div" role="heading" aria-level="1">
  Main heading
</Header>
`}
/>

<br />

## Accessibility with actions

When using the `Header` with actions (e.g., buttons or links), ensure the actions are accessible by providing clear labels and ARIA attributes.

<Source
  dark
  code={`
// ✅ accessible action
<Header
  as="h2"
  action={{
    'aria-label': 'Edit section',
    text: 'Edit',
    onClick: () => alert('Edit clicked'),
  }}
>
  Section heading
</Header>
`}
/>

<br />

## Visual hierarchy

Ensure the `Header` visually aligns with its semantic level. For example, an `<h1>` should be the largest and most prominent, while an `<h6>` should be the smallest.

<Canvas of={stories.Playground} />