---
name: accessibility-contrast-audit
description: "Walk a page's color tokens and flag every pair that fails WCAG AA, with a suggested minimal adjustment to pass."
title: Accessibility Contrast Audit
category: design-media
difficulty: beginner
author: admin
icon: 🔆
input: mixed
output: markdown
phase: post
domain: design
tags: wcag-compliance,contrast-ratio,accessibility-audit,color-tokens,css-parsing,design-tokens,luminance-calculation,color-correction,automated-qa,a11y,hex-adjustment,hsl-space
best_for:
  - design system validation
  - accessibility compliance audits
  - automated edge-case detection
  - token-driven component libraries
  - WCAG AA/AAA remediation
---

## Description

Input: a CSS file, a design-tokens JSON, or a rendered URL. Output: a list of every color pair used together (text on background) with their contrast ratio and WCAG AA / AAA pass/fail status. For each failure, proposes the smallest hex delta that would pass while staying close to the original hue.

## Why it works

Manual contrast audits miss combinations because they only check the pairs that show up on-screen at the moment of review. Walking the tokens exhaustively catches the edge-case pages (error states, hover states) that a human QA rarely visits.

## How it works

1. Parse tokens + all text/background combinations declared in CSS. 2. Compute WCAG contrast ratio for each pair (relative luminance formula). 3. Flag failures with their required minimum (4.5 for normal text, 3.0 for large text). 4. For each failure, search nearby hex values in HSL space for the minimum lightness adjustment that brings the ratio above threshold. 5. Emit a markdown report with a fix-suggestion column and a ready-to-paste CSS patch at the bottom.