@clhaas/palette-kit 0.1.0 → 0.1.2

package/README.md

@@ -23,10 +23,11 @@ pnpm add @clhaas/palette-kit
 - 12-step scale (light/dark) from a seed.
 - Semantic tokens for UI (`radix-like-ui` preset).
 - Alpha scale for overlays.
-- Exporters for TS, JSON, and CSS vars.
+- Exporters for TS, JSON, CSS vars, Tailwind, and React Native.
+- Auto anchor selection per mode (light/dark), overridable via `anchorStep`.
 - Basic contrast and gamut diagnostics.
 
-## Usage example (planned API)
+## Usage example
 
 ```ts
 import { createTheme } from "@clhaas/palette-kit";
@@ -40,7 +41,7 @@ const theme = createTheme({
     danger: { source: "seed", value: "#ef4444" },
   },
   tokens: { preset: "radix-like-ui" },
-  output: { format: "css", cssVarPrefix: "pk" },
+  p3: true,
 });
 ```
 

package/dist/alpha/generateAlphaScale.d.ts

@@ -0,0 +1,5 @@
+import type { AlphaScale, ColorHex } from "../types.js";
+export declare function generateAlphaScale(base: ColorHex, _background: {
+    light: ColorHex;
+    dark: ColorHex;
+}): AlphaScale;

package/dist/alpha/generateAlphaScale.js

@@ -0,0 +1,34 @@
+import Color from "colorjs.io";
+const steps = [1, 2, 3, 4, 5, 6, 7, 8, 9, 10, 11, 12];
+const alphaCurve = {
+    1: 0.05,
+    2: 0.1,
+    3: 0.15,
+    4: 0.2,
+    5: 0.3,
+    6: 0.4,
+    7: 0.5,
+    8: 0.6,
+    9: 0.7,
+    10: 0.8,
+    11: 0.9,
+    12: 0.95,
+};
+function mixWithAlpha(foreground, alpha) {
+    const color = new Color(foreground).to("srgb");
+    const [r, g, b] = color.coords;
+    const hex = new Color({ space: "srgb", coords: [r, g, b], alpha }).toString({
+        format: "hex",
+    });
+    return hex;
+}
+export function generateAlphaScale(base, _background) {
+    const light = {};
+    const dark = {};
+    for (const step of steps) {
+        const alpha = alphaCurve[step];
+        light[step] = mixWithAlpha(base, alpha);
+        dark[step] = mixWithAlpha(base, alpha);
+    }
+    return { light, dark };
+}

package/dist/contrast/apca.d.ts

@@ -0,0 +1,2 @@
+import type { ColorHex } from "../types.js";
+export declare function apcaContrast(foreground: ColorHex, background: ColorHex): number;

package/dist/contrast/apca.js

@@ -0,0 +1,5 @@
+import { calcAPCA } from "apca-w3";
+export function apcaContrast(foreground, background) {
+    const contrast = Number(calcAPCA(foreground, background));
+    return Number(contrast.toFixed(2));
+}

package/dist/contrast/onSolid.d.ts

@@ -0,0 +1,6 @@
+import type { ColorHex } from "../types.js";
+export declare function onSolidTextTokens(background: ColorHex): {
+    primary: ColorHex;
+    secondary: ColorHex;
+    disabled: ColorHex;
+};

package/dist/contrast/onSolid.js

@@ -0,0 +1,28 @@
+import { apcaContrast } from "./apca.js";
+const white = "#ffffff";
+const black = "#000000";
+const alphaLevels = {
+    primary: 0.92,
+    secondary: 0.72,
+    disabled: 0.48,
+};
+function withAlpha(hex, alpha) {
+    const normalized = hex.replace("#", "");
+    const alphaHex = Math.round(alpha * 255)
+        .toString(16)
+        .padStart(2, "0");
+    return `#${normalized}${alphaHex}`;
+}
+function chooseTextColor(background) {
+    const whiteScore = Math.abs(apcaContrast(white, background));
+    const blackScore = Math.abs(apcaContrast(black, background));
+    return whiteScore >= blackScore ? white : black;
+}
+export function onSolidTextTokens(background) {
+    const base = chooseTextColor(background);
+    return {
+        primary: withAlpha(base, alphaLevels.primary),
+        secondary: withAlpha(base, alphaLevels.secondary),
+        disabled: withAlpha(base, alphaLevels.disabled),
+    };
+}

