@clhaas/palette-kit 0.3.0 → 0.4.0

package/docs/README.md

@@ -0,0 +1,60 @@
+# Palette Kit v0.4 Documentation
+
+This directory documents the current v0.4 branch implementation.
+
+The public runtime surface is intentionally small:
+
+- `createPaletteKit`
+- `palette.resolve`
+- official resolver preset configs
+
+The package root also reexports public TypeScript types. Internal modules,
+serializers, registries, validators, and resolver helpers are not public API.
+
+## Start Here
+
+- [API](./API.md)
+- [Configuration](./Config.md)
+- [Concepts](./Concepts.md)
+- [Architecture](./Architecture.md)
+- [Validation](./Validation.md)
+- [FAQ](./FAQ.md)
+
+## Usage
+
+- [Usage: Web](./Usage-Web.md)
+- [Usage: React Native](./Usage-ReactNative.md)
+- [Usage: JSON](./Usage-JSON.md)
+
+## Status References
+
+- [CLI](./CLI.md)
+- [Exporters](./Exporters.md)
+- [Tokens](./Tokens.md)
+- [Diagnostics](./Diagnostics.md)
+- [Alpha](./Alpha.md)
+- [Overlays](./Overlays.md)
+- [Text](./Text.md)
+- [Why](./Why.md)
+
+## v0.4 Planning References
+
+- [v0.4 SPEC](../planning/v0.4/v0.4-palette-kit-spec.md)
+- [Resolver Reference](../planning/v0.4/v0.4-resolver-reference.md)
+- [Output Serialization Contract](../planning/v0.4/v0.4-output-serialization-contract.md)
+- [Testing Strategy and Golden Cases](../planning/v0.4/v0.4-testing-strategy-golden-cases.md)
+
+## Diagrams
+
+- [Axes](../planning/v0.4/diagrams/axes.md)
+- [Context](../planning/v0.4/diagrams/context.md)
+- [Relations](../planning/v0.4/diagrams/relations.md)
+- [Resolver Pipeline](../planning/v0.4/diagrams/resolver-pipeline.md)
+- [What Never Happens](../planning/v0.4/diagrams/what-never-happens.md)
+
+## Historical Documents
+
+- [Legacy spec](./spec-legacy.md)
+
+The legacy spec and manifesto files are historical context. They do not define
+the current v0.4 public API.

package/docs/Text.md

@@ -0,0 +1,41 @@
+# Text and Visual Vocabulary
+
+Text, icons, and similar foreground elements use:
+
+```ts
+usage: "visualVocabulary"
+```
+
+## Rules
+
+`visualVocabulary`:
+
+- requires `on`;
+- forbids `level`;
+- resolves from the selected intent and relation target.
+
+```ts
+const surface = palette.resolve({
+  usage: "fill",
+  intent: "neutral",
+  level: 2,
+});
+
+const text = palette.resolve({
+  usage: "visualVocabulary",
+  intent: "brand",
+  on: surface,
+});
+```
+
+## Current Behavior
+
+`on` enforces APCA contrast. The default target is Lc 60. APCA is the primary
+metric; WCAG contrast is available as a fallback diagnostic when APCA does not
+produce a usable numeric value.
+
+The resolver first adjusts OKLCH lightness while preserving hue. If luminance
+alone is insufficient, it may reduce chroma within the configured limits. If the
+target still cannot be reached, resolution throws.
+
+The contrast solver never changes alpha for `visualVocabulary`.

package/docs/Tokens.md

@@ -0,0 +1,42 @@
+# Tokens
+
+Palette Kit v0.4 does not expose a public token registry or token exporter.
+
+The current model resolves colors from axes. Applications may store the resolved
+values as tokens if they need build artifacts.
+
+```ts
+const tokens = {
+  "surface.default": palette.resolve({
+    usage: "fill",
+    intent: "neutral",
+    level: 2,
+    output: "hex",
+  }),
+};
+```
+
+## Important Constraint
+
+Palette Kit rejects intent names that encode usage, state, relation, level, or
+visual implementation details. Keep those dimensions in resolver options.
+
+Prefer:
+
+```ts
+palette.resolve({
+  usage: "fill",
+  intent: "brand",
+  level: 4,
+  state: "hover",
+  stateDirection: "increase",
+});
+```
+
+Avoid designing intent names such as:
+
+```text
+brandFillHoverOnDark
+dangerStrong
+successText
+```

