@stigmer/theme 3.1.3 → 3.1.5

package/src/contract/resolve.ts

@@ -0,0 +1,92 @@
+import type { ThemeFileTokens, TokenDeclaration } from "./parse.js";
+
+/**
+ * Cascade-faithful token resolution for a Stigmer theme scope.
+ *
+ * Models the element `StigmerProvider` renders:
+ * `<div class="stgm stgm-theme-<id>" data-stgm-color-mode="<mode>">` with
+ * `tokens.css` loaded before the preset CSS. On that element the cascade
+ * resolves each token in this priority order (highest first):
+ *
+ * 1. **preset dark** — `[data-stgm-color-mode="dark"] .stgm-theme-<id>`
+ *    (specificity 0,2,0) beats everything else.
+ * 2. **preset light** — `.stgm-theme-<id>` (0,1,0) ties with the default
+ *    dark block (0,1,0) and wins: preset CSS is loaded after `tokens.css`
+ *    (source order within a layer) and, in app setups that import presets
+ *    unlayered while `tokens.css` sits in `@layer stgm`, unlayered wins
+ *    outright. Both routes give the preset-light value priority — which is
+ *    why a preset that defines a token only in its light block leaks that
+ *    light value into dark mode (a defect the audit detects; see
+ *    `presetLightLeaksIntoDark`).
+ * 3. **default dark** — `[data-stgm-color-mode="dark"]` in `tokens.css`.
+ * 4. **default light** — `:root` in `tokens.css` (inherited).
+ */
+
+/** Which cascade layer supplied a resolved token value. */
+export type TokenSource =
+  | "preset-dark"
+  | "preset-light"
+  | "default-dark"
+  | "default-light";
+
+/** A token value after cascade resolution, with its winning layer. */
+export interface ResolvedToken {
+  readonly name: string;
+  readonly value: string;
+  readonly source: TokenSource;
+}
+
+export type ColorMode = "light" | "dark";
+
+/**
+ * Resolve every token visible in the given scope.
+ *
+ * @param defaults Parsed `tokens.css`.
+ * @param preset Parsed preset CSS, or `undefined` for the built-in default
+ *   preset (no theme class).
+ */
+export function resolveTokens(
+  defaults: ThemeFileTokens,
+  preset: ThemeFileTokens | undefined,
+  mode: ColorMode,
+): ReadonlyMap<string, ResolvedToken> {
+  // Lowest priority first; later layers overwrite.
+  const layers: readonly { source: TokenSource; tokens: ReadonlyMap<string, TokenDeclaration> }[] = [
+    { source: "default-light", tokens: defaults.light },
+    ...(mode === "dark" ? [{ source: "default-dark" as const, tokens: defaults.dark }] : []),
+    ...(preset ? [{ source: "preset-light" as const, tokens: preset.light }] : []),
+    ...(preset && mode === "dark"
+      ? [{ source: "preset-dark" as const, tokens: preset.dark }]
+      : []),
+  ];
+
+  const resolved = new Map<string, ResolvedToken>();
+  for (const layer of layers) {
+    for (const [name, declaration] of layer.tokens) {
+      resolved.set(name, { name, value: declaration.value, source: layer.source });
+    }
+  }
+  return resolved;
+}
+
+/**
+ * Tokens whose dark-mode value is silently the preset's *light* value —
+ * the preset defines them in its light block but not its dark block, while
+ * the defaults do provide a dark value that can no longer take effect.
+ *
+ * Every such token is a latent defect: the preset author almost certainly
+ * intended the default dark value to show through, but the cascade gives
+ * the preset-light value priority (see module doc, rule 2).
+ */
+export function presetLightLeaksIntoDark(
+  defaults: ThemeFileTokens,
+  preset: ThemeFileTokens,
+): readonly string[] {
+  const leaks: string[] = [];
+  for (const name of preset.light.keys()) {
+    if (!preset.dark.has(name) && defaults.dark.has(name)) {
+      leaks.push(name);
+    }
+  }
+  return leaks;
+}

package/src/presets/corporate.css

@@ -44,7 +44,7 @@
   --stgm-muted-faint: oklch(0.96 0.01 250);
   --stgm-primary-muted: oklch(0.58 0.10 250);
   --stgm-destructive-muted: oklch(0.65 0.12 27);
-  --stgm-muted-foreground-faint: oklch(0.68 0.02 250);
+  --stgm-muted-foreground-faint: oklch(0.62 0.02 250);
   --stgm-backdrop: oklch(0.97 0.01 250 / 80%);
   --stgm-sidebar: oklch(0.20 0.06 250);
   --stgm-sidebar-foreground: oklch(0.93 0 0);
