# Select

> Pick one value from four to fifteen, with the phone’s own picker. A native select in Kwark’s box, with a drawn chevron and every state.

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

## Usage

### What it is
The app’s `Select` (`components/ui/Select.tsx`) is a native `<select>` with its own box and a 14px `ChevronDown` drawn over it. The native element is the point: on a phone it opens the system wheel or sheet, which is better than anything drawn in a page, and keyboard and screen reader support come free.

### Choosing the control
| Options | Use |
|---|---|
| 2–3, worth seeing at once | [Segmented control](https://kwark.space/designSystem/components/segmented-control.md) or radios |
| 4–15 | **Select** |
| More, or answers people type | [Combobox](https://kwark.space/designSystem/components/combobox.md) |
| Several at once | [Multiselect](https://kwark.space/designSystem/components/multiselect.md) |

### Kwark examples
- *Time of day* for a scene heading: Day, Night, Dawn, Dusk, Continuous, in that order (how scene headings are written), not alphabetical.
- *What it follows* on a calendar date: option groups (*Shoot*, *Post*) keep a long list scannable.
- *Paper*: A4 or US Letter. In a form it is a select; in Settings it is a radio pair with each paper’s line count.

### Behaviour
- Changing the value applies when the form is saved, unless the select sits in a settings row that applies at once (then say so).
- A select that must be chosen starts on a prompt option (*Choose a location*) that is not a valid value; the error says what it blocks.
- Disabled selects say why next to them. If someone cannot change it, prefer showing the value as text.

**Do:** *Time of day* · *Night* with a drawn chevron, and the phone’s own picker when tapped.

**Don't:** A div-built dropdown that cannot be opened from the keyboard and scrolls inside a tiny box on a phone.

## Style

### Anatomy

1. **Box**: the [Text input](https://kwark.space/designSystem/components/text-input.md) box: 36px, 1px `--k-line`, 6px corners, 7px 10px padding, 34px kept on the right. The app’s component uses 12px padding and 8px corners (`p-3 rounded-lg`); the system box is the target.
2. **Chevron**: 14px, stroke 2, `--k-text-2`, 12px from the right, `pointer-events: none` so the click reaches the select.
3. **Label**: 500 12px `--k-text`, sentence case. The app’s label is still upper case with wide tracking; move it to `.kw-label` when touched (Rule 3 bans all-caps labels).
4. **Option groups**: `<optgroup>` with sentence-case names.

### States
| State | Look |
|---|---|
| Hover | Edge steps to `--k-line-strong`. |
| Focus | Edge `--k-accent-soft`, 2px ring 2px off. |
| Error | `aria-invalid="true"`: `--k-danger` edge; message under it with an alert glyph. |
| Disabled | 50% opacity, chevron too, `not-allowed` cursor, reason as a hint. |
| Phone | 16px text so iOS does not zoom; 44px tall. |

### Tokens

| Token | Light | Dark |
|---|---|---|
| `--k-surface` | #ffffff | #1a1a1a |
| `--k-bg` | #f8fafc | #191919 |
| `--k-line` | #e2e8f0 | rgba(255, 255, 255, .1) |
| `--k-line-strong` | var(--k-text-2) | var(--k-text-2) |
| `--k-text` | #0f172a | #e3e3e3 |
| `--k-text-2` | #5b6779 | #9ca3af |
| `--k-accent-soft` | #e8b58b | #e8b58b |
| `--k-danger` | #b4382c | #e0685c |
| `--k-control-md` | 36px |  |
| `--k-radius-control` | 6px |  |

## Code

### React

In the Kwark app: `import Select from '@/components/ui/Select'`.

```tsx
<Select label="Time of day" value={tod} onChange={setTod}
  options={[{ value: 'DAY', label: 'Day' }, { value: 'NIGHT', label: 'Night' },
    { value: 'DAWN', label: 'Dawn' }, { value: 'DUSK', label: 'Dusk' }, { value: 'CONTINUOUS', label: 'Continuous' }]} />
```

| Prop | Type | Notes |
|---|---|---|
| `label` | `string` | Visible label, tied to the select by id. |
| `options` | `{ value: string; label: string }[]` | In the order people expect, not alphabetical by default. |
| `value` | `string` | The current value. |
| `onChange` | `(value: string) => void` | Receives the value, not the event. |
| `...rest` | `SelectHTMLAttributes` | `disabled`, `aria-invalid`, `aria-describedby` pass through. |

### HTML and CSS

Works anywhere with `kwark.css`.

```html
<div class="kw-specimen-row">
  <label class="kw-field"><span class="kw-label">Time of day</span><span class="kw-select-wrap"><select class="kw-select"><option>Day</option><option selected>Night</option><option>Dawn</option><option>Dusk</option><option>Continuous</option></select><svg 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></span><span class="kw-hint">Prints in Scene 12’s heading.</span></label>
  <label class="kw-field"><span class="kw-label">What it follows</span><span class="kw-select-wrap"><select class="kw-select"><optgroup label="Shoot"><option>First shooting day</option><option selected>Last shooting day</option></optgroup><optgroup label="Post"><option>Picture lock</option><option>Final mix</option></optgroup></select><svg 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></span></label>
</div>
<div class="kw-specimen-row">
  <label class="kw-field"><span class="kw-label">Location for Day 7</span><span class="kw-select-wrap"><select class="kw-select" aria-invalid="true"><option selected>Choose a location</option><option>Lumen Studios</option><option>Street outside the lab</option></select><svg 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></span><span class="kw-error" role="alert"><svg viewBox="0 0 24 24" fill="none" stroke="currentColor" stroke-width="1.75" stroke-linecap="round" stroke-linejoin="round" aria-hidden="true"><circle cx="12" cy="12" r="10"/><path d="M12 8v4M12 16h.01"/></svg>Choose a location before issuing the call sheet.</span></label>
  <label class="kw-field"><span class="kw-label">Paper</span><span class="kw-select-wrap"><select class="kw-select" disabled><option selected>A4</option><option>US Letter</option></select><svg 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></span><span class="kw-hint">Set by the production for every script.</span></label>
</div>
```

## Accessibility

### Keyboard
Native: Tab to focus; Space or Alt + Down opens; arrows move; typing jumps to an option; Enter chooses; Escape closes.

### Rules
- The visible label is a real `<label>` (the component ties it with `useId`).
- Errors and hints are tied with `aria-describedby`.
- The chevron is `aria-hidden`.
- Never rebuild a select from divs to get a custom look; style the box and leave the list to the platform.

## For agents

### Rules

- **Must** use the native `<select>` through the shared `Select` for single choices from four to fifteen options.
- **Never** use a select for three or fewer options; show them with a segmented control or radios.
- **Always** order options the way people say them (Day, Night, Dawn, Dusk), not alphabetically by default.
- **Must** draw the chevron as a 14px SVG that ignores pointer events; never type ▾ or ⌄.
- **Always** say why a select is disabled, next to it.

### AI readiness test

**Task:** Let a person choose a scene’s time of day in the scene heading editor.

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

**Constraint:** Values are Day, Night, Dawn, Dusk, Continuous.

**A reliable answer:**
- Uses the shared Select (five options)
- Visible sentence-case label
- Options in scene-heading order
- Native element with drawn chevron
