@hewnui/themes 0.0.0-stage → 0.1.0

package/dist/authoring/export-formats.js

@@ -0,0 +1,62 @@
+import { exportDesignMd } from "./export-design-md.js";
+import { exportDtcg } from "./export-dtcg.js";
+import { exportTailwindTheme } from "./export-css.js";
+import { exportSkillMd } from "./export-skill.js";
+/** Free curated Theme Lab / docs site formats. */
+export const THEME_EXPORT_FORMATS = [
+    {
+        id: "design-md",
+        label: "DESIGN.md",
+        description: "Human- and AI-readable design brief with OKLCH roles and rules",
+        filename: (packId) => `${packId}.DESIGN.md`,
+        mime: "text/markdown;charset=utf-8",
+        tier: "free",
+        render: exportDesignMd,
+    },
+    {
+        id: "dtcg",
+        label: "DTCG tokens",
+        description: "W3C Design Tokens JSON ($value / $type) with light and dark modes",
+        filename: (packId) => `${packId}.tokens.dtcg.json`,
+        mime: "application/json",
+        tier: "free",
+        render: exportDtcg,
+    },
+    {
+        id: "tailwind-theme",
+        label: "Tailwind @theme",
+        description: "Tailwind CSS v4 @theme file with mode remaps",
+        filename: (packId) => `${packId}.theme.css`,
+        mime: "text/css;charset=utf-8",
+        tier: "free",
+        render: exportTailwindTheme,
+    },
+    {
+        id: "skill-md",
+        label: "Agent skill",
+        description: "SKILL.md instructions for coding agents using this theme",
+        filename: (packId) => `${packId}.SKILL.md`,
+        mime: "text/markdown;charset=utf-8",
+        tier: "free",
+        render: exportSkillMd,
+    },
+];
+export function getThemeExportFormat(id) {
+    const format = THEME_EXPORT_FORMATS.find((entry) => entry.id === id);
+    if (!format)
+        throw new Error(`Unknown theme export format: ${id}`);
+    return format;
+}
+export function renderThemeExport(id, pack) {
+    return getThemeExportFormat(id).render(pack);
+}
+export const THEME_EXPORT_BASENAMES = {
+    "design-md": "DESIGN.md",
+    dtcg: "tokens.dtcg.json",
+    "tailwind-theme": "theme.css",
+    "skill-md": "SKILL.md",
+};
+/** Static public path for a generated curated export. */
+export function themeExportPublicPath(packId, id) {
+    return `/themes/${packId}/${THEME_EXPORT_BASENAMES[id]}`;
+}

package/dist/authoring/export-skill.d.ts

@@ -0,0 +1,5 @@
+import type { ResolvedPack } from "./types";
+/**
+ * Free — Cursor-style agent skill (SKILL.md) for applying this theme correctly.
+ */
+export declare function exportSkillMd(pack: ResolvedPack): string;

package/dist/authoring/export-skill.js