@@ -98,7 +98,7 @@
   --stgm-muted-faint: oklch(0.19 0.03 250);
   --stgm-primary-muted: oklch(0.60 0.10 250);
   --stgm-destructive-muted: oklch(0.60 0.10 22);
-  --stgm-muted-foreground-faint: oklch(0.48 0.03 250);
+  --stgm-muted-foreground-faint: oklch(0.5 0.03 250);
   --stgm-backdrop: oklch(0.16 0.04 250 / 80%);
   --stgm-sidebar: oklch(0.13 0.05 250);
   --stgm-sidebar-foreground: oklch(0.93 0 0);

package/src/presets/fintech.css

@@ -45,7 +45,7 @@
   --stgm-muted-faint: oklch(0.975 0.003 280);
   --stgm-primary-muted: oklch(0.58 0.14 280);
   --stgm-destructive-muted: oklch(0.65 0.12 27);
-  --stgm-muted-foreground-faint: oklch(0.70 0.02 280);
+  --stgm-muted-foreground-faint: oklch(0.62 0.02 280);
   --stgm-backdrop: oklch(0.98 0.005 280 / 80%);
   --stgm-sidebar: oklch(0.12 0.06 280);
   --stgm-sidebar-foreground: oklch(0.90 0.01 280);
@@ -72,7 +72,7 @@
   --stgm-secondary: oklch(0.23 0.05 280);
   --stgm-secondary-foreground: oklch(0.92 0.01 280);
   --stgm-muted: oklch(0.23 0.05 280);
-  --stgm-muted-foreground: oklch(0.58 0.04 280);
+  --stgm-muted-foreground: oklch(0.65 0.04 280);
   --stgm-accent: oklch(0.28 0.06 280);
   --stgm-accent-foreground: oklch(0.92 0.01 280);
   --stgm-border: oklch(0.35 0.06 280);
@@ -99,14 +99,14 @@
   --stgm-muted-faint: oklch(0.15 0.04 280);
   --stgm-primary-muted: oklch(0.60 0.14 280);
   --stgm-destructive-muted: oklch(0.60 0.10 22);
-  --stgm-muted-foreground-faint: oklch(0.42 0.03 280);
+  --stgm-muted-foreground-faint: oklch(0.5 0.03 280);
   --stgm-backdrop: oklch(0.12 0.05 280 / 80%);
   --stgm-sidebar: oklch(0.08 0.06 280);
   --stgm-sidebar-foreground: oklch(0.88 0.01 280);
   --stgm-sidebar-primary: oklch(0.70 0.22 280);
   --stgm-sidebar-primary-foreground: oklch(0.10 0 0);
   --stgm-sidebar-muted: oklch(0.14 0.06 280);
-  --stgm-sidebar-muted-foreground: oklch(0.52 0.04 280);
+  --stgm-sidebar-muted-foreground: oklch(0.58 0.04 280);
   --stgm-sidebar-accent: oklch(0.16 0.07 280);
   --stgm-sidebar-accent-foreground: oklch(0.88 0.01 280);
   --stgm-sidebar-border: oklch(0.22 0.06 280);

package/src/presets/friendly.css

@@ -10,7 +10,7 @@
   --stgm-card-foreground: oklch(0.22 0.03 50);
   --stgm-popover: oklch(0.99 0.01 65);
   --stgm-popover-foreground: oklch(0.22 0.03 50);
-  --stgm-primary: oklch(0.62 0.20 40);
+  --stgm-primary: oklch(0.55 0.20 40);
   --stgm-primary-foreground: oklch(0.98 0 0);
   --stgm-secondary: oklch(0.94 0.02 65);
   --stgm-secondary-foreground: oklch(0.30 0.03 50);
@@ -21,7 +21,7 @@
   --stgm-border: oklch(0.88 0.02 65);
   --stgm-input: oklch(0.88 0.02 65);
   --stgm-input-bg: oklch(0.99 0.01 65);
-  --stgm-ring: oklch(0.62 0.15 40);
+  --stgm-ring: oklch(0.55 0.15 40);
   --stgm-chart-1: oklch(0.62 0.20 40);
   --stgm-chart-2: oklch(0.58 0.16 150);
   --stgm-chart-3: oklch(0.55 0.18 280);
@@ -32,7 +32,7 @@
   --stgm-shadow-lg: 0 10px 20px -3px rgb(0 0 0 / 0.08), 0 4px 8px -4px rgb(0 0 0 / 0.06);
   --stgm-transition-duration: 200ms;
   --stgm-transition-timing: cubic-bezier(0.4, 0, 0.2, 1);
-  --stgm-primary-hover: oklch(0.57 0.18 40);
+  --stgm-primary-hover: oklch(0.50 0.18 40);
   --stgm-primary-subtle: oklch(0.95 0.03 40);
   --stgm-destructive-subtle: oklch(0.95 0.03 27);
   --stgm-muted-subtle: oklch(0.95 0.02 65);
