@clhaas/palette-kit 0.1.7 → 0.3.0

package/README.md

@@ -1,217 +1,127 @@
 # 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 is a **runtime-first color engine** for generating OKLCH-based palettes from semantic queries, with optional build-time tooling (serializer, exporters, CLI, codegen).
 
-Status: WIP. The API may change while the MVP is under construction.
-
-## Installation
+## Install
 
 ```bash
 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
+## Runtime 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",
+  seeds: {
+    light: { neutral: "#111827", accent: "#3d63dd" },
+    dark: { neutral: "#111827", accent: "#3d63dd" },
   },
-  p3: true,
+  preset: "modern",
 });
-```
-
-## 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 bg = theme.resolve({
+  role: "bg.app",
+  usage: "bg",
+  surface: "app",
+  context: "light",
 });
 
-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);
-}
+const onSolidText = theme.onSolid({
+  bgRole: "bg.app",
+  usage: "text",
+  context: "light",
+  contrast: { model: "apca", targetLc: 75 },
+});
 ```
 
-## Step-by-step (install -> usage -> types)
-
-1) Install:
+## Serializer (public)
 
-```bash
-npm install @clhaas/palette-kit
-```
+Use the serializer to turn resolved OKLCH into CSS/RN-ready strings:
 
-2) Create a config file (`palette.config.mjs`):
+```ts
+import { createTheme } from "@clhaas/palette-kit";
+import { serializeResolved } from "@clhaas/palette-kit/serialize";
 
-```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",
+const theme = createTheme({
+  seeds: {
+    light: { neutral: "#111827", accent: "#3d63dd" },
+    dark: { neutral: "#111827", accent: "#3d63dd" },
   },
-  p3: true,
-};
-```
+});
 
-3) Generate a typed theme file (includes token name types):
+const resolved = theme.resolve({ role: "bg.app", usage: "bg", surface: "app" });
+const color = serializeResolved(resolved, { preferSpace: "srgb", srgbFormat: "hex" });
 
-```bash
-npx palette-kit generate --out src/theme.ts
+console.log(color.value);
 ```
 
-4) Export CSS vars (for web apps):
-
-```ts
-import { toCssVars } from "@clhaas/palette-kit";
-import { theme } from "./theme";
-
-const css = toCssVars(theme, { prefix: "pk" });
-// write the string into a .css file or inject it at build time
-```
+## Exporters (public, build-time)
 
-5) Use the generated types:
+Export deterministic CSS variables and JSON tokens:
 
 ```ts
-import { theme, ThemeTokenMap, ThemeTokenName } from "./theme";
+import { createTheme } from "@clhaas/palette-kit";
+import { exportThemeCss, exportThemeJson } from "@clhaas/palette-kit/export";
 
-const tokens: ThemeTokenMap = theme.tokens.light;
-const tokenName: ThemeTokenName = "bg.app";
-```
+const theme = createTheme({
+  seeds: {
+    light: { neutral: "#111827", accent: "#3d63dd" },
+    dark: { neutral: "#111827", accent: "#3d63dd" },
+  },
+});
 
-## Alpha, overlay, and text examples
+const tokens = {
+  "bg.app": { usage: "bg", surface: "app" },
+  "text.primary": { usage: "text", surface: "surface" },
+};
 
-```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"];
+const { css } = exportThemeCss(theme, tokens, { includeSpaces: ["oklch", "p3"] });
+const json = exportThemeJson(theme, tokens, { includeSpaces: ["srgb"] });
 ```
 
-## Migration note (alpha)
+## CLI
 
-Alpha scales are now generated per palette slot. If you previously used:
+- `palette-kit init` creates `palette.config.ts`
+- `palette-kit build` writes `dist/palette/` artifacts (`tokens.css`, `tokens.json`, `tokens.ts`, `tokens.d.ts`)
 
-```ts
-theme.alpha?.light[5];
-```
+See `docs/CLI.md` for flags and config details.
 
-Update to:
+## Docs
 
-```ts
-theme.alpha?.accent.light[5];
-```
-
-CSS variables were also updated from `--pk-alpha-<step>` to `--pk-alpha-<slot>-<step>`.
-
-## React Native + Expo
+- `docs/README.md`
+- `docs/_api-surface.md`
+- `docs/Exporters.md`
+- `docs/CLI.md`
+- `docs/Migration.md`
 
-Use the React Native exporter and `useColorScheme()`:
+## Compatibility
 
