# AccordionButton

> Slug: `accordion-button` · Category: Disclosure

## When to use
- A standalone expand/collapse trigger for a custom disclosure region you've built yourself.
- When `Accordion` (data-driven, multi-item) is too rigid — e.g. a single "Show details" toggle inside a card.

## When NOT to use
- For a multi-item disclosure list — use `Accordion` (which composes the same button visuals).
- For a button that opens a popup menu — use `MenuButton`.
- For a navigational link that just changes pages — use `Link`.

## Variants & decision tree
There is one logical role (toggle), with appearance switches:

- **`size`** — `'large'` (default) or `'small'`. Match the surrounding density (e.g. small inside cards, large in page-level disclosures).
- **`monochrome`** — neutral coloring instead of brand accent. Useful over imagery or branded panels.
- **`inverse`** — dark-background styling.
- **`icon`** — chevron SVG; the consumer provides it (e.g. `chevronUpOutlined` / `chevronDownOutlined`).

You manage the `expanded` boolean and the connected region externally (e.g. with `aria-controls` on a wrapping disclosure).

## States
- `expanded` — sets `aria-expanded`. Toggle externally on click.
- `disabled` — pass via the native `disabled` prop.
- Force-state flags (`focused`, `hover`, `pressed`) for visual testing.

## Props
| Prop | Type | Default | Description |
|---|---|---|---|
| `children` | `ReactNode` | — | Button label. Empty string renders nothing. |
| `expanded` | `boolean` | — | Required; sets `aria-expanded`. |
| `size` | `'large' \| 'small'` | `'large'` | Button size. |
| `inverse` | `boolean` | inherited | Dark-background styling. |
| `monochrome` | `boolean` | `false` | Neutral coloring. |
| `icon` | `ReactNode` | — | Chevron icon SVG. |
| `ariaLabel` | `string` | — | Override `aria-label`. |
| `type` | `'button' \| 'submit' \| 'reset'` | — | Native button type. |

## Usage examples
```tsx
const [open, setOpen] = useState(false);

<AccordionButton
  expanded={open}
  icon={open ? <ChevronUpOutlined /> : <ChevronDownOutlined />}
  aria-controls="details-region"
  onClick={() => setOpen((o) => !o)}
>
  {open ? 'Hide details' : 'Show details'}
</AccordionButton>

<div id="details-region" hidden={!open}>…</div>
```

## Composition
Pair with a content region you control. For multi-section disclosure use `Accordion` instead — it composes this button automatically.

## Accessibility
- Always pair with a target region: set `aria-controls` to its `id`.
- `expanded` drives `aria-expanded`; keep it in sync with the visible state.
- Use `aria-label` only when the visible label isn't descriptive enough.

## Do / Don't
- Do change the icon when `expanded` flips (chevron up vs. down).
- Do keep the label stable or paired (e.g. "Show / Hide details").
- Don't nest inside another button or anchor.
- Don't use this component to navigate; use `Link`.
