Accordion

A native <details> styled via a single class. Animated open and close via ::details-content + the CSS Grid 0fr → 1fr trick + transition-behavior: allow-discrete. Single-open grouping via the native name attribute. Two variants, three sizes, color theming. No JavaScript.

Install

import "elements-kit/ui/styles.css";

// pick a neutral palette for --neutral-* (must match data-neutral on root):
import "elements-kit/ui/styles/palette/gray.css";
import "elements-kit/ui/styles/neutral/gray.css";
// and the accordion itself:
import "elements-kit/ui/accordion/accordion.css";

API

<!-- Single-open group: same `name` on all items -->
<details class="x-accordion" name="faq" data-size="2">
  <summary>How does it work?</summary>
  <p>Any HTML inside.</p>
</details>
<details class="x-accordion" name="faq">
  <summary>Is it accessible?</summary>
  <p>Native disclosure semantics.</p>
</details>

<!-- Multi-open: omit `name` -->
<details class="x-accordion">
  <summary>Standalone</summary>
  <p>Content.</p>
</details>

Attribute	Values
name (native HTML)	any string — items sharing a name form an exclusive group
data-variant	surface (default — bordered card), soft (tinted block, no border), borderless (no chrome — color-only hover)
data-size	1, 2 (default), 3
data-accent (on parent or self)	any imported color scale
aria-disabled="true"	greys out and stops clicks; screen readers announce as disabled
open (native HTML)	initial open state

Sizing

data-size	summary padding	font-size
1	--space-2 / --space-3	--font-size-2
2 (default)	--space-3 / --space-4	--font-size-3
3	--space-4 / --space-5	--font-size-4

Variants

• surface (default) — --color-material background with a soft --neutral-a5 border and --radius-4 corners. In light mode the body sits at --neutral-a2; in dark mode that tint moves to the summary. Stacked siblings collapse their adjoining borders into one card.
• soft — surface minus the border. Shares the panel bg, per-mode alpha flip on summary/body, and hover behavior; just no 1px solid ring around it. Mid-emphasis between surface and borderless.
• borderless — no border, no background, no horizontal padding. Hover affordance is a text-color shift (a12 → 12) — no bg wash. The trigger color also stays at full strength while [open]. For FAQs inside body copy.

The primitive ships no chevron — keep it quiet by default. If you want one, place an SVG (or anything else) inside <summary> and rotate it with your own [open] > summary svg { transform: rotate(180deg); } rule. See the playground for an example.

Single-open grouping

Browser-enforced via the native name attribute. Opening one item closes its siblings.

<details class="x-accordion" name="faq"><summary>One</summary>…</details>
<details class="x-accordion" name="faq"><summary>Two</summary>…</details>
<details class="x-accordion" name="faq"><summary>Three</summary>…</details>

Omit name and each item opens independently.

Animation

Three pieces cooperate to animate both open and close, cross-browser:

1. ::details-content — addresses the content wrapper as a pseudo-element so we can style it without an extra DOM node.
2. display: grid; grid-template-rows: 0fr → 1fr — the classic grid trick. The implicit row track holds the rendered children of <details> (minus <summary>). Transitioning the track between 0fr and 1fr is universal CSS — no interpolate-size needed, so it works in every current browser. padding-block-end is animated alongside so the bottom padding grows in lockstep.
3. transition-behavior: allow-discrete on content-visibility — defers the browser’s instant content-hide until the row collapse finishes, so the close animation runs to completion.

Without allow-discrete, the browser would yank the content the moment [open] flipped off and the close would be invisible.

Respects prefers-reduced-motion: reduce — transitions are removed.

States

• [open] — content expanded.
• :focus-visible on summary — 2px --focus-8 outline at -2px inset offset.
• aria-disabled="true" — 0.6 opacity, pointer-events: none on the summary. <details> has no native disabled and isn’t a form control, so :disabled doesn’t apply; aria-disabled is the spec-correct hook and is announced by screen readers.

Nested accordions

Nest a <details class="x-accordion"> inside another’s content. Cascade Just Works — sizing tokens scope per item, single-open grouping scopes per name.

<details class="x-accordion" name="outer">
  <summary>Parent</summary>
  <details class="x-accordion" name="inner">
    <summary>Child</summary>
    <p>Deep content.</p>
  </details>
</details>

Theming

Set data-accent="<color>" on the accordion or any ancestor to theme the accent. Light/dark flips automatically via the .dark class on a parent — see Light & dark.

Accessibility

<details> / <summary> is a native disclosure widget. Keyboard support (Enter, Space to toggle) and screen-reader announcement (disclosure triangle, collapsed/expanded) come from the browser.

• Put the trigger label in <summary> directly — wrap with <h3> inside the summary only if document outline matters. Don’t wrap <details> in a heading.
• For long content panels, the disclosure region is implicitly labeled by the summary. No aria-controls needed.

Don’t

Set aria-expanded on <summary>. The browser owns it. Adding the attribute manually fights the native state and confuses assistive tech.

Browser support

Feature	Chrome	Safari	Firefox
<details name> grouping	120+	17.4+	129+
::details-content	131+	18.2+	137+
transition-behavior: allow-discrete	117+	17.4+	129+
grid-template-rows transition	universal	universal	universal

All current browsers support the full set. Older browsers degrade to instant open and close — disclosure still works; grouping falls back to multi-open. No JavaScript fallback is shipped.