@clhaas/palette-kit 0.3.0 → 0.4.0

package/docs/API.md

@@ -0,0 +1,167 @@
+# API
+
+This document describes the public API exposed by the package root in the v0.4
+branch.
+
+## Public Entry Point
+
+```ts
+import { createPaletteKit } from "@clhaas/palette-kit";
+```
+
+The package root exports `createPaletteKit` and the official resolver preset
+configs. Public TypeScript types are also reexported from the package root.
+
+## createPaletteKit
+
+```ts
+function createPaletteKit(config: PaletteKitConfig): PaletteKit;
+```
+
+`createPaletteKit` creates an immutable palette resolver. It normalizes the
+intent registry once and keeps context and output defaults explicit.
+
+```ts
+const palette = createPaletteKit({
+  context: "light",
+  output: "oklch",
+  preset: "neutral",
+  intents: {
+    brand: { hue: 260, chroma: 0.14 },
+    neutral: { hue: 0, chroma: 0 },
+  },
+});
+```
+
+## palette.resolve
+
+```ts
+palette.resolve({
+  usage,
+  intent,
+  level,
+  on,
+  over,
+  under,
+  state,
+  stateDirection,
+  context,
+  output,
+});
+```
+
+Resolution always happens in OKLCH first. The selected `output` is applied only
+after resolution.
+
+```ts
+const surface = palette.resolve({
+  usage: "fill",
+  intent: "neutral",
+  level: 2,
+});
+
+const text = palette.resolve({
+  usage: "visualVocabulary",
+  intent: "brand",
+  on: surface,
+});
+```
+
+## Usage Rules
+
+| Usage | Level | Relations |
+| --- | --- | --- |
+| `fill` | Required | `on` optional |
+| `visualVocabulary` | Forbidden | `on` required |
+| `lines` | Required | `on` optional |
+| `overlays` | Required | `over` or `under` optional |
+
+`on` enforces APCA contrast. The default target is Lc 60. If the resolver cannot
+meet the target after the configured luminance shift and chroma reduction, it
+throws.
+
+## State Rules
+
+`state` defaults to `"default"`.
+
+When `state` is not `"default"`, `stateDirection` is required. Palette Kit never
+infers whether a state should increase or decrease lightness.
+
+```ts
+palette.resolve({
+  usage: "fill",
+  intent: "brand",
+  level: 4,
+  state: "hover",
+  stateDirection: "increase",
+});
+```
+
+## Context Rules
+
+Context is never inferred from the system or DOM.
+
+Precedence:
+
+1. Resolver-level `context`
+2. Palette-level `context`
+3. `systemDefaultContext`
+
+If none is available, resolution throws.
+
+Context affects default level curves. In dark context, the default fill and
+lines curves use the inverted structural lightness scale while preserving
+intent hue and chroma.
+
+## Output Rules
+
+| Output | Runtime status |
+| --- | --- |
+| `oklch` | Returns normalized OKLCH object |
+| `oklab` | Returns OKLab object |
+| `srgb` | Returns `{ r, g, b, alpha }` |
+| `p3` | Returns Display-P3 `{ r, g, b, alpha }` |
+| `hex` | Serialized to `#rrggbb` |
+| `rgba` | Serialized to `{ r, g, b, a }` |
+
+RGB-like outputs use clipped 8-bit channels.
+
+Output precedence:
+
+1. Resolver-level `output`
+2. Palette-level `output`
+3. `systemDefaultOutput`
+4. Explicit `oklch` default
+
+## Public Types
+
+The package root reexports:
+
+- `PaletteKitConfig`
+- `PaletteKit`
+- `PaletteResolveOptions`
+- `PaletteResolveOutput`
+- `Usage`
+- `Level`
+- `State`
+- `StateDeltaDirection`
+- `Context`
+- `ColorOutput`
+- `OklchColor`
+- `RgbColor`
+- `RgbaColor`
+- `IntentDefinition`
+- `ResolverPresetName`
+- `ResolverConfig`
+- `ResolverConfigOverrides`
+- `RelationParamsConfig`
+- `ChromaConfig`
+
+## Not Public in v0.4
+
+- Intent registry helpers
+- Validators
+- Internal resolver helpers
+- Serializer functions
+- CLI
+- Subpath exporters

package/docs/Alpha.md

@@ -0,0 +1,14 @@
+# Alpha
+
+Alpha is present in the normalized OKLCH model as `alpha`.
+
+In the current v0.4 implementation:
+
+- base resolved OKLCH colors use `alpha: 1`;
+- `rgba` output maps alpha to `a`;
+- `over` and `under` relations apply configured alpha by level;
+- state alpha deltas from `resolverConfig` apply only to `overlays`;
+- non-overlay usages preserve resolved alpha and never use alpha to satisfy
+  contrast.
+
+Alpha behavior is explicit and deterministic.

