From 742d4a5c6d24a12382b377a486c661f1a1836b67 Mon Sep 17 00:00:00 2001
From: iris <iris@hyperhive.local>
Date: Mon, 8 Jun 2026 20:48:11 +0200
Subject: [PATCH 1/2] fix(frontend): var-derive hardcoded palette colours for
 theme-swap safety

Replace ~92 hardcoded Catppuccin rgba literals across the dashboard,
agent, and shared terminal stylesheets with color-mix() over the theme
:root vars, so a stylix-generated theme.css recolours the whole UI, not
just the elements that already referenced the vars. Pixel-identical
under the default palette (same RGB + alpha; color-mix(in srgb, C N%,
transparent) == rgba(C, N/100)).

Also fixes four var(--mauve, #cba6f7) usages: --mauve is undefined (the
var is --purple), so they were silently falling back to the hardcoded
hex and would not have recoloured on a theme swap. The bare crust hex in
terminal.css and the checkerboard-gradient hexes in common.css are
var-derived too.

Pure black/white drop-shadow/frost scrims are left as literals (not
theme colours). Two off-palette surface tints (dim-purple schedule rows,
warm-amber inline-button hover) are also left, with a comment, pending a
dedicated named var. Correct-var fallbacks like var(--red, #f38ba8) are
left as-is since they already recolour via the var.
---
 frontend/packages/agent/src/agent.css         | 58 ++++++------
 frontend/packages/dashboard/src/common.css    | 48 +++++-----
 frontend/packages/dashboard/src/dashboard.css | 91 ++++++++++---------
 frontend/packages/dashboard/src/flow.css      |  4 +-
 frontend/packages/dashboard/src/home.css      |  6 +-
 frontend/packages/shared/src/terminal.css     | 12 +--
 6 files changed, 112 insertions(+), 107 deletions(-)

diff --git a/frontend/packages/agent/src/agent.css b/frontend/packages/agent/src/agent.css
index fc782216..dde06fa6 100644
--- a/frontend/packages/agent/src/agent.css
+++ b/frontend/packages/agent/src/agent.css
@@ -15,7 +15,7 @@
      on top, state strip below). */
   --agent-header-h: 6em;
   --agent-composer-h: 3.6em;
-  --agent-frost-bg: rgba(30, 30, 46, 0.72);
+  --agent-frost-bg: color-mix(in srgb, var(--bg) 72%, transparent);
   --agent-frost-blur: blur(12px) saturate(140%);
 }
 