package/docs/Usage-JSON.md

@@ -0,0 +1,39 @@
+# Usage: JSON
+
+Palette Kit v0.4 does not expose a public JSON exporter. Build JSON manually
+from `palette.resolve` outputs.
+
+```ts
+import { createPaletteKit } from "@clhaas/palette-kit";
+
+const palette = createPaletteKit({
+  context: "light",
+  intents: {
+    brand: { hue: 260, chroma: 0.14 },
+    neutral: { hue: 0, chroma: 0 },
+  },
+});
+
+const tokens = {
+  "surface.default": palette.resolve({
+    usage: "fill",
+    intent: "neutral",
+    level: 2,
+    output: "hex",
+  }),
+  "brand.default": palette.resolve({
+    usage: "fill",
+    intent: "brand",
+    level: 4,
+    output: "hex",
+  }),
+};
+
+const json = JSON.stringify(tokens, null, 2);
+```
+
+## Notes
+
+- There is no public exporter subpath in v0.4.
+- `hex` and `rgba` are supported runtime outputs.
+- `oklch`, `oklab`, `srgb`, and `p3` are also supported runtime outputs.

package/docs/Usage-ReactNative.md

@@ -0,0 +1,63 @@
+# Usage: React Native
+
+React Native needs platform-compatible color values. In v0.4, use
+`output: "rgba"` for public runtime output.
+
+```ts
+import { createPaletteKit } from "@clhaas/palette-kit";
+
+const palette = createPaletteKit({
+  context: "light",
+  output: "rgba",
+  intents: {
+    brand: { hue: 260, chroma: 0.14 },
+    neutral: { hue: 0, chroma: 0 },
+  },
+});
+```
+
+## Resolve RGBA
+
+```ts
+const background = palette.resolve({
+  usage: "fill",
+  intent: "brand",
+  level: 4,
+});
+```
+
+`background` has this shape:
+
+```ts
+type RgbaColor = {
+  r: number;
+  g: number;
+  b: number;
+  a: number;
+};
+```
+
+Convert it to a React Native string if needed:
+
+```ts
+const rnColor = `rgba(${background.r}, ${background.g}, ${background.b}, ${background.a})`;
+```
+
+## Resolver Override
+
+You can override output per call:
+
+```ts
+const hex = palette.resolve({
+  usage: "fill",
+  intent: "brand",
+  level: 4,
+  output: "hex",
+});
+```
+
+## Notes
+
+- Palette Kit does not inspect platform color scheme automatically.
+- Provide `context` or `systemDefaultContext` explicitly.
+- `rgba` is usually the most direct React Native output.

package/docs/Usage-Web.md

@@ -0,0 +1,66 @@
+# Usage: Web
+
+Use `createPaletteKit` from the package root.
+
+```ts
+import { createPaletteKit } from "@clhaas/palette-kit";
+
+const palette = createPaletteKit({
+  context: "light",
+  intents: {
+    brand: { hue: 260, chroma: 0.14 },
+    neutral: { hue: 0, chroma: 0 },
+  },
+});
+```
+
+## Resolve OKLCH
+
+```ts
+const surface = palette.resolve({
+  usage: "fill",
+  intent: "neutral",
+  level: 2,
+});
+```
+
+The default output is a normalized OKLCH object.
+
+```ts
+surface.space; // "oklch"
+surface.l; // number in 0..100
+surface.c; // number >= 0
+surface.h; // number in [0, 360)
+surface.alpha; // number in 0..1
+```
+
+## Resolve Hex
+
+```ts
+const background = palette.resolve({
+  usage: "fill",
+  intent: "brand",
+  level: 4,
+  output: "hex",
+});
+
+document.documentElement.style.setProperty("--brand-bg", background);
+```
+
+## Resolve Related Text
+
+```ts
+const text = palette.resolve({
+  usage: "visualVocabulary",
+  intent: "brand",
+  on: surface,
+});
+```
+
+`visualVocabulary` requires `on` and forbids `level`.
+
+## Notes
+
+- `fill`, `lines`, and `overlays` require `level`.
+- `state !== "default"` requires `stateDirection`.
+- `hex`, `rgba`, `srgb`, and `p3` are available for platform delivery.

