Color System
Espalier generates a complete, accessible color palette from a single seed color. You provide a brand hue; the system derives harmonious color families, maps them to semantic roles, and enforces APCA contrast — all without manual tuning.
Color model
Espalier uses OKLCH as its internal color model. OKLCH is perceptually uniform, gamut-independent, and maps naturally to APCA contrast calculations. You can write seed colors in any CSS format; the system converts them internally.
Theming
A theme is a configuration object with a seedColor and optional overrides.
Pass it to <esp-root> to generate the full token set for your app.
The lightness ramp
Anchors declare which colors a theme uses; the eleven-stop lightness ramp decides where they sit. Seating brand swatches on their exact measured stops is the judgement half of fitting a brand — this guide documents the procedure, with a worked example, and explains when an isolated custom tone is safer than moving a shared stop.
Semantic color groups
Espalier's 23 semantic tokens cluster into six groups: foundation surfaces, structure and chrome, content ink, action surfaces, inline emphasis, and utility/status. Understanding these groups helps you configure themes correctly and build theme editors that expose the right choices.
Accessibility
All generated text tokens meet APCA Lc targets automatically. Custom colors you add outside the token system are your responsibility to check.
Theme fit report
Contrast enforcement and anchor resolution both move tokens silently. The dev-mode fit report shows, per token, what the theme asked for, what was emitted, every contrast adjustment with its reason, and how far an anchor-sourced token landed from its brand swatch.
Data colors and ramps
Charts use a separate eight-slot categorical palette plus perceptual sequential and diverging ramps. This keeps series identity out of the semantic status families and warns when overrides become difficult to distinguish under color-vision-deficiency simulations.
Color format references
If you encounter legacy color formats in existing codebases, these guides cover the formats and their trade-offs: