# Colour: agent spec

Twin of `/colour`. Source wins: `packages/brand/app/utils/motive-tokens.ts`, `packages/brand/app/utils/site-theme.ts`, `app/composables/useSiteTheme.ts`.

## Roles

| Role | Colours | Use for |
|---|---|---|
| Primary theme | Neutrals (Light, Dark) and one accent, orange (`brandAccent`, now `brandOrange`) | Motive Unknown: website, pitches, social posts, advertising. Light and Dark are also the themes of this guide |
| Black and white only | B&W | Work where colour is not possible, for example a one-colour print |
| Secondary | The 19 palettes on `/colour` | One project (release, campaign, tour). Choose the palette that agrees with the artist or the collaborator |

## Page

- `::primary-theme` (`PrimaryTheme.vue`) shows `PrimaryDemo.vue` in the site theme. Light or Dark: the key-figure card is `var(--brand-accent)` with `var(--brand-on-accent)` type. The vertical cards are ground with ink. The last word of the title is `var(--brand-accent)`. Colour theme: the key-figure card is ink with ground type.
- `::neutral-chips` (`NeutralChips.vue`) shows the seven tokens of the site theme in use. Each chip has a name and a hex value (`text-caption`).
- `::brand-ramp` (`BrandRamp.vue`) shows the warm black, the eight steps and the warm white in the same chip style. A chip paints `p3` on a wide-gamut screen and shows the hex of `colour`.
- `useRenderedTheme()` renders Light on the server and the site mode after mount, so hydration matches.

## Neutrals

The tokens come from `siteTheme()`, on the warm neutrals (`brandNeutrals`): each has a very small chroma at the orange's hue, and the grey and the tones keep it. See Site theme.

