Accordion

Two containers with opposite promises. A layout panel says this is here, and it stays here. An accordion says this is here, but you will have to ask for it. In clinical software the second promise is expensive, so it is made rarely and never about anything that changes a decision.

Overview

Both exist to give a screen structure the clinician can rely on. The panel does it by drawing a boundary — everything inside belongs to one subject, and the panel header says which. The accordion does it by trading visibility for density.

That trade is the whole risk. Collapsed content is content nobody read. Not "content read later" — in practice, not read at all. So the question this page keeps asking is the same one: is it acceptable for a clinician to never open this? If the answer is no, it does not go in an accordion.

Layout panel

Accordion

• Never exclusive-open by default. Opening one section must not close another; comparing two sections is a normal thing to want.
• Never collapse what the clinician opened, on refresh, on data arrival, or when a sibling opens.
• Never nest accordions. Two levels of collapse is two chances to lose something, and the second level is almost never opened.
• Never put a form across sections. Validation errors in a collapsed section are errors the clinician cannot see; if a form is long, use Tabs with a visible progress statement or a single scrolling panel.
• Never animate longer than 150 ms, and honour prefers-reduced-motion — see Motion.
• Headers are real headings containing a button, so the section structure is navigable by heading, not just by tab.

How to build one

This page previously documented a hand-built accordion — a button, a region, and aria-expanded — without asking whether that was the right construction. It usually is not.

Why find-in-page is the deciding argument

A clinician who presses Ctrl+F and types troponin expects the page to answer. In a hand-built accordion the collapsed content is in the DOM but hidden, so the browser reports no match — and the reader concludes the page does not contain it. That is content which exists, is on screen in principle, and cannot be found, which is the failure this component's own rule was written to prevent. It is also invisible in testing, because the person testing knows where the content is.

Native <details> is opened by the browser when a match is inside it. If you must hand-build, the collapsed region uses hidden="until-found" rather than hidden, and listens for beforematch to set its own expanded state. A plain hidden is a defect.

Never use name to group them. The attribute makes <details> elements mutually exclusive, which is exactly the exclusive-open behaviour this component forbids — the platform offers it, and we decline.

Heading level

The node lives inside a heading at the level the surrounding document implies, so an accordion under an h2 uses h3. Getting this wrong breaks heading navigation, which is the primary way a screen-reader user moves through a long record — and it is the fastest route for everyone else too. With <details>, wrap the <summary> content in the heading rather than the element itself.

Deep links and scroll

• A fragment pointing inside a closed section opens it. Linking to #acquisition-notes and landing on a collapsed node is the same failure as find-in-page, arriving by a different route.
• Collapsing a section above the viewport must not move the content below it. The reader's place is theirs. Where the browser's scroll anchoring does not hold it, hold it explicitly — see Reprioritisation for what content moving under a reader costs.
• Everything expands for print. A collapse on paper is a deletion, per Printed output.

Anatomy of a node

Six parts, four of which stay readable while the node is closed. That is the whole design problem: a closed node is the only thing most readers will ever see of it, so everything needed to decide whether to open it has to survive the collapse.

Variants

Three choices, each fixed for the whole accordion rather than per node.

Type

Divider is the default — hairlines between nodes, no gaps, one enclosing border. It reads as one object with parts. Filled gives each node its own surface with a 4 px gap, and reads as a list of separable things. Choose by which is true. Never mix them in one accordion: a node that looks unlike its neighbours reads as a different kind of thing, and readers will look for a meaning that is not there.

Size

The floor exists for a gloved fingertip, which has a larger contact patch and no feel for the edge of a target. A 32 px node is not a denser layout; it is a control that cannot reliably be acquired. If a deployment is uncertain — a workstation that is sometimes a cart — it is not a no-touch context.

Node format

The key–value format puts the value at the far end of the node, where it stays readable closed. The accordion then doubles as a summary a clinician can scan without opening anything, and the expansion carries the working — the method, the source, the interval. Values follow Key–value pair: units always present, and an absence stated in words rather than left blank.

Secondary text qualifies the label — a time, a source, a scope. It may be stacked under the label or inline beside it, consistently. It never carries the finding: a node reading "Findings · ST elevation 3.1 mm" has put a clinical conclusion in a place the reader may skip.

Configuration

• Caret side. Leading or trailing, chosen once and identical on every node. A caret that moves between nodes turns a scan into a search.
• Metadata slot order. Count first, then priority, then the caret. Fixed, because a reader locates these by position long before they read them.
• Counts are exact. No capping, per Badge — the difference between 9 and 90 prior recordings is the difference between glancing and planning.
• Priority is the highest contained, not a summary of the section's mood. If anything inside is advisory, the closed node says advisory.
• No required-field marker on a node. Other systems place an asterisk on a node whose content holds a required field. Two rules here forbid needing one: forms do not span sections at all, and "required" is stated in words rather than punctuation — see Text field.

Behaviour

Formatting

• Spacing. Divider type stacks with no gap. Filled type stacks with 4 px between nodes.
• Padding. 0.8 rem inside the node, and content padding matching it so the label and the text beneath it share a leading edge.
• Placement. Inside a panel, or directly on the page surface. Never inside another accordion — two levels of collapse is two chances to lose something, and the second level is almost never opened.
• Caret direction. Down when closed, up when open. This is the one thing the caret is for, and it is still decorative: aria-expanded is what is actually announced.
• Right-to-left. The node mirrors — label, secondary text, metadata and caret all swap edge. Nothing inside the content mirrors that would not mirror on its own, so a trace or a time axis keeps its direction, per International design.

States

What the component enforces, and what it only asks for

Built on <details>, so the platform holds the mechanics and the component holds one rule the platform has no opinion about.

Do's and don'ts

Accessibility

• Collapsed content stays findable. Native <details> is opened by find-in-page; a hand-built region uses hidden="until-found" and handles beforematch. A plain hidden makes the text unreachable by the browser's own search — see How to build one.
• Header is a native <summary> containing a heading (headingLevel, default 3), so the disclosure is announced as a disclosure with its state, and the title still sits in the page outline. Screen-reader users navigate by heading far more than by tab. This bullet used to describe a heading wrapping a button, which is the hand-built construction the component was rebuilt away from.
• Expanded state is the element’s own. <details> carries it; there is no aria-expanded or aria-controls to keep in step, and nothing to drift.
• The native marker is hidden and the state is in words. A glyph is not a state.
• Contained state is in the accessible name — "Device and acquisition notes, 1 advisory, collapsed" — not only in a coloured chip.
• Panels use <section aria-labelledby> so the boundary the border draws visually exists non-visually too.
• Panel borders meet 3:1 against both surfaces they separate (SC 1.4.11). This is verified in CI against tokens.
• Expansion animates ≤ 150 ms and respects prefers-reduced-motion, which disables the height transition entirely.
• No scroll trapping. An expanded section extends the page; it does not create an inner scroll area the user cannot escape by keyboard.
• Targets ≥ 24 px — the whole header row is the target, not just the caret (SC 2.5.8).
• Find-in-page. Where the platform supports it, collapsed content uses hidden="until-found" so browser search still reaches it. Nothing safety-relevant depends on that support existing.

Outcomes of use

What this contributes to, in the terms of Usability & context of use. These are attributes believed to contribute to an outcome; the outcome itself is settled by observing real use in a specified context, not by this page.

• Effectiveness — nothing decision-relevant is behind a caret, and closed sections still declare what they hold.
• Efficiency — a screen dense enough to work in, without the cost of opening three sections to answer one question.
• Satisfaction — sections that stay as they were left. Re-collapsing what someone opened is a small betrayal, repeated all shift.

Clinical safety notes

• Alarms and active findings are never collapsible. (you) Mitigates: a critical finding never read because it was behind a caret.
• Closed headers declare contained count and priority. (the component) Mitigates: no cue to open the section that matters.
• Non-exclusive expansion. (the component) Mitigates: losing the section being read when another is opened.
• Expansion state preserved across data arrival and refresh. (you) Mitigates: re-reading work already done, and missing that content changed.
• No forms split across collapsed sections. (you) Mitigates: validation errors hidden from the person being asked to fix them.
• One panel, one subject, named in the header. (the component names it; one subject is you) Mitigates: two patients' data read as one patient's.
• Panels degrade with a stated reason rather than disappearing. (you) Mitigates: a missing panel read as absent data rather than a failure.
• Sections never removed silently. (you) Mitigates: a permission or availability state indistinguishable from non-existence.

Implementation

$ npx shadcn@latest add https://md.notjustany.tech/r/accordion.json

<Accordion>
  <AccordionItem
    title="Device & acquisition notes"
    summary="2 advisories, both acknowledged"   // required: a closed section must describe itself
    headingLevel={3}
  >
    <p>Lead V3 reversed on acquisition.</p>
  </AccordionItem>
</Accordion>

// No 'exclusive' prop and no 'name' on the underlying <details>, so one
// section cannot close another. The constraint is the absent API, not a
// runtime check.
// Panel used to ship with this install command and is not an accordion:
// a Panel is a titled container, an Accordion is a set of sections that
// open and close. It moved to the layout item — see Grid & panels.

What the component takes. This table used to list multiple, heading, LayoutPanel, subjectId — props the component does not have, and never had. Found by the registry gate’s props-table rule.

Related

• Affordance & perceivability — the general rule this page applies: a control exists only if every reader who can operate it can perceive it.
• Card — when the container is a discrete object rather than a region of a layout.
• Tabs — mutually exclusive views, where an accordion would be wrong.
• Tree — the same collapse rule applied to hierarchy.
• Toolbar — what may sit inside a panel's border, and why.
• Elevation — why panels stay flat.
• Motion — the 150 ms ceiling and reduced motion.