Color Systems skill for Codex

Gives the Codex app a display name, a one-line description and a starter prompt for this skill.

interface:
  display_name: "Color Systems"
  short_description: "Even OKLCH ramps, semantic roles, contrast that passes"
  default_prompt: "$color-systems Build a color palette in OKLCH from our brand blue #1d5fd6 with light and dark roles"

#!/usr/bin/env python3
"""OKLCH palette helper: build gamut-safe ramps, convert colors, check WCAG contrast.

Standard library only (Python 3.10+).

  python3 oklch_palette.py ramp --hue 255 --chroma 0.16 --name blue
  python3 oklch_palette.py contrast "#ffffff" "oklch(0.55 0.16 255)" --min 4.5
  python3 oklch_palette.py convert "#1d5fd6"
"""
from __future__ import annotations

import argparse
import math
import re
import sys

STEPS = [50, 100, 200, 300, 400, 500, 600, 700, 800, 900, 950]
# Perceptual lightness targets and chroma multipliers per step (mid steps carry most chroma).
LIGHTNESS = [0.975, 0.945, 0.89, 0.82, 0.72, 0.63, 0.55, 0.47, 0.39, 0.31, 0.25]
CHROMA_FACTOR = [0.22, 0.38, 0.6, 0.82, 0.96, 1.0, 1.0, 0.92, 0.8, 0.66, 0.52]


def srgb_to_linear(c: float) -> float:
    return c / 12.92 if c <= 0.04045 else ((c + 0.055) / 1.055) ** 2.4


def linear_to_srgb(c: float) -> float:
    return 12.92 * c if c <= 0.0031308 else 1.055 * (c ** (1 / 2.4)) - 0.055


def oklch_to_linear_rgb(L: float, C: float, H: float) -> tuple[float, float, float]:
    a = C * math.cos(math.radians(H))
    b = C * math.sin(math.radians(H))
    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, m, s = l_ ** 3, m_ ** 3, s_ ** 3
    return (
        4.0767416621 * l - 3.3077115913 * m + 0.2309699292 * s,
        -1.2684380046 * l + 2.6097574011 * m - 0.3413193965 * s,
        -0.0041960863 * l - 0.7034186147 * m + 1.7076147010 * s,
    )


def linear_rgb_to_oklch(r: float, g: float, b: float) -> tuple[float, float, float]:
    l = 0.4122214708 * r + 0.5363325363 * g + 0.0514459929 * b
    m = 0.2119034982 * r + 0.6806995451 * g + 0.1073969566 * b
    s = 0.0883024619 * r + 0.2817188376 * g + 0.6299787005 * b
    l_, m_, s_ = (math.copysign(abs(v) ** (1 / 3), v) for v in (l, m, s))
    L = 0.2104542553 * l_ + 0.7936177850 * m_ - 0.0040720468 * s_
    A = 1.9779984951 * l_ - 2.4285922050 * m_ + 0.4505937099 * s_
    B = 0.0259040371 * l_ + 0.7827717662 * m_ - 0.8086757660 * s_
    C = math.hypot(A, B)
    H = math.degrees(math.atan2(B, A)) % 360 if C > 1e-6 else 0.0
    return L, C, H


def in_gamut(rgb: tuple[float, float, float], eps: float = 1e-4) -> bool:
    return all(-eps <= c <= 1 + eps for c in rgb)


def gamut_map(L: float, C: float, H: float) -> tuple[float, float, float]:
    """Reduce chroma (keeping L and H) until the color fits in sRGB."""
    if in_gamut(oklch_to_linear_rgb(L, C, H)):
        return L, C, H
    lo, hi = 0.0, C
    for _ in range(30):
        mid = (lo + hi) / 2
        if in_gamut(oklch_to_linear_rgb(L, mid, H)):
            lo = mid
        else:
            hi = mid
    return L, lo, H


def to_hex(L: float, C: float, H: float) -> str:
    rgb = oklch_to_linear_rgb(*gamut_map(L, C, H))
    chans = [round(min(1, max(0, linear_to_srgb(min(1, max(0, c))))) * 255) for c in rgb]
    return "#" + "".join(f"{c:02x}" for c in chans)


