Accordion

Problem Context

• A page contains multiple related sections under one topic, form, policy, help article, settings group, or result detail.
• Users may need an overview of section labels before choosing which detail to read.
• Some sections may be optional, reference-heavy, or repeated enough that always showing all content would bury the page's main task.
• The product can keep headings, content order, open state, focus, and validation or status indicators synchronized.

Selection Rules

• Choose accordion when multiple related page sections can be independently shown or hidden without changing route, page context, or selected mode.
• Use a single details disclosure when there is only one less-prominent revealable section.
• Use tabs when only one peer panel should be active and users are switching between sibling sections rather than scanning many section headings.
• Use side navigation when sections are separate pages or a persistent local hierarchy, not content panels on one page.
• Use filter panel when the collapsed groups contain controls that narrow a result set and need active-filter counts, applied summaries, and result synchronization.
• Use process list when expandable items are ordered journey steps with task links, costs, and branch guidance.
• Keep required errors, submit buttons, urgent warnings, and primary instructions visible or summarized outside collapsed sections.
• Allow several panels to remain open when comparison or form editing across sections is common; if only one panel can stay open, explain and preserve data before closing another section.
• Use expand-all or collapse-all for long accordion groups when users commonly need to scan or print several panels.
• Do not use accordion labels as page navigation unless the interaction actually navigates and exposes current-page state.

Required States

• All collapsed state with every section title visible.
• One section expanded state with button and controlled panel synchronized.
• Multiple sections expanded state when the accordion supports independent panels.
• Expand all and collapse all state when group controls are present.
• Collapsed section with error, changed, selected, or required-count summary when hidden content affects completion.
• Focused section header state that remains visible during keyboard navigation.
• Disabled or unavailable section state with explanation when expansion is blocked.
• Responsive state where long labels and panel content remain readable.

Interaction Contract

• Activating a section header toggles only the panel it owns unless the component is explicitly single-open.
• The header button exposes expanded or collapsed state and stays in the heading order.
• Revealed content appears immediately after its heading in reading and focus order.
• Enter or Space toggles the focused header; optional arrow, Home, and End support must not break normal Tab movement.
• Expand all opens every section and Collapse all closes every closable section without losing form values or scroll context.
• Collapsed sections that contain errors, active filters, changed values, or selected options expose a concise summary at the header.
• Deep links, validation, search hits, or find-in-page targets inside a panel open that panel or provide a clear route to it.

Implementation Checklist

• Use button elements for section headers and place them inside semantic headings that match the page outline.
• Connect each button to its panel with stable identifiers and keep expanded state synchronized with visibility.
• Decide whether multiple panels can be open and implement that rule consistently.
• Keep content in source order so headings and panels make sense when styles or scripts fail.
• Expose hidden-error counts, selected-count summaries, or changed-state badges on collapsed headers when users need them.
• Avoid overusing landmark regions for every panel on pages with many sections.
• Test Enter, Space, Tab order, optional arrows, Home, End, screen reader announcements, print, no-JavaScript fallback, deep links, and mobile wrapping.

Common Generated-UI Mistakes

• Using divs or links as section toggles without button semantics or expanded state.
• Hiding content users must read sequentially before completing a task.
• Making collapsed section labels too vague, such as More, Details, or Information.
• Removing form values or validation messages when another section opens.
• Showing errors only inside collapsed panels without a header summary or error link.
• Using an accordion as local navigation to separate pages.
• Forcing one panel open at a time when users need to compare multiple sections.

Critique Questions

• Are these sections related content on one page, or are they separate destinations?
• Can users understand every collapsed section from its label and summary?
• What important content, errors, or changed values are hidden when panels collapse?
• Should users be able to open multiple panels at once?
• Does keyboard focus move predictably from heading button to revealed content?
• Would always-visible headings, a details disclosure, tabs, side navigation, or a process list better match the task?