# Writing rooms

> The screenplay editor's five rooms (Studio, Daylight, Paper, Lamplight, Midnight): what each is made of, how every colour in the editor is worked out from it, the legibility maths, and the rules for building inside one.

Source: https://kwark.space/designSystem/foundations/rooms

## A room is not a colour

A screenplay is written over months, mostly at night, mostly by one person looking at the same rectangle. What that rectangle looks like matters more than almost anything else in the editor. "Dark or light" is not much of an answer, and neither is a list of eleven colour pickers.

So the editor has five rooms, and one of the writer's own. A room is a **desk**, a **sheet of paper** on it, the **ink**, the **pencil** that marks what is active, whether the paper has a **tooth**, and what the **index cards** are cut from. Each is chosen for the others. The chrome, the timeline, the overview and the cards are all worked out from that one set (`paletteFrom()` in `pages/Understanding/EditorModule/utils/editorTheme.ts`), so nothing in the room is left in another room's colours.

Legibility is measured, not assumed. Every ink is settled against the grounds it sits on, so a pale room cannot leave its labels grey on grey.

A writer picks a room from **View › Room…** in the screenplay. The choice is content, not interface: `docs/design-system.md` says that what a writer chooses (rooms in the editor, fonts in the reader) may differ from the system. Everything else inside the editor takes the room's roles.

## The five rooms

| Room | `id` in code | What the app says about it |
|---|---|---|
| Studio | `dark` | A dark room with the page lifted just off the desk, marked in your project's colour. |
| Daylight | `light` | White paper on a cool grey desk, blue pen. The script as it will print. |
| Paper | `paper` | Cream stock with a tooth to it on a kraft desk, and a script editor's red pencil. |
| Lamplight | `sepia` | Warm brown desk, amber ink marks. Kind at two in the morning. |
| Midnight | `slate` | Deep blue with cool ink. Quieter than black without going cold. |

Studio is the default (`DEFAULT_THEME`). The ids are older than the names and are kept because they are stored in writers' settings; never show an id to a person.

| Room | Desk (`--k-bg`) | Chrome (`--k-surface`) | Page | Ink (`--k-text`) | Pencil (`--k-accent`) |
|---|---|---|---|---|---|
| Studio (`data-room="studio"`) | #0f0f11 | #151518 | #1a1a1d | #e8e6e3 | #e8b58b |
| Daylight (`data-room="daylight"`) | #e6e9ee | #f4f6f8 | #ffffff | #181b21 | #2f55c0 |
| Paper (`data-room="paper"`) | #d6ccb8 | #e6dece | #f8f2e4 | #28221a | #a3352b |
| Lamplight (`data-room="lamplight"`) | #16110d | #1d1712 | #251e18 | #eddcc3 | #e0a24e |
| Midnight (`data-room="midnight"`) | #0b111b | #101826 | #141e2e | #dde6f2 | #7fb5e8 |

## Every value

| | Studio | Daylight | Paper | Lamplight | Midnight |
|---|---|---|---|---|---|
| Desk | `#0f0f11` | `#e6e9ee` | `#d6ccb8` | `#16110d` | `#0b111b` |
| Chrome | `#151518` | `#f4f6f8` | `#e6dece` | `#1d1712` | `#101826` |
| Page | `#1a1a1d` | `#ffffff` | `#f8f2e4` | `#251e18` | `#141e2e` |
| Ink | `#e8e6e3` | `#181b21` | `#28221a` | `#eddcc3` | `#dde6f2` |
| Pencil | project colour | `#2f55c0` | `#a3352b` | `#e0a24e` | `#7fb5e8` |
| Grain | no | no | yes | no | no |
| Card stock | `#222226` | `#ffffff` | `#fbf7ec` | `#2e251d` | `#1a2536` |
| Card rule | project colour | `#d9534f` | `#c0453a` | `#e0a24e` | `#7fb5e8` |

Studio names no pencil, so it wears the project's own colour: the caret, the selection and the scene you are in are drawn in whatever colour the writer gave the project. In this design system's `kwark.css`, Studio's `--k-pencil` is set to `#e8b58b`, the app's default dark accent, which is what Studio shows when a project has no colour of its own.

Paper's grain is drawn, not loaded: a small SVG noise filter at 7% opacity tinted toward brown, so the stock has a tooth without an image request.

## How the roles follow the room

Put `data-room` on the editor's container and the design system's roles take the room's values. In the app the same thing happens through `--editor-*` variables set from `paletteFrom()`.