@@ -44,11 +44,11 @@
   --stgm-muted-faint: oklch(0.96 0.015 65);
   --stgm-primary-muted: oklch(0.68 0.12 40);
   --stgm-destructive-muted: oklch(0.65 0.12 27);
-  --stgm-muted-foreground-faint: oklch(0.70 0.02 50);
+  --stgm-muted-foreground-faint: oklch(0.62 0.02 50);
   --stgm-backdrop: oklch(0.97 0.015 65 / 80%);
   --stgm-sidebar: oklch(0.95 0.02 65);
   --stgm-sidebar-foreground: oklch(0.22 0.03 50);
-  --stgm-sidebar-primary: oklch(0.62 0.20 40);
+  --stgm-sidebar-primary: oklch(0.55 0.20 40);
   --stgm-sidebar-primary-foreground: oklch(0.98 0 0);
   --stgm-sidebar-muted: oklch(0.92 0.02 65);
   --stgm-sidebar-muted-foreground: oklch(0.50 0.03 50);
@@ -71,7 +71,7 @@
   --stgm-secondary: oklch(0.27 0.03 50);
   --stgm-secondary-foreground: oklch(0.93 0.01 65);
   --stgm-muted: oklch(0.27 0.03 50);
-  --stgm-muted-foreground: oklch(0.62 0.03 50);
+  --stgm-muted-foreground: oklch(0.67 0.03 50);
   --stgm-accent: oklch(0.33 0.04 50);
   --stgm-accent-foreground: oklch(0.93 0.01 65);
   --stgm-border: oklch(0.38 0.04 50);
@@ -89,7 +89,7 @@
   --stgm-primary-hover: oklch(0.66 0.16 40);
   --stgm-primary-subtle: oklch(0.26 0.04 40);
   --stgm-destructive-subtle: oklch(0.26 0.04 22);
-  --stgm-muted-subtle: oklch(0.22 0.02 50);
+  --stgm-muted-subtle: oklch(0.24 0.02 50);
   --stgm-muted-foreground-subtle: oklch(0.52 0.03 50);
   --stgm-accent-hover: oklch(0.26 0.03 50);
   --stgm-destructive-hover: oklch(0.64 0.16 22);
@@ -98,7 +98,7 @@
   --stgm-muted-faint: oklch(0.20 0.02 50);
   --stgm-primary-muted: oklch(0.62 0.10 40);
   --stgm-destructive-muted: oklch(0.60 0.10 22);
-  --stgm-muted-foreground-faint: oklch(0.45 0.02 50);
+  --stgm-muted-foreground-faint: oklch(0.52 0.02 50);
   --stgm-backdrop: oklch(0.18 0.03 50 / 80%);
   --stgm-sidebar: oklch(0.15 0.03 50);
   --stgm-sidebar-foreground: oklch(0.90 0.01 65);

package/src/presets/monochrome.css

@@ -46,7 +46,7 @@
   --stgm-muted-faint: oklch(0.98 0 0);
   --stgm-primary-muted: oklch(0.40 0 0);
   --stgm-destructive-muted: oklch(0.65 0.12 27.325);
-  --stgm-muted-foreground-faint: oklch(0.68 0 0);
+  --stgm-muted-foreground-faint: oklch(0.63 0 0);
   --stgm-backdrop: oklch(0.99 0 0 / 80%);
   --stgm-sidebar: oklch(0.97 0 0);
   --stgm-sidebar-foreground: oklch(0.15 0 0);
@@ -91,7 +91,7 @@
   --stgm-primary-hover: oklch(0.88 0 0);
   --stgm-primary-subtle: oklch(0.21 0 0);
   --stgm-destructive-subtle: oklch(0.21 0.03 25);
-  --stgm-muted-subtle: oklch(0.18 0 0);
+  --stgm-muted-subtle: oklch(0.20 0 0);
   --stgm-muted-foreground-subtle: oklch(0.55 0 0);
   --stgm-accent-hover: oklch(0.22 0 0);
   --stgm-destructive-hover: oklch(0.64 0.17 22);
@@ -100,14 +100,14 @@
   --stgm-muted-faint: oklch(0.17 0 0);
   --stgm-primary-muted: oklch(0.80 0 0);
   --stgm-destructive-muted: oklch(0.60 0.10 22);
-  --stgm-muted-foreground-faint: oklch(0.45 0 0);
+  --stgm-muted-foreground-faint: oklch(0.5 0 0);
   --stgm-backdrop: oklch(0.145 0 0 / 80%);
   --stgm-sidebar: oklch(0.11 0 0);
   --stgm-sidebar-foreground: oklch(0.96 0 0);
   --stgm-sidebar-primary: oklch(0.96 0 0);
   --stgm-sidebar-primary-foreground: oklch(0.145 0 0);
   --stgm-sidebar-muted: oklch(0.18 0 0);