package/docs/Architecture.md

@@ -0,0 +1,56 @@
+# Architecture
+
+This document reflects the current v0.4 branch implementation.
+
+## Public Flow
+
+```text
+createPaletteKit(config) -> palette.resolve(options) -> output
+```
+
+Resolution is deterministic and side-effect free.
+
+## Main Layers
+
+- `core`: OKLCH model and intent registry.
+- `engine`: usage, level, state, relation, context, and resolver pipeline.
+- `export`: output typing and serializers.
+- `presets`: official resolver presets and config merge helpers.
+- `types`: public type contracts reexported by the package root.
+- `utils`: structured internal errors.
+
+## Resolver Pipeline
+
+The internal resolver:
+
+1. validates usage, state, context, level, and relations;
+2. looks up the registered intent;
+3. selects the usage strategy;
+4. applies context-aware level curves for level-driven usages;
+5. applies relation validation and behavior;
+6. applies explicit luminance state deltas and overlay alpha deltas;
+7. applies structural context hooks;
+8. returns normalized OKLCH.
+
+Output serialization happens after resolution.
+
+## Public Outputs
+
+- `oklch`: normalized OKLCH object.
+- `oklab`: OKLab object.
+- `srgb`: clipped 8-bit sRGB object.
+- `p3`: clipped 8-bit Display-P3 object.
+- `hex`: serialized sRGB hex string.
+- `rgba`: serialized sRGB object.
+
+## Not Public in v0.4
+
+- CLI
+- subpath exporters
+- serializer functions
+- registry helpers
+
+See also:
+
+- [Resolver Pipeline Diagram](../planning/v0.4/diagrams/resolver-pipeline.md)
+- [Axes Diagram](../planning/v0.4/diagrams/axes.md)

package/docs/CLI.md

@@ -0,0 +1,22 @@
+# CLI
+
+Palette Kit v0.4 does not expose a public CLI.
+
+There is no `bin` entry in the current package surface and no documented command
+for generating tokens.
+
+Use the runtime API directly:
+
+```ts
+import { createPaletteKit } from "@clhaas/palette-kit";
+
+const palette = createPaletteKit({
+  context: "light",
+  intents: {
+    brand: { hue: 260, chroma: 0.14 },
+  },
+});
+```
+
+CLI support may be added in a future phase, but it is not part of v0.4 current
+implementation.

package/docs/Concepts.md

@@ -0,0 +1,73 @@
+# Concepts
+
+Palette Kit v0.4 resolves colors from orthogonal axes instead of precomposed
+tokens.
+
+## Intent
+
+An intent is a semantic hue and chroma anchor.
+
+```ts
+intents: {
+  brand: { hue: 260, chroma: 0.14 },
+  neutral: { hue: 0, chroma: 0 },
+}
+```
+
+Intent does not encode usage, level, state, relation, or context.
+
+## Usage
+
+`usage` describes how the color is used:
+
+- `fill`
+- `visualVocabulary`
+- `lines`
+- `overlays`
+
+## Level
+
+`level` is an explicit integer from `1` to `9`.
+
+It is required for:
+
+- `fill`
+- `lines`
+- `overlays`
+
+It is forbidden for `visualVocabulary`.
+
+## Relation
+
+Relations connect one resolved color to another:
+
+- `on`
+- `over`
+- `under`
+
+`visualVocabulary` requires `on`.
+
+## State
+
+`state` defaults to `default`.
+
+When state is not `default`, the caller must provide `stateDirection` as
+`increase` or `decrease`.
+
+## Context
+
+Context is `light` or `dark`. It is never inferred automatically.
+
+Precedence:
+
+1. resolver-level context
+2. palette-level context
+3. system default context
+
+## Output
+
+Output is a delivery concern, not semantic input.
+
+Changing output must not change internal OKLCH resolution.
+
+See [What Never Happens](../planning/v0.4/diagrams/what-never-happens.md).

package/docs/Config.md

