Color System
Espalier generates a palette from a seed color, maps color families to UI roles, and adjusts text colors toward APCA contrast targets. Configure brand anchors and roles when a single seed is not enough, then check the result with the theme fit report.
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
Generated text colors are adjusted toward APCA Lc targets. Extreme themes can leave some targets unmet; the fit report identifies those pairs. Check custom colors outside the token system separately.
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: