haze-ui 1.28.0 → 1.30.0

package/README.md

@@ -35,6 +35,24 @@ English | [简体中文](./README-zh_CN.md)
 
 ## Getting Started
 
+### Quickstart via create-haze-ui
+
+Scaffold a ready-to-run app with the official templates — the CLI has zero
+runtime dependencies and needs no network access beyond dependency install:
+
+```sh
+pnpm create haze-ui my-app                    # vite template (default)
+pnpm create haze-ui my-app --template nextjs  # or: npm create haze-ui@latest my-app --
+```
+
+The **vite** template is a React 19 + Vite + TypeScript single-page demo
+(`Button` / `Input` / `Dialog` / `Toast`) with the theme classes mounted on
+the page root; the **nextjs** template is a Next.js 15 App Router starter
+whose home page renders the RSC-safe static subset (`Badge` / `Card` /
+`Typography`) as a server component, with a client island for the
+interactive pieces. Prefer wiring an existing project by hand? Continue
+with Installation below.
+
 ### Installation
 
 ```sh
@@ -129,30 +147,30 @@ checklist:
 
 ### Dependencies
 
-haze-ui ships two runtime dependencies — `react-use-control`, the engine
-behind `ControlOrValue<T>`, and `react-f0rm` (^1.3), the form engine
-behind `FormItem`/`FormList` (the same author's headless form store).
-Five integrations remain optional peers, installed only when you use the
-components that need them:
-
-```sh
-npm i @tanstack/react-table               # DataTable (peer range ^9.2.4)
-npm i recharts                            # Chart (peer range ^3.10.1)
-npm i @dnd-kit/core @dnd-kit/sortable \
-      @dnd-kit/utilities                  # TagInput/TagGroup sortable
-                                           # (^6.3.1 / ^10.0.0 / ^3.2.2)
-```
-
-Everything else — `Button`, `Input`, `Dialog`, `Select`, … — runs with
-nothing beyond `react` and the two runtime dependencies. The dist is ESM
-with `preserveModules` and side-effect-free JS, so bundlers (Next.js,
-Vite, webpack, Turbopack, Rollup) tree-shake the unused re-export chains
-and never resolve peers you haven't installed: `import { Button } from
-'haze-ui'` works without `@tanstack/react-table`. Only bundler-less
-consumers (bare Node ESM importing the barrel, which links the module
-graph eagerly) must install the optional peers; the
-`haze-ui/components/DataTable` and `haze-ui/components/Chart` subpaths
-bypass the barrel entirely.
+haze-ui declares only the host environment as peers: `react` and
+`react-dom` (^19). Everything else is a regular dependency — one
+`npm i haze-ui` and every component works:
+
+- `react-use-control` — the engine behind `ControlOrValue<T>`
+- `react-f0rm` (^1.3) — the form engine behind `FormItem`/`FormList`
+  (the same author's headless form store)
+- `@tanstack/react-table` — DataTable
+- `recharts` — Chart
+- `@dnd-kit/core` / `@dnd-kit/sortable` / `@dnd-kit/utilities` — the
+  sortable TagInput/TagGroup variants
+- `qrcode` — QRCode
+
+Swapping any of these engines for another library is invisible to your
+code (the one deliberate exception: DataTable's column API exposes
+TanStack's `ColumnDef` types). The dist is ESM with `preserveModules`
+and side-effect-free JS, and engines are imported only by the components
+that need them, so bundlers (Next.js, Vite, webpack, Turbopack, Rollup)
+tree-shake the unused re-export chains: `import { Button } from
+'haze-ui'` never pulls `@tanstack/react-table` into the bundle. Engines
+install as regular dependencies, so even bundler-less consumers (bare
+Node ESM importing the barrel, which links the module graph eagerly)
+work with zero manual installs; the `haze-ui/components/DataTable` and
+`haze-ui/components/Chart` subpaths bypass the barrel entirely.
 
 ### Browser support
 
@@ -393,16 +411,18 @@ user-controllable, SSR/jsdom-safe when the underlying API is missing.
 | `useTitle(title)` | — | Document title while mounted |
 | `useToast()` | toast API | Requires a `ToastContainer` ancestor |
 
-## Sortable tags and chips (optional dnd-kit peers)
+## Sortable tags and chips
 
-`TagInput` and `TagGroup` accept `sortable?: boolean` — opt-in drag
-reordering powered by `@dnd-kit/core` / `@dnd-kit/sortable` /
-`@dnd-kit/utilities` (optional peers, same tree-shaking contract as
-recharts and TanStack Table). `TagInput` writes the new array through
-`onChange`; `TagGroup` reports `onReorder(nextOrder)` (the new
-arrangement of original child indexes) and leaves re-rendering to the
-parent. Sorting is keyboard-complete: focus a tag, `Space` to lift,
-arrows to move, `Space` to drop, `Escape` to cancel.
+Drag reordering is an opt-in variant: `SortableTagInput` /
+`SortableTagInputCore` and `SortableTagGroup` statically import
+`@dnd-kit/core` / `@dnd-kit/sortable` / `@dnd-kit/utilities` (regular
+dependencies — the plain `TagInput`/`TagGroup` never touch them, so they
+stay out of every bundle that doesn't import a Sortable variant).
+`SortableTagInput` writes the new array through `onChange`;
+`SortableTagGroup` reports `onReorder(nextOrder)` (the new arrangement of
+original child indexes) and leaves re-rendering to the parent. Sorting is
+keyboard-complete: focus a tag, `Space` to lift, arrows to move, `Space`
+to drop, `Escape` to cancel.
 
 ## Imperative overlay handles
 
@@ -456,6 +476,46 @@ not wrapped.
 }
 ```
 
+## Brand themes: presets, runtime generation, CLI
+
+Five preset brand themes ship as complete theme classes — `violetTheme`,
+`tealTheme`, `cyanTheme`, `orangeTheme`, `roseTheme` — each a drop-in
+replacement for `lightTheme`/`darkTheme` with primary/info/focus-ring
+rerouted to the brand's scale.
+
+**Runtime custom brands.** `createBrandTheme` (from `haze-ui` or
+`haze-ui/tokens`) runs the exact preset pipeline from your own seed hex:
+
+```ts
+import { createBrandTheme } from 'haze-ui/tokens';
+
+const brand = createBrandTheme({
+  name: 'acme',       // → --haze-acme-1…12 (lowercase kebab; not gray/green/amber/red)
+  light: '#0066ff',   // light-mode primary seed (scale step 9)
+  dark: '#0a3d99',    // optional — derived from light (oklch l +0.2) when omitted
+  overrides: { light: { 10: '#0052cc' } },  // optional extra anchors
+});
+// brand.light / brand.dark: bare declaration blocks — wrap in classes once:
+// styleEl.textContent = `.acme-light { ${brand.light} }\n.acme-dark { ${brand.dark} }`;
+```
+
+The blocks are theme *replacements* (never stack on `lightTheme`), and you
+own contrast: pick a light seed dark enough for white text — the presets'
+step-9 anchors sit near Tailwind's 600/700 range for that reason.
+
+**CLI.** Zero Node dependencies, identical output:
+
+```bash
+npx haze-ui-theme --primary '#0066ff' [--dark '#0a3d99'] [--name brand] [--out brand.css]
+```
+
+**W3C design-token archives.** Every preset is also exported per mode as
+W3C DTF JSON:
+
+```js
+import violetLight from 'haze-ui/design-tokens/violet/light.json';
+```
+
 ## Component-level tokens
 
 Global `--haze-*` tokens theme the whole system; **component-level tokens**