@@ -0,0 +1,144 @@
+# Configuration
+
+`createPaletteKit` accepts a small explicit configuration object.
+
+```ts
+import { createPaletteKit } from "@clhaas/palette-kit";
+
+const palette = createPaletteKit({
+  context: "light",
+  output: "oklch",
+  intents: {
+    brand: { hue: 260, chroma: 0.14 },
+    neutral: { hue: 0, chroma: 0 },
+  },
+});
+```
+
+## intents
+
+```ts
+Record<string, { hue: number; chroma: number }>
+```
+
+`intents` is required. Intent names must be flat strings:
+
+- not empty
+- no whitespace
+- no `.`
+
+`hue` must be finite and is normalized to `[0, 360)`. `chroma` must be finite
+and greater than or equal to `0`.
+
+Intent names must describe semantic meaning only. Names that encode usage,
+state, relation, level, or visual implementation details are rejected. Keep
+dimensions such as `fill`, `hover`, `on`, `strong`, `red`, and `dark` in
+resolver options or configuration instead of intent names.
+
+## context
+
+```ts
+"light" | "dark"
+```
+
+`context` is optional at palette creation. It becomes the default environment
+for resolver calls.
+
+Palette Kit never reads `prefers-color-scheme`, the DOM, or platform state.
+
+Context affects default level curves. Dark context inverts the structural
+lightness scale for `fill` and `lines` while preserving semantic hue and chroma.
+
+## systemDefaultContext
+
+```ts
+"light" | "dark"
+```
+
+`systemDefaultContext` is an optional host-provided fallback.
+
+Context precedence:
+
+1. Resolver-level `context`
+2. Palette-level `context`
+3. `systemDefaultContext`
+
+If no context can be resolved, `palette.resolve` throws.
+
+## output
+
+```ts
+"oklch" | "oklab" | "srgb" | "p3" | "hex" | "rgba"
+```
+
+`output` is optional and defaults to `oklch`.
+
+Runtime support in the current v0.4 implementation:
+
+- `oklch`: supported
+- `oklab`: supported
+- `srgb`: supported
+- `p3`: supported
+- `hex`: supported
+- `rgba`: supported
+
+## systemDefaultOutput
+
+```ts
+"oklch" | "oklab" | "srgb" | "p3" | "hex" | "rgba"
+```
+
+`systemDefaultOutput` is an optional host-provided output fallback.
+
+Output precedence:
+
+1. Resolver-level `output`
+2. Palette-level `output`
+3. `systemDefaultOutput`
+4. Explicit `oklch` default
+
+## Presets and Resolver Config
+
+`preset` is optional and defaults to `"neutral"`.
+
+```ts
+createPaletteKit({
+  context: "light",
+  preset: "soft",
+  intents,
+});
+```
+
+Public presets:
+
+- `soft`
+- `neutral`
+- `strong`
+
+`resolverConfig` explicitly overrides the selected preset.
+
+```ts
+createPaletteKit({
+  context: "light",
+  preset: "neutral",
+  intents,
+  resolverConfig: {
+    relationParams: {
+      on: { contrastTarget: 75 },
+    },
+    stateDeltas: {
+      luminance: { hover: 4 },
+    },
+  },
+});
+```
+
+Supported resolver config sections:
+
+- `levelCurves`
+- `stateDeltas`
+- `relationParams`
+- `chromaLimits`
+
+The default `on` contrast target is APCA Lc 60. `over` and `under` alpha values
+are configured per level.

package/docs/Diagnostics.md

@@ -0,0 +1,22 @@
+# Diagnostics
+
+Palette Kit v0.4 does not expose a public diagnostics API.
+
+Runtime misuse is reported through thrown errors. Core resolver/configuration
+misuse uses structured internal `PaletteKitError` instances, but that class is
+not part of the public API surface yet.
+
+## Observable Error Areas
+
+- unknown intent
+- missing required level
+- forbidden level on `visualVocabulary`
+- missing `on` relation
+- multiple relations
+- unresolved context
+- invalid or unsupported serialized output
+
+## Current Recommendation
+
+Catch errors at application boundaries and report the message. Do not depend on
+internal error classes until they are explicitly exported.

package/docs/Exporters.md

@@ -0,0 +1,33 @@
+# Exporters
+
+Palette Kit v0.4 does not expose public CSS or JSON exporters.
+
+There is no public exporter subpath.
+
+## Current Public Path
+
+Build exported artifacts manually from `palette.resolve`.
+
+```ts
+const tokens = {
+  "brand.surface": palette.resolve({
+    usage: "fill",
+    intent: "brand",
+    level: 4,
+    output: "hex",
+  }),
+};
+```
+
+## Supported Runtime Outputs
+
+- `oklch`
+- `oklab`
+- `srgb`
+- `p3`
+- `hex`
+- `rgba`
+
+## Future Work
+
+Public exporters may be added after the minimal v0.4 resolver surface is stable.

package/docs/FAQ.md

