better-colors

SKILL.md

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 warning 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.

Every step has a job