@clhaas/palette-kit 0.1.8 → 0.3.0

package/dist/engine/normalize.test.js

@@ -0,0 +1,136 @@
+import { describe, expect, it, vi } from "vitest";
+import { normalizeQuery } from "./normalize.js";
+describe("normalizeQuery", () => {
+    it("applies defaults", () => {
+        const result = normalizeQuery({ role: "text.primary", surface: "surface" });
+        expect(result.usage).toBe("text");
+        expect(result.context).toBe("light");
+        expect(result.surface).toBe("surface");
+        expect(result.state).toBe("default");
+        expect(result.emphasis).toBe("default");
+    });
+    it("throws when role is missing", () => {
+        expect(() => normalizeQuery({})).toThrowError(/role/i);
+    });
+    it("applies output defaults", () => {
+        const result = normalizeQuery({ role: "text.primary", surface: "surface" });
+        expect(result.output.preferSpace).toBe("oklch");
+        expect(result.output.gamutMapping).toBe("preferP3ThenCompress");
+        expect(result.output.precision).toMatchObject({ l: 1, c: 3, h: 1 });
+        expect(result.output.strict).toBe(false);
+        expect(result.output.includeMeta).toBe(false);
+    });
+    it("infers usage from role prefixes", () => {
+        const warnSpy = vi.spyOn(console, "warn").mockImplementation(() => undefined);
+        try {
+            expect(normalizeQuery({ role: "icon.primary" }).usage).toBe("icon");
+            expect(normalizeQuery({ role: "border.muted" }).usage).toBe("border");
+            expect(normalizeQuery({ role: "bg.canvas" }).usage).toBe("bg");
+            expect(normalizeQuery({ role: "ring.focus" }).usage).toBe("ring");
+            expect(normalizeQuery({ role: "chart.axis.stroke" }).usage).toBe("stroke");
+            expect(normalizeQuery({ role: "chart.fill.primary" }).usage).toBe("fill");
+            expect(normalizeQuery({ role: "chart.grid.muted" }).usage).toBe("border");
+            expect(normalizeQuery({ role: "chart.label" }).usage).toBe("text");
+        }
+        finally {
+            warnSpy.mockRestore();
+        }
+    });
+    it("infers surface when obvious", () => {
+        expect(normalizeQuery({ role: "bg.app" }).surface).toBe("app");
+        expect(normalizeQuery({ role: "bg.surface" }).surface).toBe("surface");
+        expect(normalizeQuery({ role: "app.bg", usage: "bg" }).surface).toBe("app");
+    });
+    it("infers variant from role token", () => {
+        const warnSpy = vi.spyOn(console, "warn").mockImplementation(() => undefined);
+        try {
+            expect(normalizeQuery({ role: "success.bg", usage: "bg", surface: "surface" }).variant).toBe("success");
+            expect(normalizeQuery({ role: "warning.text", usage: "text", surface: "surface" }).variant).toBe("warning");
+            expect(normalizeQuery({ role: "danger.border", usage: "border", surface: "surface" }).variant).toBe("danger");
+            expect(normalizeQuery({ role: "category:sales.fill", usage: "fill", surface: "surface" }).variant).toBe("category:sales");
+            expect(normalizeQuery({
+                role: "chart:revenue.stroke",
+                usage: "stroke",
+                surface: "surface",
+            }).variant).toBe("chart:revenue");
+            expect(normalizeQuery({ role: "text.primary", usage: "text", surface: "surface" }).variant).toBeUndefined();
+        }
+        finally {
+            warnSpy.mockRestore();
+        }
+    });
+    it("requires usage when strict and inference fails", () => {
+        expect(() => normalizeQuery({ role: "brand.primary", output: { strict: true } })).toThrowError(/Provide usage explicitly/i);
+    });
+    it("warns when usage cannot be inferred in non-strict mode", () => {
+        const warnSpy = vi.spyOn(console, "warn").mockImplementation(() => undefined);
+        expect(normalizeQuery({ role: "brand.primary" }).usage).toBe("bg");
+        expect(warnSpy).toHaveBeenCalledWith(expect.stringContaining('Defaulting usage to "bg"'));
+        warnSpy.mockRestore();
+    });
+    it("requires surface when strict and inference fails", () => {
+        expect(() => normalizeQuery({ role: "text.primary", output: { strict: true } })).toThrowError(/Provide surface explicitly/i);
+    });
+    it("warns when surface cannot be inferred in non-strict mode", () => {
+        const warnSpy = vi.spyOn(console, "warn").mockImplementation(() => undefined);
+        expect(normalizeQuery({ role: "text.primary" }).surface).toBe("surface");
+        expect(warnSpy).toHaveBeenCalledWith(expect.stringContaining('Defaulting surface to "surface"'));
+        warnSpy.mockRestore();
+    });
+    it("validates background hint color values", () => {
+        const warnSpy = vi.spyOn(console, "warn").mockImplementation(() => undefined);
+        expect(normalizeQuery({ role: "bg.canvas", surface: "surface", on: { kind: "color", value: "#fff" } })
+            .on).toEqual({ kind: "color", value: "#fff" });
+        expect(normalizeQuery({
+            role: "bg.canvas",
+            surface: "surface",
+            on: { kind: "color", value: "oklch(62% 0.18 265)" },
+        }).on).toEqual({ kind: "color", value: "oklch(62% 0.18 265)" });
+        expect(normalizeQuery({
+            role: "bg.canvas",
+            surface: "surface",
+            on: { kind: "color", value: "color(display-p3 1 0.5 0.25)" },
+        }).on).toEqual({ kind: "color", value: "color(display-p3 1 0.5 0.25)" });
+        expect(normalizeQuery({ role: "bg.canvas", surface: "surface", on: { kind: "color", value: "banana" } })
+            .on).toEqual({ kind: "color", value: "banana" });
+        expect(warnSpy).toHaveBeenCalledTimes(3);
+        warnSpy.mockRestore();
+    });
+    it("normalizes nested background hints", () => {
+        expect(normalizeQuery({
+            role: "bg.canvas",
+            surface: "surface",
+            on: { kind: "role", role: " text.primary " },
+        })
+            .on).toEqual({ kind: "role", role: "text.primary" });
+        expect(normalizeQuery({ role: "bg.canvas", surface: "surface", on: { kind: "auto" } }).on).toEqual({
+            kind: "auto",
+        });
+        expect(() => normalizeQuery({ role: "bg.canvas", surface: "surface", on: { kind: "color", value: "   " } })).toThrowError(/color value is required/i);
+        expect(() => normalizeQuery({
+            role: "bg.canvas",
+            surface: "surface",
+            on: { kind: "color", value: "banana" },
+            output: { strict: true },
+        })).toThrowError(/background hint color value/i);
+        expect(() => normalizeQuery({ role: "bg.canvas", surface: "surface", on: { kind: "nope" } })).toThrowError(/background hint kind/i);
+    });
+    it("validates contrast requirements", () => {
+        expect(normalizeQuery({ role: "text.primary", contrast: { model: "apca", targetLc: 75 } })
+            .contrast).toEqual({ model: "apca", targetLc: 75 });
+        expect(normalizeQuery({ role: "text.primary", contrast: { model: "wcag2", minRatio: 4.5 } })
+            .contrast).toEqual({ model: "wcag2", minRatio: 4.5 });
+        expect(normalizeQuery({ role: "text.primary", contrast: { model: "none" } }).contrast).toEqual({ model: "none" });
+        expect(() => normalizeQuery({ role: "text.primary", contrast: { model: "apca" } })).toThrowError(/targetLc/i);
+        expect(() => normalizeQuery({ role: "text.primary", contrast: { model: "wcag2" } })).toThrowError(/minRatio.*ratio/i);
+        expect(() => normalizeQuery({ role: "text.primary", contrast: { model: "wcag2", minRatio: NaN } })).toThrowError(/minRatio must be a number/i);
+        expect(() => normalizeQuery({ role: "text.primary", contrast: { model: "nope" } })).toThrowError(/contrast model/i);
+    });
+    it("validates alpha strategies", () => {
+        expect(normalizeQuery({ role: "bg.canvas", alpha: { mode: "none" } }).alpha).toEqual({ mode: "none" });
+        expect(normalizeQuery({ role: "bg.canvas", alpha: { mode: "fixed", alpha: 0.5 } }).alpha).toEqual({ mode: "fixed", alpha: 0.5 });
+        expect(normalizeQuery({ role: "bg.canvas", alpha: { mode: "solveOnBackground" } }).alpha).toEqual({ mode: "solveOnBackground" });
+        expect(() => normalizeQuery({ role: "bg.canvas", alpha: { mode: "fixed" } })).toThrowError(/fixed alpha/i);
+        expect(() => normalizeQuery({ role: "bg.canvas", alpha: { mode: "nope" } })).toThrowError(/alpha strategy mode/i);
+    });
+});