| Role in this system | Room part | App variable | Use |
|---|---|---|---|
| `--k-bg` | Desk | `--editor-bg` | Around the page |
| `--k-surface` | Chrome | `--editor-surface` | Menus, navigator, rails |
| `--k-page` | Page | `--editor-page-bg` | The sheet |
| `--k-text` | Ink | `--editor-text` | The words |
| `--k-text-2` | Settled muted ink | `--editor-text-muted` | Meta, scene numbers, rail labels |
| `--k-accent` | Pencil | `--room-caret`, `--project-accent` | Caret, selection, current scene, primary action |
| `--k-on-accent` | Desk | `--project-accent-text` | Text on a pencil-coloured fill |
| `--k-line` | Ink mixed into chrome | `--editor-border` | Hairlines |

A shared component placed inside the editor (a menu, a dialog, a toast) therefore takes the room's colours without knowing it is in one. That is the point: one Button, five rooms, no branches.

```html
<div class="kw-script-page kw-script-page--crop" style="max-width:420px"><p class="kw-sp-scene" data-number="12">INT. EDIT SUITE – NIGHT</p><p class="kw-sp-action">Mira scrubs back. Stops.</p><p class="kw-sp-character">MIRA</p><p class="kw-sp-dialogue">I didn’t shoot this.</p></div>
<button class="kw-button kw-button--primary" type="button">Make a restore point</button>
<button class="kw-button" type="button">Export</button>
<span class="kw-badge">Scene 12 · 2:40</span>
```

## What is worked out from the room

`paletteFrom()` takes the room and returns about forty variables. The ones that carry meaning:

