# Script timeline

> How long the script will run and where the minutes go: scenes in proportion, a dashed target, a ring on the scene you are in. On a phone, a 22px strip.

Source: https://kwark.space/designSystem/components/script-timeline

## Usage

### When to use
Under the screenplay menu, so a writer can steer by length while writing: the estimate, the target they set in Project info, and where each scene sits. On a phone it rests as a 22px strip; turned sideways it opens as a full-screen bay (Decision 0007).

### When not to
- As a video editor's timeline against an arbitrary ruler. The ruler measures the script, and the target is a mark on it, not the whole world (editor.css comment).
- To judge pace. The pace control lets the writer say their film moves faster or slower; Kwark never says a scene is too long.

### Variants
| Variant | Where | Behaviour |
|---|---|---|
| Bar | Desktop, under the menu | Acts, scenes in proportion, ruler in minutes, legend, Pace and Details toggles |
| Strip | Phone upright, 22px | Slide a thumb to scrub; the loupe names the scene; tap opens the bar |
| Bay | Phone sideways | Full-screen bar as a dialog; choosing a scene goes there and folds it away; Escape closes |

### The marks
- **Ring** (2px project colour) and the small triangle above: the scene the caret is in (Decision 0041). No glow, no brightness filter, no particles.
- **Dashed line**: the target. Its label says the minutes.
- **Fill**: talk is the project colour mixed into the surface; action is slate. Both is half and half.

### Writing
Say time the way a person says it: *Runs about 1 h 44 min*, *6 min over the 98 min you set*. Scene lengths read as a clock: 4:40.

**Do:** *6 min over the 98 min you set*, in grey, with the dashed target on the track.

**Don't:** A red bar, a warning icon, or *Your script is too long*.

## Style

### Anatomy

Bar: 10/14px padding, reading in 15px Poppins 600, track 34px with 7px tick pattern, scenes inset 3px with 5px corners, acts row 22px, ruler 16px. Strip: 22px track, 6px scene bar at 8px from the top, 2px × 14px *here* mark, dashed target.

### Tokens

| Token | Light | Dark |
|---|---|---|
| `--k-accent` | #98633f | #98633f |
| `--k-tl-slate` | #64748b |  |
| `--k-surface` | #ffffff | #1a1a1a |
| `--k-inset` | #f1f5f9 | #141414 |
| `--k-line` | #e2e8f0 | rgba(255, 255, 255, .1) |
| `--k-text-2` | #5b6779 | #9ca3af |

## Code

### React

In the Kwark app: `import { TimelineBar } from '@/pages/Understanding/EditorModule/components/timeline/TimelineBar'`.

```tsx
<TimelineBar scenes={scenes} targetDuration={project.runtime} activeIndex={caretScene}
  onSelectScene={goToScene} onSelectPos={goToPos} projectId={project.id}
  targets={targets} onChangeTargets={canEdit ? saveTargets : undefined} />
```

| Prop | Type | Notes |
|---|---|---|
| `scenes` | `TimelineScene[]` | title, duration, start, type ACTION | DIALOGUE | BALANCED |
| `targetDuration` | `number` | minutes; 0 when none is set |
| `activeIndex` | `number \| null` | the scene the caret is in |
| `targets` | `TimelineTarget[]` | the writer's own aims, "55:00" or "p.55" |
| `onChangeTargets` | `(t) => void` | absent for people who cannot edit |

### HTML and CSS

Works anywhere with `kwark.css`.

