# Spinner

> The three quarks of the Kwark mark taking turns, for work whose length cannot be measured. Nothing for the first 0.4 seconds, and always with words.

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

## Usage

### What it is
A small mark that says *working* when nobody can say for how long: waiting for a server, preparing a preview, checking an address. If the amount is known (*48 of 112 pages*), use [progress](https://kwark.space/designSystem/components/progress.md) instead.

### The Kwark idea: it is the mark
Kwark's logo is three quarks: a large one, a middle one and a small one, set off-centre (`public/img/kwark_logo.svg`). The spinner is the same three circles at the same positions and sizes, lit one after another, like a light passing between them. Nothing rotates. Nothing glows. It is quiet enough to sit inside a button, and recognisable enough that the 40px version can stand in for the page loader's mark. The first quark takes `--k-accent-soft` in the brand form, as the coral quark does in the logo.

### Timing
| Wait | Show |
|---|---|
| Under 0.4 seconds | Nothing. The spinner fades in after 0.4s, so a quick answer never flickers. |
| 0.4 to about 4 seconds | Spinner and words: *Preparing the print preview*. |
| Longer, or measurable | [Progress](https://kwark.space/designSystem/components/progress.md) with figures, and a Cancel if stopping is safe. |
| Opening a page | The [page loader](https://kwark.space/designSystem/components/cinematic-loader.md): the page's own ground, the mark after 0.4s (Decision 0012). |

### When not to use
- To block the screenplay while something else loads. Never.
- Where the shape of the content is known: a [skeleton](https://kwark.space/designSystem/components/skeleton.md) holds its place.
- As decoration or a brand moment: there is no idle animation in Kwark.

### Writing
Say what is happening, as an *-ing* verb and its object: *Issuing Rev 3*, *Checking the address*, *Opening Blank Pages*. Never *Loading…* or *Please wait*.

## Style

### Anatomy

1. **Mark**: an SVG on an 80-unit grid with the logo's circles: (24, 22) r14, (58, 40) r11, (38, 64) r10, filled with `currentColor`.
2. **Sizes**: 14 (`--sm`, inside buttons), 16 (default, inline), 24 (`--md`, panels), 40px (`--lg`, the page).
3. **Cycle**: 1.2s. Each quark rises from 22% to full opacity and falls, 0.2s after the one before, in logo order (large, middle, small).
4. **Brand form** (`--brand`): the first quark in `--k-accent-soft`.
5. **With words** (`kw-busy`): 8px gap, Poppins 500 12px `--k-text-2`; fades in over `--k-dur-2` after a 0.4s delay. `kw-busy--now` skips the delay where it follows a press (inside a button).
6. **Block**: centred in a dashed 1px `--k-line` frame at least 160px tall, for a panel whose content is coming.
7. **Reduced motion**: the quarks stand still at full, 60% and 35%; the words carry the state.

### Tokens

| Token | Light | Dark |
|---|---|---|
| `--k-text` | #0f172a | #e3e3e3 |
| `--k-text-2` | #5b6779 | #9ca3af |
| `--k-accent-soft` | #e8b58b | #e8b58b |
| `--k-line` | #e2e8f0 | rgba(255, 255, 255, .1) |
| `--k-icon-sm` | 14px |  |
| `--k-icon-md` | 16px |  |
| `--k-radius-card` | 10px |  |
| `--k-fs-meta` | 12px |  |
| `--k-dur-2` | 200ms |  |
| `--k-ease` | cubic-bezier(.2, .7, .2, 1) |  |
| `--k-ease-in-out` | cubic-bezier(.65, 0, .35, 1) |  |

## 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 style="display:flex;flex-wrap:wrap;gap:32px;align-items:center">
  <span class="kw-busy kw-busy--now" role="status" style="color:var(--k-text)"><svg class="kw-quarks kw-quarks--sm" viewBox="0 0 80 80" aria-hidden="true"><circle cx="24" cy="22" r="14"/><circle cx="58" cy="40" r="11"/><circle cx="38" cy="64" r="10"/></svg><span>14 in a button</span></span>
  <span class="kw-busy kw-busy--now" style="color:var(--k-text)"><svg class="kw-quarks" viewBox="0 0 80 80" aria-hidden="true"><circle cx="24" cy="22" r="14"/><circle cx="58" cy="40" r="11"/><circle cx="38" cy="64" r="10"/></svg><span>16 inline</span></span>
  <span class="kw-busy kw-busy--now" style="color:var(--k-text)"><svg class="kw-quarks kw-quarks--md" viewBox="0 0 80 80" aria-hidden="true"><circle cx="24" cy="22" r="14"/><circle cx="58" cy="40" r="11"/><circle cx="38" cy="64" r="10"/></svg><span>24 in a panel</span></span>
  <span class="kw-busy kw-busy--now" style="color:var(--k-text)"><svg class="kw-quarks kw-quarks--lg kw-quarks--brand" viewBox="0 0 80 80" aria-hidden="true"><circle cx="24" cy="22" r="14"/><circle cx="58" cy="40" r="11"/><circle cx="38" cy="64" r="10"/></svg><span>40, the mark</span></span>
</div>
<div style="display:flex;flex-wrap:wrap;gap:12px;align-items:center">
  <button class="kw-button kw-button--primary" type="button" aria-busy="true" aria-disabled="true"><svg class="kw-quarks kw-quarks--sm" viewBox="0 0 80 80" aria-hidden="true"><circle cx="24" cy="22" r="14"/><circle cx="58" cy="40" r="11"/><circle cx="38" cy="64" r="10"/></svg>Issuing Rev 3</button>
  <button class="kw-button" type="button" aria-busy="true" aria-disabled="true"><svg class="kw-quarks kw-quarks--sm" viewBox="0 0 80 80" aria-hidden="true"><circle cx="24" cy="22" r="14"/><circle cx="58" cy="40" r="11"/><circle cx="38" cy="64" r="10"/></svg>Checking the address</button>
  <span class="kw-busy" role="status"><svg class="kw-quarks" viewBox="0 0 80 80" aria-hidden="true"><circle cx="24" cy="22" r="14"/><circle cx="58" cy="40" r="11"/><circle cx="38" cy="64" r="10"/></svg>Preparing the print preview<button class="kw-text-button" type="button">Cancel</button></span>
</div>
<div class="kw-busy kw-busy--block" role="status"><svg class="kw-quarks kw-quarks--lg kw-quarks--brand" viewBox="0 0 80 80" aria-hidden="true"><circle cx="24" cy="22" r="14"/><circle cx="58" cy="40" r="11"/><circle cx="38" cy="64" r="10"/></svg><span>Opening Blank Pages</span></div>
```

## Accessibility

### ARIA
- The SVG is `aria-hidden="true"`. The words, or a visually hidden label, are in `role="status"`: *Preparing the print preview*.
- In a button: keep the button's label as the *-ing* form, set `aria-busy="true"` and `aria-disabled="true"`, and keep its width.
- Announce the end once: *Print preview ready*.

### Motion
- Only opacity changes; nothing spins, so there is no vestibular trigger.
- Under `prefers-reduced-motion` the animation stops and the mark holds one frame.
- Offer **Cancel** beside it whenever stopping is safe.

## For agents

### Rules

- **Must** show nothing for the first 0.4 seconds of a wait.
- **Must** say what is happening in words beside or inside the spinner; never a mark alone.
- **Never** use a rotating ring, a glow or a gradient; the spinner is the three quarks taking turns.
- **Never** block the screenplay with a spinner, and use progress instead when the amount is known.
- **Always** stop the animation under prefers-reduced-motion and keep the words.

### AI readiness test

**Task:** Show that Kwark is checking whether a location address can be found on the map.

**Give the agent:** This page, Progress, Loading pattern.

**Constraint:** Usually under a second, sometimes ten.

**A reliable answer:**
- Nothing for 0.4s
- Then the quark spinner with "Checking the address"
- A Cancel after a few seconds
- role="status" announces the result once
- No ring, no glow