@@ -0,0 +1,75 @@
+import { COLOR_ROLES, DESIGN_DO, DESIGN_DONT, PACK_IDENTITY, } from "./pack-meta.js";
+import { colorEntries, modeOrder, primaryMode, structuralEntries, } from "./token-entries.js";
+function identity(pack) {
+    return (PACK_IDENTITY[pack.basePackId] ?? {
+        label: pack.id,
+        summary: `Custom pack based on ${pack.basePackId}.`,
+    });
+}
+/**
+ * Free — Cursor-style agent skill (SKILL.md) for applying this theme correctly.
+ */
+export function exportSkillMd(pack) {
+    const { label, summary } = identity(pack);
+    const modes = modeOrder(pack);
+    const mode = primaryMode(pack);
+    const skillName = `hewn-${pack.id}-theme`;
+    const colorLines = colorEntries(mode)
+        .map((e) => `| \`--kp-${e.name}\` / \`--color-${e.name}\` | ${COLOR_ROLES[e.name] ?? e.name} | \`${e.value}\` |`)
+        .join("\n");
+    const structuralLines = structuralEntries(mode)
+        .map((e) => `- \`--kp-${e.name}\`: \`${e.value}\``)
+        .join("\n");
+    return `---
+name: ${skillName}
+description: Apply the Hewn ${label} theme tokens, typography, motion, and design rules when building or restyling UI.
+---
+
+# ${label} theme (Hewn)
+
+${summary}
+
+Use this skill whenever generating UI that should match the **${label}** pack
+(\`${pack.id}\`). Supported modes: **${modes.join(", ")}**.
+
+## Quick rules
+
+${DESIGN_DO.map((item) => `- ${item}`).join("\n")}
+
+## Never
+
+${DESIGN_DONT.map((item) => `- ${item}`).join("\n")}
+
+## How to apply
+
+1. Set \`data-theme="${pack.id}"\` and \`data-mode="{${modes.join("|")}}"\` on a root element (or import the generated \`@theme\` CSS).
+2. Prefer semantic utilities / CSS variables (\`bg-background\`, \`text-foreground\`, \`bg-accent\`, \`border-border\`, \`--kp-*\`).
+3. Respect reduced motion — disable springs/shimmers when \`prefers-reduced-motion: reduce\`.
+4. Keep glass as a global material toggle; do not add per-component glass props.
+
+## Color tokens (primary mode: ${mode.mode})
+
+| Token | Role | Value |
+|---|---|---|
+${colorLines}
+
+## Structure
+
+${structuralLines}
+
+## Typography
+
+- **Sans:** IBM Plex Sans — UI and body
+- **Mono:** IBM Plex Mono — labels, code, metrics (\`tabular-nums\`)
+- **Display:** Space Grotesk — hero H1 / brand wordmark ≥18px only
+
+## Export companions
+
+- \`DESIGN.md\` — full design brief
+- \`tokens.dtcg.json\` — DTCG (\`$value\` / \`$type\`) with light/dark modes
+- \`theme.css\` — Tailwind v4 \`@theme\` block
+
+When unsure, re-read \`DESIGN.md\` for this pack and keep accents within the
+curated ramp — do not invent a new hue family.
+`;
+}

package/dist/authoring/export-sticker.d.ts

@@ -0,0 +1,6 @@
+import type { ResolvedPack } from "./types";
+/**
+ * Core sticker sheet SVG — surfaces, button, and input per pack.
+ * Use as a Figma community kit reference (paste or import SVG).
+ */
+export declare function exportStickerSheetSvg(packs: readonly ResolvedPack[]): string;

package/dist/authoring/export-sticker.js

