APCA Gap Remediation — Requirement Specification
| Field | Value |
|---|---|
| Priority | P3 |
| Category | Validation |
| Effort | Medium |
| Status | Not started |
Objective
Close the 400 APCA (WCAG 3.0 draft) L^c contrast gaps catalogued in docs/data/apca-gaps.json by adjusting palette colors to meet WCAG 3.0 draft thresholds.
Current State
APCA 0.0.98G L^c scoring is implemented in scripts/validate-contrast.js with a soft gate: WCAG 2.1 AAA (7:1) remains the hard build gate, while APCA gaps are tracked but do not fail the build. All 420 WCAG AAA tests pass (100%).
Gap Breakdown
| Category | Threshold | Count |
|---|---|---|
| Body text | |L^c| < 75 | 293 |
| Fine text | |L^c| < 90 | 77 |
| Non-text UI | |L^c| < 60 | 30 |
| Total | 400 |
Gaps are concentrated in night themes (dark-bg/light-text polarity, where APCA scores are naturally lower than WCAG ratios for the same pairs).
Requirements
- Palette audit across all 20 themes (10 light + 10 night).
- Adjust token colors to meet APCA L^c thresholds without breaking WCAG AAA (7:1) compliance.
- Design review required — changing palette colors modifies the visual identity of themes across all 20 variants.
- Regenerate all downstream artifacts after palette changes:
- Theme JSON files (
pnpm run build) - Design tokens (
pnpm run tokens) - Terminal schemes (included in
pnpm run build) - Gallery (
pnpm run gallery) - Validation report (
pnpm run validate) - APCA gap catalogue (re-generated by validation)
- Theme JSON files (
Implementation Notes
- APCA L^c thresholds: body text ≥ 75, fine text ≥ 90, non-text UI ≥ 60.
- Night themes are the primary challenge — dark backgrounds with light text produce lower APCA scores than the equivalent WCAG ratios.
- Consider whether some gaps are acceptable (e.g. decorative tokens that don’t carry critical information).
- The gap catalogue is machine-readable at
docs/data/apca-gaps.json.
Dependencies
- Design review (visual identity impact across 20 themes)
- All downstream regeneration (tokens, terminals, gallery, validation)