UX#8: hex color ratchet — lock baseline, migration starts with DimensionsTab

Adds tests/HexColorRatchet.test.ts that ratchets per-file hex-literal
counts against tests/fixtures/hex_color_baseline.json. Two guarantees:

  1) New files cannot introduce hex literals — must use theme tokens
     (T.surface, T.text, T.success, T.danger, etc. from @/theme).
  2) Existing files cannot regress past their current count — the
     baseline only goes down. To intentionally add hex, the migrator
     must edit the baseline JSON, which is visible in code review.

Current baseline: 592 hex literals across 45 component files. The
test passes today; future PRs will fail if they bloat any file or
add a new offender.

DimensionsTab.tsx migrated as a proof of pattern: every "#6b7280"
replaced with T.textSecondary, baseline count down from 18 to 12.

This is a ratchet, not a mass rewrite. Migration continues file by
file in future commits; the test guarantees the tide only goes out.

Author: apstenku123

vbgui/src/components/sidebar/DimensionsTab.tsx

@@ -8,6 +8,7 @@
 
 import { useState } from "react";
 import { DimEnvEditor } from "@/components/DimEnvEditor";
+import { T } from "@/theme";
 
 export interface InferenceEntryClient {
   brick: string;
@@ -56,14 +57,14 @@ export function DimensionsTab({
 
       <header style={{ marginBottom: 8 }}>
         <h4 style={{ margin: 0, fontSize: 13 }}>Inferred Dimensions</h4>
-        <div style={{ color: "#6b7280", marginTop: 2 }}>
+        <div style={{ color: T.textSecondary, marginTop: 2 }}>
           {visible.length} of {log.length} entries
         </div>
       </header>
 
       <div style={{ display: "flex", gap: 6, marginBottom: 8 }}>
         <label style={{ display: "flex", flexDirection: "column" }}>
-          <span style={{ color: "#6b7280", fontSize: 11 }}>Source</span>
+          <span style={{ color: T.textSecondary, fontSize: 11 }}>Source</span>
           <select data-testid="dimensions-filter-source"
                   value={filterSource}
                   onChange={(e) =>
@@ -74,7 +75,7 @@ export function DimensionsTab({
           </select>
         </label>
         <label style={{ display: "flex", flexDirection: "column", flex: 1 }}>
-          <span style={{ color: "#6b7280", fontSize: 11 }}>Brick</span>
+          <span style={{ color: T.textSecondary, fontSize: 11 }}>Brick</span>
           <input data-testid="dimensions-filter-brick"
                  placeholder="filter…"
                  value={filterBrick}
@@ -115,7 +116,7 @@ export function DimensionsTab({
                         fontSize: 10, textTransform: "uppercase",
                       }}>{e.source}</span>
               </td>
-              <td style={{ ...td, color: "#6b7280", fontSize: 11 }}>
+              <td style={{ ...td, color: T.textSecondary, fontSize: 11 }}>
                 {e.reason}
               </td>
               <td style={td}>
@@ -164,7 +165,7 @@ export function DimensionsTab({
                            ? "#1e40af" : "#111827" }}>
               <strong>{e.brick}.{e.param}</strong> ={" "}
               <code>{String(e.value)}</code>{" "}
-              <em style={{ color: "#6b7280" }}>
+              <em style={{ color: T.textSecondary }}>
                 ({e.source}; {e.reason})
               </em>
             </li>
@@ -177,7 +178,7 @@ export function DimensionsTab({
 
 const th: React.CSSProperties = {
   textAlign: "left", padding: "4px 6px",
-  color: "#6b7280", fontSize: 11, fontWeight: 600,
+  color: T.textSecondary, fontSize: 11, fontWeight: 600,
   borderBottom: "1px solid #e5e7eb",
 };
 const td: React.CSSProperties = { padding: "4px 6px" };

vbgui/tests/HexColorRatchet.test.ts

@@ -0,0 +1,109 @@
+// UX#8 — ratchet test for hex colour literals in vbgui components.
+//
+// 518 hex literals across 45 component files (commit 5a4e314 baseline).
+// Replacing all in one go would be a giant risky diff, so this test
+// runs as a ratchet: every file has a max-allowed hex count locked in
+// tests/fixtures/hex_color_baseline.json. New code is forbidden from:
+//
+//   - Exceeding the baseline count for an existing file (ratchet down).
+//   - Adding a NEW file with hex literals not present in the baseline.
+//
+// Migration path is to replace `#xxxxxx` literals with `T.surface`,
+// `T.text`, `T.success`, etc. from `@/theme`, then drop the file's
+// baseline number. Drop the entry entirely when count hits 0.
+
+import { describe, it, expect } from "vitest";
+import { readFileSync, readdirSync, statSync } from "node:fs";
+import { dirname, join, resolve } from "node:path";
+import { fileURLToPath } from "node:url";
+import baseline from "./fixtures/hex_color_baseline.json";
+
+const HERE = dirname(fileURLToPath(import.meta.url));
+const COMPONENTS_DIR = resolve(HERE, "..", "src", "components");
+const HEX_RE = /#[0-9a-fA-F]{3,8}\b/g;
+const IGNORE_FILES = new Set(["theme.ts"]);
+
+function walk(dir: string, rel = ""): string[] {
+  const out: string[] = [];
+  for (const entry of readdirSync(dir)) {
+    if (IGNORE_FILES.has(entry)) continue;
+    const full = join(dir, entry);
+    const relPath = rel ? `${rel}/${entry}` : entry;
+    if (statSync(full).isDirectory()) {
+      out.push(...walk(full, relPath));
+    } else if (entry.endsWith(".ts") || entry.endsWith(".tsx")) {
+      out.push(`components/${relPath}`);
+    }
+  }
+  return out;
+}
+
+function countHex(absPath: string): number {
+  const src = readFileSync(absPath, "utf-8");
+  // Ignore line + block comments so docs/JSDoc with example colours
+  // don't dominate the count.
+  const stripped = src
+    .replace(/\/\*[\s\S]*?\*\//g, "")
+    .replace(/(^|[^:])\/\/[^\n]*/g, (_m, p1) => p1);
+  return (stripped.match(HEX_RE) ?? []).length;
+}
+
+const baselineMap = baseline as Record<string, number>;
+
+describe("UX#8: hex color ratchet (only counts can decrease)", () => {
+  const files = walk(COMPONENTS_DIR);
+
+  it("does not introduce hex colors in new files", () => {
+    const offenders: string[] = [];
+    for (const f of files) {
+      if (f in baselineMap) continue;
+      const abs = join(COMPONENTS_DIR, f.replace(/^components\//, ""));
+      const n = countHex(abs);
+      if (n > 0) {
+        offenders.push(`${f}: ${n} hex literal${n === 1 ? "" : "s"}`);
+      }
+    }
+    if (offenders.length > 0) {
+      throw new Error(
+        "UX#8: new files contain hex literals — use theme tokens " +
+        "from @/theme (T.surface, T.text, T.success, etc.) instead. " +
+        "If you must add a hex literal, bump the baseline at " +
+        "tests/fixtures/hex_color_baseline.json:\n  " +
+        offenders.join("\n  "),
+      );
+    }
+  });
+
+  it("does not exceed per-file baseline hex counts", () => {
+    const offenders: string[] = [];
+    for (const [rel, limit] of Object.entries(baselineMap)) {
+      const abs = join(COMPONENTS_DIR, rel.replace(/^components\//, ""));
+      try {
+        const n = countHex(abs);
+        if (n > limit) {
+          offenders.push(`${rel}: ${n} > baseline ${limit}`);
+        }
+      } catch {
+        // File deleted — that's fine, baseline becomes stale but
+        // doesn't fail; CI can drop the entry on next commit.
+      }
+    }
+    if (offenders.length > 0) {
+      throw new Error(
+        "UX#8: hex literal counts exceed baseline — please replace " +
+        "with theme tokens (T.surface/T.text/etc) from @/theme, or " +
+        "if the addition is intentional, update the baseline at " +
+        "tests/fixtures/hex_color_baseline.json:\n  " +
+        offenders.join("\n  "),
+      );
+    }
+  });
+
+  it("baseline file is non-empty and tracks > 0 violations " +
+     "(starting reality, not aspiration)", () => {
+    const total = Object.values(baselineMap)
+      .reduce((a, b) => a + b, 0);
+    expect(Object.keys(baselineMap).length).toBeGreaterThan(0);
+    expect(total).toBeGreaterThan(0);
+  });
+});

vbgui/tests/fixtures/hex_color_baseline.json

@@ -0,0 +1,47 @@
+{
+  "components/AppTabs.tsx": 4,
+  "components/AutoGroupButton.tsx": 13,
+  "components/BottomStrip.tsx": 7,
+  "components/BrickContextPanel.tsx": 32,
+  "components/BrickNode.tsx": 1,
+  "components/CompileTracePanel.tsx": 20,
+  "components/DataInspector.tsx": 47,
+  "components/DimEnvEditor.tsx": 2,
+  "components/ErrorDetailsPanel.tsx": 10,
+  "components/ExplainModal.tsx": 1,
+  "components/FlowCanvas.tsx": 24,
+  "components/GalleryScaleDownSlider.tsx": 9,
+  "components/GalleryTab.tsx": 5,
+  "components/GenerationPanel.tsx": 10,
+  "components/GradAttnPanel.tsx": 5,
+  "components/HFQuickStartModal.tsx": 6,
+  "components/HelpIcon.tsx": 30,
+  "components/InsertIntoEdgeBar.tsx": 2,
+  "components/LLMGalleryWizardModal.tsx": 24,
+  "components/LiveGenPanel.tsx": 9,
+  "components/LossChart.tsx": 8,
+  "components/LossGhostNode.tsx": 2,
+  "components/LossSurfaceModal.tsx": 3,
+  "components/MemoryBar.tsx": 9,
+  "components/ParallelComposeBar.tsx": 2,
+  "components/RunResultModal.tsx": 15,
+  "components/ScheduleEditor.tsx": 14,
+  "components/Sidebar.tsx": 5,
+  "components/SweepPanel.tsx": 6,
+  "components/TokenizerMatrixTab.tsx": 16,
+  "components/TokenizerPlayground.tsx": 28,
+  "components/Tooltip.tsx": 4,
+  "components/TopBar.tsx": 27,
+  "components/TrainExtrasOverlay.tsx": 40,
+  "components/TrainLiveControls.tsx": 46,
+  "components/TransplantBar.tsx": 2,
+  "components/diagrams/TensorDiagram.tsx": 20,
+  "components/sidebar/AblationsTab.tsx": 19,
+  "components/sidebar/DimensionsTab.tsx": 12,
+  "components/sidebar/GotchasTab.tsx": 17,
+  "components/sidebar/MemoryMatrixTab.tsx": 11,
+  "components/sidebar/OptimTab.tsx": 2,
+  "components/sidebar/RewritersTab.tsx": 1,
+  "components/sidebar/ShardingTab.tsx": 6,
+  "components/sidebar/SideChannelsTab.tsx": 16
+}