design-protocol 1.0.0

package/skills/dp-color/export_tokens.py

@@ -0,0 +1,297 @@
+#!/usr/bin/env python3
+"""
+Export color palette tokens in multiple formats.
+
+Usage:
+    python3 export_tokens.py --input palette.json --format css,json,figma --output ./tokens/
+    python3 export_tokens.py --input palette.json --format css --p3    # Include P3 enhanced values
+    python3 export_tokens.py --input palette.json --format all --dark  # Include dark mode remap
+
+Input JSON format:
+{
+  "colors": {
+    "primary": {
+      "hue": 260,
+      "max_chroma": 0.145,
+      "p3_max_chroma": 0.19,
+      "steps": {
+        "50":  { "L": 0.96, "C": 0.029, "H": 256 },
+        "100": { "L": 0.93, "C": 0.044, "H": 257 },
+        ...
+      }
+    }
+  },
+  "meta": {
+    "name": "Enterprise Color System",
+    "base": "#1c2739",
+    "wcag_target": "AA"
+  }
+}
+
+If "steps" are omitted, the script auto-generates an 11-step ramp from hue + max_chroma
+using the eased lightness curve.
+"""
+
+import json
+import math
+import argparse
+import os
+import sys
+
+# ─── OKLCH → sRGB Conversion ───
+
+def oklch_to_oklab(L, C, H):
+    h_rad = math.radians(H)
+    return L, C * math.cos(h_rad), C * math.sin(h_rad)
+
+def oklab_to_linear_rgb(L, a, b):
+    l_ = L + 0.3963377774 * a + 0.2158037573 * b
+    m_ = L - 0.1055613458 * a - 0.0638541728 * b
+    s_ = L - 0.0894841775 * a - 1.2914855480 * b
+
+    l = l_ ** 3
+    m = m_ ** 3
+    s = s_ ** 3
+
+    r = +4.0767416621 * l - 3.3077115913 * m + 0.2309699292 * s
+    g = -1.2684380046 * l + 2.6097574011 * m - 0.3413193965 * s
+    bl = -0.0041960863 * l - 0.7034186147 * m + 1.7076147010 * s
+    return r, g, bl
+
+def linear_to_srgb(c):
+    if c <= 0.0031308:
+        return 12.92 * c
+    return 1.055 * (c ** (1 / 2.4)) - 0.055
+
+def clamp(v, lo=0.0, hi=1.0):
+    return max(lo, min(hi, v))
+
+def oklch_to_hex(L, C, H):
+    ol, oa, ob = oklch_to_oklab(L, C, H)
+    r, g, b = oklab_to_linear_rgb(ol, oa, ob)
+    r = clamp(linear_to_srgb(r))
+    g = clamp(linear_to_srgb(g))
+    b = clamp(linear_to_srgb(b))
+    return f"#{int(round(r*255)):02x}{int(round(g*255)):02x}{int(round(b*255)):02x}"
+
+def is_in_srgb_gamut(L, C, H):
+    """Check if OKLCH value is within sRGB gamut (no clamping needed)."""
+    ol, oa, ob = oklch_to_oklab(L, C, H)
+    r, g, b = oklab_to_linear_rgb(ol, oa, ob)
+    return all(-0.001 <= v <= 1.001 for v in [r, g, b])
+
+# ─── Auto-generate ramp ───
+
+STEPS = [50, 100, 200, 300, 400, 500, 600, 700, 800, 900, 950]
+LIGHTNESS_EASED = [0.96, 0.93, 0.87, 0.79, 0.70, 0.60, 0.50, 0.40, 0.32, 0.25, 0.18]
+CHROMA_BELL = [0.10, 0.18, 0.40, 0.65, 0.85, 1.00, 0.90, 0.75, 0.55, 0.35, 0.25]
+HUE_OFFSETS = [-4, -3, -2, -1, 0, 0, 1, 2, 3, 4, 5]
+
+def generate_ramp(hue, max_chroma, hue_shift=1.0):
+    ramp = {}
+    for i, step in enumerate(STEPS):
+        L = LIGHTNESS_EASED[i]
+        C = round(max_chroma * CHROMA_BELL[i], 4)
+        H = round((hue + HUE_OFFSETS[i] * hue_shift) % 360, 1)
+        # Gamut safety: reduce chroma until in-gamut
+        while C > 0.001 and not is_in_srgb_gamut(L, C, H):
+            C = round(C - 0.001, 4)
+        ramp[str(step)] = {"L": L, "C": C, "H": H}
+    return ramp
+
+def generate_dark_ramp(light_ramp):
+    """Remap a light-mode ramp for dark mode surfaces."""
+    dark = {}
+    for step_name, vals in light_ramp.items():
+        L = vals["L"]
+        C = vals["C"]
+        H = vals["H"]
+        # Invert lightness mapping and reduce chroma ~20%
+        dark_L = round(1.0 - L, 3)
+        # Clamp to useful range
+        dark_L = round(clamp(dark_L, 0.10, 0.95), 3)
+        dark_C = round(C * 0.80, 4)
+        dark[step_name] = {"L": dark_L, "C": dark_C, "H": H}
+    return dark
+
+# ─── Output formatters ───
+
+def format_css(colors, meta, include_p3=False, include_dark=False):
+    lines = [f"/* {meta.get('name', 'Color System')} — CSS Custom Properties */",
+             f"/* Base: {meta.get('base', 'N/A')} | WCAG: {meta.get('wcag_target', 'AA')} */", ""]
+    lines.append(":root {")
+    for color_name, color_data in colors.items():
+        steps = color_data.get("steps", {})
+        lines.append(f"  /* {color_name} */")
+        for step, vals in sorted(steps.items(), key=lambda x: int(x[0])):
+            oklch = f"oklch({vals['L']:.2f} {vals['C']:.3f} {vals['H']:.0f})"
+            hx = oklch_to_hex(vals['L'], vals['C'], vals['H'])
+            lines.append(f"  --{color_name}-{step}: {oklch}; /* {hx} */")
+        lines.append("")
+    lines.append("}")
+
+    if include_p3:
+        lines.extend(["", "@media (color-gamut: p3) {", "  :root {"])
+        for color_name, color_data in colors.items():
+            p3_max = color_data.get("p3_max_chroma")
+            if not p3_max:
+                continue
+            base_max = color_data.get("max_chroma", 0.15)
+            steps = color_data.get("steps", {})
+            lines.append(f"    /* {color_name} — P3 enhanced */")
+            for step, vals in sorted(steps.items(), key=lambda x: int(x[0])):
+                # Scale chroma proportionally to P3 ceiling
+                p3_C = round(vals['C'] * (p3_max / base_max), 4)
+                if p3_C > vals['C'] + 0.005:  # Only include if meaningfully different
+                    oklch = f"oklch({vals['L']:.2f} {p3_C:.3f} {vals['H']:.0f})"
+                    lines.append(f"    --{color_name}-{step}: {oklch};")
+            lines.append("")
+        lines.extend(["  }", "}"])
+
+    if include_dark:
+        lines.extend(["", "/* Dark mode */",
+                       "@media (prefers-color-scheme: dark) {", "  :root {"])
+        for color_name, color_data in colors.items():
+            steps = color_data.get("steps", {})
+            dark_steps = generate_dark_ramp(steps)
+            lines.append(f"    /* {color_name} — dark */")
+            for step, vals in sorted(dark_steps.items(), key=lambda x: int(x[0])):
+                oklch = f"oklch({vals['L']:.2f} {vals['C']:.3f} {vals['H']:.0f})"
+                hx = oklch_to_hex(vals['L'], vals['C'], vals['H'])
+                lines.append(f"    --{color_name}-{step}: {oklch}; /* {hx} */")
+            lines.append("")
+        lines.extend(["  }", "}"])
+
+    return "\n".join(lines)
+
+def format_json_tokens(colors, meta, include_dark=False):
+    """W3C Design Tokens Community Group format."""
+    tokens = {
+        "$name": meta.get("name", "Color System"),
+        "$description": f"Base: {meta.get('base', 'N/A')} | WCAG: {meta.get('wcag_target', 'AA')}",
+        "color": {}
+    }
+    for color_name, color_data in colors.items():
+        steps = color_data.get("steps", {})
+        token_group = {}
+        for step, vals in sorted(steps.items(), key=lambda x: int(x[0])):
+            oklch_str = f"oklch({vals['L']:.2f} {vals['C']:.3f} {vals['H']:.0f})"
+            hx = oklch_to_hex(vals['L'], vals['C'], vals['H'])
+            token_group[step] = {
+                "$type": "color",
+                "$value": oklch_str,
+                "hex": hx,
+                "oklch": {"L": vals["L"], "C": vals["C"], "H": vals["H"]}
+            }
+        tokens["color"][color_name] = token_group
+
+    if include_dark:
+        tokens["color-dark"] = {}
+        for color_name, color_data in colors.items():
+            steps = color_data.get("steps", {})
+            dark_steps = generate_dark_ramp(steps)
+            token_group = {}
+            for step, vals in sorted(dark_steps.items(), key=lambda x: int(x[0])):
+                oklch_str = f"oklch({vals['L']:.2f} {vals['C']:.3f} {vals['H']:.0f})"
+                hx = oklch_to_hex(vals['L'], vals['C'], vals['H'])
+                token_group[step] = {
+                    "$type": "color",
+                    "$value": oklch_str,
+                    "hex": hx,
+                    "oklch": {"L": vals["L"], "C": vals["C"], "H": vals["H"]}
+                }
+            tokens["color-dark"][color_name] = token_group
+
+    return json.dumps(tokens, indent=2)
+
+def format_figma_tokens(colors, meta):
+    """Figma Tokens plugin format (Tokens Studio compatible)."""
+    figma = {}
+    for color_name, color_data in colors.items():
+        steps = color_data.get("steps", {})
+        group = {}
+        for step, vals in sorted(steps.items(), key=lambda x: int(x[0])):
+            hx = oklch_to_hex(vals['L'], vals['C'], vals['H'])
+            group[step] = {
+                "value": hx,
+                "type": "color",
+                "description": f"oklch({vals['L']:.2f} {vals['C']:.3f} {vals['H']:.0f})"
+            }
+        figma[color_name] = group
+    return json.dumps(figma, indent=2)
+
+# ─── Main ───
+
+def main():
+    parser = argparse.ArgumentParser(description="Export color palette tokens")
+    parser.add_argument("--input", required=True, help="Input palette JSON file")
+    parser.add_argument("--format", default="all",
+                        help="Output formats: css, json, figma, or all (comma-separated)")
+    parser.add_argument("--output", default="./tokens", help="Output directory")
+    parser.add_argument("--p3", action="store_true", help="Include P3 gamut enhanced values in CSS")
+    parser.add_argument("--dark", action="store_true", help="Include dark mode remapped values")
+    args = parser.parse_args()
+
+    with open(args.input, "r") as f:
+        palette = json.load(f)
+
+    colors = palette.get("colors", {})
+    meta = palette.get("meta", {})
+
+    # Auto-generate ramps for colors that only have hue + max_chroma
+    for name, data in colors.items():
+        if "steps" not in data:
+            data["steps"] = generate_ramp(
+                data.get("hue", 0),
+                data.get("max_chroma", 0.15),
+                data.get("hue_shift", 1.0)
+            )
+
+    os.makedirs(args.output, exist_ok=True)
+    formats = [f.strip() for f in args.format.split(",")]
+    if "all" in formats:
+        formats = ["css", "json", "figma"]
+
+    generated = []
+
+    if "css" in formats:
+        css = format_css(colors, meta, include_p3=args.p3, include_dark=args.dark)
+        path = os.path.join(args.output, "tokens.css")
+        with open(path, "w") as f:
+            f.write(css)
+        generated.append(path)
+
+    if "json" in formats:
+        tokens = format_json_tokens(colors, meta, include_dark=args.dark)
+        path = os.path.join(args.output, "tokens.json")
+        with open(path, "w") as f:
+            f.write(tokens)
+        generated.append(path)
+
+    if "figma" in formats:
+        figma = format_figma_tokens(colors, meta)
+        path = os.path.join(args.output, "figma-tokens.json")
+        with open(path, "w") as f:
+            f.write(figma)
+        generated.append(path)
+
+    # Gamut check
+    warnings = []
+    for name, data in colors.items():
+        for step, vals in data.get("steps", {}).items():
+            if not is_in_srgb_gamut(vals["L"], vals["C"], vals["H"]):
+                warnings.append(f"  ⚠ {name}-{step}: oklch({vals['L']} {vals['C']} {vals['H']}) is OUT of sRGB gamut")
+
+    print(f"✅ Generated {len(generated)} token file(s):")
+    for p in generated:
+        print(f"   {p}")
+
+    if warnings:
+        print(f"\n⚠ Gamut warnings ({len(warnings)}):")
+        for w in warnings:
+            print(w)
+    else:
+        print("\n✅ All colors are within sRGB gamut.")
+
+if __name__ == "__main__":
+    main()

