@hewnui/themes 0.0.0-stage → 0.1.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Himanshu Kumar
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -1,3 +1,34 @@
-# Temporary Holding Version
+# @hewnui/themes
 
-This version is a temporary placeholder for this package. An operational version to replace this has been submitted for review and is awaiting a staged release.
+Semantic OKLCH design tokens, motion tokens, and six curated theme packs (forest, tide, graphite, dune, clay, ember), with DESIGN.md, DTCG, and Tailwind v4 exports.
+
+Part of [Hewn](https://hewnui.dev).
+
+## Install
+
+```bash
+pnpm add @hewnui/themes
+```
+
+## CSS entrypoints
+
+```css
+@import "@hewnui/themes/tokens.css";
+@import "@hewnui/themes/motion.css";
+@import "@hewnui/themes/radius.css";
+@import "@hewnui/themes/glass.css";
+```
+
+Packs live under `@hewnui/themes/packs/*`. Public theme exports (DESIGN.md, DTCG, Tailwind `@theme`, SKILL.md) are also published on the docs site at `/themes`.
+
+Programmatic theme authoring:
+
+```ts
+import { derivePack, BASE_PACKS } from "@hewnui/themes/authoring";
+```
+
+Docs: https://hewnui.dev/docs/themes
+
+## License
+
+MIT — see [LICENSE](./LICENSE).

package/dist/authoring/css-vars.d.ts

@@ -0,0 +1,10 @@
+import type { ResolvedMode } from "./types";
+/**
+ * Map a resolved mode to CSS custom properties for scoped live preview.
+ * Includes Tailwind `--color-*` rebinds so utilities do not keep :root-resolved
+ * docs-shell values, plus local glass vars so html[data-material=glass] rules
+ * sample the draft pack instead of the documentation theme.
+ */
+export declare function modeToCssVars(mode: ResolvedMode): Record<string, string>;
+/** Stylesheet block for a live-preview selector (no :root). */
+export declare function modeToPreviewCss(selector: string, mode: ResolvedMode): string;

package/dist/authoring/css-vars.js

@@ -0,0 +1,83 @@
+import { formatOklch } from "./oklch.js";
+import { colorEntries, structuralEntries } from "./token-entries.js";
+const COLOR_BRIDGE = [
+    "background",
+    "foreground",
+    "surface",
+    "surface-raised",
+    "muted",
+    "muted-foreground",
+    "accent",
+    "accent-foreground",
+    "border",
+    "ring",
+    "danger",
+    "danger-foreground",
+    "danger-subtle",
+    "danger-border",
+    "success",
+    "success-foreground",
+    "success-subtle",
+    "success-border",
+    "warning",
+    "warning-foreground",
+    "warning-subtle",
+    "warning-border",
+    "info",
+    "info-foreground",
+    "info-subtle",
+    "info-border",
+];
+/**
+ * Map a resolved mode to CSS custom properties for scoped live preview.
+ * Includes Tailwind `--color-*` rebinds so utilities do not keep :root-resolved
+ * docs-shell values, plus local glass vars so html[data-material=glass] rules
+ * sample the draft pack instead of the documentation theme.
+ */
+export function modeToCssVars(mode) {
+    const vars = {};
+    for (const entry of colorEntries(mode)) {
+        vars[`--kp-${entry.name}`] = entry.value;
+    }
+    for (const entry of structuralEntries(mode)) {
+        vars[`--kp-${entry.name}`] = entry.value;
+    }
+    vars["--kp-font-sans"] =
+        'var(--font-plex-sans, "IBM Plex Sans"), ui-sans-serif, system-ui, sans-serif';
+    vars["--kp-font-mono"] =
+        'var(--font-plex-mono, "IBM Plex Mono"), ui-monospace, monospace';
+    vars["--kp-font-display"] =
+        'var(--font-space-grotesk, "Space Grotesk"), var(--kp-font-sans)';
+    vars["--kp-shadow-surface"] =
+        `0 1px 2px color-mix(in oklch, ${formatOklch(mode.foreground)} 8%, transparent), ` +
+            `0 16px 40px -28px color-mix(in oklch, ${formatOklch(mode.foreground)} 28%, transparent)`;
+    // Recompute glass locally so inherited html glass fills cannot leak docs tint.
+    vars["--kp-glass-fill"] =
+        "color-mix(in oklch, var(--kp-surface) 46%, transparent)";
+    vars["--kp-glass-border"] =
+        "color-mix(in oklch, var(--kp-foreground) 16%, transparent)";
+    vars["--kp-glass-sheen"] =
+        "linear-gradient(148deg, color-mix(in oklch, var(--kp-glass-tint) 70%, white 8%), " +
+            "color-mix(in oklch, var(--kp-surface) 22%, transparent) 42%, " +
+            "color-mix(in oklch, var(--kp-surface) 38%, transparent))";
+    for (const name of COLOR_BRIDGE) {
+        vars[`--color-${name}`] = `var(--kp-${name})`;
+    }
+    // Fumadocs tokens occasionally paint nested chrome; keep them on the draft.
+    vars["--color-fd-background"] = "var(--kp-background)";
+    vars["--color-fd-foreground"] = "var(--kp-foreground)";
+    vars["--color-fd-card"] = "var(--kp-surface)";
+    vars["--color-fd-card-foreground"] = "var(--kp-foreground)";
+    vars["--color-fd-muted"] = "var(--kp-muted)";
+    vars["--color-fd-muted-foreground"] = "var(--kp-muted-foreground)";
+    vars["--color-fd-primary"] = "var(--kp-accent)";
+    vars["--color-fd-primary-foreground"] = "var(--kp-accent-foreground)";
+    vars["--color-fd-border"] = "var(--kp-border)";
+    vars["--color-fd-ring"] = "var(--kp-ring)";
+    return vars;
+}
+/** Stylesheet block for a live-preview selector (no :root). */
+export function modeToPreviewCss(selector, mode) {
+    const lines = Object.entries(modeToCssVars(mode)).map(([name, value]) => `  ${name}: ${value};`);
+    return `${selector} {\n${lines.join("\n")}\n}\n`;
+}

package/dist/authoring/derive.d.ts

@@ -0,0 +1,9 @@
+import type { OverrideMap, ResolvedPack } from "./types";
+export type DeriveResult = {
+    ok: true;
+    pack: ResolvedPack;
+} | {
+    ok: false;
+    errors: string[];
+};
+export declare function derivePack(overrides: OverrideMap): DeriveResult;

package/dist/authoring/derive.js

@@ -0,0 +1,79 @@
+import { applyGlass, applyMotion, applyNeutrals, applySemantic, applyShape } from "./pro-apply.js";
+import { BASE_PACKS, supportedModes } from "./packs.js";
+import { accentSetFromSeed } from "./ramps.js";
+const RADIUS_PRESETS = {
+    sharp: {
+        radiusSm: "0.125rem",
+        radiusMd: "0.2rem",
+        radiusLg: "0.3rem",
+        radiusPanel: "0.25rem",
+    },
+    rounded: {
+        radiusSm: "0.85rem",
+        radiusMd: "1.15rem",
+        radiusLg: "1.5rem",
+        radiusPanel: "1.25rem",
+    },
+    pill: {
+        radiusSm: "9999px",
+        radiusMd: "9999px",
+        radiusLg: "1.5rem",
+        radiusPanel: "1.15rem",
+    },
+};
+export function derivePack(overrides) {
+    const base = BASE_PACKS[overrides.basePackId];
+    const modes = supportedModes(overrides.basePackId);
+    const adjustments = [];
+    const resolved = {};
+    let structural = { ...base.structural };
+    if (overrides.radiusPreset && overrides.radiusPreset !== "soft") {
+        structural = { ...structural, ...RADIUS_PRESETS[overrides.radiusPreset] };
+    }
+    structural = applyShape(structural, overrides.shape);
+    structural = applyMotion(structural, overrides.motion);
+    for (const mode of modes) {
+        const colors = base.modes[mode];
+        if (!colors)
+            continue;
+        let next = { ...colors };
+        if (overrides.accentSeed) {
+            const accent = accentSetFromSeed(overrides.accentSeed, mode);
+            if ("error" in accent) {
+                return { ok: false, errors: [accent.error] };
+            }
+            next = {
+                ...next,
+                accent: accent.set.accent,
+                accentForeground: accent.set.accentForeground,
+                ring: accent.set.ring,
+                glassTint: accent.set.glassTint,
+            };
+            adjustments.push(...accent.adjustments);
+        }
+        next = applyNeutrals(next, overrides.neutrals, mode, adjustments);
+        const semantic = applySemantic(next, overrides.semantic, mode, adjustments);
+        if ("error" in semantic) {
+            return { ok: false, errors: [semantic.error] };
+        }
+        next = applyGlass(semantic, overrides.glass);
+        resolved[mode] = {
+            ...next,
+            ...structural,
+            mode,
+            colorScheme: mode,
+        };
+    }
+    const packId = overrides.packId ??
+        `custom-${overrides.basePackId}${overrides.accentSeed ? "-accent" : ""}`;
+    return {
+        ok: true,
+        pack: {
+            id: packId,
+            basePackId: overrides.basePackId,
+            supportedModes: modes,
+            modes: resolved,
+            adjustments: [...new Set(adjustments)],
+        },
+    };
+}

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

@@ -0,0 +1,8 @@
+import type { ResolvedPack } from "./types";
+/** Free-tier CSS pack export — drop-in `[data-theme]` file. */
+export declare function exportPackCss(pack: ResolvedPack): string;
+/**
+ * Free — Tailwind v4 `@theme` block for the primary mode, plus mode overrides
+ * that remap the same `--color-*` custom properties.
+ */
+export declare function exportTailwindTheme(pack: ResolvedPack): string;

package/dist/authoring/export-css.js

@@ -0,0 +1,60 @@
+import { colorEntries, modeOrder, primaryMode, structuralEntries, } from "./token-entries.js";
+function colorLines(mode) {
+    return [
+        `  color-scheme: ${mode.colorScheme};`,
+        ...colorEntries(mode).map((entry) => `  --kp-${entry.name}: ${entry.value};`),
+    ].join("\n");
+}
+function structuralLines(mode) {
+    return [
+        ...structuralEntries(mode).map((entry) => `  --kp-${entry.name}: ${entry.value};`),
+        `  --kp-font-sans: var(--font-plex-sans, "IBM Plex Sans"), ui-sans-serif, system-ui,`,
+        `    sans-serif;`,
+        `  --kp-font-mono: var(--font-plex-mono, "IBM Plex Mono"), ui-monospace, monospace;`,
+        `  --kp-font-display: var(--font-space-grotesk, "Space Grotesk"), var(--kp-font-sans);`,
+    ].join("\n");
+}
+/** Free-tier CSS pack export — drop-in `[data-theme]` file. */
+export function exportPackCss(pack) {
+    const blocks = [];
+    let first = true;
+    for (const modeName of modeOrder(pack)) {
+        const mode = pack.modes[modeName];
+        if (!mode)
+            continue;
+        const selector = first
+            ? `:root,\n[data-theme="${pack.id}"][data-mode="${mode.mode}"]`
+            : `[data-theme="${pack.id}"][data-mode="${mode.mode}"]`;
+        const body = first
+            ? `${colorLines(mode)}\n${structuralLines(mode)}`
+            : colorLines(mode);
+        blocks.push(`${selector} {\n${body}\n}`);
+        first = false;
+    }
+    return `${blocks.join("\n\n")}\n`;
+}
+/**
+ * Free — Tailwind v4 `@theme` block for the primary mode, plus mode overrides
+ * that remap the same `--color-*` custom properties.
+ */
+export function exportTailwindTheme(pack) {
+    const primary = primaryMode(pack);
+    const themeLines = [
+        ...colorEntries(primary).map((entry) => `  --color-${entry.name}: ${entry.value};`),
+        ...structuralEntries(primary)
+            .filter((entry) => entry.name.startsWith("radius-"))
+            .map((entry) => `  --${entry.name}: ${entry.value};`),
+        `  --font-sans: var(--font-plex-sans, "IBM Plex Sans"), ui-sans-serif, system-ui, sans-serif;`,
+        `  --font-mono: var(--font-plex-mono, "IBM Plex Mono"), ui-monospace, monospace;`,
+        `  --font-display: var(--font-space-grotesk, "Space Grotesk"), var(--font-sans);`,
+    ];
+    const blocks = [`@theme {\n${themeLines.join("\n")}\n}`];
+    for (const modeName of modeOrder(pack).slice(1)) {
+        const mode = pack.modes[modeName];
+        if (!mode)
+            continue;
+        const lines = colorEntries(mode).map((entry) => `  --color-${entry.name}: ${entry.value};`);
+        blocks.push(`[data-theme="${pack.id}"][data-mode="${mode.mode}"] {\n${lines.join("\n")}\n}`);
+    }
+    return `/* ${pack.id} — Tailwind v4 @theme */\n${blocks.join("\n\n")}\n`;
+}

package/dist/authoring/export-design-md.d.ts

@@ -0,0 +1,5 @@
+import type { ResolvedPack } from "./types";
+/** Free — human- and AI-readable design brief for one pack. */
+export declare function exportDesignMd(pack: ResolvedPack): string;
+/** Convenience — expose formatted OKLCH for tests/docs samples. */
+export declare function sampleAccent(pack: ResolvedPack): string;

package/dist/authoring/export-design-md.js

@@ -0,0 +1,113 @@
+import { COLOR_ROLES, DESIGN_DO, DESIGN_DONT, PACK_IDENTITY, } from "./pack-meta.js";
+import { formatOklch } from "./oklch.js";
+import { colorEntries, modeOrder, primaryMode, structuralEntries, } from "./token-entries.js";
+function identity(pack) {
+    const meta = PACK_IDENTITY[pack.basePackId];
+    return meta ?? { label: pack.id, summary: `Custom pack based on ${pack.basePackId}.` };
+}
+function paletteTable(pack) {
+    const modes = modeOrder(pack);
+    const header = modes.length > 1
+        ? `| Token | Role | ${modes.map((m) => m).join(" | ")} |`
+        : `| Token | Role | ${modes[0]} |`;
+    const sep = modes.length > 1
+        ? `|---|---|${modes.map(() => "---").join("|")}|`
+        : `|---|---|---|`;
+    const primary = primaryMode(pack);
+    const rows = colorEntries(primary).map((entry) => {
+        const role = COLOR_ROLES[entry.name] ?? entry.name;
+        const values = modes.map((modeName) => {
+            const mode = pack.modes[modeName];
+            if (!mode)
+                return "—";
+            const match = colorEntries(mode).find((e) => e.name === entry.name);
+            return match ? `\`${match.value}\`` : "—";
+        });
+        return `| \`${entry.name}\` | ${role} | ${values.join(" | ")} |`;
+    });
+    return [header, sep, ...rows].join("\n");
+}
+function structuralBlock(pack) {
+    const mode = primaryMode(pack);
+    return structuralEntries(mode)
+        .map((entry) => `- \`${entry.name}\`: \`${entry.value}\``)
+        .join("\n");
+}
+function list(items) {
+    return items.map((item) => `- ${item}`).join("\n");
+}
+/** Free — human- and AI-readable design brief for one pack. */
+export function exportDesignMd(pack) {
+    const { label, summary } = identity(pack);
+    const modes = modeOrder(pack).join(", ");
+    const mode = primaryMode(pack);
+    return `# ${label} — Design brief
+
+> Generated from Hewn curated theme packs. Semantic OKLCH tokens; do not edit by hand.
+
+## Identity
+
+${summary}
+
+- **Pack id:** \`${pack.id}\`
+- **Base pack:** \`${pack.basePackId}\`
+- **Supported modes:** ${modes}
+- **Color scheme (primary):** ${mode.colorScheme}
+
+## Palette
+
+${paletteTable(pack)}
+
+## Typography
+
+| Role | Stack | Usage |
+|---|---|---|
+| Sans | IBM Plex Sans, ui-sans-serif, system-ui | UI chrome, body, headings |
+| Mono | IBM Plex Mono, ui-monospace | Labels, code, tabular metrics |
+| Display | Space Grotesk → sans | Marketing hero H1 and brand wordmark ≥18px only |
+
+Body text uses pretty wrapping; headings use balanced wrapping; dynamic numbers use \`tabular-nums\`.
+
+## Radius & density
+
+${structuralBlock(pack)}
+
+Density scales control spacing rhythm. Panel radius (\`radius-panel\`) caps menus and dialogs so they never go full-pill.
+
+## Motion
+
+- Duration: \`${mode.motionDuration}\`
+- Spring stiffness: \`${mode.motionStiffness}\`
+- Spring damping: \`${mode.motionDamping}\`
+- Reduced motion always wins over global motion toggles.
+- Prefer transform / opacity / filter; never animate layout properties continuously.
+
+## Material
+
+- \`solid\` — structured product surfaces and separators
+- \`glass\` — accent-tinted frosted surfaces (blur, saturation, refraction, opaque fallback)
+
+## Do
+
+${list(DESIGN_DO)}
+
+## Don't
+
+${list(DESIGN_DONT)}
+
+## Token reference (primary mode)
+
+\`\`\`
+${colorEntries(mode)
+        .map((e) => `--kp-${e.name}: ${e.value};`)
+        .join("\n")}
+${structuralEntries(mode)
+        .map((e) => `--kp-${e.name}: ${e.value};`)
+        .join("\n")}
+\`\`\`
+`;
+}
+/** Convenience — expose formatted OKLCH for tests/docs samples. */
+export function sampleAccent(pack) {
+    return formatOklch(primaryMode(pack).accent);
+}

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

@@ -0,0 +1,6 @@
+import type { ResolvedPack } from "./types";
+/**
+ * Free — W3C Design Tokens Community Group JSON (`$value` / `$type`).
+ * Modes live under `modes.light` / `modes.dark` when supported.
+ */
+export declare function exportDtcg(pack: ResolvedPack): string;

package/dist/authoring/export-dtcg.js

@@ -0,0 +1,85 @@
+import { colorEntries, modeOrder, primaryMode, structuralEntries, } from "./token-entries.js";
+function leaf(type, value, description) {
+    return description
+        ? { $type: type, $value: value, $description: description }
+        : { $type: type, $value: value };
+}
+function modeColors(mode) {
+    const color = {};
+    for (const entry of colorEntries(mode)) {
+        color[entry.name] = leaf("color", entry.value);
+    }
+    return color;
+}
+function structuralGroup(mode) {
+    const radius = {};
+    const motion = {};
+    let density;
+    for (const entry of structuralEntries(mode)) {
+        if (entry.name.startsWith("radius-")) {
+            radius[entry.name.replace(/^radius-/, "")] = leaf("dimension", entry.value);
+            continue;
+        }
+        if (entry.name.startsWith("motion-")) {
+            const key = entry.name.replace(/^motion-/, "");
+            motion[key] = leaf(entry.kind === "number" ? "number" : "duration", entry.kind === "number" ? Number(entry.value) : entry.value);
+            continue;
+        }
+        if (entry.name === "density") {
+            density = leaf("number", Number(entry.value));
+        }
+    }
+    return {
+        radius,
+        motion,
+        ...(density ? { density } : {}),
+    };
+}
+/**
+ * Free — W3C Design Tokens Community Group JSON (`$value` / `$type`).
+ * Modes live under `modes.light` / `modes.dark` when supported.
+ */
+export function exportDtcg(pack) {
+    const modes = {};
+    for (const modeName of modeOrder(pack)) {
+        const mode = pack.modes[modeName];
+        if (!mode)
+            continue;
+        modes[modeName] = {
+            color: modeColors(mode),
+            ...structuralGroup(mode),
+        };
+    }
+    const primary = primaryMode(pack);
+    const doc = {
+        $description: `Hewn ${pack.id} theme — DTCG design tokens (${modeOrder(pack).join(" / ")}).`,
+        meta: {
+            packId: leaf("string", pack.id),
+            basePackId: leaf("string", pack.basePackId),
+            supportedModes: leaf("string", modeOrder(pack).join(",")),
+            colorScheme: leaf("string", primary.colorScheme),
+        },
+        typography: {
+            fontFamily: {
+                sans: leaf("fontFamily", [
+                    "IBM Plex Sans",
+                    "ui-sans-serif",
+                    "system-ui",
+                    "sans-serif",
+                ]),
+                mono: leaf("fontFamily", [
+                    "IBM Plex Mono",
+                    "ui-monospace",
+                    "monospace",
+                ]),
+                display: leaf("fontFamily", [
+                    "Space Grotesk",
+                    "IBM Plex Sans",
+                    "sans-serif",
+                ]),
+            },
+        },
+        modes,
+    };
+    return `${JSON.stringify(doc, null, 2)}\n`;
+}

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

@@ -0,0 +1,27 @@
+import type { ResolvedPack } from "./types";
+type TsToken = {
+    value: string | number;
+    type: string;
+    description?: string;
+};
+type TsSet = {
+    [key: string]: TsToken | TsSet;
+};
+type TsTheme = {
+    id: string;
+    name: string;
+    selectedTokenSets: Record<string, "enabled" | "source">;
+};
+/** Build Tokens Studio token sets + themes for one or more packs. */
+export declare function buildFigmaDocument(packs: readonly ResolvedPack[]): {
+    tokenSets: Record<string, TsSet>;
+    themes: TsTheme[];
+};
+/**
+ * Pro — Tokens Studio–compatible multi-set export for one authored pack.
+ * Import via Tokens Studio → Figma variables.
+ */
+export declare function exportFigmaVariables(pack: ResolvedPack): string;
+/** Curated kit — all packs in one Tokens Studio document. */
+export declare function exportFigmaKit(packs: readonly ResolvedPack[]): string;
+export {};

package/dist/authoring/export-figma.js

@@ -0,0 +1,76 @@
+import { colorEntries, modeOrder, primaryMode, structuralEntries, } from "./token-entries.js";
+function nest(set, path, token) {
+    let cursor = set;
+    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]] = token;
+}
+/** Build Tokens Studio token sets + themes for one or more packs. */
+export function buildFigmaDocument(packs) {
+    const tokenSets = {};
+    const themes = [];
+    for (const pack of packs) {
+        const structural = {};
+        const primary = primaryMode(pack);
+        for (const entry of structuralEntries(primary)) {
+            nest(structural, [entry.name], {
+                value: entry.kind === "number" ? Number(entry.value) : entry.value,
+                type: entry.kind === "number" ? "number" : "sizing",
+            });
+        }
+        tokenSets[`${pack.id}/structural`] = structural;
+        for (const modeName of modeOrder(pack)) {
+            const mode = pack.modes[modeName];
+            if (!mode)
+                continue;
+            const setName = `${pack.id}/${modeName}`;
+            const set = {};
+            for (const entry of colorEntries(mode)) {
+                nest(set, ["color", entry.name], {
+                    value: entry.value,
+                    type: "color",
+                });
+            }
+            tokenSets[setName] = set;
+            themes.push({
+                id: `${pack.id}-${modeName}`,
+                name: `${pack.id} / ${modeName}`,
+                selectedTokenSets: {
+                    [`${pack.id}/structural`]: "source",
+                    [setName]: "enabled",
+                },
+            });
+        }
+    }
+    return { tokenSets, themes };
+}
+function stringifyFigmaDoc(tokenSets, themes) {
+    const doc = {
+        $metadata: {
+            tokenSetOrder: Object.keys(tokenSets),
+            activeThemeEditor: themes[0]?.id ?? null,
+        },
+        $themes: themes,
+        ...tokenSets,
+    };
+    return `${JSON.stringify(doc, null, 2)}\n`;
+}
+/**
+ * Pro — Tokens Studio–compatible multi-set export for one authored pack.
+ * Import via Tokens Studio → Figma variables.
+ */
+export function exportFigmaVariables(pack) {
+    const { tokenSets, themes } = buildFigmaDocument([pack]);
+    return stringifyFigmaDoc(tokenSets, themes);
+}
+/** Curated kit — all packs in one Tokens Studio document. */
+export function exportFigmaKit(packs) {
+    const { tokenSets, themes } = buildFigmaDocument(packs);
+    return stringifyFigmaDoc(tokenSets, themes);
+}

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