@@ -47,7 +47,7 @@ body:not(.agent-shell):not(.screen-shell) {
   -webkit-background-clip: text;
   background-clip: text;
   color: transparent;
-  filter: drop-shadow(0 0 6px rgba(203, 166, 247, 0.45));
+  filter: drop-shadow(0 0 6px color-mix(in srgb, var(--purple) 45%, transparent));
 }
 
 body.agent-shell {
@@ -59,7 +59,7 @@ body.agent-shell {
      surface some depth and reinforce the vibec0re mood. */
   background:
     radial-gradient(ellipse 80% 60% at 50% 0%,
-                    rgba(203, 166, 247, 0.06) 0%,
+                    color-mix(in srgb, var(--purple) 6%, transparent) 0%,
                     transparent 60%),
     var(--bg);
 }
@@ -136,7 +136,7 @@ h2, h3 {
   color: var(--purple);
   text-transform: uppercase;
   letter-spacing: 0.15em;
-  text-shadow: 0 0 8px rgba(203, 166, 247, 0.4);
+  text-shadow: 0 0 8px color-mix(in srgb, var(--purple) 40%, transparent);
 }
 .agent-icon {
   /* Square identity anchor — explicit 5em sizing + align-self.
@@ -148,7 +148,7 @@ h2, h3 {
   flex-shrink: 0;
   align-self: flex-start;
   border-radius: 8px;
-  box-shadow: 0 0 18px -2px rgba(203, 166, 247, 0.4);
+  box-shadow: 0 0 18px -2px color-mix(in srgb, var(--purple) 40%, transparent);
   object-fit: cover;
 }
 
@@ -163,13 +163,13 @@ h2, h3 {
   letter-spacing: 0.04em;
   padding: 0.1em 0.35em;
   border-radius: 3px;
-  text-shadow: 0 0 4px rgba(137, 220, 235, 0.4);
+  text-shadow: 0 0 4px color-mix(in srgb, var(--cyan) 40%, transparent);
   transition: color 0.15s ease, text-shadow 0.15s ease, background 0.15s ease;
 }
 .agent-nav-link:hover {
   color: var(--fg);
-  background: rgba(137, 220, 235, 0.08);
-  text-shadow: 0 0 10px rgba(137, 220, 235, 0.85);
+  background: color-mix(in srgb, var(--cyan) 8%, transparent);
+  text-shadow: 0 0 10px color-mix(in srgb, var(--cyan) 85%, transparent);
 }
 
 /* Overflow menu trigger — `⋯` round button on the right of the
@@ -238,7 +238,7 @@ h2, h3 {
   transition: background 0.15s ease, border-color 0.15s ease, color 0.15s ease;
 }
 .overflow-item:hover {
-  background: rgba(203, 166, 247, 0.08);
+  background: color-mix(in srgb, var(--purple) 8%, transparent);
   border-color: var(--purple-dim);
 }
 .overflow-item-icon {
@@ -251,12 +251,12 @@ h2, h3 {
 .overflow-item-new-session { color: var(--amber); }
 .overflow-item-rebuild:hover,
 .overflow-item-new-session:hover {
-  background: rgba(250, 179, 135, 0.1);
+  background: color-mix(in srgb, var(--amber) 10%, transparent);
   border-color: var(--amber);
 }
 .overflow-item-dashboard { color: var(--cyan); }
 .overflow-item-dashboard:hover {
-  background: rgba(137, 220, 235, 0.1);
+  background: color-mix(in srgb, var(--cyan) 10%, transparent);
   border-color: var(--cyan);
 }
 .overflow-item:disabled {
@@ -281,13 +281,13 @@ h2, h3 {
 }
 .overflow-item-model:hover {
   color: var(--fg);
-  background: rgba(203, 166, 247, 0.08);
+  background: color-mix(in srgb, var(--purple) 8%, transparent);
   border-color: var(--purple-dim);
 }
 .overflow-item-model.active {
   color: var(--purple);
   border-color: var(--purple-dim);
-  background: rgba(203, 166, 247, 0.06);
+  background: color-mix(in srgb, var(--purple) 6%, transparent);
 }
 
 /* Header pill — inbox / loose-ends triggers. Compact, count-prominent. */
@@ -324,11 +324,11 @@ h2, h3 {
   font-variant-numeric: tabular-nums;
 }
 .header-pill-inbox .header-pill-count {
-  background: rgba(250, 179, 135, 0.18);
+  background: color-mix(in srgb, var(--amber) 18%, transparent);
   color: var(--amber);
 }
 .header-pill-loose .header-pill-count {
-  background: rgba(243, 139, 168, 0.18);
+  background: color-mix(in srgb, var(--red) 18%, transparent);
   color: var(--red);
 }
 
@@ -387,14 +387,14 @@ h2, h3 {
   padding-top: 0;
 }
 .meta { color: var(--muted); font-size: 0.85em; }
-.status-online { color: var(--green); text-shadow: 0 0 6px rgba(166, 227, 161, 0.55); }
-.status-needs-login { color: var(--amber); text-shadow: 0 0 6px rgba(250, 179, 135, 0.55); }
-code { background: rgba(203, 166, 247, 0.12); padding: 0.05em 0.3em; border-radius: 2px; }
+.status-online { color: var(--green); text-shadow: 0 0 6px color-mix(in srgb, var(--green) 55%, transparent); }
+.status-needs-login { color: var(--amber); text-shadow: 0 0 6px color-mix(in srgb, var(--amber) 55%, transparent); }
+code { background: color-mix(in srgb, var(--purple) 12%, transparent); padding: 0.05em 0.3em; border-radius: 2px; }
 a {
   color: var(--cyan);
-  text-shadow: 0 0 4px rgba(137, 220, 235, 0.5);
+  text-shadow: 0 0 4px color-mix(in srgb, var(--cyan) 50%, transparent);
 }
-a:hover { color: var(--fg); text-shadow: 0 0 12px rgba(137, 220, 235, 0.9); }
+a:hover { color: var(--fg); text-shadow: 0 0 12px color-mix(in srgb, var(--cyan) 90%, transparent); }
 .btn {
   font-family: inherit;
   font-size: 1em;
@@ -410,7 +410,7 @@ a:hover { color: var(--fg); text-shadow: 0 0 12px rgba(137, 220, 235, 0.9); }
   transition: box-shadow 0.15s ease, text-shadow 0.15s ease;
 }
 .btn:hover {
-  background: rgba(205, 214, 244, 0.06);
+  background: color-mix(in srgb, var(--fg) 6%, transparent);
   text-shadow: 0 0 10px currentColor;
   box-shadow: 0 0 10px -2px currentColor;
 }
@@ -712,9 +712,9 @@ pre.diff {
 }
 .status-badge.status-loading      { color: var(--muted);  border-color: var(--purple-dim); }
 .status-badge.status-online       { color: var(--green);  border-color: var(--green);
-  text-shadow: 0 0 6px rgba(166, 227, 161, 0.55); }
+  text-shadow: 0 0 6px color-mix(in srgb, var(--green) 55%, transparent); }
 .status-badge.status-rate-limited { color: var(--red);    border-color: var(--red);
-  text-shadow: 0 0 6px rgba(243, 139, 168, 0.55); }
+  text-shadow: 0 0 6px color-mix(in srgb, var(--red) 55%, transparent); }
 .status-badge.status-needs-login  { color: var(--amber);  border-color: var(--amber); }
 .status-badge.status-offline      { color: var(--muted);  border-color: var(--muted); }
 /* Orphaned tombstone — `.btn-dashlink` chip that lived beside the
@@ -734,7 +734,7 @@ pre.diff {
   transition: box-shadow 0.15s ease, background 0.15s ease;
 }
 .btn-cancel-turn:hover {
-  background: rgba(243, 139, 168, 0.1);
+  background: color-mix(in srgb, var(--red) 10%, transparent);
   box-shadow: 0 0 10px -2px currentColor;
 }
 /* Orphaned tombstone — `.btn-new-session` round-pill moved into
@@ -759,16 +759,16 @@ pre.diff {
 }
 .state-badge.state-idle {
   color: var(--cyan); border-color: var(--cyan);
-  text-shadow: 0 0 6px rgba(137, 220, 235, 0.55);
+  text-shadow: 0 0 6px color-mix(in srgb, var(--cyan) 55%, transparent);
 }
 .state-badge.state-thinking {
   color: var(--amber); border-color: var(--amber);
-  text-shadow: 0 0 6px rgba(250, 179, 135, 0.65);
+  text-shadow: 0 0 6px color-mix(in srgb, var(--amber) 65%, transparent);
   animation: badge-pulse 1.8s ease-in-out infinite;
 }
 .state-badge.state-compacting {
   color: var(--purple); border-color: var(--purple);
-  text-shadow: 0 0 6px rgba(203, 166, 247, 0.65);
+  text-shadow: 0 0 6px color-mix(in srgb, var(--purple) 65%, transparent);
   animation: badge-pulse 1.8s ease-in-out infinite;
 }
 .state-badge.state-just-changed {
@@ -841,7 +841,7 @@ pre.diff {
 }
 .term-input .prompt {
   color: var(--green);
-  text-shadow: 0 0 6px rgba(166, 227, 161, 0.6);
+  text-shadow: 0 0 6px color-mix(in srgb, var(--green) 60%, transparent);
   user-select: none;
   flex: 0 0 auto;
 }
@@ -1113,7 +1113,7 @@ body.screen-shell {
   bottom: 0; left: 0; right: 0;
   max-height: 40vh;
   overflow-y: auto;
-  background: rgba(17, 17, 27, 0.95);
+  background: color-mix(in srgb, var(--crust) 95%, transparent);
   border-top: 1px solid var(--purple-dim);
   font-size: 0.72rem;
   font-family: ui-monospace, monospace;
diff --git a/frontend/packages/dashboard/src/common.css b/frontend/packages/dashboard/src/common.css
index 7c62c882..1099848d 100644
--- a/frontend/packages/dashboard/src/common.css
+++ b/frontend/packages/dashboard/src/common.css
@@ -12,7 +12,7 @@ h1, h2 {
   text-transform: uppercase;
   letter-spacing: 0.15em;
   margin-top: 2em;
-  text-shadow: 0 0 8px rgba(203, 166, 247, 0.4);
+  text-shadow: 0 0 8px color-mix(in srgb, var(--purple) 40%, transparent);
 }
 .divider {
   color: var(--purple-dim);
@@ -27,11 +27,11 @@ a {
   color: var(--cyan);
   text-decoration: none;
   font-weight: bold;
-  text-shadow: 0 0 4px rgba(137, 220, 235, 0.5);
+  text-shadow: 0 0 4px color-mix(in srgb, var(--cyan) 50%, transparent);
 }
 a:hover {
   color: var(--fg);
-  text-shadow: 0 0 12px rgba(137, 220, 235, 0.9);
+  text-shadow: 0 0 12px color-mix(in srgb, var(--cyan) 90%, transparent);
 }
 code {
   color: var(--amber);
@@ -64,23 +64,23 @@ code {
 }
 .badge-warn {
   color: var(--amber); border-color: var(--amber);
-  text-shadow: 0 0 6px rgba(250, 179, 135, 0.5);
+  text-shadow: 0 0 6px color-mix(in srgb, var(--amber) 50%, transparent);
 }
 .badge-rate-limited {
   color: var(--red); border-color: var(--red);
-  text-shadow: 0 0 6px rgba(243, 139, 168, 0.5);
+  text-shadow: 0 0 6px color-mix(in srgb, var(--red) 50%, transparent);
 }
 .badge-muted {
   color: var(--muted); border-color: var(--purple-dim);
-  background: rgba(127, 132, 156, 0.08);
+  background: color-mix(in srgb, var(--muted) 8%, transparent);
 }
 .badge-reminder {
   color: var(--cyan); border-color: var(--cyan);
-  text-shadow: 0 0 6px rgba(137, 220, 235, 0.4);
+  text-shadow: 0 0 6px color-mix(in srgb, var(--cyan) 40%, transparent);
 }
 .badge-loose-ends {
   color: var(--purple); border-color: var(--purple);
-  text-shadow: 0 0 6px rgba(203, 166, 247, 0.4);
+  text-shadow: 0 0 6px color-mix(in srgb, var(--purple) 40%, transparent);
 }
 /* Context-window usage badges on dashboard container rows. */
 .badge-ctx-ok {
@@ -89,15 +89,15 @@ code {
 }
 .badge-ctx-caution {
   color: var(--amber); border-color: var(--amber);
-  text-shadow: 0 0 6px rgba(250, 179, 135, 0.5);
+  text-shadow: 0 0 6px color-mix(in srgb, var(--amber) 50%, transparent);
 }
 .badge-ctx-warn {
   color: var(--red); border-color: var(--red);
-  text-shadow: 0 0 6px rgba(243, 139, 168, 0.5);
+  text-shadow: 0 0 6px color-mix(in srgb, var(--red) 50%, transparent);
 }
-.badge-ok      { background: rgba(166,227,161,0.12); color: var(--green);  border-color: var(--green); }
-.badge-fail    { background: rgba(243,139,168,0.12); color: var(--red);    border-color: var(--red);   }
-.badge-running { background: rgba(250,179,135,0.12); color: var(--amber);  border-color: var(--amber); }
+.badge-ok      { background: color-mix(in srgb, var(--green) 12%, transparent); color: var(--green);  border-color: var(--green); }
+.badge-fail    { background: color-mix(in srgb, var(--red) 12%, transparent); color: var(--red);    border-color: var(--red);   }
+.badge-running { background: color-mix(in srgb, var(--amber) 12%, transparent); color: var(--amber);  border-color: var(--amber); }
 
 /* ─── buttons ───────────────────────────────────────────────────────
    .btn base + semantic colour/size modifiers. Logs page uses
@@ -121,7 +121,7 @@ code {
   transition: box-shadow 0.15s ease;
 }
 .btn:hover {
-  background: rgba(205, 214, 244, 0.06);
+  background: color-mix(in srgb, var(--fg) 6%, transparent);
   text-shadow: 0 0 10px currentColor;
   box-shadow: 0 0 10px -2px currentColor;
 }
@@ -151,7 +151,7 @@ code {
 .btn-move    { color: var(--purple); border-color: var(--purple); font-size: 0.75em; padding: 0.15em 0.5em; margin-left: 0.6em; }
 .btn-talk { color: var(--cyan); border-color: var(--cyan); }
 .btn-spawn { color: var(--amber); border-color: var(--amber); }
-.btn-fire-now { color: var(--mauve, #cba6f7); border-color: var(--mauve, #cba6f7); }
+.btn-fire-now { color: var(--purple); border-color: var(--purple); }
 /* Post-fire flash: report renders directly on the button for ~1.5s
    so the operator sees ok/failed/missing/consumed counts inline
    without a modal. Green when at least one ok; muted otherwise. */
@@ -164,7 +164,7 @@ code {
 /* Inline edit button on each schedule row. Yellow reads as a
    parallel destructive-adjacent action (edit changes state, but
    isn't deletion). */
-.btn-edit-schedule { color: var(--yellow, #f9e2af); border-color: var(--yellow, #f9e2af); }
+.btn-edit-schedule { color: var(--yellow); border-color: var(--yellow); }
 
 /* ─── file-preview / diff panel (common.js Panel) ───────────────────
    Side-panel content rendered by openFilePanel / buildTabbedPreview
@@ -184,7 +184,7 @@ code {
 .diff-base-tab.active {
   color: var(--purple);
   border-color: var(--purple);
-  background: rgba(203, 166, 247, 0.08);
+  background: color-mix(in srgb, var(--purple) 8%, transparent);
 }
 /* Image / tabbed file preview */
 .preview-host { margin-top: 0.5em; }
@@ -196,13 +196,13 @@ code {
   border: 1px solid var(--border);
   border-radius: 4px;
   /* checkerboard so transparent regions of the image read clearly */
-  background: repeating-conic-gradient(#313244 0% 25%, #1e1e2e 0% 50%) 50% / 18px 18px;
+  background: repeating-conic-gradient(var(--border) 0% 25%, var(--bg) 0% 50%) 50% / 18px 18px;
 }
 
 /* Path linkification — agents drop pointer strings into messages;
    clicking the anchor opens the file in the side panel. */
 .path-link {
-  color: var(--blue, #89b4fa);
+  color: var(--blue);
   text-decoration: underline dotted;
   cursor: pointer;
 }
@@ -226,7 +226,7 @@ code {
   position: sticky;
   top: 0;
   z-index: 25;
-  background: rgba(30, 30, 46, 0.92);
+  background: color-mix(in srgb, var(--bg) 92%, transparent);
   -webkit-backdrop-filter: blur(8px) saturate(120%);
   backdrop-filter: blur(8px) saturate(120%);
   border-bottom: 1px solid var(--purple-dim);
@@ -312,7 +312,7 @@ code {
 }
 .msg-reply-tag a:hover { color: var(--fg); }
 @keyframes msg-highlight-fade {
-  from { background: rgba(203, 166, 247, 0.18); }
+  from { background: color-mix(in srgb, var(--purple) 18%, transparent); }
   to   { background: transparent; }
 }
 .msg-highlight { animation: msg-highlight-fade 1.5s ease-out forwards; }
@@ -398,7 +398,7 @@ code {
 .side-panel-backdrop {
   position: absolute;
   inset: 0;
-  background: rgba(17, 17, 27, 0.55);
+  background: color-mix(in srgb, var(--crust) 55%, transparent);
   opacity: 0;
   transition: opacity 200ms ease;
 }
@@ -539,11 +539,11 @@ body.side-panel-resizing * { cursor: ew-resize !important; }
 }
 .server-warn-warn {
   color: var(--amber);
-  background: rgba(250, 179, 135, 0.16);
+  background: color-mix(in srgb, var(--amber) 16%, transparent);
   border-bottom: 1px solid var(--amber);
 }
 .server-warn-crit {
   color: var(--red);
-  background: rgba(243, 139, 168, 0.18);
+  background: color-mix(in srgb, var(--red) 18%, transparent);
   border-bottom: 1px solid var(--red);
 }
diff --git a/frontend/packages/dashboard/src/dashboard.css b/frontend/packages/dashboard/src/dashboard.css
index 80c7976b..a3d8b963 100644
--- a/frontend/packages/dashboard/src/dashboard.css
+++ b/frontend/packages/dashboard/src/dashboard.css
@@ -23,7 +23,7 @@ body.dashboard-shell {
   position: sticky;
   top: 0;
   z-index: 25;
-  background: rgba(30, 30, 46, 0.86);
+  background: color-mix(in srgb, var(--bg) 86%, transparent);
   -webkit-backdrop-filter: blur(8px) saturate(120%);
   backdrop-filter: blur(8px) saturate(120%);
   border-bottom: 1px solid var(--purple-dim);
@@ -83,7 +83,7 @@ body.dashboard-shell {
 }
 .tabbar .tab:hover {
   color: var(--purple);
-  background: rgba(203, 166, 247, 0.06);
+  background: color-mix(in srgb, var(--purple) 6%, transparent);
 }
 .tabbar .tab.active {
   color: var(--purple);
@@ -91,7 +91,7 @@ body.dashboard-shell {
   background: var(--bg);
   /* Lift the active tab visually — the bottom border of the tabbar
      yields under it via the -1px margin above. */
-  box-shadow: 0 -2px 12px -4px rgba(203, 166, 247, 0.4);
+  box-shadow: 0 -2px 12px -4px color-mix(in srgb, var(--purple) 40%, transparent);
 }
 .tab-label { font-weight: bold; white-space: nowrap; }
 .tab-count {
@@ -108,7 +108,7 @@ body.dashboard-shell {
 }
 .tab-count-attn {
   /* Y3R C4LL — operator-action-required pill colour, harder to miss. */
-  background: rgba(243, 139, 168, 0.22);
+  background: color-mix(in srgb, var(--red) 22%, transparent);
   color: var(--red);
 }
 
@@ -145,7 +145,7 @@ body.dashboard-shell {
 }
 .tabbar-overflow-btn:hover {
   color: var(--purple);
-  background: rgba(203, 166, 247, 0.06);
+  background: color-mix(in srgb, var(--purple) 6%, transparent);
 }
 .tabbar-overflow-btn.tabbar-overflow-active {
   color: var(--purple);
@@ -206,7 +206,7 @@ body.dashboard-shell {
   font-weight: bold;
 }
 .tabbar-overflow-badge.tab-count-attn {
-  background: rgba(243, 139, 168, 0.22);
+  background: color-mix(in srgb, var(--red) 22%, transparent);
   color: var(--red);
 }
 
@@ -234,7 +234,7 @@ body.dashboard-shell {
   -webkit-background-clip: text;
   background-clip: text;
   color: transparent;
-  filter: drop-shadow(0 0 6px rgba(203, 166, 247, 0.45));
+  filter: drop-shadow(0 0 6px color-mix(in srgb, var(--purple) 45%, transparent));
 }
 .banner.active {
   animation: banner-shimmer 1.8s linear infinite;
@@ -263,7 +263,7 @@ body.dashboard-shell {
   padding: 0.6em 0.8em;
   border: 1px solid var(--border);
   border-radius: 4px;
-  background: rgba(24, 24, 37, 0.55);
+  background: color-mix(in srgb, var(--bg-elev) 55%, transparent);
   transition: opacity 200ms ease, border-color 200ms ease;
 }
 /* Topology indent ladder. See docs/web-ui.md::Topology tree (Indent
@@ -330,7 +330,7 @@ body.dashboard-shell {
   width: 5em;
   aspect-ratio: 1;
   border-radius: 6px;
-  background-color: rgba(17, 17, 27, 0.6);
+  background-color: color-mix(in srgb, var(--crust) 60%, transparent);
   cursor: pointer;
   transition: box-shadow 120ms ease, transform 120ms ease;
 }
@@ -344,7 +344,7 @@ body.dashboard-shell {
 .container-row.selected {
   border-color: var(--purple);
   box-shadow: inset 0 0 0 1px var(--purple);
-  background: rgba(203, 166, 247, 0.06);
+  background: color-mix(in srgb, var(--purple) 6%, transparent);
 }
 .container-row.selected > .container-icon {
   box-shadow: 0 0 0 2px var(--purple), 0 0 12px -4px var(--purple);
@@ -392,7 +392,7 @@ body.dashboard-shell {
 }
 .agent-menu-btn:hover,
 .agent-menu-btn:focus-visible {
-  background: rgba(203, 166, 247, 0.1);
+  background: color-mix(in srgb, var(--purple) 10%, transparent);
   color: var(--purple);
   outline: none;
 }
@@ -443,7 +443,7 @@ body.dashboard-shell {
 .container-row.pending .actions { opacity: 0.4; pointer-events: none; }
 .container-row.pending-running {
   border-color: var(--amber);
-  background: rgba(250, 179, 135, 0.05);
+  background: color-mix(in srgb, var(--amber) 5%, transparent);
 }
 @keyframes container-icon-spin {
   from { transform: rotate(0deg); }
@@ -490,9 +490,9 @@ body.dashboard-shell {
   transition: background 0.12s ease, color 0.12s ease;
 }
 .nav-link:hover {
-  background: rgba(203, 166, 247, 0.12);
+  background: color-mix(in srgb, var(--purple) 12%, transparent);
   color: var(--cyan);
-  text-shadow: 0 0 6px rgba(137, 220, 235, 0.5);
+  text-shadow: 0 0 6px color-mix(in srgb, var(--cyan) 50%, transparent);
 }
 .container-row .actions {
   display: flex;
@@ -503,7 +503,7 @@ body.dashboard-shell {
 
 .agent-status {
   font-size: 0.82em;
-  color: var(--subtext0, #a6adc8);
+  color: var(--subtext0);
   padding: 0.1em 0.3em 0.25em;
   white-space: nowrap;
   overflow: hidden;
@@ -514,20 +514,20 @@ body.dashboard-shell {
 
 .container-row.tombstone {
   border-style: dashed;
-  background: rgba(24, 24, 37, 0.35);
+  background: color-mix(in srgb, var(--bg-elev) 35%, transparent);
   opacity: 0.85;
 }
 .container-row.tombstone .name { color: var(--muted); }
 
 /* Notification controls — sit between the banner and the containers. */
 .port-conflict {
-  background: rgba(243, 139, 168, 0.08);
+  background: color-mix(in srgb, var(--red) 8%, transparent);
   border: 1px solid var(--red);
   color: var(--red);
   padding: 0.5em 0.8em;
   margin-bottom: 0.6em;
   border-radius: 4px;
-  text-shadow: 0 0 6px rgba(243, 139, 168, 0.4);
+  text-shadow: 0 0 6px color-mix(in srgb, var(--red) 40%, transparent);
   animation: questions-pulse 2.4s ease-in-out infinite;
 }
 .port-conflict strong { color: var(--red); }
@@ -551,7 +551,7 @@ body.dashboard-shell {
   text-shadow: 0 0 4px currentColor;
 }
 .btn-notif:hover {
-  background: rgba(137, 220, 235, 0.1);
+  background: color-mix(in srgb, var(--cyan) 10%, transparent);
   box-shadow: 0 0 10px -2px currentColor;
 }
 
@@ -560,7 +560,7 @@ body.dashboard-shell {
   font-size: 0.85em;
   letter-spacing: 0.08em;
   text-transform: uppercase;
-  text-shadow: 0 0 6px rgba(250, 179, 135, 0.55);
+  text-shadow: 0 0 6px color-mix(in srgb, var(--amber) 55%, transparent);
   animation: badge-pulse 1.6s ease-in-out infinite;
 }
 @keyframes badge-pulse {
@@ -568,8 +568,8 @@ body.dashboard-shell {
   50%      { opacity: 0.7; }
 }
 @keyframes questions-pulse {
-  0%, 100% { box-shadow: 0 0 12px -4px rgba(250, 179, 135, 0.55); }
-  50%      { box-shadow: 0 0 22px -2px rgba(250, 179, 135, 0.95); }
+  0%, 100% { box-shadow: 0 0 12px -4px color-mix(in srgb, var(--amber) 55%, transparent); }
+  50%      { box-shadow: 0 0 22px -2px color-mix(in srgb, var(--amber) 95%, transparent); }
 }
 
 /* Pending approval: a card with three stacked sections — identity
@@ -596,7 +596,7 @@ body.dashboard-shell {
 }
 .approval-ts.stale {
   color: var(--amber);
-  text-shadow: 0 0 6px rgba(250, 179, 135, 0.5);
+  text-shadow: 0 0 6px color-mix(in srgb, var(--amber) 50%, transparent);
 }
 .approval-body {
   margin: 0.45em 0;
@@ -644,7 +644,7 @@ body.dashboard-shell {
 .approval-tab.active {
   color: var(--purple);
   border-color: var(--purple);
-  background: rgba(203, 166, 247, 0.08);
+  background: color-mix(in srgb, var(--purple) 8%, transparent);
   text-shadow: 0 0 4px currentColor;
 }
 .approvals-history .status { font-size: 0.85em; padding: 0 0.5em; }
@@ -667,7 +667,7 @@ body.dashboard-shell {
 .meta-inputs li {
   padding: 0.25em 0.6em;
   border: 1px solid var(--border);
-  background: rgba(24, 24, 37, 0.6);
+  background: color-mix(in srgb, var(--bg-elev) 60%, transparent);
 }
 .meta-inputs label {
   display: flex;
@@ -711,7 +711,7 @@ body.dashboard-shell {
   margin-right: 0.1em;
 }
 .btn-meta-update {
-  background: rgba(203, 166, 247, 0.12);
+  background: color-mix(in srgb, var(--purple) 12%, transparent);
   border: 1px solid var(--purple);
   color: var(--purple);
   text-shadow: 0 0 4px currentColor;
@@ -723,7 +723,7 @@ body.dashboard-shell {
   transition: box-shadow 0.15s ease, background 0.15s ease;
 }
 .btn-meta-update:hover:not([disabled]) {
-  background: rgba(203, 166, 247, 0.22);
+  background: color-mix(in srgb, var(--purple) 22%, transparent);
   box-shadow: 0 0 10px -2px currentColor;
 }
 .btn-meta-update[disabled] {
@@ -734,7 +734,7 @@ body.dashboard-shell {
   margin: 0 0 0.7em;
   padding: 0.4em 0.7em;
   border: 1px solid var(--purple);
-  background: rgba(203, 166, 247, 0.12);
+  background: color-mix(in srgb, var(--purple) 12%, transparent);
   color: var(--purple);
   font-size: 0.85em;
   animation: badge-pulse 1.6s ease-in-out infinite;
@@ -751,7 +751,7 @@ body.dashboard-shell {
 .rebuild-queue-entry {
   padding: 0.3em 0.6em;
   border: 1px solid var(--border);
-  background: rgba(24, 24, 37, 0.6);
+  background: color-mix(in srgb, var(--bg-elev) 60%, transparent);
   font-size: 0.9em;
   display: flex;
   flex-wrap: wrap;
@@ -761,7 +761,7 @@ body.dashboard-shell {
 .rebuild-queue-entry.rqe-child { margin-left: 1.6em; border-color: var(--purple-dim); }
 .rebuild-queue-entry.rqe-running {
   border-color: var(--purple);
-  background: rgba(203, 166, 247, 0.12);
+  background: color-mix(in srgb, var(--purple) 12%, transparent);
   animation: badge-pulse 1.6s ease-in-out infinite;
 }
 .rebuild-queue-entry.rqe-failed { border-color: var(--red); color: var(--red); }
@@ -797,7 +797,7 @@ body.dashboard-shell {
   flex-basis: 100%;
   margin: 0.3em 0 0;
   padding: 0.3em 0.5em;
-  background: rgba(243, 139, 168, 0.1);
+  background: color-mix(in srgb, var(--red) 10%, transparent);
   border-left: 2px solid var(--red);
   color: var(--red);
   font-size: 0.8em;
@@ -863,6 +863,8 @@ ul form.inline { display: inline-block; }
   cursor: pointer;
   margin-left: 0.4em;
 }
+/* Off-palette warm-amber hover tint: not an exact theme var (brighter than
+   --amber), left as a literal pending a dedicated named var. */
 .btn-inline:hover { background: rgba(255, 184, 77, 0.1); }
 .kind {
   display: inline-block;
@@ -933,13 +935,13 @@ summary:hover { color: var(--purple); }
   margin: 0.3em 0;
 }
 .reminder-row.reminder-failed {
-  border-left: 2px solid var(--red, #f38ba8);
+  border-left: 2px solid var(--red);
   padding-left: 0.5em;
 }
 .reminder-error {
-  color: var(--red, #f38ba8);
-  background: rgba(243, 139, 168, 0.06);
-  border: 1px solid rgba(243, 139, 168, 0.25);
+  color: var(--red);
+  background: color-mix(in srgb, var(--red) 6%, transparent);
+  border: 1px solid color-mix(in srgb, var(--red) 25%, transparent);
   padding: 0.3em 0.5em;
   font-size: 0.85em;
   white-space: pre-wrap;
@@ -974,11 +976,11 @@ summary:hover { color: var(--purple); }
   border-color: var(--amber);
 }
 .questions li.question-peer {
-  border-left: 2px solid var(--mauve, #cba6f7);
+  border-left: 2px solid var(--purple);
   padding-left: 0.6em;
 }
-.questions .msg-to-peer { color: var(--mauve, #cba6f7); }
-.btn-override { background: var(--mauve, #cba6f7) !important; color: var(--bg) !important; }
+.questions .msg-to-peer { color: var(--purple); }
+.btn-override { background: var(--purple) !important; color: var(--bg) !important; }
 .questions li.question {
   padding: 0.4em 0;
   border-bottom: 1px solid var(--border);
@@ -1046,7 +1048,7 @@ summary:hover { color: var(--purple); }
 }
 .question-answered { opacity: 0.7; }
 .question-answered .q-body { color: var(--muted); margin-bottom: 0.15em; }
-.q-answer { font-size: 0.9em; color: var(--green, #a6e3a1); padding: 0.1em 0 0.4em 0; }
+.q-answer { font-size: 0.9em; color: var(--green); padding: 0.1em 0 0.4em 0; }
 .q-answer-text { font-style: italic; }
 
 footer {
@@ -1141,7 +1143,7 @@ footer .banner-thin {
 .schedule-edit-form-wrapper {
   margin-top: 0.5em;
   padding-left: 0.5em;
-  border-left: 2px solid var(--yellow, #f9e2af);
+  border-left: 2px solid var(--yellow);
 }
 .schedule-edit-targets-note {
   color: var(--muted);
@@ -1185,13 +1187,13 @@ footer .banner-thin {
   border-radius: 999px;
   font-size: 0.85em;
   cursor: pointer;
-  background: rgba(24, 24, 37, 0.4);
+  background: color-mix(in srgb, var(--bg-elev) 40%, transparent);
 }
 .schedule-target-chip:hover { border-color: var(--purple-dim); }
 .schedule-target-chip:has(input:checked) {
   border-color: var(--purple);
   color: var(--purple);
-  background: rgba(203, 166, 247, 0.08);
+  background: color-mix(in srgb, var(--purple) 8%, transparent);
 }
 .schedule-target-chip input { margin: 0; }
 .schedule-actions {
@@ -1333,10 +1335,13 @@ footer .banner-thin {
   margin-left: 0.3em;
 }
 .schedules-table-edit-row > td {
+  /* Off-palette dim-purple surface tint: not an exact theme var, left as a
+     literal pending a dedicated named var so a theme swap can recolour it. */
   background: rgba(38, 32, 60, 0.35);
   padding: 0.5em 0.6em;
 }
 .schedules-table-create-row td {
+  /* Off-palette dim-purple surface tint — see the edit-row note above. */
   background: rgba(38, 32, 60, 0.25);
   border-top: 2px solid var(--border);
   vertical-align: top;
@@ -1443,7 +1448,7 @@ footer .banner-thin {
   flex-wrap: wrap;
   gap: 0.6em;
   padding: 0.55em 1em;
-  background: var(--flow-frost-bg, rgba(30, 30, 46, 0.74));
+  background: var(--flow-frost-bg, color-mix(in srgb, var(--bg) 74%, transparent));
   -webkit-backdrop-filter: blur(12px) saturate(140%);
   backdrop-filter: blur(12px) saturate(140%);
   border-top: 1px solid var(--purple);
diff --git a/frontend/packages/dashboard/src/flow.css b/frontend/packages/dashboard/src/flow.css
index ded775bd..6752b351 100644
--- a/frontend/packages/dashboard/src/flow.css
+++ b/frontend/packages/dashboard/src/flow.css
@@ -10,7 +10,7 @@
      footer position. */
   --flow-header-h: 3.6em;
   --flow-composer-h: 3.6em;
-  --flow-frost-bg: rgba(30, 30, 46, 0.74);
+  --flow-frost-bg: color-mix(in srgb, var(--bg) 74%, transparent);
   --flow-frost-blur: blur(12px) saturate(140%);
 }
 
@@ -24,7 +24,7 @@ body.flow-shell {
   overflow: hidden;
   background:
     radial-gradient(ellipse 80% 60% at 50% 0%,
-                    rgba(203, 166, 247, 0.06) 0%,
+                    color-mix(in srgb, var(--purple) 6%, transparent) 0%,
                     transparent 60%),
     var(--bg);
 }
diff --git a/frontend/packages/dashboard/src/home.css b/frontend/packages/dashboard/src/home.css
index a95c6758..1e0dad68 100644
--- a/frontend/packages/dashboard/src/home.css
+++ b/frontend/packages/dashboard/src/home.css
@@ -36,7 +36,7 @@ body.home-shell {
   padding: 1.1em 1.2em;
   border: 1px solid var(--purple-dim);
   border-radius: 6px;
-  background: rgba(24, 24, 37, 0.55);
+  background: color-mix(in srgb, var(--bg-elev) 55%, transparent);
   text-decoration: none;
   color: var(--fg);
   transition: color 0.15s ease, background 0.15s ease, border-color 0.15s ease,
@@ -44,8 +44,8 @@ body.home-shell {
 }
 .home-tile:hover {
   border-color: var(--purple);
-  background: rgba(203, 166, 247, 0.06);
-  box-shadow: 0 -2px 14px -6px rgba(203, 166, 247, 0.5);
+  background: color-mix(in srgb, var(--purple) 6%, transparent);
+  box-shadow: 0 -2px 14px -6px color-mix(in srgb, var(--purple) 50%, transparent);
 }
 
 .home-tile-label {
diff --git a/frontend/packages/shared/src/terminal.css b/frontend/packages/shared/src/terminal.css
index 6a39682c..2cfe7dee 100644
--- a/frontend/packages/shared/src/terminal.css
+++ b/frontend/packages/shared/src/terminal.css
@@ -18,7 +18,7 @@
 
 .terminal-wrap {
   position: relative;
-  background: rgba(17, 17, 27, 0.78);
+  background: color-mix(in srgb, var(--crust) 78%, transparent);
   -webkit-backdrop-filter: blur(8px) saturate(120%);
   backdrop-filter: blur(8px) saturate(120%);
   border: 1px solid var(--purple-dim);
@@ -120,12 +120,12 @@
   font-weight: normal;
   margin-left: 0.6em;
   font-size: 0.85em;
-  text-shadow: 0 0 6px rgba(250, 179, 135, 0.55);
+  text-shadow: 0 0 6px color-mix(in srgb, var(--amber) 55%, transparent);
   animation: badge-pulse 1.4s ease-in-out infinite;
 }
 @keyframes badge-pulse {
-  0%, 100% { opacity: 1;   text-shadow: 0 0 6px rgba(250, 179, 135, 0.55); }
-  50%      { opacity: 0.7; text-shadow: 0 0 14px rgba(250, 179, 135, 0.95); }
+  0%, 100% { opacity: 1;   text-shadow: 0 0 6px color-mix(in srgb, var(--amber) 55%, transparent); }
+  50%      { opacity: 0.7; text-shadow: 0 0 14px color-mix(in srgb, var(--amber) 95%, transparent); }
 }
 /* "↓ N new" pill: shown when new rows arrive while the operator is
    scrolled up; click to jump to bottom. Positioned by the wrapper's
@@ -136,7 +136,7 @@
   right: 1em;
   bottom: 4.2em;
   background: var(--amber);
-  color: #11111b;
+  color: var(--crust);
   font-family: inherit;
   font-size: 0.8em;
   font-weight: bold;
@@ -145,7 +145,7 @@
   border-radius: 999px;
   padding: 0.35em 0.9em;
   cursor: pointer;
-  box-shadow: 0 0 14px -2px rgba(250, 179, 135, 0.85);
+  box-shadow: 0 0 14px -2px color-mix(in srgb, var(--amber) 85%, transparent);
   opacity: 0;
   transform: translateY(6px);
   pointer-events: none;

From 09787dd1c347f9632f3c9a05bad68c49df238cd8 Mon Sep 17 00:00:00 2001
From: iris <iris@hyperhive.local>
Date: Mon, 8 Jun 2026 21:07:15 +0200
Subject: [PATCH 2/2] refactor(frontend): base16 theme contract in a swappable
 colors.css
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

Split the palette into two standalone stylesheets:
- colors.css — the 16 base16 slots (--base00..--base0F). This is the
  entire theme swap contract; a generator (e.g. a stylix base16 scheme,
  which is natively base00-base0F) replaces only this file.
- theme.css — the semantic layer (--bg, --purple, …) derived from the
  base16 slots via var()/color-mix. Never changes on a swap.

Every page links colors.css then theme.css; theme.css does NOT @import
colors.css (that would re-bake the slots into it) — they're separate
dist outputs so a swap touches just colors.css. Pixel-identical refactor:
base16 defaults are Catppuccin Mocha and the three off-slot vars
(--crust, --muted, --subtext0) derive via color-mix reproducing their
exact prior hexes.

Wires colors.css through both build.mjs CSS entry lists, the
@hive/shared exports map, and all 7 page templates. css-vars.md + the
frontend.nix output-list comment updated.
---
 docs/web-ui/css-vars.md                       | 126 +++++++++++++-----
 frontend/packages/agent/build.mjs             |  11 +-
 frontend/packages/agent/src/colors.css        |   6 +
 frontend/packages/agent/src/index.html        |   1 +
 frontend/packages/agent/src/screen.html       |   1 +
 frontend/packages/agent/src/stats.html        |   1 +
 frontend/packages/agent/src/theme.css         |  10 +-
 frontend/packages/dashboard/build.mjs         |  11 +-
 frontend/packages/dashboard/src/colors.css    |   6 +
 .../packages/dashboard/src/dashboard.html     |   1 +
 frontend/packages/dashboard/src/flow.html     |   1 +
 frontend/packages/dashboard/src/index.html    |   1 +
 frontend/packages/dashboard/src/logs.html     |   1 +
 frontend/packages/dashboard/src/theme.css     |  10 +-
 frontend/packages/shared/package.json         |   1 +
 frontend/packages/shared/src/colors.css       |  31 +++++
 frontend/packages/shared/src/theme.css        |  59 ++++----
 nix/frontend.nix                              |   4 +-
 18 files changed, 201 insertions(+), 81 deletions(-)
 create mode 100644 frontend/packages/agent/src/colors.css
 create mode 100644 frontend/packages/dashboard/src/colors.css
 create mode 100644 frontend/packages/shared/src/colors.css

diff --git a/docs/web-ui/css-vars.md b/docs/web-ui/css-vars.md
index 54f86636..ecbdb9e9 100644
--- a/docs/web-ui/css-vars.md
+++ b/docs/web-ui/css-vars.md
@@ -1,41 +1,57 @@
 # CSS custom properties (theme variables)
 
-All colour variables are declared **once** in
-`frontend/packages/shared/src/theme.css` under `:root`.
-Per-page stylesheets (`common.css`, `dashboard.css`, `flow.css`, `logs.css`, `agent.css`) must reference these
-names and must **not** redeclare them. (`base.css` holds only the
-shared `body` typography — it references the palette but no longer
-defines it.)
+Colour variables live in **two standalone stylesheets**, split so a theme
+swap touches only the first:
 
-`theme.css` is deliberately a **standalone** stylesheet, not `@import`ed
-into the page bundles: each package re-exports it (`src/theme.css` →
-`@import "@hive/shared/theme.css"`) so esbuild emits its own
-`dist/static/theme.css`, and every page links it **first**
-(`<link rel="stylesheet" href=".../theme.css">`) ahead of the page CSS.
-Because the palette lives in its own output file, a theme swap — e.g. a
-stylix-generated variant carrying the same variable names — can replace
-just that one file without rebuilding the rest of the frontend bundle.
+1. **`colors.css`** — the 16 `--base00`…`--base0F` base16 slots. **This is
+   the entire theme swap contract.** A generator (e.g. one fed a stylix
+   base16 scheme, which is natively base00–base0F) replaces *only this
+   file*.
+2. **`theme.css`** — the semantic layer: `--bg`, `--fg`, `--purple`, …
+   *derived* from the base16 slots (`--bg: var(--base00)` etc.). This is
+   what the app references and it **never changes on a swap**.
 
-## Palette (`theme.css`)
+Both files live in `frontend/packages/shared/src/`. Per-page stylesheets
+(`common.css`, `dashboard.css`, `flow.css`, `logs.css`, `agent.css`)
+reference the **semantic** names and must **not** redeclare them or reach
+for the raw `--baseNN` slots directly. (`base.css` holds only the shared
+`body` typography — it references the palette but no longer defines it.)
 
-| Variable | Hex | Catppuccin Mocha | Use |
+Both are deliberately standalone, not `@import`ed into the page bundles:
+each package re-exports them (`src/{colors,theme}.css` →
+`@import "@hive/shared/…"`) so esbuild emits its own
+`dist/static/colors.css` + `dist/static/theme.css`, and every page links
+them **first** (`colors.css` then `theme.css`) ahead of the page CSS. Note
+`theme.css` does **not** `@import` `colors.css` — that would bake the
+slots back into it; they're two separate output files so a swap replaces
+just `colors.css`. (Load order doesn't actually affect resolution —
+custom properties resolve at computed-value time — but `colors.css` is
+linked first for clarity.)
+
+## Semantic palette (`theme.css`)
+
+Each semantic var derives from a base16 slot (or, for the three that have
+no clean slot, a `color-mix()` over base16 — pixel-identical under the
+default palette). Default hexes shown are Catppuccin Mocha.
+
+| Variable | Derives from | Default hex | Use |
 |---|---|---|---|
-| `--bg` | `#1e1e2e` | base | page background |
-| `--bg-elev` | `#181825` | mantle | elevated surfaces: floating dropdowns, popovers |
-| `--crust` | `#11111b` | crust | terminal / code block background |
-| `--fg` | `#cdd6f4` | text | primary text colour |
-| `--muted` | `#7f849c` | overlay1 | secondary / dimmed text |
-| `--purple` | `#cba6f7` | mauve | accent — active tabs, links, highlights |
-| `--purple-dim` | `#45475a` | surface1 | subtle borders, terminal chrome, badge backgrounds |
-| `--cyan` | `#89dceb` | sky | tool-use events, info accents |
-| `--blue` | `#89b4fa` | blue | links, interactive accent (distinct from sky) |
-| `--pink` | `#f5c2e7` | pink | thinking events |
-| `--amber` | `#fab387` | peach | warnings, pending / running state |
-| `--yellow` | `#f9e2af` | yellow | flash messages, mild warnings |
-| `--green` | `#a6e3a1` | green | success, ok state |
-| `--red` | `#f38ba8` | red | errors, fail state |
-| `--border` | `#313244` | surface0 | general borders, hover/active backgrounds |
-| `--subtext0` | `#a6adc8` | subtext0 | secondary toolbar/status text; dimmer than `--fg`, lighter than `--muted` |
+| `--bg` | `base00` | `#1e1e2e` | page background |
+| `--bg-elev` | `base01` | `#181825` | elevated surfaces: floating dropdowns, popovers |
+| `--border` | `base02` | `#313244` | general borders, hover/active backgrounds |
+| `--purple-dim` | `base03` | `#45475a` | subtle borders, terminal chrome, badge backgrounds |
+| `--fg` | `base05` | `#cdd6f4` | primary text colour |
+| `--red` | `base08` | `#f38ba8` | errors, fail state |
+| `--amber` | `base09` | `#fab387` | warnings, pending / running state |
+| `--yellow` | `base0A` | `#f9e2af` | flash messages, mild warnings |
+| `--green` | `base0B` | `#a6e3a1` | success, ok state |
+| `--cyan` | `base0C` | `#89dceb` | tool-use events, info accents |
+| `--blue` | `base0D` | `#89b4fa` | links, interactive accent (distinct from cyan) |
+| `--purple` | `base0E` | `#cba6f7` | accent — active tabs, links, highlights |
+| `--pink` | `base0F` | `#f5c2e7` | thinking events |
+| `--crust` | `mix(base00 58%, #000)` | `#11111b` | terminal / code block background (below `--bg`) |
+| `--muted` | `mix(base05 55.5%, base00)` | `#7f849c` | secondary / dimmed text |
+| `--subtext0` | `mix(base05 77.7%, base00)` | `#a6adc8` | toolbar/status text; dimmer than `--fg`, lighter than `--muted` |
 
 ## Common mistakes
 
@@ -81,3 +97,49 @@ color: var(--red);    /* error */
 color: var(--amber);  /* warning / running */
 color: var(--green);  /* ok */
 ```
+
+## Theme swapping — the base16 contract
+
+**The swap interface is `colors.css` — the 16 base16 slots, not our
+semantic names.** A theme generator (e.g. one reading a stylix base16
+scheme) overrides only `colors.css`; the semantic layer in `theme.css`
+derives everything else, so the whole UI re-themes with nothing else to
+template or regenerate. The base16 slot → semantic mapping is *internal*
+to `theme.css` (the "Derives from" column above) — a generator never
+needs to know our var names, and `theme.css` + the page bundles stay
+untouched.
+
+`colors.css` base16 slot defaults (Catppuccin Mocha):
+
+| Slot | Default | Standard base16 role | Mapped to |
+|---|---|---|---|
+| `base00` | `#1e1e2e` | default bg | `--bg`, (darkened) `--crust` |
+| `base01` | `#181825` | lighter bg | `--bg-elev` |
+| `base02` | `#313244` | selection/surface | `--border` |
+| `base03` | `#45475a` | comments/dim surface | `--purple-dim` |
+| `base04` | `#585b70` | dark foreground | *(unused; kept for completeness)* |
+| `base05` | `#cdd6f4` | default foreground | `--fg`, (blended) `--muted`/`--subtext0` |
+| `base06` | `#f5e0dc` | light foreground | *(unused)* |
+| `base07` | `#b4befe` | lightest | *(unused)* |
+| `base08` | `#f38ba8` | red | `--red` |
+| `base09` | `#fab387` | orange | `--amber` |
+| `base0A` | `#f9e2af` | yellow | `--yellow` |
+| `base0B` | `#a6e3a1` | green | `--green` |
+| `base0C` | `#89dceb` | cyan | `--cyan` (our *sky*; Catppuccin's `base0C` is teal) |
+| `base0D` | `#89b4fa` | blue | `--blue` |
+| `base0E` | `#cba6f7` | magenta | `--purple` |
+| `base0F` | `#f5c2e7` | extra accent | `--pink` |
+
+Notes for theme authors:
+
+- **`--crust`, `--muted`, `--subtext0` have no own slot** — they're
+  derived via `color-mix()` over base16 (`--crust` = a darkened `base00`;
+  `--muted`/`--subtext0` = `base05`↔`base00` blends). They still track a
+  swap automatically; no generator action needed.
+- A standard Catppuccin base16 scheme uses **teal** for `base0C`; we
+  default it to **sky** (`#89dceb`) to preserve the historical accent. A
+  stylix Catppuccin scheme will shift `--cyan` to teal — that's the
+  operator's chosen scheme, working as intended.
+- `base04`/`base06`/`base07` aren't consumed by a semantic var today;
+  they're kept at their standard values so the 16-slot contract is
+  complete (a partial scheme override still works).
diff --git a/frontend/packages/agent/build.mjs b/frontend/packages/agent/build.mjs
index 60916de8..c5e1edfa 100644
--- a/frontend/packages/agent/build.mjs
+++ b/frontend/packages/agent/build.mjs
@@ -43,11 +43,12 @@ await build({
   logLevel: 'info',
 });
 
-// Bundle the CSS. `theme.css` re-exports the standalone Catppuccin
-// palette (kept its own output file so a theme swap replaces only it,
-// no bundle rebuild); `agent.css`'s @import lines pull in shared
-// base.css + terminal.css from the @hive/shared workspace dep.
-for (const entry of ['theme.css', 'agent.css']) {
+// Bundle the CSS. `colors.css` re-exports the standalone base16 palette
+// (the theme swap contract — its own output file so a swap replaces only
+// it, no bundle rebuild); `theme.css` is the semantic derivation layer;
+// `agent.css`'s @import lines pull in shared base.css + terminal.css from
+// the @hive/shared workspace dep.
+for (const entry of ['colors.css', 'theme.css', 'agent.css']) {
   await build({
     entryPoints: [src(entry)],
     outfile: staticDir(entry),
diff --git a/frontend/packages/agent/src/colors.css b/frontend/packages/agent/src/colors.css
new file mode 100644
index 00000000..72edd746
--- /dev/null
+++ b/frontend/packages/agent/src/colors.css
@@ -0,0 +1,6 @@
+/* Standalone base16 palette — re-exports the shared base16 slots so
+   esbuild emits its own `dist/static/colors.css`, linked first by every
+   agent page (before theme.css). This is the theme swap contract: a
+   stylix-generated variant replaces only this file. See
+   @hive/shared/colors.css + docs/web-ui/css-vars.md. */
+@import "@hive/shared/colors.css";
diff --git a/frontend/packages/agent/src/index.html b/frontend/packages/agent/src/index.html
index 74ac07a7..f27d2c81 100644
--- a/frontend/packages/agent/src/index.html
+++ b/frontend/packages/agent/src/index.html
@@ -5,6 +5,7 @@
   <meta name="viewport" content="width=device-width, initial-scale=1">
   <title>hyperhive agent</title>
   <link rel="icon" type="image/svg+xml" href="icon">
+  <link rel="stylesheet" href="static/colors.css">
   <link rel="stylesheet" href="static/theme.css">
   <link rel="stylesheet" href="static/agent.css">
 </head>
diff --git a/frontend/packages/agent/src/screen.html b/frontend/packages/agent/src/screen.html
index ed0ce3c1..d154733a 100644
--- a/frontend/packages/agent/src/screen.html
+++ b/frontend/packages/agent/src/screen.html
@@ -5,6 +5,7 @@
 <meta name="viewport" content="width=device-width, initial-scale=1">
 <title>screen</title>
 <link rel="icon" type="image/svg+xml" href="icon">
+<link rel="stylesheet" href="static/colors.css">
 <link rel="stylesheet" href="static/theme.css">
 <link rel="stylesheet" href="static/agent.css">
 </head>
diff --git a/frontend/packages/agent/src/stats.html b/frontend/packages/agent/src/stats.html
index 8fa106f3..8ed0a608 100644
--- a/frontend/packages/agent/src/stats.html
+++ b/frontend/packages/agent/src/stats.html
@@ -5,6 +5,7 @@
   <meta name="viewport" content="width=device-width, initial-scale=1">
   <title>hyperhive agent — stats</title>
   <link rel="icon" type="image/svg+xml" href="icon">
+  <link rel="stylesheet" href="static/colors.css">
   <link rel="stylesheet" href="static/theme.css">
   <link rel="stylesheet" href="static/agent.css">
 </head>
diff --git a/frontend/packages/agent/src/theme.css b/frontend/packages/agent/src/theme.css
index 941c4150..18d7d7b4 100644
--- a/frontend/packages/agent/src/theme.css
+++ b/frontend/packages/agent/src/theme.css
@@ -1,6 +1,6 @@
-/* Standalone theme bundle — re-exports the shared Catppuccin palette so
-   esbuild emits it as its own `dist/static/theme.css`, linked first by
-   every agent page. Kept separate from the page bundles so a theme swap
-   (e.g. stylix) replaces only this file. See @hive/shared/theme.css +
-   docs/web-ui/css-vars.md. */
+/* Standalone semantic theme layer — re-exports the shared derivation so
+   esbuild emits it as its own `dist/static/theme.css`, linked by every
+   agent page right after colors.css. The base16 slots it derives from
+   live in colors.css (the swap contract); a theme swap replaces only
+   that file. See @hive/shared/theme.css + docs/web-ui/css-vars.md. */
 @import "@hive/shared/theme.css";
diff --git a/frontend/packages/dashboard/build.mjs b/frontend/packages/dashboard/build.mjs
index 334a3623..6cdd553e 100644
--- a/frontend/packages/dashboard/build.mjs
+++ b/frontend/packages/dashboard/build.mjs
@@ -86,11 +86,12 @@ await build({
 });
 
 // Bundle CSS — one entry per page. esbuild resolves @import including
-// the package re-exports from @hive/shared. Each page loads theme.css
-// (the standalone Catppuccin palette — kept its own file so a theme
-// swap replaces only it) + common.css (shared typography, badges,
-// buttons, inbox, side panel) plus its own page-specific bundle.
-for (const entry of ['theme.css', 'common.css', 'dashboard.css', 'flow.css', 'logs.css', 'home.css']) {
+// the package re-exports from @hive/shared. Each page loads colors.css
+// (the standalone base16 palette — the theme swap contract, its own file
+// so a swap replaces only it) + theme.css (the semantic derivation
+// layer) + common.css (shared typography, badges, buttons, inbox, side
+// panel) plus its own page-specific bundle.
+for (const entry of ['colors.css', 'theme.css', 'common.css', 'dashboard.css', 'flow.css', 'logs.css', 'home.css']) {
   await build({
     entryPoints: [src(entry)],
     outfile: staticDir(entry),
diff --git a/frontend/packages/dashboard/src/colors.css b/frontend/packages/dashboard/src/colors.css
new file mode 100644
index 00000000..c3279b92
--- /dev/null
+++ b/frontend/packages/dashboard/src/colors.css
@@ -0,0 +1,6 @@
+/* Standalone base16 palette — re-exports the shared base16 slots so
+   esbuild emits its own `dist/static/colors.css`, linked first by every
+   dashboard page (before theme.css). This is the theme swap contract: a
+   stylix-generated variant replaces only this file. See
+   @hive/shared/colors.css + docs/web-ui/css-vars.md. */
+@import "@hive/shared/colors.css";
diff --git a/frontend/packages/dashboard/src/dashboard.html b/frontend/packages/dashboard/src/dashboard.html
index e4f5c44a..e998e496 100644
--- a/frontend/packages/dashboard/src/dashboard.html
+++ b/frontend/packages/dashboard/src/dashboard.html
@@ -5,6 +5,7 @@
   <meta name="viewport" content="width=device-width, initial-scale=1">
   <title>hyperhive // h1ve-c0re</title>
   <link rel="icon" type="image/svg+xml" href="/favicon.svg">
+  <link rel="stylesheet" href="/static/colors.css">
   <link rel="stylesheet" href="/static/theme.css">
   <link rel="stylesheet" href="/static/common.css">
   <link rel="stylesheet" href="/static/dashboard.css">
diff --git a/frontend/packages/dashboard/src/flow.html b/frontend/packages/dashboard/src/flow.html
index 9608204a..6b3d0c7e 100644
--- a/frontend/packages/dashboard/src/flow.html
+++ b/frontend/packages/dashboard/src/flow.html
@@ -5,6 +5,7 @@
   <meta name="viewport" content="width=device-width, initial-scale=1">
   <title>hyperhive // FL0W</title>
   <link rel="icon" type="image/svg+xml" href="/favicon.svg">
+  <link rel="stylesheet" href="/static/colors.css">
   <link rel="stylesheet" href="/static/theme.css">
   <link rel="stylesheet" href="/static/common.css">
   <link rel="stylesheet" href="/static/flow.css">
diff --git a/frontend/packages/dashboard/src/index.html b/frontend/packages/dashboard/src/index.html
index 17611612..63ebb5d1 100644
--- a/frontend/packages/dashboard/src/index.html
+++ b/frontend/packages/dashboard/src/index.html
@@ -5,6 +5,7 @@
   <meta name="viewport" content="width=device-width, initial-scale=1">
   <title>hyperhive // h0m3</title>
   <link rel="icon" type="image/svg+xml" href="/favicon.svg">
+  <link rel="stylesheet" href="/static/colors.css">
   <link rel="stylesheet" href="/static/theme.css">
   <link rel="stylesheet" href="/static/common.css">
   <link rel="stylesheet" href="/static/home.css">
diff --git a/frontend/packages/dashboard/src/logs.html b/frontend/packages/dashboard/src/logs.html
index 2dd7af56..2f6af3dc 100644
--- a/frontend/packages/dashboard/src/logs.html
+++ b/frontend/packages/dashboard/src/logs.html
@@ -5,6 +5,7 @@
   <meta name="viewport" content="width=device-width, initial-scale=1">
   <title>hyperhive // LOGS</title>
   <link rel="icon" type="image/svg+xml" href="/favicon.svg">
+  <link rel="stylesheet" href="/static/colors.css">
   <link rel="stylesheet" href="/static/theme.css">
   <link rel="stylesheet" href="/static/common.css">
   <link rel="stylesheet" href="/static/logs.css">
diff --git a/frontend/packages/dashboard/src/theme.css b/frontend/packages/dashboard/src/theme.css
index 5e71c223..b799ce30 100644
--- a/frontend/packages/dashboard/src/theme.css
+++ b/frontend/packages/dashboard/src/theme.css
@@ -1,6 +1,6 @@
-/* Standalone theme bundle — re-exports the shared Catppuccin palette so
-   esbuild emits it as its own `dist/static/theme.css`, linked first by
-   every dashboard page. Kept separate from the page bundles so a theme
-   swap (e.g. stylix) replaces only this file. See @hive/shared/theme.css
-   + docs/web-ui/css-vars.md. */
+/* Standalone semantic theme layer — re-exports the shared derivation so
+   esbuild emits it as its own `dist/static/theme.css`, linked by every
+   dashboard page right after colors.css. The base16 slots it derives
+   from live in colors.css (the swap contract); a theme swap replaces
+   only that file. See @hive/shared/theme.css + docs/web-ui/css-vars.md. */
 @import "@hive/shared/theme.css";
diff --git a/frontend/packages/shared/package.json b/frontend/packages/shared/package.json
index 35a885bd..1d9a7a1b 100644
--- a/frontend/packages/shared/package.json
+++ b/frontend/packages/shared/package.json
@@ -8,6 +8,7 @@
   "exports": {
     ".": "./src/index.js",
     "./terminal.js": "./src/terminal.js",
+    "./colors.css": "./src/colors.css",
     "./theme.css": "./src/theme.css",
     "./base.css": "./src/base.css",
     "./terminal.css": "./src/terminal.css"
diff --git a/frontend/packages/shared/src/colors.css b/frontend/packages/shared/src/colors.css
new file mode 100644
index 00000000..3fa8ca51
--- /dev/null
+++ b/frontend/packages/shared/src/colors.css
@@ -0,0 +1,31 @@
+/* base16 palette — THE THEME CONTRACT.
+
+   These 16 slots are the entire swap interface. A theme generator (e.g.
+   one fed a stylix base16 scheme, which is natively base00–base0F)
+   overrides *only this file*; `theme.css` derives every semantic var
+   (`--bg`, `--purple`, …) from these slots, so the whole UI re-themes
+   with nothing else to regenerate.
+
+   Kept as its own standalone stylesheet (not @import-ed into theme.css)
+   so a swap replaces just this ~16-line file — `theme.css` and the page
+   bundles stay untouched. Every page links this BEFORE `theme.css`. The
+   hex defaults are Catppuccin Mocha. Standard base16 slot meanings are
+   in the trailing comments. See docs/web-ui/css-vars.md. */
+:root {
+  --base00: #1e1e2e; /* default bg */
+  --base01: #181825; /* lighter bg (elevated surfaces) */
+  --base02: #313244; /* selection / surface — borders */
+  --base03: #45475a; /* comments / dim surface */
+  --base04: #585b70; /* dark foreground */
+  --base05: #cdd6f4; /* default foreground */
+  --base06: #f5e0dc; /* light foreground */
+  --base07: #b4befe; /* lightest */
+  --base08: #f38ba8; /* red */
+  --base09: #fab387; /* orange / peach */
+  --base0A: #f9e2af; /* yellow */
+  --base0B: #a6e3a1; /* green */
+  --base0C: #89dceb; /* cyan (our sky — note: Catppuccin's base0C is teal) */
+  --base0D: #89b4fa; /* blue */
+  --base0E: #cba6f7; /* magenta / mauve */
+  --base0F: #f5c2e7; /* extra accent — pink */
+}
diff --git a/frontend/packages/shared/src/theme.css b/frontend/packages/shared/src/theme.css
index 9c59c7e5..e7f696d8 100644
--- a/frontend/packages/shared/src/theme.css
+++ b/frontend/packages/shared/src/theme.css
@@ -1,30 +1,35 @@
-/* Theme colour variables (Catppuccin Mocha) — the single source of
-   truth for the hive UI palette. Kept in a standalone file, linked as
-   its own `<link rel="stylesheet" href=".../theme.css">` by every page
-   BEFORE the page CSS, so the `:root` vars are defined for everything
-   that references them (base typography, terminal, dashboard, agent).
+/* Semantic theme layer — derived from the base16 contract in
+   `colors.css`. This is what the app references (`--bg`, `--fg`,
+   `--purple`, …); page CSS must use these names, never literal colours
+   and never the raw `--baseNN` slots.
 
-   Why standalone rather than `@import`ed into the page bundles: esbuild
-   inlines `@import` at build time, which would bake the palette into
-   every CSS bundle. Emitting `theme.css` as its own output file lets a
-   theme swap (e.g. a stylix-generated variant carrying the same var
-   names) replace just this one file without rebuilding the rest of the
-   frontend. See docs/web-ui/css-vars.md. */
+   Standalone stylesheet, linked by every page right AFTER `colors.css`
+   (which defines the `--baseNN` slots these rules resolve against). Kept
+   separate from the page bundles — esbuild would otherwise inline an
+   `@import` and bake the palette into every CSS bundle.
+
+   A theme swap touches only `colors.css` (the 16 base16 slots); this
+   derivation layer never changes. See docs/web-ui/css-vars.md. */
 :root {
-  --bg: #1e1e2e;        /* base */
-  --bg-elev: #181825;   /* mantle */
-  --crust: #11111b;     /* crust — terminal background */
-  --fg: #cdd6f4;        /* text */
-  --muted: #7f849c;     /* overlay1 */
-  --purple: #cba6f7;    /* mauve */
-  --purple-dim: #45475a;/* surface1 */
-  --cyan: #89dceb;      /* sky */
-  --blue: #89b4fa;      /* blue */
-  --pink: #f5c2e7;      /* pink */
-  --amber: #fab387;     /* peach */
-  --yellow: #f9e2af;    /* yellow */
-  --green: #a6e3a1;     /* green */
-  --red: #f38ba8;       /* red */
-  --border: #313244;    /* surface0 */
-  --subtext0: #a6adc8;  /* subtext0 — secondary/toolbar text, dimmer than --fg but lighter than --muted */
+  --bg: var(--base00);
+  --bg-elev: var(--base01); /* elevated surfaces: dropdowns, popovers */
+  --border: var(--base02); /* general borders, hover/active backgrounds */
+  --purple-dim: var(--base03); /* subtle borders, terminal chrome, badge bg */
+  --fg: var(--base05);
+  --red: var(--base08); /* errors, fail state */
+  --amber: var(--base09); /* warnings, pending / running state */
+  --yellow: var(--base0A); /* flash messages, mild warnings */
+  --green: var(--base0B); /* success, ok state */
+  --cyan: var(--base0C); /* tool-use events, info accents */
+  --blue: var(--base0D); /* links, interactive accent (distinct from cyan) */
+  --purple: var(--base0E); /* accent — active tabs, links, highlights */
+  --pink: var(--base0F); /* thinking events */
+
+  /* Off-base16 (no exact slot) — derived from base16 so they still track
+     a swap. Each is pixel-identical to its prior literal under the
+     default palette: --crust is a darkened bg; --muted / --subtext0 are
+     foreground↔background blends (two levels of dimmed text). */
+  --crust: color-mix(in srgb, var(--base00) 58%, #000); /* terminal / code bg, below --bg */
+  --muted: color-mix(in srgb, var(--base05) 55.5%, var(--base00)); /* secondary / dimmed text */
+  --subtext0: color-mix(in srgb, var(--base05) 77.7%, var(--base00)); /* toolbar/status text; dimmer than --fg, lighter than --muted */
 }
diff --git a/nix/frontend.nix b/nix/frontend.nix
index 9740b27f..0d50b929 100644
--- a/nix/frontend.nix
+++ b/nix/frontend.nix
@@ -18,12 +18,12 @@
 #       index.html (H0M3 hub, served at /) dashboard.html (operator SPA,
 #       served at /dashboard.html) flow.html logs.html favicon.svg
 #       static/{home,tabs,flow,logs,stream-worker}.js{,.map}
-#       static/{common,home,dashboard,flow,logs,theme}.css
+#       static/{colors,theme,common,home,dashboard,flow,logs}.css
 #   $out/agent/       the per-agent default UI (layered with
 #                     hyperhive.frontend.extraFiles at activation time)
 #       index.html stats.html screen.html
 #       static/{app,stats}.js{,.map}
-#       static/agent.css
+#       static/{colors,theme,agent}.css
 #
 # The dashboard favicon lives outside the npm tree (`branding/hyperhive
 # .svg` at the repo root) — we copy it in during the install phase so