Color Theory

A focused, opinionated guide to building production color systems. Not art school theory - the engineering decisions that determine whether a color system scales, stays accessible, and survives dark mode. Every recommendation ships with working CSS so you can copy-paste into real projects.

Color systems fail in predictable ways: too many hues, raw hex values scattered through components, contrast ratios never checked, dark mode slapped on at the end. This skill prevents all four failure modes with concrete patterns.

---

When to use this skill

Trigger this skill when the user:

• Needs to create or extend a brand color palette
• Asks about WCAG contrast ratios or accessibility for color
• Wants to implement dark mode or a light/dark theme switcher
• Needs to define a semantic color token system
• Asks about HSL, OKLCH, or CSS color functions
• Wants to choose harmonious accent or secondary colors
• Needs colors for data visualization or charts
• Asks which color to use for success, error, warning, or info states

Do NOT trigger this skill for:

• Logo design, brand identity strategy, or visual brand decisions not expressed in code
• Layout, spacing, or typography questions (use ultimate-ui for those)

---

Key principles

1. OKLCH over HSL for perceptual uniformity - hsl(243, 80%, 50%) and hsl(60, 80%, 50%) claim the same lightness but look completely different in brightness to the human eye. OKLCH's L channel is perceptually uniform - if two colors share an OKLCH lightness value, they will appear equally bright. Use OKLCH when generating accessible palettes programmatically; use HSL only as a convenience for rough manual adjustments.

2. Semantic tokens over raw values - Components must never reference #4f46e5 directly. Define a primitive scale (--color-indigo-600: #4f46e5) and semantic aliases on top (--color-action-primary: var(--color-indigo-600)). Swapping themes or adjusting brand colors then requires one edit, not a grep-and-replace across the entire codebase.

3. Contrast ratios are non-negotiable - WCAG AA requires 4.5:1 for normal text and 3:1 for large text (18px+ regular, 14px+ bold). These are the legal minimum in many jurisdictions and the ethical baseline everywhere. Check every text/background pair before shipping, including hover, focus, and disabled states - those states fail just as often as default.

4. Design for dark mode from the start - Bolting on dark mode at the end destroys contrast relationships. The correct approach: define your full semantic token set, then write dark overrides alongside light defaults. The extra 30 minutes up front saves hours of debugging washed-out text and invisible borders.

5. Less color is more - A palette of 1 brand hue + 1 tinted neutral + 4 status colors (success/warning/error/info) handles 95% of real product UI. Every additional hue increases cognitive load and the chance of contrast failures. Restraint is a feature.

---

Core concepts

Color spaces

Space	Perceptually uniform	Best for
Hex / RGB	No	Copy-paste from design tools
HSL	No	Quick manual adjustment
OKLCH	Yes	Programmatic palette generation, accessible contrast
color-mix()	Depends on space	Tinting, shading, blending in CSS

OKLCH channels: L = lightness (0-1), C = chroma (0-0.4), H = hue (0-360).

Color harmony

Relationship	Hue offset	Use case
Complementary	+180 deg	High-emphasis CTAs, maximum contrast
Analogous	+/-30 deg	Secondary/accent in product UI (recommended)
Triadic	+120 deg	Data visualization series
Split-complementary	+150 / +210 deg	High contrast without full tension

Contrast ratios

Level	Normal text	Large text	UI components
AA (minimum)	4.5:1	3:1	3:1
AAA (enhanced)	7:1	4.5:1	N/A in WCAG 2.x

Tools: browser DevTools accessibility panel, whocanuse.com, colourcontrast.cc.

Semantic vs primitive tokens

Primitive → --color-indigo-600: #4f46e5
Semantic  → --color-action-primary: var(--color-indigo-600)
Component → background: var(--color-action-primary)

Primitives define what exists. Semantics define what they mean. Components consume meaning, never raw values.

---

Common tasks

Generate a color palette from a brand color using OKLCH

Start from the brand hex, convert to OKLCH, then step lightness at equal perceptual intervals while holding chroma and hue roughly constant.