@@ -0,0 +1,59 @@
+# FAQ
+
+## What is the public API in v0.4?
+
+The public runtime API is `createPaletteKit` from the package root.
+
+```ts
+import { createPaletteKit } from "@clhaas/palette-kit";
+```
+
+The palette instance exposes `palette.resolve`.
+
+## Does Palette Kit return CSS strings?
+
+It depends on `output`.
+
+- `output: "oklch"` returns a normalized OKLCH object.
+- `output: "oklab"` returns an OKLab object.
+- `output: "srgb"` returns `{ r, g, b, alpha }`.
+- `output: "p3"` returns Display-P3 `{ r, g, b, alpha }`.
+- `output: "hex"` returns a `#rrggbb` string.
+- `output: "rgba"` returns `{ r, g, b, a }`.
+
+## Are `oklab`, `srgb`, and `p3` supported?
+
+Yes. `oklab` returns an OKLab object. `srgb` and `p3` return RGB-like objects
+with `{ r, g, b, alpha }`.
+
+## Is there a CLI?
+
+No. There is no public CLI in the v0.4 branch.
+
+## Can I export CSS variables or JSON tokens?
+
+There is no public exporter subpath in v0.4. Build CSS, JSON, or token files
+manually from `palette.resolve`.
+
+## Are presets public?
+
+Yes. `soft`, `neutral`, and `strong` are public resolver presets. The package
+root also exports the preset config objects.
+
+`createPaletteKit` accepts `preset` and explicit `resolverConfig` overrides.
+
+## Does `on` enforce contrast?
+
+Yes. `on` enforces APCA contrast with a default Lc 60 target and fails
+explicitly if the target cannot be satisfied.
+
+## Does Palette Kit detect dark mode?
+
+No. Context is explicit. Provide `context`, resolver-level `context`, or
+`systemDefaultContext`.
+
+## Can output have a host default?
+
+Yes. Use `systemDefaultOutput` when the host wants to inject a fallback. Resolver
+output overrides palette output, palette output overrides `systemDefaultOutput`,
+and `oklch` is used when none of those are provided.

package/docs/Migration.md

@@ -0,0 +1,61 @@
+# Migration Notes for the v0.4 Branch
+
+The v0.4 branch is a rebuild around `createPaletteKit` and orthogonal resolver
+axes. It is not a continuation of the older theme factory API.
+
+## Removed From the Public Surface
+
+- legacy theme factory
+- public exporter subpaths
+- public serializer subpaths
+- CLI commands
+- seed-based theme config
+- older public presets
+
+## Current Public Surface
+
+```ts
+import { createPaletteKit } from "@clhaas/palette-kit";
+
+const palette = createPaletteKit({
+  context: "light",
+  intents: {
+    brand: { hue: 260, chroma: 0.14 },
+    neutral: { hue: 0, chroma: 0 },
+  },
+});
+```
+
+## Conceptual Migration
+
+Older versions organized resolution around seeds, roles, surfaces, and theme
+helpers. The v0.4 branch organizes resolution around explicit axes:
+
+- `intent`
+- `usage`
+- `level`
+- `relation`
+- `state`
+- `context`
+- `output`
+
+## Output Migration
+
+Use resolver output directly:
+
+```ts
+const color = palette.resolve({
+  usage: "fill",
+  intent: "brand",
+  level: 4,
+  output: "hex",
+});
+```
+
+There is no public token exporter or CLI in the current v0.4 branch.
+
+## References
+
+- [API](./API.md)
+- [Configuration](./Config.md)
+- [v0.4 SPEC](../planning/v0.4/v0.4-palette-kit-spec.md)

package/docs/Overlays.md

@@ -0,0 +1,33 @@
+# Overlays
+
+`overlays` is a public usage value in v0.4.
+
+```ts
+const scrim = palette.resolve({
+  usage: "overlays",
+  intent: "neutral",
+  level: 1,
+  under: surface,
+});
+```
+
+## Rules
+
+- `level` is required.
+- `on` is forbidden.
+- `over` and `under` are optional relation targets.
+
+## Current Behavior
+
+The current v0.4 resolver applies configured relation behavior:
+
+- base lightness is `50`;
+- the overlay level curve can add a configured luminance delta;
+- `over` applies alpha from `relationParams.over.baseAlphaByLevel`;
+- `under` applies alpha from `relationParams.under.baseAlphaByLevel`;
+- `under` also reduces lightness by
+  `relationParams.under.luminanceReduction`;
+- non-default state can apply configured overlay alpha deltas when
+  `stateDirection` is provided;
+
+`over` and `under` do not enforce contrast.