color-ops

Files (8)

• SKILL.md
• .gitkeep · assets/
• css-color-reference.md · references/
• tools-and-libraries.md · references/
• color-convert.js · scripts/
• contrast-check.js · scripts/
• harmony-gen.js · scripts/
• palette-gen.js · scripts/

SKILL.md (first lines)

# 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](https://github.com/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

```css
/* 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);
```

```javascript
// 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+)

```css
/* 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 */

From 0xDarkMatter/claude-mods, MIT.

More from 0xDarkMatter/claude-mods