def parse_color(text: str) -> tuple[float, float, float]:
    """Return linear sRGB for '#rgb', '#rrggbb' or 'oklch(L C H)' (L as 0-1 or %)."""
    t = text.strip().lower()
    m = re.fullmatch(r"#?([0-9a-f]{3}|[0-9a-f]{6})", t)
    if m:
        h = m.group(1)
        if len(h) == 3:
            h = "".join(ch * 2 for ch in h)
        return tuple(srgb_to_linear(int(h[i:i + 2], 16) / 255) for i in (0, 2, 4))  # type: ignore[return-value]
    m = re.fullmatch(r"oklch\(\s*([\d.]+)(%?)\s+([\d.]+)\s+([\d.]+)(?:deg)?\s*(?:/\s*[\d.%]+\s*)?\)", t)
    if m:
        L = float(m.group(1)) / (100 if m.group(2) else 1)
        rgb = oklch_to_linear_rgb(*gamut_map(L, float(m.group(3)), float(m.group(4))))
        return tuple(min(1.0, max(0.0, c)) for c in rgb)  # type: ignore[return-value]
    raise ValueError(f"unrecognized color: {text!r} (use #rrggbb or oklch(L C H))")


def luminance(rgb: tuple[float, float, float]) -> float:
    r, g, b = rgb
    return 0.2126 * r + 0.7152 * g + 0.0722 * b


def contrast(a: tuple[float, float, float], b: tuple[float, float, float]) -> float:
    la, lb = sorted((luminance(a), luminance(b)), reverse=True)
    return (la + 0.05) / (lb + 0.05)


def fmt_oklch(L: float, C: float, H: float) -> str:
    return f"oklch({L:.3f} {C:.3f} {H:.1f})"


def cmd_ramp(args: argparse.Namespace) -> int:
    white, black = parse_color("#ffffff"), parse_color("#000000")
    print(f"/* {args.name}: hue {args.hue}, peak chroma {args.chroma} (gamut-mapped to sRGB) */")
    print(":root {")
    rows = []
    for step, L, f in zip(STEPS, LIGHTNESS, CHROMA_FACTOR):
        L2, C2, H2 = gamut_map(L, args.chroma * f, args.hue)
        hexv = to_hex(L2, C2, H2)
        rgb = parse_color(hexv)
        rows.append((step, fmt_oklch(L2, C2, H2), hexv, contrast(rgb, white), contrast(rgb, black)))
        print(f"  --color-{args.name}-{step}: {fmt_oklch(L2, C2, H2)}; /* {hexv} */")
    print("}")
    print(f"\n{'step':>5}  {'oklch':<28} {'hex':<8} {'vs white':>9} {'vs black':>9}")
    for step, ok, hexv, cw, cb in rows:
        flag_w = "AA" if cw >= 4.5 else ("lg" if cw >= 3 else "  ")
        flag_b = "AA" if cb >= 4.5 else ("lg" if cb >= 3 else "  ")
        print(f"{step:>5}  {ok:<28} {hexv:<8} {cw:>6.2f} {flag_w} {cb:>6.2f} {flag_b}")
    print("\nAA = 4.5:1 body text, lg = 3:1 large text / UI boundaries only")
    return 0


def cmd_contrast(args: argparse.Namespace) -> int:
    ratio = contrast(parse_color(args.fg), parse_color(args.bg))
    verdict = "AA body" if ratio >= 4.5 else ("AA large/UI only" if ratio >= 3 else "FAIL")
    if ratio >= 7:
        verdict = "AAA body"
    print(f"{args.fg} on {args.bg}: {ratio:.2f}:1 ({verdict})")
    if args.min is not None and ratio < args.min:
        print(f"below required minimum {args.min}:1", file=sys.stderr)
        return 1
    return 0


def cmd_convert(args: argparse.Namespace) -> int:
    rgb = parse_color(args.color)
    L, C, H = linear_rgb_to_oklch(*rgb)
    print(f"{args.color} -> {to_hex(L, C, H)}  {fmt_oklch(L, C, H)}")
    return 0


def main() -> int:
    p = argparse.ArgumentParser(description=__doc__, formatter_class=argparse.RawDescriptionHelpFormatter)
    sub = p.add_subparsers(dest="cmd", required=True)
    r = sub.add_parser("ramp", help="generate an 11-step ramp (50-950)")
    r.add_argument("--hue", type=float, required=True, help="OKLCH hue in degrees")
    r.add_argument("--chroma", type=float, default=0.15, help="peak chroma (0.02 neutral to 0.25 vivid)")
    r.add_argument("--name", default="brand", help="custom property name segment")
    r.set_defaults(func=cmd_ramp)
    c = sub.add_parser("contrast", help="WCAG 2 contrast ratio of two colors")
    c.add_argument("fg")
    c.add_argument("bg")
    c.add_argument("--min", type=float, help="exit 1 if the ratio is below this")
    c.set_defaults(func=cmd_contrast)
    v = sub.add_parser("convert", help="convert hex or oklch to both forms")
    v.add_argument("color")
    v.set_defaults(func=cmd_convert)
    args = p.parse_args()
    try:
        return args.func(args)
    except ValueError as e:
        print(f"error: {e}", file=sys.stderr)
        return 2


if __name__ == "__main__":
    sys.exit(main())