# Accordion

> Sections a person opens one at a time when most are not needed at once. Each closed row already says its current value, so it rarely needs opening.

Source: https://kwark.space/designSystem/components/accordion

## Usage

### What it is
A stack of rows that each open to show more. Kwark uses it where most of a form is optional and most people never touch it: the project options in *New project* and *Edit project* (writing format, a colour for the story, genres).

### The rule that makes it work: the closed row says the answer
Every row shows its current value at the right: *Feature film*, *Choose later*, *Thriller, Family*. Most people read the closed stack, see the answers are right, and move on. A row only needs opening to change it. This is why an accordion is acceptable in Kwark at all: nothing is hidden that someone needs to know.

### When to use
- Optional settings with sensible defaults, where each section is independent.
- A long sheet on a phone where sections are scanned, such as a scene's breakdown by department, each with its pencil colour and a count.

### When not to use
- When people usually need everything: show everything.
- For steps in order: [progress steps](https://kwark.space/designSystem/components/stepper.md).
- To hide required fields, warnings or anything that blocks saving.
- For navigation between pages: [tabs](https://kwark.space/designSystem/components/tabs.md) or the [tree view](https://kwark.space/designSystem/components/tree-view.md).

### Behaviour
- Any number of rows can be open at once; opening one never closes another.
- Rows with something in them may start open (breakdown departments with items); empty ones start closed and say so (*None marked*).
- The open state is not saved; a dialog opens with the first row open only when it needs a choice.

## Style

### Anatomy

1. **Stack**: 1px `--k-line` above the first row and under each (`.story-project-options`), up to 460px in a dialog.
2. **Summary**: at least 44px, 16px top and bottom, no side padding (the story override), 12px gap.
3. **Icon**: 16px Lucide in `--k-text-2`, `--k-text` on hover. In the breakdown it is the department's 10px pencil dot (`--k-bk-*`).
4. **Label**: Poppins 600 12px in `--k-text`, taking the free width.
5. **Value**: 12px `--k-text-2`, tabular, truncated at 45% of the row.
6. **Chevron**: a 14px SVG (`ChevronDown`), turning 180° over `--k-dur-2` when open. Never a CSS border chevron or the native triangle.
7. **Body**: 0 0 16px, indented 28px so it starts under the label; 14px `--k-text-2` for prose; choices as 8px-corner cards lit with `--k-accent-soft` when pressed.
8. **Empty row**: label in 500 `--k-text-2`, value *None marked*.

### Tokens

| Token | Light | Dark |
|---|---|---|
| `--k-line` | #e2e8f0 | rgba(255, 255, 255, .1) |
| `--k-text` | #0f172a | #e3e3e3 |
| `--k-text-2` | #5b6779 | #9ca3af |
| `--k-focus` | #0f172a | #f4f4f5 |
| `--k-accent-soft` | #e8b58b | #e8b58b |
| `--k-bk-prop` | #a98bd6 |  |
| `--k-bk-wardrobe` | #72b07e |  |
| `--k-bk-vehicle` | #e38fb4 |  |
| `--k-tap` | 44px |  |
| `--k-radius-control` | 6px |  |
| `--k-fs-meta` | 12px |  |
| `--k-fs-body` | 14px |  |
| `--k-icon-md` | 16px |  |
| `--k-icon-sm` | 14px |  |
| `--k-dur-2` | 200ms |  |

## Code

### React

Use the HTML below with `kwark.css`. The example shows the markup and styling. Supply any application behavior described on this page.

### HTML and CSS

Works anywhere with `kwark.css`.

```html
<div class="kw-acc">
  <details open>
    <summary><svg viewBox="0 0 24 24" fill="none" stroke="currentColor" stroke-width="1.75" stroke-linecap="round" stroke-linejoin="round" aria-hidden="true"><path d="M20.2 6 3 11l-.9-2.4c-.3-1.1.3-2.2 1.3-2.5l13.5-4c1.1-.3 2.2.3 2.5 1.3Z"/><path d="m6.2 5.3 3.1 3.9M12.4 3.4l3.1 4M3 11h18v8a2 2 0 0 1-2 2H5a2 2 0 0 1-2-2Z"/></svg><span class="kw-acc__label">Writing format</span><span class="kw-acc__value">Feature film</span><svg class="kw-acc__chev" viewBox="0 0 24 24" fill="none" stroke="currentColor" stroke-width="2" stroke-linecap="round" stroke-linejoin="round" aria-hidden="true"><path d="m6 9 6 6 6-6"/></svg></summary>
    <div class="kw-acc__body"><div class="kw-acc__choices" role="group" aria-label="Writing format">
      <button type="button" aria-pressed="true">Feature film<span>90–120 pages</span></button>
      <button type="button" aria-pressed="false">Short film<span>Under 40 pages</span></button>
      <button type="button" aria-pressed="false">Series<span>Episodes in seasons</span></button>
    </div></div>
  </details>
  <details>
    <summary><svg viewBox="0 0 24 24" fill="none" stroke="currentColor" stroke-width="1.75" stroke-linecap="round" stroke-linejoin="round" aria-hidden="true"><path d="M12 22a1 1 0 0 1 0-20 10 9 0 0 1 10 9 5 5 0 0 1-5 5h-2.2a1.8 1.8 0 0 0-1.3 3.1 1.6 1.6 0 0 1-1.5 2.9z"/><circle cx="13.5" cy="6.5" r=".5"/><circle cx="17.5" cy="10.5" r=".5"/><circle cx="8.5" cy="7.5" r=".5"/></svg><span class="kw-acc__label">A colour for this story</span><span class="kw-acc__value">Choose later</span><svg class="kw-acc__chev" viewBox="0 0 24 24" fill="none" stroke="currentColor" stroke-width="2" stroke-linecap="round" stroke-linejoin="round" aria-hidden="true"><path d="m6 9 6 6 6-6"/></svg></summary>
    <div class="kw-acc__body"><p>The project wears it on its buttons, ticks and cover.</p></div>
  </details>
  <details>
    <summary><svg viewBox="0 0 24 24" fill="none" stroke="currentColor" stroke-width="1.75" stroke-linecap="round" stroke-linejoin="round" aria-hidden="true"><path d="M12.6 2.6A2 2 0 0 0 11.2 2H4a2 2 0 0 0-2 2v7.2a2 2 0 0 0 .6 1.4l8.7 8.7a2.4 2.4 0 0 0 3.4 0l6.6-6.6a2.4 2.4 0 0 0 0-3.4z"/><circle cx="7.5" cy="7.5" r=".5"/></svg><span class="kw-acc__label">Genres</span><span class="kw-acc__value">Thriller, Family</span><svg class="kw-acc__chev" viewBox="0 0 24 24" fill="none" stroke="currentColor" stroke-width="2" stroke-linecap="round" stroke-linejoin="round" aria-hidden="true"><path d="m6 9 6 6 6-6"/></svg></summary>
    <div class="kw-acc__body"><p>Genres help you find the project on your shelf. They never change what Kwark offers.</p></div>
  </details>
</div>
<div class="kw-acc kw-acc--departments" aria-label="Scene 12 breakdown">
  <details open>
    <summary><span class="kw-acc__pencil" style="--kw-pencil:var(--k-bk-prop)" aria-hidden="true"></span><span class="kw-acc__label">Props</span><span class="kw-acc__value">3 items</span><svg class="kw-acc__chev" viewBox="0 0 24 24" fill="none" stroke="currentColor" stroke-width="2" stroke-linecap="round" stroke-linejoin="round" aria-hidden="true"><path d="m6 9 6 6 6-6"/></svg></summary>
    <div class="kw-acc__body"><div class="kw-acc__items"><span>Splicer</span><span>Reel 3</span><span>Zippo</span></div></div>
  </details>
  <details>
    <summary><span class="kw-acc__pencil" style="--kw-pencil:var(--k-bk-wardrobe)" aria-hidden="true"></span><span class="kw-acc__label">Wardrobe</span><span class="kw-acc__value">1 item</span><svg class="kw-acc__chev" viewBox="0 0 24 24" fill="none" stroke="currentColor" stroke-width="2" stroke-linecap="round" stroke-linejoin="round" aria-hidden="true"><path d="m6 9 6 6 6-6"/></svg></summary>
    <div class="kw-acc__body"><div class="kw-acc__items"><span>Mira’s grey cardigan</span></div></div>
  </details>
  <details class="is-empty">
    <summary><span class="kw-acc__pencil" style="--kw-pencil:var(--k-bk-vehicle)" aria-hidden="true"></span><span class="kw-acc__label">Vehicles</span><span class="kw-acc__value">None marked</span><svg class="kw-acc__chev" viewBox="0 0 24 24" fill="none" stroke="currentColor" stroke-width="2" stroke-linecap="round" stroke-linejoin="round" aria-hidden="true"><path d="m6 9 6 6 6-6"/></svg></summary>
    <div class="kw-acc__body"><p>Mark a vehicle in the script and it appears here.</p></div>
  </details>
</div>
```

In the app the accordion is native `<details>` inside `.story-project-options` (`components/ui/ProjectFormModal.tsx`, styled in `shared/StorySurface.css`): a 16px Lucide icon, the label in semibold, the current value in 12px muted text, and a 14px `ChevronDown`. There is no shared `Accordion` component; use the markup above.

## Accessibility

### Keyboard
| Key | Does |
|---|---|
| Tab | Moves between summaries, and into an open body. |
| Enter / Space | Opens or closes the focused row. |

### ARIA
- Native `<details>` and `<summary>`: the browser exposes it as a disclosure button with its expanded state. Add no roles.
- The summary's text reads as label then value: *Writing format, Feature film*. The icon and chevron are `aria-hidden`.
- Focus shows a 2px `--k-focus` ring 2px out with 6px corners.
- A group of breakdown sections can be named with `aria-label` on the wrapper (*Scene 12 breakdown*).

## For agents

### Rules

- **Must** use native details and summary, with an SVG chevron that turns; never the native triangle or a CSS border chevron.
- **Must** show each row's current value in its closed summary.
- **Never** hide required fields, warnings or anything that blocks saving inside a closed row.
- **Always** let several rows be open at once; opening one never closes another.
- **Never** use an accordion when most people need most of the sections.

### AI readiness test

**Task:** Organise a scene's breakdown sheet by department on a phone.

**Give the agent:** This page, Breakdown page, Phones pattern.

**Constraint:** Most scenes use three or four of fourteen departments.

**A reliable answer:**
- One details row per department with its pencil dot and a count
- Departments with items open
- Empty ones closed with "None marked"
- SVG chevron
- 44px summaries
