Palette Kit

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.

Install

npm install @clhaas/palette-kit

Quick Start

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 },
  },
});

const surface = palette.resolve({
  usage: "fill",
  intent: "neutral",
  level: 2,
});

const text = palette.resolve({
  usage: "visualVocabulary",
  intent: "brand",
  on: surface,
});

Public Runtime API

The package root exports:

• createPaletteKit
• softResolverConfig
• neutralResolverConfig
• strongResolverConfig
• defaultResolverConfig

Public TypeScript types are also exported from the package root.

There are no public subpath exports, CLI commands, token exporters, or codegen APIs in v0.4.

Resolver Rules

Usage	Level	Relations
fill	Required	on optional
visualVocabulary	Forbidden	on required
lines	Required	on optional
overlays	Required	over or under optional

state defaults to "default". Non-default states require explicit stateDirection; Palette Kit never infers whether state should increase or decrease lightness.

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.

Output

Supported outputs:

• 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 }

RGB-like outputs use clipped 8-bit channels. Output never changes semantic resolution.

Output precedence is resolver-level output, then palette-level output, then host-injected systemDefaultOutput, then the explicit oklch default.

Configuration

createPaletteKit accepts preset and explicit resolverConfig overrides.

const palette = createPaletteKit({
  context: "light",
  preset: "soft",
  intents,
  resolverConfig: {
    relationParams: {
      on: { contrastTarget: 75 },
    },
  },
});

The default preset is neutral.

Documentation

• Docs index
• API
• Configuration
• Specification summary
• Migration

Module Format

Palette Kit is ESM-only.