FSD Frontend System Design

Part V — The Craft · Lesson 10.8

Accordion

In one lineA list of disclosure toggles — trivial to render, and a complete accessibility contract to get right.

Where you've seen itAny FAQ page, and every settings panel with collapsible sections.

  • Time14 min
  • DiagramOpen/close state machine + the ARIA wiring
  • Chapter10 · Low Level Design

Diagram

diagram
TWO MODES — decide before you write state

  SINGLE (radio-like)              MULTIPLE (checkbox-like)
  openId: 'q2'                     openIds: Set{'q1','q3'}

  ┌─ q1 ─────────────┐ ▼           ┌─ q1 ─────────────┐ ▲
  ├─ q2 ─────────────┤ ▲           │  answer text     │
  │  answer text     │             ├─ q2 ─────────────┤ ▼
  ├─ q3 ─────────────┤ ▼           ├─ q3 ─────────────┤ ▲
  └──────────────────┘             │  answer text     │
                                   └──────────────────┘
  opening q3 closes q2             each toggles independently
diagram
THE ARIA WIRING — four attributes, all required

  <h3>
    <button id="hdr-2"
            aria-expanded="true"          ← state, updated on toggle
            aria-controls="panel-2">      ← points at the panel
      What is a service worker?
    </button>
  </h3>
  <div id="panel-2"
       role="region"
       aria-labelledby="hdr-2"            ← names the panel
       hidden={!open}>                    ← hidden, not just CSS
    …
  </div>

  Heading level matters: it puts the accordion in the document
  outline so screen-reader users can navigate by heading (8.3).
diagram
KEYBOARD CONTRACT

  Tab            move between headers (each is a tab stop)
  Enter / Space  toggle the focused section
  Home / End     first / last header        (optional, expected in
  Arrow ↑↓       previous / next header      full ARIA pattern)

  Focus NEVER moves into the panel on open — the user chooses (8.4).

How it works

  1. Model state by mode: a single openId or a Set of open ids. Deriving one from the other later is messy — decide upfront.
  2. Use a real <button> inside a heading. The heading level places it in the document outline; the button gives you keys and focus for free.
  3. Wire aria-expanded and aria-controls, and hide closed panels with the hidden attribute so they leave the accessibility tree.
  4. Animate height carefully — height: auto isn't animatable. Use grid-template-rows: 0fr → 1fr, or measure and animate max-height.
  5. Consider <details>/<summary> for simple cases: the platform gives you the semantics and keyboard behaviour with no JavaScript.
jsx
const [open, setOpen] = useState(() => new Set());
const toggle = (id) => setOpen((prev) => {
  const next = single ? new Set() : new Set(prev);
  prev.has(id) ? next.delete(id) : next.add(id);
  return next;
});

Trade-offs

ChoiceConsequence
Single openFocused reading; more clicking
Multiple openComparison across sections
<details>Free semantics; harder to animate and style
CustomFull control; you own the whole contract
Unmount closed panelsLess DOM; loses internal state

Interview angle

"Build an accordion."

  • Ask single or multiple first, because it decides the state shape.
  • Buttons inside headings, aria-expanded and aria-controls wired, hidden on closed panels, focus staying on the trigger.
  • If the content is heavy, lazy-render panels on first open and keep them mounted afterwards to preserve scroll and form state.

Recap

  • Mode decides the state shape — ask before coding.
  • Button-in-heading plus aria-expanded/aria-controls is the whole contract.
  • <details> is free and correct when you don't need custom animation.