@@ -0,0 +1,54 @@
+import { formatOklch } from "./oklch.js";
+import { primaryMode } from "./token-entries.js";
+const ROW_H = 96;
+const PAD = 24;
+const COL_W = 120;
+const LABEL_W = 88;
+/**
+ * Core sticker sheet SVG — surfaces, button, and input per pack.
+ * Use as a Figma community kit reference (paste or import SVG).
+ */
+export function exportStickerSheetSvg(packs) {
+    const width = PAD * 2 + LABEL_W + COL_W * 4;
+    const height = PAD * 2 + 40 + packs.length * ROW_H;
+    const rows = packs
+        .map((pack, index) => renderRow(pack, PAD + 40 + index * ROW_H))
+        .join("\n");
+    return `<?xml version="1.0" encoding="UTF-8"?>
+<svg xmlns="http://www.w3.org/2000/svg" width="${width}" height="${height}" viewBox="0 0 ${width} ${height}" role="img" aria-label="Hewn sticker sheet">
+  <rect width="100%" height="100%" fill="#f4f4f2"/>
+  <text x="${PAD}" y="${PAD + 16}" font-family="IBM Plex Sans, ui-sans-serif, system-ui, sans-serif" font-size="16" font-weight="600" fill="#1a1a18">Hewn · sticker sheet</text>
+  <text x="${PAD + LABEL_W}" y="${PAD + 34}" font-family="IBM Plex Mono, ui-monospace, monospace" font-size="10" fill="#6b6b66">surface</text>
+  <text x="${PAD + LABEL_W + COL_W}" y="${PAD + 34}" font-family="IBM Plex Mono, ui-monospace, monospace" font-size="10" fill="#6b6b66">raised</text>
+  <text x="${PAD + LABEL_W + COL_W * 2}" y="${PAD + 34}" font-family="IBM Plex Mono, ui-monospace, monospace" font-size="10" fill="#6b6b66">button</text>
+  <text x="${PAD + LABEL_W + COL_W * 3}" y="${PAD + 34}" font-family="IBM Plex Mono, ui-monospace, monospace" font-size="10" fill="#6b6b66">input</text>
+${rows}
+</svg>
+`;
+}
+function renderRow(pack, y) {
+    const mode = primaryMode(pack);
+    const bg = formatOklch(mode.background);
+    const surface = formatOklch(mode.surface);
+    const raised = formatOklch(mode.surfaceRaised);
+    const accent = formatOklch(mode.accent);
+    const accentFg = formatOklch(mode.accentForeground);
+    const fg = formatOklch(mode.foreground);
+    const border = formatOklch(mode.border);
+    const muted = formatOklch(mode.mutedForeground);
+    const x0 = PAD + LABEL_W;
+    return `  <g>
+    <text x="${PAD}" y="${y + 42}" font-family="IBM Plex Sans, ui-sans-serif, system-ui, sans-serif" font-size="13" fill="#1a1a18">${pack.id}</text>
+    <rect x="${x0}" y="${y}" width="100" height="72" rx="10" fill="${bg}" stroke="${border}" stroke-width="1"/>
+    <rect x="${x0 + 12}" y="${y + 14}" width="76" height="44" rx="8" fill="${surface}" stroke="${border}" stroke-width="1"/>
+    <rect x="${x0 + COL_W}" y="${y}" width="100" height="72" rx="10" fill="${bg}" stroke="${border}" stroke-width="1"/>
+    <rect x="${x0 + COL_W + 12}" y="${y + 14}" width="76" height="44" rx="8" fill="${raised}" stroke="${border}" stroke-width="1"/>
+    <rect x="${x0 + COL_W * 2}" y="${y}" width="100" height="72" rx="10" fill="${bg}" stroke="${border}" stroke-width="1"/>
+    <rect x="${x0 + COL_W * 2 + 14}" y="${y + 22}" width="72" height="28" rx="8" fill="${accent}"/>
+    <text x="${x0 + COL_W * 2 + 50}" y="${y + 40}" text-anchor="middle" font-family="IBM Plex Sans, ui-sans-serif, system-ui, sans-serif" font-size="11" fill="${accentFg}">Button</text>
+    <rect x="${x0 + COL_W * 3}" y="${y}" width="100" height="72" rx="10" fill="${bg}" stroke="${border}" stroke-width="1"/>
+    <rect x="${x0 + COL_W * 3 + 10}" y="${y + 22}" width="80" height="28" rx="8" fill="${surface}" stroke="${border}" stroke-width="1"/>
+    <text x="${x0 + COL_W * 3 + 18}" y="${y + 40}" font-family="IBM Plex Sans, ui-sans-serif, system-ui, sans-serif" font-size="11" fill="${muted}">Input</text>
+    <text x="${x0 + COL_W * 3 + 70}" y="${y + 40}" font-family="IBM Plex Sans, ui-sans-serif, system-ui, sans-serif" font-size="9" fill="${fg}" opacity="0.35">|</text>
+  </g>`;
+}

package/dist/authoring/export-style-dictionary.d.ts

@@ -0,0 +1,3 @@
+import type { ResolvedPack } from "./types";
+/** Pro — Style Dictionary–friendly nested token JSON (all modes). */
+export declare function exportStyleDictionary(pack: ResolvedPack): string;

package/dist/authoring/export-style-dictionary.js