-```ts
-import { useMemo } from "react";
-import { useColorScheme } from "react-native";
-import { createTheme, toReactNative } from "@clhaas/palette-kit";
+- ESM package (`"type": "module"`).
+- CJS is not supported in v0.3; use ESM or dynamic `import()` in CJS environments.
+- Subpath imports:
+  - `@clhaas/palette-kit/serialize`
+  - `@clhaas/palette-kit/export`
+  - `@clhaas/palette-kit/cli`
+- Tree-shaking: runtime imports (`@clhaas/palette-kit`) do not bundle build-time tools (exporters/CLI).
 
-const theme = createTheme({
-  neutral: { source: "seed", value: "#111827" },
-  accent: { source: "seed", value: "#3d63dd" },
-  p3: true,
-});
+### CommonJS note
 
-export function usePalette() {
-  const scheme = useColorScheme();
-  const palette = useMemo(() => toReactNative(theme, { includeP3: true }), []);
-  return scheme === "dark" ? palette.dark : palette.light;
-}
+```js
+// CJS workaround (dynamic import)
+(async () => {
+  const { createTheme } = await import("@clhaas/palette-kit");
+  const theme = createTheme({
+    seeds: {
+      light: { neutral: "#111827", accent: "#3d63dd" },
+      dark: { neutral: "#111827", accent: "#3d63dd" },
+    },
+  });
+  console.log(theme);
+})();
 ```
 
-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`
-
-## Short roadmap
-
-1) Generate scales from seeds (light/dark).
-2) Tokens and basic exporters.
-3) Contrast and alpha scale.
-
 ## License
 
-MIT
+MIT — see `LICENSE`.

package/biome.json

@@ -0,0 +1,43 @@
+{
+  "$schema": "https://biomejs.dev/schemas/2.3.11/schema.json",
+  "formatter": {
+    "enabled": true,
+    "indentStyle": "space",
+    "indentWidth": 2,
+    "lineWidth": 100
+  },
+  "linter": {
+    "enabled": true,
+    "rules": {
+      "recommended": true
+    }
+  },
+  "files": {
+    "ignoreUnknown": true,
+    "includes": [
+      "**/*.js",
+      "**/*.ts",
+      "**/*.tsx",
+      "**/*.css",
+      "**/*.scss",
+      "**/*.html",
+      "**/*.json",
+      "**/*.md",
+      "!**/supabase/functions",
+      "!**/node_modules",
+      "!**/dist",
+      "!**/build",
+      "!**/coverage",
+      "!**/ios",
+      "!**/android",
+      "!**/.git/",
+      "!**/.vscode",
+      "!**/*.d.ts",
+      "!**/*.spec.ts",
+      "!**/*.test.ts",
+      "!**/.github",
+      "!**/examples",
+      "!**/tests"
+    ]
+  }
+}

package/dist/cli/args.d.ts

@@ -0,0 +1,12 @@
+export declare class CliUsageError extends Error {
+    name: string;
+}
+export declare const HELP_TEXT = "palette-kit <command>\n\nCommands:\n  palette-kit init [--force] [--path <dir>]\n  palette-kit build [--config <path>] [--outDir <dir>] [--report]\n\nOptions:\n  -h, --help       Show help\n  -v, --version    Show version\n";
+export type ParsedArgs = {
+    command?: string;
+    help: boolean;
+    version: boolean;
+    flags: Record<string, string | boolean>;
+};
+export declare const COMMANDS: readonly ["init", "build"];
+export declare const parseArgs: (argv: string[]) => ParsedArgs;

package/dist/cli/args.js

@@ -0,0 +1,56 @@
+export class CliUsageError extends Error {
+    name = "CliUsageError";
+}
+export const HELP_TEXT = `palette-kit <command>
+
+Commands:
+  palette-kit init [--force] [--path <dir>]
+  palette-kit build [--config <path>] [--outDir <dir>] [--report]
+
+Options:
+  -h, --help       Show help
+  -v, --version    Show version
+`;
+export const COMMANDS = ["init", "build"];
+export const parseArgs = (argv) => {
+    const first = argv[0];
+    const command = first && !first.startsWith("-") ? first : undefined;
+    const rest = command ? argv.slice(1) : argv;
+    const flags = {};
+    let i = 0;
+    while (i < rest.length) {
+        const value = rest[i];
+        if (value === undefined)
+            break;
+        if (value === "-h" || value === "--help") {
+            flags.help = true;
+            i += 1;
+            continue;
+        }
+        if (value === "-v" || value === "--version") {
+            flags.version = true;
+            i += 1;
+            continue;
+        }
+        if (value.startsWith("--")) {
+            const key = value.slice(2);
+            const next = rest[i + 1];
+            if (next && !next.startsWith("--")) {
+                flags[key] = next;
+                i += 2;
+            }
+            else {
+                flags[key] = true;
+                i += 1;
+            }
+            continue;
+        }
+        throw new CliUsageError(`Unknown argument: ${value}`);
+    }
+    return {
+        command,
+        help: Boolean(flags.help),
+        version: Boolean(flags.version),
+        flags,
+    };
+};

