# Colour

> Colour in Kwark is a set of roles. Components ask for the page, the surface or the accent, and the theme, the room or the project decides what that is.

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

## How colour works here

Kwark has two colour layers, and they never mix.

- **Brand palette.** Five colours for the brand itself: the website, the case study, marketing, this site. They never appear in the app's working surfaces.
- **Product roles.** The colours the app is made of: page, surface, line, text, accent, status. Each is a token with a light and a dark value, and inside the screenplay editor each follows the writing room.

A component never names a colour. It names a role: `background: var(--k-surface)`. That is what lets one component sit correctly in light, dark, Paper and Midnight without a single change.

> **For agents:** Use `--k-*` role tokens only. Never write hex, rgb or hsl in a component. If no role fits, stop and ask; do not add a colour.

## Brand palette

Palette No. 300. Ink is the ground; the four colours are accents, one per area, following a 60-30-10 balance: 60% ink or paper, 30% one accent, 10% a second.

| Token | Name | Light | Dark | Use |
|---|---|---|---|---|
| `--k-brand-ink` | Ink | #1b221e |  | The ground. Text on light, background on dark. |
| `--k-brand-coral` | Coral | #f28b71 |  | Calls to action on brand surfaces. Ink text on it, never white. |
| `--k-brand-mango` | Mango | #fac374 |  | Highlights, comment pins, warmth. |
| `--k-brand-mint` | Mint | #badfcf |  | Calm confirmation, selected states on dark. |
| `--k-brand-aqua` | Aqua | #83cfd3 |  | Links to the technical side: code, agents. |

## Product roles

| Token | Name | Light | Dark | Use |
|---|---|---|---|---|
| `--k-bg` | Page | #f8fafc | #191919 | The page behind everything. |
| `--k-surface` | Surface | #ffffff | #1a1a1a | Cards, panels, dialogs, inputs. |
| `--k-raise` | Raised | #f1f5f9 | #252525 | Hover, selected rows, pressed segments. |
| `--k-line` | Line | #e2e8f0 | rgba(255, 255, 255, .1) | Hairlines and borders. |
| `--k-line-strong` | Strong line | var(--k-text-2) | var(--k-text-2) | Field borders, checkbox outlines (3:1 against the surface). |
| `--k-text` | Text | #0f172a | #e3e3e3 | Body and titles. |
| `--k-text-2` | Quiet text | #5b6779 | #9ca3af | Meta, captions, placeholders (4.5:1). |
| `--k-accent` | Accent | #98633f | #98633f | Primary actions. A project's own colour replaces it. |
| `--k-on-accent` | On accent | #ffffff | #ffffff | Text and icons that sit on the accent. |
| `--k-focus` | Focus | #0f172a | #f4f4f5 | The focus ring. |

### The accent belongs to the project

Kwark's own accent is a warm copper: `#98633f`, with a light partner `#e8b58b` (`NEUTRAL_PROJECT_ACCENT` and `NEUTRAL_PROJECT_HIGHLIGHT` in `utils/colorUtils.ts`). It used to be a hard blue, so every project that had never chosen a colour read as blue; it is copper now so that an unchosen project reads in the app's own palette.

When a writer gives a project a colour, the accent becomes that colour everywhere in the project: primary buttons, the caret, the scene headings on the page, the timeline's current-scene ring. The writer picks from ten presets (`PRESET_COLORS` in `shared/constants.ts`: Red, Orange, Amber, Lime, Emerald, Teal, Cyan, Blue, Violet, Pink), and each preset is a pair:

| Part | App variable | Role here | What sits on it |
|---|---|---|---|
| The accent, strong | `--color-action` | `--k-accent` | `--story-on-accent`: black or white, whichever reads |
| The accent, light | `--color-highlight`, `--project-accent` | `--k-accent-soft` | `--project-accent-text`, which the app's `--k-on-accent` points at |

How it is applied (`utils/projectAccent.ts`):

- **Before the first paint.** The accent is set on `<html>` synchronously, and kept in `localStorage` (`thea_last_accent`), so a reload sets it in the document head before anything is drawn. An earlier version applied it after React had drawn, and every navigation flashed copper for a frame.
- **Always with its text colour.** Every accent is set together with the colour that reads on it. Setting one without the other is what once left labels white on a pale accent.
- **A colour nobody chose is no colour.** Three old default blues (`#1e40af`, `#3b82f6`, `#2d7ff9`) that older versions wrote into project records are treated as unset (`chosenAccent`).
- **Dialogs can carry a project's colour.** `Modal` takes `accentColor` and `accentLight` and sets the pair on its own overlay, so a project's dialog opened from Home wears that project's colour.

The text colour on an accent is chosen by brightness (the YIQ formula, black at 128 and above). That is fast but not a contrast check: on the Blue preset (`#3d7fea`) it picks white, which is 3.87:1, below 4.5:1 for body text. Until the rule is a real contrast calculation, put only 16px 600 or larger text on a strong accent, and test every preset.