@@ -0,0 +1,52 @@
+import { colorEntries, modeOrder, primaryMode, structuralEntries, } from "./token-entries.js";
+function setPath(root, path, leaf) {
+    let cursor = root;
+    for (let i = 0; i < path.length - 1; i += 1) {
+        const key = path[i];
+        const existing = cursor[key];
+        if (!existing || typeof existing !== "object" || "value" in existing) {
+            cursor[key] = {};
+        }
+        cursor = cursor[key];
+    }
+    cursor[path[path.length - 1]] = leaf;
+}
+function parseNumeric(value) {
+    const asNum = Number(value);
+    return Number.isFinite(asNum) && value.trim() !== "" ? asNum : value;
+}
+/** Pro — Style Dictionary–friendly nested token JSON (all modes). */
+export function exportStyleDictionary(pack) {
+    const tree = {};
+    const modes = modeOrder(pack);
+    for (const modeName of modes) {
+        const mode = pack.modes[modeName];
+        if (!mode)
+            continue;
+        for (const entry of colorEntries(mode)) {
+            setPath(tree, ["color", entry.name, modeName], {
+                value: entry.value,
+                type: "color",
+            });
+        }
+    }
+    const primary = primaryMode(pack);
+    for (const entry of structuralEntries(primary)) {
+        const [group, ...rest] = entry.name.split("-");
+        const path = rest.length > 0 ? [group, rest.join("-")] : [entry.name];
+        setPath(tree, path, {
+            value: parseNumeric(entry.value),
+            type: entry.kind === "number" ? "number" : "dimension",
+        });
+    }
+    setPath(tree, ["meta", "packId"], { value: pack.id, type: "other" });
+    setPath(tree, ["meta", "basePackId"], {
+        value: pack.basePackId,
+        type: "other",
+    });
+    setPath(tree, ["meta", "supportedModes"], {
+        value: modes.join(","),
+        type: "other",
+    });
+    return `${JSON.stringify(tree, null, 2)}\n`;
+}

package/dist/authoring/figma-kit.d.ts

@@ -0,0 +1,16 @@
+import { type ThemeExportFormatId } from "./export-formats";
+import { type BasePackId, type ResolvedPack } from "./types";
+/** Derive curated packs with no overrides (canonical kit source). */
+export declare function curatedResolvedPacks(): ResolvedPack[];
+export declare function curatedResolvedPack(basePackId: BasePackId): ResolvedPack;
+export declare function exportCuratedFigmaKit(): string;
+export declare function exportCuratedStickerSheet(): string;
+export type CuratedThemeExportFile = {
+    packId: string;
+    formatId: ThemeExportFormatId;
+    /** Stable basename under `/themes/{packId}/` */
+    basename: string;
+    contents: string;
+};
+/** All free Theme Lab formats × six curated packs. */
+export declare function exportCuratedThemeFiles(): CuratedThemeExportFile[];

package/dist/authoring/figma-kit.js

@@ -0,0 +1,41 @@
+import { derivePack } from "./derive.js";
+import { exportFigmaKit } from "./export-figma.js";
+import { THEME_EXPORT_BASENAMES, THEME_EXPORT_FORMATS, } from "./export-formats.js";
+import { exportStickerSheetSvg } from "./export-sticker.js";
+import { BASE_PACK_IDS } from "./types.js";
+/** Derive curated packs with no overrides (canonical kit source). */
+export function curatedResolvedPacks() {
+    return BASE_PACK_IDS.map((basePackId) => curatedResolvedPack(basePackId));
+}
+export function curatedResolvedPack(basePackId) {
+    const result = derivePack({
+        schemaVersion: 2,
+        basePackId,
+        packId: basePackId,
+    });
+    if (!result.ok) {
+        throw new Error(`failed to derive curated pack ${basePackId}: ${result.errors.join(", ")}`);
+    }
+    return result.pack;
+}
+export function exportCuratedFigmaKit() {
+    return exportFigmaKit(curatedResolvedPacks());
+}
+export function exportCuratedStickerSheet() {
+    return exportStickerSheetSvg(curatedResolvedPacks());
+}
+/** All free Theme Lab formats × six curated packs. */
+export function exportCuratedThemeFiles() {
+    const files = [];
+    for (const pack of curatedResolvedPacks()) {
+        for (const format of THEME_EXPORT_FORMATS) {
+            files.push({
+                packId: pack.id,
+                formatId: format.id,
+                basename: THEME_EXPORT_BASENAMES[format.id],
+                contents: format.render(pack),
+            });
+        }
+    }
+    return files;
+}

package/dist/authoring/index.d.ts

