Build and audit interface color systems

better-colors builds and audits interface color systems. It generates ramps, assigns steps to roles and token names, converts notation and measures contrast between rendered foregrounds and backgrounds. It separates project choices from defects: a tinted neutral or gradient interpolation space is a choice, while broken role mappings, failing contrast pairs and out-of-gamut steps are findings. Contrast values must be measured rather than guessed.

The workflow starts with the project's established tokens and notation. A consistent hex system should stay consistent; OKLCH is the default for a new system, with a color library used to generate ramps in the required notation. A system needs a neutral ramp, an accent ramp and only status ramps that the product actually uses. Additional accents need a concrete distinction to communicate. Each generated step must serve a role, such as page background, hover, border, solid fill or body text.

Primitive tokens name values by hue, while semantic tokens name jobs and point to primitives. Components consume the semantic tier. This separation allows themes to repoint values without changing component code. Tokens should stay in their assigned roles rather than borrowing a separator value for text because it happens to look right. Missing roles receive their own tokens.

Ramp generation holds hue steady, peaks in vividness near the middle and uses finer light-end steps. The checks cover mismatched lightness spacing, copied saturation values across hues, and dark themes made by simply reversing the light ramp. Meaning should remain consistent across the interface, with redundant labels or icons where color carries status. When filled color communicates primary emphasis, a view gives that treatment to one primary action while preserving an established hierarchy that already works differently.

Contrast is measured against the background actually behind the content, including alpha and images. A failure report names the pair, measured result and missed threshold. Colors change only when requested, followed by remeasurement. Other checks cover competing theme-switch mechanisms, increased-contrast values for each appearance, sRGB fallbacks before wider-gamut colors and whether lightness rather than hue should change to address contrast. Gradient interpolation is treated as an aesthetic decision, with oklab as the default and oklch available when a two-hue gradient loses color in the middle.

Use it for authorized color-system creation, token audits, theme checks or contrast measurement. Reviews are read-only unless implementation is requested. It preserves unrelated work and does not turn notation preferences into correctness findings. Its guidance is scoped design advice rather than a universal proof of correctness or accessibility conformance.

Inputs include interface code, declared colors, tokens and theme blocks within the requested scope. Source-only verification checks token values, gamut, theme definitions and contrast computed from declared pairs. Browser verification measures the actual rendered background in light and dark appearances. Unavailable checks are explicitly reported as Not verified.

Findings are grouped by principle and ordered by severity, with file-and-line locations, before and after values, and user impact. HIGH covers unreadable content or misleading semantic colors; MEDIUM covers noticeable theme, token or gamut failures; LOW covers isolated polish. Remaining HIGH findings produce Block. Otherwise the report ends Approve, retaining outstanding work and limiting approval to inspected coverage.

better-accessibility decides which contrast requirement applies and owns the requirement for redundant meaning cues. The better-ui skill owns surfaces, shadows and icon color. The better-colors skill supplies the palette, token and measurement work across those boundaries.