@clhaas/palette-kit 0.1.1 → 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/createTheme.d.ts

@@ -1,3 +1,4 @@
+import type { GenerateScaleOptions } from "./generateScale.js";
 import type { ColorHex, ColorSource, Theme } from "./types.js";
 export type TokenOverrides = {
     light?: Record<string, ColorHex>;
@@ -27,6 +28,7 @@ export type CreateThemeOptions = {
         textPrimary?: number;
         textSecondary?: number;
     };
+    scale?: Omit<GenerateScaleOptions, "source" | "mode" | "p3">;
     p3?: boolean;
 };
 export declare function createTheme(options: CreateThemeOptions): Theme;

package/dist/createTheme.js

@@ -6,22 +6,35 @@ 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, p3: includeP3 }),
-        accent: generateScale({ source: options.accent, p3: includeP3 }),
+        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, p3: includeP3 });
+        scales.success = generateScale({
+            source: options.semantic.success,
+            ...scaleOptions,
+            p3: includeP3,
+        });
     }
     if (options.semantic?.warning) {
-        scales.warning = generateScale({ source: options.semantic.warning, p3: includeP3 });
+        scales.warning = generateScale({
+            source: options.semantic.warning,
+            ...scaleOptions,
+            p3: includeP3,
+        });
     }
     if (options.semantic?.danger) {
-        scales.danger = generateScale({ source: options.semantic.danger, p3: includeP3 });
+        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, p3: includeP3 });
+            scales[key] = generateScale({ source, ...scaleOptions, p3: includeP3 });
         }
     }
     const preset = options.tokens?.preset ?? "radix-like-ui";

package/dist/diagnostics/analyzeScale.js

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

package/dist/generateScale.d.ts

@@ -1,9 +1,43 @@
 import { type CurveConfig } from "./engine/curves.js";
 import type { ColorSource, Scale, Step, TemplateId } from "./types.js";
