OKLCH Colors
OKLCH is a perceptually uniform color space where lightness, chroma, and hue are useful design controls. Use it when the project already uses OKLCH, when creating a new color system, or when the user asks for conversion or palette work. Otherwise preserve the project's established tokens and notation: a consistent hex or RGB token system is better than introducing a second color representation for an isolated fix. To explore interactively, visit oklch.fyi.
Quick Reference
| Category |
When to use |
Reference |
| Conversion |
Hex/rgb/hsl to oklch |
color-conversion.md |
| Palettes |
Generate scales, multi-hue, dark mode |
palette-generation.md |
| Contrast |
APCA/WCAG checks, reporting failures, fixing on request |
accessibility-contrast.md |
| Gamut & Tailwind |
P3 fallbacks, @theme scales, gamut clamping |
gamut-and-tailwind.md |
| Usage |
Semantic tokens, one meaning per color, primary-action emphasis, appearance variants |
color-usage.md |
Core Principles
1. Use a Perceptual Color Space
- Respect the existing system. Do not convert notation merely because this skill was loaded. Reuse the project's semantic tokens and authoring format unless the task includes a color-system migration.
- Perceptual uniformity. Equal L steps = equal brightness.
oklch(0.5 ...) is visually mid. HSL's lightness: 50% varies wildly by hue.
- Stable hue. HSL blue shifts toward purple as lightness changes. OKLCH hue stays constant across the full lightness range.
- Independent chroma. Chroma is an absolute measure of colorfulness that doesn't depend on lightness. HSL saturation does.
- Finite gamut. Not every oklch value maps to a displayable sRGB color. High-chroma values at certain hues will clip; gamut awareness is required.
2. Write and Format OKLCH Consistently
oklch(L C H)
oklch(L C H / alpha)
| Channel |
Range |
Description |
| L (Lightness) |
0–1 |
0 = black, 1 = white. Perceptually uniform. |
| C (Chroma) |
0–~0.4 |
Colorfulness. 0 = gray. Max depends on L and H. |
| H (Hue) |
0–360 |
Hue angle in degrees. |
| alpha |
0–1 |
Optional transparency. Slash syntax. |
oklch(0.637 0.237 25.331)
oklch(0.8 0.05 200 / 0.5)
Use three decimal places for L and C and up to three for H. Drop trailing zeros and format -0 as 0. OKLCH is Baseline 2023; when support requirements are unusually broad, check the target project's browser matrix instead of relying on a fixed global-coverage percentage.
3. Measure Contrast, Gamut, and Palette Behavior
This skill owns contrast measurement and which algorithm settles a verdict. APCA and WCAG 2
are different models with no exact conversion, so one rule decides:
- A formal WCAG 2.x conformance claim, or a legal or contractual accessibility requirement, or
a named level such as AA or AAA in the request → the WCAG ratio decides. Report the Lc as
supporting evidence.
- Anything else → APCA
Lc decides. Report the WCAG ratio when the two disagree.
- Cannot tell whether a conformance claim exists → use WCAG. It is the stricter obligation to miss.
better-accessibility decides whether contrast is required for a given element and how severe
a failure is; this skill measures the rendered pair and answers in whichever unit the rule above
selects. Never report only the flattering number. Full thresholds are in
accessibility-contrast.md.
| Rule |
Value |
| Light/dark boundary |
Neutral-background heuristic: L > 0.73 = light background → dark text; below it, light text still scores higher. Hue and chroma can flip the higher-contrast polarity, so always verify the rendered pair |
| Lightness gap (light bg) |
Foreground L < 0.35 when background L > 0.9 |
| Lightness gap (dark bg) |
Foreground L > 0.9 when background L < 0.25 |
| Hue drift threshold |
> 10° spread across palette steps = visible drift |
| APCA body text |
|Lc| >= 75 minimum, >= 90 preferred; thresholds depend on text size, weight, and foreground/background polarity — measure the rendered pair before reporting a verdict |
| APCA non-body text |
|Lc| >= 60 minimum |
| WCAG 2 normal text |
4.5:1 AA, 7:1 AAA |
| Contrast fix (only when asked) |
Adjust L first; preserve C and H when possible, then remeasure the rendered pair |
Common Mistakes
| Issue |
Fix |
| Raw color bypasses the project's semantic token system |
Reuse or add the correct role token in the project's existing notation |
| Isolated OKLCH value introduced into a hex/RGB codebase |
Preserve the established notation unless the task includes a color-system migration |
| HSL palette ramp with hue drift |
Rebuild with constant oklch hue |
| Failing contrast (check foreground vs its background using APCA) |
Report the pair, its measured Lc and the threshold it misses; change colors only when asked (then adjust L, keep C and H) |
| High chroma without gamut check |
Clamp to max chroma for the L/H in sRGB |
| Same absolute C across different hues |
Use same C% (percentage of max) for consistent vividness |
| P3 color without sRGB fallback |
Add @media (color-gamut: p3) pattern |
| Dark mode created by mechanically reversing the light palette |
Use the light palette as a starting point, then tune chroma and lightness and recheck every foreground/background pair |
Hex in Tailwind v4 @theme |
Convert to oklch values |
| Alpha with comma syntax |
Use slash: oklch(L C H / alpha) |
| Same hue means two different things (link color reused decoratively) |
One color, one meaning; give the second use a neutral |
| Semantic token used outside its role (separator as text) |
Add a token for the missing role; never borrow by value |
| Several colored control backgrounds in one view |
Fill only the single primary action; secondaries stay neutral |
| Palette verified only in light mode |
Recheck every foreground/background pair in both appearances |
Severity
HIGH makes content unreadable or assigns a misleading semantic color.MEDIUM creates a noticeable theme, gamut, or consistency failure.LOW is isolated polish.
Review Output Format
Use this format only when the user asks for a standalone color review. When better-interface orchestrates the review, provide domain evidence and findings to that skill and let its output format, severity scale, consolidation rules, cap, and verdict take precedence.
Present the standalone review in two parts.
Findings
Group all confirmed findings by principle. Use a markdown table with Severity, Location, Before, After, and Why columns. Never use separate "Before:" / "After:" lines.
- Location: cite
path/to/file:line. If the artifact has no source files, cite the exact screen and component instead.
- Before / After: show the current value or token and the exact replacement.
- Why: name the violated principle and include measured contrast or gamut evidence when relevant.
Consolidate a repeated systemic issue into one row and list every affected location. Omit principles with no findings.
| Severity |
Location |
Before |
After |
Why |
| MEDIUM |
src/theme.css:18 |
color: #3b82f6 |
color: oklch(0.623 0.188 259.815) |
New project colors use OKLCH tokens |
| MEDIUM |
src/palette.ts:31 |
Same absolute C across hues |
Same C% of each hue's maximum chroma |
Equal chroma values do not appear equally vivid across hues |
| HIGH |
src/theme.css:52 |
P3 color with no fallback |
Add an sRGB fallback before @media (color-gamut: p3) |
The color fails on non-P3 displays |
Verification and Verdict
After the findings:
- Verification: list the exact checks run and their observed results, including contrast measurements, gamut checks, and both light and dark appearances when applicable. If a check was not run, state what still needs verification.
- Verdict:
Block if any HIGH finding remains, Needs changes if only MEDIUM or LOW findings remain, and Approve only when no actionable findings remain.
When there are no findings, omit the table, state "No actionable color findings", report verification, and end with Approve.
1---2name: better-colors3description: OKLCH color space and color usage for web projects. Convert hex/rgb/hsl to oklch, generate palettes, check contrast, handle gamut boundaries, theme with Tailwind v4, and apply color with meaning. Triggers on oklch, color conversion, palette generation, contrast ratio, APCA, gamut, display p3, design tokens, semantic color tokens, hue drift, chroma, dark mode colors, accent color, color meaning, light and dark appearance, increased contrast.4license: MIT5---67# OKLCH Colors89OKLCH is a perceptually uniform color space where lightness, chroma, and hue are useful design controls. Use it when the project already uses OKLCH, when creating a new color system, or when the user asks for conversion or palette work. Otherwise preserve the project's established tokens and notation: a consistent hex or RGB token system is better than introducing a second color representation for an isolated fix. To explore interactively, visit [oklch.fyi](https://oklch.fyi).1011## Quick Reference1213| Category | When to use | Reference |14| --- | --- | --- |15| Conversion | Hex/rgb/hsl to oklch | [color-conversion.md](references/color-conversion.md) |16| Palettes | Generate scales, multi-hue, dark mode | [palette-generation.md](references/palette-generation.md) |17| Contrast | APCA/WCAG checks, reporting failures, fixing on request | [accessibility-contrast.md](references/accessibility-contrast.md) |18| Gamut & Tailwind | P3 fallbacks, `@theme` scales, gamut clamping | [gamut-and-tailwind.md](references/gamut-and-tailwind.md) |19| Usage | Semantic tokens, one meaning per color, primary-action emphasis, appearance variants | [color-usage.md](references/color-usage.md) |2021## Core Principles2223### 1. Use a Perceptual Color Space2425- **Respect the existing system.** Do not convert notation merely because this skill was loaded. Reuse the project's semantic tokens and authoring format unless the task includes a color-system migration.26- **Perceptual uniformity.** Equal L steps = equal brightness. `oklch(0.5 ...)` is visually mid. HSL's `lightness: 50%` varies wildly by hue.27- **Stable hue.** HSL blue shifts toward purple as lightness changes. OKLCH hue stays constant across the full lightness range.28- **Independent chroma.** Chroma is an absolute measure of colorfulness that doesn't depend on lightness. HSL saturation does.29- **Finite gamut.** Not every oklch value maps to a displayable sRGB color. High-chroma values at certain hues will clip; gamut awareness is required.3031### 2. Write and Format OKLCH Consistently3233```34oklch(L C H)35oklch(L C H / alpha)36```3738| Channel | Range | Description |39| --- | --- | --- |40| L (Lightness) | 0–1 | 0 = black, 1 = white. Perceptually uniform. |41| C (Chroma) | 0–~0.4 | Colorfulness. 0 = gray. Max depends on L and H. |42| H (Hue) | 0–360 | Hue angle in degrees. |43| alpha | 0–1 | Optional transparency. Slash syntax. |4445```css46oklch(0.637 0.237 25.331)47oklch(0.8 0.05 200 / 0.5)48```4950Use three decimal places for L and C and up to three for H. Drop trailing zeros and format `-0` as `0`. OKLCH is Baseline 2023; when support requirements are unusually broad, check the target project's browser matrix instead of relying on a fixed global-coverage percentage.5152### 3. Measure Contrast, Gamut, and Palette Behavior5354**This skill owns contrast measurement and which algorithm settles a verdict.** APCA and WCAG 255are different models with no exact conversion, so one rule decides:5657- A formal WCAG 2.x conformance claim, or a legal or contractual accessibility requirement, or58 a named level such as AA or AAA in the request → **the WCAG ratio decides**. Report the Lc as59 supporting evidence.60- Anything else → **APCA `Lc` decides**. Report the WCAG ratio when the two disagree.61- Cannot tell whether a conformance claim exists → use WCAG. It is the stricter obligation to miss.6263`better-accessibility` decides *whether* contrast is required for a given element and how severe64a failure is; this skill measures the rendered pair and answers in whichever unit the rule above65selects. Never report only the flattering number. Full thresholds are in66[accessibility-contrast.md](references/accessibility-contrast.md).6768| Rule | Value |69| --- | --- |70| Light/dark boundary | Neutral-background heuristic: L > 0.73 = light background → dark text; below it, light text still scores higher. Hue and chroma can flip the higher-contrast polarity, so always verify the rendered pair |71| Lightness gap (light bg) | Foreground L < 0.35 when background L > 0.9 |72| Lightness gap (dark bg) | Foreground L > 0.9 when background L < 0.25 |73| Hue drift threshold | > 10° spread across palette steps = visible drift |74| APCA body text | \|Lc\| >= 75 minimum, >= 90 preferred; thresholds depend on text size, weight, and foreground/background polarity — measure the rendered pair before reporting a verdict |75| APCA non-body text | \|Lc\| >= 60 minimum |76| WCAG 2 normal text | 4.5:1 AA, 7:1 AAA |77| Contrast fix (only when asked) | Adjust L first; preserve C and H when possible, then remeasure the rendered pair |7879## Common Mistakes8081| Issue | Fix |82| --- | --- |83| Raw color bypasses the project's semantic token system | Reuse or add the correct role token in the project's existing notation |84| Isolated OKLCH value introduced into a hex/RGB codebase | Preserve the established notation unless the task includes a color-system migration |85| HSL palette ramp with hue drift | Rebuild with constant oklch hue |86| Failing contrast (check foreground vs its background using APCA) | Report the pair, its measured Lc and the threshold it misses; change colors only when asked (then adjust L, keep C and H) |87| High chroma without gamut check | Clamp to max chroma for the L/H in sRGB |88| Same absolute C across different hues | Use same C% (percentage of max) for consistent vividness |89| P3 color without sRGB fallback | Add `@media (color-gamut: p3)` pattern |90| Dark mode created by mechanically reversing the light palette | Use the light palette as a starting point, then tune chroma and lightness and recheck every foreground/background pair |91| Hex in Tailwind v4 `@theme` | Convert to oklch values |92| Alpha with comma syntax | Use slash: `oklch(L C H / alpha)` |93| Same hue means two different things (link color reused decoratively) | One color, one meaning; give the second use a neutral |94| Semantic token used outside its role (separator as text) | Add a token for the missing role; never borrow by value |95| Several colored control backgrounds in one view | Fill only the single primary action; secondaries stay neutral |96| Palette verified only in light mode | Recheck every foreground/background pair in both appearances |9798## Severity99100- `HIGH` makes content unreadable or assigns a misleading semantic color.101- `MEDIUM` creates a noticeable theme, gamut, or consistency failure.102- `LOW` is isolated polish.103104## Review Output Format105106Use this format only when the user asks for a standalone color review. When `better-interface` orchestrates the review, provide domain evidence and findings to that skill and let its output format, severity scale, consolidation rules, cap, and verdict take precedence.107108Present the standalone review in two parts.109110### Findings111112Group all confirmed findings by principle. Use a markdown table with **Severity**, **Location**, **Before**, **After**, and **Why** columns. Never use separate "Before:" / "After:" lines.113114- **Location**: cite `path/to/file:line`. If the artifact has no source files, cite the exact screen and component instead.115- **Before / After**: show the current value or token and the exact replacement.116- **Why**: name the violated principle and include measured contrast or gamut evidence when relevant.117118Consolidate a repeated systemic issue into one row and list every affected location. Omit principles with no findings.119120| Severity | Location | Before | After | Why |121| --- | --- | --- | --- | --- |122| MEDIUM | `src/theme.css:18` | `color: #3b82f6` | `color: oklch(0.623 0.188 259.815)` | New project colors use OKLCH tokens |123| MEDIUM | `src/palette.ts:31` | Same absolute C across hues | Same C% of each hue's maximum chroma | Equal chroma values do not appear equally vivid across hues |124| HIGH | `src/theme.css:52` | P3 color with no fallback | Add an sRGB fallback before `@media (color-gamut: p3)` | The color fails on non-P3 displays |125126### Verification and Verdict127128After the findings:1291301. **Verification**: list the exact checks run and their observed results, including contrast measurements, gamut checks, and both light and dark appearances when applicable. If a check was not run, state what still needs verification.1312. **Verdict**: `Block` if any `HIGH` finding remains, `Needs changes` if only `MEDIUM` or `LOW` findings remain, and `Approve` only when no actionable findings remain.132133When there are no findings, omit the table, state "No actionable color findings", report verification, and end with `Approve`.
BjornMelin