```html
<section class="kw-timeline" aria-label="Estimated runtime">
  <div class="kw-timeline__head">
    <div class="kw-timeline__reading"><span class="kw-meta">Runs about</span><strong>1 h 44 min</strong><span class="kw-meta">6 min over the 98 min you set</span></div>
    <button class="kw-pill-toggle" type="button" aria-pressed="false">Pace</button>
  </div>
  <div class="kw-timeline__acts" aria-label="Acts"><span style="left:0;width:30%"><b>Act 1</b><small>31 min</small></span><span style="left:30%;width:50%"><b>Act 2</b><small>52 min</small></span><span style="left:80%;width:20%"><b>Act 3</b><small>21 min</small></span></div>
  <div class="kw-timeline__track">
    <button class="kw-timeline__scene" type="button" data-kind="action" style="left:0;width:14%" aria-label="Scene 1, Blank pages, about 4 min 10 sec, mostly action"><span>Blank pages</span><span>4:10</span></button>
    <button class="kw-timeline__scene" type="button" data-kind="dialogue" style="left:14%;width:16%" aria-label="Scene 2, The job, about 6 min, mostly dialogue"><span>The job</span><span>6:02</span></button>
    <button class="kw-timeline__scene" type="button" data-kind="balanced" style="left:30%;width:22%" aria-current="true" aria-label="Scene 12, Edit suite, about 4 min 40 sec, dialogue and action, you are here"><span>Edit suite</span><span>4:40</span></button>
    <button class="kw-timeline__scene" type="button" data-kind="dialogue" style="left:52%;width:28%" aria-label="Scene 13, Rooftop, about 8 min, mostly dialogue"><span>Rooftop</span><span>8:15</span></button>
    <button class="kw-timeline__scene" type="button" data-kind="action" style="left:80%;width:20%" aria-label="Scene 14, Rain, about 5 min, mostly action"><span>Rain</span><span>5:00</span></button>
    <span class="kw-timeline__target" style="left:94%"><small>98 min</small></span>
  </div>
  <div class="kw-timeline__ruler" aria-hidden="true"><span style="left:0">0</span><span style="left:29%">30</span><span style="left:58%">60</span><span style="left:87%">90</span></div>
  <div class="kw-timeline__legend"><span class="kw-key" data-kind="dialogue">Mostly dialogue</span><span class="kw-key" data-kind="action">Mostly action</span><span class="kw-key" data-kind="balanced">Both</span></div>
</section>
<div class="kw-tl-strip" aria-label="Estimated runtime, phone strip">
  <div class="kw-tl-strip__track" role="slider" tabindex="0" aria-label="Runs about 1 h 44 min. Slide to find a scene, or tap for the full timeline." aria-valuemin="0" aria-valuemax="104" aria-valuenow="38" aria-valuetext="Scene 12, Edit suite">
    <i data-kind="action" style="left:0;width:14%"></i><i data-kind="dialogue" style="left:14%;width:16%"></i><i data-kind="dialogue" style="left:30%;width:22%"></i><i data-kind="dialogue" style="left:52%;width:28%"></i><i data-kind="action" style="left:80%;width:20%"></i>
    <span class="kw-tl-strip__here" style="left:37%"></span><span class="kw-tl-strip__target" style="left:94%"></span>
  </div>
</div>
```

## Accessibility

- The bar is `<section aria-label="Estimated runtime">`; each scene is a button named with number, title, spoken length and kind.
- The current scene has `aria-current="true"`.
- The strip is a slider: arrow keys move scene by scene, Enter opens the bar, and `aria-valuetext` names the scene.
- The bay is a modal dialog with Escape to close.
- Kind is never colour alone: the legend and each name say it in words.

## For agents

### Rules

- **Must** measure the ruler by the script's own length, with the target as a mark.
- **Never** use glow, filters or particles to mark the current scene; use the 2px ring and the pointer.
- **Must** use the 22px strip on upright phones and the full-screen bay sideways (Decision 0007).
- **Never** judge length; state it, and the gap to the writer's own target, in grey.

### AI readiness test

**Task:** Show the runtime estimate in a read-only reader view for a producer.

**Give the agent:** Script timeline, Sharing by film role, Decision 0007.

**Constraint:** The producer cannot change targets.

**A reliable answer:**
- TimelineBar without onChangeTargets
- Targets visible, not editable
- Strip on phone, bay sideways
- Scenes named with spoken length
- No judgement copy