package/skills/dp-color/references/apca-contrast.md

@@ -0,0 +1,87 @@
+# APCA & WCAG Contrast Reference
+
+## APCA (Accessible Perceptual Contrast Algorithm)
+
+APCA uses **Lc (Lightness Contrast)** values. Unlike WCAG 2.x ratios, APCA is polarity-aware:
+dark text on light background produces positive Lc; light text on dark background produces
+negative Lc. Use the absolute value for threshold comparisons.
+
+### APCA Minimum Lc Thresholds by Use Case
+
+| Use Case | Min |Lc| | Font Size Context |
+|----------|---------|-------------------|
+| Body text (primary content) | 75 | 16px+ regular, 14px+ bold |
+| Large text / headings | 60 | 24px+ regular, 18.66px+ bold |
+| Sub-text, captions, labels | 60 | 14px+ |
+| Placeholder text | 60 | Minimum for legibility |
+| Non-text UI elements (icons, borders) | 45 | Meaningful boundaries |
+| Decorative / disabled states | 30 | Minimum perceptible |
+| Large non-text (logos, hero graphics) | 45 | Large-scale elements |
+
+### APCA Bronze/Silver/Gold Conformance
+
+| Level | Body Text |Lc| | Large Text |Lc| | Non-text |Lc| |
+|-------|-----------|------------|------------|
+| Bronze (minimum) | 60 | 45 | 30 |
+| Silver (recommended) | 75 | 60 | 45 |
+| Gold (enhanced) | 90 | 75 | 60 |
+
+### Computing APCA Lc from OKLCH
+
+APCA operates on luminance, not OKLCH lightness directly. However, OKLCH L correlates well
+with perceptual lightness. As a rough heuristic:
+
+```
+ΔL (OKLCH) of 0.40+ between text and background → usually |Lc| ≥ 60
+ΔL (OKLCH) of 0.55+ between text and background → usually |Lc| ≥ 75
+ΔL (OKLCH) of 0.65+ between text and background → usually |Lc| ≥ 90
+```
+
+**These are approximations.** Always validate with a proper APCA calculator for production.
+The correlation is best when chroma is low; high-chroma colors can deviate.
+
+## WCAG 2.2 Contrast Ratios
+
+WCAG 2.x uses a simpler luminance ratio (1:1 to 21:1).
+
+### Minimum Ratios
+
+| Level | Normal Text (< 24px / < 18.66px bold) | Large Text (≥ 24px / ≥ 18.66px bold) | Non-text UI |
+|-------|---------------------------------------|--------------------------------------|-------------|
+| AA | 4.5:1 | 3:1 | 3:1 |
+| AAA | 7:1 | 4.5:1 | — |
+
+### WCAG Ratio from OKLCH Lightness (Heuristic)
+
+| ΔL (OKLCH) | Approx. WCAG Ratio | Meets |
+|------------|---------------------|-------|
+| 0.30 | ~3:1 | AA Large, UI |
+| 0.40 | ~4.5:1 | AA Normal |
+| 0.55 | ~7:1 | AAA Normal |
+| 0.70+ | ~12:1+ | Well exceeds AAA |
+
+Again, these are directional. WCAG ratio depends on relative luminance, not perceptual
+lightness, so hue and chroma affect the actual ratio.
+
+## Practical Guidelines for Palette Design
+
+1. **Text colors on light backgrounds (L ≥ 0.92):** Use L ≤ 0.45 for body text (AA),
+   L ≤ 0.35 for AAA.
+2. **Text colors on dark backgrounds (L ≤ 0.20):** Use L ≥ 0.65 for body text (AA),
+   L ≥ 0.75 for AAA.
+3. **Colored text on colored backgrounds:** Reduce chroma on both to improve luminance
+   separation. High-chroma pairs can pass OKLCH ΔL checks but fail WCAG because chroma
+   affects relative luminance differently per hue.
+4. **Interactive states:** Ensure hover/focus states maintain at least the same contrast as
+   the default state. Don't rely solely on color change — combine with underline, outline,
+   or weight changes.
+5. **Dark mode:** Don't just invert. Remap: light backgrounds become L ≈ 0.15–0.20,
+   text becomes L ≈ 0.85–0.92. Reduce chroma slightly to avoid vibrating colors on dark
+   backgrounds.
+
+## Tools for Validation
+
+- **APCA Calculator:** [apcacontrast.com](https://apcacontrast.com)
+- **WCAG Contrast Checker:** browser DevTools (Chrome, Firefox both have built-in)
+- **Huetone:** Validates OKLCH palettes against contrast targets
+- **Leonardo (Adobe):** Contrast-ratio-driven palette generation

package/skills/dp-color/references/hue-emotions.md

@@ -0,0 +1,109 @@
+# Hue Emotion Map
+
+Consolidated from Adams' *Designer's Dictionary of Color* and Goethe's *Theory of Colours*,
+with practical UI/UX context from Sherin.
+
+## How to Use This Reference
+
+When selecting hues for a design system, don't pick colors in isolation. Cross-reference the
+emotional/cultural associations below with:
+
+1. The **brand personality** the system needs to convey
+2. The **audience's cultural context** (Western associations dominate below — adjust for other markets)
+3. The **functional role** (is this color semantic, like "error", or expressive, like "brand"?)
+
+## Hue Associations by Range
+
+### Reds (H: 15–40°)
+
+| Aspect | Association |
+|--------|------------|
+| **Goethe** | The "plus side" — stimulating, energetic, demands attention. The most forceful color. |
+| **Adams** | Passion, urgency, danger, love, power. In finance: loss/decline. In East Asia: luck, prosperity. |
+| **UI context** | Error states, destructive actions, urgent alerts. Use sparingly — it always dominates. |
+| **Chroma note** | High sRGB chroma available (~0.22 at L=0.65). Can push vibrant reds safely. |
+
+### Oranges (H: 40–70°)
+
+| Aspect | Association |
+|--------|------------|
+| **Goethe** | Warmth, comfort, approachability. Less aggressive than red. |
+| **Adams** | Energy, enthusiasm, creativity, warmth. Associated with affordability and friendliness. |
+| **UI context** | Warning states (amber/orange), CTAs that feel energetic but not alarming. |
+| **Chroma note** | Moderate ceiling (~0.18). Vibrant oranges need careful gamut management. |
+
+### Yellows (H: 70–100°)
+
+| Aspect | Association |
+|--------|------------|
+| **Goethe** | Closest to light itself. Joy, cheerfulness, but also anxiety and caution when desaturated. |
+| **Adams** | Optimism, caution (traffic signals), intellect. Can feel cheap if oversaturated. |
+| **UI context** | Warning/caution (amber-yellow), highlights, badges. Avoid as backgrounds — low contrast with white. |
+| **Chroma note** | Drops fast at high lightness. Yellow-50 will be nearly white. Use darker steps for legibility. |
+
+### Yellow-Greens (H: 100–130°)
+
+| Aspect | Association |
+|--------|------------|
+| **Goethe** | Renewal, growth. The transition zone — can feel fresh or sickly depending on chroma. |
+| **Adams** | Nature, freshness, sustainability. Chartreuse reads as modern/edgy. |
+| **UI context** | Less common in enterprise. Works for eco/sustainability brands. |
+| **Chroma note** | Narrow sRGB gamut (~0.17). Be conservative. |
+
+### Greens (H: 130–170°)
+
+| Aspect | Association |
+|--------|------------|
+| **Goethe** | Balance, rest, natural equilibrium. The "satisfying" color. |
+| **Adams** | Growth, success, safety, money, health. Universal "positive" signal. |
+| **UI context** | Success states, confirmations, positive metrics, "go" signals. |
+| **Chroma note** | sRGB is very constrained here (~0.13–0.17). P3 adds significant headroom. |
+
+### Teals / Cyans (H: 170–210°)
+
+| Aspect | Association |
+|--------|------------|
+| **Goethe** | Cool, calming, evokes water and sky at their most serene. |
+| **Adams** | Clarity, professionalism, modern tech. Teal signals sophistication without coldness. |
+| **UI context** | Secondary/accent in tech products. Info states. Dashboard visualizations. |
+| **Chroma note** | Most constrained sRGB region (~0.13). P3 is the biggest win here (+46% chroma). |
+
+### Blues (H: 210–270°)
+
+| Aspect | Association |
+|--------|------------|
+| **Goethe** | The "minus side" — calm, contemplative, receding. Evokes distance and depth. |
+| **Adams** | Trust, stability, authority, intelligence. The most universally "safe" brand color. Dominates enterprise, finance, healthcare, tech. |
+| **UI context** | Primary brand, links, interactive elements, info states. The default enterprise choice. |
+| **Chroma note** | Moderate ceiling (~0.17 sRGB). Navy blues (high L contrast) are universally accessible. |
+
+### Violets / Purples (H: 270–310°)
+
+| Aspect | Association |
+|--------|------------|
+| **Goethe** | Restless, ambiguous — neither warm nor cool. Creates tension and mystery. |
+| **Adams** | Luxury, creativity, royalty, spirituality. In tech: AI, innovation, premium tiers. |
+| **UI context** | Premium features, AI/ML indicators, creative tools. Avoid for error/warning (confusion with semantic colors). |
+| **Chroma note** | Opens up slightly (~0.18). Deep purples can be very rich. |
+
+### Magentas / Pinks (H: 310–360°/0–15°)
+
+| Aspect | Association |
+|--------|------------|
+| **Goethe** | The culmination of red and violet — maximum complexity. Regal and theatrical. |
+| **Adams** | Romance, playfulness, femininity (culturally loaded — use with care). Hot pink reads as bold/rebellious. |
+| **UI context** | Accent/highlight in consumer products. Rare in enterprise unless brand-driven. |
+| **Chroma note** | High availability (~0.22). Can push vibrant magentas in sRGB. |
+
+## Quick Reference Table
+
+| Hue Range | H° | Primary Emotion | Enterprise Role | Itten Contrast Pair |
+|-----------|-----|-----------------|-----------------|---------------------|
+| Red | 15–40 | Urgency, power | Error, destructive | Complement: Teal (175–200) |
+| Orange | 40–70 | Warmth, energy | Warning, CTA | Complement: Blue (220–250) |
+| Yellow | 70–100 | Optimism, caution | Highlight, badge | Complement: Violet (250–280) |
+| Green | 130–170 | Balance, success | Success, confirm | Complement: Magenta (310–350) |
+| Teal | 170–210 | Clarity, calm | Info, secondary | Complement: Red-orange (25–50) |
+| Blue | 210–270 | Trust, stability | Primary, links | Complement: Orange-yellow (50–90) |
+| Violet | 270–310 | Luxury, creativity | Premium, AI | Complement: Yellow-green (90–130) |
+| Magenta | 310–360 | Boldness, play | Accent, highlight | Complement: Green (130–170) |

package/skills/dp-color/references/oklch-gamut.md

@@ -0,0 +1,79 @@
+# OKLCH Gamut Reference
+
+## How OKLCH Works
+
+- **L (Lightness):** 0 (black) → 1 (white). Perceptually uniform — equal steps feel equal.
+- **C (Chroma):** 0 (gray) → ~0.4 (max saturation). Actual max depends on hue and lightness.
+- **H (Hue):** 0–360 degrees. 0/360 = pink-red, 90 = yellow, 145 = green, 265 = blue, 330 = magenta.
+
+## sRGB Maximum Chroma by Hue (at L = 0.65)
+
+These are approximate ceilings. Exceeding them produces out-of-gamut colors that browsers
+will clamp, potentially shifting hue or lightness unpredictably.
+
+| Hue Range | Hue (°) | Max Chroma (sRGB) | Notes |
+|-----------|---------|-------------------|-------|
+| Red | 25 | ~0.22 | High chroma available |
+| Orange | 55 | ~0.18 | Moderate ceiling |
+| Yellow | 90 | ~0.18 | Drops fast at high L |
+| Yellow-green | 120 | ~0.17 | Narrow gamut |
+| Green | 145 | ~0.17 | sRGB is weakest here |
+| Teal | 175 | ~0.13 | Very constrained |
+| Cyan | 200 | ~0.13 | Constrained |
+| Blue | 265 | ~0.17 | Moderate |
+| Violet | 295 | ~0.18 | Opens up slightly |
+| Magenta | 330 | ~0.22 | High chroma |
+| Pink-red | 0/360 | ~0.22 | High chroma |
+
+## Key Gamut Rules
+
+1. **Chroma ceiling varies by both hue AND lightness.** At very low or very high L, max chroma
+   drops significantly regardless of hue.
+2. **sRGB is smallest around teal/cyan (H ≈ 175–200).** If you need vibrant teals, consider
+   P3 gamut or accept lower chroma.
+3. **P3 gamut extends chroma ~20–40% beyond sRGB** depending on hue region. Most impactful
+   in greens and cyans.
+4. **Always test in-browser.** Even "safe" values can clip on some displays. Use
+   `color-mix(in oklch, ...)` or `@media (color-gamut: p3)` for progressive enhancement.
+
+## Display P3 Approximate Max Chroma (at L = 0.65)
+
+| Hue Region | Max Chroma (P3) | Gain over sRGB |
+|------------|-----------------|----------------|
+| Red (25°) | ~0.29 | +32% |
+| Green (145°) | ~0.24 | +41% |
+| Teal (175°) | ~0.19 | +46% |
+| Cyan (200°) | ~0.18 | +38% |
+| Blue (265°) | ~0.22 | +29% |
+| Magenta (330°) | ~0.28 | +27% |
+
+## Lightness vs. Chroma Envelope
+
+General pattern for sRGB at any hue:
+
+```
+L = 0.00–0.15  →  Max C ≈ 0.05–0.10  (very dark, low chroma ceiling)
+L = 0.15–0.35  →  Max C rises steeply
+L = 0.35–0.70  →  Max C at peak (hue-dependent, see table above)
+L = 0.70–0.85  →  Max C starts dropping
+L = 0.85–1.00  →  Max C ≈ 0.04–0.08  (very light, low chroma ceiling)
+```
+
+This means your most saturated shades will sit in the mid-lightness range (~400–600 on a
+typical scale). The extremes (25, 50, 850, 900) will always be lower chroma.
+
+## Practical CSS
+
+```css
+/* sRGB safe */
+--color-primary-500: oklch(0.65 0.17 265);
+
+/* P3 enhanced with sRGB fallback */
+--color-primary-500: oklch(0.65 0.17 265);
+@media (color-gamut: p3) {
+  --color-primary-500: oklch(0.65 0.22 265);
+}
+
+/* Relative color syntax for tinting */
+--color-primary-100: oklch(from var(--color-primary-500) 0.95 0.03 h);
+```