@@ -0,0 +1,21 @@
+export { derivePack } from "./derive";
+export type { DeriveResult } from "./derive";
+export { exportPackCss, exportTailwindTheme } from "./export-css";
+export { exportDesignMd, sampleAccent } from "./export-design-md";
+export { exportDtcg } from "./export-dtcg";
+export { getThemeExportFormat, renderThemeExport, themeExportPublicPath, THEME_EXPORT_BASENAMES, THEME_EXPORT_FORMATS, type ExportTier, type ThemeExportFormat, type ThemeExportFormatId, } from "./export-formats";
+export { exportSkillMd } from "./export-skill";
+export { modeToCssVars, modeToPreviewCss } from "./css-vars";
+export { exportFigmaKit, exportFigmaVariables } from "./export-figma";
+export { exportStyleDictionary } from "./export-style-dictionary";
+export { exportStickerSheetSvg } from "./export-sticker";
+export { curatedResolvedPack, curatedResolvedPacks, exportCuratedFigmaKit, exportCuratedStickerSheet, exportCuratedThemeFiles, type CuratedThemeExportFile, } from "./figma-kit";
+export { contrastForeground, contrastRatio, formatHex, formatOklch, parseColor } from "./oklch";
+export { normalizeOverrideMap } from "./override-map";
+export type { NormalizeResult } from "./override-map";
+export { PACK_IDENTITY, DESIGN_DO, DESIGN_DONT } from "./pack-meta";
+export { BASE_PACKS, supportedModes } from "./packs";
+export { extractColorsFromCss, parseAiProposal, pickAccentFromColors, proposeFromPalette, proposeFromPrompt, proposalToOverrideMap, suggestBasePack, suggestRadius, } from "./propose";
+export type { ThemeProposal } from "./propose";
+export { accentSetFromSeed } from "./ramps";
+export { BASE_PACK_IDS, PRO_AUTHORING_UNLOCKED, SCHEMA_VERSION, type BasePackId, type DensityPreset, type GlassOverrides, type MotionCharacter, type NeutralOverrides, type OverrideMap, type RadiusPreset, type ResolvedPack, type SemanticOverrides, type ShapeOverrides, type ThemeMode, } from "./types";

package/dist/authoring/index.js

@@ -0,0 +1,18 @@
+export { derivePack } from "./derive.js";
+export { exportPackCss, exportTailwindTheme } from "./export-css.js";
+export { exportDesignMd, sampleAccent } from "./export-design-md.js";
+export { exportDtcg } from "./export-dtcg.js";
+export { getThemeExportFormat, renderThemeExport, themeExportPublicPath, THEME_EXPORT_BASENAMES, THEME_EXPORT_FORMATS, } from "./export-formats.js";
+export { exportSkillMd } from "./export-skill.js";
+export { modeToCssVars, modeToPreviewCss } from "./css-vars.js";
+export { exportFigmaKit, exportFigmaVariables } from "./export-figma.js";
+export { exportStyleDictionary } from "./export-style-dictionary.js";
+export { exportStickerSheetSvg } from "./export-sticker.js";
+export { curatedResolvedPack, curatedResolvedPacks, exportCuratedFigmaKit, exportCuratedStickerSheet, exportCuratedThemeFiles, } from "./figma-kit.js";
+export { contrastForeground, contrastRatio, formatHex, formatOklch, parseColor } from "./oklch.js";
+export { normalizeOverrideMap } from "./override-map.js";
+export { PACK_IDENTITY, DESIGN_DO, DESIGN_DONT } from "./pack-meta.js";
+export { BASE_PACKS, supportedModes } from "./packs.js";
+export { extractColorsFromCss, parseAiProposal, pickAccentFromColors, proposeFromPalette, proposeFromPrompt, proposalToOverrideMap, suggestBasePack, suggestRadius, } from "./propose.js";
+export { accentSetFromSeed } from "./ramps.js";
+export { BASE_PACK_IDS, PRO_AUTHORING_UNLOCKED, SCHEMA_VERSION, } from "./types.js";

package/dist/authoring/oklch.d.ts

@@ -0,0 +1,11 @@
+import type { Oklch } from "./types";
+export declare function formatOklch(color: Oklch): string;
+export declare function formatHex(color: Oklch): string;
+export declare function parseColor(input: string): Oklch | null;
+export declare function relativeLuminance(color: Oklch): number;
+export declare function contrastRatio(a: Oklch, b: Oklch): number;
+/** Pick black or white foreground that meets AA (4.5:1) against the background. */
+export declare function contrastForeground(background: Oklch, prefer: Oklch, minRatio?: number): {
+    color: Oklch;
+    adjusted: boolean;
+};