:root {
  /* Brand: oklch(0.49 0.22 264) - a mid-indigo */
  --color-brand-50:  oklch(0.97 0.03 264);
  --color-brand-100: oklch(0.93 0.06 264);
  --color-brand-200: oklch(0.86 0.10 264);
  --color-brand-300: oklch(0.76 0.15 264);
  --color-brand-400: oklch(0.64 0.19 264);
  --color-brand-500: oklch(0.56 0.22 264); /* base */
  --color-brand-600: oklch(0.49 0.22 264); /* primary CTA - 4.7:1 on white */
  --color-brand-700: oklch(0.42 0.21 264); /* hover state */
  --color-brand-800: oklch(0.33 0.18 264); /* active/pressed */
  --color-brand-900: oklch(0.24 0.14 264); /* text on light bg */

  /* Tinted neutral - brand hue at low chroma */
  --color-neutral-50:  oklch(0.98 0.005 264);
  --color-neutral-100: oklch(0.95 0.007 264);
  --color-neutral-200: oklch(0.90 0.009 264);
  --color-neutral-300: oklch(0.82 0.011 264);
  --color-neutral-400: oklch(0.68 0.013 264);
  --color-neutral-500: oklch(0.54 0.013 264);
  --color-neutral-600: oklch(0.43 0.012 264);
  --color-neutral-700: oklch(0.33 0.010 264);
  --color-neutral-800: oklch(0.22 0.008 264);
  --color-neutral-900: oklch(0.14 0.006 264);
}

Rule of thumb: primary CTA needs L between 0.45-0.52 for 4.5:1 on white. Check with DevTools before shipping.

Ensure WCAG contrast compliance

Check and fix common failing combinations using the -600 / -400 shift rule:

/* FAILS: gray-400 on white = ~2.7:1 */
.badge-label {
  color: var(--color-neutral-400); /* oklch(0.68 ...) */
}

/* PASSES: gray-600 on white = ~5.9:1 */
.badge-label {
  color: var(--color-neutral-600); /* oklch(0.43 ...) */
}

/* In dark mode: flip to lighter shades */
[data-theme="dark"] .badge-label {
  color: var(--color-neutral-300); /* high L = passes on dark bg */
}

/* Focus rings: 3:1 against adjacent colors, not just background */
:focus-visible {
  outline: 2px solid var(--color-brand-600);
  outline-offset: 2px;
}

/* On dark backgrounds, lighten the ring */
[data-theme="dark"] :focus-visible {
  outline-color: var(--color-brand-400);
}

Implement dark mode with CSS custom properties

/* 1. Light defaults on :root */
:root {
  --color-bg-primary:   oklch(0.98 0.005 264);
  --color-bg-secondary: oklch(0.95 0.007 264);
  --color-bg-elevated:  oklch(1.00 0.000 264);   /* pure white cards */

  --color-text-primary:   oklch(0.16 0.010 264);
  --color-text-secondary: oklch(0.43 0.012 264);
  --color-text-muted:     oklch(0.60 0.010 264);

  --color-border:         oklch(0.88 0.009 264);
  --color-border-strong:  oklch(0.78 0.011 264);

  --color-action-primary:       var(--color-brand-600);
  --color-action-primary-hover: var(--color-brand-700);

  --shadow-sm: 0 1px 2px oklch(0 0 0 / 0.08);
  --shadow-md: 0 4px 8px oklch(0 0 0 / 0.10);
}

/* 2. Dark overrides - defined alongside, not appended later */
[data-theme="dark"],
@media (prefers-color-scheme: dark) {
  :root:not([data-theme="light"]) {
    --color-bg-primary:   oklch(0.19 0.012 264);  /* dark blue-gray */
    --color-bg-secondary: oklch(0.14 0.010 264);  /* deeper layer */
    --color-bg-elevated:  oklch(0.25 0.013 264);  /* cards sit above */

    --color-text-primary:   oklch(0.93 0.008 264); /* off-white, not pure */
    --color-text-secondary: oklch(0.70 0.011 264);
    --color-text-muted:     oklch(0.52 0.010 264);

    --color-border:         oklch(0.30 0.013 264);
    --color-border-strong:  oklch(0.38 0.013 264);

    --color-action-primary:       var(--color-brand-400); /* lighter in dark */
    --color-action-primary-hover: var(--color-brand-300);

    --shadow-sm: 0 1px 2px oklch(0 0 0 / 0.40);
    --shadow-md: 0 4px 8px oklch(0 0 0 / 0.50);
  }
}

