claude-code-superkit 0.0.0-stage → 1.5.3

package/packages/frontend-ui/hooks/tests/ui-color-check_test.sh

@@ -0,0 +1,75 @@
+#!/bin/bash
+set -u
+HOOK=$(cd "$(dirname "$0")/.." && pwd)/ui-color-check.sh
+PASS=0; FAIL=0
+
+expect_warn() {
+  local name="$1"; local needle="$2"; local payload="$3"
+  local out
+  out=$(echo "$payload" | bash "$HOOK" 2>&1 >/dev/null || true)
+  if echo "$out" | grep -q "$needle"; then
+    echo "  ✓ $name"; PASS=$((PASS + 1))
+  else
+    echo "  ✗ $name — expected warning containing '$needle', got: $(echo "$out" | head -2)"
+    FAIL=$((FAIL + 1))
+  fi
+}
+
+expect_silent() {
+  local name="$1"; local payload="$2"
+  local out
+  out=$(echo "$payload" | bash "$HOOK" 2>&1 >/dev/null || true)
+  if [ -z "$out" ]; then
+    echo "  ✓ $name"; PASS=$((PASS + 1))
+  else
+    echo "  ✗ $name — expected silent, got: $(echo "$out" | head -1)"
+    FAIL=$((FAIL + 1))
+  fi
+}
+
+echo "── ui-color-check.sh tests ──"
+
+expect_warn "A) pure #000 in color" "Pure #000 or #fff" \
+  '{"tool_input":{"file_path":"/tmp/x.css","new_string":".a{color:#000;}"}}'
+
+expect_warn "B) pure #fff in background" "Pure #000 or #fff" \
+  '{"tool_input":{"file_path":"/tmp/x.css","new_string":".b{background:#fff;}"}}'
+
+expect_warn "C) rgb(0,0,0) in color" "Pure rgb" \
+  '{"tool_input":{"file_path":"/tmp/x.tsx","new_string":"const s={color:\"rgb(0, 0, 0)\"};"}}'
+
+expect_warn "D) Tailwind bg-black" "bg-black/bg-white" \
+  '{"tool_input":{"file_path":"/tmp/x.tsx","new_string":"<div className=\"bg-black text-white\">"}}'
+
+expect_warn "E) gradient text (background-clip+linear-gradient)" "Gradient text detected" \
+  '{"tool_input":{"file_path":"/tmp/x.css","new_string":"h1{background:linear-gradient(45deg,#f00,#00f);background-clip:text;color:transparent;}"}}'
+
+expect_warn "F) purple-to-blue gradient" "Purple→blue gradient" \
+  '{"tool_input":{"file_path":"/tmp/x.css","new_string":".hero{background:linear-gradient(135deg, purple 0%, blue 100%);}"}}'
+
+expect_warn "G) 3+ hsl without oklch" "Multiple hsl" \
+  '{"tool_input":{"file_path":"/tmp/x.css","new_string":":root{--a:hsl(0 50% 50%);--b:hsl(120 50% 50%);--c:hsl(240 50% 50%);}"}}'
+
+expect_silent "H) oklch-only palette silent" \
+  '{"tool_input":{"file_path":"/tmp/x.css","new_string":":root{--a:oklch(50% 0.1 260);--b:oklch(40% 0.1 260);}"}}'
+
+expect_silent "I) Non-UI file silent" \
+  '{"tool_input":{"file_path":"/tmp/x.go","new_string":"func black() string { return \"#000\" }"}}'
+
+expect_silent "J) box-shadow with rgba(0,0,0,0.5) — not a color declaration on color/background" \
+  '{"tool_input":{"file_path":"/tmp/x.css","new_string":".a{box-shadow:0 2px 4px rgba(0,0,0,0.5);}"}}'
+
+expect_silent "K) Single hsl (not palette) silent" \
+  '{"tool_input":{"file_path":"/tmp/x.css","new_string":".a{color:hsl(200 50% 50%);}"}}'
+
+out=$(echo '{"tool_input":{"file_path":"/tmp/x.css","new_string":".a{color:#000;}"}}' | CLAUDE_DISABLE_UI_COLOR_CHECK=1 bash "$HOOK" 2>&1 >/dev/null || true)
+if [ -z "$out" ]; then
+  echo "  ✓ L) Opt-out via CLAUDE_DISABLE_UI_COLOR_CHECK"; PASS=$((PASS + 1))
+else
+  echo "  ✗ L) Opt-out failed"; FAIL=$((FAIL + 1))
+fi
+
+echo ""
+echo "── Results ──"
+echo "  Pass: $PASS  Fail: $FAIL"
+[ "$FAIL" -eq 0 ] || exit 1

