@terpjs/contract 0.6.0 → 0.7.0

package/src/tokens.contrast.test.js

@@ -0,0 +1,244 @@
+import fs from "node:fs";
+import { fileURLToPath } from "node:url";
+
+import { describe, expect, it } from "vitest";
+
+import { parseRules } from "./css-rules.js";
+
+// Text legibility of the token sheet, measured rather than reviewed.
+//
+// The sheet is the single source of every colour a Terp app renders, and a foreground and
+// a background are chosen independently — one token moves for a good reason and a pairing
+// three components away stops being readable. Nothing catches that today: the token guard
+// checks spelling, the theme test checks completeness, and neither knows that
+// `--color-status-warning` is only ever painted on `--color-status-warning-soft`.
+//
+// So the pairings are declared here, as data, and held to WCAG 2.1 contrast. Each entry is
+// a pairing some framework component actually renders as text; decorative boundaries are
+// deliberately absent, because WCAG sets no ratio for a divider and asserting one would
+// only teach the next reader to ignore this file.
+
+const here = (name) => fileURLToPath(new URL(name, import.meta.url));
+
+const tokensCss = fs.readFileSync(here("./tokens.css"), "utf8");
+const registry = JSON.parse(fs.readFileSync(here("../themes.json"), "utf8"));
+
+/** WCAG 2.1 AA, normal-size text. Large text and UI boundaries would be 3.0. */
+const AA_NORMAL_TEXT = 4.5;
+
+/** WCAG 2.1 AAA, normal-size text — the bar a theme named for contrast has to clear. */
+const AAA_NORMAL_TEXT = 7;
+
+/**
+ * Pairings the framework renders as text, read from the shared data file.
+ *
+ * `token-pairs.json` is the single source: this gate holds each pairing to AA, and the
+ * generated manifest publishes the same list so a theme editor or an agent can tell which
+ * tokens must stay legible against which. Restating them here would let the gate and the
+ * published contract disagree about what is guaranteed.
+ *
+ * `label` names the component surface so a failure says what a user would be looking at, and
+ * `id` is the stable key — labels intentionally repeat across the primitive and semantic
+ * layers ("body text on the canvas" describes both), so only the id can identify a pairing.
+ */
+const TEXT_PAIRS = JSON.parse(fs.readFileSync(here("../token-pairs.json"), "utf8")).textPairs;
+
+
+/**
+ * Pairings that do not reach AA today, with the ratio measured when they were recorded.
+ *
+ * A ratchet, not a mute button, and it moves in one direction only: a pairing may not drop
+ * below its recorded floor, and once it reaches AA it must leave this table — so an
+ * improvement cannot quietly leave a stale allowance behind, and a regression cannot hide
+ * behind an existing one. Keyed `<theme>/<label>`.
+ *
+ * Floors are the measured ratio truncated to four places, and the comparison below is
+ * against the *raw* ratio. Rounding to two places would straddle the AA boundary in both
+ * directions — 4.4951 would round into a pass, and two of these floors would only hold
+ * because rounding lifted them — so neither the gate nor the ratchet may depend on it.
+ *
+ * All five clear 3.0 (AA for large text and UI components) and fail 4.5 (normal text).
+ * Badge copy and button labels are normal text, so these are real defects, deliberately
+ * left visible: changing a token value repaints every app, which belongs to the semantic
+ * token layer rather than to the test that found it. Emptying this table is that work's
+ * acceptance criterion.
+ *
+ * Every entry is in `light` or `dark`, the two themes that shipped before the table existed.
+ * The themes added since carry none: a theme authored against this gate has no reason to land
+ * below AA, so an allowance for a new theme is a design mistake and not a legacy to record.
+ */
+const BELOW_AA = new Map([]);
+
+/** The declarations of the one rule whose selector is exactly `selector`. */
+function declarationsFor(selector) {
+  const matches = parseRules(tokensCss).filter((rule) => rule.selector === selector);
+  if (matches.length !== 1) {
+    throw new Error(
+      `expected exactly one \`${selector}\` rule in tokens.css, found ${matches.length}`,
+    );
+  }
+  return matches[0].declarations;
+}
+
+// A theme is the base root with its own colours laid over it — the same resolution the
+// cascade performs, so a pairing is measured at the value a browser would paint. The theme
+// list comes from the registry rather than from a literal here, so a theme cannot be added to
+// the sheet without this gate measuring it.
+const base = declarationsFor(":root");
+const THEMES = Object.fromEntries(
+  registry.themes.map((theme) => [
+    theme.name,
+    theme.name === registry.base
+      ? base
+      : new Map([...base, ...declarationsFor(`[data-theme='${theme.name}']`)]),
+  ]),
+);
+
+/** sRGB channel → linear light, per WCAG 2.1 relative luminance. */
+function linearise(channel) {
+  const scaled = channel / 255;
+  return scaled <= 0.04045 ? scaled / 12.92 : ((scaled + 0.055) / 1.055) ** 2.4;
+}
+
+/** Relative luminance of a `#rrggbb` value. */
+function relativeLuminance(hex) {
+  const match = /^#([0-9a-f]{6})$/i.exec(hex);
+  if (!match) throw new Error(`not a six-digit hex colour: ${hex}`);
+  const [red, green, blue] = [0, 2, 4].map((offset) =>
+    linearise(Number.parseInt(match[1].slice(offset, offset + 2), 16)),
+  );
+  return 0.2126 * red + 0.7152 * green + 0.0722 * blue;
+}
+
+/** WCAG 2.1 contrast ratio between two `#rrggbb` values, 1.0 – 21.0. */
+function contrastRatio(a, b) {
+  const [darker, lighter] = [relativeLuminance(a), relativeLuminance(b)].sort(
+    (x, y) => x - y,
+  );
+  return (lighter + 0.05) / (darker + 0.05);
+}
+
+/**
+ * The ratio a theme's pairings must reach. AA for normal text by default; a theme may declare
+ * a higher floor in `themes.json`, which is how the high-contrast theme's promise is a gate
+ * rather than a sentence in its description.
+ */
+const floorFor = (name) =>
+  registry.themes.find((theme) => theme.name === name)?.minimumContrast ?? AA_NORMAL_TEXT;
+
+/** Every pairing, in every registered theme, tagged with its `BELOW_AA` key. */
+const cases = Object.entries(THEMES).flatMap(([theme, declarations]) =>
+  TEXT_PAIRS.map((pair) => ({
+    ...pair,
+    theme,
+    declarations,
+    key: `${theme}/${pair.id}`,
+    floor: floorFor(theme),
+  })),
+);
+
+/** The measured ratio for one case, with the painted values for the failure message. */
+function measure({ fg, bg, declarations }) {
+  const foreground = declarations.get(fg);
+  const background = declarations.get(bg);
+  expect(foreground, `${fg} is not declared`).toBeDefined();
+  expect(background, `${bg} is not declared`).toBeDefined();
+  return {
+    ratio: contrastRatio(foreground, background),
+    painted: `${fg} (${foreground}) on ${bg} (${background})`,
+  };
+}
+
+const meetsAa = cases.filter(({ key }) => !BELOW_AA.has(key));
+const knownGaps = cases.filter(({ key }) => BELOW_AA.has(key));
+
+describe("token sheet text contrast", () => {
+  it("measures a known ratio correctly", () => {
+    // The calculator itself needs a fixture, or a subtly wrong exponent would move every
+    // ratio below in the same direction and the suite would still look green.
+    expect(contrastRatio("#000000", "#ffffff")).toBeCloseTo(21, 5);
+    expect(contrastRatio("#ffffff", "#ffffff")).toBeCloseTo(1, 5);
+    // A published mid-tone pair, so the curve is checked and not just its endpoints.
+    expect(contrastRatio("#767676", "#ffffff")).toBeCloseTo(4.5422, 4);
+  });
+
+  it("gives every pairing a unique id", () => {
+    // The id is the ratchet key and the manifest's handle. A duplicate would silently make
+    // one pairing's allowance apply to another, and labels cannot substitute — they repeat
+    // across the primitive and semantic layers on purpose.
+    const ids = TEXT_PAIRS.map((pair) => pair.id);
+    expect(ids.filter((id) => !id)).toEqual([]);
+    expect(new Set(ids).size).toBe(ids.length);
+  });
+
+  it("measures every registered theme", () => {
+    // The theme list is read from `themes.json`, so a theme added to the sheet is measured
+    // automatically — but only if the resolution above actually found its block. A theme that
+    // resolved to an empty map would produce cases that all read the base values and pass,
+    // which is the failure mode worth pinning: silent, and it looks like coverage.
+    expect(Object.keys(THEMES)).toEqual(registry.themes.map((theme) => theme.name));
+    for (const [name, declarations] of Object.entries(THEMES)) {
+      expect(declarations.size, `${name} resolved to nothing`).toBe(base.size);
+    }
+    expect(cases).toHaveLength(registry.themes.length * TEXT_PAIRS.length);
+  });
+
+  it("keeps the known gaps to the themes that predate the gate", () => {
+    // A theme authored against this gate has no reason to land below AA, so an allowance for a
+    // newer theme would be a design mistake being recorded as history. Naming the two
+    // grandfathered themes explicitly is what stops the table from becoming a general amnesty.
+    const grandfathered = new Set(["light", "dark"]);
+    const themeOf = (key) => key.slice(0, key.indexOf("/"));
+    expect([...BELOW_AA.keys()].filter((key) => !grandfathered.has(themeOf(key)))).toEqual([]);
+  });
+
+  it("holds every pairing in exactly one of the two sets", () => {
+    // A typo in a `BELOW_AA` key would silently move a pairing from the strict set into
+    // neither set, so the gate would stop asserting anything about it.
+    expect(meetsAa.length + knownGaps.length).toBe(cases.length);
+    expect(knownGaps).toHaveLength(BELOW_AA.size);
+    const known = new Set(cases.map(({ key }) => key));
+    expect([...BELOW_AA.keys()].filter((key) => !known.has(key))).toEqual([]);
+    expect([...BELOW_AA.keys()]).toEqual([...BELOW_AA.keys()].sort());
+  });
+
+  it.each(meetsAa)("$theme: $id ($label) reaches $floor:1 for normal text", (testCase) => {
+    const { ratio, painted } = measure(testCase);
+    expect(ratio, painted).toBeGreaterThanOrEqual(testCase.floor);
+  });
+
+  it("holds the high-contrast theme to AAA rather than AA", () => {
+    // A theme called "high contrast" that only cleared the same bar as every other theme would
+    // be a name doing the work a measurement should. The floor is declared per theme in
+    // `themes.json`; this asserts at least one theme actually raises it, so the mechanism
+    // cannot rot into an unused field that reads as enforcement.
+    const raised = registry.themes.filter((theme) => theme.minimumContrast !== undefined);
+    expect(raised.length).toBeGreaterThan(0);
+    for (const theme of raised) {
+      expect(theme.minimumContrast, `${theme.name} floor`).toBeGreaterThanOrEqual(
+        AAA_NORMAL_TEXT,
+      );
+      expect(
+        [...BELOW_AA.keys()].filter((key) => key.startsWith(`${theme.name}/`)),
+        `${theme.name} raises its floor, so it cannot also carry an allowance`,
+      ).toEqual([]);
+    }
+  });
+
+  // Deliberately titled as a gap, not as a pass: a green line reading "warning badge
+  // reaches AA" for a pairing measuring 3.07 is worse than no test, because it is the line
+  // a reviewer trusts.
+  it.each(knownGaps)(
+    "$theme: $id ($label) is a known contrast gap, held at its floor",
+    (testCase) => {
+      const { ratio, painted } = measure(testCase);
+      const floor = BELOW_AA.get(testCase.key);
+      expect(ratio, `${painted} regressed below its recorded floor`).toBeGreaterThanOrEqual(
+        floor,
+      );
+      expect(ratio, `${painted} now reaches AA — remove it from BELOW_AA`).toBeLessThan(
+        AA_NORMAL_TEXT,
+      );
+    },
+  );
+});

package/src/tokens.css

@@ -5,7 +5,7 @@
 :root {
   /* Opts native chrome (scrollbars, the <select> option popup, form controls,
      text-field carets) into the light palette so it never renders as foreign
-     OS-light chrome. The dark blocks below flip it to dark. */
+     OS-dark chrome. Each theme block below sets its own. */
   color-scheme: light;
   --color-brand-primary: #2563eb;
   --color-brand-primary-contrast: #ffffff;
@@ -22,15 +22,40 @@
   --color-neutral-700: #334155;
   --color-neutral-800: #1e293b;
   --color-neutral-900: #0f172a;
-  --color-status-success: #16a34a;
+  --color-status-success: #15803d;
   --color-status-success-soft: #f0fdf4;
-  --color-status-warning: #d97706;
+  --color-status-warning: #b45309;
   --color-status-warning-soft: #fffbeb;
-  --color-status-danger: #dc2626;
+  --color-status-danger: #b91c1c;
   --color-status-danger-soft: #fef2f2;
-  --color-status-info: #0284c7;
+  --color-status-info: #0369a1;
   --color-status-info-soft: #f0f9ff;
   --color-focus-ring: rgba(37,99,235,0.35);
+  --color-bg-canvas: #f8fafc;
+  --color-bg-surface: #ffffff;
+  --color-bg-raised: #ffffff;
+  --color-bg-inset: #f1f5f9;
+  --color-fg-default: #0f172a;
+  --color-fg-muted: #475569;
+  --color-fg-subtle: #64748b;
+  --color-fg-accent: #1d4ed8;
+  --color-fg-on-brand: #ffffff;
+  --color-border-default: #e2e8f0;
+  --color-border-strong: #cbd5e1;
+  --color-border-subtle: #f1f5f9;
+  --color-interactive-hover: #f1f5f9;
+  --color-interactive-active: #e2e8f0;
+  --color-interactive-selected: #eff6ff;
+  --color-sidebar-bg: #f8fafc;
+  --color-sidebar-fg: #0f172a;
+  --color-sidebar-muted: #475569;
+  --color-sidebar-accent: #f1f5f9;
+  --color-sidebar-border: #e2e8f0;
+  --color-chart-1: #2563eb;
+  --color-chart-2: #0d9488;
+  --color-chart-3: #d97706;
+  --color-chart-4: #7c3aed;
+  --color-chart-5: #db2777;
   --shadow-sm: 0 1px 2px rgb(15 23 42 / 0.06);
   --shadow-md: 0 4px 12px rgb(15 23 42 / 0.10);
   --shadow-lg: 0 12px 32px rgb(15 23 42 / 0.18);
@@ -39,12 +64,40 @@
   --space-2: 0.5rem;
   --space-3: 0.75rem;
   --space-4: 1rem;
+  --space-5: 1.25rem;
   --space-6: 1.5rem;
+  --space-7: 1.75rem;
   --space-8: 2rem;
+  --space-10: 2.5rem;
+  --space-12: 3rem;
+  --space-16: 4rem;
+  --space-20: 5rem;
   --radius-sm: 0.25rem;
   --radius-md: 0.5rem;
   --radius-lg: 0.75rem;
+  --radius-xl: 1rem;
   --radius-full: 9999px;
+  --border-width-thin: 1px;
+  --border-width-base: 2px;
+  --border-width-thick: 3px;
+  --z-index-base: 0;
+  --z-index-sticky: 30;
+  --z-index-backdrop: 40;
+  --z-index-drawer: 50;
+  --z-index-popover: 60;
+  --z-index-tooltip: 70;
+  --z-index-toast: 100;
+  --breakpoint-sm: 480px;
+  --breakpoint-md: 768px;
+  --breakpoint-lg: 1024px;
+  --breakpoint-xl: 1280px;
+  --motion-duration-instant: 100ms;
+  --motion-duration-fast: 150ms;
+  --motion-duration-base: 250ms;
+  --motion-duration-slow: 400ms;
+  --motion-easing-standard: ease;
+  --motion-easing-entrance: cubic-bezier(0, 0, 0.2, 1);
+  --motion-easing-exit: cubic-bezier(0.4, 0, 1, 1);
   --font-family-sans: system-ui, -apple-system, 'Segoe UI', Roboto, sans-serif;
   --font-family-mono: ui-monospace, SFMono-Regular, Menlo, monospace;
   --font-size-xs: 0.75rem;
@@ -52,19 +105,30 @@
   --font-size-base: 1rem;
   --font-size-lg: 1.125rem;
   --font-size-xl: 1.5rem;
+  --font-size-2xl: 1.875rem;
+  --font-size-3xl: 2.25rem;
+  --font-size-display: 3rem;
   --font-weight-normal: 400;
   --font-weight-medium: 500;
   --font-weight-semibold: 600;
   --font-weight-bold: 700;
+  --font-line-height-tight: 1.2;
+  --font-line-height-snug: 1.35;
+  --font-line-height-base: 1.5;
+  --font-line-height-relaxed: 1.7;
+  --font-letter-spacing-tight: -0.02em;
+  --font-letter-spacing-base: 0;
+  --font-letter-spacing-wide: 0.08em;
 }
 