-  --stgm-sidebar-muted-foreground: oklch(0.55 0 0);
+  --stgm-sidebar-muted-foreground: oklch(0.6 0 0);
   --stgm-sidebar-accent: oklch(0.20 0 0);
   --stgm-sidebar-accent-foreground: oklch(0.96 0 0);
   --stgm-sidebar-border: oklch(0.24 0 0);

package/src/presets/startup.css

@@ -43,7 +43,7 @@
   --stgm-muted-faint: oklch(0.98 0 0);
   --stgm-primary-muted: oklch(0.58 0.14 285);
   --stgm-destructive-muted: oklch(0.65 0.12 27);
-  --stgm-muted-foreground-faint: oklch(0.72 0 0);
+  --stgm-muted-foreground-faint: oklch(0.62 0 0);
   --stgm-backdrop: oklch(0.99 0 0 / 80%);
   --stgm-sidebar: oklch(0.97 0 0);
   --stgm-sidebar-foreground: oklch(0.13 0 0);
@@ -70,7 +70,7 @@
   --stgm-secondary: oklch(0.16 0 0);
   --stgm-secondary-foreground: oklch(0.85 0 0);
   --stgm-muted: oklch(0.16 0 0);
-  --stgm-muted-foreground: oklch(0.55 0 0);
+  --stgm-muted-foreground: oklch(0.62 0 0);
   --stgm-accent: oklch(0.20 0 0);
   --stgm-accent-foreground: oklch(0.90 0 0);
   --stgm-border: oklch(0.22 0 0);
@@ -88,8 +88,8 @@
   --stgm-primary-hover: oklch(0.66 0.18 285);
   --stgm-primary-subtle: oklch(0.16 0.04 285);
   --stgm-destructive-subtle: oklch(0.16 0.04 22);
-  --stgm-muted-subtle: oklch(0.12 0 0);
-  --stgm-muted-foreground-subtle: oklch(0.45 0 0);
+  --stgm-muted-subtle: oklch(0.15 0 0);
+  --stgm-muted-foreground-subtle: oklch(0.52 0 0);
   --stgm-accent-hover: oklch(0.15 0 0);
   --stgm-destructive-hover: oklch(0.64 0.17 22);
   --stgm-foreground-hover: oklch(0.82 0 0);
@@ -97,14 +97,14 @@
   --stgm-muted-faint: oklch(0.11 0 0);
   --stgm-primary-muted: oklch(0.62 0.12 285);
   --stgm-destructive-muted: oklch(0.60 0.10 22);
-  --stgm-muted-foreground-faint: oklch(0.38 0 0);
+  --stgm-muted-foreground-faint: oklch(0.48 0 0);
   --stgm-backdrop: oklch(0.09 0 0 / 80%);
   --stgm-sidebar: oklch(0.07 0 0);
   --stgm-sidebar-foreground: oklch(0.85 0 0);
   --stgm-sidebar-primary: oklch(0.72 0.20 285);
   --stgm-sidebar-primary-foreground: oklch(0.10 0 0);
   --stgm-sidebar-muted: oklch(0.13 0 0);
-  --stgm-sidebar-muted-foreground: oklch(0.50 0 0);
+  --stgm-sidebar-muted-foreground: oklch(0.58 0 0);
   --stgm-sidebar-accent: oklch(0.14 0 0);
   --stgm-sidebar-accent-foreground: oklch(0.85 0 0);
   --stgm-sidebar-border: oklch(0.18 0 0);

package/src/tokens.css

@@ -1,116 +1,257 @@
+/* The --stgm-* design token contract for all Stigmer UI components.
+   This file is the single source of truth: the token reference docs are
+   generated from it (group headers and per-token comments below are parsed
+   by site/scripts/generate-theme-docs), and the contrast contract in
+   src/contract/ gates every value against WCAG thresholds in CI.
+
+   Light values live on :root; dark values in the block below. Descriptions
+   are written once, on the light declarations — a dark declaration changes
+   the value, never the meaning. */
+
 :root {
+  /* @group Typography */
+  /* UI text font stack. Hosts override by defining the fallback variable or the token itself. */
   --stgm-font-sans: var(--font-geist-sans, system-ui, sans-serif);
+  /* Code and tabular-figure font stack. */
   --stgm-font-mono: var(--font-geist-mono, ui-monospace, monospace);
+
+  /* @group Shape */
+  /* Base corner radius. The Tailwind radius scale (sm/md/lg/xl) is derived from this single token, so one override reshapes every component. */
   --stgm-radius: 0.625rem;
+
+  /* @group Core surfaces & text */
+  /* Page background behind all Stigmer content. */
   --stgm-background: oklch(0.98 0 0);
+  /* Primary body text on the page background. */
   --stgm-foreground: oklch(0.145 0 0);
+  /* Card fill (approval cards, plan cards, panels). */
   --stgm-card: oklch(1 0 0);
+  /* Text on card surfaces. */
   --stgm-card-foreground: oklch(0.145 0 0);
+  /* Floating surface fill (dropdowns, dialogs, tooltips). */
   --stgm-popover: oklch(1 0 0);
+  /* Text on floating surfaces. */
   --stgm-popover-foreground: oklch(0.145 0 0);
-  --stgm-primary: oklch(0.55 0.12 190);
+  /* Brand action color (primary buttons, active states, links). */
+  --stgm-primary: oklch(0.52 0.12 190);
+  /* Text on primary-filled elements. */
   --stgm-primary-foreground: oklch(0.985 0 0);
+  /* Secondary button and low-emphasis control fill. */
   --stgm-secondary: oklch(0.94 0 0);
+  /* Text on secondary-filled elements. */
   --stgm-secondary-foreground: oklch(0.205 0 0);
+  /* Muted panel fill (code blocks, quiet notices). */
   --stgm-muted: oklch(0.94 0 0);
-  --stgm-muted-foreground: oklch(0.556 0 0);
+  /* Supporting text (captions, timestamps, the Thinking indicator). */
+  --stgm-muted-foreground: oklch(0.5 0 0);
+  /* Hover/selection fill for menu items and list rows. */
   --stgm-accent: oklch(0.94 0 0);
+  /* Text on accent-filled elements. */
   --stgm-accent-foreground: oklch(0.205 0 0);
-  --stgm-destructive: oklch(0.577 0.245 27.325);
+
+  /* @group Semantic colors */
+  /* Destructive action color (deny buttons, error text). */
+  --stgm-destructive: oklch(0.55 0.245 27.325);
+  /* Text on destructive-filled elements. */
   --stgm-destructive-foreground: oklch(0.985 0 0);
-  --stgm-success: oklch(0.55 0.15 150);
+  /* Positive state color (success badges, confirmations). */
+  --stgm-success: oklch(0.5 0.15 150);
+  /* Text on success-filled elements. */
   --stgm-success-foreground: oklch(0.985 0 0);
+  /* Quiet success surface (subtle badges, inline confirmations). */
   --stgm-success-subtle: oklch(0.95 0.03 150);
+  /* Caution state color (warning badges). */
   --stgm-warning: oklch(0.75 0.18 80);
+  /* Text on warning-filled elements. */
   --stgm-warning-foreground: oklch(0.145 0 0);
+  /* Informational state color (info badges, hints). */
   --stgm-info: oklch(0.55 0.15 250);
+  /* Text on info-filled elements. */
   --stgm-info-foreground: oklch(0.985 0 0);
+
+  /* @group Forms & focus */
+  /* Default border for cards, dividers, and containers. */
   --stgm-border: oklch(0.885 0 0);
+  /* Input control border. */
   --stgm-input: oklch(0.87 0 0);
+  /* Input control fill. */
   --stgm-input-bg: oklch(1 0 0);
+  /* Focus ring color. */
   --stgm-ring: oklch(0.55 0.1 190);
+
+  /* @group Charts */
+  /* Categorical chart series 1. */
   --stgm-chart-1: oklch(0.646 0.222 41.116);
+  /* Categorical chart series 2. */
   --stgm-chart-2: oklch(0.6 0.118 184.704);
+  /* Categorical chart series 3. */
   --stgm-chart-3: oklch(0.398 0.07 227.392);
+  /* Categorical chart series 4. */
   --stgm-chart-4: oklch(0.828 0.189 84.429);
+  /* Categorical chart series 5. */
   --stgm-chart-5: oklch(0.769 0.188 70.08);
+  /* Named chart color for cross-view consistency (e.g. token usage). */
   --stgm-chart-purple: oklch(0.585 0.233 292);
+  /* Named chart color for cross-view consistency. */
   --stgm-chart-blue: oklch(0.546 0.245 262);
+  /* Named chart color for cross-view consistency. */
   --stgm-chart-green: oklch(0.577 0.174 149);
+  /* Named chart color for cross-view consistency. */
   --stgm-chart-orange: oklch(0.702 0.209 41);
+  /* Named chart color for cross-view consistency. */
   --stgm-chart-yellow: oklch(0.795 0.184 86);
+
+  /* @group Emphasis & elevation */
+  /* Stronger border for emphasized containers and separators. */
   --stgm-border-prominent: oklch(0.75 0 0);
+  /* Small elevation shadow (inputs, buttons). */
   --stgm-shadow-sm: 0 1px 3px 0 rgb(0 0 0 / 0.1), 0 1px 2px -1px rgb(0 0 0 / 0.1);
+  /* Medium elevation shadow (cards, panels). */
   --stgm-shadow-md: 0 4px 6px -1px rgb(0 0 0 / 0.1), 0 2px 4px -2px rgb(0 0 0 / 0.1);
+  /* Large elevation shadow (dialogs, popovers). */
   --stgm-shadow-lg: 0 10px 15px -3px rgb(0 0 0 / 0.1), 0 4px 6px -4px rgb(0 0 0 / 0.1);
+
+  /* @group Motion & layering */
+  /* Base transition duration for interactive state changes. */
   --stgm-transition-duration: 150ms;
+  /* Base transition easing curve. */
   --stgm-transition-timing: cubic-bezier(0.4, 0, 0.2, 1);
+  /* Stacking order for portaled surfaces (dropdowns, dialogs). */
   --stgm-z-popover: 50;
-  --stgm-primary-hover: oklch(0.50 0.11 190);
+
+  /* @group State shades */
+  /* Primary fill on hover. */
+  --stgm-primary-hover: oklch(0.47 0.11 190);
+  /* Quiet primary-tinted surface (selected rows, active nav). */
   --stgm-primary-subtle: oklch(0.95 0.02 190);
+  /* Quiet destructive surface (error notices, danger zones). */
   --stgm-destructive-subtle: oklch(0.95 0.03 27);
+  /* Subtlest distinct fill on the page background (user message bubble). Kept borderless-legible: the contrast contract enforces its separation from --stgm-background. */
   --stgm-muted-subtle: oklch(0.96 0 0);
+  /* De-emphasized supporting text, one step quieter than muted-foreground. */
   --stgm-muted-foreground-subtle: oklch(0.64 0 0);
+  /* Accent fill on hover. */
   --stgm-accent-hover: oklch(0.96 0 0);
+  /* Destructive fill on hover. */
   --stgm-destructive-hover: oklch(0.52 0.22 27.325);
+  /* Foreground-colored interactive text on hover. */
   --stgm-foreground-hover: oklch(0.20 0 0);
+  /* Quieter border for nested or low-emphasis containers. */
   --stgm-border-muted: oklch(0.92 0 0);
+  /* Faintest distinct fill (zebra stripes, ghost rows). */
   --stgm-muted-faint: oklch(0.975 0 0);
+  /* Desaturated primary for secondary indicators. */
   --stgm-primary-muted: oklch(0.62 0.08 190);
+  /* Desaturated destructive for secondary error indicators. */
   --stgm-destructive-muted: oklch(0.65 0.12 27.325);
-  --stgm-muted-foreground-faint: oklch(0.72 0 0);
+  /* Faintest readable text (placeholder-level hints). Held to a 3:1 floor by the contrast contract. */
+  --stgm-muted-foreground-faint: oklch(0.64 0 0);
+  /* Modal backdrop overlay behind dialogs. */
   --stgm-backdrop: oklch(0.98 0 0 / 80%);
+
+  /* @group Sidebar */
+  /* Sidebar background. Sidebar tokens form their own context: presets may give the sidebar a contrasting (e.g. dark-on-light) treatment. */
   --stgm-sidebar: oklch(0.97 0 0);
+  /* Primary text in the sidebar. */
   --stgm-sidebar-foreground: oklch(0.145 0 0);
-  --stgm-sidebar-primary: oklch(0.55 0.12 190);
+  /* Brand action color inside the sidebar. */
+  --stgm-sidebar-primary: oklch(0.52 0.12 190);
+  /* Text on sidebar-primary fills. */
   --stgm-sidebar-primary-foreground: oklch(0.985 0 0);
+  /* Muted panel fill inside the sidebar. */
   --stgm-sidebar-muted: oklch(0.94 0 0);
-  --stgm-sidebar-muted-foreground: oklch(0.556 0 0);
+  /* Supporting text in the sidebar (section headers). */
+  --stgm-sidebar-muted-foreground: oklch(0.5 0 0);
+  /* Hover/active item fill in the sidebar. */
   --stgm-sidebar-accent: oklch(0.94 0 0);
+  /* Text on sidebar accent fills. */
   --stgm-sidebar-accent-foreground: oklch(0.205 0 0);
+  /* Borders and dividers inside the sidebar. */
   --stgm-sidebar-border: oklch(0.885 0 0);
+  /* Focus ring inside the sidebar. */
   --stgm-sidebar-ring: oklch(0.55 0.1 190);
 
-  --stgm-status-ready: oklch(0.55 0.15 150);
+  /* @group Status */
+  /* Ready/healthy status accent (pill text, solid fills, dots). */
+  --stgm-status-ready: oklch(0.5 0.15 150);
+  /* Text on a solid ready fill. */
   --stgm-status-ready-foreground: oklch(0.985 0 0);
+  /* Quiet ready surface (status pill fill). */
   --stgm-status-ready-subtle: oklch(0.95 0.03 150);
-  --stgm-status-running: oklch(0.55 0.14 230);
+  /* Running/in-progress status accent. */
+  --stgm-status-running: oklch(0.5 0.14 230);
+  /* Text on a solid running fill. */
   --stgm-status-running-foreground: oklch(0.985 0 0);
+  /* Quiet running surface. */
   --stgm-status-running-subtle: oklch(0.95 0.03 230);
-  --stgm-status-pending: oklch(0.556 0 0);
+  /* Pending/queued status accent. */
+  --stgm-status-pending: oklch(0.5 0 0);
+  /* Text on a solid pending fill. */
   --stgm-status-pending-foreground: oklch(0.985 0 0);
+  /* Quiet pending surface. */
   --stgm-status-pending-subtle: oklch(0.95 0 0);
-  --stgm-status-degraded: oklch(0.72 0.17 80);
-  --stgm-status-degraded-foreground: oklch(0.145 0 0);
+  /* Degraded/at-risk status accent. */
+  --stgm-status-degraded: oklch(0.52 0.17 80);
+  /* Text on a solid degraded fill. */
+  --stgm-status-degraded-foreground: oklch(0.985 0 0);
+  /* Quiet degraded surface. */
   --stgm-status-degraded-subtle: oklch(0.95 0.03 80);
-  --stgm-status-failed: oklch(0.577 0.245 27.325);
+  /* Failed/error status accent. */
+  --stgm-status-failed: oklch(0.55 0.245 27.325);
+  /* Text on a solid failed fill. */
   --stgm-status-failed-foreground: oklch(0.985 0 0);
+  /* Quiet failed surface. */
   --stgm-status-failed-subtle: oklch(0.95 0.03 27);
-  --stgm-status-disabled: oklch(0.64 0 0);
+  /* Disabled/inactive status accent. */
+  --stgm-status-disabled: oklch(0.5 0 0);
+  /* Text on a solid disabled fill. */
   --stgm-status-disabled-foreground: oklch(0.985 0 0);
+  /* Quiet disabled surface. */
   --stgm-status-disabled-subtle: oklch(0.94 0 0);
-  --stgm-status-draft: oklch(0.556 0 0);
+  /* Draft/unpublished status accent. */
+  --stgm-status-draft: oklch(0.5 0 0);
+  /* Text on a solid draft fill. */
   --stgm-status-draft-foreground: oklch(0.985 0 0);
+  /* Quiet draft surface. */
   --stgm-status-draft-subtle: oklch(0.95 0 0);
 
+  /* @group Diff viewer */
+  /* Added-line background in diffs. */
   --stgm-diff-added-bg: oklch(0.96 0.04 150);
+  /* Added-line text in diffs. */
   --stgm-diff-added-fg: oklch(0.35 0.12 150);
+  /* Removed-line background in diffs. */
   --stgm-diff-removed-bg: oklch(0.96 0.04 27);
+  /* Removed-line text in diffs. */
   --stgm-diff-removed-fg: oklch(0.40 0.16 27);
+  /* Hunk header background in diffs. */
   --stgm-diff-hunk-header-bg: oklch(0.96 0.02 250);
+  /* Hunk header text in diffs. */
   --stgm-diff-hunk-header-fg: oklch(0.45 0.08 250);
 
+  /* @group Syntax highlighting */
+  /* Keywords in highlighted code. */
   --stgm-syntax-keyword: oklch(0.45 0.15 280);
+  /* Properties, attributes, and titles in highlighted code. */
   --stgm-syntax-property: oklch(0.40 0.14 250);
+  /* String literals in highlighted code. */
   --stgm-syntax-string: oklch(0.42 0.12 150);
+  /* Numeric literals in highlighted code. */
   --stgm-syntax-number: oklch(0.50 0.16 50);
+  /* Booleans and literals in highlighted code. */
   --stgm-syntax-bool: oklch(0.45 0.15 280);
+  /* Comments in highlighted code. */
   --stgm-syntax-comment: oklch(0.55 0 0);
+  /* Atoms and symbols in highlighted code. */
   --stgm-syntax-atom: oklch(0.50 0.10 25);
+  /* Meta and preprocessor tokens in highlighted code. */
   --stgm-syntax-meta: oklch(0.50 0.12 320);
+  /* Tags in highlighted markup. */
   --stgm-syntax-tag: oklch(0.45 0.15 20);
 }
 