| Token | Light | Dark | Floor on ground and grey |
|---|---|---|---|
| Ground `--ui-bg` | `#FDF9F8` | `#0A0707` | – |
| Grey `--grey` | `#F8EEEA` | `#1B1614` | – |
| Ink `--ui-primary` | `#0A0707` | `#F8EEEA` (Light's grey) | – |
| Text `--ui-text` | `#3D3938` | `#C8C0BC` | 10:1 |
| Toned `--ui-text-toned` | `#53504F` | `#A8A19D` | 7:1 |
| Muted `--ui-text-muted` | `#706D6B` | `#857F7B` | 4.5:1 |
| Dimmed `--ui-text-dimmed` | `#8D8A89` | `#686360` | 3:1 |

## Accents

`brandAccent` in `motive-tokens.ts` is the source. It points at `brandOrange`: eight steps, dark (1) to light (8). Step 5 is the Accent (`brandAccent.accent`): the original orange, `#FF4800`, exactly. `brandPurple` (hue 296) stays in the file as the alternative, in the same shape. Change `brandAccent` to change the accent.

The ramp is the brand owner's, anchored on the original orange: every chroma is scaled to it (×1.033), steps 1 to 5 rise evenly in hue from 25 to 35.97, and steps 6 to 8 keep their spacing above it. Each step has `p3`, the value as authored, and `colour`, its sRGB fallback. Every `p3` value but step 5's is outside sRGB. `brandStep()` makes the fallback: it holds lightness and hue and lowers chroma to `maxChroma()`, rounded down. Contrast is measured on the fallback, against the warm neutrals.

| Step | `p3` (OKLCH) | `colour` (OKLCH) | Hex | Use | Measured |
|---|---|---|---|---|---|
| 1 | `0.3000 0.1549 25.00` | `0.3000 0.1220 25.00` | `#5D0009` | Dark panel under white type | White 13.7:1 |
| 2 | `0.4000 0.1859 27.74` | `0.4000 0.1635 27.74` | `#8B0007` | Panel under white type | White 9.6:1 |
| 3 | `0.5000 0.2065 30.48` | `0.5000 0.1979 30.48` | `#BA1200` | Orange type on white at any size | White 6.3:1 |
| 4 | `0.6000 0.2272 33.23` | `0.6000 0.2202 33.23` | `#E63100` | Orange type on white at H3 or larger, and graphics | White 4.2:1 |
| 5 (Accent) | `0.6629 0.2272 35.97` | `0.6629 0.2272 35.97` | `#FF4800` | Fill under ink. Orange type on Dark | Ink 5.9:1. On black 5.9:1. On white 3.3:1 |
| 6 | `0.7000 0.2065 38.97` | `0.7000 0.1962 38.97` | `#FF6831` | Orange type on black | Black 7.0:1 |
| 7 | `0.7500 0.1859 40.97` | `0.7500 0.1567 40.97` | `#FF885B` | Panel under ink | Ink 8.5:1 |
| 8 | `0.8500 0.1239 45.97` | `0.8500 0.0882 45.97` | `#FFBC9D` | Pale panel under ink | Ink 12.4:1 |

- `--brand-accent` declares the Accent's `colour`, then `@media (color-gamut: p3)` sets its `p3` (`app.vue`). `--brand-on-accent` is the warm black, `brandNeutrals.black`.
- Paint the Accent with `var(--brand-accent)`, also in inline styles, so a wide-gamut screen takes `p3`. Do not paint `brandAccent.accent.colour` directly.
- The Orange palette primary is the Accent's sRGB `colour`. Palettes stay in sRGB: the site theme computes its tones from them.
- The hue moves from 25 at step 1 to 46 at step 8: the dark steps are redder, the light steps are more amber.
- Use the Accent for one item in each view: a key figure, the primary action or a highlight.
- Do not put white type on the Accent (3.3:1).
- Orange type on Light: step 3 at any size, or the Accent or step 4 at H3 or larger and in graphics. Orange type on Dark: the Accent or step 6, any size.
- Do not add a brand colour. The icon of a vertical identifies the vertical (`/agent/icons.md`). Do not give a vertical a colour.

Highlights in UI components (tile icons, the active client name, playheads) are `--brand-accent` on both sides. In Light it is 3.3:1 on the ground (pads) and 3.0:1 on the grey. There are no hover colours except on buttons.

- The primary theme's neutrals are warm, never pure black or white: `brandNeutrals.white` `oklch(0.9850 0.0040 45.97)` (`#FDF9F8`) and `brandNeutrals.black` `oklch(0.1350 0.0060 35.97)` (`#0A0707`). On the staging site the Accent is never a background, only a highlight. The active hero logo is the Accent: 3.0:1 on the Light grey.
- Staging page layer: the grey (`--ui-bg-elevated`) in Light, the ground (`--ui-bg`, the darkest black) in Dark. Page-layer type is `--surface-ink`, the ink.
- Halftone photos (`SiteHalftone`) are two colours: the page and the Accent. The darker is the ink, the lighter the paper: Accent ink on the grey in Light (about 3:1), warm black ink on Accent paper in Dark (5.9:1). Pass tokens through `toHex`; the shader does not read OKLCH.

## Palettes

`palettes` in `motive-tokens.ts` keeps each value as `oklch(L C H)`. The hex values below are `toHex()` output. Use them only for decks and print specifications.

| Palette | Primary | Secondary | Ratio | Use for |
|---|---|---|---|---|
| B&W | `#F5F5F5` | `#080808` | 18.4:1 | Where colour is not possible |
| Lime | `#D5FF00` | `#6C6C6C` | 4.5:1 | Loud work |
| Purple | `#A789EE` | `#141C04` | 6.2:1 | Pop and club, fan-facing |
| Yellow | `#F1ED0E` | `#384228` | 8.5:1 | Loud work |
| Pink | `#FF00F6` | `#400036` | 5.2:1 | Pop and club, fan-facing |
| Blue | `#2370FF` | `#00022E` | 4.6:1 | Electronic, tech, data-led documents |
| Orange | `#FF4800` | `#230400` | 5.7:1 | Loud work |
| Amber | `#FFA51F` | `#101F3C` | 8.3:1 | Loud work |
| Cerise | `#FF5C9E` | `#0A2E1C` | 5.1:1 | Pop and club, fan-facing |
| Plum | `#D98FD4` | `#332A0B` | 6.0:1 | Pop and club, fan-facing |
| Rose | `#FFB3C7` | `#3A0A1B` | 10.1:1 | Pop and club, fan-facing |
| Olive | `#A6A855` | `#33102A` | 6.7:1 | Slower, earthier work |
| Green | `#2AE84F` | `#06240F` | 10.1:1 | Growth and performance stories |
| Forest | `#3E9E6B` | `#2B0E12` | 5.4:1 | Slower, earthier work |
| Mint | `#8FEFBD` | `#2F1438` | 11.9:1 | Growth and performance stories |
| Teal | `#00E0C6` | `#04302E` | 8.5:1 | Electronic, tech, data-led documents |
| Sky | `#4CC6F2` | `#3A1608` | 8.2:1 | Electronic, tech, data-led documents |
| Sand | `#E9DCC3` | `#33291B` | 10.5:1 | Quiet work |
| Ice | `#CFE6FF` | `#11243D` | 12.2:1 | Quiet work |
| Slate | `#C3CBD4` | `#1C2229` | 9.8:1 | Quiet work |

Fixed neutrals outside the system: `brandWhite` `#FFFFFF`, `brandBlack` `#000000`.

Blue’s primary and the Lime and Purple secondaries differ from the `.pen` file. `motive-tokens.ts` is authoritative.

Distinctness metric between two primaries: `hypot(ΔL, ΔC, Δh × min(C₁,C₂) × 2 / 100)`. Five existing pairs are below the 0.09 floor: Lime/Yellow 0.059, B&W/Ice 0.069, B&W/Sand 0.080, Sand/Slate 0.081, Ice/Slate 0.082. These pairs stay. Do not use them as a precedent.

Hue gap between primary and secondary: Lime, Purple, Amber, Cerise, Plum, Olive, Forest, Mint and Sky are ≥ 120°. B&W, Yellow, Pink, Blue, Orange, Rose, Green, Teal, Sand, Ice and Slate are < 120°. These pairs stay. Do not use them as a precedent.

## Layouts

`resolveLayout({ palette, layout })`:

| Layout | Surface | Ink |
|---|---|---|
| `Deep` | secondary | primary |
| `Bright` | primary | secondary |

`brand/surface` and `brand/ink` in these specs mean the `resolveLayout()` result for the active palette and layout. On the site they are `--ui-bg` and `--ui-primary`.

## Site theme

`siteTheme({ ground, ink, layout, fadeTint })` writes every colour token the site reads.

| Mode | Ground (`--ui-bg`) | Ink (`--ui-primary`) | Set by |
|---|---|---|---|
| Light | `brandNeutrals.white`, `#FDF9F8` | `brandNeutrals.black`, `#0A0707` | Switch, or the B&W Bright chip |
| Dark | `brandNeutrals.black`, `#0A0707` | Light's `--grey`, `#F8EEEA` (the light orange) | Switch, or the B&W Deep chip |
| Colour | `resolveLayout().surface` | `resolveLayout().ink` | Switch (last pick, else Lime Bright), or any other chip |

- Tokens written: `--ui-bg`, `--ui-primary`, `--ui-text-highlighted`, `--ui-text-inverted`, `--ui-bg-inverted`, `--ui-border-inverted`, `--grey`, `--ui-text`, `--ui-text-toned`, `--ui-text-muted`, `--ui-text-dimmed`.
- `--grey` feeds `--ui-bg-muted`, `--ui-bg-elevated`, `--ui-bg-accented`, `--ui-border`, `--ui-border-muted`, `--ui-border-accented` (`brand.css`).
- `--grey` is the ground moved toward the ink. It keeps the hue and the saturation of the ground (chroma as a share of the sRGB maximum at that lightness and hue). `exactContrast` sets its contrast against the ground to the B&W value: Bright 1.09:1 (`oklch(0.97 0 0)` on white), Deep 1.12:1 (`oklch(0.18 0 0)` on black). On the warm neutrals: Light `#F8EEEA` on `#FDF9F8`, Dark `#1B1614` on `#0A0707`. The light grey has more chroma than its ground (0.012 against 0.004), as saturation is held, not chroma.
- Text tones: each tone is the ink moved toward the ground in OKLCH lightness, with hue held. Chroma is held, except with `fadeTint` (Light and Dark): chroma falls toward the ground's by the same share, so each lower tone has a subtler tint. Dark: ink 0.0120, `--ui-text` 0.0109, toned 0.0102, muted 0.0094, dimmed 0.0087. Each tone moves as far as it can and still clears its floor on the ground and on `--grey` (`contrastRatio`). Floors: `--ui-text` 10, `--ui-text-toned` 7, `--ui-text-muted` 4.5, `--ui-text-dimmed` 3. Captions are in the ink (`text-highlighted`). A tone that cannot clear its floor keeps the ink.
- `--ui-text-highlighted`, `--ui-bg-inverted` and `--ui-border-inverted` are the ink. `--ui-text-inverted` is the ground.

| Token | Light | Dark | Ice Bright | Yellow Deep |
|---|---|---|---|---|
| `--grey` | `oklch(0.9560 0.0120 45.97)` `#F8EEEA` | `oklch(0.2052 0.0087 35.97)` `#1B1614` | `#BFDEFF` | `#3E492D` |
| `--ui-text` | `oklch(0.3499 0.0055 35.97)` `#3D3938` | `oklch(0.8121 0.0109 45.97)` `#C8C0BC` | `#1A2D47` | ink, `#F1ED0E` |
| `--ui-text-toned` | `oklch(0.4334 0.0053 35.97)` `#53504F` | `oklch(0.7128 0.0102 45.97)` `#A8A19D` | `#314561` | `#E7E300` |
| `--ui-text-muted` | `oklch(0.5363 0.0051 35.97)` `#706D6B` | `oklch(0.5998 0.0094 45.97)` `#857F7B` | `#4C627E` | `#BCB700` |
| `--ui-text-dimmed` | `oklch(0.6353 0.0048 35.97)` `#8D8A89` | `oklch(0.5026 0.0087 45.97)` `#686360` | `#677D9C` | `#9A9400` |

- Light and Dark tokens are in a `<style>` in the head (`packages/brand/app/app.vue`): `:root{…}` and `:root.dark{…}`. Outside `.report-*` scopes, the CSS sets no colour token except the six that read `--grey`.
- A colour theme’s ink on its `--grey` is lower than the pair’s ratio. Lime (4.04 to 4.16:1) and Blue (4.12 to 4.25:1) are below 4.5:1 on `--grey`, in both layouts.
- `PalettePair` (`::palette-pair{name}`) chips call `useSiteTheme().pick()`. The primary chip gives Bright, the secondary chip gives Deep. A cross marks the chip in use.
- `ThemeSwitch` (Light / Dark / Colour) calls `setMode('light' | 'dark' | 'colour')`. From `lg` (1124px) it is in the foot bar. Below `lg` it is at the foot of the menu.
- A colour theme persists in `localStorage`: `mu-colour-theme` (`{palette, layout, vars}`), removed on Light or Dark, and `mu-colour-last` (`{palette, layout}`), kept. An inline head script in `nuxt.config.ts` reads `mu-colour-theme` and sets its tokens as inline styles on `<html>` before paint.
- A colour theme sets `data-theme="{palette}-{layout}"` on `<html>`, for example `Ice-Bright`.
- A Deep colour theme sets colour mode to dark, so `dark:` variants follow.
- `::motif-square` paints with `var(--ui-bg)` and `var(--ui-primary)`, `::piano-roll` with `var(--grey)` and `var(--ui-primary)`. They have no palette or layout props.

## Craft: `better-colors`

- Author colour as `oklch(L C H)`. Convert only with `parseColor`, `toRgb`, `toHex`, `luminance`, `contrastRatio`, `exactContrast` in `motive-tokens.ts`.
- Hex appears only on `/colour` tiles (`toHex()`) and in `brandWhite`/`brandBlack`.
- Components and content reference semantic tokens (`--ui-primary`, `--report-ink`, `brand/surface`), never primitives. Exception: a swatch whose purpose is to show a value.
- Use a token only in its role. If a role has no token, add a token.
- Hues within 15° are the same colour. The only semantic hues are `success`, `info`, `warning`, `error`. `/report` does not use them. `report-theme.ts` `label` resolves to black or white.
- One filled control per view marks the primary action. Its peers stay neutral (`outline`, `ghost`).
- Measure contrast against the colour below the element. Resolve opacity and any band or image below it.
- When a pair fails, report the pair, the measured value and the threshold. Do not repaint a brand colour.
- Gradients: use `in oklab` by default. Use `in oklch` only when a two-hue gradient goes grey in the middle. `patternGradient` sets no keyword.
- A colour outside sRGB declares the sRGB value first, then overrides it in `@media (color-gamut: p3)`. No palette value is outside sRGB. Every brand ramp step is: see Accents.

## Rules

1. Dress one project in one secondary palette and one layout. Never change palette per piece or rotate for variety.
2. Dress Motive Unknown's own work in the primary theme. Use B&W without the accent only where colour is not possible.
3. Never mix two palettes in one composition. Never use Deep for some elements and Bright for others on one surface.
4. Never hardcode a palette hex outside `motive-tokens.ts`. Resolve through `getPalette`/`resolveLayout`, or a prop that does (`LogoTile` `palette`/`layout`).
5. In site components, use `--ui-bg` and `--ui-primary` so the colour follows the site theme.
6. Contrast floor: WCAG 2, 4.5:1 for normal text, 3:1 for large text (≥24px) and UI components. Preferred: APCA Lc 90 for body text, Lc 60 for large text.
7. Every palette pair clears 4.5:1 between its two colours. Never measure a pair against white.
8. To fix a failing pair, change OKLCH lightness only, hold hue and chroma, and re-measure. Flag the change to a human.
9. Use `brandWhite`/`brandBlack` only where a colour must stay neutral under every palette. They do not replace B&W’s primary or secondary.
10. A new palette’s primary and secondary are ≥ 120° apart in OKLCH hue. A darker copy of the primary’s hue is not a second colour.
11. A new palette’s primary is ≥ 0.09 from every existing primary on the distinctness metric.

## Related

- `/agent/pattern.md`: generator colour inputs.
- `/agent/logo.md`: mark and wordmark ink.
- `/agent/layout.md#rounding`: controls versus content containers.
- `/agent/typography.md`: type on these colours. Never fix contrast by changing the type.
