Oklch Skill

# Accessibility & Contrast

Contrast is always measured between a **foreground color** (text, icon, or UI element) and the **background color** it sits on. When checking contrast, identify the background the element will be rendered against — typically the nearest parent's background color.

## APCA thresholds (recommended)

APCA (Accessible Perceptual Contrast Algorithm) is more perceptually accurate than WCAG 2 and pairs naturally with oklch since both are grounded in perceptual lightness. Use APCA as the default.

Lc (Lightness Contrast) measures the perceived contrast between foreground and background. These are conservative approximations:

| Content Type | Pass | Pass+ |
| --- | --- | --- |
| Normal text | Lc 60 | Lc 75 |
| Large text | Lc 45 | Lc 60 |
| UI components | Lc 30 | — |

APCA's Lc value is signed — positive means light text on dark background, negative means dark text on light. Use the absolute value for threshold comparison.

## WCAG 2 thresholds (for legal compliance)

WCAG 2 is still required when making formal WCAG 2.x conformance claims. It uses a luminance ratio that can be both too strict and too lenient depending on the color pair.

| Content Type | AA | AAA |
| --- | --- | --- |
| Normal text (<18px / <14px bold) | 4.5:1 | 7:1 |
| Large text (>=18px / >=14px bold) | 3:1 | 4.5:1 |
| UI components & graphical objects | 3:1 | — |

## Fixing contrast with oklch

In hex/rgb, fixing contrast means trial and error across three channels. In oklch, contrast is controlled by **lightness (L) alone** — adjust the L distance between the foreground and its background:

```css
/* Failing: text too close in lightness to its background */
color: oklch(0.65 0.2 250);       /* foreground */
background: oklch(0.75 0.05 250); /* background */

/* Fix: darken the text, keep C and H unchanged */
color: oklch(0.35 0.2 250);       /* foreground — more L distance */
background: oklch(0.75 0.05 250); /* background — unchanged */
```

Chroma has negligible effect on contrast — always adjust L, never C.

## Quick lightness gap guide

- **Light background (L > 0.85):** foreground L should be below 0.45
- **Dark background (L < 0.25):** foreground L should be above 0.75

These are approximations — always verify with an actual contrast calculation.

## Light vs dark color detection

A color is considered light when its oklch lightness exceeds 0.6:

```
if L > 0.6 → use dark text on this background
if L <= 0.6 → use light text on this background
```

## Hue drift detection

To detect hue drift in an existing HSL palette:

1. Convert each step to oklch
2. Compare the H values across steps
3. If the hue spread is greater than 10°, the palette has visible drift

```css
/* HSL blue ramp — hue shifts toward purple */
hsl(240, 80%, 20%)  →  oklch H ≈ 269
hsl(240, 80%, 50%)  →  oklch H ≈ 267
hsl(240, 80%, 90%)  →  oklch H ≈ 285  /* shifted 18° */
```


# Color Conversion

When converting existing colors to oklch, convert the color values but leave everything else unchanged — don't change gradient interpolation, don't restructure the CSS.

## Supported input formats

| Format | Examples |
| --- | --- |
| Hex (3/6/8-digit) | `#f00`, `#ff0000`, `#ff000080` |
| `rgb()` / `rgba()` | `rgb(255, 0, 0)`, `rgba(255, 0, 0, 0.5)` |
| `hsl()` / `hsla()` | `hsl(0, 100%, 50%)`, `hsla(0, 100%, 50%, 0.5)` |

## Conversion examples

```css
/* Before */
color: #3b82f6;
background: #1e293b;
border-color: #e2e8f0;

/* After */
color: oklch(0.623 0.188 259.815);
background: oklch(0.279 0.037 260.031);
border-color: oklch(0.929 0.013 255.508);
```

```css
/* Before */
color: rgb(59, 130, 246);
border: 1px solid rgba(0, 0, 0, 0.1);

/* After */
color: oklch(0.623 0.188 259.815);
border: 1px solid oklch(0 0 0 / 0.1);
```

Alpha uses the forward-slash syntax. Omit alpha when it's 1.

## What to leave alone

- CSS keywords: `currentColor`, `inherit`, `initial`, `unset`, `transparent`
- Gradient interpolation methods — only convert the color stops, not the function i