Never use pure #000000 in dark mode backgrounds - it is harsh and eliminates all depth cues. Never use pure #ffffff for text on dark - reduce to L ~0.93 to prevent eye strain.

Define a semantic color token system

:root {
  /* ---- Primitive scale (source of truth) ---- */
  --color-brand-400: oklch(0.64 0.19 264);
  --color-brand-600: oklch(0.49 0.22 264);
  --color-brand-700: oklch(0.42 0.21 264);

  --color-green-400: oklch(0.73 0.17 145);  --color-green-600: oklch(0.53 0.17 145);
  --color-red-400:   oklch(0.68 0.19 27);   --color-red-600:   oklch(0.50 0.19 27);
  --color-amber-400: oklch(0.80 0.15 70);   --color-amber-600: oklch(0.63 0.16 70);
  --color-blue-400:  oklch(0.67 0.16 232);  --color-blue-600:  oklch(0.50 0.18 232);

  /* ---- Semantic aliases ---- */
  --color-action-primary:       var(--color-brand-600);
  --color-action-primary-hover: var(--color-brand-700);
  --color-status-success:       var(--color-green-600);
  --color-status-warning:       var(--color-amber-600);
  --color-status-error:         var(--color-red-600);
  --color-status-info:          var(--color-blue-600);
  --color-status-success-bg:    oklch(0.96 0.04 145);
  --color-status-warning-bg:    oklch(0.97 0.04 70);
  --color-status-error-bg:      oklch(0.97 0.03 27);
  --color-status-info-bg:       oklch(0.96 0.03 232);
}

[data-theme="dark"] {
  /* Semantic overrides only - primitives unchanged */
  --color-action-primary:       var(--color-brand-400);
  --color-action-primary-hover: var(--color-brand-300);
  --color-status-success:       var(--color-green-400);
  --color-status-warning:       var(--color-amber-400);
  --color-status-error:         var(--color-red-400);
  --color-status-info:          var(--color-blue-400);
  --color-status-success-bg:    oklch(0.22 0.05 145);
  --color-status-warning-bg:    oklch(0.22 0.05 70);
  --color-status-error-bg:      oklch(0.22 0.04 27);
  --color-status-info-bg:       oklch(0.22 0.04 232);
}

Create accessible data visualization colors

Data viz colors must be distinguishable by colorblind users (8% of males have red-green deficiency). Use hues spaced 45+ degrees apart in OKLCH hue and vary chroma and lightness too.

:root {
  /* 6-series palette - colorblind safe, distinct at equal lightness */
  --chart-1: oklch(0.55 0.20 264);  /* blue-violet */
  --chart-2: oklch(0.55 0.18 145);  /* green */
  --chart-3: oklch(0.55 0.20 27);   /* red */
  --chart-4: oklch(0.55 0.16 70);   /* amber */
  --chart-5: oklch(0.55 0.18 310);  /* purple */
  --chart-6: oklch(0.55 0.16 200);  /* cyan */
}

/* Never rely on color alone - add pattern/shape redundancy */
.chart-series-1 { stroke: var(--chart-1); stroke-dasharray: none; }
.chart-series-2 { stroke: var(--chart-2); stroke-dasharray: 6 3; }
.chart-series-3 { stroke: var(--chart-3); stroke-dasharray: 2 3; }

Use a tool like Oklab Palette Generator or Huemint to verify colorblind simulations. Never use red + green as the only distinguishing pair.

Use CSS color-mix() for tints and shades

