Accessibility

Quick summary

• The accordion must be fully operable with the keyboard. Users should be able to navigate to the header and toggle it using Enter or Space.
• The header must behave as an interactive element with a clear focus state, so users can easily see where they are.
• Open and closed states must be communicated both visually and programmatically. This includes a clear change in icon direction or state indicator, and appropriate ARIA attributes (aria-expanded, aria-controls).
• The content panel should be associated with its header via unique IDs for clear screen-reader navigation.
• Text and icon contrast must meet WCAG AA standards to support readability in different environments.
• The component should follow consistent spacing, typography, and motion guidelines from the design system to reinforce predictable behavior across the interface.

For designers

• All accordion states (collapsed, expanded, hover, and focus) must maintain accessible contrast in both light and dark background contexts.
• Focus styles must remain visible and meet WCAG AA contrast requirements across all supported surfaces. Focus should be clearly distinguishable from hover.
• Interaction feedback (hover, expanded) must use more than colour alone to convey state — for example icon rotation, border emphasis, or background changes.
• Colour tokens used within the accordion should be semantic (e.g. color-foreground-neutral-default) rather than fixed values. This ensures the accordion adapts correctly to different themes or surfaces.
• The icon indicating the open/closed state must have a clear and consistent visual transformation (e.g. rotation) and should not rely on colour alone.

Contrast compliance — Toyota

State	Label colour	Border colour	Contrast ratio	Passes WCAG AA?
Rested	#FFFFFF	#282830	11.5:1	✅ Yes
Hover	#15151B	#A8AAAC	11.5:1	✅ Yes
Expanded	#15151B	#282830	11.5:1	✅ Yes

For developers

The accordion leverages native <details> and <summary> elements, which provide built-in accessibility:

• Enter and Space toggle the panel.
• The browser exposes the expanded/collapsed state to assistive technologies automatically.
• No ARIA attributes are required when using native elements.

Note

If you build a custom accordion without <details>, you must manage aria-expanded on the trigger, aria-controls pointing to the panel’s id, and keyboard interaction yourself. Prefer the native elements whenever possible.

Accordion group

• Use the name attribute on <details> elements to create an exclusive accordion group (only one open at a time).
• Mark decorative icons (like the chevron) with aria-hidden="true" so screen readers skip them.

Implementation checklist

To meet WCAG 2.1 AA and support assistive technologies, follow these implementation standards:

1. Semantic HTML
   • Prefer <details> + <summary>. If building a custom accordion, use a semantic <button> for the header — do not use <div> or <span> with click handlers.
   • The content region must be associated with the header via aria-controls and aria-expanded.
2. Keyboard navigation
   • Accordion headers must be reachable via Tab.
   • Panels must toggle open/closed with Enter and Space.
   • If the accordion is part of a multi-expand list, arrow-key navigation may be supported as an enhancement.
3. Screen-reader support
   • The header text must clearly describe the content it controls.
   • The panel may use role="region" and reference the header with aria-labelledby or aria-controls.
   • Icon-only headers are not permitted; they must include visible text or an accessible label.
4. Interaction feedback
   • Expanded state must be announced via aria-expanded.
   • Visual changes should reinforce state (icon rotation, background, border).
   • Avoid relying solely on colour to indicate open/closed status.
5. Responsive and tap targets
   • The accordion header’s interactive area must be at least 44 px in height to support touch accessibility.

Good vs bad

Case	✅ Good	❌ Bad
Semantic structure	<button aria-expanded="true">…	<div onclick="toggle()">…
Keyboard navigation	Toggles using Enter / Space	Only toggles with pointer click
Focus visibility	Clear, high-contrast focus ring	Focus removed or replaced by hover-only styling
Open/closed state	Icon rotation + aria-expanded + background shift	Only colour change with no semantic state