package/dist/authoring/oklch.js

@@ -0,0 +1,116 @@
+const OKLCH_RE = /^oklch\(\s*([0-9.]+)\s+([0-9.]+)\s+([0-9.]+)(?:\s*\/\s*([0-9.]+)%?)?\s*\)$/i;
+const HEX_RE = /^#([0-9a-f]{3}|[0-9a-f]{6})$/i;
+export function formatOklch(color) {
+    const { l, c, h, alpha } = color;
+    const base = `oklch(${round(l)} ${round(c)} ${round(h)}`;
+    if (alpha === undefined || alpha >= 1)
+        return `${base})`;
+    return `${base} / ${Math.round(alpha * 100)}%)`;
+}
+export function formatHex(color) {
+    const [r, g, b] = oklchToSrgb(color);
+    const toByte = (channel) => Math.round(Math.min(1, Math.max(0, channel)) * 255);
+    return `#${[toByte(r), toByte(g), toByte(b)]
+        .map((n) => n.toString(16).padStart(2, "0"))
+        .join("")}`;
+}
+export function parseColor(input) {
+    const trimmed = input.trim();
+    const oklch = trimmed.match(OKLCH_RE);
+    if (oklch) {
+        return {
+            l: Number(oklch[1]),
+            c: Number(oklch[2]),
+            h: Number(oklch[3]),
+            ...(oklch[4] !== undefined
+                ? {
+                    alpha: Number(oklch[4]) > 1
+                        ? Number(oklch[4]) / 100
+                        : Number(oklch[4]),
+                }
+                : {}),
+        };
+    }
+    const hex = trimmed.match(HEX_RE);
+    if (!hex?.[1])
+        return null;
+    return srgbToOklch(hexToSrgb(hex[1]));
+}
+export function relativeLuminance(color) {
+    const [r, g, b] = oklchToSrgb(color);
+    const lin = (channel) => {
+        const c = Math.min(1, Math.max(0, channel));
+        return c <= 0.04045 ? c / 12.92 : ((c + 0.055) / 1.055) ** 2.4;
+    };
+    return 0.2126 * lin(r) + 0.7152 * lin(g) + 0.0722 * lin(b);
+}
+export function contrastRatio(a, b) {
+    const l1 = relativeLuminance(a);
+    const l2 = relativeLuminance(b);
+    const lighter = Math.max(l1, l2);
+    const darker = Math.min(l1, l2);
+    return (lighter + 0.05) / (darker + 0.05);
+}
+/** Pick black or white foreground that meets AA (4.5:1) against the background. */
+export function contrastForeground(background, prefer, minRatio = 4.5) {
+    if (contrastRatio(prefer, background) >= minRatio) {
+        return { color: prefer, adjusted: false };
+    }
+    const white = { l: 0.99, c: 0, h: background.h };
+    const black = { l: 0.18, c: 0, h: background.h };
+    const whiteRatio = contrastRatio(white, background);
+    const blackRatio = contrastRatio(black, background);
+    return {
+        color: whiteRatio >= blackRatio ? white : black,
+        adjusted: true,
+    };
+}
+function round(value) {
+    return Math.round(value * 1000) / 1000;
+}
+function hexToSrgb(hex) {
+    const full = hex.length === 3
+        ? hex
+            .split("")
+            .map((ch) => ch + ch)
+            .join("")
+        : hex;
+    const n = Number.parseInt(full, 16);
+    return [(n >> 16) / 255, ((n >> 8) & 0xff) / 255, (n & 0xff) / 255];
+}
+/** Compact OKLCH ↔ sRGB (Björn Ottosson). Good enough for contrast floors. */
+function oklchToSrgb(color) {
+    const a = color.c * Math.cos((color.h * Math.PI) / 180);
+    const b = color.c * Math.sin((color.h * Math.PI) / 180);
+    const l_ = color.l + 0.3963377774 * a + 0.2158037573 * b;
+    const m_ = color.l - 0.1055613458 * a - 0.0638541728 * b;
+    const s_ = color.l - 0.0894841775 * a - 1.291485548 * b;
+    const l = l_ ** 3;
+    const m = m_ ** 3;
+    const s = s_ ** 3;
+    return [
+        +4.0767416621 * l - 3.3077115913 * m + 0.2309699292 * s,
+        -1.2684380046 * l + 2.6097574011 * m - 0.3413193965 * s,
+        -0.0041960863 * l - 0.7034186147 * m + 1.707614701 * s,
+    ];
+}
+function srgbToOklch([r, g, b]) {
+    const toLinear = (c) => c <= 0.04045 ? c / 12.92 : ((c + 0.055) / 1.055) ** 2.4;
+    const rl = toLinear(r);
+    const gl = toLinear(g);
+    const bl = toLinear(b);
+    const l = 0.4122214708 * rl + 0.5363325363 * gl + 0.0514459929 * bl;
+    const m = 0.2119034982 * rl + 0.6806995451 * gl + 0.1073969566 * bl;
+    const s = 0.0883024619 * rl + 0.2817188376 * gl + 0.6299787005 * bl;
+    const l_ = Math.cbrt(l);
+    const m_ = Math.cbrt(m);
+    const s_ = Math.cbrt(s);
+    const L = 0.2104542553 * l_ + 0.793617785 * m_ - 0.0040720468 * s_;
+    const A = 1.9779984951 * l_ - 2.428592205 * m_ + 0.4505937099 * s_;
+    const B = 0.0259040371 * l_ + 0.7827717662 * m_ - 0.808675766 * s_;
+    const C = Math.sqrt(A * A + B * B);
+    let H = (Math.atan2(B, A) * 180) / Math.PI;
+    if (H < 0)
+        H += 360;
+    return { l: L, c: C, h: H };
+}