package/packages/frontend-ui/hooks/ui-animation-easing-check.sh

@@ -0,0 +1,86 @@
+#!/bin/bash
+# ui-animation-easing-check.sh — warns on ease-in, transition: all, scale(0)
+# Triggers on: PostToolUse (Edit|Write)
+# Profile: all (advisory only, never blocks)
+# Opt-out: CLAUDE_DISABLE_UI_ANIM_CHECK=1
+#
+# Flags motion anti-patterns from motion-and-animation.md and
+# ui-anti-patterns.md:
+#   - ease-in on UI transitions/animations (sluggish; use ease-out)
+#   - transition: all (animates layout props; specify exact)
+#   - scale(0) as entry animation (use scale(0.95))
+#   - Animating width/height/top/left/margin (not compositor-accelerated)
+
+# Unified profile + disable check
+SUPERKIT_PROFILE_LIB="$(dirname "$0")/lib/profile.sh"
+[ -f "$SUPERKIT_PROFILE_LIB" ] || SUPERKIT_PROFILE_LIB="$(dirname "$0")/../lib/profile.sh"
+# shellcheck source=/dev/null
+[ -f "$SUPERKIT_PROFILE_LIB" ] && source "$SUPERKIT_PROFILE_LIB" && should_skip_hook "$(basename "$0" .sh)" && exit 0
+
+if [ "${CLAUDE_DISABLE_UI_ANIM_CHECK:-}" = "1" ]; then
+  exit 0
+fi
+
+INPUT=$(cat 2>/dev/null || echo '{}')
+FILE_PATH=$(echo "$INPUT" | jq -r '.tool_input.file_path // .file_path // empty' 2>/dev/null)
+NEW_STRING=$(echo "$INPUT" | jq -r '.tool_input.new_string // .tool_input.content // .new_string // empty' 2>/dev/null)
+
+if [ -z "$FILE_PATH" ] || [ -z "$NEW_STRING" ]; then
+  exit 0
+fi
+
+case "$FILE_PATH" in
+  *.css|*.scss|*.tsx|*.jsx|*.ts|*.html|*.vue|*tailwind.config.*|*.tokens.*)
+    ;;
+  *)
+    exit 0
+    ;;
+esac
+
+WARNINGS=""
+
+# (1) ease-in on UI — must NOT match ease-in-out (which is legitimate).
+# POSIX-grep has no negative lookahead, so we use `ease-in([^-]|$)` which
+# requires any non-hyphen character (or end-of-line) after ease-in.
+if echo "$NEW_STRING" | grep -qE '(transition|animation)[[:space:]]*:[^;]*ease-in([^-]|$)'; then
+  WARNINGS+="  • ease-in on UI transition/animation — use ease-out (starts fast, feels responsive)\n"
+elif echo "$NEW_STRING" | grep -qE '(transition-timing-function|animation-timing-function)[[:space:]]*:[[:space:]]*ease-in([^-]|$)'; then
+  WARNINGS+="  • ease-in timing function — use ease-out\n"
+fi
+
+# (2) transition: all
+if echo "$NEW_STRING" | grep -qE 'transition[[:space:]]*:[[:space:]]*all\b'; then
+  WARNINGS+="  • transition: all — specify exact properties (transform/opacity) to avoid layout stutter\n"
+fi
+
+# Tailwind transition-all
+if echo "$NEW_STRING" | grep -qE '\btransition-all\b'; then
+  WARNINGS+="  • Tailwind transition-all — prefer transition-transform / transition-opacity / transition-colors\n"
+fi
+
+# (3) scale(0) as entry animation — but not scale(0.X) which is fine
+if echo "$NEW_STRING" | grep -qE '(transform|animation)[^;]*\bscale\([[:space:]]*0[[:space:]]*\)|@keyframes[^}]*\bscale\([[:space:]]*0[[:space:]]*\)'; then
+  WARNINGS+="  • scale(0) as animation target — nothing in the real world appears from true zero; use scale(0.95)\n"
+fi
+
+# Tailwind scale-0 — must not match scale-0.95 or scale-01 etc.
+# `scale-0` followed by anything that is NOT a digit/period/letter, or end-of-line.
+if echo "$NEW_STRING" | grep -qE 'scale-0[^0-9.a-zA-Z]|scale-0$'; then
+  WARNINGS+="  • Tailwind scale-0 — prefer scale-95 (or custom tw scale) for entry/exit animations\n"
+fi
+
+# (4) Animating layout properties (width/height/top/left/margin) — expensive
+if echo "$NEW_STRING" | grep -qE 'transition[^;]*\b(width|height|top|left|right|bottom|margin(-top|-right|-bottom|-left)?|padding(-top|-right|-bottom|-left)?)\b'; then
+  WARNINGS+="  • Transitioning width/height/top/left/margin — use transform + opacity (compositor-accelerated)\n"
+fi
+
+if [ -n "$WARNINGS" ]; then
+  echo "" >&2
+  echo "⚠ UI: motion anti-patterns in ${FILE_PATH}" >&2
+  printf "%b" "$WARNINGS" >&2
+  echo "  See .claude/rules/motion-and-animation.md" >&2
+  echo "  Opt out: export CLAUDE_DISABLE_UI_ANIM_CHECK=1" >&2
+  echo "" >&2
+fi
+
+exit 0