package/dist/engine/onSolid.d.ts

@@ -0,0 +1,3 @@
+import type { OnSolidQuery } from "../types/index.js";
+import type { BaseResolvedColor, ThemeConfig } from "./resolveBaseColor.js";
+export declare function onSolid(query: OnSolidQuery, theme: ThemeConfig): BaseResolvedColor;

package/dist/engine/onSolid.js

@@ -0,0 +1,110 @@
+import { computeApcaLc } from "../contrast/apca.js";
+import { solveContrast } from "../contrast/solver.js";
+import { blendSrgb, toSrgbColor } from "../contrast/utils.js";
+import { contrastRatio } from "../contrast/wcag2.js";
+import { applyOperators } from "./applyOperators.js";
+import { mapColorContextToEngine } from "./context.js";
+import { normalizeOnSolidQuery, normalizeQuery } from "./normalize.js";
+import { resolveBaseColor } from "./resolveBaseColor.js";
+const DEFAULT_SOLVE_EPSILON = 0.01;
+const nearWhite = { l: 97, c: 0, h: 0, alpha: 1 };
+const nearBlack = { l: 15, c: 0, h: 0, alpha: 1 };
+const defaultContrastForUsage = (usage) => ({
+    model: "apca",
+    targetLc: usage === "text" ? 75 : 60,
+});
+const validateFixedAlpha = (alpha) => {
+    if (alpha < 0 || alpha > 1) {
+        throw new Error("Fixed alpha must be between 0 and 1");
+    }
+    return alpha;
+};
+const resolveAlphaStrategy = (alpha, usage, strict) => {
+    if (!alpha) {
+        return { mode: "fixed", alpha: usage === "text" ? 0.92 : 0.72 };
+    }
+    if (alpha.mode === "none") {
+        return alpha;
+    }
+    if (alpha.mode === "fixed") {
+        return { mode: "fixed", alpha: validateFixedAlpha(alpha.alpha) };
+    }
+    if (strict) {
+        throw new Error('onSolid does not support alpha.mode "solveOnBackground"');
+    }
+    console.warn('onSolid does not support alpha.mode "solveOnBackground"; falling back to fixed defaults');
+    return { mode: "fixed", alpha: usage === "text" ? 0.92 : 0.72 };
+};
+const checkContrastWithAlpha = (fg, bg, req, alpha, epsilon = DEFAULT_SOLVE_EPSILON) => {
+    if (req.model === "none") {
+        return { pass: true, value: 0 };
+    }
+    const fgSrgb = toSrgbColor(fg);
+    const bgSrgb = toSrgbColor(bg);
+    if (!fgSrgb || !bgSrgb) {
+        return { pass: false, value: Number.NaN };
+    }
+    const composite = blendSrgb(fgSrgb, bgSrgb, alpha);
+    if (req.model === "apca") {
+        const value = Math.abs(computeApcaLc(composite, bgSrgb));
+        const minTarget = req.minLc ?? req.targetLc;
+        const maxTarget = req.maxLc ?? Number.POSITIVE_INFINITY;
+        return {
+            pass: Number.isFinite(value) && value >= minTarget - epsilon && value <= maxTarget + epsilon,
+            value,
+        };
+    }
+    const value = contrastRatio(composite, bgSrgb);
+    return { pass: Number.isFinite(value) && value + epsilon >= req.minRatio, value };
+};
+export function onSolid(query, theme) {
+    const normalized = normalizeOnSolidQuery(query);
+    const contrastRequirement = normalized.contrast ?? defaultContrastForUsage(normalized.usage);
+    const alphaStrategy = resolveAlphaStrategy(normalized.alpha, normalized.usage, normalized.output.strict);
+    const alpha = alphaStrategy.mode === "none" ? 1 : alphaStrategy.alpha;
+    const bgNormalized = normalizeQuery({
+        role: normalized.bgRole,
+        usage: "bg",
+        surface: "solid",
+        context: normalized.context,
+        state: normalized.state,
+        emphasis: normalized.emphasis,
+    });
+    const bgBase = resolveBaseColor(bgNormalized, theme);
+    // Apply state/emphasis operators to the background before onSolid solves.
+    const bgResolved = applyOperators(bgBase, bgNormalized, theme);
+    const bg = bgResolved.oklch;
+    const baseFg = bg.l >= 50 ? nearBlack : nearWhite;
+    const seedUsed = `oklch(${baseFg.l}% ${baseFg.c} ${baseFg.h})`;
+    const solverContext = {
+        preset: theme.preset,
+        surface: bgNormalized.surface,
+        context: mapColorContextToEngine(bgNormalized.context),
+    };
+    const solved = solveContrast({ ...baseFg, alpha }, bg, contrastRequirement, solverContext, {
+        strict: normalized.output.strict,
+    });
+    let finalAlpha = alpha;
+    let finalColor = solved.color;
+    let finalCheck = checkContrastWithAlpha(finalColor, bg, contrastRequirement, finalAlpha, DEFAULT_SOLVE_EPSILON);
+    if (!finalCheck.pass && finalAlpha < 1) {
+        finalAlpha = 1;
+        const solvedOpaque = solveContrast({ ...baseFg, alpha: 1 }, bg, contrastRequirement, solverContext, { strict: normalized.output.strict });
+        finalColor = solvedOpaque.color;
+        finalCheck = checkContrastWithAlpha(finalColor, bg, contrastRequirement, finalAlpha, DEFAULT_SOLVE_EPSILON);
+    }
+    if (!finalCheck.pass && normalized.output.strict) {
+        const target = contrastRequirement.model === "apca"
+            ? contrastRequirement.targetLc
+            : contrastRequirement.model === "wcag2"
+                ? contrastRequirement.minRatio
+                : 0;
+        throw new Error(`onSolid contrast failed (${contrastRequirement.model}) target=${target} value=${finalCheck.value}`);
+    }
+    return {
+        oklch: { ...finalColor, alpha: finalAlpha },
+        step: 0,
+        variantUsed: "onSolid",
+        seedUsed,
+    };
+}

