@hewnui/themes 0.0.0-stage → 0.1.1

package/src/authoring/pro-apply.ts

@@ -0,0 +1,156 @@
+import { contrastForeground, parseColor } from "./oklch";
+import { statusColors } from "./status-ramps";
+import type {
+  GlassOverrides,
+  ModeColorTokens,
+  MotionCharacter,
+  NeutralOverrides,
+  Oklch,
+  OverrideMap,
+  SemanticOverrides,
+  ShapeOverrides,
+  StructuralTokens,
+  ThemeMode,
+} from "./types";
+
+const DENSITY: Record<NonNullable<ShapeOverrides["density"]>, number> = {
+  compact: 0.85,
+  default: 1,
+  comfortable: 1.15,
+};
+
+const MOTION: Record<
+  Exclude<MotionCharacter, "balanced">,
+  Pick<StructuralTokens, "motionDuration" | "motionStiffness" | "motionDamping">
+> = {
+  snappy: {
+    motionDuration: "180ms",
+    motionStiffness: 480,
+    motionDamping: 32,
+  },
+  soft: {
+    motionDuration: "340ms",
+    motionStiffness: 220,
+    motionDamping: 26,
+  },
+};
+
+function clampL(color: Oklch, delta: number): Oklch {
+  return { ...color, l: Math.min(0.99, Math.max(0.05, color.l + delta)) };
+}
+
+function scaleC(color: Oklch, scale: number): Oklch {
+  return { ...color, c: Math.max(0, color.c * scale) };
+}
+
+function biasNeutral(color: Oklch, n: NeutralOverrides): Oklch {
+  let next = color;
+  if (n.surfaceShift !== undefined) next = clampL(next, n.surfaceShift);
+  if (n.chromaScale !== undefined) next = scaleC(next, n.chromaScale);
+  return next;
+}
+
+export function applyNeutrals(
+  colors: ModeColorTokens,
+  neutrals: NeutralOverrides | undefined,
+  mode: ThemeMode,
+  adjustments: string[],
+): ModeColorTokens {
+  if (!neutrals) return colors;
+  if (
+    neutrals.surfaceShift === undefined &&
+    neutrals.chromaScale === undefined
+  ) {
+    return colors;
+  }
+
+  const next = {
+    ...colors,
+    background: biasNeutral(colors.background, neutrals),
+    surface: biasNeutral(colors.surface, neutrals),
+    surfaceRaised: biasNeutral(colors.surfaceRaised, neutrals),
+    muted: biasNeutral(colors.muted, neutrals),
+    border: biasNeutral(colors.border, neutrals),
+  };
+
+  const fg = contrastForeground(next.background, colors.foreground);
+  if (fg.adjusted) {
+    next.foreground = fg.color;
+    adjustments.push(
+      `${mode} foreground adjusted after neutral bias to meet WCAG AA`,
+    );
+  } else {
+    next.foreground = colors.foreground;
+  }
+
+  const mutedFg = contrastForeground(next.muted, colors.mutedForeground, 3);
+  next.mutedForeground = mutedFg.color;
+
+  return next;
+}
+
+export function applySemantic(
+  colors: ModeColorTokens,
+  semantic: SemanticOverrides | undefined,
+  mode: ThemeMode,
+  adjustments: string[],
+): ModeColorTokens | { error: string } {
+  if (!semantic?.dangerSeed) return colors;
+  const seed = parseColor(semantic.dangerSeed);
+  if (!seed) return { error: `invalid danger seed: "${semantic.dangerSeed}"` };
+
+  const danger: Oklch =
+    mode === "dark"
+      ? { ...seed, l: Math.min(0.78, Math.max(0.58, seed.l + 0.08)) }
+      : { ...seed, l: Math.min(0.62, Math.max(0.48, seed.l)) };
+
+  if (danger.l !== seed.l) {
+    adjustments.push(
+      `${mode} danger lightness clamped to ${danger.l.toFixed(2)}`,
+    );
+  }
+
+  const status = statusColors(mode, danger, {
+    success: colors.success.h,
+    warning: colors.warning.h,
+    info: colors.info.h,
+  });
+  return {
+    ...colors,
+    danger,
+    dangerForeground: status.dangerForeground,
+    dangerSubtle: status.dangerSubtle,
+    dangerBorder: status.dangerBorder,
+  };
+}
+
+export function applyGlass(
+  colors: ModeColorTokens,
+  glass: GlassOverrides | undefined,
+): ModeColorTokens {
+  if (!glass?.tintStrength || glass.tintStrength === 1) return colors;
+  const base = colors.glassTint.alpha ?? 1;
+  return {
+    ...colors,
+    glassTint: {
+      ...colors.glassTint,
+      alpha: Math.min(0.55, Math.max(0.08, base * glass.tintStrength)),
+    },
+  };
+}
+
+export function applyShape(
+  structural: StructuralTokens,
+  shape: ShapeOverrides | undefined,
+): StructuralTokens {
+  if (!shape?.density || shape.density === "default") return structural;
+  return { ...structural, density: DENSITY[shape.density] };
+}
+
+export function applyMotion(
+  structural: StructuralTokens,
+  motion: OverrideMap["motion"],
+): StructuralTokens {
+  if (!motion || motion === "balanced") return structural;
+  return { ...structural, ...MOTION[motion] };
+}