package/packages/frontend-ui/hooks/ui-banned-fonts-check.sh

@@ -0,0 +1,90 @@
+#!/bin/bash
+# ui-banned-fonts-check.sh — warns on reflex-list fonts in .css/.tsx/.html
+# Triggers on: PostToolUse (Edit|Write)
+# Profile: all (advisory only, never blocks)
+# Opt-out: CLAUDE_DISABLE_UI_FONT_CHECK=1
+#
+# Scans the incoming diff for fonts in the reflex_fonts_to_reject list
+# from .claude/rules/ui-anti-patterns.md. Writes a stderr
+# warning pointing at the rule so Claude can correct course BEFORE the
+# edit settles into the design system. Never blocks — exit 0 always.
+
+# Unified profile + disable check
+SUPERKIT_PROFILE_LIB="$(dirname "$0")/lib/profile.sh"
+[ -f "$SUPERKIT_PROFILE_LIB" ] || SUPERKIT_PROFILE_LIB="$(dirname "$0")/../lib/profile.sh"
+# shellcheck source=/dev/null
+[ -f "$SUPERKIT_PROFILE_LIB" ] && source "$SUPERKIT_PROFILE_LIB" && should_skip_hook "$(basename "$0" .sh)" && exit 0
+
+if [ "${CLAUDE_DISABLE_UI_FONT_CHECK:-}" = "1" ]; then
+  exit 0
+fi
+
+INPUT=$(cat 2>/dev/null || echo '{}')
+FILE_PATH=$(echo "$INPUT" | jq -r '.tool_input.file_path // .file_path // empty' 2>/dev/null)
+NEW_STRING=$(echo "$INPUT" | jq -r '.tool_input.new_string // .tool_input.content // .new_string // empty' 2>/dev/null)
+
+if [ -z "$FILE_PATH" ] || [ -z "$NEW_STRING" ]; then
+  exit 0
+fi
+
+# Only scan UI-relevant files
+case "$FILE_PATH" in
+  *.css|*.scss|*.tsx|*.jsx|*.ts|*.html|*.vue|*tailwind.config.*|*.tokens.*)
+    ;;
+  *)
+    exit 0
+    ;;
+esac
+
+# Skip if file path suggests we're in a code-block / prose / syntax highlighter
+# context where monospace fonts like Space Mono are legitimately used.
+case "$FILE_PATH" in
+  *code-block*|*codeblock*|*prose*|*syntax-highlight*|*highlighter*)
+    exit 0
+    ;;
+esac
+
+# reflex_fonts_to_reject — case-insensitive exact-ish matching.
+# Match is scoped to font-family declarations and common Tailwind font classes
+# to avoid false positives (e.g. a variable named `inter` in JSX).
+BANNED_PATTERNS=(
+  'Fraunces'
+  'Newsreader'
+  '\bLora\b'
+  'Crimson[[:space:]]*(Pro|Text)?'
+  'Playfair([[:space:]]*Display)?'
+  'Cormorant([[:space:]]*Garamond)?'
+  '\bSyne\b'
+  'IBM[[:space:]]*Plex[[:space:]]*(Sans|Serif|Mono)'
+  'Space[[:space:]]*(Mono|Grotesk)'
+  '\bInter\b'
+  'DM[[:space:]]*(Sans|Serif[[:space:]]*(Display|Text))'
+  '\bOutfit\b'
+  'Plus[[:space:]]*Jakarta[[:space:]]*Sans'
+  'Instrument[[:space:]]*(Sans|Serif)'
+)
+
+# Collect hits
+HITS=""
+for pat in "${BANNED_PATTERNS[@]}"; do
+  # Look for font in font-family declaration OR Tailwind font-* utility OR import url
+  matches=$(echo "$NEW_STRING" | grep -E "(font-family:.*${pat}|font-\[['\"]?${pat}|['\"]${pat}['\"].*(font|family)|fonts\.googleapis\.com.*${pat// /+}|${pat}[[:space:]]*[,;])" -io 2>/dev/null | head -3)
+  if [ -n "$matches" ]; then
+    # Extract clean font name for reporting
+    clean=$(echo "$pat" | sed -E 's/\\b|\[\[:space:\]\]\*|\(|\)|\?|\|/ /g' | tr -s ' ' | sed -E 's/^ | $//g' | head -c 40)
+    HITS="${HITS}  • ${clean}\n"
+  fi
+done
+
+if [ -n "$HITS" ]; then
+  echo "" >&2
+  echo "⚠ UI: reflex-list font detected in ${FILE_PATH}" >&2
+  printf "%b" "$HITS" >&2
+  echo "  These fonts are the LLM's training-data defaults and create visual" >&2
+  echo "  monoculture. Consider running the font-selection procedure in" >&2
+  echo "  .claude/rules/typography-guidelines.md (Step 1-4)." >&2
+  echo "  Opt out: export CLAUDE_DISABLE_UI_FONT_CHECK=1" >&2
+  echo "" >&2
+fi
+
+exit 0