package/dist/engine/resolveBaseColor.d.ts

@@ -0,0 +1,25 @@
+import type { CurvePresetName } from "../presets/index.js";
+import type { ColorQuery, CssColorString } from "../types/index.js";
+import { type OkLchColor } from "./generateScale.js";
+import type { NormalizedQuery } from "./normalize.js";
+type ThemeSeeds = {
+    neutral: CssColorString;
+    accent: CssColorString;
+};
+export type ThemeConfig = {
+    seeds: {
+        light: ThemeSeeds;
+        dark: ThemeSeeds;
+    };
+    variants?: Record<string, CssColorString>;
+    preset?: CurvePresetName;
+};
+export type BaseResolvedColor = {
+    oklch: OkLchColor;
+    step: number;
+    variantUsed: string;
+    seedUsed: CssColorString;
+};
+export declare function resolveBaseColor(query: ColorQuery, theme: ThemeConfig): BaseResolvedColor;
+export declare function resolveBaseColor(normalized: NormalizedQuery, theme: ThemeConfig): BaseResolvedColor;
+export {};

package/dist/engine/resolveBaseColor.js

@@ -0,0 +1,127 @@
+import { parseColor } from "../utils/parseColor.js";
+import { mapColorContextToEngine } from "./context.js";
+import { generateScale } from "./generateScale.js";
+import { normalizeQuery } from "./normalize.js";
+const isCategoryVariant = (variant) => variant.startsWith("category:");
+const isChartVariant = (variant) => variant.startsWith("chart:");
+const aliasVariants = new Set(["success", "warning", "danger", "info"]);
+const inferVariantFromRole = (role) => {
+    const normalizedRole = role.toLowerCase();
+    if (normalizedRole.startsWith("action.")) {
+        return "accent";
+    }
+    if (normalizedRole.startsWith("bg.") ||
+        normalizedRole.startsWith("surface.") ||
+        normalizedRole.startsWith("border.") ||
+        normalizedRole.startsWith("text.")) {
+        return "neutral";
+    }
+    return "neutral";
+};
+const resolveVariantSeed = (variant, role, config, contextKey) => {
+    if (variant) {
+        if (variant === "neutral" || variant === "accent") {
+            return {
+                variantUsed: variant,
+                seedUsed: config.seeds[contextKey][variant],
+            };
+        }
+        if (isCategoryVariant(variant) || isChartVariant(variant)) {
+            const customSeed = config.variants?.[variant];
+            if (customSeed) {
+                return { variantUsed: variant, seedUsed: customSeed };
+            }
+            return { variantUsed: "accent", seedUsed: config.seeds[contextKey].accent };
+        }
+        if (aliasVariants.has(variant)) {
+            return { variantUsed: "accent", seedUsed: config.seeds[contextKey].accent };
+        }
+        return { variantUsed: "accent", seedUsed: config.seeds[contextKey].accent };
+    }
+    const inferredVariant = inferVariantFromRole(role);
+    return {
+        variantUsed: inferredVariant,
+        seedUsed: config.seeds[contextKey][inferredVariant],
+    };
+};
+const clampStep = (value) => Math.min(12, Math.max(1, value));
+const resolveStep = (usage, surface) => {
+    switch (usage) {
+        case "bg": {
+            switch (surface) {
+                case "app":
+                    return 1;
+                case "surface":
+                    return 2;
+                case "subtle":
+                    return 3;
+                case "solid":
+                    return 9;
+                case "overlay":
+                    return 2;
+                case "data":
+                    return 9;
+                case "transparent":
+                    return 1;
+                default:
+                    return 2;
+            }
+        }
+        case "border": {
+            switch (surface) {
+                case "solid":
+                case "data":
+                    return 8;
+                default:
+                    return 6;
+            }
+        }
+        case "text":
+            return 11;
+        case "icon":
+            return 11;
+        case "ring":
+            return 8;
+        case "stroke":
+            return surface === "data" ? 9 : 8;
+        case "fill":
+            return 9;
+        default:
+            return 6;
+    }
+};
+// Best-effort guard: ColorQuery may include state/emphasis already; a branded flag
+// from normalizeQuery would be the strict approach in a future version.
+const isNormalizedQuery = (value) => typeof value === "object" &&
+    value !== null &&
+    typeof value.role === "string" &&
+    typeof value.usage === "string" &&
+    typeof value.surface === "string" &&
+    typeof value.context === "string" &&
+    typeof value.state === "string" &&
+    typeof value.emphasis === "string";
+export function resolveBaseColor(query, theme) {
+    const normalized = isNormalizedQuery(query) ? query : normalizeQuery(query);
+    const contextKey = mapColorContextToEngine(normalized.context);
+    const { variantUsed, seedUsed } = resolveVariantSeed(normalized.variant, normalized.role, theme, contextKey);
+    const parsedSeed = parseColor(seedUsed);
+    const seed = {
+        l: parsedSeed.okLch.channels[0] * 100,
+        c: parsedSeed.okLch.channels[1],
+        h: parsedSeed.okLch.channels[2],
+        alpha: parsedSeed.okLch.alpha,
+    };
+    const scale = generateScale(seed, {
+        context: contextKey,
+        surface: normalized.surface,
+        preset: theme.preset,
+    });
+    const step = clampStep(resolveStep(normalized.usage, normalized.surface));
+    const oklch = scale[step - 1];
+    return {
+        oklch,
+        step,
+        variantUsed,
+        seedUsed,
+    };
+}

package/dist/engine/resolveBaseColor.test.d.ts

@@ -0,0 +1 @@
+export {};

package/dist/engine/resolveBaseColor.test.js

@@ -0,0 +1,97 @@
+import { describe, expect, it } from "vitest";
+import { parseColor } from "../utils/parseColor.js";
+import { normalizeQuery } from "./normalize.js";
+import { resolveBaseColor } from "./resolveBaseColor.js";
+const themeConfig = {
+    seeds: {
+        light: { neutral: "#8B8D98", accent: "#3D63DD" },
+        dark: { neutral: "#8B8D98", accent: "#3D63DD" },
+    },
+    variants: {
+        "category:food": "#C2410C",
+    },
+    preset: "modern",
+};
+describe("resolveBaseColor", () => {
+    const r = (query) => resolveBaseColor(normalizeQuery(query), themeConfig);
+    it("defaults action roles to accent when variant is missing", () => {
+        const result = r({
+            role: "action.primary",
+            usage: "bg",
+            surface: "solid",
+            context: "light",
+        });
+        expect(result.variantUsed).toBe("accent");
+        expect(result.seedUsed).toBe(themeConfig.seeds.light.accent);
+    });
+    it("defaults text roles to neutral when variant is missing", () => {
+        const result = r({
+            role: "text.primary",
+            usage: "text",
+            surface: "surface",
+            context: "light",
+        });
+        expect(result.variantUsed).toBe("neutral");
+        expect(result.seedUsed).toBe(themeConfig.seeds.light.neutral);
+    });
+    it("uses custom category variants when provided", () => {
+        const result = r({
+            role: "bg.category",
+            variant: "category:food",
+            usage: "bg",
+            surface: "surface",
+            context: "light",
+        });
+        expect(result.variantUsed).toBe("category:food");
+        expect(result.seedUsed).toBe(themeConfig.variants?.["category:food"]);
+    });
+    it("falls back to accent for missing category variants", () => {
+        const result = r({
+            role: "bg.category",
+            variant: "category:missing",
+            usage: "bg",
+            surface: "surface",
+            context: "light",
+        });
+        expect(result.variantUsed).toBe("accent");
+        expect(result.seedUsed).toBe(themeConfig.seeds.light.accent);
+    });
+    it("chooses steps based on usage and surface", () => {
+        const appBg = r({ role: "bg.app", usage: "bg", surface: "app", context: "light" });
+        const solidBg = r({ role: "bg.solid", usage: "bg", surface: "solid", context: "light" });
+        const borderSurface = r({
+            role: "border.surface",
+            usage: "border",
+            surface: "surface",
+            context: "light",
+        });
+        const ring = r({ role: "ring.focus", usage: "ring", surface: "surface", context: "light" });
+        expect(appBg.step).toBe(1);
+        expect(solidBg.step).toBe(9);
+        expect(borderSurface.step).toBe(6);
+        expect(ring.step).toBe(8);
+    });
+    it("returns valid OKLCH values with stable hue", () => {
+        const result = r({
+            role: "action.primary",
+            usage: "bg",
+            surface: "solid",
+            context: "light",
+        });
+        const seed = parseColor(themeConfig.seeds.light.accent);
+        expect(result.oklch.l).toBeGreaterThanOrEqual(0);
+        expect(result.oklch.l).toBeLessThanOrEqual(100);
+        expect(result.oklch.c).toBeGreaterThanOrEqual(0);
+        expect(result.oklch.h).toBeCloseTo(seed.okLch.channels[2], 6);
+    });
+    it("accepts normalized queries without re-normalizing", () => {
+        const normalized = normalizeQuery({
+            role: "text.secondary",
+            usage: "text",
+            surface: "surface",
+            context: "dark",
+        });
+        const result = resolveBaseColor(normalized, themeConfig);
+        expect(result.step).toBe(11);
+    });
+});

