Color Systems skill for Claude Code

#!/usr/bin/env python3
"""Color utilities for building contrast-safe palettes. Standard library only.

Commands:
  contrast FG BG [FG BG ...] [--min 4.5]   WCAG 2.x contrast ratio for each pair
  convert COLOR [COLOR ...]                 hex <-> oklch conversion
  scale HUE [--chroma 0.16]                 11-step OKLCH scale (50..950), gamut-mapped

Colors: #rgb, #rrggbb, or oklch(L C H) with L as 0-1 or a percentage.
Exit code 1 if any contrast pair falls below --min.
"""
import argparse
import math
import re
import sys

STEPS = [50, 100, 200, 300, 400, 500, 600, 700, 800, 900, 950]
LIGHTNESS = [0.975, 0.94, 0.88, 0.80, 0.71, 0.62, 0.54, 0.46, 0.38, 0.30, 0.24]
CHROMA_MULT = [0.12, 0.28, 0.52, 0.78, 0.94, 1.0, 0.96, 0.86, 0.72, 0.58, 0.46]


def parse(color):
    c = color.strip().lower()
    m = re.fullmatch(r"#([0-9a-f]{3}|[0-9a-f]{6})", c)
    if m:
        h = m.group(1)
        if len(h) == 3:
            h = "".join(ch * 2 for ch in h)
        return tuple(int(h[i:i + 2], 16) / 255 for i in (0, 2, 4))
    m = re.fullmatch(r"oklch\(\s*([\d.]+)(%?)\s+([\d.]+)\s+([\d.]+)(?:deg)?\s*(?:/\s*[\d.%]+)?\s*\)", c)
    if m:
        L = float(m.group(1)) / (100 if m.group(2) else 1)
        r, g, b = oklch_to_srgb(L, float(m.group(3)), float(m.group(4)))
        return clamp(r), clamp(g), clamp(b)
    raise ValueError(f"unsupported color: {color!r} (use #rrggbb or oklch(L C H))")


def clamp(x):
    return min(1.0, max(0.0, x))


def to_linear(x):
    return x / 12.92 if x <= 0.04045 else ((x + 0.055) / 1.055) ** 2.4


def from_linear(x):
    return 12.92 * x if x <= 0.0031308 else 1.055 * (x ** (1 / 2.4)) - 0.055


def oklch_to_srgb(L, C, H):
    a, b = C * math.cos(math.radians(H)), 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
    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 tuple(from_linear(v) if v >= 0 else -from_linear(-v) for v in (r, g, bl))


def srgb_to_oklch(rgb):
    r, g, b = (to_linear(v) for v in rgb)
    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
    return L, C, H


def in_gamut(rgb, eps=1e-4):
    return all(-eps <= v <= 1 + eps for v in rgb)


def to_hex(rgb):
    return "#" + "".join(f"{round(clamp(v) * 255):02x}" for v in rgb)


def luminance(rgb):
    r, g, b = (to_linear(v) for v in rgb)
    return 0.2126 * r + 0.7152 * g + 0.0722 * b


def ratio(fg, bg):
    a, b = luminance(fg), luminance(bg)
    hi, lo = max(a, b), min(a, b)
    return (hi + 0.05) / (lo + 0.05)


def verdict(r):
    tags = []
    tags.append("AAA" if r >= 7 else "AA" if r >= 4.5 else "AA-large/UI" if r >= 3 else "FAIL")
    return tags[0]


def cmd_contrast(args):
    vals = args.colors
    if len(vals) % 2:
        sys.exit("contrast needs FG BG pairs")
    failed = 0
    print(f"{'foreground':<26}{'background':<26}{'ratio':>7}  level")
    for fg, bg in zip(vals[0::2], vals[1::2]):
        r = ratio(parse(fg), parse(bg))
        flag = "" if r >= args.min else f"  < {args.min}"
        failed += r < args.min
        print(f"{fg:<26}{bg:<26}{r:>7.2f}  {verdict(r)}{flag}")
    print(f"\n{failed} pair(s) below {args.min}:1" if failed else f"\nall pairs >= {args.min}:1")
    return 1 if failed else 0


def cmd_convert(args):
    for c in args.colors:
        rgb = parse(c)
        L, C, H = srgb_to_oklch(rgb)
        note = ""
        m = re.match(r"\s*oklch\(\s*([\d.]+)(%?)\s+([\d.]+)\s+([\d.]+)", c.lower())
        if m:
            raw = oklch_to_srgb(float(m.group(1)) / (100 if m.group(2) else 1), float(m.group(3)), float(m.group(4)))
            if not in_gamut(raw):
                note = "  (outside sRGB: hex is clipped)"
        print(f"{c:<28} {to_hex(rgb)}  oklch({L:.3f} {C:.3f} {H:.1f}){note}")
    return 0


def cmd_scale(args):
    white, black = (1.0, 1.0, 1.0), (0.0, 0.0, 0.0)
    print(f"{'step':<6}{'oklch':<26}{'hex':<10}{'vs white':>9}{'vs black':>9}")
    css = []
    for step, L, k in zip(STEPS, LIGHTNESS, CHROMA_MULT):
        C = args.chroma * k
        rgb = oklch_to_srgb(L, C, args.hue)
        while not in_gamut(rgb) and C > 0:
            C = max(0.0, C - 0.002)
            rgb = oklch_to_srgb(L, C, args.hue)
        rgb = tuple(clamp(v) for v in rgb)
        ok = f"oklch({L:.3f} {C:.3f} {args.hue:g})"
        print(f"{step:<6}{ok:<26}{to_hex(rgb):<10}{ratio(rgb, white):>9.2f}{ratio(rgb, black):>9.2f}")
        css.append(f"  --{args.name}-{step}: {ok};")
    print("\n:root {\n" + "\n".join(css) + "\n}")
    return 0


def main():
    p = argparse.ArgumentParser(description=__doc__, formatter_class=argparse.RawDescriptionHelpFormatter)
    sub = p.add_subparsers(dest="cmd", required=True)
    c = sub.add_parser("contrast")
    c.add_argument("colors", nargs="+")
    c.add_argument("--min", type=float, default=4.5)
    v = sub.add_parser("convert")
    v.add_argument("colors", nargs="+")
    s = sub.add_parser("scale")
    s.add_argument("hue", type=float)
    s.add_argument("--chroma", type=float, default=0.16)
    s.add_argument("--name", default="hue")
    args = p.parse_args()
    try:
        return {"contrast": cmd_contrast, "convert": cmd_convert, "scale": cmd_scale}[args.cmd](args)
    except ValueError as e:
        print(f"error: {e}", file=sys.stderr)
        return 2


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