**This is why components never assume the accent is copper.** Test with a pale accent (Amber, Lime) and a dark one (Violet), in light and dark.

## Status

Four pairs, each a strong colour for text and icons and a soft one for backgrounds. They are muted on purpose: Kwark tells people about problems without alarming them.

| Token | Name | Light | Dark | Use |
|---|---|---|---|---|
| `--k-ok` | Ok | #2c6e49 | #6cc08a | Settled: Saved, Locked, Issued. |
| `--k-info` | Info | #255799 | #7db4f0 | Worth knowing: Shared, Revised. |
| `--k-warn` | Warn | #8a5a00 | #d8a44a | Needs attention soon: Out of sync, Clash in two days. |
| `--k-danger` | Danger | #b4382c | #e0685c | Blocks work or destroys it: Delete, Clash today. |
| `--k-rev` | Revision | #346a58 | #9fd4bf | Words a machine proposed. See AI and authorship. |

**Do:** *Out of sync* in a warn badge with words. The colour supports the word.

**Don't:** A red dot with no label, or red for a scene that is merely long.

## Light, dark and the rooms

The app follows the system theme unless the person chooses. Add `class="dark"` (or `data-theme="dark"`) on `<html>`. Inside the screenplay editor the writer chooses a room, and the roles take the room's values. See [Writing rooms](https://kwark.space/designSystem/foundations/rooms.md).

```html
<button class="kw-button kw-button--primary" type="button">Save scene</button>
<button class="kw-button" type="button">Share</button>
<span class="kw-badge kw-badge--info">Revised</span>
<label class="kw-switch"><input type="checkbox" role="switch" checked><span class="kw-track"></span>Typewriter sound</label>
```

## Colour in light rooms: pastels, a shade deeper

Data colours (timeline marks, index-card lenses, avatars) are pastels taken about 20% darker in lightness, with hue and saturation kept. Never mix toward black: it reads as dirty. Never use plain pastels on white: they wash out. Keep dark ink on the fills and check the contrast.

**Do:** Sage for dialogue and clean sand for action on the timeline, each a step deeper than a pastel, dark ink on top.

**Don't:** Saturated blue blocks with white numbers, grey chips with an accent underline, or a sand that drifts to brown.

## Where this site and the app differ

`kwark.css` takes its values from the app's `styles/tokens.css`. Four roles differ, each on purpose or because the two names mean different things:

| Role | App | Here | Why |
|---|---|---|---|
| `--k-danger`, light | #e0685c in both modes, 3.33:1 on white | #b4382c, 5.93:1 | The app's light danger fails as text; dark keeps #e0685c |
| `--k-on-accent` | #17110c: the text for the light accent (`--project-accent-text`) | #ffffff: the text for `--k-accent` (`--story-on-accent`), 5.01:1 on #98633f | The app's name pairs with `--k-accent-soft`; here it pairs with `--k-accent`, which is what a primary button needs |
| `--k-line-strong` | #cbd5e1 light, #48433d dark | `var(--k-text-2)` | Field borders and checkbox outlines must reach 3:1 against the surface; #cbd5e1 on white is about 1.5:1 |
| `--k-rev`, `--k-rev-bg`, `--k-rev-line` | Not defined | Defined | The revision mark for machine-proposed words is designed here first ([AI and authorship](https://kwark.space/designSystem/foundations/ai-and-authorship.md)) |

**The accent in dark mode.** `--k-accent` stays #98633f in dark, in the app and here. On the #191919 page it is 3.51:1: fine as a button fill with white text on it, not enough for accent-coloured text or a thin icon. On dark, accent text and icons use `--k-accent-soft` (#e8b58b, 9.56:1), as the app's own dark screens do through `--project-accent`.

## Contrast

| What | Minimum | Kwark target |
|---|---|---|
| Body text | 4.5:1 | 7:1 where it is the work itself (the script) |
| Large text (24px, or 19px bold) | 3:1 | 4.5:1 |
| Icons, field borders, focus ring | 3:1 | 3:1 |
| Disabled controls | none | still readable; say why it is disabled |

Check any pair here:

## No glow

Kwark does not use glows, light washes, blurred colour blobs or gradient fills in its interface. They read as decoration, cost contrast, and make the interface louder than the work. Depth comes from a line and a step in tone. See [Elevation](https://kwark.space/designSystem/foundations/elevation.md).

## AI readiness test

**Task:** Restyle a settings panel so it works in the Paper room and in dark mode.

**Give the agent:** This page, Writing rooms, tokens.json.

**Constraint:** No new colours. Say which roles you used.

**A reliable answer:**
- Only --k-* roles
- No hex values
- Text 4.5:1 in both
- Accent never assumed to be copper