| Variable | Worked out as | Why |
|---|---|---|
| Muted ink | Ink faded toward the chrome until the worst of chrome, desk and page reaches 5.2:1 | Quiet labels that still read on every ground |
| Faint ink | The same, to 3.2:1 | Marks that are present but not text |
| Border | Chrome with 13% (dark) or 15% (light) of the ink | A line that shows on every room |
| Warning | `#d8a44a` pushed toward the ink until 4.5:1 | Warnings that read on Paper as well as Midnight |
| Input background | Chrome lifted 5% toward the ink (dark) or 70% toward white (light) | Fields that look like fields |
| Popover background | Chrome lifted 3.5% (dark) or 82% (light) toward white | Menus a step above the chrome |
| Active row | Chrome with 12% (dark) or 10% (light) of the ink | Hover and pressed states |
| Page edge | Page 7% toward white (dark) or 9% toward black (light) | The sheet's outline on the desk |
| Card muted ink | Ink settled against the card stock to 5:1 | Index card meta |
| Timeline talk and action | See [timeline marks](#timeline-marks) | Each scene carries its own number |
| Overview marks | Scene `#d9a24a`, action `#6aa6d8`, dialogue `#7fb86a`, each pushed toward the ink until 3:1 on the page | The overview's highlighting stays visible on any paper |
| Selection | The pencil at 30% (dark) or 22% (light) alpha | Selected text stays readable |
| Caret | The pencil, or the project's colour | The one thing that moves |

## The legibility maths

Four small functions do the work. They use the WCAG relative-luminance formula, so the numbers mean the same thing an accessibility checker means.

**`readableOn(ground)`.** Ink that can be read on a ground. It measures both white and near-black (`#0b0b0b`) against the ground and takes the better one. It does not ask "is this ground dark?", because a mid-grey reads as dark on that test and yet takes black ink far better than white (5.3:1 against 3.9:1): a threshold picks the worse of the two exactly where the choice is hardest. Then it carries up to 16% of the ground into the ink, in 4% steps, but only as much as still keeps 7:1. The page looks like one room instead of a rectangle with text stuck on it.

**`settle(ink, grounds, target)`.** A quieter ink. A fixed fade (say 40% toward the ground) is a whisper on black and illegible on white, so the amount is found by binary search, fourteen steps, against every ground the label may sit on, and the worst ground decides. Muted ink targets 5.2:1, faint 3.2:1; with Stronger contrast, 7:1 and 4.6:1.

**`legible(colour, ink, grounds, target)`.** A colour pushed toward the ink, 10% at a time, until it can be read as text on these grounds. Used for the pencil when it colours text (4.6:1), for warnings (4.5:1) and for overview marks (3:1).

**`carrying(fill, ink, ground, target)`.** A fill pushed toward its ground, 10% at a time, until the ink on top of it reads. Used for the timeline's scene blocks, which carry their own numbers.

Two helpers sit around them: `isDark(colour)` (relative luminance under 0.42) chooses which set of light-appearance rules the editor's stylesheet applies, and `readsWell(ground)` says whether a ground can carry a comfortable read at all (4.5:1 with its best ink). The custom-room picker uses the second to warn a writer.

### What the maths produces

| Room | Ink on page | Ink on desk | Muted text on chrome | Pencil on page |
|---|---|---|---|---|
| Studio | 13.9:1 | 15.4:1 | 7.2:1 | project colour, made legible to 4.6:1 |
| Daylight | 17.2:1 | 14.2:1 | 6.6:1 | 6.6:1 |
| Paper | 14.1:1 | 9.9:1 | 5.7:1 | 6.1:1 |
| Lamplight | 12.2:1 | 14.0:1 | 7.4:1 | 7.4:1 |
| Midnight | 13.3:1 | 15.0:1 | 7.6:1 | 7.7:1 |

Muted values here are the ones in `kwark.css`; the app settles its own at runtime against all three grounds and never goes under 5.2:1.

## Timeline marks

The timeline under the page is a strip of scenes coloured by what fills them: **talk** and **action**. Each block carries its own number, so the fill is pulled toward the page until the ink reads on it (`carrying`, 4.5:1 on light rooms, 5:1 on dark). A scene that is both is drawn half and half.

Each room ships five pairs, chosen for its desk. The first pair is the room's default, and its preview in the picker shows that strip.

| Room | Pairs (talk and action) |
|---|---|
| Studio | Amber and graphite · Teal and graphite · Indigo and taupe · Plum and slate · Moss and stone |
| Daylight | Clay and sand · Sea and linen · Lavender and stone · Rose and cream · Cornflower and stone |
| Paper | Terracotta and kraft · Verdigris and oat · Ink blue and kraft · Ochre and pewter · Dusty rose and oat |
| Lamplight | Amber and walnut · Copper and umber · Petrol and walnut · Olive and umber · Rose and walnut |
| Midnight | Moon blue and slate · Teal and slate · Lilac and slate · Sandstone and slate · Dusk rose and slate |

Default pairs, as hex:

| Token | Name | Light | Dark | Use |
|---|---|---|---|---|
| `#b98545` | Studio talk · Amber | #b98545 |  | Action is graphite #45484e |
| `#d9a58c` | Daylight talk · Clay | #d9a58c |  | Action is sand #dcd2bd |
| `#c98e72` | Paper talk · Terracotta | #c98e72 |  | Action is kraft #d3c8b0 |
| `#c9953f` | Lamplight talk · Amber | #c9953f |  | Action is walnut #4a4038 |
| `#5f8fc0` | Midnight talk · Moon blue | #5f8fc0 |  | Action is slate #2e3a4c |

**Light rooms use pastels a shade deeper.** On a pale room the strip is two pastels set about 20% darker in lightness than a pastel usually is, hue and saturation kept, so they hold against white without turning into blocks of colour. The sand stays sand and never drifts into tan. Rejected on the way, and not to be revived: plain pastels (washed out), saturated blue with white numbers, anything mixed toward black (dirty), and grey chips with an accent underline (hard to read). Dark ink stays on the fills: Daylight's clay carries 8.0:1, its sand 11.5:1.

**Dark rooms derive talk from the pencil.** With no pair chosen, talk is the pencil mixed halfway with the page, and action is the ink mixed 72% toward the page, both then carried to 5:1.

**The current scene** is a 2px ring in the project's colour with a pointer above it. It used to have an 18px glow, a brightness filter and six particles rising through it on a loop. They are gone (Decision 0041).

### Card and mark swatches

Each room also ships twelve swatches for marking index cards (times of day, lenses) and characters, named for the room: Studio from Terracotta to Slate, Daylight from Clay to Slate, Paper from Terracotta to Pewter, Lamplight from Copper to Umber, Midnight from Dusk rose to Deep slate. A writer chooses from the room's own set, so a colour that suits Paper is never dropped into Midnight.

## Stronger contrast

A switch in the room picker: *Stronger contrast. Fuller ink and firmer lines, in whichever room.* With it on:

- ink becomes pure white or pure black, whichever scores better against desk, chrome and page together;
- muted ink targets 7:1 and faint 4.6:1;
- borders take 30% of the ink instead of 13 to 15%;
- the page edge is drawn three times firmer;
- pencil text targets 7:1.

It is not a room. It works in any of them, including one the writer mixed.

## A room of the writer's own

A writer can name one colour, the desk, and optionally a pencil. `customRoom()` builds the rest the way the shipped rooms are built:

- chrome is the desk lifted 3.5% toward white (dark desk) or 35% (light desk);
- the page is the desk lifted 6% (dark) or 72% (light);
- ink is `readableOn(page)`, or `readableOn(desk)` if that ink would fall under 4.5:1 on the desk;
- card stock is a step off the page; the card rule is the pencil, or the project's colour.

If the desk is too close to the middle for anything to read well, the picker says so plainly: *That desk is close to the middle, so nothing reads really well on it.* It then explains that the sheet is lifted off it to keep the script readable but the menus will be tiring. The writer may keep it. A writer can also save a mixed room under a name.

## Rooms that moved

Earlier rooms were folded into the five. People who chose them are moved, not reset:

| Old room | Now |
|---|---|
| Moss | Midnight |
| Contrast | Studio, with Stronger contrast on |
| Notebook | Paper |
| Typewriter | Lamplight |

## Flat rooms and the printed page

Decision 0041 (12 November 2026) settled two things after the founder's audit: "I can see glow in some themes and not sure if writers would appreciate it… make sure we aren't off by even 1px."

**Rooms are flat.** Each room keeps its desk, paper, ink and pencil; the light layer that put a window, a lamp or a moon over the desk is removed, and the room notes no longer mention one. Writers' reference points (Final Draft, Highland, WriterSolo, Fade In) use flat desks. If writers ask for an atmosphere they miss, it comes back as an opt-in room, never the default. The Reader's opt-in *Printed book* style keeps its lit desk, because it is chosen, not default.

**The screen is the printed page.** A room changes colour only. It never changes geometry:

- dialogue wraps at 33 characters and parentheticals at 28, as Highland's printed pages do (3.3 and 2.8 inches);
- the narrow-page rule fires below 580px; a full text column is 587px, so it no longer fires on every page;
- scene headings sit on the action margin (each heading's chevron returned the 5px it borrowed);
- a linked act's ⟷ sits beside the act name and takes no line, so the screen has no line the PDF does not.

## Building inside a room

> **For agents:** - **Must** use role tokens (`--k-bg`, `--k-surface`, `--k-page`, `--k-text`, `--k-text-2`, `--k-accent`, `--k-line`) for anything inside the editor; never a hex value and never a theme check.
> - **Must** keep `data-room` on any portal (menu, popover, toast) rendered outside the editor container, or it will open in the wrong room.
> - **Must** check new text at 4.5:1 and marks at 3:1 in all five rooms and with Stronger contrast on.
> - **Must** use the room's own mark swatches and timeline pairs for data colours inside the editor.
> - **Never** change page geometry, type size or line breaks per room.
> - **Never** add light, glow, gradient washes, vignettes or particles to a room.
> - **Never** show a room's code id (`sepia`, `slate`) to a person.

What a room may change: desk, chrome, page, ink, pencil, grain, card stock and rule, mark colours. What a room may never change: the page's geometry, the type, the page count, where a line breaks, what a mark means.

**Do:** A scene card that takes `--k-surface` and `--k-text`, with its time-of-day mark from the room's swatches, checked in Paper and Midnight.

**Don't:** A scene card with `background: #ffffff` and a saturated blue chip that looks right in Daylight and glares in Lamplight.

**Do:** Mark the current scene with the 2px ring in the project's colour and the pointer above it.

**Don't:** A glow, a brightness filter or rising particles on the current scene.

**Do:** In a light room, talk in clay `#d9a58c` and action in sand `#dcd2bd`, dark ink on both.

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

## AI readiness test

**Task:** Add a "Notes" rail to the screenplay editor that lists the writer's notes for the current scene.

**Give the agent:** This page, Colour, the List row and Menu components, decision 0041.

**Constraint:** It must sit correctly in all five rooms and with Stronger contrast on, and its ⋯ menu opens in a portal.

**A reliable answer:**
- Uses --k-surface, --k-text, --k-text-2 and --k-line only
- Portal menu carries the editor's data-room
- Text 4.5:1 and marks 3:1 in all five rooms
- No glow, gradient or room-specific branches
- Page geometry untouched
