---
name: review-ui-color-contrast
description: Audit, plan, implement, and verify accessible UI color and contrast systems in web applications. Use when Codex is asked to make an interface darker or more readable, review WCAG color contrast, improve muted text or control boundaries, redesign semantic color tokens, validate light/dark or user-selectable themes, fix focus/status/chart colors, add contrast regression tests, or persist reusable color-system guidance for future UI work.
---

# UI Color and Contrast Review

## Start With Scope

Confirm the authorized outcome from the request:

- For an audit, inspect and report evidence without editing.
- For a plan, persist a phased plan only when requested.
- For implementation, update the color system, components, tests, and generated assets, then verify locally.
- Do not deploy, publish, commit, or push unless separately authorized.

Read repository instructions and `references/contrast-review-playbook.md` before auditing or changing an app.

## Core Workflow

1. Discover the stack, design-system sources, generated assets, build commands, test commands, themes, chart libraries, and representative routes.
2. Inventory rendered foreground/background pairs by semantic role and state. Include text, controls, focus, status, navigation, tables, overlays, charts, disabled states, and every supported theme.
3. Measure current values and identify failures or narrow margins. Evaluate actual composited colors rather than judging isolated swatches.
4. Propose the smallest role-based change that preserves brand direction and hierarchy. Do not apply a global brightness filter or darken every divider and surface.
5. If implementation is authorized, centralize reusable roles, replace hard-coded component/chart colors, add non-color cues, and update all supported states and themes.
6. Add a permanent contrast gate in the app's native test/build system. Cover each approved pair; for multi-theme systems, run the same role/surface matrix against every theme.
7. Rebuild committed/generated assets and run focused plus broader tests required by the repository.
8. Review representative pages in a browser at desktop and narrow widths. Check keyboard focus, hover/pressed/selected states, status meaning, charts, console errors, clipping, and horizontal overflow.
9. Persist the durable roles, thresholds, change workflow, and guardrail command in the app's design-system or contributor instructions when requested or when implementation is meant to govern future UI work.

## Contrast Contract

Use WCAG 2.2 AA as the default conformance gate unless the repository specifies a stronger standard:

- Normal text: `4.5:1`.
- Large text: `3:1`.
- Meaningful non-text controls, boundaries, focus indicators, icons, and chart marks: `3:1` against adjacent colors.
- Target more than the exact minimum for frequently used muted text and critical controls when practical.
- Never use hue alone to communicate status, selection, validation, or chart meaning.
- Keep browser forced-colors behavior enabled unless an exception has an accessible fallback.

Treat disabled controls separately, but ensure they remain identifiable and do not contain the only presentation of essential information.

## Implementation Rules

- Name tokens by role: canvas, surface, text, muted text, decorative border, control border, focus, accent, accent contrast, status surface/foreground/border, and chart series.
- Separate decorative borders from boundaries required to identify interactive controls.
- Separate light status surfaces from strong status foregrounds and solid fills.
- Give hover/pressed and focus states deliberate colors; opacity alone is not enough.
- For multiple themes, define complete role sets. Do not derive every role mechanically from five brand swatches and assume it remains accessible.
- Use the active surface token in gradients and `color-mix()` expressions instead of hard-coded white when dark themes exist.
- Read chart colors from shared theme tokens, add accessible labels or summaries, and use an outline, label, weight, pattern, or another non-hue selection cue.
- Prefer shared components or semantic utility classes over per-page color literals.
- Preserve the app's layout and behavior unless the request also authorizes interaction or responsive changes.

## Automated Checking

Prefer the repository's native language and test framework for the permanent guardrail. Integrate the check into an existing build or CI command so it cannot be skipped accidentally.

Use `scripts/contrast_check.py` to evaluate candidate pairs or a portable JSON matrix before adapting the assertions to the app:

```bash
python3 scripts/contrast_check.py --foreground '#66574D' --background '#FFFCFA' --minimum 4.5
python3 scripts/contrast_check.py path/to/contrast-matrix.json
```

The script accepts opaque hex, `rgb(...)`, and space-separated RGB triplets. Inspect rendered/composited browser colors before checking translucent values.

## Validation and Handoff

Report:

- the semantic roles and surfaces changed;
- measured ratios and thresholds;
- components, states, themes, and representative pages reviewed;
- automated checks and browser checks completed;
- generated assets changed;
- known layout or accessibility issues outside the authorized scope;
- deployment, commit, or release actions explicitly not taken.

Do not claim complete accessibility from contrast checks alone. Contrast review does not replace semantic HTML, accessible names, keyboard behavior, reflow, reduced-motion, screen-reader, or user testing.

## Resource Routing

- Read `references/contrast-review-playbook.md` for discovery, audit matrices, multi-theme handling, implementation patterns, browser verification, and failure modes.
- Run `scripts/contrast_check.py` for deterministic candidate-palette or matrix calculations. Use `-` as the matrix path to read JSON from standard input.