# Segmented control

> Two or three mutually exclusive views or modes, all in sight, chosen with one press and moved through with the arrow keys.

Source: https://kwark.space/designSystem/components/segmented-control

## Usage

### What it is
The app’s `Segmented` (`components/ui/Segmented.tsx`, styled by `.k-seg` in `system.css`) shows two or three choices side by side and marks the current one with a raised ground. Its own comment states the limit: *two or three: more than that is a list, not a switch.* It is in the Character module (*Where to look*: Library, My presets, From a character; *Learn this method*: Understand, Watch, Evidence; *Manage pages*) and on calendar dates (*On a date* / *Follows the shoot*).

### When to use
- Switching the view or the source of one panel: what you see changes, nothing is saved.
- A mode with two or three named options inside a form.

### When not to
- Four or more options: [Tabs](https://kwark.space/designSystem/components/tabs.md) for sections of content, a [Select](https://kwark.space/designSystem/components/select.md) for values.
- Steps in a process: progress steps, never segments.
- On or off: a [Switch](https://kwark.space/designSystem/components/switch.md).

### Behaviour
- One press chooses; the panel under it changes at once.
- The arrow keys move the choice *and* the focus (it is a radio group), wrapping at the ends.
- Labels are short words, the same width class: *Library*, *My presets*. If one option is conditional (*Watch* only when there are videos), leave it out rather than disabling it, as the app does.
- On a phone it is the one 40–48px band allowed above the content (Decision 0016), 44px tall, full width.

**Do:** *Library · My presets · From a character*, the current one raised, no shadow.

**Don't:** Five segments that wrap to two lines, or a selected segment lit with a coloured glow.

## Style

### Anatomy

1. **Track**: 2px padding, 1px `--k-line`, 10px corners, `--k-surface`.
2. **Segment**: 30px (44 on a phone or touch), 0 16px, 8px corners, Poppins 500 12px (14px on a phone), `--k-text-2`, no wrapping.
3. **Chosen**: `--k-raise` ground and `--k-text`. No shadow, no border, no colour.
4. **Hover**: the label steps to `--k-text`. **Pressed**: a faint `--k-raise` before release.
5. **Focus**: 2px `--k-focus` ring 2px off the segment.
6. **Phone**: `.kw-segment--fill` stretches the track and shares the width equally.

### Tokens

| Token | Light | Dark |
|---|---|---|
| `--k-raise` | #f1f5f9 | #252525 |
| `--k-surface` | #ffffff | #1a1a1a |
| `--k-line` | #e2e8f0 | rgba(255, 255, 255, .1) |
| `--k-text` | #0f172a | #e3e3e3 |
| `--k-text-2` | #5b6779 | #9ca3af |
| `--k-focus` | #0f172a | #f4f4f5 |
| `--k-radius-card` | 10px |  |
| `--k-tap` | 44px |  |
| `--k-fs-meta` | 12px |  |

## Code

### React

In the Kwark app: `import { Segmented } from '@/components/ui/Segmented'`.

```tsx
<Segmented<'library' | 'mine' | 'copy'> label="Where to look" value={door} onChange={setDoor}
  options={[{ value: 'library', label: 'Library' }, { value: 'mine', label: 'My presets' },
    { value: 'copy', label: 'From a character' }]} />
```

| Prop | Type | Notes |
|---|---|---|
| `value` | `T extends string` | The current option. |
| `options` | `readonly { value: T; label: string }[]` | Two or three. More is a list, not a switch. |
| `label` | `string` | Names the radiogroup. |
| `onChange` | `(value: T) => void` | Called on click and on arrow keys. |

### HTML and CSS

Works anywhere with `kwark.css`.

```html
<div style="display:grid;gap:8px;justify-items:start"><span class="kw-label">Where to look · Character library</span>
<div class="kw-segment" role="radiogroup" aria-label="Where to look"><button type="button" role="radio" aria-checked="true">Library</button><button type="button" role="radio" aria-checked="false" tabindex="-1">My presets</button><button type="button" role="radio" aria-checked="false" tabindex="-1">From a character</button></div></div>
<div style="display:grid;gap:8px;justify-items:start"><span class="kw-label">Learn this method · Character method</span>
<div class="kw-segment" role="radiogroup" aria-label="Learn this method"><button type="button" role="radio" aria-checked="false" tabindex="-1">Understand</button><button type="button" role="radio" aria-checked="true">Watch</button><button type="button" role="radio" aria-checked="false" tabindex="-1">Evidence</button></div></div>
<div style="display:grid;gap:8px;justify-items:start"><span class="kw-label">When · Calendar date</span>
<div class="kw-segment" role="radiogroup" aria-label="When"><button type="button" role="radio" aria-checked="true">On a date</button><button type="button" role="radio" aria-checked="false" tabindex="-1">Follows the shoot</button></div></div>
<div style="display:grid;gap:8px;width:min(100%,375px)"><span class="kw-label">On a phone: full width, 44px</span>
<div class="kw-segment kw-segment--fill" role="radiogroup" aria-label="Manage pages"><button type="button" role="radio" aria-checked="true">Pages</button><button type="button" role="radio" aria-checked="false" tabindex="-1">Order</button><button type="button" role="radio" aria-checked="false" tabindex="-1">Hidden</button></div></div>
```

## Accessibility

### Keyboard (from `Segmented.tsx`)
| Key | Does |
|---|---|
| Tab | Into the group, onto the chosen segment (roving `tabindex`: only it is 0). |
| Right / Down | Next option, chosen and focused; wraps. |
| Left / Up | Previous option; wraps. |
| Home / End | First / last option. |

### Roles and names
- `role="radiogroup"` with an `aria-label` (*Where to look*); each segment is `role="radio"` with `aria-checked`.
- When the control switches between panels of one page, the panel it shows follows it directly in the reading order.
- Chosen is shown by ground and text colour together; screen readers hear *checked*.

## For agents

### Rules

- **Never** put more than three options in a segmented control.
- **Must** show the selected state with surface and text colour, never a glow or shadow.
- **Must** implement arrow keys with roving tabindex, as the shared `Segmented` does.
- **Always** leave out an option that does not apply rather than disabling it.
- **Always** make it 44px tall and full width on a phone.

### AI readiness test

**Task:** Let the Outline switch between cards, list and timeline.

**Give the agent:** Segmented control, Tabs.

**Constraint:** The current view stays visible; it must work on a phone.

**A reliable answer:**
- Shared Segmented with three options
- radiogroup with aria-checked and roving tabindex
- Arrow keys move and choose
- 44px full width on a phone
- Not a dropdown
