Files
arr/.impeccable/design.json
T
Miguel PalhasandClaude Opus 5.5 1b6dae676a
ci / web (push) Successful in 20s
e2e / e2e (push) Failing after 51s
ci / rust (push) Failing after 1m13s
ci / image (push) Skipped
docs(design): record Master Control revision 2
Co-Authored-By: Claude Opus 5.5 (1M context) <noreply@anthropic.com>
2026-10-24 17:28:22 +01:00

436 lines
30 KiB
JSON

{
"schemaVersion": 2,
"generatedAt": "2026-10-24T00:00:00.000Z",
"title": "Design System: arr — Master Control, revision 2 (mobile first)",
"extensions": {
"colorMeta": {
"ground": {
"role": "neutral",
"displayName": "Console Charcoal",
"canonical": "oklch(0.14 0.01 250)",
"tonalRamp": [
"oklch(0.14 0.01 250)",
"oklch(0.18 0.012 250)",
"oklch(0.21 0.014 250)",
"oklch(0.3 0.015 250)",
"oklch(0.42 0.02 250)",
"oklch(0.58 0.015 250)",
"oklch(0.72 0.015 250)",
"oklch(0.93 0.008 250)"
]
},
"signal-ok": {
"role": "secondary",
"displayName": "Signal Green",
"canonical": "oklch(0.8 0.17 150)",
"tonalRamp": [
"oklch(0.45 0.1 150)",
"oklch(0.62 0.14 150)",
"oklch(0.8 0.17 150)",
"oklch(0.88 0.12 150)"
]
},
"signal-warn": {
"role": "tertiary",
"displayName": "Caution Amber",
"canonical": "oklch(0.82 0.14 80)",
"tonalRamp": [
"oklch(0.5 0.1 80)",
"oklch(0.66 0.13 80)",
"oklch(0.82 0.14 80)",
"oklch(0.9 0.1 80)"
]
},
"signal-fault": {
"role": "secondary",
"displayName": "Fault Red",
"canonical": "oklch(0.68 0.21 25)",
"tonalRamp": [
"oklch(0.42 0.15 25)",
"oklch(0.55 0.19 25)",
"oklch(0.68 0.21 25)",
"oklch(0.8 0.14 25)"
]
},
"accent": {
"role": "primary",
"displayName": "Phosphor Cyan",
"canonical": "oklch(0.8 0.12 220)",
"tonalRamp": [
"oklch(0.5 0.1 220)",
"oklch(0.65 0.11 220)",
"oklch(0.8 0.12 220)",
"oklch(0.9 0.08 220)"
]
},
"verdict-eligible": {
"role": "secondary",
"displayName": "Eligible Green",
"canonical": "oklch(0.8 0.17 150)",
"tonalRamp": [
"oklch(0.45 0.1 150)",
"oklch(0.62 0.14 150)",
"oklch(0.8 0.17 150)",
"oklch(0.88 0.12 150)"
]
},
"verdict-waived": {
"role": "tertiary",
"displayName": "Waiver Amber",
"canonical": "oklch(0.82 0.14 80)",
"tonalRamp": [
"oklch(0.5 0.1 80)",
"oklch(0.66 0.13 80)",
"oklch(0.82 0.14 80)",
"oklch(0.9 0.1 80)"
]
},
"verdict-rejected": {
"role": "neutral",
"displayName": "Rejected Slate",
"canonical": "oklch(0.68 0.02 250)",
"tonalRamp": [
"oklch(0.42 0.02 250)",
"oklch(0.55 0.02 250)",
"oklch(0.68 0.02 250)",
"oklch(0.8 0.015 250)"
]
},
"status-airing": {
"role": "tertiary",
"displayName": "Channel Violet",
"canonical": "oklch(0.78 0.14 305)",
"tonalRamp": [
"oklch(0.64 0.045 305)",
"oklch(0.72 0.09 305)",
"oklch(0.78 0.14 305)",
"oklch(0.86 0.09 305)"
]
},
"score-heat": {
"role": "tertiary",
"displayName": "Score Heat",
"canonical": "oklch(0.8 0.17 150)",
"tonalRamp": [
"oklch(0.68 0.19 25)",
"oklch(0.7 0.185 46)",
"oklch(0.72 0.175 67)",
"oklch(0.75 0.165 88)",
"oklch(0.77 0.16 108)",
"oklch(0.79 0.165 129)",
"oklch(0.8 0.17 150)"
]
}
},
"typographyMeta": {
"display": {
"displayName": "Display (Rajdhani)",
"purpose": "Rajdhani 700 — wordmark and module names only. Machined, condensed, uppercase with 0.1-0.12em tracking. Self-hosted woff2 in web/public/fonts (no CDN: the SPA is embedded in the binary and must work offline)."
},
"label": {
"displayName": "Label (system sans)",
"purpose": "system-ui 600 uppercase, 0.6875rem, 0.12em tracking — group labels inside a section (eligible, below policy, no pt source). Never a kicker above a heading."
},
"readout": {
"displayName": "Readout (mono)",
"purpose": "ui-monospace stack — every value the operator reads: status words, details, version, rtt. Mono is for measurement, never costume."
},
"scale": {
"displayName": "Type scale",
"purpose": "Seven fixed steps as tokens: --text-2xs 0.6875rem (micro-labels, chips), --text-xs 0.75rem (controls, readouts in rows), --text-sm 0.8125rem (row titles on a phone, readouts), --text-base 1rem (body, inputs on touch so iOS never zooms), --text-md 1.0625rem (section titles), --text-lg 1.3125rem (page titles on a phone), --text-xl 1.625rem (page titles from 40rem, wordmark). Components never carry a literal font-size. Controls and chips no longer share a height: --control-h 2.75rem (44px touch target; 2.25rem only under (pointer: fine) and (min-width: 64rem)) and --chip-h 1.5rem."
},
"roles": {
"displayName": "Type roles",
"purpose": "Five roles, one job each. Page title: display 700, text-lg (text-xl from 40rem). Section: display 600, text-md, uppercase 0.08em, ink-muted. Group label: label 600, text-2xs, uppercase 0.12em, with its count. Row title: label 600, text-sm (text-base from 40rem), one line with ellipsis, year in the readout face beside it. Readout: mono, tabular numerals, text-xs/2xs."
}
},
"shadows": [
{
"name": "panel-highlight",
"value": "inset 0 1px oklch(1 0 0 / 4%)",
"purpose": "The machined top edge of every panel and control. The only non-lamp shadow in the system."
},
{
"name": "lamp-glow",
"value": "0 0 6px var(--lamp), 0 0 14px oklch(from var(--lamp) l c h / 35%)",
"purpose": "A lamp's own light. Reserved for .lamp; never decoration on panels or text."
}
],
"motion": [
{
"name": "ease-out",
"value": "cubic-bezier(0.25, 1, 0.5, 1)",
"purpose": "Default easing for state transitions."
},
{
"name": "duration-state",
"value": "150-300ms",
"purpose": "Hover/focus 150ms, lamp and trace state changes 300ms."
},
{
"name": "power-up strike",
"value": "lamp-strike 420ms, staggered 120ms upstream→downstream, once",
"purpose": "The one authored moment: the board lights in signal order on first verdict. Guarded by prefers-reduced-motion."
}
],
"breakpoints": [
{
"name": "base",
"value": "the phone (390px) is the base layout; every rule without a query is phone truth"
},
{
"name": "wide",
"value": "min-width 40rem — the tab bar becomes rail links, the search field sits in the rail, rows show priority-2 chips and their wide-only actions, ⋯ trays retire"
},
{
"name": "dense",
"value": "(pointer: fine) and (min-width: 64rem) — --control-h 2.25rem, --row-min 3rem; the version readout and the / hint appear"
},
{
"name": "row container",
"value": "rows answer to their container (.deck, .buckets, .subs-panel, .chain-wrap): 40rem as above, 46rem turns release chips into the §9.3 fixed columns and the stacked chain into the five-column chain"
}
],
"themes": {
"strategy": "committed dark only — a control room is lit by its lamps; the operator uses this on a homelab desk at night. color-scheme: dark is declared in the shell.",
"dark": {
"bg": "oklch(0.14 0.01 250)",
"ink": "oklch(0.93 0.008 250)",
"primary": "oklch(0.8 0.12 220)"
}
}
},
"components": [
{
"name": "Lamp",
"kind": "custom",
"refersTo": "signal-ok",
"description": "Status lamp. Hue by state (ok/degraded/unconfigured/unreachable), glow is its own light. data-state=\"off\" is dead air: dark, no glow, no motion. Always paired with a status word — remove color and the state must survive.",
"html": "<span class=\"lamp\" data-state=\"ok\" aria-hidden=\"true\"></span>",
"css": ".lamp { --lamp: var(--signal-idle); width: 0.625rem; height: 0.625rem; border-radius: 50%; background: var(--lamp); box-shadow: 0 0 6px var(--lamp), 0 0 14px oklch(from var(--lamp) l c h / 35%); } .lamp[data-state=\"ok\"] { --lamp: var(--signal-ok); } .lamp[data-state=\"off\"] { --lamp: var(--lamp-off); box-shadow: none; }"
},
{
"name": "Chip",
"kind": "custom",
"refersTo": "ground",
"description": "The §9.3 column unit and every row's meta: a small machined panel holding one mono value. A label, not a target — --chip-h (24px), one line, its text never wraps. A row's chips sit on one line; what does not fit fades at the edge.",
"html": "<span class=\"chip readout\">2160p</span>",
"css": ".chip { display: inline-flex; align-items: center; gap: var(--space-1); height: var(--chip-h); padding: 0 var(--space-2); background: var(--panel-raised); border: 1px solid var(--line); border-radius: 3px; font-family: var(--font-readout); font-size: var(--text-2xs); white-space: nowrap; color: var(--ink-muted); }"
},
{
"name": "Verdict chip",
"kind": "custom",
"refersTo": "verdict-eligible",
"description": "Release classification (§9.3): eligible / waived / rejected. Hue + border treatment + the word, so the three buckets survive with colour removed — eligible is a solid tinted border, waived a dashed border (the visible mark of a relaxed rule), rejected is quiet slate and always carries the killing rule's name. Rejected is the policy working, never fault red.",
"html": "<span class=\"chip readout\" data-verdict=\"waived\">waived · pt missing</span>",
"css": ".chip[data-verdict=\"eligible\"] { color: var(--verdict-eligible); border-color: oklch(from var(--verdict-eligible) l c h / 45%); } .chip[data-verdict=\"waived\"] { color: var(--verdict-waived); border-style: dashed; border-color: oklch(from var(--verdict-waived) l c h / 55%); } .chip[data-verdict=\"rejected\"] { color: var(--verdict-rejected); }"
},
{
"name": "Status chip",
"kind": "custom",
"refersTo": "status-airing",
"description": "Library status (§4.2): airing / incomplete / waiting / complete / ended. Activity is channel violet (airing); satisfaction is signal green (complete, ended, a full N/M count); incomplete, waiting and a partial count are neutral ink. Amber never appears here — it is reserved for what needs the operator. The mono word is always present.",
"html": "<span class=\"chip readout\" data-status=\"airing\">airing</span>",
"css": ".chip[data-status=\"airing\"] { color: var(--status-airing); border-color: oklch(from var(--status-airing) l c h / 45%); } .chip[data-status=\"incomplete\"] { color: var(--ink); border-color: var(--line-strong); } .chip[data-status=\"complete\"], .chip[data-status=\"ended\"], .chip[data-counts=\"complete\"] { color: var(--signal-ok); border-color: oklch(from var(--signal-ok) l c h / 45%); } .chip[data-counts=\"partial\"] { color: var(--ink); }"
},
{
"name": "Media state chip",
"kind": "custom",
"refersTo": "signal-ok",
"description": "§4.2's per-title state chip. Every state keeps the word, with one drawn exemption: `available` renders as a check glyph instead of the word `available` — a shape, not only a hue, so it survives a greyscale read the rule otherwise protects. The word moves to the chip's aria-label (exposed via role=\"img\", since a bare span's aria-label is not reliably read).",
"html": "<span class=\"chip readout\" role=\"img\" aria-label=\"available\" data-movie-state=\"available\"><svg viewBox=\"0 0 16 16\" width=\"12\" height=\"12\"><path d=\"M3.2 8.4l3 3 6.6-6.8\" fill=\"none\" stroke=\"currentColor\" stroke-width=\"1.6\" stroke-linecap=\"round\" stroke-linejoin=\"round\"/></svg></span>",
"css": ".chip[data-movie-state=\"available\"] { color: var(--signal-ok); border-color: oklch(from var(--signal-ok) l c h / 45%); } .chip[data-movie-state=\"missing\"][data-wanted=\"true\"] { color: var(--ink); border-color: var(--line-strong); } .chip[data-movie-state=\"downloading\"] { color: var(--status-airing); border-color: oklch(from var(--status-airing) l c h / 45%); }"
},
{
"name": "Score lead",
"kind": "custom",
"refersTo": "score-heat",
"description": "The release row's lead (§9.3): a 44px square carrying the score on the list-relative heat scale (issue 111) — seven stops from the lowest-scoring candidate on screen (red) to the highest (green).",
"html": "<span class=\"score\" data-score=\"6\" aria-label=\"score 128\">128</span>",
"css": ".score { display: inline-grid; place-items: center; width: var(--control-h); height: var(--control-h); font: 700 var(--text-sm) var(--font-readout); border: 1px solid var(--line); border-radius: var(--radius); } .score[data-score=\"6\"] { color: var(--score-6); border-color: oklch(from var(--score-6) l c h / 50%); }"
},
{
"name": "Module (channel strip)",
"kind": "card",
"refersTo": "ground",
"description": "One unit on the chain: lamp + Rajdhani name + mono status word, role label, mono detail. Panel with hairline border and 1px inset highlight; 4px machined radius, never a soft card.",
"html": "<article class=\"module\"><header class=\"module-head\"><span class=\"lamp\" data-state=\"ok\" aria-hidden=\"true\"></span><h2 class=\"module-name\">prowlarr</h2><span class=\"module-status readout\" data-tone=\"ok\">ok</span></header><p class=\"module-role\">indexers in</p><p class=\"module-detail readout\">torznab search and rss</p></article>",
"css": ".module { background: var(--panel); border: 1px solid var(--line); border-radius: var(--radius); box-shadow: inset 0 1px var(--highlight); padding: var(--space-4) var(--space-4) var(--space-3); }"
},
{
"name": "Bus trace",
"kind": "custom",
"refersTo": "ground",
"description": "Signal path between modules: hairline + arrowhead SVG, tethered to its source module's row. Lit with the source's signal hue via data-tone; inert gray when nothing flows.",
"html": "<svg viewBox=\"0 0 40 8\" preserveAspectRatio=\"none\" class=\"bus-trace\" data-tone=\"ok\" aria-hidden=\"true\"><line x1=\"0\" y1=\"4\" x2=\"32\" y2=\"4\" /><path d=\"M32 0.5 39 4 32 7.5 Z\" class=\"bus-arrow\" /></svg>",
"css": ".bus-trace { --trace: var(--line-strong); } .bus-trace line { stroke: var(--trace); } .bus-arrow { fill: var(--trace); } .bus-trace[data-tone=\"ok\"] { --trace: var(--signal-ok); }"
},
{
"name": "Control",
"kind": "button",
"refersTo": "accent",
"description": "Five controls, one rule for words versus icons: icons in rows, words in headers and panels; a row may carry one word control only when that verb is why the row exists (GRAB, ALLOW ENGLISH). Primary: cyan mono uppercase on a raised plate, one per header or panel. Quiet (.control-quiet): ink on a hairline — cancel, add, retry; never a toggle. Icon (.control-icon): a 44px square glyph, aria-label is the name. Fixed (.control-fixed): a word whose label changes (GRAB → SENDING → SENT) keeps one width. Destructive ([data-kind=delete]): rests red, arms to an amber check in the same square, fires on the second tap, disarms after 4 s; the explanation goes in the row's status slot, never inside the button. One verb, one form: search is the search glyph in a row and \"search indexers\" in a header; open is the row itself; trailer is the play glyph (plus the word from 40rem).",
"html": "<button type=\"button\" class=\"control\">probe</button>",
"css": ".control { display: inline-flex; align-items: center; justify-content: center; gap: var(--space-2); min-height: var(--control-h); padding: 0 var(--space-4); font-family: var(--font-readout); font-size: var(--text-xs); font-weight: 600; text-transform: uppercase; letter-spacing: 0.08em; color: var(--accent); background: var(--panel-raised); border: 1px solid var(--line-strong); border-radius: var(--radius); } .control-icon { width: var(--control-h); padding: 0; } .control[data-armed=\"true\"] { color: var(--ground); background: var(--signal-warn); border-color: var(--signal-warn); }"
},
{
"name": "Rail",
"kind": "nav",
"refersTo": "ground",
"description": "One sticky line (--rail-h) on a panel ground: master lamp and wordmark, then — from 40rem — the destination links (library, queues with its amber count, settings), the search field and, from 64rem, the version readout. Below 40rem the destinations live in the tab bar and the field opens over the rail from a search glyph. The lamp beside the wordmark is the only header status signal.",
"html": "<header class=\"rail\"><div class=\"rail-inner\"><div class=\"rail-id\"><span class=\"lamp\" data-state=\"ok\" aria-hidden=\"true\"></span><a class=\"wordmark\" href=\"/\">arr</a></div><nav class=\"rail-nav\">…</nav><div class=\"rail-search\">…</div></div></header>",
"css": ".rail { position: sticky; top: 0; padding-top: var(--safe-top); border-bottom: 1px solid var(--line); background: var(--panel); box-shadow: inset 0 1px var(--highlight); } .rail-inner { display: flex; align-items: center; gap: var(--space-3); max-width: 68rem; height: var(--rail-h); margin-inline: auto; padding-inline: var(--gutter); }"
},
{
"name": "Row",
"kind": "list",
"refersTo": "ground",
"description": "The one list primitive (web/src/ui.ts `row()`): a grid of lead | body | actions plus a full-width tray. The body is minmax(0, 1fr), so a long title or a run of chips is clipped inside it and can never push the actions onto a second line. The body holds at most a title line, a meta line of chips (priority-2 chips from 40rem) and a sub line (evidence, full on a tap). The action column has fixed slots per row kind — icon, toggle or word width — and an empty slot keeps its width, so a kind keeps one column. On a phone a row shows at most its primary action plus ⋯, which opens the other actions, labelled, in the tray. A row that opens something is a stretched link under the controls, marked by a chevron — never a fake button.",
"html": "<li class=\"r\" data-row=\"episode\"><div class=\"r-lead\">E09</div><div class=\"r-body\"><div class=\"r-title\">The Last Signal</div><div class=\"r-meta\">…chips</div></div><div class=\"r-act\"><span class=\"r-slot\" data-width=\"icon\">…</span></div><div class=\"r-tray\">…</div></li>",
"css": ".r { display: grid; grid-template-columns: auto minmax(0, 1fr) auto; grid-template-areas: \"lead body act\" \"tray tray tray\"; column-gap: var(--space-3); min-height: var(--row-min); border-bottom: 1px solid oklch(from var(--line) l c h / 60%); }"
},
{
"name": "Lamp toggle",
"kind": "toggle",
"refersTo": "accent",
"description": "A rule that is on or off (wanted, tracked, targeted search, track future seasons): a small lamp, the label and a fixed-width on/off word. On is a lit cyan lamp and the word in cyan; off is a dark lamp and a faint word — never a grey plate that reads as disabled.",
"html": "<button class=\"toggle\" aria-pressed=\"true\"><span class=\"toggle-lamp\"></span><span class=\"toggle-label\">wanted</span><span class=\"toggle-state\">on</span></button>",
"css": ".toggle[aria-pressed=\"true\"] .toggle-lamp { background: var(--accent); box-shadow: 0 0 6px oklch(from var(--accent) l c h / 60%); } .toggle-state { min-width: 3ch; }"
},
{
"name": "Disclosure",
"kind": "button",
"refersTo": "accent",
"description": "Show / hide at full control height with a turning chevron: collapsed buckets (\"show 93\"), paged lists (\"show 103 more\"). Tabular digits, so the label never changes width. A season row's lead is the same idea as an icon control.",
"html": "<button class=\"control control-quiet disclose\" aria-expanded=\"false\"><span class=\"control-word\">show 93</span><svg class=\"icon\">…</svg></button>",
"css": ".disclose { justify-content: space-between; min-width: 9rem; }"
},
{
"name": "Segmented",
"kind": "toggle",
"refersTo": "accent",
"description": "One choice of a few, joined: library grid/list, the search kind filter, a subtitle language picker. The engaged side is lit with an inset cyan edge so joined borders never double.",
"html": "<fieldset class=\"segmented\"><button class=\"seg\" aria-pressed=\"true\">all</button><button class=\"seg\" aria-pressed=\"false\">movies</button></fieldset>",
"css": ".seg[aria-pressed=\"true\"] { color: var(--accent-bright); background: var(--panel-raised); box-shadow: inset 0 0 0 1px var(--accent); }"
},
{
"name": "Tab bar",
"kind": "nav",
"refersTo": "ground",
"description": "Below 40rem only: four destinations within thumb reach — library, search, queues (always present, amber count badge), settings — over the safe-area inset. The active destination is lit from the route, not from a tap, so deep links and back light the right one.",
"html": "<nav class=\"tabbar\"><a class=\"tab\" href=\"/\" aria-current=\"page\">…library</a>…</nav>",
"css": ".tabbar { position: fixed; bottom: 0; display: grid; grid-template-columns: repeat(4, 1fr); height: var(--tabbar-space); padding-bottom: var(--safe-bottom); background: var(--panel); border-top: 1px solid var(--line); }"
},
{
"name": "Detail page",
"kind": "layout",
"refersTo": "ground",
"description": "A back control and the title open every detail page. The hero is a fixed grid — poster box, chip line, rating and meta lines, three reserved lines of overview (a tap opens the rest) — that data fills without adding rows. Then one action bar: the primary word (search indexers), the trailer, and ⋯, which opens the page's settings: the external links, the rule toggles, the root and remove.",
"html": "<header class=\"page-head\">…</header><div class=\"hero-body\">…</div><div class=\"actionbar\">…</div>",
"css": ".hero-body { display: grid; grid-template-columns: 6rem minmax(0, 1fr); gap: var(--space-4); }"
}
],
"narrative": {
"northStar": "Master Control",
"overview": "arr's UI is a broadcast master-control panel: the daemon is a signal chain (TMDB and Prowlarr feed in, Transmission is driven out) and every surface reads as lamps, readouts and traces on that chain. Near-black charcoal ground, machined panels with hairline borders and a 1px inset highlight, Rajdhani display names, monospace readouts, three semantic lamp hues plus one phosphor-cyan interactive hue. Committed dark. Built for the operator's one-glance question: can arr do its job, and if not, which upstream is down.",
"keyCharacteristics": [
"Signal chain, not dashboard: topology mirrors DESIGN.md §3 (now a settings section); no sidebar, no stat cards, no hero metric. Phone first: a sticky one-line rail and a bottom tab bar.",
"Lamps carry state, words carry proof — every hue is paired with a mono status word.",
"Rajdhani 700 uppercase for names, system sans for micro-labels, mono for every value.",
"Panels are machined: hairline border, inset highlight, 4px radius; never soft shadows or glass.",
"One authored motion: the power-up strike, upstream to downstream, once."
],
"rules": [
{
"name": "The Lamp-Hue Rule",
"body": "Green, amber and red belong to state and to nothing else; amber means one thing — this needs you, or is armed. Interaction is phosphor-cyan. Wanted-but-missing, partial counts and rating stars are ink, not amber. A saturated colour that is neither a state nor an interactive affordance is a bug.",
"section": "colors"
},
{
"name": "The Word-Beside-The-Lamp Rule",
"body": "Every lamp and lit trace is paired with a monospace status word. Remove all color and the board must still read.",
"section": "colors"
},
{
"name": "The Readout Rule",
"body": "Monospace is for values the operator reads — statuses, sizes, latencies, versions, paths — always with tabular numerals. Prose and labels are never mono. Display (Rajdhani) carries page titles, section titles and module names; row titles are the label face, one line.",
"section": "typography"
},
{
"name": "The Machined-Panel Rule",
"body": "Depth is one inset 1px highlight on a hairline-bordered panel. No drop shadows, no glass, no gradients. The only glow on the board is a lamp's own light.",
"section": "elevation"
},
{
"name": "The Verdict Rule",
"body": "Release verdicts are eligible green, waiver amber, rejected slate. Rejected is the policy engine doing its job, so it is quiet neutral — fault red stays reserved for the daemon's own failures. Each bucket also carries a non-colour mark: solid tinted border (eligible), dashed border (waived), the killing rule's name (rejected).",
"section": "colors"
},
{
"name": "The Status-Is-Not-Severity Rule",
"body": "The five library statuses are informational, never an error ramp. Activity is violet (airing, downloading); satisfaction is green (complete, ended, a full count); incomplete, waiting and a partial count are neutral ink. Amber never appears on a status.",
"section": "colors"
},
{
"name": "The Token Rule",
"body": "Components consume the custom properties declared in :root of web/src/style.css — never a literal colour, margin, padding or gap. web/scripts/check-tokens.mjs enforces this in CI; relative-colour derivation from a token (oklch(from var(--x) …)) counts as consuming the token.",
"section": "colors"
},
{
"name": "The Dead-Air Rule",
"body": "When nothing is flowing, nothing animates. Pulse means probing; data-state=\"off\" is dark and still. Motion that misreports activity is a truth bug.",
"section": "motion"
},
{
"name": "The Check-Glyph Exemption",
"body": "The one state chip drawn instead of worded: `available` is a check glyph, because a drawn shape survives the greyscale read the Word-Beside-The-Lamp doctrine otherwise protects with text alone. The word is not deleted — it moves to the chip's aria-label. No other state gets this treatment; `incomplete` and `waiting` have no unambiguous glyph, so they keep the word on the chip.",
"section": "colors"
},
{
"name": "The List-Relative Heat Rule",
"body": "The release row's score lead (issue 111) is not an absolute quality scale — its seven stops are relative to the lowest and highest score on screen right now. Colour there answers \"which of these\", not \"how good is this release in general\".",
"section": "colors"
},
{
"name": "The Row Rule",
"body": "Every list is the one row primitive. Its action column never wraps and keeps fixed slots per row kind; the body clips, the actions do not move. A phone row shows its primary action plus ⋯; the rest are labelled in the tray.",
"section": "layout"
},
{
"name": "The Icons-In-Rows Rule",
"body": "Rows repeat, so their actions are 44px glyph squares with an aria-label. Headers, panels and forms appear once, so they spell the action out. A row carries a word control only when that verb is why the row exists. One verb has one glyph everywhere.",
"section": "components"
},
{
"name": "The Reserve-The-Space Rule",
"body": "Render the final layout empty, then fill it. Status lines are slots that keep their line; first loads paint skeleton rows at --row-min; the hero's poster box and text lines exist before their data; feedback changes a control's label at a fixed width; polled chips sit last on their line; long lists page at 25. Nothing is inserted above content after it paints.",
"section": "layout"
},
{
"name": "The Tap-To-Explain Rule",
"body": "Touch has no hover, so no meaning lives only in a tooltip. A chip whose sentence will not fit (a waiver, a download's rate, an import failure) is a button that writes the sentence into its row's status slot; a group's long note opens from an info glyph.",
"section": "components"
}
],
"dos": [
"Do build every list from the row primitive and every button from the five controls in web/src/ui.ts.",
"Do keep every control at --control-h (44px on touch), focus rings cyan and visible, and reduced motion honoured.",
"Do write the phone layout first and add from min-width 40rem / 64rem, or from container width for components.",
"Do keep muted text at or above 4.5:1 on panel ground (--ink-muted floor).",
"Do self-host every asset; the SPA is embedded in the binary and must work with no network.",
"Do take every colour, spacing and font-size from the :root tokens; web/scripts/check-tokens.mjs fails CI on literals and on any var() that names a token nothing defines.",
"Do suppress a redundant status chip where another control on the same row already implies the exact same state — the missing chip disappears from episode rows because the wanted toggle only ever renders for that state."
],
"donts": [
"Don't let a row's actions wrap, or vary the action column between rows of one kind.",
"Don't put a span styled as a control inside a clickable row; the row is the link.",
"Don't toggle a status line's visibility above content, or change a button's width to report an outcome.",
"Don't use amber for anything that does not need the operator; don't use fault red for a rejected release.",
"Don't introduce a second interactive hue or use cyan for a status.",
"Don't box content in soft-shadowed rounded cards or add glass/blur.",
"Don't put a kicker/eyebrow label above a heading.",
"Don't animate idle or dead elements; the strike runs once, on real data."
]
}
}