Build Assets
UI Component
Accordion
Collapsible sections for progressive disclosure of related content groups.
Platform: bothTags: accordion, collapse, expand, faq, disclosure
Purpose
Hides secondary content behind a clickable header, reducing cognitive load on first view. Ideal for FAQs, settings groups, and content where most users only need a subset of sections.
Anatomy
- Header: full-width clickable row, label (15–16px semibold), chevron icon right
- Chevron: rotates 180° on open (200ms transition)
- Panel: content area revealed below header, padding 16–20px
- Divider: 1px border between items
- Optional icon: 20px left of label for category identification
States
- Collapsed: header visible, panel hidden, chevron pointing down
- Expanded: header active (slight bg tint), panel visible, chevron pointing up
- Focused: visible focus ring on header
- Disabled: 40% opacity, not interactive
- Loading panel: skeleton while content loads
Tokens
spacing
headerPadding: 16px 20pxpanelPadding: 4px 20px 20pxchevronSize: 18px
Do
- Allow multiple sections to be open simultaneously (default behavior)
- Animate panel open/close — height transition 200ms ease-out
- Make the entire header row the click target (not just the chevron)
- Use for 3+ collapsible sections — for 1–2, just show the content
Don't
- Use accordions to hide primary content users always need
- Force single-open-only (exclusive accordion) without a clear reason
- Nest accordions inside accordions
- Animate width — only animate height (and opacity optionally)
Accessibility
- Header: <button> element with aria-expanded="true/false"
- aria-controls linking header to panel id
- Panel: role="region" with aria-labelledby pointing to header
- Enter/Space toggles on focused header
Code Example
<div>
<button aria-expanded="true" aria-controls="panel-1">
Section heading <ChevronDown />
</button>
<div id="panel-1" role="region" aria-labelledby="header-1">
Panel content here
</div>
</div>