package/dist/contrast/solveText.d.ts

@@ -0,0 +1,2 @@
+import type { ColorHex } from "../types.js";
+export declare function adjustTextColor(foreground: ColorHex, background: ColorHex, target: number): ColorHex;

package/dist/contrast/solveText.js

@@ -0,0 +1,31 @@
+import Color from "colorjs.io";
+import { compressToSrgb, oklchToHex } from "../engine/oklch.js";
+import { apcaContrast } from "./apca.js";
+function clamp(value, min, max) {
+    return Math.min(max, Math.max(min, value));
+}
+function adjustLightness(oklch, background, target, maxIterations = 24) {
+    const bg = new Color(background).to("oklch");
+    const bgL = bg.coords[0] ?? 0;
+    const direction = bgL > 0.5 ? -1 : 1;
+    let current = { ...oklch };
+    for (let i = 0; i < maxIterations; i += 1) {
+        const contrast = Math.abs(apcaContrast(oklchToHex(current), background));
+        if (contrast >= target) {
+            return current;
+        }
+        current = {
+            ...current,
+            l: clamp(current.l + direction * 0.02, 0, 1),
+        };
+    }
+    return current;
+}
+export function adjustTextColor(foreground, background, target) {
+    const fg = new Color(foreground).to("oklch");
+    const [l, c, h] = fg.coords;
+    let candidate = { l: l ?? 0, c: c ?? 0, h: h ?? 0 };
+    candidate = adjustLightness(candidate, background, target);
+    candidate = compressToSrgb(candidate);
+    return oklchToHex(candidate);
+}

package/dist/createTheme.d.ts

@@ -0,0 +1,34 @@
+import type { GenerateScaleOptions } from "./generateScale.js";
+import type { ColorHex, ColorSource, Theme } from "./types.js";
+export type TokenOverrides = {
+    light?: Record<string, ColorHex>;
+    dark?: Record<string, ColorHex>;
+};
+export type CreateThemeOptions = {
+    neutral: ColorSource;
+    accent: ColorSource;
+    semantic?: {
+        success?: ColorSource;
+        warning?: ColorSource;
+        danger?: ColorSource;
+    };
+    extras?: Record<string, ColorSource>;
+    tokens?: {
+        preset?: "radix-like-ui";
+        overrides?: TokenOverrides;
+    };
+    alpha?: {
+        enabled?: boolean;
+        background?: {
+            light?: ColorHex;
+            dark?: ColorHex;
+        };
+    };
+    contrast?: {
+        textPrimary?: number;
+        textSecondary?: number;
+    };
+    scale?: Omit<GenerateScaleOptions, "source" | "mode" | "p3">;
+    p3?: boolean;
+};
+export declare function createTheme(options: CreateThemeOptions): Theme;

package/dist/createTheme.js

@@ -0,0 +1,88 @@
+import { generateAlphaScale } from "./alpha/generateAlphaScale.js";
+import { onSolidTextTokens } from "./contrast/onSolid.js";
+import { adjustTextColor } from "./contrast/solveText.js";
+import { analyzeTheme } from "./diagnostics/analyzeTheme.js";
+import { generateScale } from "./generateScale.js";
+import { buildPresetTokens } from "./tokens/presetRadixLikeUi.js";
+export function createTheme(options) {
+    const includeP3 = options.p3 ?? false;
+    const scaleOptions = options.scale ?? {};
+    const scales = {
+        neutral: generateScale({ source: options.neutral, ...scaleOptions, p3: includeP3 }),
+        accent: generateScale({ source: options.accent, ...scaleOptions, p3: includeP3 }),
+    };
+    if (options.semantic?.success) {
+        scales.success = generateScale({
+            source: options.semantic.success,
+            ...scaleOptions,
+            p3: includeP3,
+        });
+    }
+    if (options.semantic?.warning) {
+        scales.warning = generateScale({
+            source: options.semantic.warning,
+            ...scaleOptions,
+            p3: includeP3,
+        });
+    }
+    if (options.semantic?.danger) {
+        scales.danger = generateScale({
+            source: options.semantic.danger,
+            ...scaleOptions,
+            p3: includeP3,
+        });
+    }
+    if (options.extras) {
+        for (const [key, source] of Object.entries(options.extras)) {
+            scales[key] = generateScale({ source, ...scaleOptions, p3: includeP3 });
+        }
+    }
+    const preset = options.tokens?.preset ?? "radix-like-ui";
+    const tokens = preset === "radix-like-ui" ? buildPresetTokens(scales) : { light: {}, dark: {} };
+    const lightBg = tokens.light["bg.app"];
+    const darkBg = tokens.dark["bg.app"];
+    const textPrimaryTarget = options.contrast?.textPrimary ?? 75;
+    const textSecondaryTarget = options.contrast?.textSecondary ?? 60;
+    if (lightBg && tokens.light["text.primary"]) {
+        tokens.light["text.primary"] = adjustTextColor(tokens.light["text.primary"], lightBg, textPrimaryTarget);
+    }
+    if (lightBg && tokens.light["text.secondary"]) {
+        tokens.light["text.secondary"] = adjustTextColor(tokens.light["text.secondary"], lightBg, textSecondaryTarget);
+    }
+    if (darkBg && tokens.dark["text.primary"]) {
+        tokens.dark["text.primary"] = adjustTextColor(tokens.dark["text.primary"], darkBg, textPrimaryTarget);
+    }
+    if (darkBg && tokens.dark["text.secondary"]) {
+        tokens.dark["text.secondary"] = adjustTextColor(tokens.dark["text.secondary"], darkBg, textSecondaryTarget);
+    }
+    const accentScale = scales.accent;
+    const lightOnSolid = onSolidTextTokens(accentScale.light[9]);
+    const darkOnSolid = onSolidTextTokens(accentScale.dark[9]);
+    tokens.light["onSolid.primary"] = lightOnSolid.primary;
+    tokens.light["onSolid.secondary"] = lightOnSolid.secondary;
+    tokens.light["onSolid.disabled"] = lightOnSolid.disabled;
+    tokens.dark["onSolid.primary"] = darkOnSolid.primary;
+    tokens.dark["onSolid.secondary"] = darkOnSolid.secondary;
+    tokens.dark["onSolid.disabled"] = darkOnSolid.disabled;
+    if (options.tokens?.overrides?.light) {
+        Object.assign(tokens.light, options.tokens.overrides.light);
+    }
+    if (options.tokens?.overrides?.dark) {
+        Object.assign(tokens.dark, options.tokens.overrides.dark);
+    }
+    let alpha;
+    if (options.alpha?.enabled !== false) {
+        const background = {
+            light: options.alpha?.background?.light ?? "#ffffff",
+            dark: options.alpha?.background?.dark ?? "#111111",
+        };
+        alpha = generateAlphaScale(accentScale.light[9], background);
+    }
+    const diagnostics = analyzeTheme({ scales, tokens, alpha });
+    return {
+        scales,
+        tokens,
+        alpha,
+        diagnostics,
+    };
+}

package/dist/data/radixSeeds.d.ts

@@ -0,0 +1,3 @@
+import type { ColorHex, RadixSeedName } from "../types.js";
+export declare const radixSeeds: Record<RadixSeedName, ColorHex>;
+export declare const radixSeedNames: string[];

package/dist/data/radixSeeds.js

@@ -0,0 +1,34 @@
+export const radixSeeds = {
+    amber: "#ffc53d",
+    blue: "#0090ff",
+    bronze: "#a18072",
+    brown: "#ad7f58",
+    crimson: "#e93d82",
+    cyan: "#00a2c7",
+    gold: "#978365",
+    grass: "#46a758",
+    gray: "#8d8d8d",
+    green: "#30a46c",
+    indigo: "#3e63dd",
+    iris: "#5b5bd6",
+    jade: "#29a383",
+    lime: "#bdee63",
+    mauve: "#8e8c99",
+    mint: "#86ead4",
+    olive: "#898e87",
+    orange: "#f76b15",
+    pink: "#d6409f",
+    plum: "#ab4aba",
+    purple: "#8e4ec6",
+    red: "#e5484d",
+    ruby: "#e54666",
+    sage: "#868e8b",
+    sand: "#8d8d86",
+    sky: "#7ce2fe",
+    slate: "#8b8d98",
+    teal: "#12a594",
+    tomato: "#e54d2e",
+    violet: "#6e56cf",
+    yellow: "#ffe629",
+};
+export const radixSeedNames = Object.keys(radixSeeds).sort();

