@stigmer/theme 3.1.4 → 3.1.5

package/README.md

@@ -22,79 +22,34 @@ This defines CSS custom properties on `:root` (light) and `[data-stgm-color-mode
 
 ### Token Reference
 
-#### Layout
-
-| Token | Purpose |
-|-------|---------|
-| `--stgm-radius` | Base border radius |
-
-#### Colors (Core)
-
-| Token | Purpose |
-|-------|---------|
-| `--stgm-background` | Page / app background |
-| `--stgm-foreground` | Default text color |
-| `--stgm-primary` | Primary brand / action color |
-| `--stgm-primary-foreground` | Text on primary |
-| `--stgm-secondary` | Secondary surfaces |
-| `--stgm-secondary-foreground` | Text on secondary |
-| `--stgm-muted` | Muted / disabled surfaces |
-| `--stgm-muted-foreground` | Text on muted |
-| `--stgm-accent` | Accent highlights |
-| `--stgm-accent-foreground` | Text on accent |
-
-#### Colors (Semantic)
-
-| Token | Purpose |
-|-------|---------|
-| `--stgm-destructive` | Destructive / error actions |
-| `--stgm-destructive-foreground` | Text on destructive |
-| `--stgm-success` | Success states |
-| `--stgm-success-foreground` | Text on success |
-| `--stgm-warning` | Warning states |
-| `--stgm-warning-foreground` | Text on warning |
-| `--stgm-info` | Informational states |
-| `--stgm-info-foreground` | Text on info |
-
-#### Colors (Surfaces)
-
-| Token | Purpose |
-|-------|---------|
-| `--stgm-card` | Card background |
-| `--stgm-card-foreground` | Card text |
-| `--stgm-popover` | Popover / dropdown background |
-| `--stgm-popover-foreground` | Popover text |
-
-#### Colors (Form)
-
-| Token | Purpose |
-|-------|---------|
-| `--stgm-border` | Default border color |
-| `--stgm-input` | Input border color |
-| `--stgm-ring` | Focus ring color |
-
-#### Colors (Chart)
-
-| Token | Purpose |
-|-------|---------|
-| `--stgm-chart-1` through `--stgm-chart-5` | Data visualization palette |
-
-#### Colors (Sidebar)
-
-| Token | Purpose |
-|-------|---------|
-| `--stgm-sidebar` | Sidebar background |
-| `--stgm-sidebar-foreground` | Sidebar text |
-| `--stgm-sidebar-primary` | Sidebar active item |
-| `--stgm-sidebar-primary-foreground` | Text on sidebar active |
-| `--stgm-sidebar-accent` | Sidebar hover / accent |
-| `--stgm-sidebar-accent-foreground` | Text on sidebar accent |
-| `--stgm-sidebar-border` | Sidebar border |
-| `--stgm-sidebar-ring` | Sidebar focus ring |
+The complete token contract — every token with its purpose, light/dark
+defaults, and swatches — is documented at
+[stigmer.ai/docs/sdk/theme/tokens](https://stigmer.ai/docs/sdk/theme/tokens).
+That reference is generated directly from `src/tokens.css`, so it can never
+drift from the shipped values. The token groups:
+
+- **Typography** — `--stgm-font-sans`, `--stgm-font-mono`
+- **Shape** — `--stgm-radius` (the whole radius scale derives from it)
+- **Core surfaces & text** — background/foreground, card, popover, primary, secondary, muted, accent (each with its `-foreground` pair)
+- **Semantic colors** — destructive, success, warning, info
+- **Forms & focus** — border, input, input-bg, ring
+- **Charts** — 5 categorical series + named chart colors
+- **Emphasis & elevation** — prominent borders, shadow scale
+- **Motion & layering** — transition duration/easing, popover z-index
+- **State shades** — hover/subtle/muted/faint variants of the core colors
+- **Sidebar** — a self-contained token context for contrasting sidebars
+- **Status** — ready/running/pending/degraded/failed/disabled/draft, each with `-foreground` and `-subtle`
+- **Diff viewer** and **Syntax highlighting** token sets
+
+Default token values are contrast-audited in CI: `src/contract/` measures
+every declared text/surface pairing (WCAG 2.1 AA for text, a documented
+lightness-delta floor for borderless surfaces) across all presets and both
+color modes. Run `npx tsx scripts/contrast-report.ts` in this package to see
+the full matrix.
 
 ## Design Language Presets
 
-Stigmer ships with 5 design language presets. Each represents a real-world product category's visual DNA — not just a color swap, but a complete design language with different border radius, surface treatments, border styles, sidebar appearance, and color palette.
+Stigmer ships with 6 design language presets. Each represents a real-world product category's visual DNA — not just a color swap, but a complete design language with different border radius, surface treatments, border styles, sidebar appearance, and color palette.
 
 | Preset | Archetype | Import | CSS Class |
 |--------|-----------|--------|-----------|
@@ -103,8 +58,9 @@ Stigmer ships with 5 design language presets. Each represents a real-world produ
 | Startup | Dev tools (Linear, Vercel) | `@stigmer/theme/presets/startup.css` | `stgm-theme-startup` |
 | Friendly | Consumer SaaS (Notion, Intercom) | `@stigmer/theme/presets/friendly.css` | `stgm-theme-friendly` |
 | Fintech | Premium financial (Stripe, Mercury) | `@stigmer/theme/presets/fintech.css` | `stgm-theme-fintech` |
+| Monochrome | Editorial black-and-white (Linear, Notion) | `@stigmer/theme/presets/monochrome.css` | `stgm-theme-monochrome` |
 
-Each preset overrides the full token surface — radius, all surface colors, borders, sidebar, and accent palette — for both light and dark modes.
+Each preset overrides most of the token surface — radius, surface colors, borders, sidebar, and accent palette — for both light and dark modes, and falls through to the defaults for anything it leaves alone (Monochrome deliberately keeps the semantic status colors). The full per-preset override tables are at [stigmer.ai/docs/sdk/theme/presets](https://stigmer.ai/docs/sdk/theme/presets).
 
 ### Using a Preset
 
@@ -172,9 +128,9 @@ Apply via `className` on `StigmerProvider`:
 
 ### What a Full Preset Overrides
 
-A complete design language preset overrides the entire token surface:
+A complete design language preset overrides most of the token surface:
 
-- **Shape**: `--stgm-radius` (sharp `0.25rem` to very rounded `0.875rem`)
+- **Shape**: `--stgm-radius` (sharp `0.125rem` in Fintech to very rounded `1.25rem` in Friendly)
 - **Surfaces**: `--stgm-background`, `--stgm-card`, `--stgm-popover`, `--stgm-muted`, `--stgm-secondary`, `--stgm-accent`
 - **Text**: `--stgm-foreground`, `--stgm-card-foreground`, `--stgm-muted-foreground`, etc.
 - **Accent**: `--stgm-primary` / `--stgm-primary-foreground`, `--stgm-ring`
@@ -184,6 +140,11 @@ A complete design language preset overrides the entire token surface:
 
 You can also create minimal presets that override only a subset of tokens.
 
+If your preset defines a token in its light block, define its dark value
+too: preset-light declarations outrank the default dark block in the
+cascade, so a light-only override would leak into dark mode. The theme
+package's contract tests flag this automatically for built-in presets.
+
 ### Color Format
 
 All built-in tokens use [OKLCH](https://developer.mozilla.org/en-US/docs/Web/CSS/color_value/oklch) for perceptually uniform color manipulation. You can use any CSS color format in your overrides.
@@ -211,6 +172,7 @@ import { cn } from "@stigmer/theme";
 | `@stigmer/theme/presets/startup.css` | Startup (Modern dev tools) design language |
 | `@stigmer/theme/presets/friendly.css` | Friendly (Consumer SaaS) design language |
 | `@stigmer/theme/presets/fintech.css` | Fintech (Premium financial) design language |
+| `@stigmer/theme/presets/monochrome.css` | Monochrome (Editorial black-and-white) design language |
 
 ## License
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@stigmer/theme",
-  "version": "3.1.4",
+  "version": "3.1.5",
   "description": "Design tokens, CSS custom properties, and utility functions for Stigmer UI components",
   "license": "Apache-2.0",
   "type": "module",

package/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/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/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/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/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/contract/__tests__/color.test.ts

@@ -0,0 +1,59 @@
+import { describe, expect, it } from "vitest";
+import { compositeOver, contrastRatio, isColorValue, lightnessDelta, parseColor } from "../color.js";
+
+describe("contrastRatio", () => {
+  it("computes the canonical black-on-white ratio", () => {
+    expect(contrastRatio("black", "white")).toBeCloseTo(21, 5);
+    expect(contrastRatio("white", "white")).toBeCloseTo(1, 5);
+  });
+
+  it("parses OKLCH token values", () => {
+    // Dark-mode foreground on background from tokens.css — a high-contrast pair.
+    const ratio = contrastRatio("oklch(0.985 0 0)", "oklch(0.145 0 0)");
+    expect(ratio).toBeGreaterThan(15);
+  });
+
+  it("composites a translucent foreground over the background first", () => {
+    // 50% white over black is a grey; contrast must be far below solid white's.
+    const solid = contrastRatio("white", "black");
+    const translucent = contrastRatio("rgb(255 255 255 / 50%)", "black");
+    expect(translucent).toBeLessThan(solid);
+    expect(translucent).toBeGreaterThan(1);
+  });
+
+  it("requires a backdrop for a translucent background", () => {
+    expect(() => contrastRatio("white", "oklch(1 0 0 / 14%)")).toThrow(/backdropValue/);
+    const ratio = contrastRatio("white", "oklch(1 0 0 / 14%)", "oklch(0.145 0 0)");
+    expect(ratio).toBeGreaterThan(1);
+  });
+});
+
+describe("compositeOver", () => {
+  it("returns the foreground unchanged when opaque", () => {
+    const fg = parseColor("rgb(10 20 30)");
+    expect(compositeOver(fg, parseColor("white"))).toBe(fg);
+  });
+
+  it("blends channels linearly by alpha in sRGB", () => {
+    const result = compositeOver(parseColor("rgb(255 255 255 / 50%)"), parseColor("black"));
+    expect(result.r).toBeCloseTo(0.5, 5);
+    expect(result.g).toBeCloseTo(0.5, 5);
+    expect(result.b).toBeCloseTo(0.5, 5);
+    expect(result.alpha).toBe(1);
+  });
+});
+
+describe("lightnessDelta", () => {
+  it("measures OKLCH lightness separation", () => {
+    expect(lightnessDelta("oklch(0.21 0 0)", "oklch(0.145 0 0)")).toBeCloseTo(0.065, 3);
+    expect(lightnessDelta("white", "white")).toBeCloseTo(0, 5);
+  });
+});
+
+describe("isColorValue", () => {
+  it("distinguishes colors from other token values", () => {
+    expect(isColorValue("oklch(0.5 0.1 190)")).toBe(true);
+    expect(isColorValue("0.625rem")).toBe(false);
+    expect(isColorValue("var(--font-geist-sans, system-ui, sans-serif)")).toBe(false);
+  });
+});

package/src/contract/__tests__/contrast.test.ts

@@ -0,0 +1,81 @@
+import { describe, expect, it } from "vitest";
+import { runContrastAudit, resultId } from "../audit.js";
+
+/**
+ * The permanent contrast gate for the token contract (stigmer/stigmer#187).
+ *
+ * Every pair declared in `pairs.ts` must meet its threshold in every preset
+ * × color mode, resolved through the real cascade. A regression here means
+ * shipped chrome text or surfaces became unreadable in someone's theme.
+ *
+ * EXEMPTIONS is the explicit, reviewed list of accepted misses. Adding to
+ * it is a design decision, not a fix — every entry needs a rationale, and
+ * the exemption is pinned to a measured floor so an exempted pair can still
+ * never silently get *worse*.
+ */
+
+interface Exemption {
+  /** `resultId()` of the accepted miss. */
+  readonly id: string;
+  /** Why this miss is acceptable. */
+  readonly rationale: string;
+  /** The measured value at the time of exemption; regressions below fail. */
+  readonly measuredFloor: number;
+}
+
+const EXEMPTIONS: readonly Exemption[] = [];
+
+const exemptionById = new Map(EXEMPTIONS.map((e) => [e.id, e]));
+
+describe("token contract contrast audit", () => {
+  const { results, leaks } = runContrastAudit();
+
+  it("declared pairs resolve for every preset and mode", () => {
+    // 6 presets × 2 modes × (text+supporting+surface pairs); exact count is
+    // asserted loosely so adding a pair does not require touching this test.
+    expect(results.length).toBeGreaterThan(400);
+  });
+
+  it("no preset leaks a light-only token value into dark mode", () => {
+    const formatted = leaks.map(
+      (leak) => `${leak.preset}: ${leak.tokens.join(", ")}`,
+    );
+    expect(formatted, "preset tokens defined light-only override the default dark value (see resolve.ts)").toEqual([]);
+  });
+
+  const failures = results.filter(
+    (r) => r.enforced && !r.passes && !exemptionById.has(resultId(r)),
+  );
+
+  it("every non-exempt pair meets its threshold", () => {
+    const formatted = failures.map(
+      (r) =>
+        `${resultId(r)} — ${r.pair.kind} ${r.measured.toFixed(2)} < ${r.threshold} ` +
+        `(fg ${r.foregroundValue} on bg ${r.backgroundValue}; used by: ${r.pair.usage})`,
+    );
+    expect(formatted).toEqual([]);
+  });
+
+  it("exempted pairs never regress below their recorded floor", () => {
+    const regressions: string[] = [];
+    const staleExemptions: string[] = [];
+    for (const exemption of EXEMPTIONS) {
+      const result = results.find((r) => resultId(r) === exemption.id);
+      if (!result) {
+        staleExemptions.push(exemption.id);
+        continue;
+      }
+      if (result.passes) {
+        // The pair now meets the real threshold — the exemption must be
+        // removed so the full gate applies again.
+        staleExemptions.push(exemption.id);
+      } else if (result.measured < exemption.measuredFloor - 1e-6) {
+        regressions.push(
+          `${exemption.id}: ${result.measured.toFixed(3)} fell below exempted floor ${exemption.measuredFloor}`,
+        );
+      }
+    }
+    expect(regressions).toEqual([]);
+    expect(staleExemptions, "exemption no longer needed or references a removed pair — delete it").toEqual([]);
+  });
+});

package/src/contract/__tests__/parse.test.ts

@@ -0,0 +1,106 @@
+import { describe, expect, it } from "vitest";
+import { parseThemeCss } from "../parse.js";
+
+describe("parseThemeCss", () => {
+  it("splits :root and dark-attribute blocks into light and dark maps", () => {
+    const css = `
+:root {
+  --stgm-background: oklch(0.98 0 0);
+  --stgm-foreground: oklch(0.145 0 0);
+}
+
+[data-stgm-color-mode="dark"] {
+  --stgm-background: oklch(0.145 0 0);
+}
+`;
+    const { light, dark } = parseThemeCss(css);
+    expect(light.get("--stgm-background")?.value).toBe("oklch(0.98 0 0)");
+    expect(light.get("--stgm-foreground")?.value).toBe("oklch(0.145 0 0)");
+    expect(dark.get("--stgm-background")?.value).toBe("oklch(0.145 0 0)");
+    expect(dark.has("--stgm-foreground")).toBe(false);
+  });
+
+  it("classifies the preset dual dark selector spanning multiple lines", () => {
+    const css = `
+.stgm-theme-x {
+  --stgm-primary: oklch(0.5 0.2 250);
+}
+
+[data-stgm-color-mode="dark"] .stgm-theme-x,
+.stgm-theme-x[data-stgm-color-mode="dark"] {
+  --stgm-primary: oklch(0.7 0.2 250);
+}
+`;
+    const { light, dark } = parseThemeCss(css);
+    expect(light.get("--stgm-primary")?.value).toBe("oklch(0.5 0.2 250)");
+    expect(dark.get("--stgm-primary")?.value).toBe("oklch(0.7 0.2 250)");
+  });
+
+  it("keeps values containing semicolons-free complex expressions intact", () => {
+    const css = `
+:root {
+  --stgm-shadow-sm: 0 1px 3px 0 rgb(0 0 0 / 0.1), 0 1px 2px -1px rgb(0 0 0 / 0.1);
+  --stgm-font-sans: var(--font-geist-sans, system-ui, sans-serif);
+  --stgm-backdrop: oklch(0.98 0 0 / 80%);
+}
+`;
+    const { light } = parseThemeCss(css);
+    expect(light.get("--stgm-shadow-sm")?.value).toBe(
+      "0 1px 3px 0 rgb(0 0 0 / 0.1), 0 1px 2px -1px rgb(0 0 0 / 0.1)",
+    );
+    expect(light.get("--stgm-font-sans")?.value).toBe(
+      "var(--font-geist-sans, system-ui, sans-serif)",
+    );
+    expect(light.get("--stgm-backdrop")?.value).toBe("oklch(0.98 0 0 / 80%)");
+  });
+
+  it("attaches @group headers and per-token descriptions", () => {
+    const css = `
+:root {
+  /* @group Core colors */
+  /* Page background behind all content. */
+  --stgm-background: oklch(0.98 0 0);
+  --stgm-foreground: oklch(0.145 0 0);
+
+  /* @group Shape */
+  --stgm-radius: 0.625rem;
+}
+`;
+    const { light } = parseThemeCss(css);
+    expect(light.get("--stgm-background")).toMatchObject({
+      group: "Core colors",
+      description: "Page background behind all content.",
+    });
+    // The description belongs only to the token directly beneath it.
+    expect(light.get("--stgm-foreground")).toMatchObject({ group: "Core colors" });
+    expect(light.get("--stgm-foreground")?.description).toBeUndefined();
+    expect(light.get("--stgm-radius")).toMatchObject({ group: "Shape" });
+  });
+
+  it("ignores multi-line file header comments", () => {
+    const css = `
+/* Corporate — Enterprise SaaS design language
+   Tight radius, corporate blue */
+
+.stgm-theme-corporate {
+  --stgm-radius: 0.375rem;
+}
+`;
+    const { light } = parseThemeCss(css);
+    expect(light.get("--stgm-radius")?.value).toBe("0.375rem");
+    expect(light.get("--stgm-radius")?.description).toBeUndefined();
+  });
+
+  it("ignores non-stgm declarations", () => {
+    const css = `
+:root {
+  --other-token: red;
+  color: blue;
+  --stgm-primary: oklch(0.5 0.1 190);
+}
+`;
+    const { light } = parseThemeCss(css);
+    expect(light.size).toBe(1);
+    expect(light.has("--stgm-primary")).toBe(true);
+  });
+});