# agent hallucinated color palette that fails contrast check - how to fix it

## TL;DR

Verify every agent-proposed color against the contrast ratio before accepting: compute the ratio for each text/background pair in the patch and reject palettes that fail. Agents invent pretty palettes that miss 4.5 to 1 constantly. One line of why: color harmony and contrast ratio are unrelated, and models optimize for the former.

## The error, verbatim

```text
RemediationAgentWarning: proposed palette fails contrast
    palette: text #8a9ba8 on #f4f6f8 (ratio 2.8, needs 4.5)
    for: body text, 14px

```

## Fix it step by step

### Step 1: Reproduce the bad palette

```bash
node agent/remediate.js --rule color-contrast | rg -i 'palette|ratio' | head -5
```

Expected: The agent proposes a palette that fails the ratio.

### Step 2: Compute the ratios

```bash
python3 -c "def lum(h): c=[int(h[i+1:i+3],16)/255 for i in (0,2,4)]; c=[((v+0.055)/1.055)**2.4 for v in c]; return 0.2126*c[0]+0.7152*c[1]+0.0722*c[2]
def r(a,b):
 x,y=lum(a),lum(b); return round((max(x,y)+0.05)/(min(x,y)+0.05),2)
print(r('#8a9ba8','#f4f6f8'))"
```

Expected: Prints 2.8, confirming the failure objectively.

### Step 3: Add the ratio gate

```bash
rg -n 'palette|contrast' agent/remediate.js | head -10
```

Expected: Add: compute ratios for every proposed pair, reject below 4.5 for normal text, feed the numbers back.

### Step 4: Re-run remediation

```bash
node agent/remediate.js --rule color-contrast | tail -4
```

Expected: Agent iterates palettes until the ratios pass, then lands the patch.

### Step 5: Add a regression probe

```bash
node agent/run-audit.js --smoke | tail -3
```

Expected: Smoke run passes; schedule it so the breakdown is caught if it ever regresses.

## When to use this skill

- You run an agent that scans UIs for accessibility and it hits this breakdown
- The agent's scan loop stalls, crashes, or loops on this exact failure
- You are hardening an audit agent's error handling for production scans

## When NOT to use this skill

- A human runs the scan manually and it works, this is agent-harness failure handling
- The scan completes and only reports violations, use the rule-specific skills

## Compatibility

Remediation agent with a contrast ratio function in the harness. The gate is arithmetic, not model judgment. Pin the tool version in the lockfile so scans stay reproducible across machines.

## Variant phrasings

### agent palette fails contrast

Same hallucination, same ratio gate.

### remediation colors fail wcag

Practitioner phrasing.

### the breakdown hits other routes too

Agent failure modes are systemic; apply the hardening to every route the agent covers, not just the one that failed.

## Why it happens

Color contrast is arithmetic on relative luminance, but language models propose colors by aesthetic association, so their palettes routinely land at 2.5 to 3.5 to 1 for body text. Without a verification gate the agent ships a pretty, failing palette and reports success. The gate computes the ratio for every proposed pair and rejects failures with the numbers as feedback, which lets the model iterate toward passing values. Large text (3 to 1) vs normal text (4.5 to 1) must be distinguished in the gate. Agent breakdowns are systemic: the same failure mode will hit every route, page, or run the agent touches. Harden the harness once (timeouts, loop detection, verification gates) instead of patching per page, and keep breakdown telemetry separate from violation counts.

## Edge cases

- Gate on 4.5 for normal text and 3.0 for large text, the model needs to know which applies per element.
- Brand colors that cannot change need a different fix (heavier weight, larger size, scrim), not a new palette.
- Dark mode palettes need the same gate, models hallucinate low-contrast dark themes just as often.
- Log breakdowns separately from violations in agent telemetry; mixing them hides whether the agent itself is getting more reliable.

## Provenance

Resolved from the public thread: https://vectle.com/posts/pst_uvWnH3rRDAgsF9CvS6qbAQ