From 7604651579be52c73326ddc6781b8e9d0bb70db0 Mon Sep 17 00:00:00 2001
From: Brummel <mould@mycelium.de>
Date: Sat, 4 Jul 2026 11:24:07 +0200
Subject: [PATCH] =?UTF-8?q?feat(cli):=20aura.css=20becomes=20the=20style?=
 =?UTF-8?q?=20pin=20=E2=80=94=20tokens,=20component=20library,=20CLAUDE.md?=
 =?UTF-8?q?=20rule?=
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

Second half of the style pin. assets/aura.css now carries (a) the full
:root token palette (Catppuccin-Mocha-derived; --bg deliberately darker
than Mocha base; new --border3 #585b70 completes the border ladder at an
identical computed value), (b) the shell rules migrated color-literal to
var() with identical computed values (font stacks stay literal — the
--mono token's longer fallback chain would change the computed value),
and (c) an opt-in, class-scoped component library distilled from the
milestone demo page (.aura-doc register, .wrap, .badge, .stats, .cards,
.term, .callout, table.res, .pipe) — unused by the runtime pages, which
render pixel-identically. CHART_CSS migrates to the same tokens (it
lands in the same document after the shell <style>, so :root resolves).
CLAUDE.md gains the binding '## HTML surfaces' rule: every HTML surface
embeds this asset; extend, never fork.

Gates: suite 1043/0, clippy -D warnings clean, doc build 0 warnings;
regenerated chart page resolves all 17 used var() names against its
:root. Independent CSS audit passed (two cosmetic notes: --bg3/--orange
currently unused; the pre-existing html,body height:100% also reaches
future .aura-doc pages).

closes #209
---
 CLAUDE.md                       |   8 ++
 crates/aura-cli/assets/aura.css | 166 ++++++++++++++++++++++++++++----
 crates/aura-cli/src/render.rs   |  10 +-
 3 files changed, 160 insertions(+), 24 deletions(-)

diff --git a/CLAUDE.md b/CLAUDE.md
index f71c7a9..838e5f6 100644
--- a/CLAUDE.md
+++ b/CLAUDE.md
@@ -161,6 +161,14 @@ design decision, not a refactor, and belongs in the ledger.
     streams during, recorded traces after) — never a scene editor; topology is
     grown in Rust + hot-reload, runtime params are UI-tunable.
 
+## HTML surfaces
+
+Every HTML surface — runtime-rendered (chart/graph viewer) or ad-hoc generated
+(demo/report pages) — embeds `crates/aura-cli/assets/aura.css` as its style
+source; the palette tokens and shared components live only there. New components
+extend that file; never fork the palette. Pages stay self-contained: all assets
+inlined, no external requests. Design record: issue #209.
+
 ## Skills plugin: project facts
 
 The few facts the skills plugin needs that genuinely vary per project.
