# Switch

> Turns a setting on or off the moment it is pressed. In Kwark it lives in a settings row with a title, what it does, and whether it is for this project or all your scripts.

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

## Usage

### What it is
A switch changes a setting at once. Kwark’s is the editor’s `.ui-switch` (`EditorModule/styles/editor.css`), used in Settings as a `<button role="switch">` (`SettingsModal.tsx`). It rarely stands alone: it sits at the end of a **settings row** that says what the setting is, what it does in a sentence, and where it applies, with a small scope tag: *This project* (tinted with the project’s accent) or *All your scripts*.

### When to use
- Settings that apply immediately and can be switched back: *Character colours*, *Timeline*, *Check spelling*, *Suggest names*.

### When not to
- A choice that is saved with a form: a [Checkbox](https://kwark.space/designSystem/components/checkbox-and-radio.md).
- A choice of two named options (*A4 / US Letter*): radios or a [Segmented control](https://kwark.space/designSystem/components/segmented-control.md).
- Anything that cannot be undone by switching back.

### Rules from Kwark
- **Applies at once.** No Save button anywhere near a switch.
- **Off by default if it interrupts the writer.** Kwark is a safe, quiet place (Decision 0001): anything that pops up, sounds or nags starts off.
- **Dependent settings explain themselves.** When a setting depends on another, it stays visible, dimmed, with the reason in words: *Turn on Map the outline onto the script first.* Structure is optional (Decision 0003): the dependent setting never forces the outline on.
- **The title names the setting, not the action**: *Timeline*, not *Show the timeline*.

**Do:** *Timeline · This project* — *The film’s running time above the page, scene by scene.* — and a switch.

**Don't:** *Enable timeline?* with a switch and a Save button under the list.

## Style

### Anatomy

### Switch
1. **Track**: 38 × 22px (large, `.ui-switch--lg`) or 28 × 16px (small), 99px corners. Off: `--k-text-2` at 38% with a 1px inset `--k-line`. On: the accent tint (`--k-accent-soft`; the app uses the project’s accent).
2. **Thumb**: 18px (12px small), `--k-on-switch`, 2px in; slides 16px (12px) in 200ms with `--k-ease`.
3. **Hover**: a 1px `--k-line-strong` inset. **Disabled**: 45–55% with the reason in the row.

### Settings row (`.settings-row`)
1. Text on the left, the switch on the right, 24px apart (12px on a phone); 16px above and below; a 1px line at 70% between rows.
2. **Title**: 600 13px (`--k-fs-detail`) with the scope tag after it.
3. **Scope tag**: 11px 600 pill; *This project* in a 14% accent wash, *All your scripts* on `--k-raise`.
4. **Detail**: 12px `--k-text-2`, up to 58 characters a line.

A bare switch with a label (`.kw-switch`, the last example) is for a single setting inside a panel.

### Tokens

| Token | Light | Dark |
|---|---|---|
| `--k-accent` | #98633f | #98633f |
| `--k-accent-soft` | #e8b58b | #e8b58b |
| `--k-on-switch` | #ffffff |  |
| `--k-text-2` | #5b6779 | #9ca3af |
| `--k-line` | #e2e8f0 | rgba(255, 255, 255, .1) |
| `--k-line-strong` | var(--k-text-2) | var(--k-text-2) |
| `--k-raise` | #f1f5f9 | #252525 |
| `--k-text` | #0f172a | #e3e3e3 |
| `--k-dur-2` | 200ms |  |
| `--k-ease` | cubic-bezier(.2, .7, .2, 1) |  |
| `--k-fs-detail` | 13px |  |

## 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-settings">
  <div class="kw-setting"><div class="kw-setting__text"><strong>Character colours <span class="kw-setting__scope kw-setting__scope--project">This project</span></strong><p>Each voice in its colour — the one it has in the cast list, the breakdown and the shot list.</p></div><button class="kw-switch-btn" type="button" role="switch" aria-checked="true" aria-label="Character colours"></button></div>
  <div class="kw-setting"><div class="kw-setting__text"><strong>Timeline <span class="kw-setting__scope kw-setting__scope--project">This project</span></strong><p>The film’s running time above the page, scene by scene.</p></div><button class="kw-switch-btn" type="button" role="switch" aria-checked="false" aria-label="Timeline"></button></div>
  <div class="kw-setting"><div class="kw-setting__text"><strong>Check spelling <span class="kw-setting__scope">All your scripts</span></strong><p>The browser’s own spelling check, underlined on the page.</p></div><button class="kw-switch-btn" type="button" role="switch" aria-checked="true" aria-label="Check spelling"></button></div>
  <div class="kw-setting is-disabled"><div class="kw-setting__text"><strong>What the page shows <span class="kw-setting__scope kw-setting__scope--project">This project</span></strong><p>Acts, sequences or beats from the outline, in the margin.<span class="kw-setting__why">Turn on Map the outline onto the script first.</span></p></div><button class="kw-switch-btn" type="button" role="switch" aria-checked="false" aria-label="What the page shows" disabled></button></div>
</div>
<label class="kw-switch"><input type="checkbox" role="switch"><span class="kw-track"></span>Typewriter sound</label>
```

### In the app
The settings switch is not exported from `components/ui`; it is the `Switch` inside `SettingsModal.tsx`:

```tsx
<button type="button" role="switch" aria-checked={checked} aria-label={label}
  disabled={disabled} className={`ui-switch ui-switch--lg${checked ? ' is-on' : ''}`} onClick={onChange}><i /></button>
```

Use the same markup (or `.kw-switch-btn` with `kwark.css`) until a shared component exists. Do not create a second switch style.

## Accessibility

### Keyboard
| Key | Does |
|---|---|
| Tab | Moves to the switch. |
| Space / Enter | Toggles it; the change applies immediately. |

### Roles and names
- `role="switch"` with `aria-checked`, so it is announced *Character colours, switch, on*.
- Name it with the row’s title; the detail sentence can be tied with `aria-describedby`.
- State is carried by the thumb’s position as well as colour.
- A disabled switch keeps its reason as visible text; when the reason matters to reach it, use `aria-disabled` so it stays focusable.
- The thumb’s slide stops under `prefers-reduced-motion`.

## For agents

### Rules

- **Must** take effect immediately; never pair a switch with a Save button.
- **Always** default anything that interrupts the writer to off.
- **Must** say in the row whether a setting applies to this project or all your scripts.
- **Always** keep a dependent setting visible with its reason in words when it is unavailable.
- **Never** create a second switch style; use `.ui-switch` / `.kw-switch-btn`.

### AI readiness test

**Task:** Add a setting for the typewriter sound in the editor’s Settings.

**Give the agent:** Switch, Principles, Decision 0001.

**Constraint:** Applies immediately, to all your scripts.

**A reliable answer:**
- A settings row titled Typewriter sound with one sentence of detail
- Scope tag All your scripts
- role="switch" with aria-checked
- Default off
- No Save button
