Color Operations

Practical color knowledge for developers and designers. Covers color spaces, accessibility, palette generation, CSS implementation, and design token architecture.

Inspired by meodai/skill.color-expert - a comprehensive 286K-word color science knowledge base with 113 reference files. This is a lightweight operational skill for everyday frontend and design work. For deep color science (spectral mixing, historical color theory, CAM16, pigment physics), install the full skill.

Color Space Decision Table

Pick the right space for the task. This is the single most impactful color decision you'll make.

Task	Use	Why
Perceptual color manipulation	OKLCH	Best uniformity for lightness, chroma, hue
CSS gradients & palettes	OKLCH or color-mix(in oklab)	No mid-gradient grey/brown deadzone
Gamut-aware color picking	OKHSL / OKHSV	Cylindrical like HSL but perceptually grounded
Normalized saturation (0-100%)	HSLuv	CIELUV chroma normalized per hue/lightness
Print workflows	CIELAB D50	ICC standard illuminant
Screen workflows	OKLAB	D65 standard, perceptually uniform
Color difference (precision)	CIEDE2000	Gold standard perceptual distance metric
Color difference (fast)	Euclidean in OKLAB	Good enough for most applications
Quick prototyping	HSL	Simple, fast, every tool supports it

Why HSL Falls Short

HSL is fine for quick prototyping. It fails for anything perceptual:

• Lightness is a lie: hsl(60,100%,50%) (yellow) and hsl(240,100%,50%) (blue) have the same L=50% but vastly different perceived brightness
• Hue is non-uniform: 20 degrees near red is a dramatic shift; 20 degrees near green is barely visible
• Saturation doesn't correlate: S=100% dark blue still looks muted

Rule of thumb: Use HSL for throwaway work. Use OKLCH for anything that ships.

Key Distinctions

• Chroma = colorfulness relative to a same-lightness neutral
• Saturation = perceived colorfulness relative to the color's own brightness
• Lightness = perceived reflectance relative to a similarly lit white
• Same chroma != same saturation. These are different dimensions.

Accessibility - Contrast Numbers That Matter

The Odds Are Against You

Of ~281 trillion hex color pairs:

Threshold	% passing	Odds
WCAG 3:1 (large text)	26.49%	~1 in 4
WCAG 4.5:1 (AA body)	11.98%	~1 in 8
WCAG 7:1 (AAA)	3.64%	~1 in 27
APCA 60	7.33%	~1 in 14
APCA 75 (fluent reading)	1.57%	~1 in 64
APCA 90 (preferred body)	0.08%	~1 in 1,250

WCAG vs APCA

	WCAG 2.x	APCA (WCAG 3 draft)
Model	Simple luminance ratio	Perceptual contrast, polarity-aware
Dark-on-light vs light-on-dark	Same ratio	Different - accounts for spatial frequency
Text size/weight	Only large vs normal	Continuous scale with font lookup table
Accuracy	Known problems with blue, dark mode	Much better perceptual accuracy
Status	Current standard, legally referenced	Draft - not yet a requirement

Practical guidance: Test with WCAG 2.x for compliance. Use APCA for better perceptual results. When they disagree, APCA is usually more accurate.

Quick Contrast Checks

/* Use relative color syntax to auto-generate readable text */
--surface: oklch(0.95 0.02 250);
--on-surface: oklch(from var(--surface) calc(l - 0.6) c h);

/* Or simpler: light surface = dark text, dark surface = light text */
--text: oklch(from var(--surface) calc(1 - l) 0 h);

// Quick WCAG 2.x relative luminance contrast
function contrastRatio(l1, l2) {
  const lighter = Math.max(l1, l2);
  const darker = Math.min(l1, l2);
  return (lighter + 0.05) / (darker + 0.05);
}

function relativeLuminance(r, g, b) {
  const [rs, gs, bs] = [r, g, b].map(c => {
    c /= 255;
    return c <= 0.04045 ? c / 12.92 : ((c + 0.055) / 1.055) ** 2.4;
  });
  return 0.2126 * rs + 0.7152 * gs + 0.0722 * bs;
}

Color Vision Deficiency (CVD)

~8% of men and ~0.5% of women have some form of color vision deficiency. Design accordingly.

Type	Affects	Prevalence	What breaks
Protanopia	Red perception	~1% men	Red/green distinction, red appears dark
Deuteranopia	Green perception	~1% men	Red/green distinction (most common)
Tritanopia	Blue perception	~0.01%	Blue/yellow distinction (rare)

Rules:

• Never use color alone to convey information (add icons, labels, patterns)
• Test with CVD simulation tools (see references)
• Red/green is the most dangerous pair - always add a secondary signal

CSS Color Functions - Modern Syntax

Core Functions (Baseline 2024+)

