# Data visualisation

> The charts Kwark draws (the timeline, the story spine, the stripboard, the calendar, Dailies, the budget's top sheet), the colours they use and in what order, labels over legends, accessible alternatives, and the one chart Kwark never draws: a score for the writing.

Source: https://kwark.space/designSystem/foundations/data-visualization

## What Kwark charts, and why

A chart in Kwark exists for one reason: to let a filmmaker **see** their own work or their own production so they can decide something. Indie shoots are short, so every scene shows its estimated runtime and the timeline shows talk against action. A crew needs to know which day is which, so the stripboard is coloured the way stripboards have always been coloured.

Every chart answers principle 6: **does it measure the work, or evaluate it?** Only the first is allowed. A chart shows quantities and positions. It never shows a verdict, a target zone that turns green, or a comparison with other writers.

| Chart | Where | What it shows | Component |
|---|---|---|---|
| Timeline | Under the screenplay; phone strip and sideways bay (Decision 0007) | Each scene's estimated length, coloured by talk or action; acts; targets; the current scene | [Script timeline](https://kwark.space/designSystem/components/script-timeline.md) |
| Talk and action | Timeline card | One stacked bar: share of screen time that is dialogue against action | Part of the timeline |
| By act | Timeline card | A row per act: its length and share of the whole | Part of the timeline |
| Story spine | Outline, structure view (Decision 0031) | One band per section at its planned share, a segment per part, a dot per beat | [Outline board](https://kwark.space/designSystem/components/outline-board.md) |
| Stripboard | Schedule | One strip per scene, coloured INT/EXT and DAY/NIGHT | [Stripboard strip](https://kwark.space/designSystem/components/stripboard-strip.md) |
| Day planner | Schedule | A day from crew call to wrap, as blocks | [Production timeline](https://kwark.space/designSystem/components/production-timeline.md) |
| Calendar | Project calendar (Decision 0043) | Seven categories of work across days and hours | [Production calendar](https://kwark.space/designSystem/components/production-calendar.md) |
| Dailies | A person's own record (Decision 0043, Dailies) | Week film strips with up to three quiet bands per day; a year contact sheet | [Dailies frame](https://kwark.space/designSystem/components/dailies-frame.md) |
| Budget | Budget's top sheet | Sections, contingency, tax and total, as a table | [Budget top sheet](https://kwark.space/designSystem/components/budget-top-sheet.md) |

Generic charts for anything else (a bar, line, area, donut, heatmap or sparkline) are in the components: [bar chart](https://kwark.space/designSystem/components/bar-chart.md), [line chart](https://kwark.space/designSystem/components/line-chart.md), [area chart](https://kwark.space/designSystem/components/area-chart.md), [donut chart](https://kwark.space/designSystem/components/donut-chart.md), [heatmap](https://kwark.space/designSystem/components/heatmap.md), [sparkline](https://kwark.space/designSystem/components/sparkline.md), [data table](https://kwark.space/designSystem/components/data-table.md), [Gantt chart](https://kwark.space/designSystem/components/gantt-chart.md). They follow every rule on this page.

## The timeline, in detail

The specimen above is the desktop timeline. Its rules are the model for every chart in Kwark:

- **One reading, in words, first.** *Runs about 1 h 42 min*. The chart illustrates the sentence; it does not replace it.
- **Every mark means one thing.** A block is a scene; its width is its estimated screen time; its colour is what fills it (mostly dialogue, mostly action, or both, drawn half and half). A scene too narrow to label still keeps its number for screen readers.
- **The current scene** is a 2px ring in the project's colour with a pointer above it. No glow, brightness filter or particles (Decision 0041).
- **Targets** are dashed lines the writer set, labelled with their own words (*Act 2 break · aim 55 min*). They are the writer's aims, not Kwark's.
- **The ruler** marks minutes often enough to read and never crowded: every 1, 2, 5, 10, 15, 30 or 60 minutes, whichever gives twelve or fewer marks.
- **Talk and action** is a measure. *Talk 62% · Action 38%*, headed *in screen time, headings and transitions left out*. There is no "good" range, no colour for too much talk, no genre norm.
- **The colours follow the room.** Talk and action come from the room's pair (see [Writing rooms](https://kwark.space/designSystem/foundations/rooms.md#timeline-marks)), and each block's fill is pulled toward the page until its number reads.

On a phone the timeline rests as a 22px strip under the menu: slide a thumb to scrub, with a loupe that names the scene (*Scene 12. INT. EDIT SUITE – NIGHT · 26:40 of 102:00 · 2:40 long*: the clock counts minutes and seconds); tap to open; turn the phone sideways for the full bay (Decision 0007).

## The story spine

Above the outline's rows, the story spine shows the story at a glance (Decision 0031). Writers never see the word *spine*: the strip is announced as *The story at a glance*.

```html
<div class="kw-spine" style="max-width:560px"><ul class="kw-spine__strip" aria-label="The story at a glance"><li style="flex-grow:25"><button class="kw-spine__act" type="button" style="--kw-act:var(--k-cal-writing)"><span class="kw-spine__band"><span class="kw-spine__part"><i></i><i></i><i></i></span><span class="kw-spine__part"><i></i><i></i></span></span><span class="kw-spine__name">Act 1</span><span class="kw-spine__meta">5 beats</span></button></li><li style="flex-grow:50"><button class="kw-spine__act" type="button" style="--kw-act:var(--k-cal-rehearsal)"><span class="kw-spine__band"><span class="kw-spine__part"><i></i><i></i><i></i><i></i></span><span class="kw-spine__part"><i></i><i></i><i></i><i></i><i></i><i></i></span><span class="kw-spine__part"><i></i><i></i><small>+3</small></span></span><span class="kw-spine__name">Act 2</span><span class="kw-spine__meta">15 beats</span></button></li><li style="flex-grow:25"><button class="kw-spine__act" type="button" style="--kw-act:var(--k-cal-recce)"><span class="kw-spine__band"><span class="kw-spine__part"><i></i><i></i><i></i></span></span><span class="kw-spine__name">Act 3</span><span class="kw-spine__meta">3 beats</span></button></li></ul><p class="kw-spine__total">3 acts · 23 beats</p></div>
```

- **Band**: a section, as long as the share the writer gave it in its title (*Act 1 (25%)*, or a range such as *(0–10%)* read as its width), or evenly split if they gave none.
- **Segment**: a part inside the section.
- **Dot**: one beat. Up to 12 per segment, then *+n*.
- **Total line**: sections and beats.
- Choosing a section scrolls to it. On a phone the strip scrolls sideways.

Its remove condition is written down: writers ignore it in testing, *or read the band length as a judgement*. That is the line every chart in Kwark walks.

## Colour order for series

For charts with up to four series, use the chart tokens `--k-chart-coral`, `--k-chart-mango`, `--k-chart-mint` and `--k-chart-aqua`: Palette No. 300 deepened in light mode so every mark reaches 3:1 on white, and the brand colours as they are in dark. For five or more categories, or when a chart shows calendar categories, use the calendar colours below.

Kwark's data colours are muted, warm and named. Use them in this order for categorical series. The order is the calendar's (Decision 0043), because those seven are already tested together in light and dark and each has a fill, a stripe and an ink.

| Token | Name | Light | Dark | Use |
|---|---|---|---|---|
| `--k-cal-writing` | 1 · Writing (copper) | #98633f | #e8b58b | First series. Writing sessions |
| `--k-cal-rehearsal` | 2 · Rehearsal (sage) | #4f7359 | #86b392 | Second series |
| `--k-cal-reading` | 3 · Reading (ochre) | #a87b32 | #dcb36a | Third series. Stripe is 3.3:1 on its fill: never text |
| `--k-cal-shoot` | 4 · Shoot (olive gold) | #826d35 | #c4b068 | Fourth series. Shoot days |
| `--k-cal-recce` | 5 · Recce (slate blue) | #4d6a7a | #83aac0 | Fifth series |
| `--k-cal-meeting` | 6 · Meeting (mauve) | #7c5c6b | #be97aa | Sixth series |
| `--k-cal-deadline` | 7 · Deadline (brick) | #a44a3f | #df8275 | Last, and only for deadlines or what blocks work |
| `--k-cal-muted` | Muted | #78716c | #8c867d | Away, rest, phases, anything in the background |

Each category has three tokens: `--k-cal-<name>` (the stripe and the mark), `--k-cal-<name>-bg` (a soft fill) and `--k-cal-<name>-ink` (text on the fill). Measured in light mode, ink on fill is 6.8:1 to 8.9:1 and the stripe on its fill is 3.3:1 to 4.9:1; in dark mode, ink on fill is 8.6:1 to 10.4:1. The day-job hours use `--k-cal-dayjob-bg` and `--k-cal-dayjob-stripe`, a faint hatch, never a colour that says *wasted time*.

Rules for series colour:

- **Two series**: talk and action inside the editor use the room's pair. Outside it, use copper and sage.
- **More than seven series** is the wrong chart. Group, or use a table.
- **Brick is never a series colour by default.** It means *deadline* or *blocks work*, as status red does.
- **One series in a chart?** Use `--k-text` at full strength for the mark and `--k-text-2` for axes. Colour only when there is more than one thing to tell apart.
- **Status colours** (`--k-ok`, `--k-warn`, `--k-danger`) are for state, never for series.
- **Never** a rainbow scale, a saturated palette, or colours mixed toward black.

### Dailies: the three kinds of work

Dailies frames show up to three quiet bands a day, never volume and never streaks.

| Token | Name | Light | Dark | Use |
|---|---|---|---|---|
| `--k-kind-story` | Story | #a8734c | #e8b58b | Writing, outline, characters, research |
| `--k-kind-prep` | Prep | #627d5c | #a9bfa3 | Breakdown, shots, schedule, departments |
| `--k-kind-performance` | Performance | #5f7393 | #a9b8cf | An actor marking a scene Read, Rehearsed or Off book |

In light mode the three measure 4.0:1, 4.6:1 and 4.8:1 against white, so they are bands, not text. Dark mode lifts them (`#e8b58b`, `#a9bfa3`, `#a9b8cf`), each above 8:1 on the dark surface.

### The stripboard: an old code, kept

The stripboard uses the four paper colours production offices have used for decades, kept exactly so a crew reads it at a glance:

| Strip | Colour | Ink `#1f2427` on it |
|---|---|---|
| INT. DAY | Off-white `#f5f4ee` | 14.2:1 |
| EXT. DAY | Yellow `#f1d563` | 10.8:1 |
| INT. NIGHT | Blue `#8fb4d6` | 7.2:1 |
| EXT. NIGHT | Green `#93c197` | 7.7:1 |

These are one of the three places hex values are allowed outside the token file (`docs/design-system.md`), because they are the industry's, not Kwark's. Every strip also says *INT.* or *EXT.* and *DAY* or *NIGHT* in words.

## Light rooms: pastels a shade deeper

In light themes, data marks (the timeline, index-card lenses, avatars) are pastels taken about 20% darker in lightness, with hue and saturation kept. The timeline pairs a clay or sage for talk with a clean sand for action, and the sand must stay sand, never drifting into tan.

Rejected, and not to be revived:

- plain pastels, which wash out on white;
- solid saturated blue with white numbers;
- any colour mixed toward black, which reads as dirty;
- grey chips with an accent underline, which were hard to understand.

Lower the lightness in oklch or HSL; never mix with black. Keep dark ink on the fills and check the contrast: Daylight's clay carries 8.0:1, its sand 11.5:1.

## Labels over legends

- **Label the thing directly.** Act names sit on the acts; scene numbers sit on the scenes; the budget's sections carry their totals. A legend is the last resort, for marks too small to label.
- **When a legend is needed**, it uses the same words as the interface (*Mostly dialogue*, *Mostly action*, *Dialogue and action*) and sits under the chart, in reading order.
- **Numbers carry units** (*24 min*, *₹12,50,000*, *1 4/8 pages*) and use tabular figures (`font-variant-numeric: tabular-nums`) so columns line up.
- **Estimates say so**: *about*.
- **Axis text** is `--k-text-2` at `--k-fs-meta`; gridlines are `--k-line`. Nothing smaller than 11px, and 12px on a phone.
- **Bars start at zero.** No dual axes, no truncated scales, no 3D, no pie with more than five slices.
- **Motion is not information.** Bars may grow in on first draw (and not at all under reduced motion); nothing pulses.

## Accessible charts

Every chart has a text alternative that carries the same numbers.

| Chart | Alternative |
|---|---|
| Talk and action bar | `role="img"` named *Talk 62 percent, action 38 percent*, and the labels beside it in text |
| Timeline strip (phone) | A slider named *Runs about 1 h 42 min*, value text *Scene 12, INT. EDIT SUITE – NIGHT, at 26:40* |
| Timeline scenes (desktop) | Each scene a button named with its number, heading and length |
| Story spine | Each section a button with its name and beat count; the total line in text |
| Budget | It is already a table |
| Calendar | Agenda view is the list alternative, and the default on phones |
| Any new chart | A *Show as table* control, or a table beside it, with the same rows |

- **Never colour alone.** Strips say INT/EXT and DAY/NIGHT in words; balanced scenes are split, not a third colour; a clash in the calendar carries an icon, and its name says *clash*.
- **Interactive marks are buttons** with names, reachable by keyboard, with the focus ring drawn inside the mark so it is not clipped.
- **Patterns are allowed** where two colours sit side by side (the day-job hatch) and help people who cannot tell the colours apart.

## Charts Kwark never draws

- **No scores for writing**: no pacing score, readability grade, dialogue quality, "engagement" or sentiment arc of the script.
- **No targets that judge**: no green zone for runtime, no red bar for a long scene, no genre benchmark for talk against action.
- **No counts of the person**: no word-count streaks, no heatmap of writing days, no leaderboard, no "most productive hour" (Decisions 0001, 0008, 0036). Dailies shows kinds of work, never volume.
- **No percentages of done** for creative work. *Conviction %* in the idea module is a recorded deviation to remove (Decision 0002).
- **No comparison with other writers or projects.**

The older *Dialogue analytics* panel in the screenplay (DialogueAnalytics.tsx) uses eight saturated hex colours from a chart library and all-caps labels. It does not follow this page and should move to these rules when it is next touched.

**Do:** *Runs about 1 h 42 min*, scenes labelled with their numbers, talk and action in the room's pair, a table or named buttons for screen readers.

**Don't:** A runtime gauge that turns red past 110 minutes, a legend of eight saturated colours, and no text alternative.

**Do:** The story spine's bands at the shares the writer typed, with a dot per beat and the counts in words.

**Don't:** A "structure health" ring showing 72% with a tip to add beats to Act 2.

**Do:** Clay and sand a shade deeper than pastel, dark ink on top, checked at 4.5:1.

**Don't:** Plain pastels on white, or a sand mixed toward black until it turns brown.

> **For agents:** - **Must** state the chart's main reading in words before or above the chart.
> - **Must** use `--k-cal-*` in calendar order for categorical series, the room's pair for talk and action, and `--k-kind-*` for Dailies.
> - **Must** label marks directly; use a legend only for marks too small to label, in the interface's own words.
> - **Must** give every chart a text alternative with the same numbers, and never rely on colour alone.
> - **Must** start bars at zero, carry units, and say *about* for estimates.
> - **Never** chart a score, grade, target zone or comparison of a person's writing or a person's activity.
> - **Never** use status colours, saturated palettes or colours mixed toward black for series.

## AI readiness test

**Task:** Add a chart to the Schedule that shows how many shoot days each location needs for Blank Pages.

**Give the agent:** This page, the bar chart and data table components, decision 0043, Colour.

**Constraint:** Works in light and dark, on a phone, and for a screen reader; no judgement.

**A reliable answer:**
- A one-line reading in words (for example "6 locations over 18 shoot days")
- Horizontal bars from zero, each labelled with the location and its days
- One series in --k-text, or --k-cal-shoot if it sits with other categories
- A data table alternative with the same rows
- No targets, red bars or rankings