package/dist/diagnostics/analyzeScale.d.ts

@@ -0,0 +1,2 @@
+import type { Scale, ScaleDiagnostics } from "../types.js";
+export declare function analyzeScale(scale: Scale): ScaleDiagnostics;

package/dist/diagnostics/analyzeScale.js

@@ -0,0 +1,7 @@
+export function analyzeScale(scale) {
+    return {
+        outOfGamutCount: scale.meta?.outOfGamutCount ?? 0,
+        outOfP3GamutCount: scale.meta?.outOfP3GamutCount ?? 0,
+        anchorSteps: scale.meta?.anchorSteps,
+    };
+}

package/dist/diagnostics/analyzeTheme.d.ts

@@ -0,0 +1,2 @@
+import type { Theme, ThemeDiagnostics } from "../types.js";
+export declare function analyzeTheme(theme: Theme): ThemeDiagnostics;

package/dist/diagnostics/analyzeTheme.js

@@ -0,0 +1,35 @@
+import { apcaContrast } from "../contrast/apca.js";
+import { analyzeWarnings } from "./warnings.js";
+export function analyzeTheme(theme) {
+    const contrast = {};
+    const lightBg = theme.tokens.light["bg.app"];
+    const darkBg = theme.tokens.dark["bg.app"];
+    if (lightBg) {
+        if (theme.tokens.light["text.primary"]) {
+            contrast["light.text.primary"] = apcaContrast(theme.tokens.light["text.primary"], lightBg);
+        }
+        if (theme.tokens.light["text.secondary"]) {
+            contrast["light.text.secondary"] = apcaContrast(theme.tokens.light["text.secondary"], lightBg);
+        }
+    }
+    if (darkBg) {
+        if (theme.tokens.dark["text.primary"]) {
+            contrast["dark.text.primary"] = apcaContrast(theme.tokens.dark["text.primary"], darkBg);
+        }
+        if (theme.tokens.dark["text.secondary"]) {
+            contrast["dark.text.secondary"] = apcaContrast(theme.tokens.dark["text.secondary"], darkBg);
+        }
+    }
+    if (theme.tokens.light["onSolid.primary"] && theme.tokens.light["accent.solid"]) {
+        contrast["light.onSolid.primary"] = apcaContrast(theme.tokens.light["onSolid.primary"], theme.tokens.light["accent.solid"]);
+    }
+    if (theme.tokens.dark["onSolid.primary"] && theme.tokens.dark["accent.solid"]) {
+        contrast["dark.onSolid.primary"] = apcaContrast(theme.tokens.dark["onSolid.primary"], theme.tokens.dark["accent.solid"]);
+    }
+    let outOfGamutCount = 0;
+    for (const scale of Object.values(theme.scales)) {
+        outOfGamutCount += scale.meta?.outOfGamutCount ?? 0;
+    }
+    const warnings = analyzeWarnings(theme);
+    return { contrast, outOfGamutCount, warnings };
+}

package/dist/diagnostics/warnings.d.ts

@@ -0,0 +1,2 @@
+import type { Theme } from "../types.js";
+export declare function analyzeWarnings(theme: Theme): string[];

package/dist/diagnostics/warnings.js

@@ -0,0 +1,20 @@
+import Color from "colorjs.io";
+export function analyzeWarnings(theme) {
+    const warnings = [];
+    const accent = theme.scales.accent?.light?.[9];
+    if (accent) {
+        const { coords } = new Color(accent).to("oklch");
+        const l = coords[0] ?? 0;
+        const c = coords[1] ?? 0;
+        if (c < 0.03) {
+            warnings.push("Accent seed has very low chroma; the palette may look gray.");
+        }
+        if (l < 0.2) {
+            warnings.push("Accent seed is very dark; light mode solids may lack contrast.");
+        }
+        if (l > 0.9) {
+            warnings.push("Accent seed is very light; dark mode solids may lack contrast.");
+        }
+    }
+    return warnings;
+}

