color

Files (6)

• SKILL.md
• audit_image.py · scripts/
• check_contrast.py · scripts/
• extract_colors.py · scripts/
• generate_palette.py · scripts/
• simulate_cvd.py · scripts/

SKILL.md (first lines)

# Color: Best Practices, Accessibility & Perceptual Safety

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

## Quick Reference

| Task | Approach |
|------|----------|
| **Full audit (start here)** | `python scripts/audit_image.py screenshot.png` |
| Extract colors from image | `python scripts/extract_colors.py screenshot.png` |
| Check contrast ratio | `python scripts/check_contrast.py "#0D9488" "#FFFFFF"` |
| Generate shade scale | `python scripts/generate_palette.py "#0D9488"` |
| Simulate color blindness | `python scripts/simulate_cvd.py "#EF4444" "#22C55E"` |
| Audit all pairs in bulk | `python scripts/check_contrast.py --audit palette.json` |

---

## 1. How to Audit a Design

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

```bash
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:

```bash
# 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

| Meaning | Typical Colors | Rule |
|---------|---------------|------|
| Success | Green (emerald, mint) | Same color = same meaning everywhere |
| Error | Red/pink (rose, crimson) | Never reuse error colors for decoration |
| Warning | Orange/amber | Must still pass contrast on its background |
| Info | Blue (sky, indigo) | Common for links — pair with underline |
| Neutral | Gray/slate | Add subtle warm/cool tint — avoid pure gray |

---

## 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.

```bash
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

| Shade | Lightness | Typical Role |
|-------|-----------|-------------|
| 50–100 | 97–94% | Tinted backgrounds, hover states |
| 200–300 | 87–75% | Borders, dividers, disabled states |
| 400 | 62% | Muted/placeholder text (check contrast!) |
| **500** | 48% | **Brand baseline** |
| 600 | 40% | Primary actions, buttons |
| 700–800 | 33–27% | Hover/active states on primary |
| 900–950 | 20–10% | Text on light bg, dark mode backgrounds |

### 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:

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

From Matrixx0070/xclaw, MIT.

More from Matrixx0070/xclaw