@yemi33/minions 0.1.2448 → 0.1.2449

package/docs/design-language.md

@@ -0,0 +1,1051 @@
+# Minions Design Language
+
+> A code-derived specification of the Minions dashboard visual and interaction
+> system. Every rule below is traceable to a concrete token, selector, HTML
+> fragment, or JavaScript renderer in `dashboard/`. Treat this as both an
+> **implementation guide** (convert another app to the Minions language) and an
+> **audit standard** (grade new and existing Minions UI objectively).
+
+**Scope.** This covers the two live front-ends served by `dashboard.js`:
+
+- **Classic UX** — the default multi-page SPA. Canonical stylesheet
+  `dashboard/styles.css`; shell `dashboard/layout.html`; page fragments
+  `dashboard/pages/*.html`; renderers `dashboard/js/*.js`.
+- **Slim UX** — a feature-flagged (`slim-ux`) single-screen cockpit. Self-contained
+  stylesheet `dashboard/slim/styles.css`; shell `dashboard/slim/layout.html` +
+  `dashboard/slim/body.html`; renderers `dashboard/slim/js/*.js`.
+
+Both are assembled into one HTML string at startup by `dashboard-build.js` and
+served from disk on each request (no build step). The two stylesheets are
+**served independently** and intentionally duplicate their token blocks; a
+tripwire test keeps the shared values in lockstep (see
+[§13 Known inconsistencies](#13-known-inconsistencies--legacy-exceptions)).
+
+> **Golden rule.** The design language lives in CSS custom properties declared
+> in the `:root` blocks of the two stylesheets. New UI MUST consume tokens, never
+> raw hex or raw `Npx`. Ad-hoc values are the single most common audit failure.
+
+---
+
+## Table of contents
+
+1. [Design principles & personality](#1-design-principles--personality)
+2. [Color system](#2-color-system)
+3. [Typography](#3-typography)
+4. [Spacing, radii, shadows, motion](#4-spacing-radii-shadows-motion)
+5. [Layout & page shells](#5-layout--page-shells)
+6. [Components](#6-components)
+7. [Status & content language](#7-status--content-language)
+8. [Interaction states & accessibility](#8-interaction-states--accessibility)
+9. [Classic vs Slim: shared foundations vs intentional differences](#9-classic-vs-slim-shared-foundations-vs-intentional-differences)
+10. [Reusable implementation patterns](#10-reusable-implementation-patterns)
+11. [Migration playbook (adopt Minions in another app)](#11-migration-playbook)
+12. [Audit rubric & checklist](#12-audit-rubric--checklist)
+13. [Known inconsistencies & legacy exceptions](#13-known-inconsistencies--legacy-exceptions)
+
+---
+
+## 1. Design principles & personality
+
+Minions is **mission control for an autonomous agent fleet** — a dense,
+always-on operator dashboard, not a marketing surface. The visual language is
+derived directly from its implementation and reflects five principles:
+
+1. **Dark, terminal-adjacent, GitHub-native.** The palette is GitHub's Primer
+   dark scale (`#0d1117` canvas, `#161b22` surface, `#30363d` border, `#58a6ff`
+   blue). Operators live in GitHub, ADO, and terminals all day; the dashboard
+   sits beside them without a jarring context switch. There is **no light theme**
+   — dark is the only mode (see [§2](#2-color-system)).
+
+2. **Information density over whitespace.** Tight spacing (`2/4/6/8px` base
+   rhythm), a `12px` type floor for readable metadata, uppercase micro-labels,
+   and `tabular-nums` for aligned counters. The sidebar is a fixed `150px`; cards
+   and tables pack many rows per viewport. Compare a consumer app's airy
+   `24px` gutters — Minions deliberately uses `--space-4: 8px` as its workhorse.
+
+3. **Color is semantic, never decorative.** Each accent hue maps to a fixed
+   meaning: **green = success/create/go**, **red = failure/destroy/stop**,
+   **yellow/amber = in-progress/attention**, **blue = active/primary/info**,
+   **purple = merged/agent/review**, **muted grey = idle/neutral/disabled**. A
+   badge's color IS its status. Never pick a hue for looks (see
+   [§7](#7-status--content-language)).
+
+4. **State is always legible at a glance.** Every agent, work item, PR, plan,
+   dispatch, and engine has a color-coded badge plus, where it matters, motion
+   (a pulsing dot = live/working, a dashed border = stale/needs-attention). An
+   operator should read fleet health from across the room.
+
+5. **Progressive disclosure through panels & modals.** The surface stays calm;
+   detail lives one click deep. Cards open modals (`.modal-bg` / `.modal`), the
+   modal stack supports depth up to 5 (`.modal-stack-chip`), and the Command
+   Center is a right-hand drawer, not a page.
+
+**Interaction philosophy.** Optimistic UI (flip a toggle, then await the API),
+non-blocking async refresh (`/api/status` polled every 4s), hover-to-preview /
+click-to-open, and keyboard-reachable focus rings on every interactive element.
+Destructive actions route through a promise-based confirm dialog
+(`dashboard/js/confirm-dialog.js`), never `window.confirm`.
+
+---
+
+## 2. Color system
+
+### 2.1 Source of truth
+
+All colors are CSS custom properties in the `:root` block of each stylesheet.
+**Classic:** `dashboard/styles.css:10-12`. **Slim:** `dashboard/slim/styles.css:13-25`.
+Never write a raw hex outside these blocks; the only sanctioned literals are the
+`rgba(...)` tint fills derived from these hues (see [§2.4](#24-tint-fills)) and
+the one audited scoped token block slim declares for the reused detail panel
+(`dashboard/slim/styles.css:1859-1865` — see [§2.3](#23-palette-tokens-that-diverge-classic-vs-slim)
+and §13 item 10).
+
+### 2.2 Core palette (shared foundation)
+
+These seven tokens are **byte-identical** across Classic and Slim and form the
+neutral + primary spine:
+
+| Token        | Hex       | Semantic role                                             |
+| ------------ | --------- | --------------------------------------------------------- |
+| `--bg`       | `#0d1117` | App canvas / page background, input backgrounds           |
+| `--surface`  | `#161b22` | Header, sidebar, modals, table sticky headers, raised bars|
+| `--border`   | `#30363d` | Hairline borders, dividers, default (idle) button borders |
+| `--muted`    | `#8b949e` | Secondary text, metadata, timestamps, disabled/idle state |
+| `--blue`     | `#58a6ff` | Primary action, active state, links, info, focus rings    |
+| `--green`    | `#3fb950` | Success, create/add, approve, build-pass, "go"            |
+| `--red`      | `#f85149` | Failure, destroy/delete, changes-requested, build-fail    |
+
+### 2.3 Palette tokens that diverge Classic vs Slim
+
+These carry the **same semantic role** but different hex. The table describes
+slim's **global** `:root` (`dashboard/slim/styles.css:13-56`) — see the scoped
+token island below before auditing a rule. Do **not** assume parity — the
+divergence is real and load-bearing (see
+[§13](#13-known-inconsistencies--legacy-exceptions)):
+
+| Token        | Classic (`styles.css`) | Slim `:root` (`slim/styles.css`) | Role                                   |
+| ------------ | ---------------------- | -------------------------------- | -------------------------------------- |
+| `--surface2` | `#21262d`              | `#1c2128`                        | Cards, chips, nested panels, row hover |
+| `--text`     | `#e6edf3`              | `#c9d1d9`                        | Primary body text                      |
+| in-progress  | `--yellow: #d29922`    | `--amber: #d29922`               | Working / building (same hex, diff name)|
+| `--orange`   | `#e3b341`              | `#ea580c`                        | Attention / stale / fan-out            |
+| `--purple`   | `#bc8cff`              | *(not in slim `:root`)*          | Merged / agent / review / archive      |
+
+> **Audit note.** Slim names its in-progress token `--amber` and Classic names it
+> `--yellow`, but both resolve to `#d29922`. Slim's `--orange` (`#ea580c`, a hotter
+> red-orange) and Classic's `--orange` (`#e3b341`, a golden amber) genuinely
+> differ. Reference the token by name; never hard-code the hex.
+
+> 🔑 **Scoped token island — slim is not token-poor everywhere.** Beyond its
+> global `:root`, slim re-declares the **full Classic token set** scoped to the
+> reused agent detail panel: `--yellow`, `--purple`, `--orange` (at the *Classic*
+> `#e3b341`, not slim's `#ea580c`), `--radius-sm..--radius-full`,
+> `--transition-fast/base/slow`, and `--space-1..--space-9` at the *Classic* 2px
+> values — all under `#detail-panel, #detail-overlay`
+> (`dashboard/slim/styles.css:1859-1865`). It exists so the panel rules mirrored
+> verbatim from Classic (`dashboard/slim/styles.css:1867-1974`) resolve to
+> Classic values **without** disturbing slim's global palette. Consequence for
+> auditors: `var(--purple)` is *valid* in a panel descendant — e.g.
+> `.dispatch-type.review` (`:1914`) and `.dispatch-type.decompose` (`:1923`) —
+> and *invalid* anywhere else in slim. Always resolve the selector's scope before
+> flagging a slim token reference (§13 item 10).
+
+### 2.4 Tint fills
+
+Accent backgrounds are the accent hue at **~15% opacity** with a **solid 1px
+border** at full opacity. This "ghost chip" pattern is the entire badge/pill
+system. Canonical values (`dashboard/styles.css:769-774`):
+
+```css
+.badge-blue   { background: rgba(88,166,255,0.15); color: var(--blue);   border: 1px solid var(--blue); }
+.badge-green  { background: rgba(63,185,80,0.15);  color: var(--green);  border: 1px solid var(--green); }
+.badge-red    { background: rgba(248,81,73,0.15);  color: var(--red);    border: 1px solid var(--red); }
+.badge-yellow { background: rgba(210,153,34,0.15); color: var(--yellow); border: 1px solid var(--yellow); }
+.badge-purple { background: rgba(188,140,255,0.15);color: var(--purple); border: 1px solid var(--purple); }
+.badge-muted  { background: var(--surface);        color: var(--muted);  border: 1px solid var(--border); }
+```
+
+Hover tints on action buttons use **~10%** opacity of the same hue
+(`.btn-add:hover { background: rgba(63,185,80,0.1); }`,
+`dashboard/styles.css:568`). Emphasis variants step up to `0.22`–`0.25` and swap
+to a **dashed** or **2px** border (`.pr-badge.build-escalated`,
+`dashboard/styles.css:441`).
+
+> The `rgba()` literals restate the hex of the corresponding token. This is the
+> one sanctioned exception to "no raw color" — CSS cannot yet apply alpha to a
+> custom property without `color-mix`, which the codebase does not use. When you
+> add a tinted surface, reuse the exact `rgba` triplet already used for that hue
+> elsewhere; do not introduce a new opacity step without cause.
+
+### 2.5 Off-palette accent literals (observed, constrained)
+
+A handful of dispatch/type chips use raw hex for hues with no token, in
+`dashboard/styles.css:1089-1098`:
+
+- `#a855f7` — `plan` / `plan-to-prd` dispatch type (violet, distinct from `--purple`)
+- `#38bdf8` — `docs` dispatch type (sky)
+- `#14b8a6` — `setup` dispatch type (teal)
+
+**Observed vs canonical:** these are intentional type-taxonomy colors with no
+`:root` token. Recommended canonical guidance: if you add a new dispatch/work
+type chip, follow the same tint pattern (`rgba(...,0.15)` fill + solid text
+color) and, if the hue recurs, promote it to a `:root` token. Do not scatter new
+raw hex for one-off UI.
+
+### 2.6 Light/dark & contrast
+
+There is **no light mode**. All contrast targets assume the dark canvas.
+Expectations:
+
+- Body text `--text` on `--bg`/`--surface`: comfortably exceeds WCAG AA (7:1+).
+- `--muted` (`#8b949e`) on `--bg` is the **contrast floor** (~AA for normal text
+  ≥ the `12px` type floor). Do **not** put `--muted` below `12px` for
+  reading text — that combination fails; the type system enforces a `12px` floor
+  precisely for this reason (see [§3.4](#34-the-12px-readability-floor)).
+- Accent text (`--blue`, `--green`, `--red`, etc.) is only used at badge/label
+  weight (`font-weight: 600`, uppercase) on its matching `0.15` tint, which
+  preserves legibility. Never use a `0.15` tint as text color.
+
+**Prohibited:**
+- Raw hex or named CSS colors (`#fff`, `white`, `black`) outside the `:root`
+  blocks — with the audited exceptions `#fff` for text-on-solid-accent buttons
+  (`.btn-primary`, `dashboard/styles.css:539`) and the `rgba(0,0,0,…)` shadow /
+  modal-backdrop scrims.
+- Introducing a second neutral scale, a light theme, or a gradient background
+  (the only gradients are the intentional "Try Slim UX" shimmer animation,
+  `dashboard/styles.css:966`).
+
+---
+
+## 3. Typography
+
+### 3.1 Font families
+
+- **UI:** `'Segoe UI', system-ui, sans-serif` (Classic body,
+  `dashboard/styles.css:72`; Slim adds `-apple-system, BlinkMacSystemFont`,
+  `dashboard/slim/styles.css:86`).
+- **Monospace:** `Consolas, monospace` for IDs, branch names, feature IDs, code
+  (`.mono`, `dashboard/styles.css:795`; `.feat-id`, `:510`).
+- **Inline code:** `--text-code: 0.9em` — the one relative token, so code reads
+  10% smaller than its surrounding text (`dashboard/styles.css:49`).
+
+### 3.2 Size primitives (single source of truth)
+
+Declared once per stylesheet (`dashboard/styles.css:31-33`), documented in
+`dashboard/docs/typography.md`. **Never hand-roll a `font-size: Npx`** — a
+tripwire test (`test/unit/dashboard-font-size-tokens.test.js`) fails CI if a raw
+px/em font-size leaks in.
+
+| Token            | Base  | Common use                                              |
+| ---------------- | ----- | ------------------------------------------------------- |
+| `--text-xs`      | 10px  | Reserved dense chrome only (below the readability floor) |
+| `--text-sm`      | 12px  | Status badges, chip / tag labels                        |
+| `--text-base`    | 12px  | Captions, secondary metadata, dense table cells         |
+| `--text-md`      | 13px  | Detail tables, button labels, slim chat body            |
+| `--text-lg`      | 14px  | Body text, modal textarea, card titles                  |
+| `--text-xl`      | 16px  | Main `<body>` font, secondary headers, chat input       |
+| `--text-2xl`     | 18px  | Section headers, page headers, modal h3                 |
+| `--text-stat`    | 22px  | Stat counter readouts, member emoji glyphs              |
+| `--text-stat-lg` | 28px  | Larger stat readouts, completion type emoji             |
+| `--text-display` | 32px  | Page hero, markdown H1, agent-detail emoji              |
+| `--text-code`    | 0.9em | Inline `<code>` (relative)                              |
+
+Each primitive is `calc(<base>px * var(--minions-text-scale))`. Classic pins
+`--minions-text-scale: 1.05` (a global +5% bump); Slim pins it to `1`. The base
+px values **must** match between the two stylesheets.
+
+### 3.3 Role aliases (preferred for new code)
+
+Semantic names that point at primitives (`dashboard/styles.css:42-49`). Prefer
+these — they survive a size redesign without callsite edits:
+
+| Role token            | Alias → size        | Intended use                             |
+| --------------------- | ------------------- | ---------------------------------------- |
+| `--text-role-display` | `--text-display`    | Page hero, dashboard title               |
+| `--text-heading`      | `--text-2xl` (18px) | Section + modal headers                  |
+| `--text-subheading`   | `--text-xl` (16px)  | Secondary headers, card titles           |
+| `--text-body`         | `--text-lg` (14px)  | Default body text                        |
+| `--text-meta`         | `--text-md` (13px)  | Captions, timestamps, secondary metadata |
+| `--text-caption`      | `--text-base` (12px)| Small labels, table cells                |
+| `--text-micro`        | `--text-sm` (12px)  | Chip / tag pill labels                   |
+| `--text-code`         | `0.9em`             | Inline code                              |
+
+Utility classes mirror each role: `.text-display .text-heading .text-subheading
+.text-body .text-meta .text-caption .text-micro .text-code`
+(`dashboard/styles.css:80-87`). They set **only** `font-size`; weight, color, and
+line-height stay with the caller.
+
+### 3.4 The 12px readability floor
+
+`--text-sm` was raised to a **12px** base so it clears the readability floor in
+both stylesheets (Classic renders `12 × 1.05 = 12.6px`, Slim `12px`). `--text-xs`
+(10px) stays below the floor and is retained only at two genuinely dense chrome
+callsites (`.token-chart-labels span`, `.qa-phase-arrow`). See
+`dashboard/docs/typography.md` §"12px readability floor". **Do not** introduce
+new `--text-xs` reading text.
+
+### 3.5 Weight, case, and treatment conventions
+
+- **Section headers:** `text-transform: uppercase; letter-spacing: 1px; color:
+  var(--muted); font-weight: 600` at `--text-base` (`section h2`,
+  `dashboard/styles.css:114`). Uppercase micro-labels are a signature of the
+  language.
+- **Table headers:** uppercase, `letter-spacing: 0.5px`, `--muted`,
+  `font-weight: 500`, `--text-sm` (`.table th`, `:778`; `.pr-table th`, `:381`).
+- **Badges/pills:** uppercase, `font-weight: 600`, `--text-sm` (`.badge`, `:764`;
+  `.pr-badge`, `:428`).
+- **Body:** default weight, `--text` color; **bold** = `font-weight: 600` via
+  `.font-bold` (`:796`) — the design uses 600 as its "bold", not 700, except for
+  emphasis badges (`.dispatch-stat-num` 700, `:1073`).
+- **Numeric readouts:** `font-variant-numeric: tabular-nums` for timestamps and
+  counters (`.timestamp`, `:98`; `.modal-stack-chip`, `:1210`).
+
+### 3.6 Truncation & wrapping
+
+- Single-line ellipsis via `.truncate` (`white-space:nowrap; overflow:hidden;
+  text-overflow:ellipsis`, `:797`) — used for agent actions, dispatch tasks, PR
+  titles/branches, project branches. Always pair a truncated element with a
+  `title` attribute carrying the full text (see `_renderProjectBranch` note,
+  `dashboard/styles.css:1523`).
+- Multi-line content that must wrap uses `white-space: pre-wrap; word-break:
+  break-word` (`.modal-qa-a`, `:137`).
+
+### 3.7 Responsive type scaling
+
+Two independent mechanisms:
+
+1. **User zoom** — `[data-font-size]` on `<html>` drives `--minions-font-scale`
+   applied as body-level `zoom` (`small 1.0 / medium 1.08 / large 1.18 / xlarge
+   1.30`, `dashboard/styles.css:66-69,72`). Set in `<head>` before first paint
+   from `localStorage['minions:font-size']` (`dashboard/layout.html:13-19`).
+2. **Global bump** — `--minions-text-scale` (Classic `1.05`) is an actual
+   font-size change applied uniformly to every primitive.
+
+At `≤640px`, headers, stats, and tables shrink to smaller tokens (`.pr-table`
+→ `--text-base`, headers → `--text-xl`, `dashboard/styles.css:1470-1483`).
+
+---
+
+## 4. Spacing, radii, shadows, motion
+
+### 4.1 Spacing scale
+
+**Classic** — 9-step, `2px`-anchored (`dashboard/styles.css:15-16`):
+
+`--space-1:2 --space-2:4 --space-3:6 --space-4:8 --space-5:10 --space-6:12
+--space-7:16 --space-8:20 --space-9:24`
+
+**Slim (global `:root`)** — 5-step, `4px`-anchored `4/8/12/16/20` rhythm
+(`dashboard/slim/styles.css:30`):
+
+`--space-1:4 --space-2:8 --space-3:12 --space-4:16 --space-5:20`
+
+> **Critical divergence.** The `--space-N` tokens mean **different pixel values**
+> in the two stylesheets. `--space-4` = `8px` in Classic but `16px` in Slim. Never
+> copy a spacing rule between the two without re-mapping. Slim declares its own
+> scale precisely because it ships CSS independently. `--space-4: 8px` is the
+> Classic workhorse gutter (cards, flex gaps, table cells).
+
+> **Exception — the scoped token island.** Inside `#detail-panel,
+> #detail-overlay` slim re-declares the **Classic** 9-step 2px scale
+> (`--space-1..--space-9`, `dashboard/slim/styles.css:1863-1864`), so panel
+> descendants resolve `--space-4` to `8px`, not `16px`. Panel rules mirrored from
+> Classic into that subtree are therefore correct **unmapped** — the re-mapping
+> rule above governs slim's *global* surfaces only (§2.3, §13 item 10).
+
+### 4.2 Border radius (Classic, `dashboard/styles.css:52`)
+
+`--radius-sm:4px --radius-md:6px --radius-lg:8px --radius-xl:10px
+--radius-full:50%`
+
+- Buttons, inputs, small chips → `--radius-sm`.
+- Cards, dispatch items → `--radius-md` / `--radius-lg`.
+- Badges/pills → `--radius-xl` (`10px`, near-pill).
+- Dots/avatars → `--radius-full`.
+
+Slim's **global** `:root` collapses this to a single `--radius: 6px`
+(`dashboard/slim/styles.css:25`), but slim re-declares the whole
+`--radius-sm..--radius-full` ladder at the Classic values scoped to
+`#detail-panel, #detail-overlay` (`dashboard/slim/styles.css:1861`). So
+`var(--radius-xl)` resolves inside the slim detail panel and nowhere else in
+slim — check the selector's scope before flagging it (§2.3, §13 item 10).
+
+### 4.3 Shadows (Classic, `dashboard/styles.css:55-57`)
+
+`--shadow-sm: 0 1px 3px rgba(0,0,0,0.2)` · `--shadow-md: 0 2px 8px rgba(0,0,0,0.3)`
+· `--shadow-lg: 0 4px 16px rgba(0,0,0,0.4)`
+
+Shadows are **restrained** — used for hover lift on cards (`.agent-card:hover`,
+`:122`), floating buttons (`.ask-selection-btn`, `:157`), and elevated menus.
+The primary elevation signal is **border-color change**, not shadow. Focus glow
+uses a blue ring: `box-shadow: 0 0 0 3px rgba(88,166,255,0.12)`
+(`.cmd-input-wrap:focus-within`, `:811`).
+
+### 4.4 Motion (Classic, `dashboard/styles.css:60`)
+
+`--transition-fast:0.15s --transition-base:0.2s --transition-slow:0.3s`
+
+- Hover/color transitions → `--transition-fast` / `--transition-base`.
+- Card transforms → `--transition-slow`.
+- **Live-state animations** are the semantic motion vocabulary:
+  - `pulse` (2s opacity, `:97`) — the live "engine running" dot (`.pulse`),
+    working badges, stuck warnings.
+  - `dotPulse` (1.2s, `:145`) — loading "typing" dots (QA, notif-processing).
+  - `notifPulse` (2s, `:1251`) — red unread notification dot.
+  - `planPulse` / `wipPulse` / `prdWipPulse` / `plSegPulse` — WIP emphasis on
+    plan/PRD/pipeline nodes.
+- **Reduced motion:** honor `@media (prefers-reduced-motion: reduce)`
+  (`.try-slim-ux-btn` animation disabled, `:982`). One deliberate exception is
+  documented inline at `:1000` (the Command Center sweep). New decorative
+  animation MUST respect the reduced-motion query.
+
+---
+
+## 5. Layout & page shells
+
+### 5.1 Classic shell (`dashboard/layout.html`)
+
+```
+<body>  (flex column, height 100%, overflow hidden, zoom = font-scale)
+ ├─ <header>            sticky, --surface, bottom border, title + engine badge + tools
+ ├─ .engine-alert       cross-page alert strip
+ ├─ .paused-banner      sticky kill-switch banner (pollingPaused / autoFixPaused)
+ ├─ #cc-drawer          Command Center right drawer (420px, fixed)
+ └─ .page-layout        flex row, flex:1, overflow hidden
+     ├─ .sidebar        150px fixed, --surface, right border, sticky
+     └─ .page-content   flex:1, scrollable; holds .page fragments (one .active)
+```
+
+Key rules:
+- **Header** — `dashboard/styles.css:89-98`. Sticky, `z-index:100`. `h1` is
+  `--text-2xl`, `font-weight:600`, `--blue`, `letter-spacing:0.5px`, with a muted
+  `<span>` suffix.
+- **Sidebar** — `:105-111`. Fixed `150px`; links are `--muted` → `--text` on
+  hover, active link gets a `3px` `--blue` left border + `--surface2` bg + 600
+  weight. Each link carries a `.sidebar-count` pill and optional `.notif-badge`.
+- **Pages** — `.page { display:none }`, `.page.active { display:block }` (`:112`).
+  Single-page-at-a-time; sidebar nav swaps `.active`.
+- **Section** — `section { padding: 20px 24px; border-bottom: 1px solid
+  var(--border) }` (`:101`); `section h2` is the uppercase muted micro-header
+  with an optional `.count` chip (`:114-115`).
+- **Embed mode** — `?embed=1` adds `.embed` to `<html>` to strip chrome (header,
+  sidebar, banners) so a page can be iframed as just its panel
+  (`dashboard/layout.html:20-32`).
+
+### 5.2 Slim shell (`dashboard/slim/layout.html` + `body.html`)
+
+A three-region cockpit — **ACTIONS / STATUS / HISTORY** — built from `.panel`
+grid areas (`dashboard/slim/styles.css:204-276`), a `.topbar` (46px, `:123-132`),
+a chat surface (`.chat-*`), and member/tile grids. It is a **single screen**, not
+a paged SPA. See `docs/slim-ux/concepts.md`.
+
+### 5.3 Cards, panels, grids
+
+- **Card base** `.card` — `--surface2` bg, `1px --border`, `--radius-lg`, padding
+  `12px 16px`, hover → `--blue` border (`dashboard/styles.css:522-528`). The
+  universal container primitive; specific cards (`.agent-card`, `.plan-card`,
+  `.archive-card`) extend it.
+- **Agent grid** — 2-column (`.agents { grid-template-columns: 1fr 1fr }`,
+  `:117`), collapses to 1 column at `≤640px` (`:1475`).
+- **Hover lift** — cards raise via `transform: translateY(-1px)` + `--shadow-md` +
+  accent border (`.agent-card:hover`, `:122`).
+
+### 5.4 Tables
+
+Two table systems:
+- **Generic** `.table` (`:777-780`) — full-width, `border-collapse`, `--text-md`
+  body, uppercase muted `th`, `--surface2` row hover.
+- **PR/work-item** `.pr-table` (`:354-384`) — adds sticky headers
+  (`thead th { position: sticky; top: 0; background: var(--surface) }`, `:380`),
+  horizontal scroll wrapper (`.pr-table-wrap { overflow-x: auto }`, `:353`), a
+  fixed-layout `--prs` variant with `min-width: 1600px` and per-column ellipsis
+  (`:361-372`), and a mobile card-reflow for `.quarantine-ref-table` at `≤640px`
+  (`:1484-1508`).
+
+Tables are dense: `td` padding `8px 10px`, `1px --border` row dividers, no zebra
+striping — hover is the row-affordance.
+
+---
+
+## 6. Components
+
+### 6.1 Buttons
+
+Minions has a **deliberately consolidated** button taxonomy. Each family is a
+single source of truth with size variants; **do not** re-create the inline style
+blob for a new button — extend the primitive. All families share: `--surface2`
+or transparent bg, `--radius-sm`, `--transition` on hover, a `~10%` hue-tint
+hover, a `2px` accent `:focus-visible` outline, and a `0.4` opacity disabled
+state.
+
+| Class                | Identity                          | Use                                        | Source |
+| -------------------- | --------------------------------- | ------------------------------------------ | ------ |
+| `.btn`               | neutral bordered, `--surface`     | generic default button                     | `:531` |
+| `.btn-primary`       | solid `--blue`, `#fff` text       | inline primary                             | `:539` |
+| `.btn-success/-danger/-warning` | colored border/text    | semantic outline variants                  | `:542` |
+| `.btn-add` (+`-lg`)  | green border/text, no glyph rules | "+ Add / + New" creators                   | `:558` |
+| `.btn-action` (+`-md/-lg`) | green border/text            | verb actions (Approve/Verify/Save/Run)     | `:592` |
+| `.btn-destructive` (+`-md/-lg`) | red border/text         | Delete / Abort / Remove / Unpin            | `:625` |
+| `.pr-info-pill`      | blue border/text (↗)              | open-PR-detail affordance in PR rows       | `:652` |
+| `.btn-primary-solid` | solid blue, `font-weight:600`     | gating CTA (Start QA, Save runbook)        | `:673` |
+| `.btn-primary-lg`    | solid blue, normal weight         | modal Save / Create / Re-execute           | `:697` |
+| `.btn-ghost`         | transparent, muted, bordered      | secondary next to a primary CTA            | `:717` |
+| `.empty-state-add`   | dashed border, green, CTA chip    | empty-state "+ Add Project"                | `:736` |
+
+**Rule:** color encodes intent — green = create/affirm, red = destroy, blue =
+primary/navigate, muted ghost = secondary. Size variant suffixes (`-md`, `-lg`)
+change only padding/size, never color. Positional spacing (`margin-left`) lives
+at the callsite, not on the button (`dashboard/styles.css:555`).
+
+### 6.2 Badges & status pills
+
+- **`.badge`** (`:764-774`) — generic uppercase pill, `--radius-xl`, `--text-sm`,
+  600 weight, 6 color variants (`-blue -green -red -yellow -purple -muted`) using
+  the `0.15` tint pattern.
+- **`.pr-badge`** (`:428-443`) — the PR/work-item status pill with a **status
+  vocabulary of classes** rather than color names:
+  `draft active approved rejected needs-review review-escalated merged building
+  build-pass build-fail no-build build-stale build-escalated needs-attention`.
+  See [§7](#7-status--content-language) for the state→class→color mapping.
+- **`.status-badge`** (`:128-131`) — agent status (`idle` muted / `working`
+  amber-pulsing / `done` green).
+- **`.dispatch-type.*`** (`:1081-1098`) — per-work-type chips (implement, review,
+  fix, test, plan, docs, setup, …), each a fixed tint.
+
+Emphasis: escalated / needs-attention states step the tint to `0.22–0.25` and
+switch to a **dashed** or **2px** border + `font-weight:700` (`:434, :441`).
+Motion (`animation: pulse`) marks live/critical states (`building`,
+`dispatch-stuck`).
+
+### 6.3 Forms & inputs
+
+- Inputs/textareas: `--bg` background, `1px --border`, `--radius-sm`, `--text`
+  color, `font-family: inherit`; focus swaps border to `--blue` and drops the
+  native outline (`.modal-qa-input`, `:152-153`).
+- The **Command Center composer** (`.cmd-input-wrap`, `:806-838`) is the richest
+  input: a `2px` border that lights `--blue` with a `3px` glow on
+  `:focus-within`, a transparent syntax-highlight layer under the textarea
+  (`.cmd-highlight-layer` colorizes `@mentions`, `/commands`, `!priority`,
+  `#project`, `--flags`), and intent chips (`.cmd-chip`) beneath.
+- Toggles: `.settings-switch` and `.pr-automation-switch` are custom checkbox
+  switches with `:focus-visible` rings on the track (`:1455, :493`).
+
+### 6.4 Dialogs & modals
+
+- **Backdrop** `.modal-bg` — `position:fixed; inset:0; background:
+  rgba(0,0,0,0.75); z-index:400`; `.open` sets `display:flex` centered
+  (`:1185-1186`).
+- **Card** `.modal` — `--surface`, `1px --border`, `--radius-xl`, `width:95%;
+  max-width:1100px; max-height:80vh`, flex column (`:1187`). `.modal-wide` widens
+  to `1500px`.
+- **Header** — flex row, bottom border, `h3` is `--text-xl` `--blue`
+  (`:1189-1190`); a `.modal-close` muted × and optional `.modal-copy` chrome.
+- **Modal stack** — supports depth (back button `.modal-back-btn` +
+  `.modal-stack-chip` showing `n/5`, `:1200-1211`).
+- **Confirm dialog** — promise-based, reuses `.modal-bg`/`.modal` sized down to
+  `.confirm-card` (max 480px), right-aligned action row (`:1234-1244`). Replaces
+  `window.confirm`; behavior in `dashboard/js/confirm-dialog.js`.
+
+### 6.5 Command Center (drawer)
+
+A right-hand `420px` fixed drawer (`#cc-drawer`, `dashboard/layout.html:60`) with
+its own overlay scrim, the rich composer (§6.3), streaming tool chips
+(`renderToolChip`, `dashboard/js/render-utils.js:13`), and action/message chips.
+It is a **surface, not a page** — the primary conversational control plane.
+
+### 6.6 Empty / loading / error states
+
+- **Empty** — `.empty { color: var(--muted); font-style: italic; font-size:
+  var(--text-md); padding: 8px 0 }` (`:802`); `.tile-empty` in slim
+  (`slim/styles.css:889`). Empty-state CTAs use the dashed `.empty-state-add`
+  chip.
+- **Loading** — animated dot triads (`.modal-qa-loading .dot-pulse span`,
+  `:141-144`; `.notif-badge.processing`, `:1247`) using `dotPulse`. Live
+  activity uses the `pulse` dot.
+- **Error** — red accent: `.modal-copy.is-danger` (`:1196`), agent-detail error
+  state with a `.btn-primary-lg` Retry (`:694`), `.dispatch-stuck` dashed-red
+  pulsing warning (`:1102`). Error text uses `--red`; never a raw red.
+
+### 6.7 Notification badges
+
+`.notif-badge` (`:1245-1250`) — absolutely positioned dot on sidebar links / CC
+tabs. `.done` = `8px` red `notifPulse` dot (unread completion); `.processing` =
+three blue `dotPulse` dots (in-flight).
+
+---
+
+## 7. Status & content language
+
+Status is the heart of the design. The mapping from **domain state → CSS class →
+color → meaning** is defined in the renderers and MUST be reused, not re-derived.
+
+### 7.1 Work-item status (`dashboard/js/render-work-items.js:200-201, 810`)
+
+| Status                | `.pr-badge` class | Color            | Meaning              |
+| --------------------- | ----------------- | ---------------- | -------------------- |
+| `pending` / `queued`  | `active`          | blue             | waiting to dispatch  |
+| `dispatched`          | `building`        | yellow (pulsing) | agent running        |
+| `done` / `decomposed` | `approved`        | green            | complete             |
+| `failed`              | `rejected`        | red              | failed               |
+| `cancelled`           | `draft`           | muted            | cancelled/removed    |
+
+### 7.2 PR review status (`dashboard/js/render-prs.js:130, 480`)
+
+| `reviewStatus`        | class      | Color            |
+| --------------------- | ---------- | ---------------- |
+| `approved`            | `approved` | green            |
+| `changes-requested` / `rejected` | `rejected` | red   |
+| `waiting`             | `building` | yellow (pulsing) |
+| everything else / `pending` | `draft` | muted          |
+
+Minions-sourced review labels append `(minions)` and the "reviewing (minions)"
+wording (`render-prs.js:131`).
+
+### 7.3 PR build status (`dashboard/js/render-prs.js:133-134, 484-487`)
+
+| `buildStatus`         | class        | Color                 |
+| --------------------- | ------------ | --------------------- |
+| `passing`             | `build-pass` | green                 |
+| `failing`             | `build-fail` | red                   |
+| `running`             | `building`   | yellow (pulsing)      |
+| `none`                | `no-build`   | muted                 |
+| `_buildStatusStale`   | `build-stale`| orange, **dashed** border |
+
+Stale/escalated states are visually distinct (dashed / 2px border) so an operator
+never confuses a **confirmed** failure with a **cached/stale** one — a
+load-bearing product rule (build fixes are not dispatched from stale failures).
+
+### 7.4 Agent status (`.status-badge`, `dashboard/styles.css:129-131`)
+
+`idle` (muted) · `working` (amber, pulsing) · `done` (green). Agent cards also
+recolor their border: `.agent-card.working` yellow, `.agent-card.done` green
+(`:123-124`).
+
+### 7.5 Dispatch type taxonomy (`.dispatch-type.*`, `:1082-1098`)
+
+Each work type has a fixed chip color: `implement`/`meeting` blue,
+`review`/`decompose` purple, `fix` yellow, `analyze`/`ask`/`verify` green, `test`
+orange, `explore`/`manual` muted, `plan` violet `#a855f7`, `docs` sky `#38bdf8`,
+`setup` teal `#14b8a6`, `evaluate` red.
+
+### 7.6 Content & label conventions
+
+- **IDs & branches** — monospace (`.mono`), often muted; truncate with a `title`.
+- **Timestamps** — `--muted`, `tabular-nums`, relative ("3 min ago").
+- **Section headers** — UPPERCASE, muted, letter-spaced.
+- **Counts** — pill chips (`.sidebar-count`, `.count`) with tabular numerals.
+- **Status verbs** — imperative and terminal: `approved`, `failing`, `merged`,
+  `needs-attention`, `dispatched`. Match the engine constants (`WI_STATUS`,
+  `PR_STATUS`, `DISPATCH_RESULT` in `engine/core/shared.js`) — do not invent UI-only
+  status words. Never surface a raw enum the user can't read; humanize but keep
+  the canonical term recognizable.
+
+---
+
+## 8. Interaction states & accessibility
+
+### 8.1 The four interactive states
+
+Every interactive element defines all four:
+
+1. **Default** — `--border` hairline, `--muted` or `--text` label.
+2. **Hover** — border → accent or `--text`; background → `~10%` hue tint or
+   `--surface2`; cards add `translateY(-1px)` + shadow.
+3. **Focus** — `:focus-visible { outline: 2px solid <accent>; outline-offset:
+   1–2px }` on **every** button family (`:569, :603, :636, :664, :685, :708,
+   :728, :749`), plus the `3px` blue glow on rich inputs. **Never** remove focus
+   without a visible replacement.
+4. **Disabled** — `opacity: 0.4; cursor: not-allowed; pointer-events: none`
+   (uniform across every button family).
+
+### 8.2 Accessibility requirements
+
+- **Hit targets ≥ 24×24px** — enforced via `min-height/min-width` on small
+  affordances (command-chip close, `dashboard/styles.css:854`; `.empty-state-add`
+  `min 24×24`, `:738`).
+- **12px readability floor** — enforced by the type system (§3.4); do not put
+  reading text below it.
+- **Truncated text carries `title`** — full value always reachable (§3.6).
+- **Reduced motion** — honor `prefers-reduced-motion` for decorative animation
+  (§4.4).
+- **Focus-visible on all controls**, including custom switches (track gets the
+  ring, `:493, :1455`).
+- **Contrast** — accent-on-tint at badge weight; muted text kept ≥ 12px (§2.6).
+- **Semantic markers** — `cursor: help` on informational badges that expose a
+  `title` explanation (`.needs-attention`, `:443`; `.dispatch-stuck`, `:1102`).
+- **XSS discipline (implementation a11y/security)** — dashboard JS prefers
+  `insertAdjacentHTML('beforeend', …)` / DOM construction over `innerHTML +=`
+  (preserves event handlers); an ESLint gate
+  (`eslint-plugin-no-unsanitized`, `npm run lint`) blocks unsanitized sinks. All
+  user/agent text is escaped via `escapeHtml` before interpolation
+  (`dashboard/js/render-work-items.js:202`).
+
+---
+
+## 9. Classic vs Slim: shared foundations vs intentional differences
+
+**Do not assume parity.** The two front-ends share a language but ship
+independent CSS. This is the authoritative reconciliation.
+
+### 9.1 Genuinely shared (kept in lockstep by a tripwire)
+
+- The **7 core palette tokens** `--bg --surface --border --muted --blue --green
+  --red` (identical hex).
+- The **typography size primitives** (base px identical; tripwire
+  `test/unit/dashboard-font-size-tokens.test.js`) and **role aliases**.
+- The **`.text-*` utility classes** (duplicated verbatim,
+  `dashboard/slim/styles.css:61-68`).
+- The **dark, GitHub-Primer aesthetic**, semantic-color philosophy, uppercase
+  micro-labels, and pulse-for-live motion vocabulary.
+- **`.status-line`** and **`.status-badge`** definitions appear in both — but
+  slim's copies (`slim/styles.css:1900-1906`) live inside the mirrored
+  detail-panel block and depend on the scoped token island (`.status-badge.working`
+  resolves `var(--yellow)` only under `#detail-panel` / `#detail-overlay`). They
+  are duplicated *presentation*, not a globally shared slim primitive (§9.2 †).
+
+### 9.2 Intentional differences (do NOT "fix" toward parity)
+
+| Aspect                | Classic                              | Slim (global `:root`)                  |
+| --------------------- | ------------------------------------ | -------------------------------------- |
+| `--minions-text-scale`| `1.05` (global +5% bump)             | `1` (pinned — excluded from bump)      |
+| Spacing scale         | 9-step, 2px base (`--space-1..9`)    | 5-step, 4px base (`--space-1..5`) †    |
+| `--surface2`          | `#21262d`                            | `#1c2128`                              |
+| `--text`              | `#e6edf3`                            | `#c9d1d9`                              |
+| In-progress token     | `--yellow`                           | `--amber` (same hex `#d29922`) †       |
+| `--orange`            | `#e3b341` (golden)                   | `#ea580c` (hot) †                      |
+| `--purple`            | declared                             | not in `:root` †                       |
+| Radius                | 5 tokens (`--radius-sm..full`)       | single `--radius: 6px` †               |
+| Shell                 | paged SPA (sidebar + `.page`)        | single-screen cockpit (`.panel` grid)  |
+| Line-height baseline  | none on body                         | `line-height: 1.5` on body             |
+| Scrollbars            | `6px` thin (`:799`)                  | `10px` themed + thin nested (`:98-120`)|
+
+> † **Global `:root` only — mind the scoped token island.** The Slim column
+> describes `dashboard/slim/styles.css:13-56`. Slim *also* re-declares the
+> Classic `--yellow` / `--purple` / `--orange` (Classic `#e3b341`) /
+> `--radius-sm..full` / `--transition-*` / `--space-1..9` (Classic 2px) set
+> scoped to `#detail-panel, #detail-overlay`
+> (`dashboard/slim/styles.css:1859-1865`), so the detail-panel rules mirrored
+> verbatim from Classic (`:1867-1974`) resolve correctly without disturbing
+> slim's global palette. **Inside that subtree the Classic values apply.** Do not
+> flag a mirrored panel rule that uses `var(--purple)`, `var(--radius-xl)`, or
+> Classic `--space-*` arithmetic as a token violation — resolve the selector's
+> scope first (§13 item 10).
+
+### 9.3 Reuse-before-fork rule
+
+When adding behavior to Slim, first check whether Classic already implements it
+and extract a **shared helper** rather than forking a divergent copy (CLAUDE.md
+"Slim UX vs Classic UX — reuse, don't fork"). A divergent parallel copy of an
+existing renderer is grounds for review rejection. The token *duplication* is
+sanctioned (independent stylesheets); *logic* duplication is not.
+
+---
+
+## 10. Reusable implementation patterns
+
+Concrete, traceable references for converting or auditing UI.
+
+### 10.1 Token consumption
+
+```css
+/* GOOD — every value is a token */
+.my-chip {
+  background: var(--surface2);
+  border: 1px solid var(--border);
+  border-radius: var(--radius-sm);
+  padding: var(--space-2) var(--space-5);
+  font-size: var(--text-micro);
+  color: var(--muted);
+}
+/* BAD — raw hex + raw px (fails audit + font-size tripwire) */
+.my-chip { background:#1c2128; padding:4px 10px; font-size:12px; color:#8b949e; }
+```
+
+### 10.2 Status badge
+
+```js
+// Reuse the class vocabulary, never re-pick colors:
+const cls = s === 'failed' ? 'rejected'
+          : s === 'dispatched' ? 'building'
+          : s === 'done' ? 'approved'
+          : s === 'cancelled' ? 'draft' : 'active';
+return `<span class="pr-badge ${cls}">${escapeHtml(s)}</span>`;
+// (dashboard/js/render-work-items.js:200-202, 810)
+```
+
+### 10.3 Button — extend, don't inline
+
+```html
+<!-- GOOD -->
+<button class="btn-action btn-action-lg" onclick="save()">Save</button>
+<!-- BAD — re-creating the green blob -->
+<button style="color:var(--green);border:1px solid var(--green);padding:2px 10px">Save</button>
+```
+
+### 10.4 DOM-safe rendering
+
+```js
+el.insertAdjacentHTML('beforeend', html);   // preserves handlers; passes lint
+// el.innerHTML += html;                     // BANNED — drops handlers, XSS risk
+text = escapeHtml(userValue);                // ALWAYS escape untrusted text
+```
+
+### 10.5 Truncate + title
+
+```js
+`<span class="truncate" title="${escapeHtml(full)}">${escapeHtml(full)}</span>`
+```
+
+### 10.6 Reference index (files & symbols)
+
+| Concern                 | File                                            | Anchor                              |
+| ----------------------- | ----------------------------------------------- | ----------------------------------- |
+| Tokens (Classic)        | `dashboard/styles.css`                          | `:root` `:1-61`                     |
+| Tokens (Slim)           | `dashboard/slim/styles.css`                     | `:root` `:13-56`                    |
+| Tokens (Slim, scoped)   | `dashboard/slim/styles.css`                     | `#detail-panel, #detail-overlay` `:1859-1865` |
+| Typography contract     | `dashboard/docs/typography.md`                  | whole file                          |
+| Type tripwire           | `test/unit/dashboard-font-size-tokens.test.js`  | raw-px gate                         |
+| Buttons                 | `dashboard/styles.css`                          | `:519-761`                          |
+| Badges / pr-badge       | `dashboard/styles.css`                          | `:428-443, 763-774`                 |
+| Tables                  | `dashboard/styles.css`                          | `:354-384, 776-780`                 |
+| Modals / confirm        | `dashboard/styles.css`                          | `:1185-1244`                        |
+| Command Center composer | `dashboard/styles.css`                          | `:804-853`                          |
+| Status renderers        | `dashboard/js/render-prs.js`, `render-work-items.js` | status→class maps              |
+| Shared render helpers   | `dashboard/js/render-utils.js`                  | `renderToolChip`, `escapeHtml` uses |
+| Shell / embed mode      | `dashboard/layout.html`                         | `:38-60, :20-32`                    |
+| Slim shell              | `dashboard/slim/layout.html`, `body.html`       | `.panel` grid                       |
+| Lint gate               | `npm run lint`                                  | `eslint-plugin-no-unsanitized`      |
+
+---
+
+## 11. Migration playbook
+
+Adopting the Minions language in another application, in dependency order.
+
+**Phase 0 — Establish tokens.**
+1. Copy the `:root` token block (`dashboard/styles.css:1-61`) into your global
+   stylesheet: the 7 core palette tokens, accent tokens, the full type primitive
+   + role-alias system, the 9-step spacing scale, radii, shadows, transitions.
+2. Set the body baseline: `background: var(--bg); color: var(--text);
+   font-family: 'Segoe UI', system-ui, sans-serif; font-size: var(--text-xl)`.
+3. Add the `.text-*` utility classes and (optionally) the `[data-font-size]`
+   zoom mechanism from `dashboard/layout.html:13-19`.
+
+**Phase 1 — Token mapping.** Map your existing values to tokens:
+
+| Your value                | Minions token       |
+| ------------------------- | ------------------- |
+| page background           | `--bg`              |
+| card / panel background   | `--surface2`        |
+| raised bar / header       | `--surface`         |
+| primary text              | `--text`            |
+| secondary/meta text       | `--muted`           |
+| hairline border           | `--border`          |
+| primary action / link     | `--blue`            |
+| success / create          | `--green`           |
+| error / destroy           | `--red`             |
+| in-progress / warning     | `--yellow`          |
+| gutter (default)          | `--space-4` (8px)   |
+| card padding              | `--space-6 --space-7` |
+| body font                 | `--text-body`       |
+| labels                    | `--text-micro`      |
+
+Replace every raw hex and raw `font-size` as you go; run a grep for `#[0-9a-f]{3,6}`
+and `font-size:\s*\d` to find stragglers.
+
+**Phase 2 — Component conversion.** Port the primitives in this order (each
+depends on tokens only): `.card` → `.btn*` families → `.badge`/`.pr-badge` →
+`.table`/`.pr-table` → `.modal`/confirm → inputs/switches → empty/loading/error
+states → Command-Center-style composer (if you need a conversational surface).
+Reuse the exact class vocabulary and status→class maps from §7 and §10.
+
+**Phase 3 — Interaction & states.** Add the four interactive states (§8.1) to
+every control: hover tint, `:focus-visible` accent outline, `0.4` disabled,
+`--transition-fast` timing. Wire the `pulse`/`dotPulse` live-state animations and
+respect `prefers-reduced-motion`.
+
+**Phase 4 — Responsive validation.** Add the `≤1100px` and `≤640px` breakpoints
+(`dashboard/styles.css:1460-1514`): grids collapse to 1 column, stats wrap,
+tables shrink type and gain horizontal scroll, modals go to `95vw`. Verify at
+`320 / 640 / 1100 / 1440px`.
+
+**Phase 5 — Accessibility.** Confirm §8.2: ≥24px hit targets, 12px reading floor,
+`title` on all truncation, focus-visible everywhere, contrast on the dark canvas,
+escaped user text, sanitized HTML sinks.
+
+**Phase 6 — Visual-regression.** Capture Playwright screenshots of each converted
+surface at a normal viewport (BEFORE/AFTER for conversions). Minions gates this
+in CI (`docs/visual-evidence-ci.md`); mirror that discipline. Run the type
+tripwire equivalent to prevent raw-px regressions.
+
+---
+
+## 12. Audit rubric & checklist
+
+Grade a Minions UI change objectively. **Severity:** 🔴 blocker (must fix before
+merge) · 🟡 major (fix or file follow-up) · 🔵 minor (nit).
+
+### 12.1 Tokens & color
+
+- 🔴 Any raw hex / named CSS color outside a `:root` block (except audited
+  `#fff`-on-accent and `rgba(0,0,0,…)` scrims/shadows, and the sanctioned slim
+  scoped token island at `dashboard/slim/styles.css:1859-1865` — §13 item 10).
+- 🔴 A color chosen for looks rather than its semantic role (§2.2, §7).
+- 🟡 A new tint fill with a novel opacity step instead of the established
+  `0.10 / 0.15 / 0.22–0.25` ladder.
+- 🟡 A hue that recurs ≥3× still hard-coded instead of promoted to a token.
+
+### 12.2 Typography
+
+- 🔴 Raw `font-size: Npx` / `Nem` in CSS, inline style, or JS template (fails
+  `test/unit/dashboard-font-size-tokens.test.js`).
+- 🟡 Reading text below the 12px floor (`--text-xs` used for anything but the two
+  allowlisted dense-chrome callsites).
+- 🔵 New code using a size primitive where a role alias exists.
+
+### 12.3 Spacing / layout
+
+- 🟡 Raw `Npx` padding/margin/gap where a `--space-*` token fits.
+- 🔴 Copying a `--space-*` rule between Classic and Slim without re-mapping (the
+  scales differ — §4.1). **Not** a violation inside `#detail-panel,
+  #detail-overlay` in slim, where the Classic 9-step scale is re-declared on
+  purpose (§9.2 †, §13 item 10) — verify the selector's scope before flagging.
+- 🟡 A new card/panel not built on `.card` (or a slim `.panel`).
+
+### 12.4 Components & states
+
+- 🔴 A new button that inlines the color/border blob instead of extending a
+  `.btn-*` family (§6.1).
+- 🔴 Missing `:focus-visible` outline on an interactive element.
+- 🟡 Missing hover and/or disabled state.
+- 🟡 A status rendered with an ad-hoc class instead of the `.pr-badge` / status
+  vocabulary and the §7 maps.
+- 🔵 Hit target < 24px without a `min-width/min-height` bump.
+
+### 12.5 Accessibility & safety
+
+- 🔴 `innerHTML +=` / unsanitized HTML sink (fails `npm run lint`).
+- 🔴 Unescaped user/agent text interpolated into markup.
+- 🟡 Truncated text without a `title`.
+- 🟡 Decorative animation ignoring `prefers-reduced-motion`.
+
+### 12.6 Classic/Slim discipline
+
+- 🔴 Forking an existing Classic renderer into a divergent Slim copy instead of
+  extracting a shared helper (§9.3).
+- 🟡 "Normalizing" an intentional Classic/Slim token difference toward false
+  parity (§9.2).
+
+### 12.7 Common anti-patterns (fast reference)
+
+| Anti-pattern                                    | Correct pattern                        |
+| ----------------------------------------------- | -------------------------------------- |
+| `style="color:#3fb950"`                         | `class="text-green"` / token           |
+| `font-size:14px`                                | `var(--text-body)` / `.text-body`      |
+| `padding:8px`                                   | `var(--space-4)`                       |
+| new `<button style="border:1px solid green…">`  | `class="btn-action"`                   |
+| `innerHTML += row`                              | `insertAdjacentHTML('beforeend', row)` |
+| `window.confirm('Sure?')`                       | `confirm-dialog.js` promise            |
+| raw enum text `"changes_requested"` in UI       | humanized label + `.pr-badge rejected` |
+
+### 12.8 Worked review examples
+
+- **REJECT:** a PR adds `<span style="background:#21262d;padding:4px;font-size:12px">`.
+  → 🔴 raw hex, raw px, raw padding. Fix: `class="card text-caption"` with
+  `--space-*` padding.
+- **APPROVE:** a PR adds a new work-type chip as
+  `.dispatch-type.migrate { background: rgba(88,166,255,0.15); color: var(--blue); }`
+  extending the existing pattern with a token color. 🟢 (Would be 🟡 if it
+  introduced a novel raw hue used only once.)
+- **REQUEST CHANGES:** a Slim panel re-implements the PR status→class logic
+  inline instead of importing the shared helper. → 🔴 fork; extract shared.
+
+---
+
+## 13. Known inconsistencies & legacy exceptions
+
+Labelled **observed** (what the code does today) vs **canonical** (recommended
+guidance). Do not silently normalize these away.
+
+1. **Duplicated token blocks, by design.** Classic and Slim declare separate
+   `:root` blocks. *Observed:* intentional (independent stylesheets served from
+   disk). *Canonical:* keep them duplicated but rely on
+   `test/unit/dashboard-font-size-tokens.test.js` to keep the type values in
+   lockstep; there is **no** tripwire for the palette/spacing tokens, so
+   palette/spacing drift is possible — verify manually when touching either
+   `:root`. Slim additionally carries a **third**, scoped declaration block for
+   the reused detail panel — see item 10.
+
+2. **`--yellow` (Classic) vs `--amber` (Slim), same hex.** *Observed:* two names,
+   one value `#d29922`. *Canonical:* reference the token that exists in the
+   stylesheet you're editing; do not cross-import the name.
+
+3. **`--orange` differs in hue between the two.** Classic `#e3b341` (golden),
+   Slim `#ea580c` (hot). *Observed:* genuine difference. *Canonical:* accept it;
+   both signal "attention/fan-out/stale" in their own surface.
+
+4. **`--space-*` tokens mean different pixels.** Classic 2px-base 9-step vs Slim
+   4px-base 5-step. *Observed & canonical:* never copy spacing rules across
+   without re-mapping.
+
+5. **Off-palette dispatch-type hues** (`#a855f7`, `#38bdf8`, `#14b8a6`,
+   `dashboard/styles.css:1089-1098`). *Observed:* raw hex with no token.
+   *Canonical:* acceptable as a fixed type taxonomy; promote to tokens if reused
+   outside the dispatch chips.
+
+6. **Two table systems** (`.table` and `.pr-table`). *Observed:* `.pr-table`
+   duplicates much of `.table` plus sticky-header/scroll behavior. *Canonical:*
+   use `.pr-table` for data grids (PRs, work items) and `.table` for simple
+   tables; do not add a third system.
+
+7. **`--text-xs` below the 12px floor.** *Observed:* retained at two dense-chrome
+   callsites only. *Canonical:* never use it for reading text.
+
+8. **Legacy `.layout` grid** is superseded by `.page-layout`
+   (`dashboard/styles.css:100` comments "Replaced by page-layout"). *Observed:*
+   the old `.layout` rule and its `≤1100px` media rule (`:1461`) still exist.
+   *Canonical:* build on `.page-layout`; treat `.layout` as dead.
+
+9. **Inline styles in `layout.html`.** *Observed:* the header toolbar buttons
+   carry inline `style="…"` blobs (`dashboard/layout.html:41-47`) with token
+   values. *Canonical:* new controls should use the button primitives (§6.1)
+   rather than inline blobs; these header buttons predate the consolidation.
+
+10. **Slim's scoped Classic-token island (`#detail-panel, #detail-overlay`).**
+    *Observed:* `dashboard/slim/styles.css:1859-1865` re-declares the full
+    Classic token set — `--yellow: #d29922`, `--purple: #bc8cff`,
+    `--orange: #e3b341` (the *Classic* golden value, shadowing slim's global hot
+    `#ea580c`), `--radius-sm..--radius-full`, `--transition-fast/base/slow`, and
+    `--space-1..--space-9` at the Classic 2px values — scoped to the two panel
+    roots. It exists because the agent detail-panel markup and JS are reused
+    **verbatim** from Classic (`dashboard/layout.html` +
+    `dashboard/js/{render-agents,detail-panel,live-stream,charter-editor,…}.js`),
+    while slim and Classic ship separate top-level stylesheets with no shared CSS
+    partial (W-mrz11djx00050594, rationale comment at
+    `dashboard/slim/styles.css:1845-1858`). Mirroring the classic rule bodies
+    unchanged (`:1867-1974`) is only sound because the tokens they reference
+    resolve to Classic values inside that subtree.
+
+    *Canonical:* keep it. It is the cheapest way to reuse Classic panel CSS
+    without forking it (§9.3) or globally re-pointing slim's palette. Two
+    consequences bind every auditor and contributor:
+    - **Scope before flagging.** `var(--purple)`, `var(--radius-xl)`, and Classic
+      `--space-*` arithmetic are *valid* inside a panel descendant and *invalid*
+      elsewhere in slim. A blanket "slim has no `--purple`" rejection is a
+      false positive (§2.3, §9.2 †, §12.1, §12.3).
+    - **Don't widen it.** Add tokens to the island only when a newly mirrored
+      Classic panel rule needs them; never promote them to slim's global `:root`
+      (that would silently re-skin slim), and never author *new* slim-native UI
+      against island tokens.
+
+---
+
+## Validation
+
+Every claim above was verified against source at the paths/line ranges cited.
+This is a **documentation-only** artifact — no UI behavior changed. When the
+implementation evolves, update the cited anchors here and re-run
+`test/unit/dashboard-font-size-tokens.test.js` (the one automated guard this doc
+depends on).
+
+Authored with [Minions](https://icy-water-0224cc51e.2.azurestaticapps.net/minions).