package/packages/frontend-ui/hooks/ui-color-check.sh

@@ -0,0 +1,102 @@
+#!/bin/bash
+# ui-color-check.sh — warns on pure #000/#fff, AI-palette patterns, gradient text
+# Triggers on: PostToolUse (Edit|Write)
+# Profile: all (advisory only, never blocks)
+# Opt-out: CLAUDE_DISABLE_UI_COLOR_CHECK=1
+#
+# Flags three categories of AI-color-reflex:
+#   1. Pure #000 / #fff / rgb(0,0,0) / rgb(255,255,255)
+#   2. Gradient text (background-clip: text with a multi-color gradient)
+#   3. Purple→blue / cyan-on-black / neon-glow accents
+#
+# Per color-and-contrast.md: tint everything toward brand hue, use oklch,
+# avoid gradient text for impact, avoid the AI palette.
+
+# Unified profile + disable check
+SUPERKIT_PROFILE_LIB="$(dirname "$0")/lib/profile.sh"
+[ -f "$SUPERKIT_PROFILE_LIB" ] || SUPERKIT_PROFILE_LIB="$(dirname "$0")/../lib/profile.sh"
+# shellcheck source=/dev/null
+[ -f "$SUPERKIT_PROFILE_LIB" ] && source "$SUPERKIT_PROFILE_LIB" && should_skip_hook "$(basename "$0" .sh)" && exit 0
+
+if [ "${CLAUDE_DISABLE_UI_COLOR_CHECK:-}" = "1" ]; then
+  exit 0
+fi
+
+INPUT=$(cat 2>/dev/null || echo '{}')
+FILE_PATH=$(echo "$INPUT" | jq -r '.tool_input.file_path // .file_path // empty' 2>/dev/null)
+NEW_STRING=$(echo "$INPUT" | jq -r '.tool_input.new_string // .tool_input.content // .new_string // empty' 2>/dev/null)
+
+if [ -z "$FILE_PATH" ] || [ -z "$NEW_STRING" ]; then
+  exit 0
+fi
+
+# Only scan UI-relevant files
+case "$FILE_PATH" in
+  *.css|*.scss|*.tsx|*.jsx|*.ts|*.html|*.vue|*tailwind.config.*|*.tokens.*)
+    ;;
+  *)
+    exit 0
+    ;;
+esac
+
+WARNINGS=""
+
+# (1) Pure black / white — look in color / background(-color) / fill / stroke contexts
+# to avoid false positives on shadow opacity, box-shadow: 0 0 0 etc.
+# SEP matches :, optional whitespace, optional quote/backtick (JSX/TS inline styles)
+SEP='[[:space:]]*:[[:space:]]*[\"'"'"'\`]*[[:space:]]*'
+if echo "$NEW_STRING" | grep -qE "(color|background|background-color|fill|stroke)${SEP}#(000|fff|000000|ffffff|FFF|FFFFFF)([^0-9a-fA-F]|$)"; then
+  WARNINGS+="  • Pure #000 or #fff in color/background — tint toward brand hue (oklch)\n"
+elif echo "$NEW_STRING" | grep -qE "(color|background|background-color|fill|stroke)${SEP}rgb[a]?\([[:space:]]*0[[:space:]]*,[[:space:]]*0[[:space:]]*,[[:space:]]*0|(color|background|background-color|fill|stroke)${SEP}rgb[a]?\([[:space:]]*255[[:space:]]*,[[:space:]]*255[[:space:]]*,[[:space:]]*255"; then
+  WARNINGS+="  • Pure rgb(0,0,0) or rgb(255,255,255) — tint toward brand hue (oklch)\n"
+fi
+
+# Tailwind bg-black / text-black / bg-white / text-white (not tinted)
+# Note: if the project uses Tailwind with customised black/white tokens, this
+# may false-positive. It's advisory only, so a small false-positive tax is OK.
+if echo "$NEW_STRING" | grep -qE '\b(bg|text|fill|stroke|border)-(black|white)\b'; then
+  WARNINGS+="  • Tailwind bg-black/bg-white or text-black/text-white — prefer tinted neutrals\n"
+fi
+
+# (2) Gradient text — background-clip: text with a *-gradient background
+if echo "$NEW_STRING" | grep -qE 'background-clip[[:space:]]*:[[:space:]]*text' && \
+   echo "$NEW_STRING" | grep -qE 'background(-image)?[[:space:]]*:[[:space:]]*(linear|radial|conic)-gradient'; then
+  WARNINGS+="  • Gradient text detected (background-clip: text + gradient) — solid colors only for text\n"
+fi
+
+# Tailwind gradient-text pattern
+if echo "$NEW_STRING" | grep -qE 'bg-clip-text[[:space:]][^>]*bg-gradient-to|bg-gradient-to[[:space:]][^>]*bg-clip-text'; then
+  WARNINGS+="  • Tailwind gradient text (bg-clip-text + bg-gradient-*) — solid colors only for text\n"
+fi
+
+# (3) AI palette — purple-to-blue gradient
+if echo "$NEW_STRING" | grep -qiE 'linear-gradient\([^)]*(purple|violet|indigo|#8b5cf6|#a855f7|#7c3aed)[^)]*(blue|cyan|#3b82f6|#06b6d4|#0ea5e9)'; then
+  WARNINGS+="  • Purple→blue gradient detected — a trademark AI-palette pattern, reconsider\n"
+fi
+
+# Cyan on black — #0ff or oklch cyan on pure black
+if echo "$NEW_STRING" | grep -qE 'color[[:space:]]*:[[:space:]]*(#0ff|#00ffff|cyan)' && \
+   echo "$NEW_STRING" | grep -qE '(background|bg)[^;]*(#000|#0+0|black)'; then
+  WARNINGS+="  • Cyan on black detected — the AI 'cyber' aesthetic default\n"
+fi
+
+# No oklch in a file that only uses hsl (suggest migration)
+# Only warn when the file looks like it's defining a palette (multiple color tokens)
+if echo "$NEW_STRING" | grep -qE 'hsl\(' && ! echo "$NEW_STRING" | grep -qE 'oklch\('; then
+  # Count actual hsl() occurrences, not lines containing hsl
+  hsl_count=$(echo "$NEW_STRING" | grep -oE 'hsl\(' | wc -l | tr -d ' ')
+  if [ "${hsl_count:-0}" -ge 3 ]; then
+    WARNINGS+="  • Multiple hsl() declarations without oklch() — prefer oklch for perceptual uniformity\n"
+  fi
+fi
+
+if [ -n "$WARNINGS" ]; then
+  echo "" >&2
+  echo "⚠ UI: color anti-patterns in ${FILE_PATH}" >&2
+  printf "%b" "$WARNINGS" >&2
+  echo "  See .claude/rules/color-and-contrast.md and ui-anti-patterns.md" >&2
+  echo "  Opt out: export CLAUDE_DISABLE_UI_COLOR_CHECK=1" >&2
+  echo "" >&2
+fi
+
+exit 0