package/dist/export/__snapshots__/exportTheme.test.js.snap

@@ -0,0 +1,74 @@
+// Vitest Snapshot v1, https://vitest.dev/guide/snapshot.html
+
+exports[`exportTheme > exports deterministic CSS with @supports overrides 1`] = `
+":root {
+  --pk-bg-app: #dddee1;
+  --pk-custom-alias: #f1f4fb;
+  --pk-text-primary: #f1f4fb;
+}
+
+@supports (color: oklch(0% 0 0)) {
+  :root {
+    --pk-bg-app: oklch(90% 0.004 264.7);
+    --pk-bg-app-oklch: oklch(90% 0.004 264.7);
+    --pk-custom-alias: oklch(96.7% 0.01 264.7);
+    --pk-custom-alias-oklch: oklch(96.7% 0.01 264.7);
+    --pk-text-primary: oklch(96.7% 0.01 264.7);
+    --pk-text-primary-oklch: oklch(96.7% 0.01 264.7);
+  }
+}
+
+@supports (color: color(display-p3 1 1 1)) {
+  :root {
+    --pk-bg-app-p3: color(display-p3 0.866 0.87 0.88);
+    --pk-custom-alias-p3: color(display-p3 0.947 0.957 0.981);
+    --pk-text-primary-p3: color(display-p3 0.947 0.957 0.981);
+  }
+}
+"
+`;
+
+exports[`exportTheme > exports deterministic JSON with light/dark contexts 1`] = `
+{
+  "dark": {
+    "bg.app": {
+      "alpha": 1,
+      "oklch": "oklch(6% 0.004 264.7)",
+      "srgb": "#010101",
+      "value": "oklch(6% 0.004 264.7)",
+    },
+    "custom.alias": {
+      "alpha": 1,
+      "oklch": "oklch(27.5% 0.01 264.7)",
+      "srgb": "#25282d",
+      "value": "oklch(27.5% 0.01 264.7)",
+    },
+    "text.primary": {
+      "alpha": 1,
+      "oklch": "oklch(27.5% 0.01 264.7)",
+      "srgb": "#25282d",
+      "value": "oklch(27.5% 0.01 264.7)",
+    },
+  },
+  "light": {
+    "bg.app": {
+      "alpha": 1,
+      "oklch": "oklch(90% 0.004 264.7)",
+      "srgb": "#dddee1",
+      "value": "oklch(90% 0.004 264.7)",
+    },
+    "custom.alias": {
+      "alpha": 1,
+      "oklch": "oklch(96.7% 0.01 264.7)",
+      "srgb": "#f1f4fb",
+      "value": "oklch(96.7% 0.01 264.7)",
+    },
+    "text.primary": {
+      "alpha": 1,
+      "oklch": "oklch(96.7% 0.01 264.7)",
+      "srgb": "#f1f4fb",
+      "value": "oklch(96.7% 0.01 264.7)",
+    },
+  },
+}
+`;

