@clhaas/palette-kit 0.1.8 → 0.4.0

package/CHANGELOG.md

@@ -0,0 +1,59 @@
+# Changelog
+
+<!-- markdownlint-disable MD024 -->
+
+## v0.4.0
+
+### Breaking changes
+
+- Replaces the previous experimental `createTheme` API with `createPaletteKit`.
+- Publishes only the package root export. CLI commands, token exporters, and
+  serializer subpaths are not part of v0.4.
+- Resolver options are modeled as explicit axes: `usage`, `intent`, `level`,
+  relation, `state`, `context`, and `output`.
+
+### Features
+
+- Public `createPaletteKit` factory and `palette.resolve`.
+- Public resolver presets: `soft`, `neutral`, and `strong`.
+- Explicit `resolverConfig` overrides for level curves, state deltas, relation
+  parameters, and chroma limits.
+- APCA contrast enforcement for `on` relations with a default Lc 60 target.
+- Functional `over` and `under` overlay relations with configured alpha and
+  depth behavior.
+- Supported outputs: `oklch`, `oklab`, `srgb`, `p3`, `hex`, and `rgba`.
+- Strict public TypeScript option types for invalid usage/level/relation/state
+  combinations where possible.
+
+## v0.3.0
+
+### Breaking changes
+
+- ESM-only package (`"type": "module"`), no `require()` support.
+- Public API is split into subpath exports:
+  - `@clhaas/palette-kit` (runtime)
+  - `@clhaas/palette-kit/serialize` (serializer)
+  - `@clhaas/palette-kit/export` (exporters)
+  - `@clhaas/palette-kit/cli` and bin `palette-kit` (CLI)
+- Exporters are not re-exported from the main entrypoint to keep the runtime lean and tree-shakeable.
+
+### Features
+
+- Public serializer (`serializeColor`, `serializeResolved`, `theme.serialize`) with OKLCH/sRGB/P3 output options.
+- Public exporters: `exportThemeCss` (progressive `@supports` fallbacks) and `exportThemeJson` (stable `{ light, dark }` structure).
+- Declarative Token Registry + official token presets (`minimal-ui`, `radixLike-ui`, `modern-ui`).
+- CLI tooling:
+  - `palette-kit init` (typed config template)
+  - `palette-kit build` (deterministic `dist/palette/` artifacts: CSS/JSON/TS + d.ts)
+- Strong inference and DX validation improvements (strict vs non-strict behavior, clearer errors).
+
+### Migration
+
+- See `docs/Migration.md` for upgrade notes and updated import paths.
+
+## v0.2.0
+
+- Public API limited to `createTheme` and public types.
+- Resolver returns OKLCH channel data, not CSS strings.
+- Internal serializers/exporters exist but are not exported.
+- CLI is declared but not implemented in this tag.

package/README.md

@@ -1,217 +1,120 @@
 # Palette Kit
 
-Modern palette generator (OKLCH + APCA) with Radix-like steps. The library accepts seeds (initial colors) and produces light/dark scales, semantic tokens, and exporters ready for use.
+Palette Kit v0.4 is a deterministic OKLCH color resolution engine. It resolves
+semantic color requests from explicit axes and serializes the result only after
+resolution.
 
-Status: WIP. The API may change while the MVP is under construction.
+## Install
 
-## Installation
-
-```bash
+```sh
 npm install @clhaas/palette-kit
 ```
 
-```bash
-yarn add @clhaas/palette-kit
-```
-
-```bash
-pnpm add @clhaas/palette-kit
-```
-
-## What the library provides
-
-- 12-step scale (light/dark) from a seed.
-- Semantic tokens for UI (`radix-like-ui` preset).
-- Alpha scales per palette slot (chromatic alpha).
-- Overlay scales (black/white alpha).
-- Deterministic text scales for light/dark backgrounds.
-- 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
+## Quick Start
 
 ```ts