package/packages/frontend-ui/rules/color-and-contrast.md

@@ -0,0 +1,230 @@
+---
+name: color-and-contrast
+description: "Color system rules — OKLCH over HSL, tinted neutrals, 60-30-10 weight, contrast, dark/light theme selection by use context. Auto-loaded when editing UI files."
+tokens: 2498
+alwaysApply: false
+applyWhenPaths:
+  - "**/*.tsx"
+  - "**/*.jsx"
+  - "**/*.ts"
+  - "**/*.css"
+  - "**/*.scss"
+  - "**/*.html"
+  - "**/*.vue"
+  - "**/tailwind.config.*"
+  - "**/*.tokens.*"
+---
+
+# Color & Contrast
+
+## Principles (always apply)
+
+1. **Use OKLCH, not HSL.** OKLCH is perceptually uniform — equal steps
+   in lightness *look* equal, which HSL does not deliver. Modern browsers
+   all support `oklch()`; there is no reason to ship HSL in new code.
+2. **Reduce chroma at the extremes of lightness.** High chroma at 90%+
+   lightness or below 15% lightness reads as garish or muddy. A light
+   blue at 85% lightness wants ~0.08 chroma, not the 0.15 of your base
+   color. Similarly for deep shades — a near-black surface wants
+   ~0.02 chroma, not 0.15.
+3. **Tint your neutrals toward the brand hue.** Even a chroma of
+   0.005–0.01 is perceptible and creates subconscious cohesion between
+   brand color and UI surfaces. Pure neutrals feel disconnected.
+4. **60-30-10 is about visual weight, not pixel count.** 60% neutrals
+   and surfaces, 30% secondary text and borders, 10% accent. The accent
+   works *because* it is rare; overuse destroys its power.
+5. **No pure black or pure white.** `#000` and `#fff` never appear in
+   nature. Always tint. A "near-black" surface at `oklch(15% 0.01 260)`
+   is categorically different from `#000` even though the difference is
+   subtle on first glance.
+
+## Theme selection — by USE context
+
+Theme (light vs dark) is DERIVED from the audience and physical viewing
+context, not picked from a default. Read the brief and ask: when is this
+product used, by whom, in what physical setting?
+
+| Product | Theme | Reasoning |
+|---------|-------|-----------|
+| Perp DEX consumed during fast trading sessions | Dark | Reduces eye strain over long sessions; trading rooms often dim. |
+| Hospital portal consumed by anxious patients on phones late at night | Light | Bright environment perception = trust/safety; dark feels ominous in healthcare. |
+| Children's reading app | Light | Parents view dark interfaces as "less safe for kids"; content needs to feel open. |
+| Vintage motorcycle forum (users in their garage at 9pm) | Dark | Matches the physical environment and enthusiast subculture. |
+| Observability dashboard for SREs in dark rooms | Dark | Physical environment match; graph contrast against dark is clearer. |
+| Wedding planning checklist on Sunday morning | Light | Bright/optimistic mood; physical environment bright. |
+| Music player for headphone listening at night | Dark | Cinematic; physical environment dark. |
+| Food magazine homepage browsed over coffee | Light | Food imagery reads as more appetising on light surfaces. |
+
+**Do not default to light "to play it safe." Do not default to dark "to
+look cool."** Both defaults are the lazy reflex. The correct theme is
+the one the actual user wants in their actual context.
+
+If neither dark nor light is obviously right, ship **light with a
+high-quality dark mode**. (Not the other way around — light-first
+designs tend to port to dark cleanly; dark-first designs often have
+contrast issues in their light port.)
+
+## Building the palette
+
+### Step 1 — Pick the brand hue first
+
+Every other decision follows from one anchor color. This is usually the
+brand's actual hue (existing logo, product identity). If truly
+greenfield, pick based on the three-word brief from
+`typography-guidelines.md`:
+
+- "warm, mechanical, opinionated" → oklch hue 30–60 (orange/brown)
+- "calm, clinical, careful" → oklch hue 200–240 (cool blue-green)
+- "expensive, quiet, precise" → oklch hue 20–40 with very low chroma
+- "fast, dense, unimpressed" → oklch hue 120–160 with moderate chroma
+  (mint/green) or a desaturated near-grey
+
+### Step 2 — Build neutrals tinted toward the brand hue
+
+```css
+--neutral-0:  oklch(98% 0.005 <hue>);   /* page */
+--neutral-10: oklch(94% 0.008 <hue>);   /* subtle surface */
+--neutral-20: oklch(88% 0.010 <hue>);   /* hairline border */
+--neutral-40: oklch(68% 0.012 <hue>);   /* placeholder / muted icon */
+--neutral-60: oklch(50% 0.015 <hue>);   /* secondary text */
+--neutral-80: oklch(30% 0.018 <hue>);   /* body text */
+--neutral-95: oklch(15% 0.010 <hue>);   /* max-contrast text / deep surface */
+```
+
+Note: chroma INCREASES slightly into the middle of the scale and
+DECREASES at both extremes. This matches perception.
+
+### Step 3 — Accent scale with reduced chroma at extremes
+
+```css
+--accent-50:  oklch(95% 0.05 <hue>);
+--accent-300: oklch(78% 0.12 <hue>);
+--accent-500: oklch(60% 0.18 <hue>);   /* base brand color */
+--accent-700: oklch(42% 0.14 <hue>);
+--accent-900: oklch(22% 0.08 <hue>);
+```
+
+Compare chromas: `0.05 → 0.12 → 0.18 → 0.14 → 0.08`. The peak is in the
+middle, not at either end. A 500 color at chroma 0.18 would be
+overbearing at 900 lightness.
+
+### Step 4 — Status colors, but treat them as system, not brand
+
+Success, warning, error, info — these should NOT be your brand color
+with a hue shift. They should be their own mini-palettes. An e-commerce
+brand at hue 40 (orange) cannot use its accent 500 as a warning color —
+there is no differentiation between brand and warning.
+
+Use hue 140 (green) for success, hue 60–80 for warning, hue 25 (red-orange)
+for error, hue 250 (blue) for info. Apply the same lightness/chroma
+scaling as the accent scale.
+
+## Contrast and accessibility
+
+- **Metric selection is deterministic — no judgment call.** WCAG AA is
+  the hard floor in every project: ≥ 4.5:1 for body text, ≥ 3:1 for
+  large text (18px+ or 14px+ bold). Additionally check APCA targets
+  (Lc ≥ 60 body, Lc ≥ 45 large — APCA correlates better with
+  readability) ONLY when the project already ships APCA tooling
+  (search `package.json` and lockfile for "apca"). No APCA tooling
+  found → check WCAG only; do not guess Lc values.
+- **Do NOT use gray text on colored backgrounds.** Gray on a colored
+  surface reads as washed out. Instead, use a shade of the background
+  color — for an accent-tinted card, the body text should be a deep
+  shade of the same hue, not neutral gray.
+- **Borders:** a 1px border at `neutral-20` on a `neutral-0` background
+  is the right starting point. If you need more separation, prefer a
+  slight shadow over a heavier border.
+- **Focus rings:** 2px minimum, contrast ≥3:1 against both the element
+  and the background. Don't rely on default browser rings; they hide on
+  colored surfaces.
+
+## Modern CSS color tools
+
+All supported in every modern browser — use them in new code.
+
+```css
+/* Perceptually uniform lightness scale */
+--surface: oklch(from var(--brand) 98% c h);
+
+/* Mix between brand and neutral for hover states */
+--brand-hover: color-mix(in oklch, var(--brand) 92%, black);
+
+/* Auto light/dark */
+color: light-dark(var(--neutral-80), var(--neutral-0));
+background: light-dark(var(--neutral-0), var(--neutral-95));
+```
+
+## Color rules of execution
+
+**DO:**
+- Use `oklch()` everywhere. HSL in new code is tech debt.
+- Tint your neutrals toward the brand hue. Check by viewing them beside
+  pure gray — if they don't look different, increase chroma by 0.002.
+- Use `color-mix()` for hover/pressed states instead of hand-picked shades.
+- Use `light-dark()` for theme-aware colors; it is simpler than dual
+  CSS variable sets.
+- Pick a theme based on use context; document the reasoning in one line
+  at the top of the palette file.
+
+**DO NOT:**
+- Use HSL for new palettes. (OK for small legacy patches, not for new
+  systems.)
+- Use pure `#000` / `#fff` / `rgb(0,0,0)` anywhere.
+- Use gray text on a colored background. Tint the text.
+- Ship the AI palette: cyan-on-dark, purple-to-blue gradient text,
+  neon accents on a black page.
+- Use gradient text for impact. Solid colors for text; see
+  `ui-anti-patterns.md` for the strict definition.
+- Default to dark mode with glowing accents "because it looks cool."
+- Default to light mode "to play it safe."
+- Use the same accent color for brand and for system colors (success,
+  warning, error).
+
+## Validation procedure (before shipping a palette)
+
+Pick the branch with one test: can you render CSS and view the result
+this session (browser, Playwright, screenshot tooling)? Yes → Branch A.
+No, or unsure → Branch B. Never claim a render or simulator run that
+did not happen.
+
+**Branch A — rendering available:**
+
+1. Render the full neutral scale beside `#808080`. If any step looks
+   identical to pure gray, increase its chroma by 0.002.
+2. Render accent-500 on neutral-0 and on neutral-95, and compute its
+   WCAG contrast against both. Below 3:1 on either surface → adjust
+   accent-500 lightness until both pass.
+3. Run the palette through a deuteranopia / protanopia simulator
+   (e.g., Sim Daltonism, Stark). If status colors collapse onto each
+   other, re-hue them.
+4. Check text on every background used — minimum 4.5:1 for body,
+   3:1 for large.
+
+**Branch B — no rendering (the normal editing session).** Validate
+numerically from the token values:
+
+1. Read every neutral token: chroma ≥ 0.005 and one consistent hue
+   angle across the scale. Any step at chroma 0 → retint it (add
+   0.002 minimum).
+2. Compute the WCAG ratio for every text-on-background pair with a
+   Bash `python3`/`node` one-liner: linearize each sRGB channel
+   (c/12.92 if c ≤ 0.03928, else ((c+0.055)/1.055)^2.4); relative
+   luminance L = 0.2126R + 0.7152G + 0.0722B; ratio =
+   (L_lighter + 0.05) / (L_darker + 0.05). Concrete hex/rgb pairs give
+   an exact ratio; an oklch value or unresolved `var()` chain you
+   cannot convert → estimate from the lightness difference and label
+   the number "estimated".
+3. Status colors: no simulator ran, so hue alone must not carry
+   meaning — every status indicator pairs color with an icon or text
+   label, or adjacent status colors differ by ≥ 15 lightness points.
+4. Report each check as VERIFIED (with the computed numbers) or
+   NOT RUN — in this branch the render and simulator checks are always
+   NOT RUN; say so explicitly. An estimated (not exactly computed)
+   value caps that check's confidence at MEDIUM — the same rule
+   `ui-color-reviewer` applies to contrast findings.
+
+---
+
+Attribution: adapted from Impeccable's `reference/color-and-contrast.md`
+(Apache-2.0). See `../NOTICE.md`.