package/dist/engine/curves.d.ts

@@ -0,0 +1,9 @@
+import type { Step } from "../types.js";
+export type CurveConfig = {
+    lightness?: Partial<Record<Step, number>>;
+    chroma?: Partial<Record<Step, number>>;
+};
+export declare function resolveCurves(curves?: CurveConfig): {
+    lightness: Record<Step, number>;
+    chroma: Record<Step, number>;
+};

package/dist/engine/curves.js

@@ -0,0 +1,48 @@
+const steps = [1, 2, 3, 4, 5, 6, 7, 8, 9, 10, 11, 12];
+const defaultLightness = {
+    1: 0.3,
+    2: 0.3,
+    3: 0.6,
+    4: 0.6,
+    5: 0.6,
+    6: 0.85,
+    7: 0.85,
+    8: 0.85,
+    9: 1,
+    10: 1,
+    11: 1,
+    12: 1,
+};
+const defaultChroma = {
+    1: 0.2,
+    2: 0.2,
+    3: 0.6,
+    4: 0.6,
+    5: 0.6,
+    6: 0.8,
+    7: 0.8,
+    8: 0.8,
+    9: 1,
+    10: 1,
+    11: 0.7,
+    12: 0.7,
+};
+export function resolveCurves(curves) {
+    const lightness = { ...defaultLightness };
+    const chroma = { ...defaultChroma };
+    if (curves?.lightness) {
+        for (const step of steps) {
+            if (curves.lightness[step] !== undefined) {
+                lightness[step] = curves.lightness[step];
+            }
+        }
+    }
+    if (curves?.chroma) {
+        for (const step of steps) {
+            if (curves.chroma[step] !== undefined) {
+                chroma[step] = curves.chroma[step];
+            }
+        }
+    }
+    return { lightness, chroma };
+}

package/dist/engine/oklch.d.ts

@@ -0,0 +1,8 @@
+import type { ColorHex, ColorP3, OklchColor } from "../types.js";
+export declare function hexToOklch(hex: ColorHex): OklchColor;
+export declare function oklchToHex(oklch: OklchColor): ColorHex;
+export declare function inSrgbGamut(oklch: OklchColor): boolean;
+export declare function compressToSrgb(oklch: OklchColor): OklchColor;
+export declare function inP3Gamut(oklch: OklchColor): boolean;
+export declare function compressToP3(oklch: OklchColor): OklchColor;
+export declare function oklchToP3(oklch: OklchColor): ColorP3;

package/dist/engine/oklch.js

@@ -0,0 +1,40 @@
+import Color from "colorjs.io";
+export function hexToOklch(hex) {
+    const color = new Color(hex).to("oklch");
+    const [l, c, h] = color.coords;
+    return { l: l ?? 0, c: c ?? 0, h: h ?? 0 };
+}
+export function oklchToHex(oklch) {
+    const color = new Color("oklch", [oklch.l, oklch.c, oklch.h]);
+    return color.to("srgb").toString({ format: "hex" });
+}
+export function inSrgbGamut(oklch) {
+    const color = new Color("oklch", [oklch.l, oklch.c, oklch.h]);
+    return color.inGamut("srgb");
+}
+export function compressToSrgb(oklch) {
+    let current = { ...oklch };
+    let iterations = 0;
+    while (!inSrgbGamut(current) && current.c > 0 && iterations < 40) {
+        current = { ...current, c: current.c * 0.95 };
+        iterations += 1;
+    }
+    return current;
+}
+export function inP3Gamut(oklch) {
+    const color = new Color("oklch", [oklch.l, oklch.c, oklch.h]);
+    return color.inGamut("p3");
+}
+export function compressToP3(oklch) {
+    let current = { ...oklch };
+    let iterations = 0;
+    while (!inP3Gamut(current) && current.c > 0 && iterations < 40) {
+        current = { ...current, c: current.c * 0.95 };
+        iterations += 1;
+    }
+    return current;
+}
+export function oklchToP3(oklch) {
+    const color = new Color("oklch", [oklch.l, oklch.c, oklch.h]);
+    return color.to("p3").toString({ format: "color" });
+}

package/dist/engine/templates.d.ts

