From 2a74db448a3cbfcbc97cb43996e62c2e23023af8 Mon Sep 17 00:00:00 2001
From: Nathaniel Tucker <me@ntucker.me>
Date: Sun, 26 Jul 2026 17:52:10 -0400
Subject: [PATCH 1/2] Stage 5: Harden theming for product-grade multi-tenant
 branding.

Add OKLCH palette generation with paired light/dark derivation, public contrast auditing, portal variable channels that preserve component hooks across named nests, and docs TenantGallery/ThemePlayground exit demos.

Co-authored-by: Cursor <cursoragent@cursor.com>
---
 .changeset/stage-5-theming-core.md            |  10 +
 .changeset/stage-5-theming-web.md             |   9 +
 README.md                                     |   9 +-
 apps/docs/src/Theming.mdx                     |  94 ++++-
 apps/docs/src/theme/TenantGallery.stories.tsx |  28 ++
 apps/docs/src/theme/TenantGallery.test.tsx    |  59 +++
 apps/docs/src/theme/TenantGallery.tsx         |  81 ++++
 apps/docs/src/theme/Theme.demo.tsx            |  22 +-
 .../src/theme/ThemePlayground.stories.tsx     |  52 +++
 apps/docs/src/theme/ThemePlayground.test.tsx  |  26 ++
 apps/docs/src/theme/ThemePlayground.tsx       | 141 +++++++
 apps/docs/src/theme/tenants.ts                |  49 +++
 .../docs/src/theme/themingAcceptance.test.tsx | 110 +++++
 docs/API_POLICY.md                            |  11 +-
 docs/ARCHITECTURE.md                          |   8 +-
 docs/ROADMAP.md                               |  14 +-
 packages/silk-core/package.json               |   4 +
 packages/silk-core/src/index.ts               |  19 +-
 .../src/theme/checkThemeContrast.test.ts      |  75 ++++
 .../silk-core/src/theme/checkThemeContrast.ts | 380 ++++++++++++++++++
 packages/silk-core/src/theme/colorMath.ts     | 101 +++++
 packages/silk-core/src/theme/contrast.test.ts | 159 +-------
 packages/silk-core/src/theme/createTheme.ts   |  12 +-
 .../src/theme/generatePairedPalette.ts        | 130 ++++++
 .../src/theme/generateScale.matrix.test.ts    |  63 +++
 .../silk-core/src/theme/generateScale.test.ts |  65 +++
 packages/silk-core/src/theme/generateScale.ts | 169 ++++++++
 packages/silk-core/src/theme/index.ts         |  21 +
 packages/silk-core/src/theme/oklchUtil.ts     |  68 ++++
 packages/silk/src/components/Dialog.test.tsx  |  23 ++
 packages/silk/src/index.ts                    |  12 +
 .../silk/src/theme/ThemeProvider.test.tsx     |   8 +-
 packages/silk/src/theme/ThemeProvider.tsx     |  50 ++-
 packages/silk/src/theme/ThemeScope.tsx        |  17 +-
 packages/silk/src/theme/componentVars.test.ts |   7 +
 packages/silk/src/theme/componentVars.ts      | 206 +++++++++-
 .../silk/src/theme/componentVarsDocs.test.ts  |  23 ++
 packages/silk/src/theme/index.ts              |  26 +-
 packages/silk/src/theme/partitionCssVars.ts   |  60 +++
 .../silk/src/theme/themingAcceptance.test.tsx |  43 +-
 yarn.lock                                     |  16 +
 41 files changed, 2250 insertions(+), 230 deletions(-)
 create mode 100644 .changeset/stage-5-theming-core.md
 create mode 100644 .changeset/stage-5-theming-web.md
 create mode 100644 apps/docs/src/theme/TenantGallery.stories.tsx
 create mode 100644 apps/docs/src/theme/TenantGallery.test.tsx
 create mode 100644 apps/docs/src/theme/TenantGallery.tsx
 create mode 100644 apps/docs/src/theme/ThemePlayground.stories.tsx
 create mode 100644 apps/docs/src/theme/ThemePlayground.test.tsx
 create mode 100644 apps/docs/src/theme/ThemePlayground.tsx
 create mode 100644 apps/docs/src/theme/tenants.ts
 create mode 100644 apps/docs/src/theme/themingAcceptance.test.tsx
 create mode 100644 packages/silk-core/src/theme/checkThemeContrast.test.ts
 create mode 100644 packages/silk-core/src/theme/checkThemeContrast.ts
 create mode 100644 packages/silk-core/src/theme/colorMath.ts
 create mode 100644 packages/silk-core/src/theme/generatePairedPalette.ts
 create mode 100644 packages/silk-core/src/theme/generateScale.matrix.test.ts
 create mode 100644 packages/silk-core/src/theme/generateScale.test.ts
 create mode 100644 packages/silk-core/src/theme/generateScale.ts
 create mode 100644 packages/silk-core/src/theme/oklchUtil.ts
 create mode 100644 packages/silk/src/theme/componentVarsDocs.test.ts
 create mode 100644 packages/silk/src/theme/partitionCssVars.ts

diff --git a/.changeset/stage-5-theming-core.md b/.changeset/stage-5-theming-core.md
new file mode 100644
index 0000000..012bd78
--- /dev/null
+++ b/.changeset/stage-5-theming-core.md
@@ -0,0 +1,10 @@
+---
+'@reactive/silk-core': minor
+---
+
+Stage 5 theming maturity (core): palette generation, paired dark derivation, and contrast auditing.
+
+- Add `generateScale(seedHex, colorScheme)` — OKLCH 12-step ramps from canonical sRGB hex.
+- Add `generatePairedPalette(brandHex)` — tenant recipe producing full light+dark palettes (accent + brand-tinted gray; optional danger/success seeds).
+- Add `checkThemeContrast`, `contrastRatio`, `relativeLuminance`, and `parseCanonicalHex` for CI/tooling.
+- Depends on `culori` for OKLCH conversion and gamut mapping (private to the generator).
diff --git a/.changeset/stage-5-theming-web.md b/.changeset/stage-5-theming-web.md
new file mode 100644
index 0000000..fb83b04
--- /dev/null
+++ b/.changeset/stage-5-theming-web.md
@@ -0,0 +1,9 @@
+---
+'@reactive/silk': minor
+---
+
+Stage 5 theming maturity (web): portal variable channels and re-exports.
+
+- Split theme-scope CSS vars into `semanticVars` (replaced by nested `theme`/`colorScheme`) and `customVars` (component hooks that inherit through named children into portals).
+- Re-export `generateScale`, `generatePairedPalette`, `checkThemeContrast`, and related types from `@reactive/silk`.
+- Document the frozen public component CSS-variable list via `silkComponentVarMeta` / `formatComponentVarDocsTable`.
diff --git a/README.md b/README.md
index d5aad4f..c9d90c9 100644
--- a/README.md
+++ b/README.md
@@ -17,7 +17,7 @@ yarn docs    # http://localhost:6006
 
 ## Status
 
-Stage 2 (visual primitives & forms): `Surface`, `Card`, `Heading`, `Badge`, status primitives, `Field`/`Input`/`Textarea`, Radix-backed form controls, token audit (`success`, elevation shadows, contrast), SettingsForm fixture, and [pre-1.0 API policy](docs/API_POLICY.md). Stage 1 layout vocabulary remains. The staged plan is in [docs/ROADMAP.md](docs/ROADMAP.md); the project charter is [docs/PRINCIPLES.md](docs/PRINCIPLES.md).
+Stage 5 (theming maturity): `generatePairedPalette` / `generateScale`, `checkThemeContrast`, nested portal variable channels, TenantGallery + ThemePlayground in docs, frozen public component CSS-var list. Prior stages shipped layout, visual/forms, interaction primitives, and composites. The staged plan is in [docs/ROADMAP.md](docs/ROADMAP.md); the project charter is [docs/PRINCIPLES.md](docs/PRINCIPLES.md).
 
 ## Packages
 
@@ -89,10 +89,13 @@ export function App() {
 }
 ```
 
-Custom / tenant themes use the style-attribute path:
+Custom / tenant themes use the style-attribute path. For brand seeds with paired light/dark:
 
 ```tsx
-<SilkProvider theme={createTheme({ semantic: { color: { surface: '#fafafa' } } })}>
+import { createTheme, generatePairedPalette } from '@reactive/silk';
+
+const paired = generatePairedPalette('#0ea5e9');
+<SilkProvider theme={createTheme({ colorScheme: 'light', palette: paired.light })}>
   …
 </SilkProvider>
 ```
diff --git a/apps/docs/src/Theming.mdx b/apps/docs/src/Theming.mdx
index 12f2845..95151cb 100644
--- a/apps/docs/src/Theming.mdx
+++ b/apps/docs/src/Theming.mdx
@@ -40,6 +40,37 @@ const theme = createTheme({
 
 Prefer **either** `theme` **or** `colorScheme`. If both are passed, `theme` wins for `data-theme` and inline variables.
 
+### Palette generation and dark derivation
+
+For multi-tenant branding, generate a full light+dark palette from one brand hex:
+
+```tsx
+import {
+  createTheme,
+  generatePairedPalette,
+  checkThemeContrast,
+} from '@reactive/silk';
+
+const paired = generatePairedPalette('#0ea5e9');
+const light = createTheme({ colorScheme: 'light', palette: paired.light });
+const dark = createTheme({ colorScheme: 'dark', palette: paired.dark });
+
+// CI / playground guard — hex-only semantic audit
+const { ok, violations } = checkThemeContrast(light);
+```
+
+Slot mapping for `generatePairedPalette(brand)`:
+
+| Palette scale | Source |
+| --- | --- |
+| `blue` (accent) | Brand chromatic OKLCH ramp |
+| `gray` (surfaces / neutral / text) | Low-chroma brand-hue ramp |
+| `red` / `green` | Built-in defaults, or `dangerSeedHex` / `successSeedHex` |
+
+`generateScale(seed, colorScheme)` is the lower-level primitive (12-step OKLCH ramp). Seed input is canonical sRGB hex (`#RGB` / `#RRGGBB`); invalid input throws. Algorithm curves may improve between minors; the hex contract and 12-step shape are stable.
+
+See **Theme/TenantGallery** (two tenants × light/dark side by side) and **Theme/ThemePlayground** (live controls + contrast readout).
+
 ## Typography and fonts
 
 Silk exposes three font-family tokens (inspired by Claude Cowork's sans / serif / mono roles) and maps typography roles onto them:
@@ -88,23 +119,66 @@ Defaults are a typed map — not a runtime component registry.
 
 ## Nesting and portals
 
-Nesting works via DOM CSS variable inheritance in normal flow.
-
-Portals (for example Dialog) still render under `document.body` by default, but Silk reconstitutes the **nearest** `ThemeProvider` / `SilkProvider` scope on the portaled tree: the same theme class, `data-theme` (when set), and custom `createTheme` CSS variables. Nested providers therefore theme their dialogs correctly without an explicit portal container.
+Nesting works via DOM CSS variable inheritance in normal flow, with two variable **channels**:
 
-For cases where you need the portal DOM to live inside a particular subtree (stacking, clipping, or measuring against that subtree), pass Dialog `container`. Nested theming itself does **not** require `container` — see **Components/Interaction/Dialog → NestedThemePortal**.
-
-## Component CSS variable hooks
-
-Public hooks like `--silk-button-bg` resolve through private vars:
+| Channel | Contents | Nested `theme` / `colorScheme` |
+| --- | --- | --- |
+| Semantic | `--silk-color-*`, radii, type, motion, shadows, focus geometry, space source scales | **Replaced** — named children do not carry outer tenant semantics into portals |
+| Custom | Component hooks (`--silk-button-bg`, …) and other `--silk-*` extensions | **Inherited** — portals under an inner named scheme still see outer hooks |
+
+Supported patterns:
+
+1. **Tenant → named** — outer `theme={tenant}`, inner `colorScheme="dark"`: inner (and its portals) use named dark semantics; outer component hooks still apply.
+2. **Named → tenant** — outer named scheme, inner custom theme: inner semantics win for that subtree and its portals.
+3. **Tenant → tenant** — inner custom theme fully replaces outer semantics; custom hooks merge.
+
+Portals (Dialog, Popover, Select, …) reconstitute the nearest scope: theme class, `data-theme`, semantic vars, and custom vars. Nested theming does **not** require Dialog `container` — pass `container` only when the portal DOM must live inside a particular subtree.
+
+Constant SSR `<style>` from behavior bindings (ScrollArea) is charter-permitted and is not a theme stylesheet.
+
+## Public component CSS variable hooks
+
+Component tokens stay sparse — an override surface, not a parallel token system. Every hook is consumed as `var(--silk-…, <semantic fallback>)` and never pre-declared on the component.
+
+{/* COMPONENT_VAR_TABLE_START */}
+| Variable | Component | Default resolution | Rationale |
+| --- | --- | --- | --- |
+| `--silk-avatar-size` | Avatar | mediaScale edge (px) | Runtime size when not using the size axis |
+| `--silk-badge-bg` | Badge | tone solid / subtle by variant | Brand fill override |
+| `--silk-badge-border` | Badge | tone border | Brand border override |
+| `--silk-badge-fg` | Badge | tone onSolid / text by variant | Brand foreground override |
+| `--silk-badge-radius` | Badge | radius.md / full by size | Corner radius escape hatch |
+| `--silk-button-bg` | Button | tone solid / subtle by variant | Brand fill override |
+| `--silk-button-border` | Button | tone border | Brand border override |
+| `--silk-button-fg` | Button | tone onSolid / text by variant | Brand foreground override |
+| `--silk-button-radius` | Button | radius.md | Corner radius escape hatch |
+| `--silk-card-bg` | Card | color.surfaceRaised | Surface fill override |
+| `--silk-card-border` | Card | color.borderSubtle | Border override |
+| `--silk-card-radius` | Card | radius.lg | Corner radius escape hatch |
+| `--silk-card-shadow` | Card | shadow.raised when elevated | Elevation ink override |
+| `--silk-empty-state-measure` | EmptyState | measure.prose | Readable measure for empty-state copy |
+| `--silk-grid-min` | Grid | minColumnWidth prop / recipe default | Runtime track minimum |
+| `--silk-input-bg` | Input/Textarea | color.surfaceSunken | Control fill override |
+| `--silk-input-border` | Input/Textarea | color.borderSubtle | Control border override |
+| `--silk-input-radius` | Input/Textarea | radius.md | Control radius escape hatch |
+| `--silk-scrollarea-thumb` | ScrollArea | color.borderSubtle | Scrollbar thumb ink |
+| `--silk-select-bg` | Select | color.surfaceSunken | Trigger fill override |
+| `--silk-select-border` | Select | color.borderSubtle | Trigger border override |
+| `--silk-select-radius` | Select | radius.md | Trigger radius escape hatch |
+| `--silk-status-dot-bg` | StatusDot | tone solid | Status ink override |
+| `--silk-surface-bg` | Surface | color.surface / surfaceRaised / surfaceSunken | Surface fill override |
+| `--silk-surface-border` | Surface | color.borderSubtle | Surface border override |
+| `--silk-surface-radius` | Surface | radius.md | Surface radius escape hatch |
+| `--silk-surface-shadow` | Surface | shadow.raised when elevated | Elevation ink override |
+{/* COMPONENT_VAR_TABLE_END */}
 
 ```css
 --_bg: var(--silk-button-bg, var(--_tone-solid));
 ```
 
-Do **not** pre-declare `--silk-button-bg: var(--silk-accent)` on the component — that shadows consumer overrides. See **Components/Visual/Button → StyledOverrides**.
+Do **not** pre-declare `--silk-button-bg: var(--silk-accent)` on the component — that shadows consumer overrides. See **Components/Visual/Button → StyledOverrides**. Removals, renames, and meaning changes are breaking per [API_POLICY](https://github.com/reactive/silk/blob/main/docs/API_POLICY.md).
 
 ## Further reading
 
-- Theme stories under **Theme**
+- Theme stories under **Theme** (TenantGallery, ThemePlayground, TokenAudit)
 - Architecture: [docs/ARCHITECTURE.md](https://github.com/reactive/silk/blob/main/docs/ARCHITECTURE.md)
diff --git a/apps/docs/src/theme/TenantGallery.stories.tsx b/apps/docs/src/theme/TenantGallery.stories.tsx
new file mode 100644
index 0000000..6f4bd49
--- /dev/null
+++ b/apps/docs/src/theme/TenantGallery.stories.tsx
@@ -0,0 +1,28 @@
+import type { Meta, StoryObj } from 'storybook-react-rsbuild';
+import type { JSX } from 'react';
+import { withSource } from '../docsSource';
+import { TenantGallery } from './TenantGallery';
+import tenantGallerySource from './TenantGallery.tsx?raw';
+import tenantsSource from './tenants.ts?raw';
+
+const meta = {
+  title: 'Theme/TenantGallery',
+  parameters: {
+    docs: {
+      description: {
+        component:
+          'Stage 5 exit: two visually distinct tenant themes (Ocean, Ember), each with paired light/dark from `generatePairedPalette`, rendered side by side with inline CSS variables only.',
+      },
+      ...withSource(tenantGallerySource, tenantsSource).docs,
+    },
+  },
+} satisfies Meta;
+
+export default meta;
+
+type Story = StoryObj<typeof meta>;
+
+export const SideBySide: Story = {
+  tags: ['test'],
+  render: (): JSX.Element => <TenantGallery />,
+};
diff --git a/apps/docs/src/theme/TenantGallery.test.tsx b/apps/docs/src/theme/TenantGallery.test.tsx
new file mode 100644
index 0000000..9b3d37b
--- /dev/null
+++ b/apps/docs/src/theme/TenantGallery.test.tsx
@@ -0,0 +1,59 @@
+import { expect, test } from '@rstest/core';
+import { render, within } from '@testing-library/react';
+import { TenantGallery } from './TenantGallery';
+import {
+  emberDark,
+  emberLight,
+  oceanDark,
+  oceanLight,
+  tenantThemes,
+} from './tenants';
+
+const panels = [
+  'Ocean / light',
+  'Ocean / dark',
+  'Ember / light',
+  'Ember / dark',
+] as const;
+
+test('TenantGallery mounts four side-by-side tenant panels', () => {
+  const { container } = render(<TenantGallery />);
+  const root = container.querySelector('[data-fixture="tenant-gallery"]');
+  expect(root).not.toBeNull();
+  expect(root?.getAttribute('data-fixture-state')).toBe('side-by-side');
+
+  for (const label of panels) {
+    const panel = container.querySelector(`[data-tenant-panel="${label}"]`);
+    expect(panel).not.toBeNull();
+    expect(
+      within(panel as HTMLElement).getByRole('button', { name: 'Accent' }),
+    ).toBeTruthy();
+  }
+});
+
+test('each tenant theme panel applies inline CSS variables (no stylesheet insert)', () => {
+  const styleCountBefore = document.querySelectorAll('style').length;
+  const { container } = render(<TenantGallery />);
+
+  for (const label of panels) {
+    const panel = container.querySelector(
+      `[data-tenant-panel="${label}"]`,
+    ) as HTMLElement;
+    const scope = panel.closest('[data-theme]') as HTMLElement | null;
+    expect(scope).not.toBeNull();
+    expect(scope!.style.getPropertyValue('--silk-color-surface')).not.toBe('');
+    expect(scope!.style.getPropertyValue('--silk-color-tone-accent-solid')).not.toBe(
+      '',
+    );
+  }
+
+  expect(document.querySelectorAll('style').length).toBe(styleCountBefore);
+});
+
+test('tenantThemes exports ocean and ember', () => {
+  expect(Object.keys(tenantThemes)).toEqual(['ocean', 'ember']);
+  expect(oceanLight.colorScheme).toBe('light');
+  expect(oceanDark.colorScheme).toBe('dark');
+  expect(emberLight.colorScheme).toBe('light');
+  expect(emberDark.colorScheme).toBe('dark');
+});
diff --git a/apps/docs/src/theme/TenantGallery.tsx b/apps/docs/src/theme/TenantGallery.tsx
new file mode 100644
index 0000000..442aa6f
--- /dev/null
+++ b/apps/docs/src/theme/TenantGallery.tsx
@@ -0,0 +1,81 @@
+import {
+  Badge,
+  Button,
+  Inline,
+  Input,
+  SilkProvider,
+  Stack,
+  Text,
+  type Theme,
+} from '@reactive/silk';
+import type { JSX } from 'react';
+import { SurfacePanel } from '../surfacePanel';
+import {
+  emberDark,
+  emberLight,
+  oceanDark,
+  oceanLight,
+} from './tenants';
+
+function GalleryPanel({
+  label,
+  theme,
+}: {
+  readonly label: string;
+  readonly theme: Theme;
+}): JSX.Element {
+  return (
+    <SilkProvider theme={theme}>
+      <SurfacePanel
+        gap="3"
+        data-tenant-panel={label}
+        style={{ minWidth: 0 }}
+      >
+        <Text role="headingSm">{label}</Text>
+        <Text tone="secondary">
+          Surfaces, text, and tones resolve from the tenant theme scope.
+        </Text>
+        <Inline gap="2" wrap="wrap">
+          <Button>Accent</Button>
+          <Button tone="neutral" variant="outline">
+            Neutral
+          </Button>
+          <Button tone="danger" variant="soft">
+            Danger
+          </Button>
+          <Button tone="success" variant="soft">
+            Success
+          </Button>
+        </Inline>
+        <Inline gap="2" wrap="wrap">
+          <Badge>Accent</Badge>
+          <Badge tone="danger">Danger</Badge>
+          <Badge tone="success">Success</Badge>
+        </Inline>
+        <Input aria-label={`${label} input`} placeholder="Tenant input" />
+      </SurfacePanel>
+    </SilkProvider>
+  );
+}
+
+/**
+ * Four-panel Stage 5 exit fixture: two tenants × light/dark, side by side,
+ * each under its own `SilkProvider theme=` (inline CSS variables only).
+ */
+export function TenantGallery(): JSX.Element {
+  return (
+    <Stack
+      gap="4"
+      data-fixture="tenant-gallery"
+      data-fixture-state="side-by-side"
+    >
+      <Text role="heading">Tenant themes side by side</Text>
+      <Inline gap="3" wrap="wrap" align="stretch">
+        <GalleryPanel label="Ocean / light" theme={oceanLight} />
+        <GalleryPanel label="Ocean / dark" theme={oceanDark} />
+        <GalleryPanel label="Ember / light" theme={emberLight} />
+        <GalleryPanel label="Ember / dark" theme={emberDark} />
+      </Inline>
+    </Stack>
+  );
+}
diff --git a/apps/docs/src/theme/Theme.demo.tsx b/apps/docs/src/theme/Theme.demo.tsx
index 54f55cb..a0bde07 100644
--- a/apps/docs/src/theme/Theme.demo.tsx
+++ b/apps/docs/src/theme/Theme.demo.tsx
@@ -1,24 +1,10 @@
-import {
-  Button,
-  Inline,
-  Text,
-  createTheme,
-} from '@reactive/silk';
+import { Button, Inline, Text } from '@reactive/silk';
 import type { JSX } from 'react';
 import { SurfacePanel } from '../surfacePanel';
+import { emberLight } from './tenants';
 
-export const tenantTheme = createTheme({
-  colorScheme: 'light',
-  semantic: {
-    color: {
-      surface: '#fff7ed',
-      surfaceRaised: '#ffedd5',
-      textPrimary: '#7c2d12',
-      textSecondary: '#9a3412',
-      borderSubtle: '#fdba74',
-    },
-  },
-});
+/** Warm tenant — same ember light theme as TenantGallery. */
+export const tenantTheme = emberLight;
 
 export const providerDefaults = {
   Button: { variant: 'soft', tone: 'neutral' },
diff --git a/apps/docs/src/theme/ThemePlayground.stories.tsx b/apps/docs/src/theme/ThemePlayground.stories.tsx
new file mode 100644
index 0000000..341d379
--- /dev/null
+++ b/apps/docs/src/theme/ThemePlayground.stories.tsx
@@ -0,0 +1,52 @@
+import type { Meta, StoryObj } from 'storybook-react-rsbuild';
+import type { JSX } from 'react';
+import { withSource } from '../docsSource';
+import { ThemePlayground } from './ThemePlayground';
+import playgroundSource from './ThemePlayground.tsx?raw';
+
+const meta = {
+  title: 'Theme/ThemePlayground',
+  component: ThemePlayground,
+  argTypes: {
+    brandSeed: { control: 'color' },
+    colorScheme: {
+      control: 'inline-radio',
+      options: ['light', 'dark'],
+    },
+    surface: { control: 'color' },
+    radiusMd: { control: { type: 'number', min: 0, max: 24, step: 1 } },
+  },
+  args: {
+    brandSeed: '#0ea5e9',
+    colorScheme: 'light',
+    radiusMd: 8,
+  },
+  parameters: {
+    docs: {
+      description: {
+        component:
+          'Live token editing against real components. Builds `createTheme` + `generatePairedPalette` from controls (debounced) and applies via inline CSS variables. Shows `checkThemeContrast` status.',
+      },
+      ...withSource(playgroundSource).docs,
+    },
+  },
+} satisfies Meta<typeof ThemePlayground>;
+
+export default meta;
+
+type Story = StoryObj<typeof meta>;
+
+export const Playground: Story = {
+  tags: ['test'],
+  render: (args): JSX.Element => <ThemePlayground {...args} />,
+  play: async ({ canvasElement }): Promise<void> => {
+    const root = canvasElement.querySelector('[data-fixture="theme-playground"]');
+    if (!root) {
+      throw new Error('Theme playground did not mount');
+    }
+    const contrast = root.querySelector('[data-contrast]');
+    if (!contrast) {
+      throw new Error('Contrast readout missing');
+    }
+  },
+};
diff --git a/apps/docs/src/theme/ThemePlayground.test.tsx b/apps/docs/src/theme/ThemePlayground.test.tsx
new file mode 100644
index 0000000..7cc413f
--- /dev/null
+++ b/apps/docs/src/theme/ThemePlayground.test.tsx
@@ -0,0 +1,26 @@
+import { expect, test } from '@rstest/core';
+import { act, render, screen } from '@testing-library/react';
+import { ThemePlayground } from './ThemePlayground';
+
+test('ThemePlayground mounts gallery and contrast readout', async () => {
+  render(<ThemePlayground brandSeed="#0ea5e9" colorScheme="dark" />);
+  const root = document.querySelector('[data-fixture="theme-playground"]');
+  expect(root).not.toBeNull();
+  expect(root?.getAttribute('data-scheme')).toBe('dark');
+  expect(screen.getByText(/Contrast: pass/)).toBeTruthy();
+  expect(screen.getByRole('button', { name: 'Accent' })).toBeTruthy();
+});
+
+test('invalid intermediate seed keeps last valid theme', async () => {
+  const { rerender } = render(
+    <ThemePlayground brandSeed="#0ea5e9" colorScheme="light" />,
+  );
+  expect(screen.getByText(/Contrast: pass/)).toBeTruthy();
+
+  rerender(<ThemePlayground brandSeed="#zz" colorScheme="light" />);
+  await act(async () => {
+    await new Promise((r) => setTimeout(r, 200));
+  });
+  expect(screen.getByText(/holding last valid theme/)).toBeTruthy();
+  expect(screen.getByText(/Contrast: pass/)).toBeTruthy();
+});
diff --git a/apps/docs/src/theme/ThemePlayground.tsx b/apps/docs/src/theme/ThemePlayground.tsx
new file mode 100644
index 0000000..0557864
--- /dev/null
+++ b/apps/docs/src/theme/ThemePlayground.tsx
@@ -0,0 +1,141 @@
+import {
+  Badge,
+  Button,
+  Inline,
+  Input,
+  SilkProvider,
+  Stack,
+  Text,
+  checkThemeContrast,
+  createTheme,
+  generatePairedPalette,
+  type PairedPalette,
+  type Theme,
+} from '@reactive/silk';
+import { parseCanonicalHex } from '@reactive/silk-core';
+import {
+  useEffect,
+  useMemo,
+  useRef,
+  useState,
+  type JSX,
+} from 'react';
+import { SurfacePanel } from '../surfacePanel';
+
+export interface ThemePlaygroundControls {
+  readonly brandSeed?: string;
+  readonly colorScheme?: 'light' | 'dark';
+  readonly surface?: string;
+  readonly radiusMd?: number;
+}
+
+const DEFAULT_BRAND = '#0ea5e9';
+const DEFAULT_SCHEME = 'light' as const;
+
+const pairedCache = new Map<string, PairedPalette>();
+
+function pairedFor(brandSeed: string): PairedPalette | null {
+  const seed = parseCanonicalHex(brandSeed);
+  if (!seed) {
+    return null;
+  }
+  const cached = pairedCache.get(seed);
+  if (cached) {
+    return cached;
+  }
+  const paired = generatePairedPalette(seed);
+  pairedCache.set(seed, paired);
+  return paired;
+}
+
+function buildTheme(
+  brandSeed: string,
+  colorScheme: 'light' | 'dark',
+  surface: string | undefined,
+  radiusMd: number | undefined,
+): Theme | null {
+  const paired = pairedFor(brandSeed);
+  if (!paired) {
+    return null;
+  }
+  const surfaceHex =
+    surface !== undefined ? parseCanonicalHex(surface) : undefined;
+  return createTheme({
+    colorScheme,
+    palette: paired[colorScheme],
+    semantic: {
+      ...(surfaceHex ? { color: { surface: surfaceHex } } : {}),
+      ...(radiusMd !== undefined ? { radius: { md: radiusMd } } : {}),
+    },
+  });
+}
+
+/**
+ * Live theme playground — debounces control changes, caches paired palettes by
+ * brand seed, and holds the last valid theme while the seed is mid-edit.
+ */
+export function ThemePlayground({
+  brandSeed = DEFAULT_BRAND,
+  colorScheme = DEFAULT_SCHEME,
+  surface,
+  radiusMd,
+}: ThemePlaygroundControls): JSX.Element {
+  const [theme, setTheme] = useState<Theme>(
+    () =>
+      buildTheme(brandSeed, colorScheme, surface, radiusMd) ??
+      createTheme({ colorScheme }),
+  );
+  const lastValid = useRef(theme);
+
+  useEffect(() => {
+    const id = window.setTimeout(() => {
+      const next = buildTheme(brandSeed, colorScheme, surface, radiusMd);
+      if (next) {
+        lastValid.current = next;
+        setTheme(next);
+      } else {
+        setTheme(lastValid.current);
+      }
+    }, 150);
+    return () => window.clearTimeout(id);
+  }, [brandSeed, colorScheme, surface, radiusMd]);
+
+  const holding = pairedFor(brandSeed) === null;
+  const contrast = useMemo(() => checkThemeContrast(theme), [theme]);
+
+  return (
+    <SilkProvider theme={theme}>
+      <Stack
+        gap="4"
+        data-fixture="theme-playground"
+        data-scheme={theme.colorScheme}
+      >
+        <SurfacePanel gap="3">
+          <Text role="heading">Theme playground</Text>
+          <Text tone="secondary">
+            Brand seed {brandSeed} · {theme.colorScheme}
+            {holding ? ' (holding last valid theme)' : ''}
+          </Text>
+          <Text
+            data-contrast={contrast.ok ? 'ok' : 'fail'}
+            tone={contrast.ok ? 'secondary' : 'danger'}
+          >
+            Contrast:{' '}
+            {contrast.ok ? 'pass' : `${contrast.violations.length} issue(s)`}
+          </Text>
+          <Inline gap="2" wrap="wrap">
+            <Button>Accent</Button>
+            <Button tone="neutral" variant="outline">
+              Neutral
+            </Button>
+            <Button tone="danger" variant="soft">
+              Danger
+            </Button>
+            <Badge tone="success">Success</Badge>
+          </Inline>
+          <Input aria-label="Playground input" placeholder="Typed control" />
+        </SurfacePanel>
+      </Stack>
+    </SilkProvider>
+  );
+}
diff --git a/apps/docs/src/theme/tenants.ts b/apps/docs/src/theme/tenants.ts
new file mode 100644
index 0000000..095250f
--- /dev/null
+++ b/apps/docs/src/theme/tenants.ts
@@ -0,0 +1,49 @@
+import {
+  checkThemeContrast,
+  createTheme,
+  generatePairedPalette,
+  type Theme,
+} from '@reactive/silk';
+
+/**
+ * Stage 5 exit tenants — visually distinct brand seeds, each with paired
+ * light/dark palettes from `generatePairedPalette` (no runtime CSS).
+ */
+const oceanPaired = generatePairedPalette('#0ea5e9');
+const emberPaired = generatePairedPalette('#ea580c', {
+  dangerSeedHex: '#e11d48',
+});
+
+export const oceanLight: Theme = createTheme({
+  colorScheme: 'light',
+  palette: oceanPaired.light,
+});
+export const oceanDark: Theme = createTheme({
+  colorScheme: 'dark',
+  palette: oceanPaired.dark,
+});
+export const emberLight: Theme = createTheme({
+  colorScheme: 'light',
+  palette: emberPaired.light,
+});
+export const emberDark: Theme = createTheme({
+  colorScheme: 'dark',
+  palette: emberPaired.dark,
+});
+
+export const tenantThemes = {
+  ocean: { light: oceanLight, dark: oceanDark },
+  ember: { light: emberLight, dark: emberDark },
+} as const;
+
+/** Fail loudly at module load if a demo tenant drifts off-contract. */
+for (const [tenant, schemes] of Object.entries(tenantThemes)) {
+  for (const [scheme, theme] of Object.entries(schemes)) {
+    const result = checkThemeContrast(theme);
+    if (!result.ok) {
+      throw new Error(
+        `Tenant theme ${tenant}/${scheme} failed contrast: ${JSON.stringify(result.violations)}`,
+      );
+    }
+  }
+}
diff --git a/apps/docs/src/theme/themingAcceptance.test.tsx b/apps/docs/src/theme/themingAcceptance.test.tsx
new file mode 100644
index 0000000..5ad8646
--- /dev/null
+++ b/apps/docs/src/theme/themingAcceptance.test.tsx
@@ -0,0 +1,110 @@
+import { SilkProvider } from '@reactive/silk';
+import { expect, test } from '@rstest/core';
+import { render, screen } from '@testing-library/react';
+import { InspectorPanel } from '../fixtures/InspectorPanel';
+import { SocialFeed } from '../fixtures/SocialFeed';
+import { emberDark, emberLight, oceanDark, oceanLight } from './tenants';
+
+test('SocialFeed renders under both tenant themes and both schemes', () => {
+  const themes = [
+    ['ocean/light', oceanLight],
+    ['ocean/dark', oceanDark],
+    ['ember/light', emberLight],
+    ['ember/dark', emberDark],
+  ] as const;
+
+  for (const [label, theme] of themes) {
+    const { container, unmount } = render(
+      <SilkProvider theme={theme}>
+        <SocialFeed state="normal" />
+      </SilkProvider>,
+    );
+    const root = container.querySelector('[data-fixture="social-feed"]');
+    expect(root, label).not.toBeNull();
+    const scope = container.firstElementChild as HTMLElement;
+    expect(scope.style.getPropertyValue('--silk-color-surface')).not.toBe('');
+    expect(scope.getAttribute('data-theme')).toBe(theme.colorScheme);
+    unmount();
+  }
+});
+
+test('InspectorPanel under outer tenant reconstitutes hooks into portal', () => {
+  render(
+    <SilkProvider
+      theme={oceanLight}
+      style={{ ['--silk-button-bg' as string]: 'rgb(10, 20, 30)' }}
+    >
+      <InspectorPanel state="overlaysOpen" />
+    </SilkProvider>,
+  );
+
+  const menu = document.querySelector('[role="menu"]');
+  expect(menu).not.toBeNull();
+  const portalScope = menu!.closest('[data-theme]') as HTMLElement | null;
+  expect(portalScope).not.toBeNull();
+  expect(portalScope!.style.getPropertyValue('--silk-color-surface')).not.toBe(
+    '',
+  );
+  expect(portalScope!.style.getPropertyValue('--silk-button-bg')).toBe(
+    'rgb(10, 20, 30)',
+  );
+
+  // Theme delivery stays on the style attribute (ScrollArea may add constant
+  // <style> elements; those must not carry theme CSS variables).
+  const themeStylesheets = [...document.querySelectorAll('style')].filter(
+    (el) => (el.textContent ?? '').includes('--silk-color-surface'),
+  );
+  expect(themeStylesheets).toEqual([]);
+});
+
+test('tenant-inside-named and named-inside-tenant nesting', () => {
+  const { container: namedInside } = render(
+    <SilkProvider
+      theme={emberLight}
+      style={{ ['--silk-badge-bg' as string]: 'rgb(1, 2, 3)' }}
+    >
+      <SilkProvider colorScheme="dark">
+        <SocialFeed state="normal" />
+      </SilkProvider>
+    </SilkProvider>,
+  );
+  const namedScope = (
+    namedInside.firstElementChild as HTMLElement
+  ).firstElementChild as HTMLElement;
+  expect(namedScope.getAttribute('data-theme')).toBe('dark');
+  expect(namedScope.style.getPropertyValue('--silk-color-surface')).toBe('');
+  expect(namedScope.style.getPropertyValue('--silk-badge-bg')).toBe(
+    'rgb(1, 2, 3)',
+  );
+
+  const { container: tenantInside } = render(
+    <SilkProvider colorScheme="dark">
+      <SilkProvider theme={emberLight}>
+        <span data-testid="inner">x</span>
+      </SilkProvider>
+    </SilkProvider>,
+  );
+  const tenantScope = (
+    tenantInside.firstElementChild as HTMLElement
+  ).firstElementChild as HTMLElement;
+  expect(tenantScope.style.getPropertyValue('--silk-color-surface')).not.toBe(
+    '',
+  );
+  expect(tenantScope.contains(screen.getByTestId('inner'))).toBe(true);
+});
+
+test('side-by-side tenants do not insert dynamic stylesheets', () => {
+  const before = document.querySelectorAll('style').length;
+  const { unmount } = render(
+    <>
+      <SilkProvider theme={oceanLight}>
+        <SocialFeed state="normal" />
+      </SilkProvider>
+      <SilkProvider theme={emberDark}>
+        <SocialFeed state="normal" />
+      </SilkProvider>
+    </>,
+  );
+  expect(document.querySelectorAll('style').length).toBe(before);
+  unmount();
+});
diff --git a/docs/API_POLICY.md b/docs/API_POLICY.md
index 97b78a5..23054b1 100644
--- a/docs/API_POLICY.md
+++ b/docs/API_POLICY.md
@@ -10,7 +10,7 @@ Silk is pre-1.0. This document defines what counts as **public API** and how bre
 | Semantic token names | `surface`, `textPrimary`, `tones.accent.solid`, space steps `0`–`10` | Renaming or removing a token key is breaking |
 | Public CSS variables | `--silk-color-surface`, `--silk-color-surface-sunken`, `--silk-color-overlay`, `--silk-shadow-raised`, `--silk-shadow-overlay`, `--silk-color-tone-*-text`, `--silk-space-2`, `--silk-button-bg`, `--silk-grid-min` | Removing or changing the meaning of a documented `--silk-*` variable is breaking |
 | Recipe shapes | `buttonRecipe.variants`, `stackRecipe.defaults` | Removing an axis or declared value is breaking |
-| Core utilities | `defineRecipe`, `createTheme`, `compactSpace`, `DensityName` | Signature or behavioral changes that affect consumers are breaking |
+| Core utilities | `defineRecipe`, `createTheme`, `generateScale`, `generatePairedPalette`, `checkThemeContrast`, `contrastRatio`, `relativeLuminance`, `compactSpace`, `DensityName` | Signature or behavioral changes that affect consumers are breaking |
 | Package exports / subpaths | `@reactive/silk`, `@reactive/silk-core/tokens`, `@reactive/silk/styles.css` | Removing an export path is breaking |
 
 **Not public API** (may change without a major bump pre-1.0, but still prefer a changeset note):
@@ -49,6 +49,15 @@ Every user-facing change gets a changeset (`yarn changeset`):
 - **`Field.Root controlId`** — names the labelled control so `Field.Label htmlFor` and the control agree during server rendering. `FieldContextValue.controlId` is gone; `inputId` is the one resolved id. Setting `id` on a control inside a Field no longer retargets the label. *breaking:* move control-level `id` overrides up to `Field.Root controlId`.
 - Compact space remains the fixed `compactSpace` scale (not overridable via `createTheme.semantic.space`).
 
+## Stage 5 public additions
+
+- **`generateScale(seedHex, colorScheme)`** — OKLCH 12-step `PaletteScale` from canonical sRGB hex (`#RGB` / `#RRGGBB`); invalid input throws. Stable: hex input contract, 12-step shape, lowercase `#rrggbb` output. May improve: exact L/C curves between minors (validate with `checkThemeContrast`).
+- **`generatePairedPalette(brandHex, options?)`** — tenant recipe → `{ light, dark }` palettes (`blue`/`gray` from brand; `red`/`green` default or optional seeds). Dark derivation is a full palette, not accent-only.
+- **`checkThemeContrast(theme)`** → `{ ok, violations }` with discriminated kinds `contrast` \| `unsupported-color` \| `distinctness`. Hex-only audit; non-hex semantic colors are diagnostics, not silent passes.
+- **`contrastRatio` / `relativeLuminance` / `parseCanonicalHex`** — platform-neutral hex contrast helpers.
+- **Theme scope channels** — `semanticVars` vs `customVars` on web theme scope (behavior change for named-inside-tenant portals: component hooks now inherit; semantic vars still drop).
+- **Public component CSS-var list frozen** in `silkComponentVarMeta` (documented in Theming.mdx). Removals/renames/meaning changes are breaking.
+
 ## Stage 3 public additions
 
 - **Recipes:** `popoverRecipe` (`size`), `tabsRecipe` (`variant`), `selectRecipe` (`size`/`density`), `toastRecipe` (`tone`), `toggleRecipe` (`size`) — shared by Toggle and ToggleGroup.
diff --git a/docs/ARCHITECTURE.md b/docs/ARCHITECTURE.md
index 61efba2..e3e4b1f 100644
--- a/docs/ARCHITECTURE.md
+++ b/docs/ARCHITECTURE.md
@@ -38,12 +38,18 @@ Do **not** declare `--silk-button-bg: var(--silk-accent)` on the component — t
 | ---------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
 | Named light/dark | Static CSS + `data-theme` / `color-scheme` (and `prefers-color-scheme` when unset)                                                                                                                                                   |
 | Dynamic / tenant | `themeToCssVars(theme)` on the ThemeProvider `style` attribute                                                                                                                                                                       |
-| Nesting          | Secondary. Works via DOM variable inheritance in normal flow. Portals reconstitute the nearest ThemeProvider scope (class + `data-theme` + custom CSS vars); pass Dialog `container` when the portal DOM must live inside a subtree. |
+| Nesting          | Secondary. Works via DOM variable inheritance in normal flow. Portals reconstitute the nearest ThemeProvider scope (class + `data-theme` + semantic vars + custom vars); pass Dialog `container` when the portal DOM must live inside a subtree. |
 
 Prefer either `theme` (custom object) or `colorScheme` (named/static). If both are passed, `theme` wins for `data-theme` and inline variables. Nested providers inherit omitted `colorScheme` / `density` from the nearest ancestor.
 
+**Variable channels (Stage 5):** theme scope splits CSS variables into `semanticVars` (theme-owned: `--silk-color-*`, scales, type, motion, shadows, focus geometry) and `customVars` (component hooks / extensions). A nested `theme` or `colorScheme` **replaces** semantic vars so named children do not drag outer tenant semantics into portals; custom vars **always inherit** so branding hooks survive an inner named flip.
+
+**Tenant branding:** `generatePairedPalette(brandHex)` → `{ light, dark }` palettes (accent + brand-tinted gray; optional danger/success seeds). `generateScale` is the OKLCH 12-step primitive. `checkThemeContrast(theme)` audits the semantic contrast contract (hex-only; non-hex yields `unsupported-color` diagnostics).
+
 No runtime CSS-in-JS. No ad hoc `<style>` injection per provider. Constant SSR-rendered `<style>` from behavior bindings (Radix ScrollArea Viewport) is allowed when static and nonce-compatible — see PRINCIPLES amendment 2026-07-26.
 
+Public component CSS variables are listed in `silkComponentVarMeta` / Theming.mdx — sparse by design; removals/renames are breaking.
+
 ### Density
 
 System-level density remaps effective space tokens without renaming steps:
diff --git a/docs/ROADMAP.md b/docs/ROADMAP.md
index 5e2c4b9..957a005 100644
--- a/docs/ROADMAP.md
+++ b/docs/ROADMAP.md
@@ -88,16 +88,16 @@ Where product value lives. Styling and shared behavior come entirely from Silk p
 
 ---
 
-## Stage 5 — Theming maturity
+## Stage 5 — Theming maturity ✅ (done)
 
 Harden theming from "works" to "product-grade multi-tenant".
 
-- Nested themes: extend the Stage 2 acceptance tests to full-app composition and document the supported patterns.
-- Tenant branding: `createTheme` ergonomics for partial overrides, palette generation/contrast guidance, dark-mode derivation.
-- Component token audit: confirm the public CSS-variable surface is sparse, documented, and stable (it becomes API).
-- Theme preview/dev tooling in Storybook (live token editing against real components).
+- Nested themes: fixture-scale acceptance (SocialFeed / InspectorPanel) under tenants × schemes; portal channel split (`semanticVars` vs `customVars`); patterns documented in Theming.mdx + ARCHITECTURE.
+- Tenant branding: `generateScale` (OKLCH) + `generatePairedPalette` (paired light/dark, accent + gray); `checkThemeContrast` / `contrastRatio` public; ThemePlayground + TenantGallery in docs.
+- Component token audit: `silkComponentVarMeta` is the single source; Theming.mdx table sync-tested; sparse criteria documented.
+- Theme preview: Storybook ThemePlayground (debounced controls, contrast readout, last-valid-theme hold).
 
-**Exit criteria:** two visually distinct tenant themes plus light/dark run side by side in docs with no runtime CSS generation; public component-token list documented.
+**Exit criteria (met):** Ocean + Ember tenants × light/dark side by side in docs (inline CSS vars only); public component-token list documented and drift-guarded.
 
 ---
 
@@ -136,7 +136,7 @@ Tracked from the founding brief; each has a home stage where it must be resolved
 | Question | Resolved in | Status |
 | --- | --- | --- |
 | Recipes: shared model vs. per-renderer | Stage 0 | ✅ Shared contracts in core; renderers own styling |
-| Semantic vs. component tokens, how many | Stage 2/5 | Partially — Stage 2 audit landed (`success`, surfaces, shadows, tone `text`); Stage 5 freezes public CSS-var list |
+| Semantic vs. component tokens, how many | Stage 2/5 | ✅ Stage 2 audit + Stage 5 freeze (`silkComponentVarMeta` / Theming.mdx) |
 | Responsive strategy | Stage 1 | ✅ Intrinsic-first + container queries; `collapseBelow` web-only |
 | Slot architecture for composites | Stage 4 | ✅ Dual API, compound-first — [COMPOSITES.md](COMPOSITES.md) |
 | Variant expression (typed, tree-shakeable, RN-friendly) | Stage 0/1 | ✅ Proven on web; native spike validates in Stage 1 |
diff --git a/packages/silk-core/package.json b/packages/silk-core/package.json
index d6f8911..40aeafa 100644
--- a/packages/silk-core/package.json
+++ b/packages/silk-core/package.json
@@ -51,6 +51,10 @@
   },
   "devDependencies": {
     "@rstest/core": "^0.11.4",
+    "@types/culori": "^4.0.1",
     "typescript": "^7.0.2"
+  },
+  "dependencies": {
+    "culori": "^4.0.2"
   }
 }
diff --git a/packages/silk-core/src/index.ts b/packages/silk-core/src/index.ts
index 5f48203..fb5beb3 100644
--- a/packages/silk-core/src/index.ts
+++ b/packages/silk-core/src/index.ts
@@ -51,8 +51,23 @@ export {
   toneNames,
 } from './tokens/index.js';
 
-export { createTheme } from './theme/index.js';
-export type { CreateThemeOptions } from './theme/index.js';
+export {
+  checkThemeContrast,
+  contrastRatio,
+  createTheme,
+  generatePairedPalette,
+  generateScale,
+  parseCanonicalHex,
+  relativeLuminance,
+} from './theme/index.js';
+export type {
+  ContrastViolation,
+  CreateThemeOptions,
+  GenerateScaleOptions,
+  PairedPalette,
+  PairedPaletteOptions,
+  ThemeContrastResult,
+} from './theme/index.js';
 
 export {
   actionBarRecipe,
diff --git a/packages/silk-core/src/theme/checkThemeContrast.test.ts b/packages/silk-core/src/theme/checkThemeContrast.test.ts
new file mode 100644
index 0000000..75b4cca
--- /dev/null
+++ b/packages/silk-core/src/theme/checkThemeContrast.test.ts
@@ -0,0 +1,75 @@
+import { expect, test } from '@rstest/core';
+import { createTheme } from './createTheme.js';
+import { checkThemeContrast } from './checkThemeContrast.js';
+import { contrastRatio, relativeLuminance } from './colorMath.js';
+
+test('checker reports all diagnostic kinds without throwing', () => {
+  const theme = createTheme({
+    semantic: {
+      color: {
+        surface: 'oklch(100% 0 0)',
+        textPrimary: '#000000',
+        tones: {
+          accent: {
+            solid: '#cccccc',
+            onSolid: '#ffffff',
+            hover: '#cccccc',
+            active: '#cccccc',
+          },
+        },
+      },
+    },
+  });
+  const result = checkThemeContrast(theme);
+  expect(result.ok).toBe(false);
+  const kinds = new Set(result.violations.map((v) => v.kind));
+  expect(kinds.has('unsupported-color')).toBe(true);
+  expect(kinds.has('contrast') || kinds.has('distinctness')).toBe(true);
+});
+
+test('canonical hex forms are not treated as distinct', () => {
+  const theme = createTheme({
+    semantic: {
+      color: {
+        surface: '#ffffff',
+        surfaceRaised: '#fff',
+      },
+    },
+  });
+  const result = checkThemeContrast(theme);
+  expect(
+    result.violations.some(
+      (v) =>
+        v.kind === 'distinctness' &&
+        v.paths.includes('color.surface') &&
+        v.paths.includes('color.surfaceRaised'),
+    ),
+  ).toBe(true);
+});
+
+test('identical primary/secondary text fails distinctness', () => {
+  const theme = createTheme({
+    semantic: {
+      color: {
+        textPrimary: '#202020',
+        textSecondary: '#202020',
+      },
+    },
+  });
+  const result = checkThemeContrast(theme);
+  expect(
+    result.violations.some(
+      (v) =>
+        v.kind === 'distinctness' &&
+        v.paths.includes('color.textPrimary') &&
+        v.paths.includes('color.textSecondary'),
+    ),
+  ).toBe(true);
+});
+
+test('contrastRatio and relativeLuminance are hex-only', () => {
+  expect(relativeLuminance('#ffffff')).toBeCloseTo(1, 5);
+  expect(relativeLuminance('rgb(255,255,255)')).toBeNull();
+  expect(contrastRatio('#000000', '#ffffff')).toBeCloseTo(21, 5);
+  expect(contrastRatio('black', 'white')).toBeNull();
+});
diff --git a/packages/silk-core/src/theme/checkThemeContrast.ts b/packages/silk-core/src/theme/checkThemeContrast.ts
new file mode 100644
index 0000000..a497f63
--- /dev/null
+++ b/packages/silk-core/src/theme/checkThemeContrast.ts
@@ -0,0 +1,380 @@
+import { toneNames, type Theme } from '../tokens/index.js';
+import {
+  contrastRatio,
+  parseCanonicalHex,
+  relativeLuminance,
+} from './colorMath.js';
+
+export type ContrastViolation =
+  | {
+      readonly kind: 'contrast';
+      readonly pathFg: string;
+      readonly pathBg: string;
+      readonly threshold: number;
+      readonly actual: number;
+      readonly reason: string;
+    }
+  | {
+      readonly kind: 'unsupported-color';
+      readonly path: string;
+      readonly value: string;
+      readonly reason: string;
+    }
+  | {
+      readonly kind: 'distinctness';
+      readonly paths: readonly string[];
+      readonly reason: string;
+    };
+
+export interface ThemeContrastResult {
+  readonly ok: boolean;
+  readonly violations: readonly ContrastViolation[];
+}
+
+/** Minimum relative-luminance delta for “visibly distinct” fills (charter). */
+const MIN_LUMINANCE_DELTA = 0.01;
+
+function collectHex(
+  violations: ContrastViolation[],
+  seenUnsupported: Set<string>,
+  path: string,
+  value: string,
+): string | null {
+  const hex = parseCanonicalHex(value);
+  if (hex) {
+    return hex;
+  }
+  if (!seenUnsupported.has(path)) {
+    seenUnsupported.add(path);
+    violations.push({
+      kind: 'unsupported-color',
+      path,
+      value,
+      reason: 'Contrast auditing supports sRGB hex (#RGB / #RRGGBB) only',
+    });
+  }
+  return null;
+}
+
+function assertContrast(
+  violations: ContrastViolation[],
+  seenUnsupported: Set<string>,
+  pathFg: string,
+  fg: string,
+  pathBg: string,
+  bg: string,
+  threshold: number,
+  reason: string,
+): void {
+  const fgHex = collectHex(violations, seenUnsupported, pathFg, fg);
+  const bgHex = collectHex(violations, seenUnsupported, pathBg, bg);
+  if (!fgHex || !bgHex) {
+    return;
+  }
+  const actual = contrastRatio(fgHex, bgHex);
+  if (actual == null) {
+    return;
+  }
+  if (actual < threshold) {
+    violations.push({
+      kind: 'contrast',
+      pathFg,
+      pathBg,
+      threshold,
+      actual,
+      reason,
+    });
+  }
+}
+
+function assertDistinct(
+  violations: ContrastViolation[],
+  seenUnsupported: Set<string>,
+  paths: readonly string[],
+  values: readonly string[],
+  reason: string,
+): void {
+  const canonical: string[] = [];
+  for (let i = 0; i < values.length; i += 1) {
+    const hex = collectHex(violations, seenUnsupported, paths[i]!, values[i]!);
+    if (hex == null) {
+      return;
+    }
+    canonical.push(hex);
+  }
+  if (new Set(canonical).size !== canonical.length) {
+    violations.push({ kind: 'distinctness', paths, reason });
+  }
+}
+
+function assertLuminanceSeparation(
+  violations: ContrastViolation[],
+  seenUnsupported: Set<string>,
+  pathA: string,
+  a: string,
+  pathB: string,
+  b: string,
+  reason: string,
+): void {
+  const hexA = collectHex(violations, seenUnsupported, pathA, a);
+  const hexB = collectHex(violations, seenUnsupported, pathB, b);
+  if (!hexA || !hexB) {
+    return;
+  }
+  const lA = relativeLuminance(hexA);
+  const lB = relativeLuminance(hexB);
+  if (lA == null || lB == null) {
+    return;
+  }
+  if (Math.abs(lA - lB) < MIN_LUMINANCE_DELTA) {
+    violations.push({
+      kind: 'distinctness',
+      paths: [pathA, pathB],
+      reason,
+    });
+  }
+}
+
+/**
+ * Audit a theme against Silk's contrast and state-distinguishability contract.
+ *
+ * Hex-only: non-hex semantic colors produce `unsupported-color` diagnostics
+ * (they are not treated as passing). Overlay/rgba scrims are skipped.
+ */
+export function checkThemeContrast(theme: Theme): ThemeContrastResult {
+  const violations: ContrastViolation[] = [];
+  const seenUnsupported = new Set<string>();
+  const { color } = theme.semantic;
+
+  const surfaces = [
+    ['color.surface', color.surface],
+    ['color.surfaceRaised', color.surfaceRaised],
+    ['color.surfaceSunken', color.surfaceSunken],
+  ] as const;
+
+  // Validate core semantic colors once (overlay excluded — may include alpha).
+  for (const [path, value] of [
+    ...surfaces,
+    ['color.textPrimary', color.textPrimary],
+    ['color.textSecondary', color.textSecondary],
+    ['color.borderSubtle', color.borderSubtle],
+  ] as const) {
+    collectHex(violations, seenUnsupported, path, value);
+  }
+
+  for (const [path, surface] of surfaces) {
+    assertContrast(
+      violations,
+      seenUnsupported,
+      'color.textPrimary',
+      color.textPrimary,
+      path,
+      surface,
+      4.5,
+      'Primary text on surface must meet WCAG AA 4.5:1',
+    );
+    assertContrast(
+      violations,
+      seenUnsupported,
+      'color.textSecondary',
+      color.textSecondary,
+      path,
+      surface,
+      4.5,
+      'Secondary text on surface must meet WCAG AA 4.5:1',
+    );
+  }
+
+  assertDistinct(
+    violations,
+    seenUnsupported,
+    ['color.surface', 'color.surfaceRaised'],
+    [color.surface, color.surfaceRaised],
+    'Raised surface must differ from flat surface',
+  );
+  assertDistinct(
+    violations,
+    seenUnsupported,
+    ['color.surface', 'color.surfaceSunken'],
+    [color.surface, color.surfaceSunken],
+    'Sunken surface must differ from flat surface',
+  );
+  assertDistinct(
+    violations,
+    seenUnsupported,
+    ['color.textPrimary', 'color.textSecondary'],
+    [color.textPrimary, color.textSecondary],
+    'Primary and secondary text must differ',
+  );
+
+  for (const tone of toneNames) {
+    const t = color.tones[tone];
+    const base = `color.tones.${tone}`;
+
+    for (const [slot, value] of [
+      ['solid', t.solid],
+      ['onSolid', t.onSolid],
+      ['text', t.text],
+      ['subtle', t.subtle],
+      ['subtleHover', t.subtleHover],
+      ['subtleActive', t.subtleActive],
+      ['border', t.border],
+      ['hover', t.hover],
+      ['active', t.active],
+      ['focusRing', t.focusRing],
+      ['disabledFg', t.disabledFg],
+      ['disabledBg', t.disabledBg],
+    ] as const) {
+      collectHex(violations, seenUnsupported, `${base}.${slot}`, value);
+    }
+
+    assertContrast(
+      violations,
+      seenUnsupported,
+      `${base}.onSolid`,
+      t.onSolid,
+      `${base}.solid`,
+      t.solid,
+      4.5,
+      'onSolid on solid must meet WCAG AA 4.5:1',
+    );
+
+    for (const [slot, fill] of [
+      ['subtle', t.subtle],
+      ['subtleHover', t.subtleHover],
+      ['subtleActive', t.subtleActive],
+    ] as const) {
+      assertContrast(
+        violations,
+        seenUnsupported,
+        `${base}.text`,
+        t.text,
+        `${base}.${slot}`,
+        fill,
+        4.5,
+        'Tone text on subtle fills must meet WCAG AA 4.5:1',
+      );
+    }
+
+    assertContrast(
+      violations,
+      seenUnsupported,
+      `${base}.text`,
+      t.text,
+      'color.surface',
+      color.surface,
+      4.5,
+      'Tone text on page surface must meet WCAG AA 4.5:1',
+    );
+
+    if (tone !== 'neutral') {
+      for (const [path, surface] of [
+        ['color.surface', color.surface],
+        ['color.surfaceRaised', color.surfaceRaised],
+      ] as const) {
+        assertContrast(
+          violations,
+          seenUnsupported,
+          `${base}.text`,
+          t.text,
+          path,
+          surface,
+          4.5,
+          'Chromatic tone text on raised/flat surfaces must meet WCAG AA 4.5:1',
+        );
+      }
+    }
+
+    for (const [path, surface] of surfaces) {
+      assertContrast(
+        violations,
+        seenUnsupported,
+        `${base}.focusRing`,
+        t.focusRing,
+        path,
+        surface,
+        3,
+        'Focus ring must meet WCAG 1.4.11 non-text contrast 3:1',
+      );
+    }
+
+    for (const [slot, fill] of [
+      ['hover', t.hover],
+      ['active', t.active],
+    ] as const) {
+      assertContrast(
+        violations,
+        seenUnsupported,
+        `${base}.onSolid`,
+        t.onSolid,
+        `${base}.${slot}`,
+        fill,
+        4.5,
+        'onSolid must stay readable on hover/active fills',
+      );
+    }
+
+    assertDistinct(
+      violations,
+      seenUnsupported,
+      [`${base}.solid`, `${base}.hover`, `${base}.active`],
+      [t.solid, t.hover, t.active],
+      'solid/hover/active must be three distinct fills',
+    );
+    assertLuminanceSeparation(
+      violations,
+      seenUnsupported,
+      `${base}.solid`,
+      t.solid,
+      `${base}.hover`,
+      t.hover,
+      'solid and hover must be perceptually separated',
+    );
+    assertLuminanceSeparation(
+      violations,
+      seenUnsupported,
+      `${base}.hover`,
+      t.hover,
+      `${base}.active`,
+      t.active,
+      'hover and active must be perceptually separated',
+    );
+    assertDistinct(
+      violations,
+      seenUnsupported,
+      [`${base}.subtle`, `${base}.subtleHover`],
+      [t.subtle, t.subtleHover],
+      'subtleHover must differ from subtle',
+    );
+    assertDistinct(
+      violations,
+      seenUnsupported,
+      [`${base}.subtleHover`, `${base}.subtleActive`],
+      [t.subtleHover, t.subtleActive],
+      'subtleActive must differ from subtleHover',
+    );
+    assertDistinct(
+      violations,
+      seenUnsupported,
+      [`${base}.disabledBg`, `${base}.solid`],
+      [t.disabledBg, t.solid],
+      'disabledBg must differ from solid',
+    );
+    assertDistinct(
+      violations,
+      seenUnsupported,
+      [`${base}.disabledFg`, `${base}.onSolid`],
+      [t.disabledFg, t.onSolid],
+      'disabledFg must differ from onSolid',
+    );
+    assertDistinct(
+      violations,
+      seenUnsupported,
+      [`${base}.disabledFg`, `${base}.disabledBg`],
+      [t.disabledFg, t.disabledBg],
+      'disabledFg must differ from disabledBg',
+    );
+  }
+
+  return { ok: violations.length === 0, violations };
+}
diff --git a/packages/silk-core/src/theme/colorMath.ts b/packages/silk-core/src/theme/colorMath.ts
new file mode 100644
index 0000000..99e607a
--- /dev/null
+++ b/packages/silk-core/src/theme/colorMath.ts
@@ -0,0 +1,101 @@
+/**
+ * sRGB hex contrast utilities (WCAG 2.x relative luminance).
+ * Platform-neutral; hex-only — other CSS color syntaxes return null.
+ */
+
+/** Normalize `#RGB` / `#RRGGBB` to lowercase `#rrggbb`, or null. */
+export function parseCanonicalHex(color: string): string | null {
+  const hex = color.trim();
+  if (!hex.startsWith('#')) {
+    return null;
+  }
+  if (hex.length === 4 && /^#[0-9a-f]{3}$/i.test(hex)) {
+    return `#${hex[1]}${hex[1]}${hex[2]}${hex[2]}${hex[3]}${hex[3]}`.toLowerCase();
+  }
+  if (hex.length === 7 && /^#[0-9a-f]{6}$/i.test(hex)) {
+    return hex.toLowerCase();
+  }
+  return null;
+}
+
+export function parseHexChannels(
+  color: string,
+): [number, number, number] | null {
+  const hex = parseCanonicalHex(color);
+  if (!hex) {
+    return null;
+  }
+  return [
+    Number.parseInt(hex.slice(1, 3), 16),
+    Number.parseInt(hex.slice(3, 5), 16),
+    Number.parseInt(hex.slice(5, 7), 16),
+  ];
+}
+
+function linearize(channel: number): number {
+  const c = channel / 255;
+  return c <= 0.04045 ? c / 12.92 : ((c + 0.055) / 1.055) ** 2.4;
+}
+
+const luminanceCache = new Map<string, number>();
+
+/** WCAG relative luminance, or null when `color` is not a parseable hex. */
+export function relativeLuminance(color: string): number | null {
+  const hex = parseCanonicalHex(color);
+  if (!hex) {
+    return null;
+  }
+  const cached = luminanceCache.get(hex);
+  if (cached !== undefined) {
+    return cached;
+  }
+  const rgb = parseHexChannels(hex);
+  if (!rgb) {
+    return null;
+  }
+  const [r, g, b] = rgb;
+  const value =
+    0.2126 * linearize(r) + 0.7152 * linearize(g) + 0.0722 * linearize(b);
+  luminanceCache.set(hex, value);
+  return value;
+}
+
+/**
+ * WCAG contrast ratio for two sRGB hex colors.
+ * Returns null when either value is not a parseable hex (callers should emit
+ * `unsupported-color` rather than treating the pair as passing).
+ */
+export function contrastRatio(
+  foreground: string,
+  background: string,
+): number | null {
+  const l1 = relativeLuminance(foreground);
+  const l2 = relativeLuminance(background);
+  if (l1 == null || l2 == null) {
+    return null;
+  }
+  const lighter = Math.max(l1, l2);
+  const darker = Math.min(l1, l2);
+  return (lighter + 0.05) / (darker + 0.05);
+}
+
+/** Assert `#RRGGBB` (any case); returns canonical lowercase hex or throws. */
+export function requireCanonicalHex(seed: string, label = 'color'): string {
+  const hex = parseCanonicalHex(seed);
+  if (!hex) {
+    throw new Error(
+      `Invalid ${label}: expected #RGB or #RRGGBB sRGB hex, got ${JSON.stringify(seed)}`,
+    );
+  }
+  return hex;
+}
+
+/** Assert a finite number ≥ 0 (chroma caps, etc.). */
+export function requireFiniteNonNegative(value: number, label: string): number {
+  if (!Number.isFinite(value) || value < 0) {
+    throw new Error(
+      `Invalid ${label}: expected finite number >= 0, got ${String(value)}`,
+    );
+  }
+  return value;
+}
diff --git a/packages/silk-core/src/theme/contrast.test.ts b/packages/silk-core/src/theme/contrast.test.ts
index f39f08d..9691503 100644
--- a/packages/silk-core/src/theme/contrast.test.ts
+++ b/packages/silk-core/src/theme/contrast.test.ts
@@ -1,155 +1,16 @@
 import { expect, test } from '@rstest/core';
-import { toneNames } from '../tokens/index.js';
 import { createTheme } from './createTheme.js';
+import { checkThemeContrast } from './checkThemeContrast.js';
 
-/** sRGB channel → linear. */
-function linearize(channel: number): number {
-  const c = channel / 255;
-  return c <= 0.04045 ? c / 12.92 : ((c + 0.055) / 1.055) ** 2.4;
-}
-
-function parseHex(color: string): [number, number, number] | null {
-  const hex = color.trim();
-  if (!hex.startsWith('#') || (hex.length !== 7 && hex.length !== 4)) {
-    return null;
-  }
-  if (hex.length === 4) {
-    const r = Number.parseInt(hex[1]! + hex[1]!, 16);
-    const g = Number.parseInt(hex[2]! + hex[2]!, 16);
-    const b = Number.parseInt(hex[3]! + hex[3]!, 16);
-    return [r, g, b];
-  }
-  const r = Number.parseInt(hex.slice(1, 3), 16);
-  const g = Number.parseInt(hex.slice(3, 5), 16);
-  const b = Number.parseInt(hex.slice(5, 7), 16);
-  return [r, g, b];
-}
-
-function relativeLuminance(color: string): number | null {
-  const rgb = parseHex(color);
-  if (!rgb) {
-    return null;
-  }
-  const [r, g, b] = rgb;
-  return (
-    0.2126 * linearize(r) + 0.7152 * linearize(g) + 0.0722 * linearize(b)
-  );
-}
-
-function contrastRatio(foreground: string, background: string): number {
-  const l1 = relativeLuminance(foreground);
-  const l2 = relativeLuminance(background);
-  if (l1 == null || l2 == null) {
-    throw new Error(`Non-hex color pair: ${foreground} / ${background}`);
-  }
-  const lighter = Math.max(l1, l2);
-  const darker = Math.min(l1, l2);
-  return (lighter + 0.05) / (darker + 0.05);
-}
-
-const tones = toneNames;
-
+/**
+ * Stage 2/5 maturity gate: default themes satisfy the full contrast contract.
+ * Detailed diagnostics live in `checkThemeContrast`; this file keeps the
+ * per-scheme readability of the original Stage 2 suite.
+ */
 for (const scheme of ['light', 'dark'] as const) {
-  test(`${scheme}: text on surfaces meets 4.5:1`, () => {
-    const theme = createTheme({ colorScheme: scheme });
-    const { color } = theme.semantic;
-    for (const surface of [
-      color.surface,
-      color.surfaceRaised,
-      color.surfaceSunken,
-    ]) {
-      expect(contrastRatio(color.textPrimary, surface)).toBeGreaterThanOrEqual(
-        4.5,
-      );
-      expect(
-        contrastRatio(color.textSecondary, surface),
-      ).toBeGreaterThanOrEqual(4.5);
-    }
-  });
-
-  test(`${scheme}: onSolid/solid meets 4.5:1 for all tones`, () => {
-    const theme = createTheme({ colorScheme: scheme });
-    for (const tone of tones) {
-      const t = theme.semantic.color.tones[tone];
-      expect(contrastRatio(t.onSolid, t.solid)).toBeGreaterThanOrEqual(4.5);
-    }
-  });
-
-  test(`${scheme}: soft/outline/ghost FG (tone text) on subtle fills meets 4.5:1`, () => {
-    const theme = createTheme({ colorScheme: scheme });
-    for (const tone of tones) {
-      const t = theme.semantic.color.tones[tone];
-      for (const bg of [t.subtle, t.subtleHover, t.subtleActive]) {
-        expect(contrastRatio(t.text, bg)).toBeGreaterThanOrEqual(4.5);
-      }
-      // Transparent outline/ghost rests on page surface.
-      expect(
-        contrastRatio(t.text, theme.semantic.color.surface),
-      ).toBeGreaterThanOrEqual(4.5);
-    }
-  });
-
-  test(`${scheme}: tone text on raised/flat surfaces meets 4.5:1`, () => {
-    const theme = createTheme({ colorScheme: scheme });
-    const { color } = theme.semantic;
-    for (const surface of [color.surface, color.surfaceRaised]) {
-      for (const tone of ['accent', 'danger', 'success'] as const) {
-        expect(
-          contrastRatio(color.tones[tone].text, surface),
-        ).toBeGreaterThanOrEqual(4.5);
-      }
-    }
-  });
-
-  test(`${scheme}: focus ring ≥3:1 on all surfaces`, () => {
-    const theme = createTheme({ colorScheme: scheme });
-    const { color } = theme.semantic;
-    for (const tone of tones) {
-      for (const surface of [
-        color.surface,
-        color.surfaceRaised,
-        color.surfaceSunken,
-      ]) {
-        expect(
-          contrastRatio(color.tones[tone].focusRing, surface),
-        ).toBeGreaterThanOrEqual(3);
-      }
-    }
-  });
-
-  test(`${scheme}: disabled pair is distinguishable from enabled solid/onSolid`, () => {
-    const theme = createTheme({ colorScheme: scheme });
-    for (const tone of tones) {
-      const t = theme.semantic.color.tones[tone];
-      expect(t.disabledBg).not.toBe(t.solid);
-      expect(t.disabledFg).not.toBe(t.onSolid);
-      expect(t.disabledFg).not.toBe(t.disabledBg);
-      expect(t.subtleHover).not.toBe(t.subtle);
-      expect(t.subtleActive).not.toBe(t.subtleHover);
-    }
-  });
-
-  test(`${scheme}: solid/hover/active are three distinct fills`, () => {
-    const theme = createTheme({ colorScheme: scheme });
-    for (const tone of tones) {
-      const t = theme.semantic.color.tones[tone];
-      expect(new Set([t.solid, t.hover, t.active]).size).toBe(3);
-    }
-  });
-
-  test(`${scheme}: onSolid stays readable on hover and active fills`, () => {
-    const theme = createTheme({ colorScheme: scheme });
-    for (const tone of tones) {
-      const t = theme.semantic.color.tones[tone];
-      for (const fill of [t.hover, t.active]) {
-        expect(contrastRatio(t.onSolid, fill)).toBeGreaterThanOrEqual(4.5);
-      }
-    }
-  });
-
-  test(`${scheme}: raised surface differs from flat surface`, () => {
-    const theme = createTheme({ colorScheme: scheme });
-    const { color } = theme.semantic;
-    expect(color.surfaceRaised).not.toBe(color.surface);
+  test(`${scheme}: default theme passes checkThemeContrast`, () => {
+    const result = checkThemeContrast(createTheme({ colorScheme: scheme }));
+    expect(result.violations).toEqual([]);
+    expect(result.ok).toBe(true);
   });
 }
diff --git a/packages/silk-core/src/theme/createTheme.ts b/packages/silk-core/src/theme/createTheme.ts
index 92e7e7e..9b81515 100644
--- a/packages/silk-core/src/theme/createTheme.ts
+++ b/packages/silk-core/src/theme/createTheme.ts
@@ -14,6 +14,7 @@ import type {
   Theme,
   ToneName,
 } from '../tokens/index.js';
+import { parseHexChannels } from './colorMath.js';
 
 export interface CreateThemeOptions {
   readonly colorScheme?: ColorScheme;
@@ -59,17 +60,6 @@ function mergePalette(
   };
 }
 
-function parseHexChannels(color: string): [number, number, number] | null {
-  if (!/^#[0-9a-f]{6}$/i.test(color)) {
-    return null;
-  }
-  return [
-    Number.parseInt(color.slice(1, 3), 16),
-    Number.parseInt(color.slice(3, 5), 16),
-    Number.parseInt(color.slice(5, 7), 16),
-  ];
-}
-
 /**
  * Blend `from` toward `to` in sRGB, weighting `to` by `amount`.
  *
diff --git a/packages/silk-core/src/theme/generatePairedPalette.ts b/packages/silk-core/src/theme/generatePairedPalette.ts
new file mode 100644
index 0000000..7fd2983
--- /dev/null
+++ b/packages/silk-core/src/theme/generatePairedPalette.ts
@@ -0,0 +1,130 @@
+import { oklch } from 'culori';
+import {
+  defaultPalette,
+  defaultPaletteDark,
+  type ColorScheme,
+  type Palette,
+  type PaletteScale,
+} from '../tokens/index.js';
+import {
+  requireCanonicalHex,
+  requireFiniteNonNegative,
+} from './colorMath.js';
+import { generateScale } from './generateScale.js';
+import { nudgeLUntil, oklchChannelsToHex } from './oklchUtil.js';
+
+export interface PairedPaletteOptions {
+  /** Optional danger seed; defaults to Silk's built-in red scales. */
+  readonly dangerSeedHex?: string;
+  /** Optional success seed; defaults to Silk's built-in green scales. */
+  readonly successSeedHex?: string;
+  /**
+   * Peak OKLCH chroma for the brand-tinted gray scale. Defaults to 0.012 —
+   * enough for warm/cool neutrals without reading as a second accent.
+   */
+  readonly grayChromaCap?: number;
+}
+
+export interface PairedPalette {
+  readonly light: Palette;
+  readonly dark: Palette;
+}
+
+/**
+ * After gray + chromatic scales exist, repair steps that depend on both:
+ * dark onSolid (gray[1] on chromatic[9]) and focus rings vs sunken surfaces.
+ */
+function repairChromaticAgainstGray(
+  chromatic: PaletteScale,
+  gray: PaletteScale,
+  scheme: ColorScheme,
+): PaletteScale {
+  const next = { ...chromatic };
+  if (scheme === 'dark') {
+    // Brighten solid until onSolid and focus-ring floors clear.
+    next[9] = nudgeLUntil(next[9], gray[1], 4.5, {
+      direction: 1,
+      maxL: 0.9,
+      maxIters: 48,
+    });
+    next[9] = nudgeLUntil(next[9], gray[3], 3, {
+      direction: 1,
+      maxL: 0.9,
+      maxIters: 48,
+    });
+    // Keep hover (10) / active (11) above solid for distinctness.
+    const solid = oklch(next[9]);
+    const solidL = solid?.l ?? 0.65;
+    const c10 = oklch(next[10])?.c ?? 0;
+    const h10 = oklch(next[10])?.h ?? 0;
+    next[10] = oklchChannelsToHex(Math.min(0.92, solidL + 0.04), c10, h10);
+    const c11 = oklch(next[11])?.c ?? 0;
+    const h11 = oklch(next[11])?.h ?? 0;
+    next[11] = oklchChannelsToHex(Math.min(0.94, solidL + 0.1), c11, h11);
+  } else {
+    next[10] = nudgeLUntil(next[10], gray[3], 3, {
+      direction: -1,
+      minL: 0.2,
+    });
+  }
+  return next;
+}
+
+function buildSchemePalette(
+  brand: string,
+  scheme: ColorScheme,
+  grayCap: number,
+  danger: string | undefined,
+  success: string | undefined,
+): Palette {
+  const defaults = scheme === 'dark' ? defaultPaletteDark : defaultPalette;
+  const gray = generateScale(brand, scheme, { chromaCap: grayCap });
+  const blue = repairChromaticAgainstGray(
+    generateScale(brand, scheme),
+    gray,
+    scheme,
+  );
+  const red = danger
+    ? repairChromaticAgainstGray(generateScale(danger, scheme), gray, scheme)
+    : defaults.red;
+  const green = success
+    ? repairChromaticAgainstGray(generateScale(success, scheme), gray, scheme)
+    : defaults.green;
+  return { gray, blue, red, green };
+}
+
+/**
+ * Tenant branding recipe: one brand hex → light and dark palettes.
+ *
+ * Slot mapping:
+ * - `blue` (accent) ← brand seed chromatic scales
+ * - `gray` (surfaces / neutral / text) ← low-chroma brand-hue scales
+ * - `red` / `green` ← built-in defaults, or generated from optional seeds
+ *
+ * Pair both schemes from the same seeds so dark derivation is a complete
+ * palette (surfaces and neutrals included), not an accent-only remap.
+ */
+export function generatePairedPalette(
+  brandHex: string,
+  options: PairedPaletteOptions = {},
+): PairedPalette {
+  const brand = requireCanonicalHex(brandHex, 'brandHex');
+  const grayCap = requireFiniteNonNegative(
+    options.grayChromaCap ?? 0.012,
+    'grayChromaCap',
+  );
+
+  const danger =
+    options.dangerSeedHex !== undefined
+      ? requireCanonicalHex(options.dangerSeedHex, 'dangerSeedHex')
+      : undefined;
+  const success =
+    options.successSeedHex !== undefined
+      ? requireCanonicalHex(options.successSeedHex, 'successSeedHex')
+      : undefined;
+
+  return {
+    light: buildSchemePalette(brand, 'light', grayCap, danger, success),
+    dark: buildSchemePalette(brand, 'dark', grayCap, danger, success),
+  };
+}
diff --git a/packages/silk-core/src/theme/generateScale.matrix.test.ts b/packages/silk-core/src/theme/generateScale.matrix.test.ts
new file mode 100644
index 0000000..5880ff1
--- /dev/null
+++ b/packages/silk-core/src/theme/generateScale.matrix.test.ts
@@ -0,0 +1,63 @@
+import { expect, test } from '@rstest/core';
+import { createTheme } from './createTheme.js';
+import { checkThemeContrast } from './checkThemeContrast.js';
+import { generatePairedPalette } from './generatePairedPalette.js';
+import { generateScale } from './generateScale.js';
+
+/** Broad seed matrix spanning hue, lightness, and chroma — Stage 5 stability gate. */
+const MATRIX_SEEDS = [
+  '#ef4444',
+  '#f97316',
+  '#eab308',
+  '#22c55e',
+  '#14b8a6',
+  '#0ea5e9',
+  '#3b82f6',
+  '#8b5cf6',
+  '#ec4899',
+  '#78716c',
+  '#fafafa',
+  '#171717',
+  '#7c3aed',
+  '#65a30d',
+  '#0891b2',
+  '#b45309',
+] as const;
+
+test('generateScale is deterministic for a fixed seed', () => {
+  const a = generateScale('#2563eb', 'light');
+  const b = generateScale('#2563EB', 'light');
+  expect(a).toEqual(b);
+  expect(generateScale('#2563eb', 'dark')).toEqual(
+    generateScale('#2563eb', 'dark'),
+  );
+});
+
+test('hue/lightness/chroma matrix paired themes pass checkThemeContrast', () => {
+  const failures: string[] = [];
+  for (const seed of MATRIX_SEEDS) {
+    const paired = generatePairedPalette(seed);
+    for (const scheme of ['light', 'dark'] as const) {
+      const result = checkThemeContrast(
+        createTheme({ colorScheme: scheme, palette: paired[scheme] }),
+      );
+      if (!result.ok) {
+        failures.push(
+          `${seed}/${scheme}: ${JSON.stringify(result.violations)}`,
+        );
+      }
+    }
+  }
+  expect(failures).toEqual([]);
+});
+
+test('golden contract: ocean brand step roles stay contrast-safe', () => {
+  const scale = generateScale('#0ea5e9', 'light');
+  const theme = createTheme({
+    colorScheme: 'light',
+    palette: { blue: scale },
+  });
+  expect(checkThemeContrast(theme).ok).toBe(true);
+  expect(scale[11]).toMatch(/^#[0-9a-f]{6}$/);
+  expect(scale[12]).not.toBe(scale[11]);
+});
diff --git a/packages/silk-core/src/theme/generateScale.test.ts b/packages/silk-core/src/theme/generateScale.test.ts
new file mode 100644
index 0000000..fd5a06b
--- /dev/null
+++ b/packages/silk-core/src/theme/generateScale.test.ts
@@ -0,0 +1,65 @@
+import { expect, test } from '@rstest/core';
+import { createTheme } from './createTheme.js';
+import { checkThemeContrast } from './checkThemeContrast.js';
+import { generatePairedPalette } from './generatePairedPalette.js';
+import { generateScale } from './generateScale.js';
+
+test('generateScale validates and canonicalizes seeds', () => {
+  expect(() => generateScale('blue', 'light')).toThrow(/Invalid seedHex/);
+  expect(() => generateScale('#gg0000', 'light')).toThrow(/Invalid seedHex/);
+  expect(() => generateScale('#0ea5e9', 'light', { chromaCap: Number.NaN })).toThrow(
+    /chromaCap/,
+  );
+  expect(() =>
+    generateScale('#0ea5e9', 'light', { chromaCap: Number.POSITIVE_INFINITY }),
+  ).toThrow(/chromaCap/);
+  const scale = generateScale('#09F', 'light');
+  for (const step of [1, 2, 3, 4, 5, 6, 7, 8, 9, 10, 11, 12] as const) {
+    expect(scale[step]).toMatch(/^#[0-9a-f]{6}$/);
+  }
+});
+
+test('paired palettes preserve recipe invariants', () => {
+  const paired = generatePairedPalette('#2563eb', {
+    dangerSeedHex: '#e11d48',
+  });
+  expect(paired.light.blue[9]).not.toBe(paired.light.gray[9]);
+  expect(paired.dark.blue[9]).not.toBe(paired.dark.gray[9]);
+  // Default green retained; danger overridden in both schemes.
+  expect(paired.light.green).toEqual(
+    createTheme({ colorScheme: 'light' }).palette.green,
+  );
+  expect(paired.light.red[9]).not.toBe(
+    createTheme({ colorScheme: 'light' }).palette.red[9],
+  );
+  expect(paired.dark.red[9]).not.toBe(
+    createTheme({ colorScheme: 'dark' }).palette.red[9],
+  );
+});
+
+const TENANT_SEEDS = [
+  ['ocean', '#0ea5e9'],
+  ['violet', '#7c3aed'],
+  ['warm', '#ea580c'],
+  ['yellow', '#eab308'],
+  ['nearWhite', '#f5f5f5'],
+  ['nearBlack', '#1a1a1a'],
+  ['lowChroma', '#6b7280'],
+] as const;
+
+for (const [name, seed] of TENANT_SEEDS) {
+  test(`generated tenant ${name} passes maturity checks in both schemes`, () => {
+    const paired = generatePairedPalette(seed);
+    for (const scheme of ['light', 'dark'] as const) {
+      const theme = createTheme({
+        colorScheme: scheme,
+        palette: paired[scheme],
+      });
+      const result = checkThemeContrast(theme);
+      expect(
+        result,
+        `${name}/${scheme}: ${JSON.stringify(result.violations, null, 2)}`,
+      ).toMatchObject({ ok: true });
+    }
+  });
+}
diff --git a/packages/silk-core/src/theme/generateScale.ts b/packages/silk-core/src/theme/generateScale.ts
new file mode 100644
index 0000000..ec35c3c
--- /dev/null
+++ b/packages/silk-core/src/theme/generateScale.ts
@@ -0,0 +1,169 @@
+import { oklch } from 'culori';
+import type { ColorScheme, PaletteScale, PaletteStep } from '../tokens/index.js';
+import {
+  requireCanonicalHex,
+  requireFiniteNonNegative,
+} from './colorMath.js';
+import {
+  nudgeLUntil,
+  oklchAt,
+  oklchChannelsToHex,
+  oklchToHex,
+} from './oklchUtil.js';
+
+/**
+ * Lightness / relative-chroma templates distilled from Silk's default scales
+ * (Radix-inspired). Relative chroma is C / C₉ so a seed's chroma can scale the
+ * whole ramp while keeping the same shape.
+ */
+const CHROMATIC_LIGHT_L = [
+  0.993, 0.982, 0.96, 0.938, 0.905, 0.863, 0.81, 0.734, 0.649, 0.622, 0.556,
+  0.324,
+] as const;
+const CHROMATIC_LIGHT_C_REL = [
+  0.016, 0.047, 0.104, 0.181, 0.264, 0.352, 0.461, 0.627, 1, 0.948, 0.839,
+  0.497,
+] as const;
+const CHROMATIC_DARK_L = [
+  0.194, 0.213, 0.274, 0.32, 0.367, 0.416, 0.474, 0.541, 0.649, 0.688, 0.764,
+  0.907,
+] as const;
+const CHROMATIC_DARK_C_REL = [
+  0.13, 0.155, 0.342, 0.503, 0.549, 0.585, 0.632, 0.725, 1, 0.876, 0.653,
+  0.264,
+] as const;
+
+/** Neutral (gray) L curves — darker step 11 so textSecondary clears sunken. */
+const NEUTRAL_LIGHT_L = [
+  0.991, 0.982, 0.955, 0.931, 0.907, 0.885, 0.851, 0.792, 0.643, 0.61, 0.48,
+  0.244,
+] as const;
+const NEUTRAL_DARK_L = [
+  0.178, 0.213, 0.252, 0.285, 0.313, 0.348, 0.402, 0.489, 0.538, 0.583, 0.77,
+  0.949,
+] as const;
+
+const STEPS = [1, 2, 3, 4, 5, 6, 7, 8, 9, 10, 11, 12] as const;
+const SUNKEN_PROXY = oklchChannelsToHex(0.955, 0, 0);
+const SURFACE_PROXY = oklchChannelsToHex(0.178, 0, 0);
+
+/** Nudge L so adjacent steps serialize to distinct hex after gamut mapping. */
+function ensureDistinctSteps(
+  scale: Record<PaletteStep, string>,
+  hue: number,
+  peakC: number,
+  cRels: readonly number[],
+): void {
+  for (let i = 1; i < 12; i += 1) {
+    const prev = STEPS[i - 1]!;
+    const step = STEPS[i]!;
+    if (scale[step] !== scale[prev]) {
+      continue;
+    }
+    const prevL = oklch(scale[prev])?.l ?? 0.5;
+    const direction = i < 8 ? -1 : 1;
+    for (let n = 1; n <= 20; n += 1) {
+      const l = Math.min(0.995, Math.max(0.12, prevL + direction * 0.01 * n));
+      const next = oklchChannelsToHex(l, peakC * (cRels[i] ?? 0), hue);
+      if (next !== scale[prev]) {
+        scale[step] = next;
+        break;
+      }
+    }
+  }
+}
+
+export interface GenerateScaleOptions {
+  /**
+   * Cap chroma for near-neutral ramps (brand-tinted grays). When set, the
+   * seed's chroma is ignored and this absolute OKLCH C is used as the peak;
+   * the neutral L curve is used instead of the chromatic one.
+   */
+  readonly chromaCap?: number;
+}
+
+/**
+ * Generate a 12-step palette scale from a brand seed in OKLCH.
+ *
+ * - Input must be canonical sRGB hex (`#RGB` / `#RRGGBB`); invalid input throws.
+ * - Output is twelve lowercase `#rrggbb` values, gamut-mapped via clampChroma.
+ * - Guarantees monotonic role behavior for Silk's semantic mapping (light solid
+ *   at step 11 vs white; dark solid at step 9 vs dark surfaces), not visual
+ *   identity with Radix hand-authored scales.
+ * - Algorithm details (exact L/C curves) may improve between minor releases;
+ *   the hex input contract and 12-step shape are stable.
+ */
+export function generateScale(
+  seedHex: string,
+  colorScheme: ColorScheme,
+  options: GenerateScaleOptions = {},
+): PaletteScale {
+  const seed = requireCanonicalHex(seedHex, 'seedHex');
+  const seedOklch = oklch(seed);
+  if (!seedOklch) {
+    throw new Error(`Unable to parse seedHex: ${seed}`);
+  }
+
+  const chromaCap = options.chromaCap;
+  const isNeutral = chromaCap !== undefined;
+  if (chromaCap !== undefined) {
+    requireFiniteNonNegative(chromaCap, 'chromaCap');
+  }
+  const hue = seedOklch.h ?? 0;
+  const seedC = seedOklch.c ?? 0;
+  const peakC =
+    chromaCap !== undefined
+      ? chromaCap
+      : Math.min(0.25, Math.max(0.1, seedC < 0.04 ? 0.14 : seedC));
+
+  const Ls = isNeutral
+    ? colorScheme === 'light'
+      ? NEUTRAL_LIGHT_L
+      : NEUTRAL_DARK_L
+    : colorScheme === 'light'
+      ? CHROMATIC_LIGHT_L
+      : CHROMATIC_DARK_L;
+  const Crels =
+    colorScheme === 'light' ? CHROMATIC_LIGHT_C_REL : CHROMATIC_DARK_C_REL;
+
+  // Only shift chromatic mid-tones toward the seed's lightness; neutrals and
+  // extreme seeds keep the template so surfaces/text stay on-contract.
+  const seedL = seedOklch.l ?? Ls[8];
+  const lShift =
+    isNeutral || seedL < 0.25 || seedL > 0.9 ? 0 : seedL - Ls[8];
+
+  const out = {} as Record<PaletteStep, string>;
+  for (let i = 0; i < 12; i += 1) {
+    const step = STEPS[i]!;
+    let l = Ls[i]! + lShift * (1 - Math.abs(i - 8) / 11);
+    l = Math.min(0.995, Math.max(0.12, l));
+    out[step] = oklchChannelsToHex(l, peakC * Crels[i]!, hue);
+  }
+
+  if (colorScheme === 'light') {
+    if (isNeutral) {
+      // textSecondary = step 11 must clear 4.5:1 on surfaceSunken (step 3).
+      out[11] = nudgeLUntil(out[11], out[3], 4.5, { direction: -1 });
+      out[12] = nudgeLUntil(out[12], out[3], 7, { direction: -1 });
+      if ((oklch(out[12])?.l ?? 1) >= (oklch(out[11])?.l ?? 0)) {
+        out[12] = nudgeLUntil(out[12], out[11], 1.2, { direction: -1 });
+      }
+    } else {
+      out[11] = nudgeLUntil(out[11], '#ffffff', 4.5, { direction: -1 });
+      out[10] = nudgeLUntil(out[10], SUNKEN_PROXY, 3, { direction: -1 });
+      const l11 = oklch(out[11])?.l ?? 0.5;
+      out[12] = oklchToHex(
+        oklchAt(Math.min(l11 - 0.14, 0.35), peakC * Crels[11]!, hue),
+      );
+      out[12] = nudgeLUntil(out[12], SUNKEN_PROXY, 4.5, { direction: -1 });
+    }
+  } else if (!isNeutral) {
+    out[9] = nudgeLUntil(out[9], SURFACE_PROXY, 3, {
+      direction: 1,
+      maxL: 0.92,
+    });
+  }
+
+  ensureDistinctSteps(out, hue, peakC, Crels);
+  return out;
+}
diff --git a/packages/silk-core/src/theme/index.ts b/packages/silk-core/src/theme/index.ts
index 0072e8d..8dc4f33 100644
--- a/packages/silk-core/src/theme/index.ts
+++ b/packages/silk-core/src/theme/index.ts
@@ -1,2 +1,23 @@
 export { createTheme } from './createTheme.js';
 export type { CreateThemeOptions } from './createTheme.js';
+
+export {
+  contrastRatio,
+  parseCanonicalHex,
+  relativeLuminance,
+} from './colorMath.js';
+
+export { checkThemeContrast } from './checkThemeContrast.js';
+export type {
+  ContrastViolation,
+  ThemeContrastResult,
+} from './checkThemeContrast.js';
+
+export { generateScale } from './generateScale.js';
+export type { GenerateScaleOptions } from './generateScale.js';
+
+export { generatePairedPalette } from './generatePairedPalette.js';
+export type {
+  PairedPalette,
+  PairedPaletteOptions,
+} from './generatePairedPalette.js';
diff --git a/packages/silk-core/src/theme/oklchUtil.ts b/packages/silk-core/src/theme/oklchUtil.ts
new file mode 100644
index 0000000..0ccf43c
--- /dev/null
+++ b/packages/silk-core/src/theme/oklchUtil.ts
@@ -0,0 +1,68 @@
+import { clampChroma, formatHex, oklch, type Oklch } from 'culori';
+import { contrastRatio, relativeLuminance } from './colorMath.js';
+
+export function oklchAt(l: number, c: number, h: number): Oklch {
+  return { mode: 'oklch', l, c, h };
+}
+
+export function oklchToHex(color: Oklch): string {
+  const hex = formatHex(clampChroma(color, 'oklch'));
+  if (!hex) {
+    throw new Error('Failed to serialize OKLCH color to hex');
+  }
+  return hex.toLowerCase();
+}
+
+export function oklchChannelsToHex(l: number, c: number, h: number): string {
+  return oklchToHex(oklchAt(l, c, h));
+}
+
+/**
+ * Walk lightness until contrast vs `against` clears `threshold`.
+ * Caches the against-side luminance so each step only measures the candidate.
+ */
+export function nudgeLUntil(
+  hex: string,
+  against: string,
+  threshold: number,
+  options: {
+    readonly direction: 1 | -1;
+    readonly minL?: number;
+    readonly maxL?: number;
+    readonly delta?: number;
+    readonly maxIters?: number;
+  },
+): string {
+  let current = oklch(hex);
+  if (!current) {
+    return hex;
+  }
+  const againstL = relativeLuminance(against);
+  const delta = options.delta ?? 0.015;
+  const minL = options.minL ?? 0.15;
+  const maxL = options.maxL ?? 0.92;
+  const maxIters = options.maxIters ?? 40;
+
+  for (let i = 0; i < maxIters; i += 1) {
+    const candidate = oklchToHex(current);
+    const candidateL = relativeLuminance(candidate);
+    if (candidateL != null && againstL != null) {
+      const lighter = Math.max(candidateL, againstL);
+      const darker = Math.min(candidateL, againstL);
+      if ((lighter + 0.05) / (darker + 0.05) >= threshold) {
+        return candidate;
+      }
+    } else {
+      const ratio = contrastRatio(candidate, against);
+      if (ratio != null && ratio >= threshold) {
+        return candidate;
+      }
+    }
+    current = oklchAt(
+      Math.min(maxL, Math.max(minL, (current.l ?? 0.5) + options.direction * delta)),
+      current.c ?? 0,
+      current.h ?? 0,
+    );
+  }
+  return oklchToHex(current);
+}
diff --git a/packages/silk/src/components/Dialog.test.tsx b/packages/silk/src/components/Dialog.test.tsx
index f266f13..951496e 100644
--- a/packages/silk/src/components/Dialog.test.tsx
+++ b/packages/silk/src/components/Dialog.test.tsx
@@ -131,6 +131,29 @@ test('style attribute --silk-* overrides propagate to portal scope', () => {
   expect(scope.style.padding).toBe('');
 });
 
+test('named nested portal replaces semantics but preserves component hooks', () => {
+  const theme = createTheme({
+    semantic: { color: { surface: 'rgb(1, 2, 3)' } },
+  });
+
+  render(
+    <ThemeProvider
+      theme={theme}
+      style={{ ['--silk-button-bg' as string]: 'rgb(4, 5, 6)' }}
+    >
+      <ThemeProvider colorScheme="dark">
+        <OpenDialog />
+      </ThemeProvider>
+    </ThemeProvider>,
+  );
+
+  const scope = portalScope(screen.getByRole('dialog'));
+  expect(scope.getAttribute('data-theme')).toBe('dark');
+  // Outer tenant semantics must not override the named dark theme in the portal.
+  expect(scope.style.getPropertyValue('--silk-color-surface')).toBe('');
+  expect(scope.style.getPropertyValue('--silk-button-bg')).toBe('rgb(4, 5, 6)');
+});
+
 test('explicit container still hosts a single theme scope wrapper', () => {
   const host = document.createElement('div');
   document.body.append(host);
diff --git a/packages/silk/src/index.ts b/packages/silk/src/index.ts
index f56aec6..f88c59e 100644
--- a/packages/silk/src/index.ts
+++ b/packages/silk/src/index.ts
@@ -208,9 +208,15 @@ export type {
 } from './components';
 
 export {
+  checkThemeContrast,
+  contrastRatio,
   createTheme,
   cssVars,
   densityClass,
+  generatePairedPalette,
+  generateScale,
+  relativeLuminance,
+  silkComponentVarMeta,
   silkComponentVarNames,
   SilkProvider,
   ThemeProvider,
@@ -220,17 +226,23 @@ export {
 } from './theme';
 export type {
   ColorScheme,
+  ContrastViolation,
   CreateThemeOptions,
   CssVarMap,
   DensityName,
   FontFamilyName,
+  GenerateScaleOptions,
+  PairedPalette,
+  PairedPaletteOptions,
   Palette,
   SemanticTokens,
+  SilkComponentVarMeta,
   SilkComponentVarName,
   SilkComponentVars,
   SilkDefaults,
   SilkProviderProps,
   Theme,
+  ThemeContrastResult,
   ThemeProviderProps,
 } from './theme';
 
diff --git a/packages/silk/src/theme/ThemeProvider.test.tsx b/packages/silk/src/theme/ThemeProvider.test.tsx
index 2965182..2b7165e 100644
--- a/packages/silk/src/theme/ThemeProvider.test.tsx
+++ b/packages/silk/src/theme/ThemeProvider.test.tsx
@@ -73,12 +73,15 @@ test('nested density-only provider inherits parent colorScheme', () => {
   expect(inner.getAttribute('data-density')).toBe('compact');
 });
 
-test('explicit named scheme drops parent custom CSS vars', () => {
+test('explicit named scheme drops parent semantic vars but keeps component hooks', () => {
   const theme = createTheme({
     semantic: { color: { surface: 'rgb(1, 2, 3)' } },
   });
   const { container } = render(
-    <ThemeProvider theme={theme}>
+    <ThemeProvider
+      theme={theme}
+      style={{ ['--silk-button-bg' as string]: 'rgb(4, 5, 6)' }}
+    >
       <ThemeProvider colorScheme="dark">
         <span>content</span>
       </ThemeProvider>
@@ -90,6 +93,7 @@ test('explicit named scheme drops parent custom CSS vars', () => {
     'rgb(1, 2, 3)',
   );
   expect(inner.style.getPropertyValue('--silk-color-surface')).toBe('');
+  expect(inner.style.getPropertyValue('--silk-button-bg')).toBe('rgb(4, 5, 6)');
   expect(inner.getAttribute('data-theme')).toBe('dark');
 });
 
diff --git a/packages/silk/src/theme/ThemeProvider.tsx b/packages/silk/src/theme/ThemeProvider.tsx
index a17d71d..3439064 100644
--- a/packages/silk/src/theme/ThemeProvider.tsx
+++ b/packages/silk/src/theme/ThemeProvider.tsx
@@ -8,6 +8,10 @@ import {
   type ReactNode,
 } from 'react';
 import { Slot } from 'radix-ui';
+import {
+  mergeCssVarMaps,
+  partitionCssVars,
+} from './partitionCssVars';
 import {
   ThemeScopeContext,
   themeScopeDomProps,
@@ -84,6 +88,13 @@ function resolveDataTheme(
  * Theme scope root. Named themes flip `data-theme` against static CSS;
  * custom themes set CSS variables on the style attribute.
  * Nested providers inherit omitted `colorScheme` / `density` from the parent.
+ *
+ * Variable channels:
+ * - `semanticVars` — theme-owned tokens; replaced by nested `theme` /
+ *   `colorScheme` (named children do not carry outer tenant semantics into
+ *   portals).
+ * - `customVars` — component hooks / extensions; always inherit so portals
+ *   under an inner named scheme still see outer branding hooks.
  */
 export function ThemeProvider({
   theme,
@@ -97,29 +108,44 @@ export function ThemeProvider({
   const parent = useContext(ThemeScopeContext);
   const dataTheme = resolveDataTheme(theme, colorScheme, parent?.dataTheme);
   const resolvedDensity = density ?? parent?.density;
-  const inheritsParentVars =
-    theme === undefined && colorScheme === undefined;
+  const replacesSemantics = theme !== undefined || colorScheme !== undefined;
 
   const themeVars = useMemo(
     () => (theme ? themeToCssVars(theme) : undefined),
     [theme],
   );
-  const styleVars = useMemo(() => pickSilkCssVars(style), [style]);
+  const styleParts = useMemo(
+    () => partitionCssVars(pickSilkCssVars(style)),
+    [style],
+  );
 
   const scopeValue = useMemo((): ThemeScopeValue => {
-    const parentVars = inheritsParentVars ? parent?.cssVars : undefined;
-    const cssVars =
-      themeVars || styleVars || parentVars
-        ? { ...parentVars, ...themeVars, ...styleVars }
-        : undefined;
-    return { dataTheme, density: resolvedDensity, cssVars };
+    const parentSemantic = replacesSemantics
+      ? undefined
+      : parent?.semanticVars;
+    const semanticVars = mergeCssVarMaps(
+      parentSemantic,
+      themeVars,
+      styleParts.semanticVars,
+    );
+    const customVars = mergeCssVarMaps(
+      parent?.customVars,
+      styleParts.customVars,
+    );
+    return {
+      dataTheme,
+      density: resolvedDensity,
+      semanticVars,
+      customVars,
+    };
   }, [
     themeVars,
-    styleVars,
+    styleParts,
     dataTheme,
     resolvedDensity,
-    inheritsParentVars,
-    parent?.cssVars,
+    replacesSemantics,
+    parent?.semanticVars,
+    parent?.customVars,
   ]);
 
   const domProps = useMemo(
diff --git a/packages/silk/src/theme/ThemeScope.tsx b/packages/silk/src/theme/ThemeScope.tsx
index f1a20db..22c0c2f 100644
--- a/packages/silk/src/theme/ThemeScope.tsx
+++ b/packages/silk/src/theme/ThemeScope.tsx
@@ -10,12 +10,22 @@ import {
   type ReactNode,
 } from 'react';
 import { themeScopeClasses } from './namedThemes.css';
+import { mergeCssVarMaps } from './partitionCssVars';
 import type { CssVarMap } from './themeToCssVars';
 
 export interface ThemeScopeValue {
   readonly dataTheme: ColorScheme | undefined;
   readonly density: DensityName | undefined;
-  readonly cssVars: CssVarMap | undefined;
+  /**
+   * Theme-owned variables (`--silk-color-*`, scales, …). Replaced by a nested
+   * `theme` / `colorScheme` provider; not inherited across named boundaries.
+   */
+  readonly semanticVars: CssVarMap | undefined;
+  /**
+   * Component hooks and extension `--silk-*` vars. Inherit through named-theme
+   * children so portals under an inner `colorScheme` still see outer hooks.
+   */
+  readonly customVars: CssVarMap | undefined;
 }
 
 export const ThemeScopeContext: Context<ThemeScopeValue | null> =
@@ -37,9 +47,10 @@ export function themeScopeDomProps(
   readonly 'data-theme'?: ColorScheme;
   readonly 'data-density'?: DensityName;
 } {
+  const cssVars = mergeCssVarMaps(scope.semanticVars, scope.customVars);
   const style =
-    scope.cssVars || extras?.style
-      ? { ...scope.cssVars, ...extras?.style }
+    cssVars || extras?.style
+      ? { ...cssVars, ...extras?.style }
       : undefined;
 
   return {
diff --git a/packages/silk/src/theme/componentVars.test.ts b/packages/silk/src/theme/componentVars.test.ts
index 0d5bf44..469fcc9 100644
--- a/packages/silk/src/theme/componentVars.test.ts
+++ b/packages/silk/src/theme/componentVars.test.ts
@@ -38,6 +38,13 @@ function extractComponentVars(css: string): Set<string> {
   return found;
 }
 
+test('silkComponentVarMeta names match silkComponentVarNames', async () => {
+  const { silkComponentVarMeta } = await import('./componentVars');
+  expect(silkComponentVarMeta.map((entry) => entry.name)).toEqual([
+    ...silkComponentVarNames,
+  ]);
+});
+
 test('no undeclared --silk-* hook leaks into the stylesheet', () => {
   const inCss = extractComponentVars(loadDistCss());
   expect([...inCss].sort()).toEqual([...silkComponentVarNames].sort());
diff --git a/packages/silk/src/theme/componentVars.ts b/packages/silk/src/theme/componentVars.ts
index abcf6ac..0bca8d4 100644
--- a/packages/silk/src/theme/componentVars.ts
+++ b/packages/silk/src/theme/componentVars.ts
@@ -1,13 +1,27 @@
 import type { CSSProperties } from 'react';
 
 /**
- * Every public component override hook, in the form components consume them:
- * `var(--silk-{component}-{slot}, <semantic fallback>)`.
+ * Sparse-criteria for public component CSS variables:
+ * - One hook per independently brandable slot (bg / border / fg / radius / …)
+ * - Must resolve to a semantic token (or geometry) by default — never a palette step
+ * - Prefer a semantic fix over adding a hook when many components need the same concept
+ * - Removals, renames, and semantic-meaning changes are breaking (API_POLICY)
+ */
+export interface SilkComponentVarMeta {
+  readonly name: SilkComponentVarName;
+  readonly component: string;
+  /** Default resolution path (semantic token or geometry the hook falls back to). */
+  readonly defaultResolution: string;
+  readonly rationale: string;
+}
+
+/**
+ * Every public component override hook. Literal union source for
+ * `SilkComponentVarName`.
  *
- * Component tokens stay sparse on purpose — they are an override surface, not a
- * parallel token system. `componentVars.test.ts` asserts this list and the
- * extracted stylesheet agree in both directions, so a hook cannot be added,
- * renamed, or dropped without the list following.
+ * Kept beside `silkComponentVarMeta` (not derived) because
+ * `isolatedDeclarations` cannot emit a const-asserted array that also carries
+ * docs metadata; `componentVars.test.ts` asserts the two lists stay identical.
  */
 export const silkComponentVarNames = [
   '--silk-avatar-size',
@@ -41,6 +55,175 @@ export const silkComponentVarNames = [
 
 export type SilkComponentVarName = (typeof silkComponentVarNames)[number];
 
+/**
+ * Canonical public component override surface with docs metadata.
+ * Theming.mdx table is generated from this list (sync-tested).
+ */
+export const silkComponentVarMeta: readonly SilkComponentVarMeta[] = [
+  {
+    name: '--silk-avatar-size',
+    component: 'Avatar',
+    defaultResolution: 'mediaScale edge (px)',
+    rationale: 'Runtime size when not using the size axis',
+  },
+  {
+    name: '--silk-badge-bg',
+    component: 'Badge',
+    defaultResolution: 'tone solid / subtle by variant',
+    rationale: 'Brand fill override',
+  },
+  {
+    name: '--silk-badge-border',
+    component: 'Badge',
+    defaultResolution: 'tone border',
+    rationale: 'Brand border override',
+  },
+  {
+    name: '--silk-badge-fg',
+    component: 'Badge',
+    defaultResolution: 'tone onSolid / text by variant',
+    rationale: 'Brand foreground override',
+  },
+  {
+    name: '--silk-badge-radius',
+    component: 'Badge',
+    defaultResolution: 'radius.md / full by size',
+    rationale: 'Corner radius escape hatch',
+  },
+  {
+    name: '--silk-button-bg',
+    component: 'Button',
+    defaultResolution: 'tone solid / subtle by variant',
+    rationale: 'Brand fill override',
+  },
+  {
+    name: '--silk-button-border',
+    component: 'Button',
+    defaultResolution: 'tone border',
+    rationale: 'Brand border override',
+  },
+  {
+    name: '--silk-button-fg',
+    component: 'Button',
+    defaultResolution: 'tone onSolid / text by variant',
+    rationale: 'Brand foreground override',
+  },
+  {
+    name: '--silk-button-radius',
+    component: 'Button',
+    defaultResolution: 'radius.md',
+    rationale: 'Corner radius escape hatch',
+  },
+  {
+    name: '--silk-card-bg',
+    component: 'Card',
+    defaultResolution: 'color.surfaceRaised',
+    rationale: 'Surface fill override',
+  },
+  {
+    name: '--silk-card-border',
+    component: 'Card',
+    defaultResolution: 'color.borderSubtle',
+    rationale: 'Border override',
+  },
+  {
+    name: '--silk-card-radius',
+    component: 'Card',
+    defaultResolution: 'radius.lg',
+    rationale: 'Corner radius escape hatch',
+  },
+  {
+    name: '--silk-card-shadow',
+    component: 'Card',
+    defaultResolution: 'shadow.raised when elevated',
+    rationale: 'Elevation ink override',
+  },
+  {
+    name: '--silk-empty-state-measure',
+    component: 'EmptyState',
+    defaultResolution: 'measure.prose',
+    rationale: 'Readable measure for empty-state copy',
+  },
+  {
+    name: '--silk-grid-min',
+    component: 'Grid',
+    defaultResolution: 'minColumnWidth prop / recipe default',
+    rationale: 'Runtime track minimum',
+  },
+  {
+    name: '--silk-input-bg',
+    component: 'Input/Textarea',
+    defaultResolution: 'color.surfaceSunken',
+    rationale: 'Control fill override',
+  },
+  {
+    name: '--silk-input-border',
+    component: 'Input/Textarea',
+    defaultResolution: 'color.borderSubtle',
+    rationale: 'Control border override',
+  },
+  {
+    name: '--silk-input-radius',
+    component: 'Input/Textarea',
+    defaultResolution: 'radius.md',
+    rationale: 'Control radius escape hatch',
+  },
+  {
+    name: '--silk-scrollarea-thumb',
+    component: 'ScrollArea',
+    defaultResolution: 'color.borderSubtle',
+    rationale: 'Scrollbar thumb ink',
+  },
+  {
+    name: '--silk-select-bg',
+    component: 'Select',
+    defaultResolution: 'color.surfaceSunken',
+    rationale: 'Trigger fill override',
+  },
+  {
+    name: '--silk-select-border',
+    component: 'Select',
+    defaultResolution: 'color.borderSubtle',
+    rationale: 'Trigger border override',
+  },
+  {
+    name: '--silk-select-radius',
+    component: 'Select',
+    defaultResolution: 'radius.md',
+    rationale: 'Trigger radius escape hatch',
+  },
+  {
+    name: '--silk-status-dot-bg',
+    component: 'StatusDot',
+    defaultResolution: 'tone solid',
+    rationale: 'Status ink override',
+  },
+  {
+    name: '--silk-surface-bg',
+    component: 'Surface',
+    defaultResolution: 'color.surface / surfaceRaised / surfaceSunken',
+    rationale: 'Surface fill override',
+  },
+  {
+    name: '--silk-surface-border',
+    component: 'Surface',
+    defaultResolution: 'color.borderSubtle',
+    rationale: 'Surface border override',
+  },
+  {
+    name: '--silk-surface-radius',
+    component: 'Surface',
+    defaultResolution: 'radius.md',
+    rationale: 'Surface radius escape hatch',
+  },
+  {
+    name: '--silk-surface-shadow',
+    component: 'Surface',
+    defaultResolution: 'shadow.raised when elevated',
+    rationale: 'Elevation ink override',
+  },
+];
+
 /**
  * `| undefined` is deliberate under `exactOptionalPropertyTypes`: without it a
  * conditional value (`cond ? color : undefined`) would not typecheck.
@@ -64,3 +247,14 @@ export type SilkComponentVars = Partial<
 export function cssVars(vars: SilkComponentVars): CSSProperties {
   return vars as CSSProperties;
 }
+
+/** Markdown table body derived from metadata — used by docs sync tests. */
+export function formatComponentVarDocsTable(): string {
+  const header =
+    '| Variable | Component | Default resolution | Rationale |\n| --- | --- | --- | --- |';
+  const rows = silkComponentVarMeta.map(
+    (entry) =>
+      `| \`${entry.name}\` | ${entry.component} | ${entry.defaultResolution} | ${entry.rationale} |`,
+  );
+  return [header, ...rows].join('\n');
+}
diff --git a/packages/silk/src/theme/componentVarsDocs.test.ts b/packages/silk/src/theme/componentVarsDocs.test.ts
new file mode 100644
index 0000000..52c5df2
--- /dev/null
+++ b/packages/silk/src/theme/componentVarsDocs.test.ts
@@ -0,0 +1,23 @@
+import { readFileSync } from 'node:fs';
+import { dirname, join } from 'node:path';
+import { fileURLToPath } from 'node:url';
+import { expect, test } from '@rstest/core';
+import { formatComponentVarDocsTable } from './componentVars';
+
+const themingMdx = join(
+  dirname(fileURLToPath(import.meta.url)),
+  '../../../../apps/docs/src/Theming.mdx',
+);
+
+test('Theming.mdx component-var table matches silkComponentVarMeta', () => {
+  const source = readFileSync(themingMdx, 'utf8');
+  const start = source.indexOf('{/* COMPONENT_VAR_TABLE_START */}');
+  const end = source.indexOf('{/* COMPONENT_VAR_TABLE_END */}');
+  expect(start).toBeGreaterThanOrEqual(0);
+  expect(end).toBeGreaterThan(start);
+  const table = source
+    .slice(start, end)
+    .replace('{/* COMPONENT_VAR_TABLE_START */}', '')
+    .trim();
+  expect(table).toBe(formatComponentVarDocsTable());
+});
diff --git a/packages/silk/src/theme/index.ts b/packages/silk/src/theme/index.ts
index 6f8e0ce..3c77cb8 100644
--- a/packages/silk/src/theme/index.ts
+++ b/packages/silk/src/theme/index.ts
@@ -1,19 +1,39 @@
-export { createTheme } from '@reactive/silk-core';
+export {
+  checkThemeContrast,
+  contrastRatio,
+  createTheme,
+  generatePairedPalette,
+  generateScale,
+  relativeLuminance,
+} from '@reactive/silk-core';
 export type {
   ColorScheme,
+  ContrastViolation,
   CreateThemeOptions,
   DensityName,
   FontFamilyName,
+  GenerateScaleOptions,
+  PairedPalette,
+  PairedPaletteOptions,
   Palette,
   SemanticTokens,
   Theme,
+  ThemeContrastResult,
 } from '@reactive/silk-core';
 
 export { themeToCssVars } from './themeToCssVars';
 export type { CssVarMap } from './themeToCssVars';
 
-export { cssVars, silkComponentVarNames } from './componentVars';
-export type { SilkComponentVarName, SilkComponentVars } from './componentVars';
+export {
+  cssVars,
+  silkComponentVarMeta,
+  silkComponentVarNames,
+} from './componentVars';
+export type {
+  SilkComponentVarMeta,
+  SilkComponentVarName,
+  SilkComponentVars,
+} from './componentVars';
 
 export { ThemeProvider } from './ThemeProvider';
 export type { ThemeProviderProps } from './ThemeProvider';
diff --git a/packages/silk/src/theme/partitionCssVars.ts b/packages/silk/src/theme/partitionCssVars.ts
new file mode 100644
index 0000000..23d8f70
--- /dev/null
+++ b/packages/silk/src/theme/partitionCssVars.ts
@@ -0,0 +1,60 @@
+import type { CssVarMap } from './themeToCssVars';
+
+/**
+ * Theme-owned CSS variables — replaced when a nested provider sets `theme` or
+ * `colorScheme`. Inherited into portals only from the nearest scope that owns
+ * them (custom theme or explicit style semantic overrides).
+ */
+export function isThemeOwnedVar(name: string): boolean {
+  return (
+    name.startsWith('--silk-color-') ||
+    name.startsWith('--silk-space-comfortable-') ||
+    name.startsWith('--silk-space-compact-') ||
+    name.startsWith('--silk-radius-') ||
+    name.startsWith('--silk-font-') ||
+    name.startsWith('--silk-typography-') ||
+    name.startsWith('--silk-measure-') ||
+    name.startsWith('--silk-motion-') ||
+    name.startsWith('--silk-shadow-') ||
+    name.startsWith('--silk-focus-')
+  );
+}
+
+export function partitionCssVars(vars: CssVarMap | undefined): {
+  readonly semanticVars: CssVarMap | undefined;
+  readonly customVars: CssVarMap | undefined;
+} {
+  if (!vars) {
+    return { semanticVars: undefined, customVars: undefined };
+  }
+  const semantic: Record<`--silk-${string}`, string> = {};
+  const custom: Record<`--silk-${string}`, string> = {};
+  let hasSemantic = false;
+  let hasCustom = false;
+  for (const [key, value] of Object.entries(vars)) {
+    if (isThemeOwnedVar(key)) {
+      semantic[key as `--silk-${string}`] = value;
+      hasSemantic = true;
+    } else if (key.startsWith('--silk-')) {
+      custom[key as `--silk-${string}`] = value;
+      hasCustom = true;
+    }
+  }
+  return {
+    semanticVars: hasSemantic ? semantic : undefined,
+    customVars: hasCustom ? custom : undefined,
+  };
+}
+
+export function mergeCssVarMaps(
+  ...maps: Array<CssVarMap | undefined>
+): CssVarMap | undefined {
+  let merged: Record<`--silk-${string}`, string> | undefined;
+  for (const map of maps) {
+    if (!map) {
+      continue;
+    }
+    merged = { ...merged, ...map };
+  }
+  return merged;
+}
diff --git a/packages/silk/src/theme/themingAcceptance.test.tsx b/packages/silk/src/theme/themingAcceptance.test.tsx
index ce53aca..83968a2 100644
--- a/packages/silk/src/theme/themingAcceptance.test.tsx
+++ b/packages/silk/src/theme/themingAcceptance.test.tsx
@@ -1,4 +1,7 @@
-import { createTheme } from '@reactive/silk-core';
+import {
+  createTheme,
+  generatePairedPalette,
+} from '@reactive/silk-core';
 import { expect, test } from '@rstest/core';
 import { render, screen } from '@testing-library/react';
 import { Badge } from '../components/Badge';
@@ -87,6 +90,42 @@ test('Dialog portal reconstitutes theme for Stage 2 content', async () => {
 
   const input = await screen.findByLabelText('Portal input');
   expect(input).toBeTruthy();
-  const portalScope = input.closest('[data-theme="dark"]');
+  const portalScope = input.closest('[data-theme="dark"]') as HTMLElement | null;
   expect(portalScope).not.toBeNull();
+  expect(portalScope!.style.getPropertyValue('--silk-color-surface-raised')).toBe(
+    '#1a1a1a',
+  );
+});
+
+test('paired tenant themes side by side use inline vars only', () => {
+  const ocean = generatePairedPalette('#0ea5e9');
+  const ember = generatePairedPalette('#ea580c');
+  const oceanTheme = createTheme({
+    colorScheme: 'light',
+    palette: ocean.light,
+  });
+  const emberTheme = createTheme({
+    colorScheme: 'dark',
+    palette: ember.dark,
+  });
+
+  const before = document.querySelectorAll('style').length;
+  const { container } = render(
+    <>
+      <ThemeProvider theme={oceanTheme}>
+        <Button>Ocean</Button>
+      </ThemeProvider>
+      <ThemeProvider theme={emberTheme}>
+        <Button>Ember</Button>
+      </ThemeProvider>
+    </>,
+  );
+  const scopes = container.querySelectorAll('[data-theme]');
+  expect(scopes.length).toBe(2);
+  for (const scope of scopes) {
+    expect(
+      (scope as HTMLElement).style.getPropertyValue('--silk-color-surface'),
+    ).not.toBe('');
+  }
+  expect(document.querySelectorAll('style').length).toBe(before);
 });
diff --git a/yarn.lock b/yarn.lock
index 80cf194..bac3cc8 100644
--- a/yarn.lock
+++ b/yarn.lock
@@ -5357,6 +5357,8 @@ __metadata:
   resolution: "@reactive/silk-core@workspace:packages/silk-core"
   dependencies:
     "@rstest/core": "npm:^0.11.4"
+    "@types/culori": "npm:^4.0.1"
+    culori: "npm:^4.0.2"
     typescript: "npm:^7.0.2"
   languageName: unknown
   linkType: soft
@@ -6262,6 +6264,13 @@ __metadata:
   languageName: node
   linkType: hard
 
+"@types/culori@npm:^4.0.1":
+  version: 4.0.1
+  resolution: "@types/culori@npm:4.0.1"
+  checksum: 10c0/f25fcf01fe709d2fce569892eae71a268b19cf85a7c8f6bf6b041f02f232e5a7d1218e8213349d6b2a458be9f61158ed1e1893e7b81e2ee4a7cebc2a172b7ebb
+  languageName: node
+  linkType: hard
+
 "@types/debug@npm:^4.0.0":
   version: 4.1.13
   resolution: "@types/debug@npm:4.1.13"
@@ -8502,6 +8511,13 @@ __metadata:
   languageName: node
   linkType: hard
 
+"culori@npm:^4.0.2":
+  version: 4.0.2
+  resolution: "culori@npm:4.0.2"
+  checksum: 10c0/5d3c952b947ac5915409bab513e1d2e8bd813caa491af8ded0c769fdc1186a5ff61fb3c59fc8edf5393237d92074dbc54a492e6e99cb039dd6535d5d96106bfe
+  languageName: node
+  linkType: hard
+
 "cwd@npm:^0.10.0":
   version: 0.10.0
   resolution: "cwd@npm:0.10.0"

From 3e3bcf642e6166541db22130492d4126bd626a55 Mon Sep 17 00:00:00 2001
From: Nathaniel Tucker <me@ntucker.me>
Date: Sun, 26 Jul 2026 17:56:39 -0400
Subject: [PATCH 2/2] Simplify theming hot paths and contrast diagnostics.

Co-authored-by: Cursor <cursoragent@cursor.com>
---
 apps/docs/src/theme/ThemePlayground.tsx       | 28 +++--------
 .../src/theme/checkThemeContrast.test.ts      | 19 ++++++++
 .../silk-core/src/theme/checkThemeContrast.ts | 47 ++++++++-----------
 packages/silk-core/src/theme/oklchUtil.ts     | 31 +++++-------
 packages/silk/src/theme/partitionCssVars.ts   |  2 +-
 5 files changed, 58 insertions(+), 69 deletions(-)

diff --git a/apps/docs/src/theme/ThemePlayground.tsx b/apps/docs/src/theme/ThemePlayground.tsx
index 0557864..d5eb9b2 100644
--- a/apps/docs/src/theme/ThemePlayground.tsx
+++ b/apps/docs/src/theme/ThemePlayground.tsx
@@ -9,7 +9,6 @@ import {
   checkThemeContrast,
   createTheme,
   generatePairedPalette,
-  type PairedPalette,
   type Theme,
 } from '@reactive/silk';
 import { parseCanonicalHex } from '@reactive/silk-core';
@@ -32,32 +31,17 @@ export interface ThemePlaygroundControls {
 const DEFAULT_BRAND = '#0ea5e9';
 const DEFAULT_SCHEME = 'light' as const;
 
-const pairedCache = new Map<string, PairedPalette>();
-
-function pairedFor(brandSeed: string): PairedPalette | null {
-  const seed = parseCanonicalHex(brandSeed);
-  if (!seed) {
-    return null;
-  }
-  const cached = pairedCache.get(seed);
-  if (cached) {
-    return cached;
-  }
-  const paired = generatePairedPalette(seed);
-  pairedCache.set(seed, paired);
-  return paired;
-}
-
 function buildTheme(
   brandSeed: string,
   colorScheme: 'light' | 'dark',
   surface: string | undefined,
   radiusMd: number | undefined,
 ): Theme | null {
-  const paired = pairedFor(brandSeed);
-  if (!paired) {
+  const seed = parseCanonicalHex(brandSeed);
+  if (!seed) {
     return null;
   }
+  const paired = generatePairedPalette(seed);
   const surfaceHex =
     surface !== undefined ? parseCanonicalHex(surface) : undefined;
   return createTheme({
@@ -71,8 +55,8 @@ function buildTheme(
 }
 
 /**
- * Live theme playground — debounces control changes, caches paired palettes by
- * brand seed, and holds the last valid theme while the seed is mid-edit.
+ * Live theme playground — debounces control changes and holds the last valid
+ * theme while the seed is mid-edit.
  */
 export function ThemePlayground({
   brandSeed = DEFAULT_BRAND,
@@ -100,7 +84,7 @@ export function ThemePlayground({
     return () => window.clearTimeout(id);
   }, [brandSeed, colorScheme, surface, radiusMd]);
 
-  const holding = pairedFor(brandSeed) === null;
+  const holding = parseCanonicalHex(brandSeed) === null;
   const contrast = useMemo(() => checkThemeContrast(theme), [theme]);
 
   return (
diff --git a/packages/silk-core/src/theme/checkThemeContrast.test.ts b/packages/silk-core/src/theme/checkThemeContrast.test.ts
index 75b4cca..c961587 100644
--- a/packages/silk-core/src/theme/checkThemeContrast.test.ts
+++ b/packages/silk-core/src/theme/checkThemeContrast.test.ts
@@ -67,6 +67,25 @@ test('identical primary/secondary text fails distinctness', () => {
   ).toBe(true);
 });
 
+test('chromatic text reports each surface contrast failure once', () => {
+  const theme = createTheme({
+    semantic: {
+      color: {
+        surface: '#ffffff',
+        tones: { accent: { text: '#ffffff' } },
+      },
+    },
+  });
+  const result = checkThemeContrast(theme);
+  const pageSurfaceFailures = result.violations.filter(
+    (violation) =>
+      violation.kind === 'contrast' &&
+      violation.pathFg === 'color.tones.accent.text' &&
+      violation.pathBg === 'color.surface',
+  );
+  expect(pageSurfaceFailures).toHaveLength(1);
+});
+
 test('contrastRatio and relativeLuminance are hex-only', () => {
   expect(relativeLuminance('#ffffff')).toBeCloseTo(1, 5);
   expect(relativeLuminance('rgb(255,255,255)')).toBeNull();
diff --git a/packages/silk-core/src/theme/checkThemeContrast.ts b/packages/silk-core/src/theme/checkThemeContrast.ts
index a497f63..58d01b2 100644
--- a/packages/silk-core/src/theme/checkThemeContrast.ts
+++ b/packages/silk-core/src/theme/checkThemeContrast.ts
@@ -256,33 +256,26 @@ export function checkThemeContrast(theme: Theme): ThemeContrastResult {
       );
     }
 
-    assertContrast(
-      violations,
-      seenUnsupported,
-      `${base}.text`,
-      t.text,
-      'color.surface',
-      color.surface,
-      4.5,
-      'Tone text on page surface must meet WCAG AA 4.5:1',
-    );
-
-    if (tone !== 'neutral') {
-      for (const [path, surface] of [
-        ['color.surface', color.surface],
-        ['color.surfaceRaised', color.surfaceRaised],
-      ] as const) {
-        assertContrast(
-          violations,
-          seenUnsupported,
-          `${base}.text`,
-          t.text,
-          path,
-          surface,
-          4.5,
-          'Chromatic tone text on raised/flat surfaces must meet WCAG AA 4.5:1',
-        );
-      }
+    const toneTextSurfaces =
+      tone === 'neutral'
+        ? ([['color.surface', color.surface]] as const)
+        : ([
+            ['color.surface', color.surface],
+            ['color.surfaceRaised', color.surfaceRaised],
+          ] as const);
+    for (const [path, surface] of toneTextSurfaces) {
+      assertContrast(
+        violations,
+        seenUnsupported,
+        `${base}.text`,
+        t.text,
+        path,
+        surface,
+        4.5,
+        tone === 'neutral'
+          ? 'Tone text on page surface must meet WCAG AA 4.5:1'
+          : 'Chromatic tone text on raised/flat surfaces must meet WCAG AA 4.5:1',
+      );
     }
 
     for (const [path, surface] of surfaces) {
diff --git a/packages/silk-core/src/theme/oklchUtil.ts b/packages/silk-core/src/theme/oklchUtil.ts
index 0ccf43c..5a55b52 100644
--- a/packages/silk-core/src/theme/oklchUtil.ts
+++ b/packages/silk-core/src/theme/oklchUtil.ts
@@ -1,5 +1,5 @@
 import { clampChroma, formatHex, oklch, type Oklch } from 'culori';
-import { contrastRatio, relativeLuminance } from './colorMath.js';
+import { contrastRatio } from './colorMath.js';
 
 export function oklchAt(l: number, c: number, h: number): Oklch {
   return { mode: 'oklch', l, c, h };
@@ -19,7 +19,6 @@ export function oklchChannelsToHex(l: number, c: number, h: number): string {
 
 /**
  * Walk lightness until contrast vs `against` clears `threshold`.
- * Caches the against-side luminance so each step only measures the candidate.
  */
 export function nudgeLUntil(
   hex: string,
@@ -37,7 +36,6 @@ export function nudgeLUntil(
   if (!current) {
     return hex;
   }
-  const againstL = relativeLuminance(against);
   const delta = options.delta ?? 0.015;
   const minL = options.minL ?? 0.15;
   const maxL = options.maxL ?? 0.92;
@@ -45,24 +43,19 @@ export function nudgeLUntil(
 
   for (let i = 0; i < maxIters; i += 1) {
     const candidate = oklchToHex(current);
-    const candidateL = relativeLuminance(candidate);
-    if (candidateL != null && againstL != null) {
-      const lighter = Math.max(candidateL, againstL);
-      const darker = Math.min(candidateL, againstL);
-      if ((lighter + 0.05) / (darker + 0.05) >= threshold) {
-        return candidate;
-      }
-    } else {
-      const ratio = contrastRatio(candidate, against);
-      if (ratio != null && ratio >= threshold) {
-        return candidate;
-      }
+    const ratio = contrastRatio(candidate, against);
+    if (ratio != null && ratio >= threshold) {
+      return candidate;
     }
-    current = oklchAt(
-      Math.min(maxL, Math.max(minL, (current.l ?? 0.5) + options.direction * delta)),
-      current.c ?? 0,
-      current.h ?? 0,
+    const currentL = current.l ?? 0.5;
+    const nextL = Math.min(
+      maxL,
+      Math.max(minL, currentL + options.direction * delta),
     );
+    if (nextL === currentL) {
+      return candidate;
+    }
+    current = oklchAt(nextL, current.c ?? 0, current.h ?? 0);
   }
   return oklchToHex(current);
 }
diff --git a/packages/silk/src/theme/partitionCssVars.ts b/packages/silk/src/theme/partitionCssVars.ts
index 23d8f70..a0a94c7 100644
--- a/packages/silk/src/theme/partitionCssVars.ts
+++ b/packages/silk/src/theme/partitionCssVars.ts
@@ -54,7 +54,7 @@ export function mergeCssVarMaps(
     if (!map) {
       continue;
     }
-    merged = { ...merged, ...map };
+    merged = merged === undefined ? map : { ...merged, ...map };
   }
   return merged;
 }