Components

Accordion

A stack of headers that each open and close a section of content.

Storybook: Storybook
Source: Source

Role and semantics

Accordion implements the APG accordion pattern with Base UI Accordion. Each item header is an <hN> element (headingLevel, default 3) that holds a <button> with aria-expanded and aria-controls. The panel is a region named by the button. The button name comes from its visible text: the title, then the description if there is one, so the visible text and the name match (WCAG 2.5.3). The chevron and icon are aria-hidden, so they are not read. Closed panels carry hidden="until-found"; the browser’s find in page finds the content and opens the item.

Keyboard

Key	Behaviour
Tab	Moves through the header buttons in order.
Enter, Space	Opens or closes the focused item.

There is no arrow-key navigation. The APG accordion pattern (2025 update) treats arrow keys as optional; Accordion does not use them.

Focus

The button shows a 2 px color-focus-ring drawn inside, so neighbouring items do not clip it. The ring shows only on keyboard focus (focus-visible).

Example	Read as
Closed item	“First heading, button, collapsed”
Open item	“First heading, button, expanded”
Item with a `description`	“First heading, button, collapsed, Short description text”
`disabled` item	“Third heading, button, dimmed”
Entering the panel	“First heading, region”

Contrast

Header and panel text meet at least 4.5:1 against their backgrounds (color-fg-default); the description meets the same threshold with color-fg-subtle. The open state is not shown by colour alone: the chevron turns and the content is visible. Disabled text is exempt from the contrast threshold (WCAG 1.4.3).

WCAG 2.2

Criterion	How Accordion meets it	What the product team must do
1.3.1 Info and relationships	Heading, button and `region` roles with `aria-controls` and the panel’s `aria-labelledby`.	Set a `headingLevel` that fits the page’s heading order.
1.4.1 Use of colour	The open state is also shown by the chevron turn and the visible content.	Do not hide the chevron with `className`.
2.1.1 Keyboard	Tab, Enter and Space.	Do not add your own key handlers to the buttons.
2.4.7 Focus visible	`focus-visible` ring.	Do not remove the ring.
2.5.8 Target size (minimum)	The smallest header button is 40 px high.	Do not leave titles empty.
4.1.2 Name, role, value	Name from the `title`, state from `aria-expanded`.	Give every item a meaningful `title`.