-/* Dark theme: an explicit user/app choice via <html data-theme="dark">. */
+/* Dark: an explicit choice via <html data-theme="dark">.
+   The slate-neutral dark counterpart to light, and the theme the OS dark preference selects. */
 [data-theme='dark'] {
   color-scheme: dark;
-  --color-brand-primary: #3b82f6;
+  --color-brand-primary: #1d4ed8;
   --color-brand-primary-contrast: #ffffff;
-  --color-brand-primary-hover: #60a5fa;
-  --color-brand-primary-soft: #1e3a5f;
+  --color-brand-primary-hover: #2563eb;
+  --color-brand-primary-soft: #15304e;
   --color-neutral-0: #1e293b;
   --color-neutral-50: #0f172a;
   --color-neutral-100: #263449;
@@ -85,16 +149,206 @@
   --color-status-info: #38bdf8;
   --color-status-info-soft: #12303f;
   --color-focus-ring: rgba(96,165,250,0.45);
+  --color-bg-canvas: #0f172a;
+  --color-bg-surface: #1e293b;
+  --color-bg-raised: #263449;
+  --color-bg-inset: #0f172a;
+  --color-fg-default: #f1f5f9;
+  --color-fg-muted: #b4c0d0;
+  --color-fg-subtle: #94a3b8;
+  --color-fg-accent: #60a5fa;
+  --color-fg-on-brand: #ffffff;
+  --color-border-default: #334155;
+  --color-border-strong: #475569;
+  --color-border-subtle: #263449;
+  --color-interactive-hover: #263449;
+  --color-interactive-active: #334155;
+  --color-interactive-selected: #15304e;
+  --color-sidebar-bg: #1e293b;
+  --color-sidebar-fg: #f1f5f9;
+  --color-sidebar-muted: #b4c0d0;
+  --color-sidebar-accent: #334155;
+  --color-sidebar-border: #334155;
+  --color-chart-1: #60a5fa;
+  --color-chart-2: #2dd4bf;
+  --color-chart-3: #fbbf24;
+  --color-chart-4: #a78bfa;
+  --color-chart-5: #f472b6;
 }
 
-/* Dark theme: the OS preference, unless the app pinned light explicitly. */
+/* Midnight: an explicit choice via <html data-theme="midnight">.
+   A near-black dark for low light and OLED displays: cooler neutrals, a deeper canvas than dark, and a deeper accent that holds a white label at AA. */
+[data-theme='midnight'] {
+  color-scheme: dark;
+  --color-brand-primary: #0b4ea8;
+  --color-brand-primary-contrast: #ffffff;
+  --color-brand-primary-hover: #1158c7;
+  --color-brand-primary-soft: #0c2d6b;
+  --color-neutral-0: #0d1117;
+  --color-neutral-50: #010409;
+  --color-neutral-100: #161b22;
+  --color-neutral-200: #21262d;
+  --color-neutral-300: #30363d;
+  --color-neutral-400: #484f58;
+  --color-neutral-500: #7d8590;
+  --color-neutral-600: #9aa4b2;
+  --color-neutral-700: #c9d1d9;
+  --color-neutral-800: #e6edf3;
+  --color-neutral-900: #f0f6fc;
+  --color-status-success: #3fb950;
+  --color-status-success-soft: #0c2417;
+  --color-status-warning: #d29922;
+  --color-status-warning-soft: #271a06;
+  --color-status-danger: #f85149;
+  --color-status-danger-soft: #2b0d0d;
+  --color-status-info: #58a6ff;
+  --color-status-info-soft: #0b2545;
+  --color-focus-ring: rgba(88,166,255,0.5);
+  --color-bg-canvas: #010409;
+  --color-bg-surface: #0d1117;
+  --color-bg-raised: #161b22;
+  --color-bg-inset: #010409;
+  --color-fg-default: #f0f6fc;
+  --color-fg-muted: #9aa4b2;
+  --color-fg-subtle: #8b949e;
+  --color-fg-accent: #58a6ff;
+  --color-fg-on-brand: #ffffff;
+  --color-border-default: #30363d;
+  --color-border-strong: #484f58;
+  --color-border-subtle: #21262d;
+  --color-interactive-hover: #161b22;
+  --color-interactive-active: #21262d;
+  --color-interactive-selected: #0c2d6b;
+  --color-sidebar-bg: #0d1117;
+  --color-sidebar-fg: #f0f6fc;
+  --color-sidebar-muted: #9aa4b2;
+  --color-sidebar-accent: #21262d;
+  --color-sidebar-border: #21262d;
+  --color-chart-1: #58a6ff;
+  --color-chart-2: #3fb950;
+  --color-chart-3: #d29922;
+  --color-chart-4: #bc8cff;
+  --color-chart-5: #f778ba;
+}
+
+/* Twilight: an explicit choice via <html data-theme="twilight">.
+   A warm violet-tinted dark. Its neutrals sit in a different hue family from dark and midnight, which is what proves a theme is a palette rather than a lightness setting. */
+[data-theme='twilight'] {
+  color-scheme: dark;
+  --color-brand-primary: #5b21b6;
+  --color-brand-primary-contrast: #ffffff;
+  --color-brand-primary-hover: #6d28d9;
+  --color-brand-primary-soft: #2b2350;
+  --color-neutral-0: #241f31;
+  --color-neutral-50: #1a1622;
+  --color-neutral-100: #2d2740;
+  --color-neutral-200: #3a3350;
+  --color-neutral-300: #4d4468;
+  --color-neutral-400: #6b5f8a;
+  --color-neutral-500: #9d90b8;
+  --color-neutral-600: #b9aecd;
+  --color-neutral-700: #d8d0e6;
+  --color-neutral-800: #ece7f3;
+  --color-neutral-900: #f6f3fa;
+  --color-status-success: #5ed49a;
+  --color-status-success-soft: #14322a;
+  --color-status-warning: #e8b04b;
+  --color-status-warning-soft: #332612;
+  --color-status-danger: #f58a92;
+  --color-status-danger-soft: #3a1a25;
+  --color-status-info: #7cb8f0;
+  --color-status-info-soft: #1a2c44;
+  --color-focus-ring: rgba(167,139,250,0.5);
+  --color-bg-canvas: #1a1622;
+  --color-bg-surface: #241f31;
+  --color-bg-raised: #2d2740;
+  --color-bg-inset: #1a1622;
+  --color-fg-default: #f6f3fa;
+  --color-fg-muted: #b9aecd;
+  --color-fg-subtle: #a294bd;
+  --color-fg-accent: #a78bfa;
+  --color-fg-on-brand: #ffffff;
+  --color-border-default: #3a3350;
+  --color-border-strong: #4d4468;
+  --color-border-subtle: #2d2740;
+  --color-interactive-hover: #2d2740;
+  --color-interactive-active: #3a3350;
+  --color-interactive-selected: #2b2350;
+  --color-sidebar-bg: #241f31;
+  --color-sidebar-fg: #f6f3fa;
+  --color-sidebar-muted: #b9aecd;
+  --color-sidebar-accent: #3a3350;
+  --color-sidebar-border: #3a3350;
+  --color-chart-1: #a78bfa;
+  --color-chart-2: #5ed49a;
+  --color-chart-3: #e8b04b;
+  --color-chart-4: #7cb8f0;
+  --color-chart-5: #f58ac8;
+}
+
+/* High contrast: an explicit choice via <html data-theme="contrast">.
+   A high-contrast light theme: white surfaces, near-black text, darkened accents and visible borders. Every declared text pairing reaches AAA, not just AA. Not wired to `prefers-contrast: more` — that needs a dark high-contrast counterpart first, or a user who asked for both more contrast and dark would be handed a light theme. */
+[data-theme='contrast'] {
+  color-scheme: light;
+  --color-brand-primary: #0842a0;
+  --color-brand-primary-contrast: #ffffff;
+  --color-brand-primary-hover: #05275a;
+  --color-brand-primary-soft: #e8f0fe;
+  --color-neutral-0: #ffffff;
+  --color-neutral-50: #ffffff;
+  --color-neutral-100: #f2f2f2;
+  --color-neutral-200: #595959;
+  --color-neutral-300: #404040;
+  --color-neutral-400: #303030;
+  --color-neutral-500: #1f1f1f;
+  --color-neutral-600: #141414;
+  --color-neutral-700: #0a0a0a;
+  --color-neutral-800: #000000;
+  --color-neutral-900: #000000;
+  --color-status-success: #0a5c2b;
+  --color-status-success-soft: #e6f4ea;
+  --color-status-warning: #6b3800;
+  --color-status-warning-soft: #fdf1e0;
+  --color-status-danger: #96000c;
+  --color-status-danger-soft: #fce8e8;
+  --color-status-info: #0b4a8f;
+  --color-status-info-soft: #e5f0fb;
+  --color-focus-ring: rgba(8,66,160,0.7);
+  --color-bg-canvas: #ffffff;
+  --color-bg-surface: #ffffff;
+  --color-bg-raised: #ffffff;
+  --color-bg-inset: #f2f2f2;
+  --color-fg-default: #000000;
+  --color-fg-muted: #141414;
+  --color-fg-subtle: #1f1f1f;
+  --color-fg-accent: #0842a0;
+  --color-fg-on-brand: #ffffff;
+  --color-border-default: #595959;
+  --color-border-strong: #000000;
+  --color-border-subtle: #767676;
+  --color-interactive-hover: #f2f2f2;
+  --color-interactive-active: #e0e0e0;
+  --color-interactive-selected: #e8f0fe;
+  --color-sidebar-bg: #ffffff;
+  --color-sidebar-fg: #000000;
+  --color-sidebar-muted: #141414;
+  --color-sidebar-accent: #e8f0fe;
+  --color-sidebar-border: #595959;
+  --color-chart-1: #0842a0;
+  --color-chart-2: #00564a;
+  --color-chart-3: #6b3800;
+  --color-chart-4: #4b1f79;
+  --color-chart-5: #8c0a4d;
+}
+
+/* Dark: the OS preference, unless the app pinned any theme explicitly. */
 @media (prefers-color-scheme: dark) {
-  :root:not([data-theme='light']) {
+  :root:not([data-theme]) {
     color-scheme: dark;
-    --color-brand-primary: #3b82f6;
+    --color-brand-primary: #1d4ed8;
     --color-brand-primary-contrast: #ffffff;
-    --color-brand-primary-hover: #60a5fa;
-    --color-brand-primary-soft: #1e3a5f;
+    --color-brand-primary-hover: #2563eb;
+    --color-brand-primary-soft: #15304e;
     --color-neutral-0: #1e293b;
     --color-neutral-50: #0f172a;
     --color-neutral-100: #263449;
@@ -115,5 +369,30 @@
     --color-status-info: #38bdf8;
     --color-status-info-soft: #12303f;
     --color-focus-ring: rgba(96,165,250,0.45);
+    --color-bg-canvas: #0f172a;
+    --color-bg-surface: #1e293b;
+    --color-bg-raised: #263449;
+    --color-bg-inset: #0f172a;
+    --color-fg-default: #f1f5f9;
+    --color-fg-muted: #b4c0d0;
+    --color-fg-subtle: #94a3b8;
+    --color-fg-accent: #60a5fa;
+    --color-fg-on-brand: #ffffff;
+    --color-border-default: #334155;
+    --color-border-strong: #475569;
+    --color-border-subtle: #263449;
+    --color-interactive-hover: #263449;
+    --color-interactive-active: #334155;
+    --color-interactive-selected: #15304e;
+    --color-sidebar-bg: #1e293b;
+    --color-sidebar-fg: #f1f5f9;
+    --color-sidebar-muted: #b4c0d0;
+    --color-sidebar-accent: #334155;
+    --color-sidebar-border: #334155;
+    --color-chart-1: #60a5fa;
+    --color-chart-2: #2dd4bf;
+    --color-chart-3: #fbbf24;
+    --color-chart-4: #a78bfa;
+    --color-chart-5: #f472b6;
   }
 }