package/dist/cli/args.test.js

@@ -0,0 +1,22 @@
+import { describe, expect, it } from "vitest";
+import { CliUsageError, parseArgs } from "./args.js";
+describe("cli args", () => {
+    it("parses init command", () => {
+        const parsed = parseArgs(["init"]);
+        expect(parsed.command).toBe("init");
+    });
+    it("parses build command with flags", () => {
+        const parsed = parseArgs(["build", "--config", "custom.ts", "--outDir", "out", "--report"]);
+        expect(parsed.command).toBe("build");
+        expect(parsed.flags.config).toBe("custom.ts");
+        expect(parsed.flags.outDir).toBe("out");
+        expect(parsed.flags.report).toBe(true);
+    });
+    it("recognizes help and version flags", () => {
+        expect(parseArgs(["--help"]).help).toBe(true);
+        expect(parseArgs(["--version"]).version).toBe(true);
+    });
+    it("throws on unknown arguments", () => {
+        expect(() => parseArgs(["build", "wat"])).toThrow(CliUsageError);
+    });
+});

package/dist/cli/codegen/__snapshots__/tokens.test.js.snap

@@ -0,0 +1,87 @@
+// Vitest Snapshot v1, https://vitest.dev/guide/snapshot.html
+
+exports[`codegen tokens > generates navigable tokens.ts and tokens.d.ts 1`] = `
+"/* This file is generated by palette-kit build (Phase 7). */
+
+export const tokens = {
+bg: {
+  /**
+   * App background.
+   * @token bg.app
+   * @category bg
+   */
+  app: "bg.app",
+  },
+border: {
+  /**
+   * Default border color.
+   * @token border.default
+   * @category border
+   */
+  "default": "border.default",
+  },
+text: {
+  /**
+   * Primary text on standard surfaces.
+   * @token text.primary
+   * @category text
+   * @states hover
+   */
+  primary: "text.primary",
+  },
+} as const;
+
+export const tokenNames = [
+  "bg.app",
+  "border.default",
+  "text.primary"
+] as const;
+
+export type TokenName = (typeof tokenNames)[number];
+
+export type ColorRole = TokenName;
+"
+`;
+
+exports[`codegen tokens > generates navigable tokens.ts and tokens.d.ts 2`] = `
+"/* This file is generated by palette-kit build (Phase 7). */
+
+export declare const tokens: {
+bg: {
+  /**
+   * App background.
+   * @token bg.app
+   * @category bg
+   */
+  app: "bg.app";
+  };
+border: {
+  /**
+   * Default border color.
+   * @token border.default
+   * @category border
+   */
+  "default": "border.default";
+  };
+text: {
+  /**
+   * Primary text on standard surfaces.
+   * @token text.primary
+   * @category text
+   * @states hover
+   */
+  primary: "text.primary";
+  };
+};
+
+export declare const tokenNames: readonly [
+  "bg.app",
+  "border.default",
+  "text.primary"
+];
+
+export type TokenName = (typeof tokenNames)[number];
+
+export type ColorRole = TokenName;
+"
+`;

package/dist/cli/codegen/tokens.d.ts

@@ -0,0 +1,12 @@
+import type { TokenRegistry } from "../../types/index.js";
+export type GeneratedTokens = {
+    tokenNames: string[];
+    tokensTs: string;
+    tokensDts: string;
+};
+/**
+ * Generate `dist/palette/tokens.ts` and `dist/palette/tokens.d.ts` sources.
+ *
+ * Output is deterministic and derived from the token registry.
+ */
+export declare const generateTokenArtifacts: (registry: TokenRegistry) => GeneratedTokens;

package/dist/cli/codegen/tokens.js