/* Tint: mix brand with white */
.alert-info-bg {
  background: color-mix(in oklch, var(--color-brand-600) 15%, white);
}

/* Shade: mix with black */
.btn-primary:active {
  background: color-mix(in oklch, var(--color-brand-600) 85%, black);
}

/* Overlay with opacity */
.overlay {
  background: color-mix(in oklch, var(--color-brand-600) 8%, transparent);
}

/* Generate hover dynamically without extra token */
.tag:hover {
  background: color-mix(in oklch, var(--color-action-primary) 12%, var(--color-bg-primary));
}

color-mix() is supported in all modern browsers (Chrome 111+, Firefox 113+, Safari 16.2+). Always specify the color space - in oklch gives perceptually smooth results.

Choose harmonious accent colors

Derive accents from your brand hue using OKLCH offsets. For an indigo brand at hue 264:

:root {
  --color-brand-600:         oklch(0.49 0.22 264);
  --color-accent-complement: oklch(0.63 0.16 84);   /* +180 - amber, max contrast */
  --color-accent-analogous:  oklch(0.52 0.21 294);  /* +30  - purple, cohesive */
}

Analogous (+30 deg) is the safest choice for product UI. Use the complementary accent (+180 deg) only for high-emphasis CTAs where you need maximum contrast against the brand.

---

Anti-patterns

Anti-pattern	Why it fails	Correct approach
Raw hex in components	Cannot theme, breaks dark mode, causes search-replace nightmares	Always use semantic tokens: var(--color-action-primary)
Pure black on white #000 / #fff	Extreme contrast causes halation; looks unnatural on screens	Use oklch(0.13 0.01 264) on oklch(0.98 0.005 264)
Gray neutrals with 0 chroma	Feels clinical and disconnected from brand	Add 3-5% brand chroma to all neutrals: oklch(L 0.008 264)
Checking contrast only in light mode	Dark mode state colors fail just as often	Test every token pair in both light and dark; check hover/focus/disabled states too
Using HSL for accessible palette generation	HSL lightness is not perceptual; hsl(60 80% 50%) looks far brighter than hsl(240 80% 50%) despite identical L	Use OKLCH for any programmatic or accessibility-critical color math
Red and green as the only data viz distinction	~8% of users cannot distinguish them	Add shape/pattern redundancy and use hues that differ by 45+ degrees

---

Gotchas

1. OKLCH browser support for older environments - OKLCH is supported in Chrome 111+, Firefox 113+, and Safari 15.4+. Environments supporting older browsers need a PostCSS plugin (postcss-oklab-function) or explicit hex fallbacks. Don't use OKLCH directly in production CSS without confirming your browser support matrix or adding a build-time transform.

2. Dark mode contrast inversion failure - A color that passes 4.5:1 in light mode often fails in dark mode because the relationship between text and background flips. A neutral-600 on white-background passes; the same neutral-600 on a dark-800 background may also fail (insufficient contrast in the other direction). Test every semantic token pair in both modes.

3. color-mix() in oklch produces unexpected hues near red - OKLCH hue wraps at 360. When mixing two colors whose hues straddle 0/360 (e.g., hue 350 and hue 10), the interpolation goes the long way around the hue wheel through greens and blues instead of the short way through near-reds. Specify hue shorter in color-mix() to force the short path: color-mix(in oklch shorter hue, ...).

4. Status color background tints failing in dark mode - Light-mode status backgrounds (e.g., oklch(0.96 0.04 145) for success) are nearly white - they look fine on white backgrounds but become invisible on dark mode backgrounds. Always define explicit dark-mode overrides for status background tokens rather than letting them inherit.

5. Semantic token naming that doesn't survive rebrand - Naming a token --color-blue-action instead of --color-action-primary means a rebrand from blue to teal requires renaming the token everywhere it's used. Semantic tokens should describe purpose (action, status-success, text-muted), never the color value itself.

---

References

• references/palette-recipes.md - Pre-built palette recipes for common product archetypes (SaaS, e-commerce, editorial, fintech)

Only load a references file if the current task requires it - they are long and will consume context.