-import { createTheme } from "@clhaas/palette-kit";
-
-const theme = createTheme({
-  neutral: { source: "seed", value: "#111827" },
-  accent: { source: "seed", value: "#3d63dd" },
-  semantic: {
-    success: { source: "seed", value: "#16a34a" },
-    warning: { source: "seed", value: "#f59e0b" },
-    danger: { source: "seed", value: "#ef4444" },
-  },
-  tokens: { preset: "radix-like-ui" },
-  text: {
-    darkBase: "#1C1C1E",
-    lightBase: "#F5F5F7",
+import { createPaletteKit } from "@clhaas/palette-kit";
+
+const palette = createPaletteKit({
+  context: "light",
+  output: "oklch",
+  preset: "neutral",
+  intents: {
+    brand: { hue: 260, chroma: 0.14 },
+    neutral: { hue: 0, chroma: 0 },
   },
-  p3: true,
 });
-```
-
-## Quick start
-
-Generate a theme and export CSS variables:
-
-```ts
-import { createTheme, toCssVars } from "@clhaas/palette-kit";
 
-const theme = createTheme({
-  neutral: { source: "seed", value: "#111827" },
-  accent: { source: "seed", value: "#3d63dd" },
+const surface = palette.resolve({
+  usage: "fill",
+  intent: "neutral",
+  level: 2,
 });
 
-const css = toCssVars(theme, { prefix: "pk" });
-```
-
-Use tokens in your app:
-
-```css
-:root {
-  /* paste the generated CSS vars here */
-}
-
-body {
-  background: var(--pk-bg-app);
-  color: var(--pk-text-primary);
-}
-```
-
-## Step-by-step (install -> usage -> types)
-
-1) Install:
-
-```bash
-npm install @clhaas/palette-kit
-```
-
-2) Create a config file (`palette.config.mjs`):
-
-```js
-/** @type {import("@clhaas/palette-kit").CreateThemeOptions} */
-export default {
-  neutral: { source: "seed", value: "#111827" },
-  accent: { source: "seed", value: "#3d63dd" },
-  semantic: {
-    success: { source: "seed", value: "#16a34a" },
-    warning: { source: "seed", value: "#f59e0b" },
-    danger: { source: "seed", value: "#ef4444" },
-  },
-  tokens: { preset: "radix-like-ui" },
-  alpha: { enabled: true },
-  text: {
-    darkBase: "#1C1C1E",
-    lightBase: "#F5F5F7",
-  },
-  p3: true,
-};
+const text = palette.resolve({
+  usage: "visualVocabulary",
+  intent: "brand",
+  on: surface,
+});
 ```
 
-3) Generate a typed theme file (includes token name types):
+## Public Runtime API
 
-```bash
-npx palette-kit generate --out src/theme.ts
-```
+The package root exports:
 
-4) Export CSS vars (for web apps):
+- `createPaletteKit`
+- `softResolverConfig`
+- `neutralResolverConfig`
+- `strongResolverConfig`
+- `defaultResolverConfig`
 
-```ts
-import { toCssVars } from "@clhaas/palette-kit";
-import { theme } from "./theme";
+Public TypeScript types are also exported from the package root.
 
-const css = toCssVars(theme, { prefix: "pk" });
-// write the string into a .css file or inject it at build time
-```
+There are no public subpath exports, CLI commands, token exporters, or codegen
+APIs in v0.4.
 
-5) Use the generated types:
+## Resolver Rules
 
-```ts
-import { theme, ThemeTokenMap, ThemeTokenName } from "./theme";
+| Usage | Level | Relations |
+| --- | --- | --- |
+| `fill` | Required | `on` optional |
+| `visualVocabulary` | Forbidden | `on` required |
+| `lines` | Required | `on` optional |
+| `overlays` | Required | `over` or `under` optional |
 
-const tokens: ThemeTokenMap = theme.tokens.light;
-const tokenName: ThemeTokenName = "bg.app";
-```
+`state` defaults to `"default"`. Non-default states require explicit
+`stateDirection`; Palette Kit never infers whether state should increase or
+decrease lightness.
 
-## Alpha, overlay, and text examples
+Context is explicit. Provide palette-level `context`, resolver-level `context`,
+or host-injected `systemDefaultContext`. Context affects default level curves;
+for example, dark context inverts the structural lightness scale while
+preserving intent hue and chroma.
 
-```ts
-const accentAlpha = theme.alpha?.accent.light[5];
-const overlay = theme.overlay.black[9];
-const textOnLight = theme.tokens.light["text.dark.primary"];
-const textOnDark = theme.tokens.dark["text.light.primary"];
-```
+## Output
 
-## Migration note (alpha)
+Supported outputs:
 
-Alpha scales are now generated per palette slot. If you previously used:
+- `oklch`: normalized OKLCH object
+- `oklab`: OKLab object
+- `srgb`: `{ r, g, b, alpha }`
+- `p3`: Display-P3 `{ r, g, b, alpha }`
+- `hex`: `#rrggbb`
+- `rgba`: `{ r, g, b, a }`
 
-```ts
-theme.alpha?.light[5];
-```
+RGB-like outputs use clipped 8-bit channels. Output never changes semantic
+resolution.
 
-Update to:
+Output precedence is resolver-level `output`, then palette-level `output`, then
+host-injected `systemDefaultOutput`, then the explicit `oklch` default.
 
-```ts
-theme.alpha?.accent.light[5];
-```
-
-CSS variables were also updated from `--pk-alpha-<step>` to `--pk-alpha-<slot>-<step>`.
+## Configuration
 
-## React Native + Expo
-
-Use the React Native exporter and `useColorScheme()`:
+`createPaletteKit` accepts `preset` and explicit `resolverConfig` overrides.
 
 ```ts
-import { useMemo } from "react";
-import { useColorScheme } from "react-native";
-import { createTheme, toReactNative } from "@clhaas/palette-kit";
-
-const theme = createTheme({
-  neutral: { source: "seed", value: "#111827" },
-  accent: { source: "seed", value: "#3d63dd" },
-  p3: true,
+const palette = createPaletteKit({
+  context: "light",
+  preset: "soft",
+  intents,
+  resolverConfig: {
+    relationParams: {
+      on: { contrastTarget: 75 },
+    },
+  },
 });
-
-export function usePalette() {
-  const scheme = useColorScheme();
-  const palette = useMemo(() => toReactNative(theme, { includeP3: true }), []);
-  return scheme === "dark" ? palette.dark : palette.light;
-}
 ```
 
-See `examples/expo` for a full example.
-
-Note: React Native does not support `color(display-p3 ...)` strings as drop-in colors. The `p3` field is provided as data for platforms that can handle wide color via native APIs.
-
-## Principles
-
-- Tokens by intent, not by color.
-- Fixed steps (1-12) for UI consistency.
-- OKLCH generation, contrast resolved with APCA.
-
-## Docs and plans
-
-- `docs/README.md`
-- `docs/concepts.md`
-- `docs/api.md`
-- `docs/tokens.md`
-- `docs/contrast.md`
-- `docs/alpha.md`
-- `docs/text.md`
-- `docs/overlays.md`
-- `docs/Why.md`
-- `docs/spec-implementation.md`
-- `docs/plan-tests.md`
-- `docs/plan-docs.md`
+The default preset is `neutral`.
 
-## Short roadmap
+## Documentation
 
-1) Generate scales from seeds (light/dark).
-2) Tokens and basic exporters.
-3) Contrast and alpha scale.
+- [Docs index](docs/README.md)
+- [API](docs/API.md)
+- [Configuration](docs/Config.md)
+- [Specification summary](docs/spec.md)
+- [Migration](docs/Migration.md)
 
-## License
+## Module Format
 
-MIT
+Palette Kit is ESM-only.

package/dist/contrast/contrast.d.ts

@@ -0,0 +1,16 @@
+import { type OklchColor } from '../core/oklch.js';
+import type { Context } from '../engine/context/context.js';
+import type { ChromaConfig, RelationParamsConfig } from '../presets/presets.js';
+export type ContrastResolutionConfig = Readonly<{
+    on: RelationParamsConfig['on'];
+    chromaLimits: ChromaConfig;
+}>;
+export type ContrastResolutionInput = Readonly<{
+    color: OklchColor;
+    target: OklchColor;
+    context: Context;
+    config: ContrastResolutionConfig;
+}>;
+export declare function measureApcaContrast(foreground: OklchColor, background: OklchColor): number;
+export declare function measureWcagContrast(foreground: OklchColor, background: OklchColor): number;
+export declare function resolveOnContrast({ color, config, context, target, }: ContrastResolutionInput): OklchColor;

package/dist/contrast/contrast.js

@@ -0,0 +1,102 @@
+import { APCAcontrast, sRGBtoY } from 'apca-w3';
+import { normalizeOklch } from '../core/oklch.js';
+import { serializeOklchToSrgb } from '../export/serialize.js';
+import { createContrastUnsatisfiableError } from '../utils/errors/errors.js';
+const LIGHTNESS_STEP = 0.5;
+const CONTRAST_PRECISION = 2;
+const clampLightness = (value) => Math.min(100, Math.max(0, value));
+const roundContrast = (contrast) => Number(contrast.toFixed(CONTRAST_PRECISION));
+export function measureApcaContrast(foreground, background) {
+    const foregroundRgb = serializeOklchToSrgb(foreground);
+    const backgroundRgb = serializeOklchToSrgb(background);
+    const contrast = APCAcontrast(sRGBtoY([foregroundRgb.r, foregroundRgb.g, foregroundRgb.b]), sRGBtoY([backgroundRgb.r, backgroundRgb.g, backgroundRgb.b]));
+    const numericContrast = typeof contrast === 'number' ? contrast : Number(contrast);
+    if (Number.isFinite(numericContrast)) {
+        return numericContrast;
+    }
+    const wcagContrast = measureWcagContrast(foreground, background);
+    const polarity = foreground.l <= background.l ? 1 : -1;
+    return polarity * wcagContrast * 10;
+}
+const channelToLinear = (channel) => {
+    const normalized = channel / 255;
+    return normalized <= 0.03928
+        ? normalized / 12.92
+        : ((normalized + 0.055) / 1.055) ** 2.4;
+};
+const relativeLuminance = (color) => {
+    const rgb = serializeOklchToSrgb(color);
+    return (0.2126 * channelToLinear(rgb.r) +
+        0.7152 * channelToLinear(rgb.g) +
+        0.0722 * channelToLinear(rgb.b));
+};
+export function measureWcagContrast(foreground, background) {
+    const foregroundLuminance = relativeLuminance(foreground);
+    const backgroundLuminance = relativeLuminance(background);
+    const lighter = Math.max(foregroundLuminance, backgroundLuminance);
+    const darker = Math.min(foregroundLuminance, backgroundLuminance);
+    return (lighter + 0.05) / (darker + 0.05);
+}
+const hasTargetContrast = (contrast, target) => Math.abs(contrast) >= target;
+const createCandidate = (color, lightness, chroma) => normalizeOklch({
+    alpha: color.alpha,
+    c: Math.max(0, chroma),
+    h: color.h,
+    l: clampLightness(lightness),
+});
+const selectContrastDirections = (target, context) => {
+    if (target.l < 45) {
+        return ['increase', 'decrease'];
+    }
+    if (target.l > 55) {
+        return ['decrease', 'increase'];
+    }
+    return context === 'dark'
+        ? ['increase', 'decrease']
+        : ['decrease', 'increase'];
+};
+const scanLightness = (color, target, chroma, direction, maxLuminanceShift, contrastTarget) => {
+    const signedStep = direction === 'increase' ? LIGHTNESS_STEP : -LIGHTNESS_STEP;
+    const iterations = Math.ceil(maxLuminanceShift / LIGHTNESS_STEP);
+    let bestColor = createCandidate(color, color.l, chroma);
+    let bestContrast = measureApcaContrast(bestColor, target);
+    for (let index = 0; index <= iterations; index += 1) {
+        const lightness = color.l + signedStep * index;
+        const shift = Math.abs(lightness - color.l);
+        if (shift > maxLuminanceShift) {
+            break;
+        }
+        const candidate = createCandidate(color, lightness, chroma);
+        const contrast = measureApcaContrast(candidate, target);
+        if (Math.abs(contrast) > Math.abs(bestContrast)) {
+            bestColor = candidate;
+            bestContrast = contrast;
+        }
+        if (hasTargetContrast(contrast, contrastTarget)) {
+            break;
+        }
+    }
+    return { bestColor, bestContrast };
+};
+export function resolveOnContrast({ color, config, context, target, }) {
+    const contrastTarget = config.on.contrastTarget;
+    const maxReduction = Math.min(color.c, color.c * config.chromaLimits.maxReduction);
+    const chromaStep = config.chromaLimits.reductionStep;
+    let bestContrast = measureApcaContrast(color, target);
+    if (hasTargetContrast(bestContrast, contrastTarget)) {
+        return Object.freeze(color);
+    }
+    for (let reduction = 0; reduction <= maxReduction + chromaStep / 2; reduction += chromaStep) {
+        const chroma = Math.max(0, color.c - reduction);
+        for (const direction of selectContrastDirections(target, context)) {
+            const result = scanLightness(color, target, chroma, direction, config.on.maxLuminanceShift, contrastTarget);
+            if (Math.abs(result.bestContrast) > Math.abs(bestContrast)) {
+                bestContrast = result.bestContrast;
+            }
+            if (hasTargetContrast(result.bestContrast, contrastTarget)) {
+                return Object.freeze(result.bestColor);
+            }
+        }
+    }
+    throw createContrastUnsatisfiableError(roundContrast(Math.abs(bestContrast)), contrastTarget);
+}

package/dist/core/intent-registry.d.ts

@@ -0,0 +1,11 @@
+export type IntentName = string;
+export type IntentDefinition = {
+    hue: number;
+    chroma: number;
+};
+export type IntentRegistry<I extends string = string> = Readonly<{
+    intents: Readonly<Record<I, Readonly<IntentDefinition>>>;
+}>;
+export declare function createIntentRegistry<const I extends string>(intents: Record<I, IntentDefinition>): IntentRegistry<I>;
+export declare function hasIntent<I extends string>(registry: IntentRegistry<I>, intent: IntentName): intent is I;
+export declare function getIntent<I extends string>(registry: IntentRegistry<I>, intent: IntentName): Readonly<IntentDefinition>;

package/dist/core/intent-registry.js

@@ -0,0 +1,70 @@
+import { createUnknownIntentError } from '../utils/errors/errors.js';
+const isFiniteNumber = (value) => typeof value === 'number' && Number.isFinite(value);
+const normalizeHue = (hue) => {
+    const normalized = ((hue % 360) + 360) % 360;
+    return Object.is(normalized, -0) ? 0 : normalized;
+};
+const forbiddenIntentTokens = Object.freeze({
+    level: new Set(['strong', 'subtle', 'weak', 'muted', 'heavy']),
+    relation: new Set(['on', 'over', 'under', 'overlay']),
+    state: new Set(['hover', 'active', 'focus', 'selected', 'disabled']),
+    usage: new Set(['text', 'border', 'icon', 'fill', 'line', 'lines']),
+    visual: new Set(['green', 'red', 'blue', 'dark', 'light']),
+});
+const splitIntentName = (name) => name
+    .replace(/([a-z0-9])([A-Z])/g, '$1 $2')
+    .split(/[-_]+|\s+/)
+    .map((part) => part.toLowerCase())
+    .filter((part) => part.length > 0);
+const validateIntentName = (name) => {
+    if (name.length === 0) {
+        throw new Error('Intent name must not be empty.');
+    }
+    if (/\s/.test(name)) {
+        throw new Error(`Intent name "${name}" must not contain whitespace.`);
+    }
+    if (name.includes('.')) {
+        throw new Error(`Intent name "${name}" must use a flat namespace.`);
+    }
+    const tokens = splitIntentName(name);
+    for (const [category, forbiddenTokens] of Object.entries(forbiddenIntentTokens)) {
+        if (tokens.some((token) => forbiddenTokens.has(token))) {
+            throw new Error(`Intent name "${name}" must describe meaning only and must not encode ${category}.`);
+        }
+    }
+};
+const normalizeIntentDefinition = (name, definition) => {
+    if (!isFiniteNumber(definition.hue)) {
+        throw new Error(`Intent "${name}" hue must be a finite number.`);
+    }
+    if (!isFiniteNumber(definition.chroma)) {
+        throw new Error(`Intent "${name}" chroma must be a finite number.`);
+    }
+    if (definition.chroma < 0) {
+        throw new Error(`Intent "${name}" chroma must be greater than or equal to 0.`);
+    }
+    return Object.freeze({
+        chroma: definition.chroma,
+        hue: normalizeHue(definition.hue),
+    });
+};
+export function createIntentRegistry(intents) {
+    const entries = Object.entries(intents);
+    const normalized = {};
+    for (const [name, definition] of entries) {
+        validateIntentName(name);
+        normalized[name] = normalizeIntentDefinition(name, definition);
+    }
+    return Object.freeze({
+        intents: Object.freeze(normalized),
+    });
+}
+export function hasIntent(registry, intent) {
+    return Object.hasOwn(registry.intents, intent);
+}
+export function getIntent(registry, intent) {
+    if (!hasIntent(registry, intent)) {
+        throw createUnknownIntentError(intent);
+    }
+    return registry.intents[intent];
+}

package/dist/core/oklch.d.ts

@@ -0,0 +1,16 @@
+export type OklchColor = {
+    space: 'oklch';
+    l: number;
+    c: number;
+    h: number;
+    alpha: number;
+};
+export type OklchInput = {
+    l: number;
+    c: number;
+    h: number;
+    alpha?: number;
+};
+export declare function normalizeOklch(input: OklchInput): OklchColor;
+export declare function isOklchColor(value: unknown): value is OklchColor;
+export declare function assertOklchColor(value: unknown): asserts value is OklchColor;

package/dist/core/oklch.js

@@ -0,0 +1,56 @@
+const isFiniteNumber = (value) => typeof value === 'number' && Number.isFinite(value);
+const normalizeHue = (hue) => {
+    const normalized = ((hue % 360) + 360) % 360;
+    return Object.is(normalized, -0) ? 0 : normalized;
+};
+const validateFiniteChannel = (name, value) => {
+    if (!isFiniteNumber(value)) {
+        throw new Error(`OKLCH ${name} must be a finite number.`);
+    }
+};
+export function normalizeOklch(input) {
+    validateFiniteChannel('l', input.l);
+    validateFiniteChannel('c', input.c);
+    validateFiniteChannel('h', input.h);
+    if (input.l < 0 || input.l > 100) {
+        throw new Error('OKLCH l must be between 0 and 100.');
+    }
+    if (input.c < 0) {
+        throw new Error('OKLCH c must be greater than or equal to 0.');
+    }
+    const alpha = input.alpha ?? 1;
+    validateFiniteChannel('alpha', alpha);
+    if (alpha < 0 || alpha > 1) {
+        throw new Error('OKLCH alpha must be between 0 and 1.');
+    }
+    return {
+        alpha,
+        c: input.c,
+        h: normalizeHue(input.h),
+        l: input.l,
+        space: 'oklch',
+    };
+}
+export function isOklchColor(value) {
+    if (typeof value !== 'object' || value === null) {
+        return false;
+    }
+    const candidate = value;
+    return (candidate.space === 'oklch' &&
+        isFiniteNumber(candidate.l) &&
+        candidate.l >= 0 &&
+        candidate.l <= 100 &&
+        isFiniteNumber(candidate.c) &&
+        candidate.c >= 0 &&
+        isFiniteNumber(candidate.h) &&
+        candidate.h >= 0 &&
+        candidate.h < 360 &&
+        isFiniteNumber(candidate.alpha) &&
+        candidate.alpha >= 0 &&
+        candidate.alpha <= 1);
+}
+export function assertOklchColor(value) {
+    if (!isOklchColor(value)) {
+        throw new Error('Expected a normalized OKLCH color.');
+    }
+}

package/dist/create-palette-kit.d.ts

@@ -0,0 +1,9 @@
+import { type ColorOutput } from './export/types.js';
+import type { PaletteDefaultOutput, PaletteKit, PaletteKitConfig } from './types/index.js';
+/**
+ * Creates an immutable Palette Kit resolver instance.
+ *
+ * The factory normalizes the provided intent registry once, keeps context and
+ * output defaults explicit, and never reads ambient platform state.
+ */
+export declare function createPaletteKit<const I extends string, const PaletteOutput extends ColorOutput | undefined = undefined, const SystemDefaultOutput extends ColorOutput | undefined = undefined>(config: PaletteKitConfig<I, PaletteOutput, SystemDefaultOutput>): PaletteKit<I, PaletteDefaultOutput<PaletteOutput, SystemDefaultOutput>>;