diff --git a/crates/aura-cli/assets/aura.css b/crates/aura-cli/assets/aura.css
index 08f1866..6d17d33 100644
--- a/crates/aura-cli/assets/aura.css
+++ b/crates/aura-cli/assets/aura.css
@@ -1,20 +1,146 @@
-  html, body { margin: 0; height: 100%; background: #16161a; color: #cdd6f4;
-    font-family: ui-monospace, monospace; }
-  header { padding: 8px 14px; border-bottom: 1px solid #313244; font-size: 13px;
-    display: flex; gap: 16px; align-items: baseline; flex-wrap: nowrap;
-    white-space: nowrap; overflow: hidden; }
-  header b { color: #f5e0dc; } .sub { color: #6c7086; }
-  #crumb a { color: #89b4fa; cursor: pointer; text-decoration: none; }
-  #crumb a:hover { text-decoration: underline; }
-  #crumb .sep { color: #6c7086; }
-  #status { color: #6c7086; margin-left: auto; }
-  #stage { width: 100%; height: calc(100% - 44px); }
-  #stage svg { width: 100%; height: 100%; cursor: default; }
-  #stage svg text { cursor: inherit; user-select: none; -webkit-user-select: none; }
-  #stage svg a { cursor: inherit; }
-  #err { padding: 14px; color: #f38ba8; white-space: pre-wrap; }
-  #tip { position: fixed; display: none; pointer-events: none; z-index: 10;
-    background: #1e1e2e; border: 1px solid #585b70; border-radius: 6px; padding: 6px 9px;
-    font-family: ui-monospace, monospace; font-size: 12px; color: #cdd6f4;
-    max-width: 420px; box-shadow: 0 6px 18px rgba(0,0,0,.55); line-height: 1.5; }
-  #tip b { color: #f5e0dc; } #tip code { color: #89b4fa; } #tip .dim { color: #7f849c; }
+/* aura.css — the single source of aura's frontend style: palette tokens +
+ * shared components. Embedded verbatim into every runtime page (render.rs
+ * SHELL_HEAD) and inlined into ad-hoc demo/report pages. New components
+ * extend this file; never fork the palette. Design record: issue #209. */
+
+/* ---------------------------------------------------------------------------
+ * :root tokens
+ * Catppuccin-Mocha-derived palette; the page background (--bg) is
+ * deliberately darker than the Mocha base. --border3 (#585b70, Mocha
+ * surface2) completes the border ladder used by the shell tooltip.
+ * ------------------------------------------------------------------------- */
+:root {
+  --bg: #16161a; --bg2: #1e1e2e; --bg3: #24243a;
+  --border: #313244; --border2: #45475a; --border3: #585b70;
+  --fg: #cdd6f4; --dim: #7f849c; --dim2: #6c7086;
+  --accent: #f5e0dc; --blue: #89b4fa; --green: #a6e3a1;
+  --red: #f38ba8; --orange: #fab387; --yellow: #f9e2af;
+  --mauve: #cba6f7; --teal: #94e2d5;
+  --mono: ui-monospace, 'JetBrains Mono', 'Cascadia Code', Menlo, monospace;
+  --sans: system-ui, -apple-system, 'Segoe UI', Roboto, sans-serif;
+}
+
+/* ---------------------------------------------------------------------------
+ * shell
+ * Rules for the runtime viewer pages (graph / chart). Values are identical
+ * to the pre-token literals; only colors with a token were migrated to
+ * var(...). The font stays the literal `ui-monospace, monospace` (the
+ * --mono token carries a longer fallback chain and would change the
+ * computed value).
+ * ------------------------------------------------------------------------- */
+html, body { margin: 0; height: 100%; background: var(--bg); color: var(--fg);
+  font-family: ui-monospace, monospace; }
+header { padding: 8px 14px; border-bottom: 1px solid var(--border); font-size: 13px;
+  display: flex; gap: 16px; align-items: baseline; flex-wrap: nowrap;
+  white-space: nowrap; overflow: hidden; }
+header b { color: var(--accent); } .sub { color: var(--dim2); }
+#crumb a { color: var(--blue); cursor: pointer; text-decoration: none; }
+#crumb a:hover { text-decoration: underline; }
+#crumb .sep { color: var(--dim2); }
+#status { color: var(--dim2); margin-left: auto; }
+#stage { width: 100%; height: calc(100% - 44px); }
+#stage svg { width: 100%; height: 100%; cursor: default; }
+#stage svg text { cursor: inherit; user-select: none; -webkit-user-select: none; }
+#stage svg a { cursor: inherit; }
+#err { padding: 14px; color: var(--red); white-space: pre-wrap; }
+#tip { position: fixed; display: none; pointer-events: none; z-index: 10;
+  background: var(--bg2); border: 1px solid var(--border3); border-radius: 6px; padding: 6px 9px;
+  font-family: ui-monospace, monospace; font-size: 12px; color: var(--fg);
+  max-width: 420px; box-shadow: 0 6px 18px rgba(0,0,0,.55); line-height: 1.5; }
+#tip b { color: var(--accent); } #tip code { color: var(--blue); } #tip .dim { color: var(--dim); }
+
+/* ---------------------------------------------------------------------------
+ * components (opt-in, class-scoped)
+ * Shared component library for ad-hoc document pages (demos, reports).
+ * Every rule is scoped to a class, so the runtime viewer pages — which use
+ * none of these classes — render pixel-identically with this block present.
+ * Element-level typography is scoped under .aura-doc: only pages that opt
+ * in via <body class="aura-doc"> get the sans document register.
+ * ------------------------------------------------------------------------- */
+
+/* document register — opt-in via body.aura-doc */
+body.aura-doc { font-family: var(--sans); line-height: 1.6; }
+.aura-doc, .aura-doc * { box-sizing: border-box; }
+.aura-doc a { color: var(--blue); text-decoration: none; }
+.aura-doc a:hover { text-decoration: underline; }
+.aura-doc code { font-family: var(--mono); font-size: 0.92em; background: var(--bg2);
+  border: 1px solid var(--border); border-radius: 4px; padding: 1px 5px; }
+
+/* centered content column */
+.wrap { max-width: 1100px; margin: 0 auto; padding: 0 24px; }
+
+/* status pill */
+.badge { display: inline-block; font-family: var(--mono); font-size: 12.5px;
+  padding: 3px 10px; border-radius: 20px; border: 1px solid; margin-right: 8px; }
+.badge.green { color: var(--green); border-color: var(--green); background: rgba(166,227,161,.08); }
+.badge.dim { color: var(--dim); border-color: var(--border2); }
+
+/* headline-number tiles */
+.stats { display: grid; grid-template-columns: repeat(auto-fit, minmax(150px, 1fr));
+  gap: 12px; margin-top: 28px; }
+.stat { background: var(--bg2); border: 1px solid var(--border); border-radius: 10px;
+  padding: 14px 16px; }
+.stat .n { font-family: var(--mono); font-size: 24px; color: var(--accent); }
+.stat .l { color: var(--dim); font-size: 12.5px; margin-top: 2px; }
+
+/* card grid */
+.cards { display: grid; gap: 16px; margin: 20px 0; }
+.cards.c3 { grid-template-columns: repeat(auto-fit, minmax(300px, 1fr)); }
+.cards.c2 { grid-template-columns: repeat(auto-fit, minmax(380px, 1fr)); }
+.card { background: var(--bg2); border: 1px solid var(--border); border-radius: 10px;
+  padding: 18px 20px; }
+.card h3 { margin: 0 0 4px; font-size: 16px; }
+.card h3 .tag { font-family: var(--mono); font-size: 11px; color: var(--dim);
+  font-weight: 400; margin-left: 6px; }
+.card .cid { font-family: var(--mono); font-size: 11.5px; color: var(--teal);
+  word-break: break-all; margin: 4px 0 10px; }
+.card .cid b { color: var(--accent); }
+.card p { color: var(--dim); font-size: 14px; margin: 6px 0; }
+.card pre { background: #131320; border: 1px solid var(--border); border-radius: 8px;
+  padding: 12px; overflow-x: auto; font-family: var(--mono); font-size: 12px;
+  line-height: 1.5; margin: 10px 0 0; }
+
+/* terminal transcript */
+.term { background: #131320; border: 1px solid var(--border); border-radius: 10px;
+  overflow: hidden; margin: 16px 0; }
+.term .bar { display: flex; gap: 8px; align-items: center; padding: 7px 12px;
+  background: var(--bg2); border-bottom: 1px solid var(--border);
+  font-family: var(--mono); font-size: 12px; color: var(--dim); }
+.term .bar .dots { display: inline-flex; gap: 5px; margin-right: 4px; }
+.term .bar .dots i { width: 9px; height: 9px; border-radius: 50%; background: var(--border2); }
+.term pre { margin: 0; padding: 14px 16px; overflow-x: auto; font-family: var(--mono);
+  font-size: 13px; line-height: 1.55; }
+.term pre .p { color: var(--green); }
+.term pre .cmd { color: var(--fg); font-weight: 600; }
+.term pre .out { color: #b6bdd8; }
+.term pre .err { color: var(--red); }
+.term pre .hi { color: var(--yellow); }
+.term pre .ok { color: var(--green); }
+.term pre .dim { color: var(--dim2); }
+
+/* attention block */
+.callout { border-left: 3px solid var(--yellow); background: rgba(249,226,175,.06);
+  border-radius: 0 8px 8px 0; padding: 12px 18px; margin: 20px 0; color: var(--fg);
+  font-size: 14.5px; }
+.callout.green { border-color: var(--green); background: rgba(166,227,161,.06); }
+.callout b { color: var(--yellow); }
+.callout.green b { color: var(--green); }
+
+/* results table */
+table.res { border-collapse: collapse; width: 100%; margin: 16px 0; font-size: 14px; }
+table.res th, table.res td { border: 1px solid var(--border); padding: 8px 12px; text-align: left; }
+table.res th { background: var(--bg2); color: var(--dim); font-weight: 600; font-size: 12.5px; }
+table.res td { font-family: var(--mono); font-size: 13px; }
+table.res td.neg { color: var(--red); }
+table.res td.pos { color: var(--green); }
+table.res td:first-child { color: var(--dim); font-family: var(--sans); font-size: 13.5px; }
+
+/* pipeline stages */
+.pipe { display: flex; flex-wrap: wrap; gap: 10px; align-items: stretch; margin: 24px 0; }
+.pipe .stage { flex: 1 1 170px; background: var(--bg2); border: 1px solid var(--border2);
+  border-radius: 10px; padding: 12px 14px; position: relative; }
+.pipe .stage.ann { border-style: dashed; }
+.pipe .stage b { font-family: var(--mono); font-size: 14px; color: var(--accent); display: block; }
+.pipe .stage i { font-style: normal; font-size: 11px; color: var(--mauve); font-family: var(--mono); }
+.pipe .stage p { margin: 6px 0 0; font-size: 12.5px; color: var(--dim); line-height: 1.45; }
+.pipe .arr { align-self: center; color: var(--dim2); font-family: var(--mono); font-size: 18px; }
diff --git a/crates/aura-cli/src/render.rs b/crates/aura-cli/src/render.rs
index 1c0eb71..14e4f3c 100644
--- a/crates/aura-cli/src/render.rs
+++ b/crates/aura-cli/src/render.rs
@@ -67,12 +67,14 @@ const CHART_VIEWER_JS: &str = include_str!("../assets/chart-viewer.js");
 
 /// Chart-page-only styling (the `#xmode-toggle` button) — injected by
 /// `render_chart_html` after the vendored uPlot CSS, NOT into the shared `SHELL_HEAD`
-/// (the graph page has no toggle and must not inherit its rule).
+/// (the graph page has no toggle and must not inherit its rule). Colors are
+/// `var(--x)` tokens from `assets/aura.css`; they resolve because this block lands
+/// in the same document, after the shell `<style>` that defines `:root`.
 const CHART_CSS: &str = r#"
-#xmode-toggle { margin-left: auto; background: #1e1e2e; color: #cdd6f4;
-  border: 1px solid #313244; border-radius: 6px; padding: 4px 10px;
+#xmode-toggle { margin-left: auto; background: var(--bg2); color: var(--fg);
+  border: 1px solid var(--border); border-radius: 6px; padding: 4px 10px;
   font-family: ui-monospace, monospace; font-size: 12px; cursor: pointer; }
-#xmode-toggle:hover { border-color: #89b4fa; color: #f5e0dc; }
+#xmode-toggle:hover { border-color: var(--blue); color: var(--accent); }
 "#;
 
 /// Assemble the self-contained interactive graph viewer page for `root`.