# Progress steps

> The steps of one piece of work, in order, each with what it already holds: Shots, Blocking, Storyboard, Animatic.

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

## Usage

### What it is
A short ordered sequence where each step is a place you can go, not a gate. In the shot module the four steps are **Shots · Blocking · Storyboard · Animatic** (`ShotWorkflow`), and under each name a count says what is already there: *6 shots*, *3 setups · optional*, *4/6 frames*, *ready to play*. The *Copy for AI* dialog uses the same idea for its handoff: *01 Prepare*, *02 Copy*.

### When to use
- Work that has a natural order and where later steps draw on earlier ones.
- Two to five steps.

### When not to use
- Choosing a view of the same thing: that is a [Segmented control](https://kwark.space/designSystem/components/segmented-control.md) or [Tabs](https://kwark.space/designSystem/components/tabs.md).
- To force an order a writer does not need. Blocking is marked *optional* because it is (Decision 0003, structure is optional).
- To show completeness as a score. Counts say what exists, never how good it is (Decision 0002).

### States
| Variant | Use for |
|---|---|
| Current | Tinted, `aria-current="step"` |
| Available | Plain; press to go there |
| Not yet | Disabled at 38% opacity, with a `title` that says what unlocks it: *Create shots first* |

### Writing
- Step names are nouns for the artefact: *Storyboard*, not *Draw boards*.
- The count line is a fact: *4/6 frames*, *after shots*. No percentages, no *Complete!*.

## Style

### Anatomy

1. **Track**: 3px padding, 1px `--k-line`, 8px corners, 2px between steps.
2. **Step**: at least 40px tall, 4px 12px 4px 5px padding, 10px corners, number circle then name and count.
3. **Number**: 24px circle, 1px `--k-line`, 12px. The workbench hides it where space is short (`.sb-steps i`); the order still reads left to right.
4. **Name**: 12px Poppins 600, `--k-text`. **Count**: 12px, `--k-text-2`.
5. **Current**: background `color-mix(--k-accent 14%, transparent)`, name in `--k-accent-soft`.

### Tokens

| Token | Light | Dark |
|---|---|---|
| `--k-surface` | #ffffff | #1a1a1a |
| `--k-raise` | #f1f5f9 | #252525 |
| `--k-line` | #e2e8f0 | rgba(255, 255, 255, .1) |
| `--k-text` | #0f172a | #e3e3e3 |
| `--k-text-2` | #5b6779 | #9ca3af |
| `--k-accent` | #98633f | #98633f |
| `--k-accent-soft` | #e8b58b | #e8b58b |
| `--k-radius-card` | 10px |  |
| `--k-radius-control` | 6px |  |
| `--k-fs-meta` | 12px |  |

## Code

### React

In the Kwark app: `import { ShotWorkflow } from '@/pages/PreProduction/ShotListModule/ShotWorkflow'`.

```tsx
<ShotWorkflow shots={shots} setups={setups} mode={mode} onMode={setMode} />
```

| Prop | Type | Notes |
|---|---|---|
| `shots` | `Shot[]` | counts and availability come from the shots |
| `setups` | `number` | shown under Blocking |
| `mode` | `'page' \| 'plan' \| 'boards' \| 'play'` | the current step |
| `onMode` | `(mode) => void` |  |

### HTML and CSS

Works anywhere with `kwark.css`.

```html
<nav class="kw-steps" aria-label="Work on this scene">
  <button type="button" aria-current="step"><i>1</i><span><b>Shots</b><small>6 shots</small></span></button>
  <button type="button"><i>2</i><span><b>Blocking</b><small>3 setups · optional</small></span></button>
  <button type="button"><i>3</i><span><b>Storyboard</b><small>4/6 frames</small></span></button>
  <button type="button" disabled title="Keep a storyboard frame for each shot to make an animatic"><i>4</i><span><b>Animatic</b><small>after storyboard</small></span></button>
</nav>
```

## Accessibility

### Keyboard
| Key | Does |
|---|---|
| Tab | Moves through available steps; disabled steps are skipped. |
| Enter / Space | Goes to the step. |

### ARIA
- `<nav aria-label="Work on this scene">` with buttons; the current one carries `aria-current="step"`.
- A disabled step keeps its reason in `title` and should repeat it in visible text nearby on touch screens, where there is no hover.

## For agents

### Rules

- **Must** show under each step what it already holds, as a count, never a score or a percentage of quality.
- **Must** mark an optional step *optional* and let people skip it (Decision 0003).
- **Always** say what unlocks a disabled step.
- **Never** use a stepper to switch views of the same content.

### AI readiness test

**Task:** Add progress steps to the call sheet flow: Draft, Review, Issue.

**Give the agent:** This page, Decision 0020 (numbered revisions).

**Constraint:** A call sheet can be issued again as Rev 2.

**A reliable answer:**
- Uses three steps with counts or facts (e.g. "Rev 1 issued 16 Nov")
- Lets Review be skipped
- Says what unlocks Issue
- Keeps aria-current="step"
