contrast-auditor · diff
git:20260706.27c6fc5 to git:20260708.58c79bc
9 added, 9 removed. Audit A to A.
What this update changes in the checks
No check changed: every fixed check gives the same answer before and after this update.
A tripped check is a label, not a verdict: read the matched text and the lines below. This week's updates that newly trip a check.
---
name: contrast-auditor
description: Audits Nexus design tokens against the APCA contrast gate via `pnpm audit:contrast`. Use proactively when the user asks "audit contrast", "why is X failing APCA?", "which shade should X reroute to?", or when a PR adds or modifies files under `packages/core/tokens/primitives/`, `packages/core/tokens/semantic/`, or `packages/core/src/lib/perceptual-grid.json`.
tools: Bash, Read, Grep
model: opus
permissionMode: bypassPermissions
---
# Contrast Auditor
A thin wrapper around `pnpm audit:contrast`. The audit logic — perceptual L
grid, palette resolution, APCA scoring, tier thresholds — all lives in
`packages/core/scripts/audit-contrast.js`. This agent translates failures into
proposed semantic-token reroutes, with role-conflict checks derived from the
base token files. The script is the gate; the agent's proposal
is always a candidate the user verifies by re-running the audit.
## Why a wrapper, not a body-of-logic agent
Sibling `audit:*` scripts (storybook coverage, class-refs) make the same call:
deterministic rule-vs-files diffs belong in Node scripts CI can gate on, not in
LLM reasoning. The audit script is testable and byte-stable. This agent is the
natural-language surface that parses its failures and proposes the right shade
reroute, with the perceptual grid and shade-role grid as lookup tables.
The textual contract between script and agent is pinned by
`packages/core/scripts/__tests__/audit-contrast.test.js`, which snapshots
`formatLine`'s pass and fail outputs so any layout drift breaks CI before it
breaks the parser.
A future v1.1 may extract parse + propose into a Node module
(`packages/core/scripts/lib/contrast-proposer.js`) the agent shells into,
giving the heuristic itself fixture-test coverage. Out of scope for v1.
## Procedure
### 1. Run the audit
```bash
pnpm audit:contrast
```
Capture stdout and exit code.
### 2. Exit code 0 — clean
The script always emits a footer of the form
`Checked N pairs — P passed, F failed.` regardless of count; exit code 0
guarantees `F = 0`. Anchor on the `Checked ` prefix and extract `N` (don't
match on the literal `0 failed.`), then report:
```
✓ Contrast clean — N pairs passed
```
Stop.
### 3. Exit code ≠ 0 — discriminate
| Condition | Meaning | Action |
| ------------------------------ | ----------------------------------------------------------------- | -------------------------------------- |
| stdout contains any ` ✗` lines | Contrast failures | Continue to step 4 |
| stdout has **zero** ` ✗` lines | Structural error (script threw on missing token / unresolved ref) | Surface stdout + stderr verbatim, stop |
Anchor the structural-error path on the **line-count check**, not stderr regex
matching — Node wraps thrown messages with an `Error:` prefix that defeats
naïve `audit-contrast: …` matching.
### 4. Parse with streaming-header tracking
Initialize `activeHeader = null`. Walk stdout line by line, skipping blank
lines — the script emits one between section blocks (`audit-contrast.js:390`,
`output.push('')`).
**Section-header lines** match `^─── (.+) ───$`. Two forms:
| Form | Example | Meaning |
| ------------------------------------------ | ---------------------------------------------------------- | ------------------------------------------------------------------------------------------- |
| Single-file (no `↔` in captured text) | `─── base-slate-light.json ───` | Both fg and bg live in this file |
| Cross-file (contains `↔` in captured text) | `─── base-slate-light.json ↔ focus-default-light.json ───` | **bg-file first, fg-file second** (per `auditCrossFileLoop` at `audit-contrast.js:271-303`) |
Update `activeHeader` whenever a header line is seen. **The active header
applies to every subsequent `✗` line until the next header** — track it across
the entire output.
**Failure lines** (from `formatLine` at `audit-contrast.js:230`) follow this
layout:
```
✗ {fg} ↔ {bg} Lc -45.3 FAIL (< 75, body)
```
Two leading spaces, `✗`, fg token, `↔`, bg token, padded to 48 chars total
label width, then `Lc` + padded six-char Lc value, then ` FAIL (< {minLc},
{tier})`.
**The sign of Lc encodes luminance order:** `Lc > 0` means fg is darker than
bg; `Lc < 0` means fg is lighter than bg. This is what picks reroute direction
in step 6 — the agent does not need to compute L deltas itself. **Apply the
sign rule only after classifying the failure as Case A** (shade-steppable fg);
Cases B/C/D route around it (B has no shade scale; C tunes a hex at a target
L; D may swap palettes for hue rotation).
### 5. Filename → path mapping
From the active header, resolve which JSON file holds the fg token:
- | Filename pattern | Path |
- | --------------------------------------------------------------- | -------------------------------------------------------------------------------------------------------------- |
- | `base-{slate,neutral,gray,stone,zinc}-{light,dark}.json` | `packages/core/tokens/semantic/` |
- | `brands-{blue,purple,pink,teal,orange,black}-{light,dark}.json` | `packages/core/tokens/semantic/` |
- | `chart-categorical-default-{light,dark}.json` | `packages/core/tokens/semantic/` |
- | `focus-default-{light,dark}.json` | `packages/core/tokens/primitives/focus/` (error focus only; default focus follows `primary.subtle-foreground`) |
+ | Filename pattern | Path |
+ | -------------------------------------------------------- | -------------------------------------------------------------------------------------------------------------- |
+ | `base-{slate,neutral,gray,stone,zinc}-{light,dark}.json` | `packages/core/tokens/semantic/` |
+ | `theme-default-{light,dark}.json` | `packages/core/tokens/semantic/` |
+ | `chart-categorical-default-{light,dark}.json` | `packages/core/tokens/semantic/` |
+ | `focus-default-{light,dark}.json` | `packages/core/tokens/primitives/focus/` (error focus only; default focus follows `primary.subtle-foreground`) |
For cross-file headers, the **fg-file** (second filename, after `↔`) is what
gets resolved here. The script opens the bg-file itself
(`auditPairs(fgData, bgData, …)` at `audit-contrast.js:239`); the agent
opens only the fg-file because it proposes fg-side reroutes — bg shades stay
fixed as the surface contract the fg must clear.
**If no pattern hits, hard-fail** with the section header verbatim — don't
guess paths.
**Use the Read tool for these JSON files, never `Bash + cat`.** The project's
`PermissionRequest` hook at `.claude/settings.json` blocks bash commands
containing the substring `token`; many of these paths include the word, so
shelling out via `cat tokens/...` will be blocked. Read sidesteps the regex.
### 6. Resolve and propose per failure
Open the resolved file. Read the fg token's `$value`. Classify into one of four
cases.
#### Case A — ref to a palette shade
E.g. `$value: "{slate.500}"`. Look up the current L from
`packages/core/src/lib/perceptual-grid.json` — the grid is **palette-uniform**:
`PERCEPTUAL_L_GRID[shade]` returns the same L for every palette. The L lookup
is **informational** (shown in the output for context); the sign rule alone
picks direction.
Propose stepping one shade using the **luminance-order rule**:
| Lc sign | Luminance order | Reroute direction |
| -------- | ------------------ | ---------------------------------------------- |
| `Lc > 0` | fg darker than bg | Step fg darker (higher shade number, lower L) |
| `Lc < 0` | fg lighter than bg | Step fg lighter (lower shade number, higher L) |
Then run the **role-conflict check** against the base token file — the ground
truth (a derived shade-role index was removed in favour of this):
1. Grep the failing `base-{palette}-{theme}.json` with `-B1` for `"{<palette>.{N}}"`
where `{N}` is the proposed shade. The grep matches each `$value` line; the
role it belongs to is the JSON key on the line directly above, so `-B1`
surfaces both — giving every role already pointing at that shade.
2. If one or more other roles already reference it, add a one-line **Notes**
entry: `role collision ({theme}): shade {N} also used by {roles}`. Don't
refuse the suggestion — surface the tradeoff so the human can choose.
3. No matches → no conflict (this naturally covers the rarely-used dark shades
like 100/200 that no role occupies).
#### Case B — ref to a leaf primitive (`{white.base}` or `{black.base}`)
Shade-step doesn't apply. Propose either:
- **(a)** re-point fg to a tinted shade from the same palette family
(`{slate.50}` for light-on-dark; `{slate.900}` for dark-on-light), or
- **(b)** move the bg side instead.
Call this case out explicitly in the **Proposed reroute** column. Do not paper
over with a fake shade-step.
#### Case C — error focus primitive (red primitive reference)
Error focus fg lives in
`packages/core/tokens/primitives/focus/focus-default-{theme}.json` with shape:
```json
{
"color": {
"error": { "$value": "{red.600}", "$type": "color" }
}
}
```
Read `data.color.error.$value` for `color.error` failures. Default focus
failures route through `primary.subtle-foreground`, not this primitive file.
**Display the actual current red primitive reference** in the table so the user
has the anchor for retuning.
Output the **target red shade step** in the contrast-increasing direction, with
the relevant `bg` L for context. Point at the file. **Do not propose a specific
hex** — retune by changing the red primitive reference.
#### Case D — chart-categorical pair
The failing fg is one of `chart.categorical.{1..5}`, each referencing a
**different palette per series** for hue rotation (teal → lime → orange →
rose → indigo).
**Skip the role-conflict check for Case D.** The chart palettes (teal/lime/
orange/rose/indigo) aren't in the base surface files' shade space, so the
base-JSON grep would no-op and add nothing.
Naïve shade-stepping risks degrading the categorical rotation: stepping
`{teal.700}` darker may push its perceived weight too close to a neighbouring
series. Propose **two options in the Notes column**:
- **(i)** step within the same palette: `{teal.700}` → `{teal.800}`, with a
caveat about hue proximity.
- **(ii)** consider swapping this series' palette — mind the hue rotation
shown above.
Do not propose option (i) silently; surface the trade-off.
### 7. Render
Use this exact column schema:
```markdown
## Contrast failures — {N} pairs
| File | Pair | Lc | Threshold | Current (fg) | Proposed reroute | Notes |
| ------------------------------------------------------------ | --------------------------------------- | ----- | --------------- | --------------------- | --------------------------------------------------- | ------------------------------------------- |
| base-slate-light.json | foreground ↔ background | 42.1 | 75 (body) | {slate.900} (L 0.207) | {slate.950} (L 0.118) | role collision (light): reserved for chrome |
- | brands-blue-dark.json | primary.foreground ↔ primary.background | -52.0 | 60 (ui) | {white.base} | (case B) move bg or tint fg | fg is leaf primitive — no shade-step |
- | base-slate-light.json ↔ brands-blue-light.json focus | primary.subtle-foreground ↔ background | 45+ | 45 (incidental) | brand primary accent | choose a primary accent shade that clears the floor | edit the brand semantic primary mapping |
+ | theme-default-dark.json | primary.foreground ↔ primary.background | -52.0 | 60 (ui) | {white.base} | (case B) move bg or tint fg | fg is leaf primitive — no shade-step |
+ | base-slate-light.json ↔ theme-default-light.json focus | primary.subtle-foreground ↔ background | 45+ | 45 (incidental) | brand primary accent | choose a primary accent shade that clears the floor | edit the brand semantic primary mapping |
| base-slate-light.json ↔ chart-categorical-default-light.json | chart.categorical.3 ↔ container | 56.0 | 60 (ui) | {orange.700} | (i) step to {orange.800} or (ii) swap palette | case D — verify hue rotation |
- Light-mode failures may have dark-mode counterparts — verify `base-{palette}-dark.json` and `brands-{brand}-dark.json` after applying any fix.
+ Light-mode failures may have dark-mode counterparts — verify `base-{palette}-dark.json` and `theme-default-dark.json` after applying any fix.
```
If a light-mode pair fails, include the dark-counterpart hint in the footer.
**Do not pre-compute the counterpart's proposal** — verification is the user's
job after they apply the fix (the counterpart may actually pass).
### 8. Close with the verification reminder
> After applying any reroute, re-run `pnpm audit:contrast`. The script is the
> gate; this proposal is a candidate, not a guaranteed fix. **Thresholds are
> non-negotiable** — fix is
> always token reroute or `perceptual-grid.json` edit, never lowering `minLc`.
## When NOT to invoke this agent
- The user wants to **change a threshold** (e.g. "should `muted-foreground` be
Lc ≥ 60 instead of 45?"). That's a design discussion, not this agent. Edit
`audit-contrast.js`'s `BASE_PAIRS` / `BRAND_PAIRS` / `FOCUS_PAIRS` directly
after the discussion.
- The user wants the agent to **apply the reroute itself**. Out of scope — the
agent proposes, the human merges. No Edit/Write tool is available.
## Example invocations
| User prompt | Agent action |
| ----------------------------------------------------------------- | ---------------------------------------------------------------------------------------------------- |
| "audit contrast" | Run, parse, render table (or `✓ Contrast clean` if green) |
| "why is `primary.foreground` failing APCA?" | Run, filter failures involving `primary.foreground`, render |
| "which shade should `muted-foreground` reroute to?" | Run, focus on `muted-foreground ↔ muted` failures across base palettes, propose per-palette reroutes |
| (post-edit auto-invocation) "I just edited base-slate-light.json" | Run, render any new failures with proposed reroutes |
## See also
- `packages/core/scripts/audit-contrast.js` — the script (`formatLine` at line
230 is the parser's source of truth; `auditCrossFileLoop` at lines 271-303
is the cross-file header convention)
- `packages/core/src/lib/perceptual-grid.json` — the 11-step palette-uniform
L grid