-type GenerateScaleOptions = {
+export type AnchorStepOption = Step | "auto" | {
+    light?: Step | "auto";
+    dark?: Step | "auto";
+};
+export type AutoAnchorModeOptions = {
+    candidateSteps?: Step[];
+    backgroundStep?: Step;
+    backgroundSteps?: Step[];
+    solidStep?: Step;
+    textStep?: Step;
+    targetContrast?: number;
+    minBackgroundL?: number;
+    maxBackgroundL?: number;
+    minTextL?: number;
+    maxTextL?: number;
+};
+export type AutoAnchorOptions = {
+    candidateSteps?: Step[];
+    light?: AutoAnchorModeOptions;
+    dark?: AutoAnchorModeOptions;
+};
+export type SeedNormalizeRange = {
+    minL?: number;
+    maxL?: number;
+    minC?: number;
+    maxC?: number;
+};
+export type SeedNormalizeOptions = {
+    enabled?: boolean;
+    light?: SeedNormalizeRange;
+    dark?: SeedNormalizeRange;
+};
+export type GenerateScaleOptions = {
     source: ColorSource;
     mode?: "light" | "dark" | "both";
-    anchorStep?: Step;
+    anchorStep?: AnchorStepOption;
+    autoAnchor?: AutoAnchorOptions;
+    seedNormalize?: SeedNormalizeOptions;
     template?: "auto" | TemplateId;
     curves?: CurveConfig;
     gamut?: {
@@ -12,4 +46,3 @@ type GenerateScaleOptions = {
     p3?: boolean;
 };
 export declare function generateScale(options: GenerateScaleOptions): Scale;
-export {};

package/dist/generateScale.js

@@ -1,8 +1,45 @@
+import { apcaContrast } from "./contrast/apca.js";
+import { onSolidTextTokens } from "./contrast/onSolid.js";
 import { radixSeeds } from "./data/radixSeeds.js";
 import { resolveCurves } from "./engine/curves.js";
 import { compressToP3, compressToSrgb, hexToOklch, inP3Gamut, inSrgbGamut, oklchToHex, oklchToP3, } from "./engine/oklch.js";
 import { selectTemplateId, templates } from "./engine/templates.js";
 const steps = [1, 2, 3, 4, 5, 6, 7, 8, 9, 10, 11, 12];
+const defaultAutoAnchor = {
+    candidateSteps: [8, 9, 10],
+    light: {
+        backgroundStep: 1,
+        backgroundSteps: [1, 2, 3],
+        solidStep: 9,
+        textStep: 12,
+        targetContrast: 90,
+        minBackgroundL: 0.86,
+        maxBackgroundL: 0.98,
+        minTextL: 0.22,
+        maxTextL: 0.55,
+    },
+    dark: {
+        backgroundStep: 1,
+        backgroundSteps: [1, 2, 3],
+        solidStep: 9,
+        textStep: 12,
+        targetContrast: 75,
+        minBackgroundL: 0.1,
+        maxBackgroundL: 0.32,
+        minTextL: 0.75,
+        maxTextL: 0.98,
+    },
+};
+const defaultSeedNormalize = {
+    light: {
+        minL: 0.35,
+        maxL: 0.9,
+    },
+    dark: {
+        minL: 0.32,
+        maxL: 0.82,
+    },
+};
 function getSeedHex(source) {
     if (source.source === "seed") {
         return source.value;
@@ -17,13 +54,122 @@ function normalizeHue(hue) {
     const normalized = ((hue % 360) + 360) % 360;
     return normalized;
 }
-function buildScaleForMode(seedHex, templateId, anchorStep, curves, gamutStrategy = "compress", mode = "light", includeP3 = false) {
-    const seedOklch = hexToOklch(seedHex);
+function clampValue(value, min, max) {
+    let current = value;
+    if (min !== undefined) {
+        current = Math.max(min, current);
+    }
+    if (max !== undefined) {
+        current = Math.min(max, current);
+    }
+    return current;
+}
+function normalizeSeed(seed, range) {
+    const l = clampValue(seed.l, range.minL, range.maxL);
+    const c = clampValue(seed.c, range.minC, range.maxC);
+    return {
+        l,
+        c: Math.max(0, c),
+        h: seed.h,
+    };
+}
+function resolveAnchorOption(option, mode) {
+    if (!option) {
+        return undefined;
+    }
+    if (typeof option === "object") {
+        return option[mode];
+    }
+    return option;
+}
+function resolveSeedNormalizeOptions(options, autoEnabled) {
+    const enabled = options?.enabled ?? autoEnabled;
+    return {
+        enabled,
+        light: { ...defaultSeedNormalize.light, ...options?.light },
+        dark: { ...defaultSeedNormalize.dark, ...options?.dark },
+    };
+}
+function resolveCandidateSteps(candidateSteps) {
+    const unique = Array.from(new Set(candidateSteps ?? defaultAutoAnchor.candidateSteps));
+    return unique.length > 0 ? unique : [9];
+}
+function resolveAutoAnchorModeOptions(base, overrides, candidateSteps) {
+    const resolvedCandidates = resolveCandidateSteps(overrides?.candidateSteps ?? candidateSteps);
+    const resolvedBackgroundStep = overrides?.backgroundStep ?? base.backgroundStep;
+    const resolvedBackgroundSteps = overrides?.backgroundSteps ?? base.backgroundSteps;
+    return {
+        candidateSteps: resolvedCandidates,
+        backgroundStep: resolvedBackgroundStep,
+        backgroundSteps: resolvedBackgroundSteps.length > 0 ? resolvedBackgroundSteps : [resolvedBackgroundStep],
+        solidStep: overrides?.solidStep ?? base.solidStep,
+        textStep: overrides?.textStep ?? base.textStep,
+        targetContrast: overrides?.targetContrast ?? base.targetContrast,
+        minBackgroundL: overrides?.minBackgroundL ?? base.minBackgroundL,
+        maxBackgroundL: overrides?.maxBackgroundL ?? base.maxBackgroundL,
+        minTextL: overrides?.minTextL ?? base.minTextL,
+        maxTextL: overrides?.maxTextL ?? base.maxTextL,
+    };
+}
+function resolveAutoAnchorOptions(options) {
+    const candidateSteps = resolveCandidateSteps(options?.candidateSteps);
+    return {
+        light: resolveAutoAnchorModeOptions(defaultAutoAnchor.light, options?.light, candidateSteps),
+        dark: resolveAutoAnchorModeOptions(defaultAutoAnchor.dark, options?.dark, candidateSteps),
+    };
+}
+function rangePenalty(value, min, max, weight = 100) {
+    if (value < min) {
+        return (min - value) * weight;
+    }
+    if (value > max) {
+        return (value - max) * weight;
+    }
+    return 0;
+}
+function scoreScale(scale, options) {
+    const solid = scale[options.solidStep];
+    const onSolid = onSolidTextTokens(solid);
+    const contrast = Math.abs(apcaContrast(onSolid.primary, solid));
+    const text = scale[options.textStep];
+    const textL = hexToOklch(text).l;
+    const backgroundLs = options.backgroundSteps.map((step) => hexToOklch(scale[step]).l);
+    const minBackgroundL = Math.min(...backgroundLs);
+    const maxBackgroundL = Math.max(...backgroundLs);
+    let score = 0;
+    const contrastDelta = options.targetContrast - contrast;
+    if (contrastDelta > 0) {
+        score += contrastDelta * 2.2;
+    }
+    score += rangePenalty(minBackgroundL, options.minBackgroundL, options.maxBackgroundL, 180);
+    score += rangePenalty(maxBackgroundL, options.minBackgroundL, options.maxBackgroundL, 180);
+    score += rangePenalty(textL, options.minTextL, options.maxTextL, 120);
+    return score;
+}
+function pickAutoAnchorStep(seed, templateId, curves, gamutStrategy, mode, options) {
+    let bestStep = 9;
+    let bestScore = Number.POSITIVE_INFINITY;
+    for (const candidate of options.candidateSteps) {
+        const result = buildScaleForMode(seed, templateId, candidate, curves, gamutStrategy, mode, false);
+        const score = scoreScale(result.scale, options) + Math.abs(candidate - 9) * 2;
+        if (score < bestScore) {
+            bestScore = score;
+            bestStep = candidate;
+        }
+        else if (score === bestScore) {
+            if (Math.abs(candidate - 9) < Math.abs(bestStep - 9)) {
+                bestStep = candidate;
+            }
+        }
+    }
+    return bestStep;
+}
+function buildScaleForMode(seed, templateId, anchorStep, curves, gamutStrategy = "compress", mode = "light", includeP3 = false) {
     const template = templates[mode][templateId];
     const anchor = template[anchorStep];
-    const dL = seedOklch.l - anchor.l;
-    const dC = seedOklch.c - anchor.c;
-    const dH = seedOklch.h - anchor.h;
+    const dL = seed.l - anchor.l;
+    const dC = seed.c - anchor.c;
+    const dH = seed.h - anchor.h;
     const curveSet = resolveCurves(curves);
     const output = {};
     const p3Output = includeP3 ? {} : undefined;
@@ -61,14 +207,30 @@ function buildScaleForMode(seedHex, templateId, anchorStep, curves, gamutStrateg
 }
 export function generateScale(options) {
     const seedHex = getSeedHex(options.source);
-    const anchorStep = options.anchorStep ?? 9;
+    const seedOklch = hexToOklch(seedHex);
     const mode = options.mode ?? "both";
     const templateId = options.template === "auto" || !options.template
-        ? selectTemplateId(hexToOklch(seedHex))
+        ? selectTemplateId(seedOklch)
         : options.template;
     const gamutStrategy = options.gamut?.strategy ?? "compress";
-    const lightResult = buildScaleForMode(seedHex, templateId, anchorStep, options.curves, gamutStrategy, "light", options.p3 ?? false);
-    const darkResult = buildScaleForMode(seedHex, templateId, anchorStep, options.curves, gamutStrategy, "dark", options.p3 ?? false);
+    const anchorOption = options.anchorStep ?? "auto";
+    const anchorLightOption = resolveAnchorOption(anchorOption, "light");
+    const anchorDarkOption = resolveAnchorOption(anchorOption, "dark");
+    const autoAnchorOptions = resolveAutoAnchorOptions(options.autoAnchor);
+    const autoEnabled = anchorLightOption === "auto" || anchorDarkOption === "auto";
+    const seedNormalize = resolveSeedNormalizeOptions(options.seedNormalize, autoEnabled);
+    const lightSeed = seedNormalize.enabled
+        ? normalizeSeed(seedOklch, seedNormalize.light)
+        : seedOklch;
+    const darkSeed = seedNormalize.enabled ? normalizeSeed(seedOklch, seedNormalize.dark) : seedOklch;
+    const lightAnchorStep = anchorLightOption === "auto"
+        ? pickAutoAnchorStep(lightSeed, templateId, options.curves, gamutStrategy, "light", autoAnchorOptions.light)
+        : (anchorLightOption ?? 9);
+    const darkAnchorStep = anchorDarkOption === "auto"
+        ? pickAutoAnchorStep(darkSeed, templateId, options.curves, gamutStrategy, "dark", autoAnchorOptions.dark)
+        : (anchorDarkOption ?? 9);
+    const lightResult = buildScaleForMode(lightSeed, templateId, lightAnchorStep, options.curves, gamutStrategy, "light", options.p3 ?? false);
+    const darkResult = buildScaleForMode(darkSeed, templateId, darkAnchorStep, options.curves, gamutStrategy, "dark", options.p3 ?? false);
     const scale = {
         light: lightResult.scale,
         dark: darkResult.scale,
@@ -76,6 +238,10 @@ export function generateScale(options) {
         meta: {
             outOfGamutCount: lightResult.outOfGamutCount + darkResult.outOfGamutCount,
             outOfP3GamutCount: lightResult.outOfP3GamutCount + darkResult.outOfP3GamutCount,
+            anchorSteps: {
+                light: lightAnchorStep,
+                dark: darkAnchorStep,
+            },
         },
     };
     if (mode === "light") {
@@ -83,6 +249,12 @@ export function generateScale(options) {
             ...scale,
             dark: scale.light,
             p3: scale.p3 ? { light: scale.p3.light, dark: scale.p3.light } : undefined,
+            meta: scale.meta
+                ? {
+                    ...scale.meta,
+                    anchorSteps: { light: lightAnchorStep, dark: lightAnchorStep },
+                }
+                : undefined,
         };
     }
     if (mode === "dark") {
@@ -90,6 +262,12 @@ export function generateScale(options) {
             ...scale,
             light: scale.dark,
             p3: scale.p3 ? { light: scale.p3.dark, dark: scale.p3.dark } : undefined,
+            meta: scale.meta
+                ? {
+                    ...scale.meta,
+                    anchorSteps: { light: darkAnchorStep, dark: darkAnchorStep },
+                }
+                : undefined,
         };
     }
     return scale;

package/dist/index.d.ts

@@ -12,5 +12,6 @@ export { toJson, toJsonWithMode } from "./exporters/toJson.js";
 export { toReactNative } from "./exporters/toReactNative.js";
 export { toTailwind } from "./exporters/toTailwind.js";
 export { toTs, toTsWithMode } from "./exporters/toTs.js";
+export type { AnchorStepOption, AutoAnchorModeOptions, AutoAnchorOptions, GenerateScaleOptions, SeedNormalizeOptions, SeedNormalizeRange, } from "./generateScale.js";
 export { generateScale } from "./generateScale.js";
 export type { AlphaScale, ColorHex, ColorSource, OklchColor, RadixSeedName, Scale, ScaleColorMode, ScaleDiagnostics, Step, TemplateId, Theme, ThemeColorMode, ThemeDiagnostics, } from "./types.js";

package/dist/types.d.ts

@@ -13,6 +13,10 @@ export type ColorSource = {
 export type ScaleDiagnostics = {
     outOfGamutCount: number;
     outOfP3GamutCount?: number;
+    anchorSteps?: {
+        light: Step;
+        dark: Step;
+    };
 };
 export type Scale = {
     light: Record<Step, ColorHex>;

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@clhaas/palette-kit",
-  "version": "0.1.1",
+  "version": "0.1.2",
   "description": "Easy way to create the color palette of your app",
   "license": "MIT",
   "author": "Claus Haas",
@@ -24,7 +24,7 @@
     "test:watch": "vitest",
     "typecheck": "tsc -p tsconfig.json --noEmit",
     "typecheck:tests": "tsc -p tsconfig.test.json --noEmit",
-    "lint:biome": "biome check .",
+    "lint:biome": "biome check --unsafe --write",
     "lint:md": "markdownlint \"**/*.md\" --ignore node_modules",
     "lint": "npm run lint:biome && npm run lint:md && npm run typecheck && npm run typecheck:tests",
     "update": "npx npm-check-updates -i"