design-protocol 1.0.0

package/skills/dp-color/references/pitfalls.md

@@ -0,0 +1,171 @@
+# Common OKLCH Pitfalls
+
+Mistakes that even experienced designers make when working with OKLCH. Consult this when
+generating palettes to avoid known traps.
+
+## 1. Chroma Clipping (The Silent Destroyer)
+
+**Problem:** You set `oklch(0.65 0.25 185)` — a vibrant teal. But sRGB max chroma at H=185°
+is ~0.13. The browser silently clamps it, shifting both the hue and lightness in
+unpredictable ways. Your carefully tuned color is now something else entirely.
+
+**Symptoms:**
+- Color looks different than expected
+- Two "different" OKLCH values render as the same hex
+- Hue appears shifted (common with greens/teals)
+- Lightness appears wrong
+
+**Fix:** Always check against the gamut ceiling for the target hue (see `oklch-gamut.md`).
+When in doubt, reduce chroma by 10–15% from what you think the limit is.
+
+**CSS mitigation:**
+```css
+/* Let the browser do smart gamut mapping */
+color: oklch(0.65 0.25 185);  /* Browser clamps — unpredictable */
+
+/* Better: explicitly target the gamut */
+color: color(display-p3 0.2 0.6 0.55);  /* P3-safe equivalent */
+```
+
+## 2. Gray Hue Shift (The Phantom Color)
+
+**Problem:** You create a "neutral gray" with `oklch(0.50 0.003 260)`. At C=0.003, you'd
+expect it to look gray. But because the chroma isn't exactly 0, it carries a visible blue
+tint — especially noticeable on calibrated displays and in large surface areas.
+
+**Symptoms:**
+- "Gray" surfaces have a color cast
+- Different "grays" at different hues don't match
+- Neutral UI elements look tinted
+
+**Fix:** For true neutrals, use `C = 0` (achromatic). For intentionally tinted neutrals
+(which are great for design systems — see the test artifact's approach), use `C = 0.01–0.02`
+and be deliberate about it. The danger zone is `C = 0.002–0.008` — too much color to be
+gray, too little to read as intentional.
+
+**Rule of thumb:**
+- `C = 0` → True gray (no hue influence)
+- `C = 0.01–0.02` → Subtly tinted neutral (deliberate warmth/coolness)
+- `C = 0.003–0.008` → Danger zone (looks like a mistake)
+- `C ≥ 0.03` → Clearly colored
+
+## 3. Lightness ≠ Luminance (The WCAG Trap)
+
+**Problem:** You ensure a OKLCH lightness difference of 0.45 between text and background,
+assuming it passes WCAG AA. But WCAG uses relative luminance (derived from linear RGB),
+not perceptual lightness. High-chroma colors can have the same OKLCH L but different
+WCAG luminance values.
+
+**Symptoms:**
+- Palette passes your ΔL check but fails a WCAG contrast checker
+- Saturated colors unexpectedly fail contrast
+- Blues appear to pass more easily than yellows at the same ΔL
+
+**Fix:** Use OKLCH ΔL as a first approximation (see `apca-contrast.md` for the heuristic),
+but always validate with a proper WCAG calculator for production. The correlation breaks
+down most at high chroma.
+
+## 4. Hue Discontinuity at 360°/0°
+
+**Problem:** You're interpolating between H=350° (pink) and H=10° (red). Naively
+interpolating gives you H=180° (teal) instead of H=0° (the short path through red).
+
+**Symptoms:**
+- Color transitions pass through unexpected hues
+- Gradient goes "the long way around" the hue wheel
+- Animated color transitions produce rainbow flashes
+
+**Fix:** When interpolating hue, always take the shortest path around the wheel:
+```javascript
+function shortestHuePath(h1, h2, t) {
+  let diff = h2 - h1;
+  if (diff > 180) diff -= 360;
+  if (diff < -180) diff += 360;
+  return ((h1 + diff * t) % 360 + 360) % 360;
+}
+```
+
+In CSS, `color-mix(in oklch, ...)` handles this automatically with `shorter hue` (the default).
+
+## 5. Non-Uniform Chroma Across a Ramp
+
+**Problem:** You use the same chroma value (say C=0.15) across all lightness steps in a
+ramp. The result: mid-tones look vivid, light tints look washed out, dark shades look
+oversaturated and may clip gamut.
+
+**Symptoms:**
+- Light steps (50, 100) look barely tinted
+- Dark steps (800, 900) look muddy or have hue shift
+- The ramp doesn't feel "smooth"
+
+**Fix:** Use a bell-curve chroma distribution that peaks at mid-lightness. See
+`scale-patterns.md` for the recommended multiplier curves. This mirrors the natural
+shape of the sRGB gamut envelope.
+
+## 6. Assuming P3 Is Always Better
+
+**Problem:** You add P3-enhanced values everywhere, pushing chroma higher for all colors.
+But for blues and magentas, the sRGB and P3 gamuts are very similar. You're adding
+complexity (extra CSS) for negligible visual difference.
+
+**Symptoms:**
+- P3 values barely differ from sRGB values for some hues
+- Extra code for no visible benefit
+- Testing burden increases
+
+**Fix:** Only include P3 overrides where the gain is meaningful (>15% chroma increase).
+The biggest wins are in greens (H≈145°, +41%), teals (H≈175°, +46%), and cyans (H≈200°, +38%).
+Blues and magentas gain less than 30% — often not worth the complexity.
+
+## 7. Dark Mode by Inversion
+
+**Problem:** You create dark mode by simply swapping your 50 with 900, 100 with 800, etc.
+This produces:
+- Text that's too bright (original backgrounds were very light)
+- Surfaces that are too dark (original text was very dark)
+- Chroma that vibrates on dark backgrounds
+
+**Symptoms:**
+- Eye strain on dark mode
+- Colors feel "electric" or harsh
+- Contrast ratios are technically fine but readability suffers
+
+**Fix:** Don't invert — remap. See the dark mode rules in SKILL.md directive 7. Key moves:
+- Surfaces: L ≈ 0.15–0.20 (not the 0.04 you'd get from inverting step 950)
+- Text: L ≈ 0.85–0.92 (not the 0.96 you'd get from inverting step 50)
+- Chroma: reduce 15–25% across the board
+- Test with real UI components, not just swatch grids
+
+## 8. Over-Rotating Hue Across Steps
+
+**Problem:** You add hue rotation to make the ramp feel more natural (warm lights, cool darks).
+But rotating more than ~20° total causes the ramp to lose its identity. A "blue" ramp starts
+looking purple in the darks and green in the lights.
+
+**Symptoms:**
+- Dark steps don't feel like they belong to the same color
+- Users describe the color inconsistently ("is this blue or purple?")
+- Adjacent ramps start overlapping in hue
+
+**Fix:** Keep total hue rotation under 15–20°. A rotation of 2–3° per step is usually enough
+to create natural shadow depth without losing identity.
+
+## 9. Ignoring Simultaneous Contrast
+
+**Problem:** You test your green "success" color on a white background and it looks perfect.
+Then a user places it next to your red "error" color and the green shifts dramatically —
+it looks more yellow.
+
+**Symptoms:**
+- Colors look "wrong" in certain UI contexts
+- Side-by-side status colors shift unexpectedly
+- The same color looks different on different pages
+
+**Fix:** This is Albers' core lesson. Always test colors in context — next to the other
+colors they'll actually appear beside. Particularly test:
+- Success next to Error (complementary clash)
+- Primary next to Neutral (chroma amplification)
+- Warning next to any high-chroma neighbor
+
+When in doubt, increase the spatial separation (more padding, dividers) or reduce chroma
+on one of the neighbors.

package/skills/dp-color/references/scale-patterns.md

@@ -0,0 +1,206 @@
+# Color Scale Patterns Reference
+
+## Standard Scale Steps
+
+Design systems typically use named stops from 25 (lightest) to 900 (darkest). The most
+common configurations:
+
+### 13-Step Scale (Comprehensive)
+
+`25, 50, 100, 200, 300, 400, 500, 600, 700, 800, 900, 950, 975`
+
+Best for: Large design systems with nuanced surface/state needs.
+
+### 11-Step Scale (Standard)
+
+`50, 100, 200, 300, 400, 500, 600, 700, 800, 900, 950`
+
+Best for: Most production design systems. Matches Tailwind's structure.
+
+### 9-Step Scale (Compact)
+
+`100, 200, 300, 400, 500, 600, 700, 800, 900`
+
+Best for: Simpler systems, single-brand palettes.
+
+## Lightness Mapping
+
+The core of a good ramp is the lightness curve. Here are proven patterns in OKLCH:
+
+### Linear Lightness (Even Steps)
+
+```
+Step  →  L (OKLCH)
+25   →  0.97
+50   →  0.95
+100  →  0.90
+200  →  0.82
+300  →  0.74
+400  →  0.66
+500  →  0.58
+600  →  0.50
+700  →  0.42
+800  →  0.34
+900  →  0.26
+950  →  0.20
+975  →  0.15
+```
+
+**Pros:** Truly perceptually uniform in OKLCH. Each step feels equal.
+**Cons:** Mid-range (400–600) can feel compressed visually in UI context.
+
+### Eased Lightness (Tailwind-style)
+
+```
+Step  →  L (OKLCH)
+25   →  0.98
+50   →  0.96
+100  →  0.93
+200  →  0.87
+300  →  0.79
+400  →  0.70
+500  →  0.60
+600  →  0.50
+700  →  0.40
+800  →  0.32
+900  →  0.25
+950  →  0.18
+975  →  0.13
+```
+
+**Pros:** More space in the light end (useful for backgrounds/surfaces) and dark end (text).
+**Cons:** Mid-tones are slightly compressed. Matches user expectations from Tailwind.
+
+### Contrast-Anchored (Leonardo-style)
+
+Instead of defining lightness directly, anchor certain stops to contrast targets:
+
+```
+Step 50   →  WCAG ≥ 1.1:1 against white  (barely tinted)
+Step 100  →  WCAG ≥ 1.3:1 against white  (light surface)
+Step 300  →  WCAG ≥ 2:1 against white     (decorative)
+Step 500  →  WCAG ≥ 4.5:1 against white   (AA text on white)
+Step 600  →  APCA |Lc| ≥ 60 on white      (APCA large text)
+Step 700  →  WCAG ≥ 7:1 against white      (AAA text on white)
+Step 900  →  WCAG ≥ 12:1 against white     (high contrast text)
+```
+
+**Pros:** Guarantees accessibility at named stops. Easy to document: "use 500+ on white."
+**Cons:** Lightness spacing is uneven — driven by contrast math, not perception.
+
+## Chroma Curves
+
+Chroma should not stay constant across a ramp. Two patterns:
+
+### Bell Curve (Recommended)
+
+Chroma peaks at mid-lightness (~500) and tapers at both extremes.
+
+```
+Step  →  C multiplier (of max hue chroma)
+25   →  0.15
+50   →  0.20
+100  →  0.30
+200  →  0.50
+300  →  0.70
+400  →  0.85
+500  →  1.00  (peak)
+600  →  0.90
+700  →  0.75
+800  →  0.55
+900  →  0.35
+950  →  0.25
+975  →  0.18
+```
+
+This mirrors the sRGB gamut envelope naturally. See `oklch-gamut.md` for why.
+
+### Front-Loaded (Vibrant Lights)
+
+Chroma peaks earlier (~300–400). Creates vivid light tints, muted darks.
+
+```
+Step  →  C multiplier
+25   →  0.25
+50   →  0.40
+100  →  0.60
+200  →  0.80
+300  →  0.95
+400  →  1.00  (peak)
+500  →  0.85
+600  →  0.65
+700  →  0.50
+800  →  0.35
+900  →  0.25
+```
+
+Useful for palettes where light surfaces need to carry brand color strongly.
+
+## Hue Rotation
+
+In OKLCH, hue can shift slightly across a ramp to create more natural-feeling scales:
+
+- **Warm shift:** Rotate hue +5–15° toward yellow/orange at lighter steps
+- **Cool shift:** Rotate hue -5–10° toward blue at darker steps
+- **Natural shadow:** Dark shades often look more natural slightly cooler (mimics real-world shadow)
+
+Example for a blue palette (H = 265):
+```
+Step 50   →  H = 260  (slightly greener / lighter feel)
+Step 500  →  H = 265  (anchor)
+Step 900  →  H = 272  (slightly violet / deeper)
+```
+
+Keep total rotation under 20° to maintain color identity.
+
+## Multi-Color System Layout
+
+For a full design system with 12+ semantic colors:
+
+| Color Role | Example Hues (H) | Notes |
+|------------|-------------------|-------|
+| Primary | Brand-dependent | Anchor color |
+| Secondary | Primary ± 30–60° | Analogous harmony |
+| Accent | Primary ± 150–180° | Complementary pop |
+| Success | 145–155 | Green family |
+| Warning | 80–95 | Yellow/amber family |
+| Error/Danger | 25–35 | Red/orange family |
+| Info | 230–260 | Blue family |
+| Neutral | 0 chroma (or C ≤ 0.02) | True gray or tinted neutral |
+| Neutral (tinted) | Primary hue, C = 0.01–0.03 | Warm/cool neutral |
+
+Each of these gets the full step ramp (25–900).
+
+## CSS Custom Properties Pattern
+
+```css
+:root {
+  /* Primary blue — 11 steps */
+  --primary-50:  oklch(0.96 0.03 265);
+  --primary-100: oklch(0.93 0.05 265);
+  --primary-200: oklch(0.87 0.09 264);
+  --primary-300: oklch(0.79 0.12 264);
+  --primary-400: oklch(0.70 0.15 265);
+  --primary-500: oklch(0.60 0.17 265);
+  --primary-600: oklch(0.50 0.15 266);
+  --primary-700: oklch(0.40 0.13 267);
+  --primary-800: oklch(0.32 0.09 268);
+  --primary-900: oklch(0.25 0.06 270);
+  --primary-950: oklch(0.18 0.04 272);
+}
+```
+
+## JSON Token Format
+
+```json
+{
+  "color": {
+    "primary": {
+      "50":  { "value": "oklch(0.96 0.03 265)", "hex": "#e8eeff" },
+      "100": { "value": "oklch(0.93 0.05 265)", "hex": "#d1deff" },
+      "500": { "value": "oklch(0.60 0.17 265)", "hex": "#4466dd" },
+      "900": { "value": "oklch(0.25 0.06 270)", "hex": "#1a2244" }
+    }
+  }
+}
+```

package/skills/dp-color/references/tool-workflows.md

@@ -0,0 +1,200 @@
+# Design Tool Workflows
+
+Step-by-step workflows for integrating OKLCH palette work with the four major color
+palette tools. Use this reference when the user mentions any of these tools or asks
+how to validate/export palettes through external tooling.
+
+## Atmos (atmos.style)
+
+**What it does:** Generates entire color systems from a few seed colors. Produces
+scales with configurable steps, lightness curves, and chroma behavior. Underrated
+tool — one of the few that thinks in terms of full systems rather than individual colors.
+
+### Workflow: Base Color → Full System
+
+1. **Open Atmos** and start a new palette
+2. **Add your seed color** as a HEX value (e.g., #1c2739)
+3. **Configure scale steps:**
+   - Set to 11 steps (50–950) or 13 steps (25–975) depending on system needs
+   - Atmos uses its own lightness distribution — compare against the eased curve
+     in `scale-patterns.md` and adjust if needed
+4. **Add semantic colors:** Use Atmos's "add color" to create Success, Warning, Error, etc.
+   - Tip: Set the hues manually based on your harmony strategy (see SKILL.md directive 8)
+     rather than accepting Atmos defaults
+5. **Review chroma behavior:** Atmos may push chroma higher than sRGB allows for some hues.
+   Cross-check against `oklch-gamut.md` chroma ceilings
+6. **Export:** Atmos exports CSS custom properties and JSON. The format may need light
+   transformation to match W3C design token spec — use `scripts/export_tokens.py` for that.
+
+### Strengths
+- Thinks in full systems (multiple color roles at once)
+- Good lightness distribution out of the box
+- Quick iteration on seed colors
+
+### Limitations
+- Doesn't explicitly show OKLCH values (uses its own internal model)
+- No APCA contrast validation built in
+- May produce out-of-gamut values without warning
+
+---
+
+## Huetone (huetone.ardov.me)
+
+**What it does:** Purpose-built for OKLCH palette creation. Visualizes the OKLCH color
+space directly, shows gamut boundaries, and validates contrast between steps. The most
+OKLCH-native tool available.
+
+### Workflow: OKLCH Palette Validation
+
+1. **Open Huetone** and create a new palette
+2. **Set your hue angle** (e.g., H=260 for the navy primary)
+3. **Define lightness stops:**
+   - Enter L values for each step manually to match your target curve
+   - Huetone shows a lightness graph — verify it follows the eased pattern
+     from `scale-patterns.md`
+4. **Set chroma per step:**
+   - Huetone displays the sRGB gamut boundary as a shaded region
+   - If your chroma dot falls outside the shaded area, it's out of gamut
+   - Adjust chroma to stay inside the boundary
+5. **Check contrast pairs:**
+   - Huetone shows WCAG contrast ratios between any two steps
+   - Verify that step 500+ on white meets your AA/AAA target
+   - Verify dark mode pairings (step 100–200 text on step 900 surface)
+6. **Export:** Huetone exports OKLCH values directly. Copy into your palette JSON
+   and run through `scripts/export_tokens.py`
+
+### Strengths
+- Native OKLCH visualization
+- Real-time gamut boundary display
+- Built-in contrast checking between steps
+- Shareable palette URLs
+
+### Limitations
+- One hue at a time (not a full system view)
+- No dark mode preview
+- Limited export formats
+- Manual process for multi-color systems
+
+---
+
+## Leonardo (leonardocolor.io) by Adobe
+
+**What it does:** Contrast-ratio-driven palette generation. You define target contrast
+ratios and Leonardo computes the colors that achieve them. The "accessibility-first"
+approach to palette building.
+
+### Workflow: Contrast-Anchored Palette
+
+1. **Open Leonardo** and create a new color scale
+2. **Set your key color** (the mid-tone anchor — typically your brand color)
+3. **Define contrast ratios** for each step against your background:
+   ```
+   Step 50  → 1.1:1  (barely tinted surface)
+   Step 100 → 1.3:1  (light surface)
+   Step 200 → 1.8:1  (decorative)
+   Step 300 → 2.5:1  (large non-text)
+   Step 400 → 3.0:1  (AA large text)
+   Step 500 → 4.5:1  (AA normal text)
+   Step 600 → 5.5:1  (comfortable reading)
+   Step 700 → 7.0:1  (AAA normal text)
+   Step 800 → 9.0:1  (high contrast)
+   Step 900 → 12.0:1 (maximum)
+   Step 950 → 15.0:1 (near-black)
+   ```
+4. **Choose the color space:** Select OKLCH (or LCH) as the interpolation space.
+   Leonardo supports multiple spaces — always use OKLCH for perceptual uniformity.
+5. **Adjust the lightness curve:** Leonardo auto-computes L values from contrast ratios.
+   The resulting curve will be non-linear (contrast-anchored pattern from `scale-patterns.md`).
+   Review whether the steps feel even visually.
+6. **Generate for multiple backgrounds:**
+   - White (#fff) for light mode
+   - Your dark surface (e.g., primary-900) for dark mode
+   - Leonardo recalculates all colors to hit the same contrast targets on each background
+7. **Export:** Leonardo exports CSS, JSON, and SVG palettes. The CSS export uses
+   the `color()` function — may need conversion to `oklch()` syntax.
+
+### Strengths
+- Accessibility is the foundation, not an afterthought
+- Multi-background support (light + dark mode from the same definition)
+- Generates tokens tied to contrast targets, not arbitrary lightness
+- Adobe-maintained, actively developed
+
+### Limitations
+- Doesn't use OKLCH natively in its UI (uses CAM02/LCH internally)
+- The contrast-driven approach produces uneven perceptual spacing
+- Less intuitive for designers who think in hue/saturation terms
+- Can produce surprising hue shifts at extreme contrast targets
+
+---
+
+## Colorbox (colorbox.io) by Lyft
+
+**What it does:** Custom easing curves for palette generation. Lets you define
+bezier curves for lightness, saturation, and hue independently — maximum control
+over the shape of your ramp.
+
+### Workflow: Custom Curve Palette
+
+1. **Open Colorbox** and set the number of steps (11 recommended)
+2. **Set your anchor color:**
+   - Use the color picker or paste your HEX
+   - Position it at the step where you want it to anchor (usually 500 or 600)
+3. **Configure the Lightness curve:**
+   - Colorbox provides bezier curve handles
+   - For the eased pattern: pull the light end slightly flatter (more space for surfaces)
+     and the dark end slightly flatter (more space for text shades)
+   - For linear: make the curve as straight as possible
+4. **Configure the Saturation curve:**
+   - Shape this as a bell curve peaking at mid-steps
+   - Pull the ends (light and dark) down to reduce chroma at extremes
+   - This naturally mirrors the sRGB gamut envelope
+5. **Configure the Hue curve:**
+   - For no rotation: flat line
+   - For natural shadow: slight upward curve (rotate toward cooler at dark end)
+   - Keep total rotation under 15–20°
+6. **Preview:** Colorbox renders the full ramp live. Check for:
+   - Smooth visual transitions (no sudden jumps)
+   - No gamut clipping (compare with `oklch-gamut.md`)
+   - The anchor color sitting at the right step
+7. **Export:** Colorbox exports HEX values. Convert to OKLCH using:
+   ```bash
+   # If you have the palette in JSON with hex values, the export script can help
+   # Or convert manually with a tool like oklch.com
+   ```
+
+### Strengths
+- Maximum control over curve shape
+- Visual bezier editor is intuitive for designers
+- Good for understanding how curves affect perception
+- Fast iteration
+
+### Limitations
+- Works in HSL internally (not OKLCH) — perceptual uniformity not guaranteed
+- No contrast validation built in
+- Exports HEX only — requires post-conversion to OKLCH
+- Gamut issues not surfaced (HSL doesn't have gamut boundaries)
+
+---
+
+## Tool Comparison Matrix
+
+| Feature | Atmos | Huetone | Leonardo | Colorbox |
+|---------|-------|---------|----------|----------|
+| Native OKLCH | ✗ | ✓ | Partial | ✗ |
+| Full system view | ✓ | ✗ | ✗ | ✗ |
+| Gamut visualization | ✗ | ✓ | ✗ | ✗ |
+| Contrast validation | ✗ | ✓ | ✓ (core) | ✗ |
+| Dark mode support | ✗ | ✗ | ✓ | ✗ |
+| Custom curves | ✗ | ✗ | ✗ | ✓ |
+| Token export | CSS/JSON | Manual | CSS/JSON | HEX only |
+| Best for | System overview | OKLCH precision | A11y-first builds | Curve experimentation |
+
+## Recommended Workflow
+
+For production design systems, combine tools:
+
+1. **Start in Colorbox** — experiment with curves to find the right "feel"
+2. **Validate in Huetone** — check gamut boundaries and inter-step contrast in OKLCH
+3. **Anchor in Leonardo** — verify contrast targets are met on both light and dark surfaces
+4. **Review in Atmos** — see the full multi-color system together
+5. **Export with `scripts/export_tokens.py`** — generate production CSS, JSON, and Figma tokens