Colors

A color system is a small set of ramps, named by role and verified against the backgrounds they actually render on. Most color bugs are system bugs. A value picked in isolation, a token borrowed because it looked right, a pair nobody measured.

Never report a contrast value you did not measure, and never estimate a color you could compute. Colors are one of the few interface concerns with an exact answer, so produce the exact answer.

Contrast requirements belong to better-accessibility. Surfaces, shadows and icon color belong to better-ui.

Match the project's color system

Reuse the project's tokens and notation. A second representation added to fix one value makes the palette harder to reason about. A consistent hex system beats hex with oklch() scattered through it.

For a new system, oklch() is the best default, because its numbers behave the way the ramp rules below describe. Everywhere else, a color library produces the same ramp in the project's own notation (color-formats.md).

A system is ramps, not colors

One neutral ramp, one accent ramp and only the status ramps the product actually renders. A ramp nothing imports is maintenance for zero pixels. A second accent hue earns its place only when two things must be distinguishable at a glance.

Mistake	Fix
A raw value where the project has a token	Reuse or add the role token, in the project's notation
An isolated `oklch()` value dropped into a hex codebase	Keep the established notation unless a migration is in scope
A primitive like `--blue-500` used directly in a component	Point a semantic token at it
Token named for its appearance (`--color-blue-button`) or first use (`--color-sidebar-gray`)	Name it for its role: `--color-accent-solid`, `--color-bg-surface`
`--color-primary` meaning the brand and `--color-text-primary` meaning body text	Reserve `accent` for the brand; let `primary` mean "most prominent of its group"
Semantic token used outside its role (separator as text)	Add a token for the missing role; never borrow by value
Ramp built by varying HSL lightness	Rebuild against perceived lightness with a constant hue
Ramp spaced evenly across the full range	Tighten the light end until `50` and `100` read as two surfaces
Same saturation number reused across hues	Match the proportion of each hue's own maximum, not the raw value
Status hue that collides with the accent hue	Move it until destructive and primary read apart side by side
Dark mode made by mechanically reversing the light palette	Reverse as a starting point, then reduce vividness, widen the dark end and recheck every pair
`prefers-color-scheme` setting some tokens and a `.dark` class setting others	Pick one switching mechanism and use it throughout
Contrast fixed by changing hue	Change lightness, the channel contrast responds to
P3 color with no sRGB fallback	Declare the sRGB value first, then override inside `@media (color-gamut: p3)`

Better Colors

Colors

Match the project's color system

A system is ramps, not colors

Every step has a job

Name primitives by hue, semantics by role

Use a token only in its role

Hold the hue across the ramp

One color, one meaning

Fill exactly one action per view

Measure the rendered pair, then report

Pick a gradient's interpolation space

Before you finish

Reporting