@@ -544,6 +604,52 @@ own css manifest. The same items are also installable straight from this
 GitHub repository — see
 [Install via shadcn CLI (GitHub registry)](#install-via-shadcn-cli-github-registry).
 
+## AI / MCP
+
+**`haze-ui-mcp`** — an [MCP server](https://modelcontextprotocol.io) that puts the
+whole component reference in your AI coding agent's tool belt. It serves the
+same docs the site renders (props tables with types/defaults/descriptions,
+import statements, CSS paths, peer deps, the full token registry), so the
+agent never guesses a prop name or a stylesheet path again:
+
+| Tool | What it returns |
+| --- | --- |
+| `haze_list_components` | Every component with its css family |
+| `haze_get_component` | One component's full reference — props tables, import statement, CSS imports. Name matching is case-insensitive and accepts kebab-case (`data-table`) or PascalCase (`DataTable`) |
+| `haze_get_tokens` | The `--haze-*` token registry with light and dark values, optionally filtered by category (`color`, `typography`, `spacing`, `radius`, `shadow`) |
+| `haze_search_docs` | Top-10 ranked matches across component names, css families, prop names and descriptions |
+
+**Claude Code**:
+
+```sh
+claude mcp add haze-ui -- npx haze-ui-mcp
+```
+
+**Cursor** (`.cursor/mcp.json`):
+
+```json
+{
+  "mcpServers": {
+    "haze-ui": {
+      "command": "npx",
+      "args": ["haze-ui-mcp"]
+    }
+  }
+}
+```
+
+The server speaks stdio JSON-RPC and ships its own docs snapshot
+(`dist/mcp-docs.json`, regenerated on every build by
+`scripts/generate-mcp-docs.mjs`) — no project access, no indexing on startup.
+In this repository you can run it directly against the local snapshot:
+
+```sh
+node scripts/generate-mcp-docs.mjs
+node mcp/index.mjs
+```
+
+Point it at a custom snapshot with `HAZE_UI_MCP_DOCS=/path/to/mcp-docs.json`.
+
 ## AI runtime integration (Vercel AI SDK `useChat`)
 
 haze-ui ships the agent chat surface as **presentational** components —

package/cli/theme.mjs

@@ -0,0 +1,446 @@
+#!/usr/bin/env node
+/**
+ * haze-ui-theme — generate a complete haze-ui brand theme CSS file from one
+ * or two seed hexes, no Node dependencies.
+ *
+ *   node cli/theme.mjs --primary '#0066ff' [--dark '#0a3d99'] [--name brand] [--out brand.css]
+ *   npx haze-ui-theme --primary '#7c3aed' --name acme
+ *
+ * The emitted classes (.haze-{name}-light / .haze-{name}-dark) are theme
+ * REPLACEMENTS for lightTheme/darkTheme — apply one per subtree, never stack
+ * on top of the default theme classes.
+ *
+ * The color math below is a dependency-free port of src/lib/tokens/oklch.ts
+ * + the scale/semantic pipeline of src/lib/tokens/palette.ts (the library
+ * source cannot be imported here: this file must also run from an
+ * as-yet-unbuilt checkout, and dist/ is not guaranteed to exist). Drift is
+ * pinned by src/lib/tokens/brand-theme.test.ts, which asserts this module's
+ * output is byte-identical to createBrandTheme() for every preset seed set.
+ */
+
+// ---------------------------------------------------------------------------
+// OKLCH math — ported from src/lib/tokens/oklch.ts
+// ---------------------------------------------------------------------------
+
+const SRGB_LINEAR_CUTOFF = 0.04045;
+const LINEAR_SRGB_CUTOFF = 0.0031308;
+const GAMUT_EPSILON = 1e-5;
+
+const srgbToLinear = (channel) =>
+  channel <= SRGB_LINEAR_CUTOFF ? channel / 12.92 : Math.pow((channel + 0.055) / 1.055, 2.4);
+
+const linearToSrgb = (channel) =>
+  channel <= LINEAR_SRGB_CUTOFF ? 12.92 * channel : 1.055 * Math.pow(channel, 1 / 2.4) - 0.055;
+
+function linearRgbToOklab({r, g, b}) {
+  const l = Math.cbrt(0.4122214708 * r + 0.5363325363 * g + 0.0514459929 * b);
+  const m = Math.cbrt(0.2119034982 * r + 0.6806995451 * g + 0.1073969566 * b);
+  const s = Math.cbrt(0.0883024619 * r + 0.2817188376 * g + 0.6299787005 * b);
+  return {
+    L: 0.2104542553 * l + 0.793617785 * m - 0.0040720468 * s,
+    a: 1.9779984951 * l - 2.428592205 * m + 0.4505937099 * s,
+    b: 0.0259040371 * l + 0.7827717662 * m - 0.808675766 * s,
+  };
+}
+
+function oklabToLinearRgb({L, a, b}) {
+  const l_ = L + 0.3963377774 * a + 0.2158037573 * b;
+  const m_ = L - 0.1055613458 * a - 0.0638541728 * b;
+  const s_ = L - 0.0894841775 * a - 1.291485548 * b;
+  const l = l_ * l_ * l_;
+  const m = m_ * m_ * m_;
+  const s = s_ * s_ * s_;
+  return {
+    r: 4.0767416621 * l - 3.3077115913 * m + 0.2309699292 * s,
+    g: -1.2684380046 * l + 2.6097574011 * m - 0.3413193965 * s,
+    b: -0.0041960863 * l - 0.7034186147 * m + 1.707614701 * s,
+  };
+}
+
+const lchToLab = ({l, c, h}) => {
+  const hue = (h * Math.PI) / 180;
+  return {L: l, a: c * Math.cos(hue), b: c * Math.sin(hue)};
+};
+
+const labToLch = ({L, a, b}) => {
+  const hue = (Math.atan2(b, a) * 180) / Math.PI;
+  return {l: L, c: Math.sqrt(a * a + b * b), h: hue < 0 ? hue + 360 : hue};
+};
+
+const inGamut = (rgb) =>
+  rgb.r >= -GAMUT_EPSILON && rgb.r <= 1 + GAMUT_EPSILON &&
+  rgb.g >= -GAMUT_EPSILON && rgb.g <= 1 + GAMUT_EPSILON &&
+  rgb.b >= -GAMUT_EPSILON && rgb.b <= 1 + GAMUT_EPSILON;
+
+/** Reduce chroma until the color fits the sRGB gamut, preserving lightness and hue exactly. */
+function clampChroma(color) {
+  const l = Math.min(1, Math.max(0, color.l));
+  const hue = (color.h * Math.PI) / 180;
+  let low = 0;
+  let high = Math.max(color.c, 0);
+  for (let i = 0; i < 20; i++) {
+    const mid = (low + high) / 2;
+    if (inGamut(oklabToLinearRgb({L: l, a: mid * Math.cos(hue), b: mid * Math.sin(hue)}))) {
+      low = mid;
+    } else {
+      high = mid;
+    }
+  }
+  return color.alpha === undefined ? {l, c: low, h: color.h} : {l, c: low, h: color.h, alpha: color.alpha};
+}
+
+/** Parse `#rgb`, `#rgba`, `#rrggbb` or `#rrggbbaa` into OKLCH. */
+function parseHex(hex) {
+  const match = /^#([0-9a-f]{3,8})$/i.exec(hex.trim());
+  const digits = match?.[1];
+  if (digits === undefined || (digits.length !== 3 && digits.length !== 4 && digits.length !== 6 && digits.length !== 8)) {
+    throw new Error(`Invalid hex color: ${hex}`);
+  }
+  const expanded =
+    digits.length === 3 || digits.length === 4 ? digits.split('').map((d) => d + d).join('') : digits;
+  const alpha = expanded.length === 8 ? parseInt(expanded.slice(6, 8), 16) / 255 : undefined;
+  const lch = labToLch(
+    linearRgbToOklab({
+      r: srgbToLinear(parseInt(expanded.slice(0, 2), 16) / 255),
+      g: srgbToLinear(parseInt(expanded.slice(2, 4), 16) / 255),
+      b: srgbToLinear(parseInt(expanded.slice(4, 6), 16) / 255),
+    }),
+  );
+  return alpha === undefined ? lch : {...lch, alpha};
+}
+
+/** Format as a CSS `oklch()` string: l/c to 3 decimals, h to 1 decimal. */
+const formatOklch = (color) =>
+  `oklch(${color.l.toFixed(3)} ${color.c.toFixed(3)} ${color.h.toFixed(1)})`;
+
+// ---------------------------------------------------------------------------
+// Palette pipeline — ported from src/lib/tokens/palette.ts
+// ---------------------------------------------------------------------------
+
+const MODES = ['light', 'dark'];
+
+/** Gray seeds and the text-muted nudge — mirror of SEEDS.gray / TEXT_MUTED_ADJUST. */
+const GRAY_SEEDS = {
+  light: {1: '#ffffff', 2: '#f7f8fa', 3: '#eef0f4', 4: '#e0e0e0', 9: '#8a8a8a', 11: '#4a4a4a', 12: '#1a1a1a'},
+  dark: {1: '#121212', 2: '#1e1e1e', 3: '#2a2a2a', 4: '#333333', 9: '#707070', 11: '#b0b0b0', 12: '#e8e8e8'},
+};
+/** Success/warning/danger seeds — mirror of SEEDS.green/amber/red (fixed in every theme). */
+const STATUS_SEEDS = {
+  green: {light: {9: '#15803d'}, dark: {8: '#22c55e'}},
+  amber: {light: {9: '#f59e0b'}, dark: {8: '#fbbf24'}},
+  red: {light: {9: '#dc2626'}, dark: {8: '#ef4444'}},
+};
+const TEXT_MUTED_ADJUST = {light: -0.008, dark: 0.014};
+
+const CHROMATIC_ENDPOINTS = {
+  light: {l1: 0.982, l12: 0.16, c1: 0.018, c12: 0.045},
+  dark: {l1: 0.155, l12: 0.982, c1: 0.03, c12: 0.012},
+};
+
+/** Piecewise-linear interpolation over sorted points (clamped at both ends). */
+function interpolateAt(points, x) {
+  const first = points[0];
+  if (x <= first.x) return first.y;
+  for (let i = 1; i < points.length; i++) {
+    const point = points[i];
+    if (x <= point.x) {
+      const previous = points[i - 1];
+      const t = (x - previous.x) / (point.x - previous.x);
+      return previous.y + t * (point.y - previous.y);
+    }
+  }
+  return points[points.length - 1].y;
+}
+
+function formatSteps(luminancePoints, chromaAt, hueAt) {
+  const steps = [];
+  for (let step = 1; step <= 12; step++) {
+    steps.push(formatOklch(clampChroma({l: interpolateAt(luminancePoints, step), c: chromaAt(step), h: hueAt(step)})));
+  }
+  return steps;
+}
+
+function grayAnchors(seed, mode) {
+  return Object.entries(seed)
+    .map(([step, hex]) => {
+      const parsed = parseHex(hex);
+      const l = Number(step) === 9 ? parsed.l + TEXT_MUTED_ADJUST[mode] : parsed.l;
+      return {step: Number(step), color: {l, c: 0, h: 0}};
+    })
+    .sort((a, b) => a.step - b.step);
+}
+
+/** The fixed neutral scales — identical to the default themes' gray family. */
+const GRAY_SCALE = Object.fromEntries(
+  MODES.map((mode) => [
+    mode,
+    formatSteps(grayAnchors(GRAY_SEEDS[mode], mode).map((a) => ({x: a.step, y: a.color.l})), () => 0, () => 0),
+  ]),
+);
+
+/** The fixed success/warning/danger scales — identical to the default themes'. */
+const STATUS_SCALE = Object.fromEntries(
+  ['green', 'amber', 'red'].map((family) => [
+    family,
+    Object.fromEntries(
+      MODES.map((mode) => [
+        mode,
+        chromaticScaleFromAnchors(
+          Object.entries(STATUS_SEEDS[family][mode]).map(([step, hex]) => ({step: Number(step), color: parseHex(hex)})),
+          mode,
+        ),
+      ]),
+    ),
+  ]),
+);
+
+function chromaticScaleFromAnchors(anchors, mode) {
+  const endpoints = CHROMATIC_ENDPOINTS[mode];
+  const luminancePoints = [{x: 1, y: endpoints.l1}, ...anchors.map((a) => ({x: a.step, y: a.color.l})), {x: 12, y: endpoints.l12}];
+  const chromaPoints = [{x: 1, y: endpoints.c1}, ...anchors.map((a) => ({x: a.step, y: a.color.c})), {x: 12, y: endpoints.c12}];
+  const huePoints = [
+    {x: 1, y: anchors[0].color.h},
+    ...anchors.map((a) => ({x: a.step, y: a.color.h})),
+    {x: 12, y: anchors[anchors.length - 1].color.h},
+  ];
+  return formatSteps(luminancePoints, (step) => interpolateAt(chromaPoints, step), (step) => interpolateAt(huePoints, step));
+}
+
+// Semantic rerouting — mirror of DEFAULT_STATUS_FAMILY / STATUS_STEP / NEUTRAL_STEP.
+const DEFAULT_STATUS_FAMILY = {primary: 'blue', success: 'green', warning: 'amber', danger: 'red', info: 'blue'};
+const STATUS_STEP = {
+  light: {primary: 9, success: 9, warning: 9, danger: 9, info: 10},
+  dark: {primary: 9, success: 8, warning: 8, danger: 8, info: 8},
+};
+const NEUTRAL_STEP = {
+  bg: 1,
+  'bg-subtle': 2,
+  'bg-muted': 3,
+  text: 12,
+  'text-secondary': 11,
+  'text-muted': 9,
+  border: 4,
+};
+
+// Interaction-state parameters — mirror of DERIVED_PARAMS / FOCUS_RING_ALPHA.
+const DERIVED_PARAMS = {
+  light: {hover: -0.045, active: -0.09, borderHover: -0.09, subtleL: 0.945, subtleC: 0.2},
+  dark: {hover: 0.05, active: 0.09, borderHover: 0.08, subtleL: 0.26, subtleC: 0.35},
+};
+const FOCUS_RING_ALPHA = 0.4;
+
+const primitiveVar = (family, step) => `var(--haze-${family}-${step})`;
+const lightnessCalc = (delta) => `calc(l ${delta < 0 ? '-' : '+'} ${Math.abs(delta)})`;
+
+function derivedCss(mode, baseVar, kind) {
+  const params = DERIVED_PARAMS[mode];
+  switch (kind) {
+    case 'hover':
+      return `oklch(from ${baseVar} ${lightnessCalc(params.hover)} c h)`;
+    case 'active':
+      return `oklch(from ${baseVar} ${lightnessCalc(params.active)} c h)`;
+    case 'subtle':
+      return `oklch(from ${baseVar} ${params.subtleL} calc(c * ${params.subtleC}) h)`;
+    case 'border-hover':
+      return `oklch(from ${baseVar} ${lightnessCalc(params.borderHover)} c h)`;
+    case 'focus-ring':
+      return `oklch(from ${baseVar} l c h / ${FOCUS_RING_ALPHA})`;
+  }
+}
+
+/**
+ * The full declaration block one mode of a brand theme carries: primitive
+ * scales first (gray/{name}/green/amber/red), then the semantic aliases
+ * with primary/info/focus-ring rerouted to the brand family.
+ */
+function themeDeclarations(mode, name, brandScale) {
+  const primitives = [
+    ['gray', GRAY_SCALE[mode]],
+    [name, brandScale],
+    ['green', STATUS_SCALE.green[mode]],
+    ['amber', STATUS_SCALE.amber[mode]],
+    ['red', STATUS_SCALE.red[mode]],
+  ]
+    .map(([family, steps]) => steps.map((value, index) => `--haze-${family}-${index + 1}: ${value};`).join('\n'))
+    .join('\n');
+  const statusFamily = {...DEFAULT_STATUS_FAMILY, primary: name, info: name};
+  const lines = [];
+  const statusGroup = (key) => {
+    const base = `--haze-color-${key}`;
+    const family = statusFamily[key];
+    lines.push(`${base}: ${primitiveVar(family, STATUS_STEP[mode][key])};`);
+    const baseVar = `var(${base})`;
+    lines.push(`${base}-hover: ${derivedCss(mode, baseVar, 'hover')};`);
+    lines.push(`${base}-active: ${derivedCss(mode, baseVar, 'active')};`);
+    lines.push(`${base}-subtle: ${derivedCss(mode, baseVar, 'subtle')};`);
+  };
+  const neutral = (key) => lines.push(`--haze-color-${key}: ${primitiveVar('gray', NEUTRAL_STEP[key])};`);
+  statusGroup('primary');
+  neutral('bg');
+  neutral('bg-subtle');
+  neutral('bg-muted');
+  neutral('text');
+  neutral('text-secondary');
+  neutral('text-muted');
+  lines.push(`--haze-color-text-inverse: ${mode === 'light' ? 'oklch(1 0 0)' : GRAY_SCALE.light[11]};`);
+  neutral('border');
+  lines.push(`--haze-color-border-hover: ${derivedCss(mode, 'var(--haze-color-border)', 'border-hover')};`);
+  statusGroup('success');
+  statusGroup('warning');
+  statusGroup('danger');
+  statusGroup('info');
+  lines.push(`--haze-color-focus-ring: ${derivedCss(mode, 'var(--haze-color-primary)', 'focus-ring')};`);
+  return `${primitives}\n\n${lines.join('\n')}`;
+}
+
+// ---------------------------------------------------------------------------
+// createBrandTheme mirror — identical options/semantics to palette.ts
+// ---------------------------------------------------------------------------
+
+const NEUTRAL_FAMILIES = new Set(['gray', 'green', 'amber', 'red']);
+const FAMILY_NAME_RE = /^[a-z][a-z0-9-]*$/;
+const DERIVED_SEED_OFFSETS = {infoStep: -0.07, darkPrimary: 0.2};
+
+const clampLightness = (l) => Math.min(1, Math.max(0, l));
+const shiftLightness = (color, delta) => clampChroma({l: clampLightness(color.l + delta), c: color.c, h: color.h});
+
+function mergeAnchors(base, seed) {
+  const byStep = new Map(base.map((anchor) => [anchor.step, anchor.color]));
+  for (const [step, hex] of Object.entries(seed ?? {})) {
+    if (Number(step) < 1 || Number(step) > 12) {
+      throw new Error(`Seed anchor step ${step} is outside the 1–12 scale`);
+    }
+    byStep.set(Number(step), parseHex(hex));
+  }
+  return [...byStep.entries()].map(([step, color]) => ({step, color})).sort((a, b) => a.step - b.step);
+}
+
+/**
+ * Build a complete brand theme at runtime — mirror of palette.ts's
+ * createBrandTheme (byte-identical output; enforced by brand-theme.test.ts).
+ *
+ * @param {{name?: string, light: string, dark?: string, overrides?: {light?: Record<number, string>, dark?: Record<number, string>}}} options
+ * @returns {{name: string, light: string, dark: string}} bare declaration blocks per mode
+ */
+export function createBrandThemeCss({name = 'brand', light, dark, overrides} = {}) {
+  if (!FAMILY_NAME_RE.test(name)) {
+    throw new Error(`Invalid brand name "${name}" — use a lowercase kebab identifier (letters, digits, hyphens)`);
+  }
+  if (NEUTRAL_FAMILIES.has(name)) {
+    throw new Error(`Brand name "${name}" collides with a fixed neutral family (gray/green/amber/red)`);
+  }
+  const lightPrimary = parseHex(light);
+  const darkPrimary = dark === undefined ? shiftLightness(lightPrimary, DERIVED_SEED_OFFSETS.darkPrimary) : parseHex(dark);
+  const anchors = {
+    light: mergeAnchors(
+      [
+        {step: 9, color: lightPrimary},
+        {step: 10, color: shiftLightness(lightPrimary, DERIVED_SEED_OFFSETS.infoStep)},
+      ],
+      overrides?.light,
+    ),
+    dark: mergeAnchors(
+      [
+        {step: 9, color: darkPrimary},
+        {step: 8, color: shiftLightness(darkPrimary, DERIVED_SEED_OFFSETS.infoStep)},
+      ],
+      overrides?.dark,
+    ),
+  };
+  return {
+    name,
+    light: themeDeclarations('light', name, chromaticScaleFromAnchors(anchors.light, 'light')),
+    dark: themeDeclarations('dark', name, chromaticScaleFromAnchors(anchors.dark, 'dark')),
+  };
+}
+
+/** Wrap the two declaration blocks into a standalone stylesheet. */
+export function renderStylesheet(theme, {lightSeed, darkSeed}) {
+  const header = [
+    `/* haze-ui brand theme "${theme.name}" — generated by haze-ui-theme.`,
+    `   light seed: ${lightSeed} · dark seed: ${darkSeed}`,
+    '   Apply ONE class per subtree as a replacement for lightTheme/darkTheme. */',
+  ].join('\n');
+  const block = (mode) => `.haze-${theme.name}-${mode} {\n${theme[mode]}\n}`;
+  return `${header}\n\n${block('light')}\n\n${block('dark')}\n`;
+}
+
+// ---------------------------------------------------------------------------
+// CLI entry
+// ---------------------------------------------------------------------------
+
+import {writeFileSync} from 'node:fs';
+import {pathToFileURL} from 'node:url';
+
+const USAGE = `Usage: haze-ui-theme --primary <hex> [--dark <hex>] [--name <kebab>] [--out <file>]
+
+  --primary <hex>   Light-mode primary seed, e.g. '#0066ff' (required).
+  --dark <hex>      Dark-mode primary seed. Omit to derive it from --primary
+                    (OKLCH lightness +0.2, chroma/hue preserved).
+  --name <kebab>    Brand family name for the custom properties (default:
+                    'brand'). Becomes --haze-<name>-1…12; may not be
+                    gray/green/amber/red.
+  --out <file>      Write the stylesheet to <file> instead of stdout.
+
+Outputs .haze-<name>-light / .haze-<name>-dark classes carrying the complete
+token set (primitive scales + semantic aliases + relative-color interaction
+states) — use them as replacements for lightTheme/darkTheme.`;
+
+function parseArgs(argv) {
+  const options = {primary: undefined, dark: undefined, name: 'brand', out: undefined};
+  for (let i = 0; i < argv.length; i++) {
+    const arg = argv[i];
+    const flag = arg.includes('=') ? arg.slice(0, arg.indexOf('=')) : arg;
+    const inline = arg.includes('=') ? arg.slice(arg.indexOf('=') + 1) : undefined;
+    const value = inline ?? argv[++i];
+    if (flag === '--help' || flag === '-h') {
+      options.help = true;
+    } else if (flag === '--primary') {
+      options.primary = value;
+    } else if (flag === '--dark') {
+      options.dark = value;
+    } else if (flag === '--name') {
+      options.name = value;
+    } else if (flag === '--out') {
+      options.out = value;
+    } else {
+      throw new Error(`Unknown argument: ${arg}\n\n${USAGE}`);
+    }
+    if (value === undefined && !options.help) {
+      throw new Error(`Missing value for ${flag}\n\n${USAGE}`);
+    }
+  }
+  return options;
+}
+
+function main(argv) {
+  const options = parseArgs(argv);
+  if (options.help) {
+    process.stdout.write(`${USAGE}\n`);
+    return 0;
+  }
+  if (options.primary === undefined) {
+    process.stderr.write(`haze-ui-theme: --primary is required\n\n${USAGE}\n`);
+    return 1;
+  }
+  let theme;
+  try {
+    theme = createBrandThemeCss({name: options.name, light: options.primary, dark: options.dark});
+  } catch (error) {
+    process.stderr.write(`haze-ui-theme: ${error instanceof Error ? error.message : error}\n`);
+    return 1;
+  }
+  const css = renderStylesheet(theme, {lightSeed: options.primary, darkSeed: options.dark ?? 'derived (oklch l +0.2)'});
+  if (options.out === undefined) {
+    process.stdout.write(css);
+    return 0;
+  }
+  writeFileSync(options.out, css);
+  process.stdout.write(`haze-ui-theme: wrote ${options.out} (.haze-${options.name}-light / .haze-${options.name}-dark)\n`);
+  return 0;
+}
+
+// Run as a script; importable as a module when executed by the parity test.
+if (process.argv[1] && import.meta.url === pathToFileURL(process.argv[1]).href) {
+  process.exit(main(process.argv.slice(2)));
+}

package/dist/components/Accordion/Accordion.js

@@ -7,6 +7,7 @@ import { jsx as t } from "react/jsx-runtime";
 var n = "haze-Accordion__base";
 function r({ className: r, children: i }) {
 	return /* @__PURE__ */ t("div", {
+		"data-slot": "accordion",
 		className: e([n, r]),
 		children: i
 	});

package/dist/components/Accordion/AccordionItem.js

@@ -7,12 +7,15 @@ import { jsx as t, jsxs as n } from "react/jsx-runtime";
 var r = "haze-AccordionItem__item", i = "haze-AccordionItem__summary", a = "haze-AccordionItem__content";
 function o({ title: o, className: s, children: c }) {
 	return /* @__PURE__ */ n("details", {
+		"data-slot": "accordion-item",
 		name: "accordion",
 		className: e([r, s]),
 		children: [/* @__PURE__ */ t("summary", {
+			"data-slot": "header",
 			className: i,
 			children: o
 		}), /* @__PURE__ */ t("div", {
+			"data-slot": "content",
 			className: a,
 			children: c
 		})]