@@ -0,0 +1,14 @@
+import type { OklchColor, Step, TemplateId } from "../types.js";
+export declare const templates: {
+    light: {
+        neutral: Record<Step, OklchColor>;
+        warm: Record<Step, OklchColor>;
+        cool: Record<Step, OklchColor>;
+    };
+    dark: {
+        neutral: Record<Step, OklchColor>;
+        warm: Record<Step, OklchColor>;
+        cool: Record<Step, OklchColor>;
+    };
+};
+export declare function selectTemplateId(oklch: OklchColor): TemplateId;

package/dist/engine/templates.js

@@ -0,0 +1,45 @@
+const steps = [1, 2, 3, 4, 5, 6, 7, 8, 9, 10, 11, 12];
+const lightnessLight = [0.99, 0.975, 0.95, 0.92, 0.89, 0.84, 0.77, 0.68, 0.58, 0.5, 0.4, 0.3];
+const lightnessDark = [0.12, 0.14, 0.18, 0.22, 0.26, 0.32, 0.4, 0.48, 0.58, 0.66, 0.76, 0.86];
+const chromaNeutral = [
+    0.01, 0.012, 0.016, 0.02, 0.024, 0.03, 0.04, 0.05, 0.055, 0.045, 0.035, 0.028,
+];
+const chromaWarm = [0.02, 0.03, 0.05, 0.08, 0.12, 0.16, 0.18, 0.2, 0.22, 0.19, 0.12, 0.08];
+const chromaCool = [0.02, 0.03, 0.05, 0.075, 0.1, 0.14, 0.17, 0.19, 0.21, 0.18, 0.11, 0.08];
+const baseHue = {
+    neutral: 250,
+    warm: 40,
+    cool: 220,
+};
+function buildTemplate(lightness, chroma, hue) {
+    const output = {};
+    for (let i = 0; i < steps.length; i += 1) {
+        const step = steps[i];
+        output[step] = {
+            l: lightness[i],
+            c: chroma[i],
+            h: hue,
+        };
+    }
+    return output;
+}
+export const templates = {
+    light: {
+        neutral: buildTemplate(lightnessLight, chromaNeutral, baseHue.neutral),
+        warm: buildTemplate(lightnessLight, chromaWarm, baseHue.warm),
+        cool: buildTemplate(lightnessLight, chromaCool, baseHue.cool),
+    },
+    dark: {
+        neutral: buildTemplate(lightnessDark, chromaNeutral, baseHue.neutral),
+        warm: buildTemplate(lightnessDark, chromaWarm, baseHue.warm),
+        cool: buildTemplate(lightnessDark, chromaCool, baseHue.cool),
+    },
+};
+export function selectTemplateId(oklch) {
+    if (oklch.c < 0.05) {
+        return "neutral";
+    }
+    const hue = ((oklch.h % 360) + 360) % 360;
+    const isWarm = hue <= 60 || hue >= 330;
+    return isWarm ? "warm" : "cool";
+}

package/dist/exporters/selectColorMode.d.ts

@@ -0,0 +1,2 @@
+import type { Theme, ThemeColorMode } from "../types.js";
+export declare function selectThemeColorMode(theme: Theme, mode: "srgb" | "p3"): ThemeColorMode;

package/dist/exporters/selectColorMode.js

@@ -0,0 +1,19 @@
+export function selectThemeColorMode(theme, mode) {
+    if (mode === "srgb") {
+        return theme;
+    }
+    const scales = Object.fromEntries(Object.entries(theme.scales).map(([slot, scale]) => {
+        if (!scale.p3) {
+            return [slot, scale];
+        }
+        return [
+            slot,
+            {
+                ...scale,
+                light: scale.p3.light,
+                dark: scale.p3.dark,
+            },
+        ];
+    }));
+    return { ...theme, scales };
+}

package/dist/exporters/toCssVars.d.ts

@@ -0,0 +1,12 @@
+import type { Theme } from "../types.js";
+type CssVarsOptions = {
+    prefix?: string;
+    includeTokens?: boolean;
+    includeScales?: boolean;
+    includeAlpha?: boolean;
+    includeP3?: boolean;
+    lightSelector?: string;
+    darkSelector?: string;
+};
+export declare function toCssVars(theme: Theme, options?: CssVarsOptions): string;
+export {};