package/dist/authoring/override-map.d.ts

@@ -0,0 +1,9 @@
+import { type OverrideMap } from "./types";
+export type NormalizeResult = {
+    ok: true;
+    map: OverrideMap;
+} | {
+    ok: false;
+    errors: string[];
+};
+export declare function normalizeOverrideMap(value: unknown): NormalizeResult;

package/dist/authoring/override-map.js

@@ -0,0 +1,150 @@
+import { BASE_PACK_IDS, SCHEMA_VERSION, } from "./types.js";
+const KEBAB = /^[a-z0-9]+(?:-[a-z0-9]+)*$/;
+const RADIUS = new Set(["sharp", "soft", "rounded", "pill"]);
+const DENSITY = new Set(["compact", "default", "comfortable"]);
+const MOTION = new Set(["snappy", "balanced", "soft"]);
+function clamp(value, min, max) {
+    return Math.min(max, Math.max(min, value));
+}
+function readNeutrals(value, errors) {
+    if (value === undefined)
+        return undefined;
+    if (typeof value !== "object" || value === null || Array.isArray(value)) {
+        errors.push("neutrals must be an object");
+        return undefined;
+    }
+    const record = value;
+    const next = {};
+    if (record.surfaceShift !== undefined) {
+        if (typeof record.surfaceShift !== "number" || Number.isNaN(record.surfaceShift)) {
+            errors.push("neutrals.surfaceShift must be a number");
+        }
+        else {
+            next.surfaceShift = clamp(record.surfaceShift, -0.08, 0.08);
+        }
+    }
+    if (record.chromaScale !== undefined) {
+        if (typeof record.chromaScale !== "number" || Number.isNaN(record.chromaScale)) {
+            errors.push("neutrals.chromaScale must be a number");
+        }
+        else {
+            next.chromaScale = clamp(record.chromaScale, 0.5, 1.5);
+        }
+    }
+    return Object.keys(next).length > 0 ? next : undefined;
+}
+function readSemantic(value, errors) {
+    if (value === undefined)
+        return undefined;
+    if (typeof value !== "object" || value === null || Array.isArray(value)) {
+        errors.push("semantic must be an object");
+        return undefined;
+    }
+    const record = value;
+    if (record.dangerSeed === undefined)
+        return undefined;
+    if (typeof record.dangerSeed !== "string") {
+        errors.push("semantic.dangerSeed must be a string");
+        return undefined;
+    }
+    return { dangerSeed: record.dangerSeed };
+}
+function readShape(value, errors) {
+    if (value === undefined)
+        return undefined;
+    if (typeof value !== "object" || value === null || Array.isArray(value)) {
+        errors.push("shape must be an object");
+        return undefined;
+    }
+    const record = value;
+    if (record.density === undefined)
+        return undefined;
+    if (typeof record.density !== "string" || !DENSITY.has(record.density)) {
+        errors.push("shape.density must be compact | default | comfortable");
+        return undefined;
+    }
+    return { density: record.density };
+}
+function readGlass(value, errors) {
+    if (value === undefined)
+        return undefined;
+    if (typeof value !== "object" || value === null || Array.isArray(value)) {
+        errors.push("glass must be an object");
+        return undefined;
+    }
+    const record = value;
+    if (record.tintStrength === undefined)
+        return undefined;
+    if (typeof record.tintStrength !== "number" || Number.isNaN(record.tintStrength)) {
+        errors.push("glass.tintStrength must be a number");
+        return undefined;
+    }
+    return { tintStrength: clamp(record.tintStrength, 0.5, 1.5) };
+}
+export function normalizeOverrideMap(value) {
+    if (typeof value !== "object" || value === null || Array.isArray(value)) {
+        return { ok: false, errors: ["override map must be an object"] };
+    }
+    const record = value;
+    const errors = [];
+    let schemaVersion = typeof record.schemaVersion === "number" ? record.schemaVersion : 0;
+    if (schemaVersion < 1)
+        schemaVersion = SCHEMA_VERSION;
+    if (schemaVersion > SCHEMA_VERSION) {
+        errors.push(`unsupported schemaVersion ${schemaVersion} (max ${SCHEMA_VERSION})`);
+    }
+    if (typeof record.basePackId !== "string" ||
+        !BASE_PACK_IDS.includes(record.basePackId)) {
+        errors.push(`basePackId must be one of: ${BASE_PACK_IDS.join(", ")}`);
+    }
+    if (record.packId !== undefined) {
+        if (typeof record.packId !== "string" || !KEBAB.test(record.packId)) {
+            errors.push("packId must be kebab-case");
+        }
+        else if (BASE_PACK_IDS.includes(record.packId)) {
+            errors.push(`packId collides with curated pack "${record.packId}"`);
+        }
+    }
+    if (record.accentSeed !== undefined &&
+        typeof record.accentSeed !== "string") {
+        errors.push("accentSeed must be a string");
+    }
+    if (record.radiusPreset !== undefined &&
+        (typeof record.radiusPreset !== "string" ||
+            !RADIUS.has(record.radiusPreset))) {
+        errors.push("radiusPreset must be sharp | soft | rounded | pill");
+    }
+    if (record.motion !== undefined &&
+        (typeof record.motion !== "string" || !MOTION.has(record.motion))) {
+        errors.push("motion must be snappy | balanced | soft");
+    }
+    const neutrals = readNeutrals(record.neutrals, errors);
+    const semantic = readSemantic(record.semantic, errors);
+    const shape = readShape(record.shape, errors);
+    const glass = readGlass(record.glass, errors);
+    if (errors.length > 0)
+        return { ok: false, errors };
+    const map = {
+        schemaVersion: SCHEMA_VERSION,
+        basePackId: record.basePackId,
+    };
+    if (typeof record.packId === "string")
+        map.packId = record.packId;
+    if (typeof record.accentSeed === "string")
+        map.accentSeed = record.accentSeed;
+    if (typeof record.radiusPreset === "string" && RADIUS.has(record.radiusPreset)) {
+        map.radiusPreset = record.radiusPreset;
+    }
+    if (neutrals)
+        map.neutrals = neutrals;
+    if (semantic)
+        map.semantic = semantic;
+    if (shape)
+        map.shape = shape;
+    if (glass)
+        map.glass = glass;
+    if (typeof record.motion === "string" && MOTION.has(record.motion)) {
+        map.motion = record.motion;
+    }
+    return { ok: true, map };
+}

package/dist/authoring/pack-def.d.ts

@@ -0,0 +1,7 @@
+import type { CoreModeColors, Oklch, StructuralTokens, ThemeMode } from "./types";
+export declare function o(l: number, c: number, h: number, alpha?: number): Oklch;
+/** Curated pack definition before status families are merged. */
+export type PackDef = {
+    modes: Partial<Record<ThemeMode, CoreModeColors>>;
+    structural: StructuralTokens;
+};