package/dist/export/exportTheme.d.ts

@@ -0,0 +1,47 @@
+import type { OkLchColor } from "../engine/generateScale.js";
+import type { ColorMeta, ColorQuery, OutputOptions } from "../types/index.js";
+export type ThemeToken = Omit<ColorQuery, "role" | "output"> & {
+    role?: string;
+};
+export type ThemeTokens = Record<string, ThemeToken>;
+export type ExportableTheme = {
+    resolve: (query: ColorQuery) => {
+        oklch: OkLchColor;
+    };
+};
+export type TokenValue = {
+    value: string;
+    srgb?: string;
+    p3?: string;
+    oklch?: string;
+    alpha: number;
+    meta?: ColorMeta;
+};
+export type ExportMeta = {
+    gamutMapping: NonNullable<OutputOptions["gamutMapping"]>;
+    preferSpace: NonNullable<OutputOptions["preferSpace"]>;
+    includeSpaces: NonNullable<OutputOptions["includeSpaces"]>;
+    precision: Required<NonNullable<OutputOptions["precision"]>>;
+    srgbFormat: NonNullable<OutputOptions["srgbFormat"]>;
+    strict: boolean;
+};
+/**
+ * Export CSS variables for a token map with progressive fallbacks.
+ *
+ * - Base output uses sRGB for maximum compatibility.
+ * - @supports blocks override the main token value with OKLCH and/or P3 as requested.
+ */
+export declare const exportThemeCss: (theme: ExportableTheme, tokens: ThemeTokens, output?: OutputOptions) => {
+    css: string;
+    meta: ExportMeta | undefined;
+};
+/**
+ * Export JSON tokens for both light and dark contexts.
+ */
+export declare const exportThemeJson: (theme: ExportableTheme, tokens: ThemeTokens, output?: OutputOptions) => {
+    tokens: {
+        light: Record<string, TokenValue>;
+        dark: Record<string, TokenValue>;
+    };
+    meta: ExportMeta | undefined;
+};