@clhaas/palette-kit 0.1.0

package/.markdownlint.json

@@ -0,0 +1,4 @@
+{
+  "MD029": false,
+  "MD013": false
+}

package/LICENSE

@@ -0,0 +1,21 @@
+# MIT License
+
+Copyright (c) 2026 Claus Haas
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,128 @@
+# 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.
+
+Status: WIP. The API may change while the MVP is under construction.
+
+## Installation
+
+```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 scale for overlays.
+- Exporters for TS, JSON, and CSS vars.
+- Basic contrast and gamut diagnostics.
+
+## Usage example (planned API)
+
+```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" },
+  output: { format: "css", cssVarPrefix: "pk" },
+});
+```
+
+## 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 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);
+}
+```
+
+## React Native + Expo
+
+Use the React Native exporter and `useColorScheme()`:
+
+```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,
+});
+
+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/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

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/package.json

@@ -0,0 +1,33 @@
+{
+  "name": "@clhaas/palette-kit",
+  "version": "0.1.0",
+  "description": "Easy way to create the color palette of your app",
+  "license": "MIT",
+  "author": "Claus Haas",
+  "type": "module",
+  "main": "index.js",
+  "publishConfig": {
+    "access": "public"
+  },
+  "scripts": {
+    "test": "vitest run",
+    "test:watch": "vitest",
+    "typecheck": "tsc -p tsconfig.json --noEmit",
+    "typecheck:tests": "tsc -p tsconfig.test.json --noEmit",
+    "lint:biome": "biome check .",
+    "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"
+  },
+  "dependencies": {
+    "apca-w3": "^0.1.9",
+    "colorjs.io": "^0.6.0"
+  },
+  "devDependencies": {
+    "@biomejs/biome": "^2.3.11",
+    "@types/apca-w3": "^0.1.3",
+    "markdownlint-cli": "^0.47.0",
+    "typescript": "^5.9.3",
+    "vitest": "^4.0.16"
+  }
+}

package/src/alpha/generateAlphaScale.ts

@@ -0,0 +1,43 @@
+import Color from "colorjs.io";
+import type { AlphaScale, ColorHex, Step } from "../types.js";
+
+const steps: Step[] = [1, 2, 3, 4, 5, 6, 7, 8, 9, 10, 11, 12];
+const alphaCurve: Record<Step, number> = {
+  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: ColorHex, alpha: number): ColorHex {
+  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 as ColorHex;
+}
+
+export function generateAlphaScale(
+  base: ColorHex,
+  _background: { light: ColorHex; dark: ColorHex },
+): AlphaScale {
+  const light: Record<Step, ColorHex> = {} as Record<Step, ColorHex>;
+  const dark: Record<Step, ColorHex> = {} as Record<Step, ColorHex>;
+
+  for (const step of steps) {
+    const alpha = alphaCurve[step];
+    light[step] = mixWithAlpha(base, alpha);
+    dark[step] = mixWithAlpha(base, alpha);
+  }
+
+  return { light, dark };
+}

package/src/contrast/apca.ts

@@ -0,0 +1,7 @@
+import { calcAPCA } from "apca-w3";
+import type { ColorHex } from "../types.js";
+
+export function apcaContrast(foreground: ColorHex, background: ColorHex): number {
+  const contrast = Number(calcAPCA(foreground, background));
+  return Number(contrast.toFixed(2));
+}

package/src/contrast/onSolid.ts

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

package/src/contrast/solveText.ts

@@ -0,0 +1,49 @@
+import Color from "colorjs.io";
+import { compressToSrgb, oklchToHex } from "../engine/oklch.js";
+import type { ColorHex, OklchColor } from "../types.js";
+import { apcaContrast } from "./apca.js";
+
+function clamp(value: number, min: number, max: number): number {
+  return Math.min(max, Math.max(min, value));
+}
+
+function adjustLightness(
+  oklch: OklchColor,
+  background: ColorHex,
+  target: number,
+  maxIterations = 24,
+): OklchColor {
+  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: ColorHex,
+  background: ColorHex,
+  target: number,
+): ColorHex {
+  const fg = new Color(foreground).to("oklch");
+  const [l, c, h] = fg.coords;
+  let candidate: OklchColor = { l: l ?? 0, c: c ?? 0, h: h ?? 0 };
+
+  candidate = adjustLightness(candidate, background, target);
+  candidate = compressToSrgb(candidate);
+
+  return oklchToHex(candidate);
+}

package/src/createTheme.ts

@@ -0,0 +1,130 @@
+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";
+import type { AlphaScale, ColorHex, ColorSource, Scale, 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;
+  };
+  p3?: boolean;
+};
+
+export function createTheme(options: CreateThemeOptions): Theme {
+  const includeP3 = options.p3 ?? false;
+  const scales: Record<string, Scale> = {
+    neutral: generateScale({ source: options.neutral, p3: includeP3 }),
+    accent: generateScale({ source: options.accent, p3: includeP3 }),
+  };
+
+  if (options.semantic?.success) {
+    scales.success = generateScale({ source: options.semantic.success, p3: includeP3 });
+  }
+  if (options.semantic?.warning) {
+    scales.warning = generateScale({ source: options.semantic.warning, p3: includeP3 });
+  }
+  if (options.semantic?.danger) {
+    scales.danger = generateScale({ source: options.semantic.danger, p3: includeP3 });
+  }
+
+  if (options.extras) {
+    for (const [key, source] of Object.entries(options.extras)) {
+      scales[key] = generateScale({ source, 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: AlphaScale | undefined;
+  if (options.alpha?.enabled !== false) {
+    const background = {
+      light: options.alpha?.background?.light ?? "#ffffff",
+      dark: options.alpha?.background?.dark ?? "#111111",
+    } as const;
+    alpha = generateAlphaScale(accentScale.light[9], background);
+  }
+
+  const diagnostics = analyzeTheme({ scales, tokens, alpha });
+
+  return {
+    scales,
+    tokens,
+    alpha,
+    diagnostics,
+  };
+}

package/src/data/radixSeeds.ts

@@ -0,0 +1,37 @@
+import type { ColorHex, RadixSeedName } from "../types.js";
+
+export const radixSeeds: Record<RadixSeedName, ColorHex> = {
+  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/src/diagnostics/analyzeScale.ts

@@ -0,0 +1,6 @@
+import type { Scale, ScaleDiagnostics } from "../types.js";
+
+export function analyzeScale(scale: Scale): ScaleDiagnostics {
+  const outOfGamutCount = scale.meta?.outOfGamutCount ?? 0;
+  return { outOfGamutCount };
+}

package/src/diagnostics/analyzeTheme.ts

@@ -0,0 +1,54 @@
+import { apcaContrast } from "../contrast/apca.js";
+import type { Theme, ThemeDiagnostics } from "../types.js";
+import { analyzeWarnings } from "./warnings.js";
+
+export function analyzeTheme(theme: Theme): ThemeDiagnostics {
+  const contrast: Record<string, number> = {};
+
+  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/src/diagnostics/warnings.ts

@@ -0,0 +1,25 @@
+import Color from "colorjs.io";
+import type { Theme } from "../types.js";
+
+export function analyzeWarnings(theme: Theme): string[] {
+  const warnings: string[] = [];
+
+  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/src/engine/curves.ts

@@ -0,0 +1,64 @@
+import type { Step } from "../types.js";
+
+export type CurveConfig = {
+  lightness?: Partial<Record<Step, number>>;
+  chroma?: Partial<Record<Step, number>>;
+};
+
+const steps: Step[] = [1, 2, 3, 4, 5, 6, 7, 8, 9, 10, 11, 12];
+
+const defaultLightness: Record<Step, number> = {
+  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: Record<Step, number> = {
+  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?: CurveConfig): {
+  lightness: Record<Step, number>;
+  chroma: Record<Step, number>;
+} {
+  const lightness = { ...defaultLightness };
+  const chroma = { ...defaultChroma };
+
+  if (curves?.lightness) {
+    for (const step of steps) {
+      if (curves.lightness[step] !== undefined) {
+        lightness[step] = curves.lightness[step] as number;
+      }
+    }
+  }
+
+  if (curves?.chroma) {
+    for (const step of steps) {
+      if (curves.chroma[step] !== undefined) {
+        chroma[step] = curves.chroma[step] as number;
+      }
+    }
+  }
+
+  return { lightness, chroma };
+}