color
Choosing and Repairing Color
Write every new color as oklch(), and repair every broken one by moving exactly one channel. Lightness alone carries contrast, hue alone carries identity, chroma alone falls out of gamut — so a fix that moves two at once is a guess wearing the costume of a decision. The default palette posture is austere: one hue per ramp, one saturated accent in the entire chrome, a grey ladder instead of a second hue for secondary text, and a warm off-white canvas rather than #fff. This skill decides what a color is; design-tokens decides what the variable holding it is called and which tier it sits in; dark-mode maps a finished light set onto dark surfaces and never picks a brand hue. Contrast ratios have one owner and it is this skill — a11y deliberately carries none.
Read the project's color plumbing before touching a value. Find where colors are declared — :root custom properties, a Tailwind v4 @theme block, a CSS-in-JS theme object, a generated token pipeline — and make the change in that mechanism, at that layer. If a ramp exists, extend it rather than starting a second. A color fix is never a reason to bolt on a parallel theming layer, and a hex literal typed into a component is a bug even when the hex is right.
Quick Reference
| Open this | When |
|---|---|
| converting-colors.md | Migrating hex / rgb() / hsl() literals, and you need what must not be converted. |
| building-scales.md | Generating a ramp, equalizing hues into one family, or auditing a scale for drift. |
| contrast.md | A specific foreground/background pair fails, or a compliance target is named. |
| gamut-p3-tailwind.md | A chroma looks clipped, a color must survive both gamuts, or you are authoring a Tailwind v4 @theme palette. |
Core Principles
- Write new color as
oklch(); convert old color value-for-value. The channels track perception, so palette math and contrast repair become arithmetic rather than eyeballing. Three decimals per channel is enough, and alpha goes after a slash —oklch(0.586 0.222 17.585 / 0.9), never a fourth comma-separated argument. Exception: third-party config that parses hex (charting libraries,manifest.json, email templates) keeps hex; converting it breaks the consumer.