package/docs/Validation.md

@@ -0,0 +1,97 @@
+# Validation
+
+This document lists observable validation behavior in the current v0.4 branch.
+
+## Intent Registry
+
+Intent names must be flat strings:
+
+- not empty
+- no whitespace
+- no `.`
+- no encoded usage, state, relation, level, or visual implementation tokens
+
+Intent values must include finite numeric `hue` and `chroma`. Chroma must be
+greater than or equal to `0`.
+
+Examples of rejected names include `textIncome`, `incomeHover`,
+`incomeOverlay`, `incomeStrong`, and `redAlert`.
+
+Unknown intents throw:
+
+```text
+Unknown intent "<name>". Did you forget to register it in the Intent Registry?
+```
+
+## Usage
+
+Valid usages:
+
+- `fill`
+- `visualVocabulary`
+- `lines`
+- `overlays`
+
+Unknown usages throw a message listing the valid usages.
+
+## Level
+
+Valid levels are integers from `1` to `9`.
+
+Level rules:
+
+- `fill`, `lines`, and `overlays` require `level`.
+- `visualVocabulary` forbids `level`.
+
+## Relations
+
+Only one relation may be provided per resolve call.
+
+Relation rules:
+
+- `visualVocabulary` requires `on`.
+- `overlays` forbids `on`.
+- `fill` and `lines` allow `on`.
+
+Relation targets must be normalized OKLCH colors.
+
+## State
+
+Valid states:
+
+- `default`
+- `hover`
+- `active`
+- `focus`
+- `selected`
+- `disabled`
+
+When `state` is not `default`, `stateDirection` is required.
+
+## Context
+
+Valid contexts:
+
+- `light`
+- `dark`
+
+If resolver context, palette context, and system default context are all absent,
+resolution throws:
+
+```text
+Context could not be resolved. Provide resolverContext, paletteContext, or systemDefaultContext.
+```
+
+## Output
+
+Valid output names:
+
+- `oklch`
+- `oklab`
+- `srgb`
+- `p3`
+- `hex`
+- `rgba`
+
+Runtime serialization supports all valid output names. RGB-like outputs use
+explicit clip gamut handling.

package/docs/Why.md

@@ -0,0 +1,37 @@
+# Why
+
+Palette Kit exists to make semantic color resolution deterministic without
+forcing applications to maintain large sets of precomposed color tokens.
+
+## Design Direction
+
+Instead of names like `brandHoverTextOnDark`, v0.4 separates decisions into
+axes:
+
+- intent
+- usage
+- level
+- relation
+- state
+- context
+- output
+
+This keeps meaning separate from presentation and environment.
+
+## Current v0.4 Constraints
+
+- Public runtime API is `createPaletteKit`.
+- Resolution is internal OKLCH.
+- Context is explicit and never inferred.
+- Level is explicit and never inferred.
+- Output is applied after resolution.
+- `on` enforces APCA contrast explicitly.
+- `hex`, `rgba`, `oklab`, `srgb`, and `p3` are supported delivery formats.
+- Presets and resolver config are explicit public configuration.
+- CLI and exporters are not public.
+
+## Trade-Off
+
+The current v0.4 branch favors an auditable API over broad convenience tooling.
+CLI commands, token exporters, and codegen can be added later without changing
+the resolver model.

package/docs/_api-surface.md

@@ -0,0 +1,53 @@
+# API Surface Report
+
+This report reflects the current v0.4 branch package root.
+
+## Runtime Exports
+
+- `createPaletteKit`
+- `defaultResolverConfig`
+- `neutralResolverConfig`
+- `softResolverConfig`
+- `strongResolverConfig`
+
+## Type Exports
+
+- `PaletteKitConfig`
+- `PaletteKit`
+- `PaletteResolveOptions`
+- `PaletteResolveOutput`
+- `Usage`
+- `Level`
+- `State`
+- `StateDeltaDirection`
+- `Context`
+- `ColorOutput`
+- `OklchColor`
+- `RgbColor`
+- `RgbaColor`
+- `IntentDefinition`
+- `ResolverPresetName`
+- `ResolverConfig`
+- `RelationParamsConfig`
+- `ChromaConfig`
+
+## Public Package Exports
+
+Only the root export is public:
+
+```json
+{
+  ".": {
+    "types": "./dist/index.d.ts",
+    "default": "./dist/index.js"
+  }
+}
+```
+
+## Not Exported
+
+- CLI
+- exporter subpaths
+- intent registry helpers
+- internal resolver helpers
+- serializer functions

package/docs/snippets/serialize-oklch.md

@@ -0,0 +1,9 @@
+# Serialize OKLCH
+
+```ts
+const toOklch = (c: { l: number; c: number; h: number; alpha?: number }) => {
+  const a = c.alpha ?? 1;
+  const alphaPart = a < 1 ? ` / ${a}` : "";
+  return `oklch(${c.l}% ${c.c} ${c.h}${alphaPart})`;
+};
+```

package/docs/spec.md

@@ -0,0 +1,98 @@
+# Palette Kit v0.4 Current Implementation Spec
+
+This document summarizes the current v0.4 branch implementation. The complete
+planning specification lives in
+[planning/v0.4/v0.4-palette-kit-spec.md](../planning/v0.4/v0.4-palette-kit-spec.md).
+
+## Public Scope
+
+The package root exposes:
+
+- `createPaletteKit`
+- `softResolverConfig`
+- `neutralResolverConfig`
+- `strongResolverConfig`
+- `defaultResolverConfig`
+- public TypeScript types
+
+The package root does not expose CLI commands, subpath exporters, serializer
+functions, validators, or internal resolver helpers.
+
+## Public Configuration
+
+```ts
+createPaletteKit({
+  context: "light",
+  output: "oklch",
+  intents: {
+    brand: { hue: 260, chroma: 0.14 },
+    neutral: { hue: 0, chroma: 0 },
+  },
+});
+```
+
+The public config supports:
+
+- `intents`
+- `context`
+- `systemDefaultContext`
+- `output`
+- `systemDefaultOutput`
+- `preset`
+- `resolverConfig`
+
+## Resolver Axes
+
+`palette.resolve` accepts:
+
+- `usage`
+- `intent`
+- `level`
+- `on`
+- `over`
+- `under`
+- `state`
+- `stateDirection`
+- `context`
+- `output`
+
+The resolver is deterministic and resolves internally in OKLCH.
+
+## Implemented Outputs
+
+- `oklch`
+- `oklab`
+- `srgb`
+- `p3`
+- `hex`
+- `rgba`
+
+RGB-like outputs use clipped 8-bit channels. `p3` uses Display-P3 conversion
+and the current explicit clip gamut strategy.
+
+## Implemented Guarantees
+
+- Same input produces the same output.
+- Output format does not change internal OKLCH resolution.
+- Context is explicit and never inferred.
+- Context affects structural level curves while preserving semantic intent.
+- Level is explicit and never inferred.
+- Non-default state requires `stateDirection`.
+- Forbidden axis combinations throw.
+- `on` enforces APCA contrast with a default Lc 60 target and exposes WCAG as a
+  fallback diagnostic.
+- `over` applies configured alpha by level.
+- `under` applies configured alpha and luminance reduction by level.
+- State alpha deltas apply only where alpha is allowed, currently `overlays`.
+- Intent names are semantic-only and cannot encode usage, state, relation,
+  level, or visual implementation details.
+
+## Current Limitations
+
+- CLI and exporters are not public in v0.4.
+
+## References
+
+- [Resolver Reference](../planning/v0.4/v0.4-resolver-reference.md)
+- [Output Serialization Contract](../planning/v0.4/v0.4-output-serialization-contract.md)
+- [Testing Strategy](../planning/v0.4/v0.4-testing-strategy-golden-cases.md)