Use this skill when choosing color palettes, ensuring contrast compliance, implementing dark mode, or defining semantic color tokens. Triggers on color palette, contrast ratio, WCAG color, dark mode, color tokens, HSL, OKLCH, brand colors, color harmony, and any task requiring color system design or implementation.
Use this skill when choosing color palettes, ensuring contrast compliance, implementing dark mode, or defining semantic color tokens. Triggers on color palette, contrast ratio, WCAG color, dark mode, color tokens, HSL, OKLCH, brand colors, color harmony, and any task requiring color system design or implementation.
When this skill is activated, always start your first response with the 🧢 emoji.
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
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.
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.
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.
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.
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.
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.970.03264);
--color-brand-100: oklch(0.930.06264);
--color-brand-200: oklch(0.860.10264);
--color-brand-300: oklch(0.760.15264);
--color-brand-400: oklch(0.640.19264);
--color-brand-500: oklch(0.560.22264); /* base */--color-brand-600: oklch(0.490.22264); /* primary CTA - 4.7:1 on white */--color-brand-700: oklch(0.420.21264); /* hover state */--color-brand-800: oklch(0.330.18264); /* active/pressed */--color-brand-900: oklch(0.240.14264); /* text on light bg *//* Tinted neutral - brand hue at low chroma */--color-neutral-50: oklch(0.980.005264);
--color-neutral-100: oklch(0.950.007264);
--color-neutral-200: oklch(0.900.009264);
--color-neutral-300: oklch(0.820.011264);
--color-neutral-400: oklch(0.680.013264);
--color-neutral-500: oklch(0.540.013264);
--color-neutral-600: oklch(0.430.012264);
--color-neutral-700: oklch(0.330.010264);
--color-neutral-800: oklch(0.220.008264);
--color-neutral-900: oklch(0.140.006264);
}
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.980.005264);
--color-bg-secondary: oklch(0.950.007264);
--color-bg-elevated: oklch(1.000.000264); /* pure white cards */--color-text-primary: oklch(0.160.010264);
--color-text-secondary: oklch(0.430.012264);
--color-text-muted: oklch(0.600.010264);
--color-border: oklch(0.880.009264);
--color-border-strong: oklch(0.780.011264);
--color-action-primary: var(--color-brand-600);
--color-action-primary-hover: var(--color-brand-700);
--shadow-sm: 01px2pxoklch(000 / 0.08);
--shadow-md: 04px8pxoklch(000 / 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.190.012264); /* dark blue-gray */--color-bg-secondary: oklch(0.140.010264); /* deeper layer */--color-bg-elevated: oklch(0.250.013264); /* cards sit above */--color-text-primary: oklch(0.930.008264); /* off-white, not pure */--color-text-secondary: oklch(0.700.011264);
--color-text-muted: oklch(0.520.010264);
--color-border: oklch(0.300.013264);
--color-border-strong: oklch(0.380.013264);
--color-action-primary: var(--color-brand-400); /* lighter in dark */--color-action-primary-hover: var(--color-brand-300);
--shadow-sm: 01px2pxoklch(000 / 0.40);
--shadow-md: 04px8pxoklch(000 / 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.
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.
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:
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
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.
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.
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, ...).
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.
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.
Companion check
On first activation of this skill in a conversation: check which companion skills are installed by running ls ~/.claude/skills/ ~/.agent/skills/ ~/.agents/skills/ .claude/skills/ .agent/skills/ .agents/skills/ 2>/dev/null. Compare the results against the recommended_skills field in this file's frontmatter. For any that are missing, mention them once and offer to install:
