Imported from mstrokin/grok-root-skills (skills/color/SKILL.md). Install upstream with npx skills add mstrokin/grok-root-skills --skill color. Copyright stays with the author.

Color: Best Practices, Accessibility & Perceptual Safety

Practical guidance and sanity-check scripts for choosing, validating, and auditing color in any project.

Quick Reference

1. How to Audit a Design

When reviewing color in an existing design, screenshot, or codebase, run the full audit in one command:

python scripts/audit_image.py screenshot.png

This single command does everything:

1. Extracts every color including small accent text (uses hue-aware clustering + accent recovery to catch minority colors like red numbers on a navy slide)
2. Auto-classifies roles — background, text, accent, surface
3. Checks WCAG contrast for every meaningful foreground/background pair
4. Runs CVD simulation + chromostereopsis detection on failing/risky pairs

Use --json for machine-readable output.

When to use the individual scripts

The individual scripts are still useful for targeted checks:

# Check a specific pair you already know about
python scripts/check_contrast.py "#0D9488" "#FFFFFF"

# Simulate CVD for a specific pair
python scripts/simulate_cvd.py "#EF4444" "#22C55E"

# Extract colors without the full audit
python scripts/extract_colors.py screenshot.png --check

# Generate a shade scale from a brand color
python scripts/generate_palette.py "#0D9488" --check

Manual review checklist

After running the audit, also verify these — the automated scan catches contrast and CVD issues, but these require human judgment:

1. Colored accent text on a dark/colored background — the #1 failure mode overall
2. Muted/secondary text — designers often make it too subtle
3. Placeholder text in inputs — commonly fails AA
4. Disabled state text — must still be readable if it carries content (WCAG permits lower contrast only for truly inactive controls)
5. Links that rely on color alone — must have underline or other non-color indicator
6. Chart/graph colors — especially red vs. green data series (CVD failure)
7. Focus rings — must hit 3:1 against both the background and the focused element
8. Error messages — red text on dark backgrounds often fails contrast

2. Color Strategy

The 60-30-10 Rule

• 60% — Dominant (neutrals/backgrounds): Sets tone without competing
• 30% — Secondary: Supporting color for structure and variety
• 10% — Accent: High-contrast moments for CTAs, alerts, key actions

Choose 2-4 colors max beyond neutrals. Strategic color beats saturation.

Semantic Consistency

3. Generating Shade Scales

Convert a single hex into an 11-shade scale (50–950) by varying lightness while keeping hue constant. Lighter shades reduce saturation to prevent overly vibrant pastels.

python scripts/generate_palette.py "#0D9488"
python scripts/generate_palette.py "#0D9488" --check   # also runs WCAG contrast on common pairs
python scripts/generate_palette.py "#0D9488" --json     # machine-readable output

Shade Roles

OKLCH for Perceptual Uniformity

When the target environment supports it, prefer OKLCH over HSL — equal steps in lightness look equal to human eyes, making shade scales more visually consistent:

background: oklch(97% 0.01 60);   /* warm tinted neutral */
background: oklch(97% 0.01 250);  /* cool tinted neutral */

4. Accessibility — WCAG Contrast

Minimum Contrast Ratios

Target AA for all projects. Target AAA for healthcare, government, accessibility-focused apps.

Rules of Thumb

• On light backgrounds: use shade 600+ for text to pass AA, shade 700+ for AAA.
• On dark backgrounds: use shade 50–200 for text. Shade 400 often looks fine but check — it may fail AA on backgrounds darker than shade 900.
• A colored accent on a dark background must still hit 3:1 minimum or it's decorative noise. Run the script — don't eyeball it.
• Two dark shades (both below 40% lightness) almost never pass. Two light shades (both above 60%) almost never pass. You need colors on opposite sides of the lightness spectrum.

Common Contrast Failure Patterns

1. Decorative accent text that fails everything. A colored accent (red, teal, brand color) used for headings, labels, or list markers on a dark background. It looks intentional but fails WCAG across the board. Example: red numbers #CC3333 on navy #2B3A67 = 2.15:1 — fails AA, AAA, and even UI component minimums. Fix: use a high-luminance accent (white, light gold, pale blue).

2. Dark accent on dark background. Two dark colors with different hues but similar luminance. Example: teal #0D9488 on charcoal #1F2937 = ~2.1:1. If both colors have lightness below 40%, they almost certainly fail.

3. Light accent on light background. Pastel or light brand colors as text on white. Example: light teal shade 300 on white = ~1.8:1. On white, text needs shade 600+ to pass.

4. Colored text on colored background. Brand-colored text on a tinted surface (e.g., primary-600 on primary-50). Looks cohesive but often lands in the contrast dead zone. Always run the check.

Quick Contrast Reference by Lightness

Approximate ratios for lightness pairings (any hue):

Checking Contrast

python scripts/check_contrast.py "#0D9488" "#FFFFFF"
# Contrast ratio: 3.74:1
# Normal text  AA: FAIL ✗    AAA: FAIL ✗
# Large text   AA: PASS ✓    AAA: FAIL ✗
# UI elements  AA: PASS ✓

Bulk Audit

Create a JSON file listing every foreground/background pair, then check them all at once:

{
  "pairs": [
    {"foreground": "#042F2E", "background": "#FFFFFF", "label": "body text"},
    {"foreground": "#FFFFFF", "background": "#0D9488", "label": "primary button"},
    {"foreground": "#CC3333", "background": "#2B3A67", "label": "red accent on navy"}
  ]
}

python scripts/check_contrast.py --audit palette.json

Don't Rely on Color Alone

Color must never be the only indicator. Always pair with at least one redundant cue:

• Icons (✓ checkmark, ✗ error, ⚠ warning)
• Text labels ("Success", "Error")
• Patterns or shapes (striped bars, different marker shapes in charts)
• Underlines for links (don't rely solely on color to distinguish links from text)

5. Perceptual Hazards

Chromostereopsis

What: Red and blue light focus at different depths on the retina. When highly saturated red and blue are placed adjacent — especially as text on background — the eye cannot focus both simultaneously, creating a depth/vibration illusion, "swimming" text, and eye strain.

The spectrum of risk (not just the extreme case):

• 🔴 High risk: Pure red (#FF0000) on pure blue (#0000FF) — immediately painful
• 🟠 Moderate risk: Saturated red/crimson (#CC3333) on dark navy (#2B3A67) — uncomfortable for extended reading, numbers/text appear to float
• 🟢 Low risk: Desaturated warm tone on a muted blue — acceptable if contrast ratio is met

The key variables are saturation and hue distance between the red and blue wavelengths. Even moderately saturated reds on dark blues cause discomfort that won't be caught by a pure contrast ratio check.

python scripts/simulate_cvd.py "#FF0000" "#0000FF"
# ⚠ CHROMOSTEREOPSIS RISK: High-saturation red + blue causes depth/vibration illusion.

Fixes:

• Desaturate one or both colors (reduce saturation below 60%)
• Separate them with a neutral gap (white, gray, or black border)
• Shift hues closer together (red → orange/coral, blue → teal)
• Add a large luminance gap (make one color much lighter)
• Best fix: use a different accent color entirely (gold, white, or light blue on navy)

Simultaneous Contrast

Colors appear different depending on their surroundings. A medium gray on white looks darker than the same gray on black. A red next to green looks more vivid than the same red next to orange.

Practical rule: Always evaluate colors on their actual background, never in isolation. A color that looks fine in a swatch can fail in context.

Halation

Light text on dark backgrounds can appear to "glow" or bleed, especially for users with astigmatism (~50% of people). The effect is worst with pure white on pure black.

Fixes:

• Use off-white text on dark backgrounds (e.g., shade 50 or oklch(93% 0.01 250)) instead of #FFFFFF
• Use off-black backgrounds (shade 950 or 900) instead of #000000
• Increase font weight slightly on dark backgrounds (text looks thinner against dark)
• Avoid thin/light font weights on dark mode entirely

Vibrating Boundaries

Two colors with similar luminance but different hue create edges that "vibrate" visually. This is distinct from chromostereopsis — it happens with any hue pair at matched luminance, not just red/blue.

Practical test: Check that adjacent colored regions have a luminance contrast ratio ≥ 3:1:

python scripts/check_contrast.py "<region1>" "<region2>"
# If ratio is below 3:1, the boundary will shimmer

Fix: Separate with a neutral border, or adjust one region's lightness.

6. Color Blindness (CVD) Safety

~8% of males and ~0.5% of females have some form of color vision deficiency.

Dangerous Pairs

Protanopia deserves extra attention: Red loses nearly all its brightness, collapsing to a dark olive/brown. A red accent on a dark background that's merely "low contrast" for typical vision may become completely invisible for protanopes.

Safe Alternatives

Instead of red/green to show good/bad:

• ✅ Blue vs. orange — safe for all CVD types
• ✅ Luminance differences — dark vs. light of any hue
• ✅ Redundant cues — icons, patterns, labels, shapes alongside color

python scripts/simulate_cvd.py "#EF4444" "#22C55E"
# Shows simulated appearance for each CVD type
# Flags INDISTINGUISHABLE or DIFFICULT pairs

CVD-Safe Palette Principles

1. Vary luminance as much as hue — if two colors have the same brightness, CVD users may not distinguish them
2. Never use red and green as the only two semantic colors — always add a third differentiator
3. Test warm colors (red/orange/yellow) against dark backgrounds with protanopia simulation — they darken dramatically
4. Blue is the safest anchor color — it's visible to all CVD types

7. Dark Mode Best Practices

Key Principles

• Swap lightness extremes (50↔950), keep middle shades near 500
• Never use pure black (#000000) for backgrounds — it causes OLED smearing, kills elevation hierarchy, and worsens halation. Use shade 950 or 900.
• Never use pure white (#FFFFFF) for body text on dark — it causes halation. Use shade 50 or an off-white.
• Brighten primary colors one shade step (e.g., 600→500) for visibility on dark surfaces
• Elevation = lightness: Higher surfaces get lighter backgrounds (opposite of light mode's shadow-based elevation)
• Every background must have a paired foreground — if you change a surface color for dark mode, you must also update the text color on it. Unpaired changes break readability.

Surface Lightness Hierarchy

Dark mode uses lightness (not shadow) to express elevation:

Each step up should be perceptibly lighter. Aim for ≥5% lightness difference between adjacent layers.

Text on Dark Surfaces

Accent Colors on Dark Surfaces

Accents chosen for contrast against white often fail on dark backgrounds. Always re-check:

Borders on Dark Surfaces

• Aim for 10–15% lightness difference from the surface
• Shade 800 border on shade 950 bg ≈ 17% difference ✓
• Shade 900 border on shade 950 bg ≈ 10% difference ✓ (subtle)
• Same shade as background = invisible border ✗

Background-Foreground Pairing Checklist

Every surface that contains text must have an explicitly paired foreground. When switching to dark mode, both must change together:

• Page background → body text
• Card/panel background → card text
• Button background → button label
• Input background → input text + placeholder
• Tooltip/popover background → tooltip text
• Alert/banner background → alert text
• Muted/disabled surface → muted text (still must pass 4.5:1 if content is meaningful)

Common Dark Mode Mistakes

8. Anti-Patterns

NEVER:

• Use every color in the rainbow — pick 2-4 beyond neutrals
• Apply color randomly without semantic meaning
• Put gray text on colored backgrounds — it looks washed out; use a tint of the background color instead
• Use pure gray for neutrals — add a subtle warm or cool tint for sophistication
• Use pure black (#000) or pure white (#fff) for large areas
• Violate WCAG contrast requirements — always run the check script, don't eyeball
• Use color as the only indicator of state (accessibility failure)
• Use red text on blue/navy backgrounds (chromostereopsis + low contrast + CVD collapse)
• Use red/green as the only differentiator (color blindness failure)
• Assume a dark-on-dark accent "looks fine" — run the contrast check; the most common color failure is decorative accent text that fails everything below 3:1

Scripts

All scripts use Python 3 stdlib only except extract_colors.py and audit_image.py which require Pillow (pip install Pillow).