# Accordion

## Overview

The accordion component presents grouped disclosure content through native `<details>` and `<summary>` elements.

The component is fully classless. It styles native `<details>` and `<summary>` markup directly so authors can keep the structure semantic and minimal.

## When to use

Use an accordion when users need to scan several short, related sections and reveal only the content they care about.

## When not to use

Do not use an accordion when content must remain visible for comparison, represents a sequence, or belongs in rows and columns; use visible sections, a stepper, navigation, or a table.

## Usage

```html
<details open>
  <summary>What is included?</summary>
  <div>
    <p>Shared theme tokens, component CSS, and semantic HTML examples.</p>
  </div>
</details>

<hr />

<details>
  <summary>Does it need JavaScript?</summary>
  <div>
    <p>No. The interaction uses native disclosure behavior.</p>
  </div>
</details>
```

Use this component when the user needs to scan several short sections and expand only the ones they care about.

Use nav, a stepper, or a table instead when the content should stay visible side by side, represent sequence, or compare values across rows and columns.

Add `<hr />` between items when the design expects a visible divider. It now renders as a subtle system border, while surrounding layout still controls spacing.

The summary text should stay short and descriptive enough to make sense on its own.

## Behavior

Covered by [Playwright behavior tests](../../tests/e2e/components.spec.js).

- ACC-001: The component uses native disclosure semantics and keyboard behavior from `<details>` and `<summary>`.
- ACC-002: Multiple items may stay open at the same time.
- ACC-003: Comfortable and compact density come from the shared layout theme tokens instead of accordion-specific theme branches.
- ACC-004: The summary row keeps a visible focus treatment and a rotating disclosure icon without extra markup.
- ACC-005: Content should accept normal block flow such as paragraphs, lists, and small form groups without requiring named inner wrappers.
- ACC-006: Dividers are opt-in. Authors provide `<hr />` wherever they want a subtle border between items.
- ACC-007: Visual emphasis should come from shared accent, text, and primary tokens rather than one-off component colors.
## Accessibility

- Use a native `<summary>` as the interactive label for each panel.
- Keep the summary concise so it remains understandable when announced on its own.
- Group related accordions in a labeled container only when the set needs extra page-level context or an accessible name.
- Do not replace the native summary interaction with nested buttons or links.
- Do not rely on the disclosure icon alone to communicate open and closed state.

## Variables

| Variable | Type | Description |
| --- | --- | --- |
| `--accordion-accent-color` | `<color>` | Sets the color for disclosure icons and highlighted summary text; change it when the accordion accent should differ from the surrounding text accent. |
| `--accordion-color-focus-ring` | `<color>` | Sets --accordion-color-focus-ring so the component can default to shared theme or layout tokens while exposing an overrideable component API. |
| `--accordion-content-color` | `<color>` | Sets the text color for expanded accordion content; change it when body copy inside panels needs a different contrast treatment. |
| `--accordion-control-gap` | `<length>` | Sets --accordion-control-gap so the component can default to shared theme or layout tokens while exposing an overrideable component API. |
| `--accordion-control-min-height` | `<length>` | Sets --accordion-control-min-height so the component can default to shared theme or layout tokens while exposing an overrideable component API. |
| `--accordion-control-padding-block` | `<length>` | Sets --accordion-control-padding-block so the component can default to shared theme or layout tokens while exposing an overrideable component API. |
| `--accordion-control-padding-inline` | `<length>` | Sets --accordion-control-padding-inline so the component can default to shared theme or layout tokens while exposing an overrideable component API. |
| `--accordion-focus-ring-size` | `<length>` | Sets --accordion-focus-ring-size so the component can default to shared theme or layout tokens while exposing an overrideable component API. |
| `--accordion-font-family-sans` | `Any` | Sets --accordion-font-family-sans so the component can default to shared theme or layout tokens while exposing an overrideable component API. |
| `--accordion-font-size` | `<length>` | Sets --accordion-font-size so the component can default to shared theme or layout tokens while exposing an overrideable component API. |
| `--accordion-icon-font-family` | `Any` | Sets --accordion-icon-font-family so the component can default to shared theme or layout tokens while exposing an overrideable component API. |
| `--accordion-icon-size` | `<length>` | Sets the disclosure icon font size; change it to make the open and closed indicators larger or smaller without changing summary text size. |
| `--accordion-line-height` | `<number>` | Sets --accordion-line-height so the component can default to shared theme or layout tokens while exposing an overrideable component API. |
| `--accordion-space-inline` | `<length>` | Sets --accordion-space-inline so the component can default to shared theme or layout tokens while exposing an overrideable component API. |
| `--accordion-summary-color` | `<color>` | Sets the default summary label color; change it when collapsed accordion headings need stronger or subtler emphasis. |

## Depends On

- `--color-focus-ring`
- `--color-text`
- `--color-text-accent`
- `--font-family-sans`
- `--font-line-height-body`
- `--font-size`
- `--icon-font-family`
- `--layout-control-gap`
- `--layout-control-icon-size`
- `--layout-control-min-height`
- `--layout-control-padding-block`
- `--layout-control-padding-inline`
- `--layout-focus-ring-size`
- `--layout-space-inline`