/* OKLCH - the recommended default */
color: oklch(0.7 0.15 150);           /* lightness chroma hue */
color: oklch(0.7 0.15 150 / 0.5);     /* with alpha */

/* OKLAB - for interpolation and mixing */
color: oklab(0.7 -0.1 0.1);           /* lightness a b */

/* color-mix() - blend two colors in any space */
color: color-mix(in oklch, #3b82f6 70%, white);
color: color-mix(in oklab, var(--primary), black 20%);

/* Relative color syntax - transform existing colors */
color: oklch(from var(--brand) calc(l + 0.1) c h);          /* lighten */
color: oklch(from var(--brand) calc(l - 0.1) c h);          /* darken */
color: oklch(from var(--brand) l calc(c * 0.5) h);          /* desaturate */
color: oklch(from var(--brand) l c calc(h + 180));           /* complement */

/* P3 wide gamut */
color: color(display-p3 1 0.5 0);     /* ~25% more colors than sRGB */

/* Fallback pattern for wide gamut */
color: #ff8800;                        /* sRGB fallback */
color: oklch(0.79 0.17 70);           /* oklch version */
color: color(display-p3 1 0.55 0);    /* P3 if supported */

Gradients That Don't Muddy

/* BAD - RGB interpolation goes through grey/brown */
background: linear-gradient(to right, blue, yellow);

/* GOOD - OKLCH interpolation stays vivid */
background: linear-gradient(in oklch, blue, yellow);

/* GOOD - OKLAB also works well */
background: linear-gradient(in oklab, blue, yellow);

/* Longer hue path for rainbow-style gradients */
background: linear-gradient(in oklch longer hue, red, red);

Design Token Architecture

Three-Layer Pattern

/* Layer 1: Reference tokens (the palette) */
:root {
  --ref-blue-50: oklch(0.97 0.01 250);
  --ref-blue-100: oklch(0.93 0.03 250);
  --ref-blue-500: oklch(0.62 0.18 250);
  --ref-blue-900: oklch(0.25 0.09 250);
  --ref-red-500: oklch(0.63 0.22 25);
  --ref-neutral-50: oklch(0.97 0.005 250);
  --ref-neutral-900: oklch(0.15 0.005 250);
}

/* Layer 2: Semantic tokens (meaning) */
:root {
  --color-surface: var(--ref-neutral-50);
  --color-on-surface: var(--ref-neutral-900);
  --color-primary: var(--ref-blue-500);
  --color-error: var(--ref-red-500);
  --color-border: oklch(from var(--color-surface) calc(l - 0.15) 0.01 h);
}

/* Layer 3: Dark mode swaps semantics, not components */
[data-theme="dark"] {
  --color-surface: var(--ref-neutral-900);
  --color-on-surface: var(--ref-neutral-50);
  --color-primary: var(--ref-blue-100);
  --color-border: oklch(from var(--color-surface) calc(l + 0.15) 0.01 h);
}

Generating Scales in OKLCH

// Generate a perceptually uniform color scale
function generateScale(hue, steps = 10) {
  return Array.from({ length: steps }, (_, i) => {
    const t = i / (steps - 1);
    return {
      step: (i + 1) * 100,  // 100..1000
      l: 0.97 - t * 0.82,   // 0.97 (lightest) to 0.15 (darkest)
      c: Math.sin(t * Math.PI) * 0.18,  // peak chroma in midtones
      h: hue,
    };
  });
}

// Usage: generateScale(250) for a blue scale
// Format: oklch(${l} ${c} ${h})

Palette & Harmony

What Actually Works

Geometric hue harmony (complementary, triadic, etc.) is a weak predictor of good palettes on its own. Better approaches:

• Character-first: Organize by mood (pale/muted/deep/vivid/dark). Chroma + lightness drive emotional response more than hue.
• 60-30-10 rule: 60% dominant, 30% secondary, 10% accent. One color dominates.
• Lightness variation = legibility: Same character + varied lightness is readable. Same lightness across hues is illegible.
• Grayscale sanity check: If your UI doesn't work in grayscale, the color system has a structural problem.

Practical Palette Workflow

1. Pick a brand hue in OKLCH
2. Generate a 10-step scale (lightness 0.97 to 0.15, chroma peaks at midtones)
3. Pick a neutral (same hue, near-zero chroma) for another 10-step scale
4. Add 1-2 semantic accent hues (success green, error red, warning amber)
5. Map to semantic tokens: surface, on-surface, primary, secondary, error
6. Test contrast at every text/surface combination (WCAG 4.5:1 minimum)
7. Swap semantic mappings for dark mode (don't just invert)

Quick Harmony Shortcuts

/* Complementary (opposite hue) */
--complement: oklch(from var(--primary) l c calc(h + 180));

/* Analogous (adjacent hues) */
--analogous-1: oklch(from var(--primary) l c calc(h - 30));
--analogous-2: oklch(from var(--primary) l c calc(h + 30));

/* Triadic */
--triadic-1: oklch(from var(--primary) l c calc(h + 120));
--triadic-2: oklch(from var(--primary) l c calc(h + 240));

/* Tint (lighter, less chroma) */
--tint: oklch(from var(--primary) calc(l + 0.2) calc(c * 0.5) h);

/* Shade (darker, slightly less chroma) */
--shade: oklch(from var(--primary) calc(l - 0.2) calc(c * 0.8) h);

Gamut & Wide Color

sRGB vs P3 vs Rec2020

Gamut	Coverage	Support
sRGB	Baseline	Universal - every screen
Display P3	~25% more than sRGB	Modern Apple, high-end Android, new monitors
Rec2020	~37% more than P3	HDR content, limited device support

/* Progressive enhancement for wide gamut */
.brand-accent {
  /* sRGB fallback - every browser */
  background: #ff6b00;

  /* P3 if supported - more vivid */
  @supports (color: color(display-p3 1 0 0)) {
    background: color(display-p3 1 0.42 0);
  }
}

/* Or use @media for gamut detection */
@media (color-gamut: p3) {
  :root {
    --accent: oklch(0.75 0.2 50);  /* Can push chroma higher in P3 */
  }
}

Gamut Mapping

When a color is out of gamut (e.g., high-chroma OKLCH on an sRGB screen), browsers clamp it. Control this:

/* Browser auto-maps (default) */
color: oklch(0.7 0.3 150);  /* if out of sRGB, browser reduces chroma */

/* Explicit gamut check in JS */
// CSS.supports('color', 'color(display-p3 1 0 0)')

Scripts

Zero-dependency Node.js tools. Run directly or let Claude invoke them during color tasks.

Contrast Checker

node scripts/contrast-check.js <color1> <color2>
node scripts/contrast-check.js "#1a1a2e" "#e0e0e0"
node scripts/contrast-check.js "oklch(0.15 0.02 250)" "oklch(0.9 0.01 250)"

Returns WCAG 2.x contrast ratio with AA/AAA pass/fail for normal and large text.

Palette Generator

node scripts/palette-gen.js <hue> [name] [--neutral] [--json]
node scripts/palette-gen.js 250 blue              # 10-step blue scale
node scripts/palette-gen.js 250 blue --neutral     # + matching neutral scale
node scripts/palette-gen.js 30 orange --json       # JSON output

Generates a perceptually uniform 10-step OKLCH scale (100-1000) as CSS custom properties. Chroma peaks at midtones via sine curve. Flags out-of-gamut sRGB values.

Color Converter

node scripts/color-convert.js <color>
node scripts/color-convert.js "#3b82f6"
node scripts/color-convert.js "oklch(0.62 0.18 250)"
node scripts/color-convert.js "hsl(217, 91%, 60%)"

Converts any color to all formats: hex, rgb, hsl, oklch, oklab. Shows relative luminance and sRGB gamut status.

Harmony Generator

node scripts/harmony-gen.js <color|hue> [scheme] [--css] [--json] [--tokens] [--tints]
node scripts/harmony-gen.js "#3b82f6" triadic      # Triadic palette from hex
node scripts/harmony-gen.js 250 complementary --tokens  # Design tokens
node scripts/harmony-gen.js 30 earth               # Earth tone palette
node scripts/harmony-gen.js random                  # Curated random palette

12 harmony schemes: complementary, analogous, triadic, split, tetradic, monochromatic, warm, cool, earth, pastel, vibrant, random. All output gamut-clamped to sRGB. Use --tokens for semantic design tokens (primary, secondary, accent, surface), --tints for tint/shade/muted variants per color.

Agent Dispatch

For complex color work beyond this skill's scope, dispatch to specialized agents:

• Palette generation algorithms (RampenSau, Poline, IQ cosine): Route to frontend-design skill or a dedicated subagent with references/tools-and-libraries.md preloaded
• Accessibility audits (full APCA + CVD simulation): Route to a subagent that runs contrast checks across all component/token combinations
• Design system color architecture: Route to tailwind-ops for Tailwind-specific implementation, or handle directly for CSS custom properties

Reference Files

File	Content
references/tools-and-libraries.md	Palette generators, analysis tools, color libraries, online tools, browser extensions
references/css-color-reference.md	Complete CSS Color Level 4/5 function reference, browser support, conversion formulas

See Also

• tailwind-ops - Tailwind color configuration and dark mode patterns
• react-ops - Theme context and color mode implementation in React
• meodai/skill.color-expert - Full color science skill (113 references, spectral mixing, historical theory)
• oklch.com - Interactive OKLCH picker by Evil Martians
• Huetone - Accessible color system builder