+/* Dark values for the same contract. Tokens omitted here inherit their
+   light value (fonts, radius, motion, z-index). */
 [data-stgm-color-mode="dark"] {
   --stgm-background: oklch(0.145 0 0);
   --stgm-foreground: oklch(0.985 0 0);
@@ -123,18 +264,20 @@
   --stgm-secondary: oklch(0.269 0 0);
   --stgm-secondary-foreground: oklch(0.985 0 0);
   --stgm-muted: oklch(0.269 0 0);
-  --stgm-muted-foreground: oklch(0.708 0 0);
+  --stgm-muted-foreground: oklch(0.75 0 0);
   --stgm-accent: oklch(0.371 0 0);
   --stgm-accent-foreground: oklch(0.985 0 0);
+  /* Dark fills are lightened, so their foregrounds flip to near-black
+     (matching --stgm-primary-foreground) to preserve AA contrast. */
   --stgm-destructive: oklch(0.704 0.191 22.216);
-  --stgm-destructive-foreground: oklch(0.985 0 0);
+  --stgm-destructive-foreground: oklch(0.145 0 0);
   --stgm-success: oklch(0.7 0.15 150);
-  --stgm-success-foreground: oklch(0.985 0 0);
+  --stgm-success-foreground: oklch(0.145 0 0);
   --stgm-success-subtle: oklch(0.24 0.04 150);
   --stgm-warning: oklch(0.78 0.16 80);
   --stgm-warning-foreground: oklch(0.145 0 0);
   --stgm-info: oklch(0.7 0.15 250);
-  --stgm-info-foreground: oklch(0.985 0 0);
+  --stgm-info-foreground: oklch(0.145 0 0);
   --stgm-border: oklch(1 0 0 / 14%);
   --stgm-input: oklch(1 0 0 / 20%);
   --stgm-input-bg: oklch(0.205 0 0);
@@ -156,7 +299,7 @@
   --stgm-primary-hover: oklch(0.66 0.11 190);
   --stgm-primary-subtle: oklch(0.24 0.03 190);
   --stgm-destructive-subtle: oklch(0.24 0.04 22);
-  --stgm-muted-subtle: oklch(0.21 0 0);
+  --stgm-muted-subtle: oklch(0.24 0 0);
   --stgm-muted-foreground-subtle: oklch(0.60 0 0);
   --stgm-accent-hover: oklch(0.30 0 0);
   --stgm-destructive-hover: oklch(0.64 0.17 22.216);
@@ -179,25 +322,25 @@
   --stgm-sidebar-ring: oklch(0.5 0.08 190);
 
   --stgm-status-ready: oklch(0.7 0.15 150);
-  --stgm-status-ready-foreground: oklch(0.985 0 0);
+  --stgm-status-ready-foreground: oklch(0.145 0 0);
   --stgm-status-ready-subtle: oklch(0.24 0.04 150);
   --stgm-status-running: oklch(0.7 0.14 230);
-  --stgm-status-running-foreground: oklch(0.985 0 0);
+  --stgm-status-running-foreground: oklch(0.145 0 0);
   --stgm-status-running-subtle: oklch(0.24 0.04 230);
   --stgm-status-pending: oklch(0.708 0 0);
-  --stgm-status-pending-foreground: oklch(0.985 0 0);
+  --stgm-status-pending-foreground: oklch(0.145 0 0);
   --stgm-status-pending-subtle: oklch(0.24 0 0);
   --stgm-status-degraded: oklch(0.78 0.16 80);
   --stgm-status-degraded-foreground: oklch(0.145 0 0);
   --stgm-status-degraded-subtle: oklch(0.24 0.04 80);
   --stgm-status-failed: oklch(0.704 0.191 22.216);
-  --stgm-status-failed-foreground: oklch(0.985 0 0);
+  --stgm-status-failed-foreground: oklch(0.145 0 0);
   --stgm-status-failed-subtle: oklch(0.24 0.04 22);
-  --stgm-status-disabled: oklch(0.55 0 0);
-  --stgm-status-disabled-foreground: oklch(0.985 0 0);
+  --stgm-status-disabled: oklch(0.62 0 0);
+  --stgm-status-disabled-foreground: oklch(0.145 0 0);
   --stgm-status-disabled-subtle: oklch(0.21 0 0);
   --stgm-status-draft: oklch(0.708 0 0);
-  --stgm-status-draft-foreground: oklch(0.985 0 0);
+  --stgm-status-draft-foreground: oklch(0.145 0 0);
   --stgm-status-draft-subtle: oklch(0.24 0 0);
 
   --stgm-diff-added-bg: oklch(0.22 0.04 150);