package/src/authoring/propose.ts

@@ -0,0 +1,181 @@
+import { formatHex, parseColor } from "./oklch";
+import { normalizeOverrideMap } from "./override-map";
+import {
+  BASE_PACK_IDS,
+  SCHEMA_VERSION,
+  type BasePackId,
+  type OverrideMap,
+  type RadiusPreset,
+} from "./types";
+
+const HEX_FIND = /#([0-9a-f]{3}|[0-9a-f]{6})\b/gi;
+const OKLCH_FIND =
+  /oklch\(\s*[0-9.]+\s+[0-9.]+\s+[0-9.]+(?:\s*\/\s*[0-9.]+%?)?\s*\)/gi;
+
+export type ThemeProposal = {
+  basePackId: BasePackId;
+  accentSeed: string;
+  radiusPreset: RadiusPreset;
+  notes: string[];
+};
+
+const PACK_BY_HUE: { pack: BasePackId; min: number; max: number }[] = [
+  { pack: "clay", min: 10, max: 45 },
+  { pack: "dune", min: 45, max: 85 },
+  { pack: "forest", min: 110, max: 165 },
+  { pack: "tide", min: 175, max: 230 },
+  { pack: "graphite", min: 230, max: 280 },
+  { pack: "ember", min: 0, max: 25 },
+];
+
+const PACK_KEYWORDS: { pack: BasePackId; words: string[] }[] = [
+  { pack: "forest", words: ["forest", "green", "nature", "leaf"] },
+  { pack: "tide", words: ["tide", "ocean", "sea", "blue", "cyan"] },
+  { pack: "graphite", words: ["graphite", "slate", "mono", "neutral", "gray", "grey"] },
+  { pack: "dune", words: ["dune", "sand", "desert", "beige", "warm"] },
+  { pack: "clay", words: ["clay", "terracotta", "earthy", "pottery"] },
+  { pack: "ember", words: ["ember", "fire", "night", "dark", "crimson"] },
+];
+
+/** Pull hex / oklch color strings from CSS or Tailwind snippets. */
+export function extractColorsFromCss(source: string): string[] {
+  const found: string[] = [];
+  for (const match of source.matchAll(HEX_FIND)) {
+    const normalized = normalizeHex(match[0]);
+    if (normalized) found.push(normalized);
+  }
+  for (const match of source.matchAll(OKLCH_FIND)) {
+    const parsed = parseColor(match[0]);
+    if (parsed) found.push(formatHex(parsed));
+  }
+  return [...new Set(found)];
+}
+
+export function pickAccentFromColors(colors: string[]): string | null {
+  let best: { hex: string; score: number } | null = null;
+  for (const hex of colors) {
+    const color = parseColor(hex);
+    if (!color) continue;
+    if (color.l < 0.2 || color.l > 0.9) continue;
+    const score = color.c * (1 - Math.abs(color.l - 0.55));
+    if (!best || score > best.score) best = { hex, score };
+  }
+  return best?.hex ?? colors[0] ?? null;
+}
+
+function normalizeHex(raw: string): string | null {
+  const match = raw.trim().match(/^#([0-9a-f]{3}|[0-9a-f]{6})$/i);
+  if (!match?.[1]) return null;
+  const hex = match[1];
+  const full =
+    hex.length === 3
+      ? hex
+          .split("")
+          .map((ch) => ch + ch)
+          .join("")
+      : hex;
+  return `#${full.toLowerCase()}`;
+}
+
+export function suggestBasePack(accentSeed: string, hint = ""): BasePackId {
+  const lower = hint.toLowerCase();
+  for (const entry of PACK_KEYWORDS) {
+    if (entry.words.some((w) => lower.includes(w))) return entry.pack;
+  }
+  const color = parseColor(accentSeed);
+  if (!color || color.c < 0.02) return "graphite";
+  const h = color.h;
+  for (const band of PACK_BY_HUE) {
+    if (h >= band.min && h < band.max) return band.pack;
+  }
+  return "forest";
+}
+
+export function suggestRadius(hint = ""): RadiusPreset {
+  const lower = hint.toLowerCase();
+  if (/\b(sharp|square|brutal)\b/.test(lower)) return "sharp";
+  if (/\b(pill|full.?round|capsule)\b/.test(lower)) return "pill";
+  if (/\b(rounded|soft.?round|friendly)\b/.test(lower)) return "rounded";
+  return "soft";
+}
+
+/** Deterministic proposal from colors + optional free-text hint (no LLM). */
+export function proposeFromPalette(
+  colors: string[],
+  hint = "",
+): ThemeProposal | null {
+  const accent = pickAccentFromColors(colors);
+  if (!accent) return null;
+  const basePackId = suggestBasePack(accent, hint);
+  const radiusPreset = suggestRadius(hint);
+  return {
+    basePackId,
+    accentSeed: accent,
+    radiusPreset,
+    notes: [
+      `Accent from palette (${colors.length} color${colors.length === 1 ? "" : "s"})`,
+      `Base pack suggested: ${basePackId}`,
+    ],
+  };
+}
+
+/** Offline prompt migration: keywords + embedded colors; never throws. */
+export function proposeFromPrompt(prompt: string): ThemeProposal {
+  const colors = extractColorsFromCss(prompt);
+  const fromPalette = proposeFromPalette(colors, prompt);
+  if (fromPalette) return fromPalette;
+  const basePackId = suggestBasePack("#2f6b4f", prompt);
+  return {
+    basePackId,
+    accentSeed: defaultAccentFor(basePackId),
+    radiusPreset: suggestRadius(prompt),
+    notes: ["No colors in prompt — used keyword defaults"],
+  };
+}
+
+export function proposalToOverrideMap(
+  proposal: ThemeProposal,
+  packId = "studio-draft",
+): OverrideMap {
+  return {
+    schemaVersion: SCHEMA_VERSION,
+    basePackId: proposal.basePackId,
+    packId,
+    accentSeed: proposal.accentSeed,
+    radiusPreset: proposal.radiusPreset,
+  };
+}
+
+/** Validate raw LLM/model JSON into a ThemeProposal via override normalize. */
+export function parseAiProposal(raw: unknown): ThemeProposal | { error: string } {
+  const normalized = normalizeOverrideMap({
+    schemaVersion: SCHEMA_VERSION,
+    ...(typeof raw === "object" && raw !== null ? raw : {}),
+  });
+  if (!normalized.ok) {
+    return { error: normalized.errors.join("; ") };
+  }
+  const { basePackId, accentSeed, radiusPreset } = normalized.map;
+  if (!accentSeed) return { error: "accentSeed required" };
+  if (!BASE_PACK_IDS.includes(basePackId)) {
+    return { error: "invalid basePackId" };
+  }
+  return {
+    basePackId,
+    accentSeed,
+    radiusPreset: radiusPreset ?? "soft",
+    notes: ["Validated AI proposal"],
+  };
+}
+
+function defaultAccentFor(pack: BasePackId): string {
+  const map: Record<BasePackId, string> = {
+    forest: "#2f6b4f",
+    tide: "#2f6f8f",
+    graphite: "#4a5568",
+    dune: "#b08968",
+    clay: "#a65d45",
+    ember: "#c45c3e",
+  };
+  return map[pack];
+}

package/src/authoring/ramps.ts

@@ -0,0 +1,62 @@
+import { contrastForeground, parseColor } from "./oklch";
+import type { Oklch, ThemeMode } from "./types";
+
+export type AccentSet = {
+  accent: Oklch;
+  accentForeground: Oklch;
+  ring: Oklch;
+  glassTint: Oklch;
+};
+
+export function accentSetFromSeed(
+  seedInput: string,
+  mode: ThemeMode,
+): { set: AccentSet; adjustments: string[] } | { error: string } {
+  const seed = parseColor(seedInput);
+  if (!seed) {
+    return { error: `invalid accent seed: "${seedInput}"` };
+  }
+
+  const adjustments: string[] = [];
+  const accent: Oklch =
+    mode === "dark"
+      ? { ...seed, l: Math.min(0.82, Math.max(0.62, seed.l + 0.12)) }
+      : { ...seed, l: Math.min(0.62, Math.max(0.42, seed.l)) };
+
+  if (accent.l !== seed.l) {
+    adjustments.push(
+      `${mode} accent lightness clamped to ${accent.l.toFixed(2)} for surface contrast`,
+    );
+  }
+
+  // Dark packs use light accents; prefer light ink so AA holds without
+  // brightening the accent beyond the pack character.
+  const preferFg: Oklch = {
+    l: 0.98,
+    c: Math.min(0.02, accent.c),
+    h: accent.h,
+  };
+  const fg = contrastForeground(accent, preferFg);
+  if (fg.adjusted) {
+    adjustments.push(
+      `${mode} accent-foreground adjusted to meet WCAG AA against accent`,
+    );
+  }
+
+  const ring = { ...accent, c: Math.min(0.14, accent.c + 0.01) };
+  const glassTint: Oklch = {
+    ...accent,
+    l: mode === "dark" ? Math.min(0.7, accent.l) : Math.min(0.82, accent.l + 0.15),
+    alpha: mode === "dark" ? 0.24 : 0.28,
+  };
+
+  return {
+    set: {
+      accent,
+      accentForeground: fg.color,
+      ring,
+      glassTint,
+    },
+    adjustments,
+  };
+}

package/src/authoring/status-ramps.ts

@@ -0,0 +1,98 @@
+import type { BasePackId, Oklch, StatusModeColors, ThemeMode } from "./types";
+
+/** Pack-character hues for semantic status families (not accent clones). */
+export const PACK_STATUS_HUES: Record<
+  BasePackId,
+  { success: number; warning: number; info: number }
+> = {
+  forest: { success: 148, warning: 78, info: 220 },
+  tide: { success: 165, warning: 75, info: 230 },
+  graphite: { success: 150, warning: 75, info: 250 },
+  dune: { success: 140, warning: 70, info: 230 },
+  clay: { success: 145, warning: 55, info: 230 },
+  ember: { success: 145, warning: 70, info: 230 },
+};
+
+function o(l: number, c: number, h: number, alpha?: number): Oklch {
+  return alpha === undefined ? { l, c, h } : { l, c, h, alpha };
+}
+
+function family(
+  mode: ThemeMode,
+  hue: number,
+  kind: "success" | "warning" | "info" | "danger",
+  dangerSeed?: Oklch,
+): { base: Oklch; fg: Oklch; subtle: Oklch; border: Oklch } {
+  const dark = mode === "dark";
+
+  if (kind === "danger" && dangerSeed) {
+    const base = dangerSeed;
+    return {
+      base,
+      fg: o(0.985, 0.01, base.h),
+      subtle: dark ? o(0.32, 0.05, base.h) : o(0.94, 0.035, base.h),
+      border: dark ? o(0.72, 0.1, base.h, 0.4) : o(0.56, 0.12, base.h, 0.4),
+    };
+  }
+
+  if (kind === "warning") {
+    const base = dark ? o(0.78, 0.12, hue) : o(0.75, 0.14, hue);
+    const fg = dark ? o(0.22, 0.04, hue) : o(0.25, 0.05, hue);
+    return {
+      base,
+      fg,
+      subtle: dark ? o(0.34, 0.04, hue) : o(0.94, 0.04, hue),
+      border: dark ? o(0.78, 0.1, hue, 0.4) : o(0.72, 0.12, hue, 0.4),
+    };
+  }
+
+  if (kind === "info") {
+    const base = dark ? o(0.72, 0.1, hue) : o(0.52, 0.11, hue);
+    return {
+      base,
+      fg: o(0.985, 0.01, hue),
+      subtle: dark ? o(0.32, 0.035, hue) : o(0.94, 0.03, hue),
+      border: dark ? o(0.72, 0.08, hue, 0.4) : o(0.52, 0.09, hue, 0.4),
+    };
+  }
+
+  // success — tide dark needs a slightly deeper base for light-fg AA
+  const successL = dark ? (hue === 165 ? 0.71 : 0.72) : 0.55;
+  const base = dark ? o(successL, 0.14, hue) : o(0.55, 0.15, hue);
+  return {
+    base,
+    fg: o(0.985, 0.01, hue),
+    subtle: dark ? o(0.32, 0.045, hue) : o(0.94, 0.035, hue),
+    border: dark ? o(0.72, 0.1, hue, 0.4) : o(0.55, 0.12, hue, 0.4),
+  };
+}
+
+/** Derive danger/success/warning/info (+ fg/subtle/border) for a mode. */
+export function statusColors(
+  mode: ThemeMode,
+  danger: Oklch,
+  hues: { success: number; warning: number; info: number },
+): StatusModeColors {
+  const dangerSet = family(mode, danger.h, "danger", danger);
+  const success = family(mode, hues.success, "success");
+  const warning = family(mode, hues.warning, "warning");
+  const info = family(mode, hues.info, "info");
+
+  return {
+    dangerForeground: dangerSet.fg,
+    dangerSubtle: dangerSet.subtle,
+    dangerBorder: dangerSet.border,
+    success: success.base,
+    successForeground: success.fg,
+    successSubtle: success.subtle,
+    successBorder: success.border,
+    warning: warning.base,
+    warningForeground: warning.fg,
+    warningSubtle: warning.subtle,
+    warningBorder: warning.border,
+    info: info.base,
+    infoForeground: info.fg,
+    infoSubtle: info.subtle,
+    infoBorder: info.border,
+  };
+}

package/src/authoring/token-entries.ts

@@ -0,0 +1,59 @@
+import { formatOklch } from "./oklch";
+import type { ResolvedMode, ResolvedPack, ThemeMode } from "./types";
+
+export type TokenEntry = { name: string; value: string; kind: "color" | "number" | "string" };
+
+export function modeOrder(pack: ResolvedPack): ThemeMode[] {
+  const order: ThemeMode[] = ["light", "dark"];
+  return order.filter((mode) => pack.modes[mode]);
+}
+
+export function colorEntries(mode: ResolvedMode): TokenEntry[] {
+  return [
+    { name: "background", value: formatOklch(mode.background), kind: "color" },
+    { name: "foreground", value: formatOklch(mode.foreground), kind: "color" },
+    { name: "surface", value: formatOklch(mode.surface), kind: "color" },
+    { name: "surface-raised", value: formatOklch(mode.surfaceRaised), kind: "color" },
+    { name: "muted", value: formatOklch(mode.muted), kind: "color" },
+    { name: "muted-foreground", value: formatOklch(mode.mutedForeground), kind: "color" },
+    { name: "accent", value: formatOklch(mode.accent), kind: "color" },
+    { name: "accent-foreground", value: formatOklch(mode.accentForeground), kind: "color" },
+    { name: "border", value: formatOklch(mode.border), kind: "color" },
+    { name: "ring", value: formatOklch(mode.ring), kind: "color" },
+    { name: "danger", value: formatOklch(mode.danger), kind: "color" },
+    { name: "danger-foreground", value: formatOklch(mode.dangerForeground), kind: "color" },
+    { name: "danger-subtle", value: formatOklch(mode.dangerSubtle), kind: "color" },
+    { name: "danger-border", value: formatOklch(mode.dangerBorder), kind: "color" },
+    { name: "success", value: formatOklch(mode.success), kind: "color" },
+    { name: "success-foreground", value: formatOklch(mode.successForeground), kind: "color" },
+    { name: "success-subtle", value: formatOklch(mode.successSubtle), kind: "color" },
+    { name: "success-border", value: formatOklch(mode.successBorder), kind: "color" },
+    { name: "warning", value: formatOklch(mode.warning), kind: "color" },
+    { name: "warning-foreground", value: formatOklch(mode.warningForeground), kind: "color" },
+    { name: "warning-subtle", value: formatOklch(mode.warningSubtle), kind: "color" },
+    { name: "warning-border", value: formatOklch(mode.warningBorder), kind: "color" },
+    { name: "info", value: formatOklch(mode.info), kind: "color" },
+    { name: "info-foreground", value: formatOklch(mode.infoForeground), kind: "color" },
+    { name: "info-subtle", value: formatOklch(mode.infoSubtle), kind: "color" },
+    { name: "info-border", value: formatOklch(mode.infoBorder), kind: "color" },
+    { name: "glass-tint", value: formatOklch(mode.glassTint), kind: "color" },
+  ];
+}
+
+export function structuralEntries(mode: ResolvedMode): TokenEntry[] {
+  return [
+    { name: "radius-sm", value: mode.radiusSm, kind: "string" },
+    { name: "radius-md", value: mode.radiusMd, kind: "string" },
+    { name: "radius-lg", value: mode.radiusLg, kind: "string" },
+    { name: "radius-panel", value: mode.radiusPanel, kind: "string" },
+    { name: "density", value: String(mode.density), kind: "number" },
+    { name: "motion-duration", value: mode.motionDuration, kind: "string" },
+    { name: "motion-stiffness", value: String(mode.motionStiffness), kind: "number" },
+    { name: "motion-damping", value: String(mode.motionDamping), kind: "number" },
+  ];
+}
+
+export function primaryMode(pack: ResolvedPack): ResolvedMode {
+  const modes = modeOrder(pack);
+  return pack.modes[modes[0]!]!;
+}

package/src/authoring/types.ts

@@ -0,0 +1,133 @@
+export const SCHEMA_VERSION = 2 as const;
+
+/** Flip when monetization lands — Studio UI reads this stub gate. */
+export const PRO_AUTHORING_UNLOCKED = false;
+
+export const BASE_PACK_IDS = [
+  "forest",
+  "tide",
+  "graphite",
+  "dune",
+  "clay",
+  "ember",
+] as const;
+
+export type BasePackId = (typeof BASE_PACK_IDS)[number];
+export type ThemeMode = "light" | "dark";
+export type RadiusPreset = "sharp" | "soft" | "rounded" | "pill";
+
+export type Oklch = {
+  l: number;
+  c: number;
+  h: number;
+  alpha?: number;
+};
+
+/** Core semantic surfaces + accent + danger seed (curated per pack mode). */
+export type CoreModeColors = {
+  background: Oklch;
+  foreground: Oklch;
+  surface: Oklch;
+  surfaceRaised: Oklch;
+  muted: Oklch;
+  mutedForeground: Oklch;
+  accent: Oklch;
+  accentForeground: Oklch;
+  border: Oklch;
+  ring: Oklch;
+  danger: Oklch;
+  glassTint: Oklch;
+};
+
+/** Status families — base + foreground / subtle / border variants. */
+export type StatusModeColors = {
+  dangerForeground: Oklch;
+  dangerSubtle: Oklch;
+  dangerBorder: Oklch;
+  success: Oklch;
+  successForeground: Oklch;
+  successSubtle: Oklch;
+  successBorder: Oklch;
+  warning: Oklch;
+  warningForeground: Oklch;
+  warningSubtle: Oklch;
+  warningBorder: Oklch;
+  info: Oklch;
+  infoForeground: Oklch;
+  infoSubtle: Oklch;
+  infoBorder: Oklch;
+};
+
+/** Full semantic color tokens authored per mode. */
+export type ModeColorTokens = CoreModeColors & StatusModeColors;
+
+export type StructuralTokens = {
+  radiusSm: string;
+  radiusMd: string;
+  radiusLg: string;
+  radiusPanel: string;
+  density: number;
+  motionDuration: string;
+  motionStiffness: number;
+  motionDamping: number;
+};
+
+export type ResolvedMode = ModeColorTokens & StructuralTokens & {
+  mode: ThemeMode;
+  colorScheme: ThemeMode;
+};
+
+export type ResolvedPack = {
+  id: string;
+  basePackId: BasePackId;
+  supportedModes: readonly ThemeMode[];
+  modes: Partial<Record<ThemeMode, ResolvedMode>>;
+  adjustments: string[];
+};
+
+export type DensityPreset = "compact" | "default" | "comfortable";
+export type MotionCharacter = "snappy" | "balanced" | "soft";
+
+/** Pro — neutrals / surfaces (constrained bias, not free-form tokens). */
+export type NeutralOverrides = {
+  /** Lightness shift −0.08…0.08 applied to surfaces. */
+  surfaceShift?: number;
+  /** Chroma multiplier 0.5…1.5 for tinted neutrals. */
+  chromaScale?: number;
+};
+
+/** Pro — semantic colors beyond accent. */
+export type SemanticOverrides = {
+  /** Danger seed as `oklch(...)` or `#rrggbb`. */
+  dangerSeed?: string;
+};
+
+/** Pro — density (radius stays free via radiusPreset). */
+export type ShapeOverrides = {
+  density?: DensityPreset;
+};
+
+/** Pro — glass tint strength. */
+export type GlassOverrides = {
+  /** Alpha multiplier 0.5…1.5 on glassTint. */
+  tintStrength?: number;
+};
+
+/**
+ * Override map — free fields + optional Pro groups.
+ * schemaVersion migrations keep older maps valid.
+ */
+export type OverrideMap = {
+  schemaVersion: typeof SCHEMA_VERSION | number;
+  basePackId: BasePackId;
+  /** Pack id for CSS `[data-theme="…"]` — kebab-case. */
+  packId?: string;
+  /** Accent seed as `oklch(...)` or `#rrggbb`. */
+  accentSeed?: string;
+  radiusPreset?: RadiusPreset;
+  neutrals?: NeutralOverrides;
+  semantic?: SemanticOverrides;
+  shape?: ShapeOverrides;
+  glass?: GlassOverrides;
+  motion?: MotionCharacter;
+};