@@ -0,0 +1,139 @@
+const RESERVED_WORDS = new Set([
+    "break",
+    "case",
+    "catch",
+    "class",
+    "const",
+    "continue",
+    "debugger",
+    "default",
+    "delete",
+    "do",
+    "else",
+    "export",
+    "extends",
+    "finally",
+    "for",
+    "function",
+    "if",
+    "import",
+    "in",
+    "instanceof",
+    "new",
+    "return",
+    "super",
+    "switch",
+    "this",
+    "throw",
+    "try",
+    "typeof",
+    "var",
+    "void",
+    "while",
+    "with",
+    "yield",
+]);
+const isValidIdentifier = (value) => {
+    if (!/^[A-Za-z_$][A-Za-z0-9_$]*$/.test(value))
+        return false;
+    return !RESERVED_WORDS.has(value);
+};
+const toPropertyKey = (key) => (isValidIdentifier(key) ? key : JSON.stringify(key));
+const indentLines = (lines, spaces) => {
+    const prefix = " ".repeat(spaces);
+    return lines.map((line) => (line.length ? `${prefix}${line}` : line));
+};
+const escapeJsDoc = (value) => value.replace(/\*\//g, "*\\/");
+const buildTokenJsDocLines = (tokenName, token) => {
+    const lines = [];
+    if (token.description?.trim()) {
+        lines.push(escapeJsDoc(token.description.trim()));
+    }
+    lines.push(`@token ${tokenName}`);
+    if (token.category?.trim()) {
+        lines.push(`@category ${escapeJsDoc(token.category.trim())}`);
+    }
+    const states = token.states ? Object.keys(token.states).sort() : [];
+    if (states.length > 0) {
+        lines.push(`@states ${states.join(", ")}`);
+    }
+    return ["/**", ...lines.map((line) => ` * ${line}`), " */"];
+};
+const buildTree = (registry) => {
+    const root = { children: new Map() };
+    const entries = Object.entries(registry.tokens).sort(([a], [b]) => a.localeCompare(b));
+    for (const [tokenName, token] of entries) {
+        const segments = tokenName.split(".").filter(Boolean);
+        if (segments.length === 0)
+            continue;
+        let node = root;
+        for (const segment of segments) {
+            let child = node.children.get(segment);
+            if (!child) {
+                child = { children: new Map() };
+                node.children.set(segment, child);
+            }
+            node = child;
+        }
+        node.token = token;
+    }
+    return root;
+};
+const renderTreeTs = (node, tokenNamePrefix) => {
+    const lines = ["{"];
+    const keys = [...node.children.keys()].sort((a, b) => a.localeCompare(b));
+    for (const key of keys) {
+        const child = node.children.get(key);
+        if (!child)
+            continue;
+        const fullTokenName = tokenNamePrefix ? `${tokenNamePrefix}.${key}` : key;
+        const propKey = toPropertyKey(key);
+        if (child.token && child.children.size === 0) {
+            lines.push(...buildTokenJsDocLines(fullTokenName, child.token));
+            lines.push(`${propKey}: "${fullTokenName}",`);
+            continue;
+        }
+        const childLines = renderTreeTs(child, fullTokenName);
+        lines.push(`${propKey}: ${childLines[0]}`);
+        lines.push(...indentLines(childLines.slice(1), 2));
+        lines[lines.length - 1] = `${lines[lines.length - 1]},`;
+    }
+    lines.push("}");
+    return lines;
+};
+const renderTreeDts = (node, tokenNamePrefix) => {
+    const lines = ["{"];
+    const keys = [...node.children.keys()].sort((a, b) => a.localeCompare(b));
+    for (const key of keys) {
+        const child = node.children.get(key);
+        if (!child)
+            continue;
+        const fullTokenName = tokenNamePrefix ? `${tokenNamePrefix}.${key}` : key;
+        const propKey = toPropertyKey(key);
+        if (child.token && child.children.size === 0) {
+            lines.push(...buildTokenJsDocLines(fullTokenName, child.token));
+            lines.push(`${propKey}: "${fullTokenName}";`);
+            continue;
+        }
+        const childLines = renderTreeDts(child, fullTokenName);
+        lines.push(`${propKey}: ${childLines[0]}`);
+        lines.push(...indentLines(childLines.slice(1), 2));
+        lines[lines.length - 1] = `${lines[lines.length - 1]};`;
+    }
+    lines.push("}");
+    return lines;
+};
+/**
+ * Generate `dist/palette/tokens.ts` and `dist/palette/tokens.d.ts` sources.
+ *
+ * Output is deterministic and derived from the token registry.
+ */
+export const generateTokenArtifacts = (registry) => {
+    const tokenNames = Object.keys(registry.tokens).sort((a, b) => a.localeCompare(b));
+    const tree = buildTree(registry);
+    const tokensObject = renderTreeTs(tree, "");
+    const tokensDtsObject = renderTreeDts(tree, "");
+    const tokensTs = `/* This file is generated by palette-kit build (Phase 7). */\n\nexport const tokens = ${tokensObject.join("\n")} as const;\n\nexport const tokenNames = ${JSON.stringify(tokenNames, null, 2)} as const;\n\nexport type TokenName = (typeof tokenNames)[number];\n\nexport type ColorRole = TokenName;\n`;
+    const tokensDts = `/* This file is generated by palette-kit build (Phase 7). */\n\nexport declare const tokens: ${tokensDtsObject.join("\n")};\n\nexport declare const tokenNames: readonly ${JSON.stringify(tokenNames, null, 2)};\n\nexport type TokenName = (typeof tokenNames)[number];\n\nexport type ColorRole = TokenName;\n`;
+    return { tokenNames, tokensTs, tokensDts };
+};

package/dist/cli/codegen/tokens.test.d.ts

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