@@ -0,0 +1,27 @@
+import type { ResolvedPack } from "./types";
+/**
+ * Export tier marker — today every curated Theme Lab format is `free`.
+ * Advanced Studio formats (Style Dictionary, Figma) can flip to `pro` later
+ * without changing call sites; consumers must not gate on this yet.
+ */
+export type ExportTier = "free" | "pro";
+export type ThemeExportFormatId = "design-md" | "dtcg" | "tailwind-theme" | "skill-md";
+export type ThemeExportFormat = {
+    id: ThemeExportFormatId;
+    /** Short UI label */
+    label: string;
+    /** Accessible description for buttons / docs */
+    description: string;
+    /** Suggested download filename (pack id substituted) */
+    filename: (packId: string) => string;
+    mime: string;
+    tier: ExportTier;
+    render: (pack: ResolvedPack) => string;
+};
+/** Free curated Theme Lab / docs site formats. */
+export declare const THEME_EXPORT_FORMATS: readonly ThemeExportFormat[];
+export declare function getThemeExportFormat(id: ThemeExportFormatId): ThemeExportFormat;
+export declare function renderThemeExport(id: ThemeExportFormatId, pack: ResolvedPack): string;
+export declare const THEME_EXPORT_BASENAMES: Record<ThemeExportFormatId, string>;
+/** Static public path for a generated curated export. */
+export declare function themeExportPublicPath(packId: string, id: ThemeExportFormatId): string;