---
name: ada-compliance-agent
title: ADA Compliance Agent
short_description: Deterministic WCAG 2.1 AA scanner and source-code fixer for static sites. Finds and fixes alt text, headings, labels, contrast, landmarks, links, and tables with .bak backups. Zero paid APIs.
description: Autonomous ADA/WCAG 2.1 AA compliance agent. Scans static HTML/CSS for accessibility violations, writes source-code fixes with .bak backups, and renders a dark-themed audit report. Zero paid API keys.
primary_category: Developer Tools
additional_categories: ["Productivity", "Marketing"]
tags: ["ada", "wcag", "accessibility", "a11y", "compliance", "static-sites", "html"]
support_email: hotchows@gmail.com
privacy_policy: https://hotchows.com/privacy-policy/
execution_mode: run_online
execution_time_minutes: 2
llm_model: frontier-default
---

# ADA Compliance Agent

Deterministic WCAG 2.1 AA scanner + fixer for static sites. Parses HTML with
BeautifulSoup and CSS with tinycss2, flags violations with rule IDs and line
numbers, optionally writes source-code fixes (each file backed up to `.bak`
before any change), then renders a dark-themed HTML audit report.

Zero paid API keys. No browser engine, no cloud vision service — rules are
deterministic and offline.

## When to use

Trigger this skill when asked to:

- Audit a static site (or directory of HTML files) for ADA/WCAG 2.1 AA issues
- Find missing alt text, broken heading order, unlabeled forms
- Check color contrast ratios in CSS against AA thresholds
- Fix accessibility violations directly in source code (with backups)
- Generate an accessibility compliance report for stakeholders

## Inputs

- `--site-dir` (required): directory containing `.html` files to audit
- `--fix` (optional): write fixes into the source files (backs up each to `.bak` first)
- `--css` (optional): also audit linked stylesheets found in the site dir
- `--output-json` / `--output-html`: audit result paths

## Usage examples

```bash
# Scan only
python scripts/audit.py --site-dir ./public --output-json audit.json

# Scan + fix + report
python scripts/audit.py --site-dir ./public --fix --output-json audit.json
python scripts/report.py --input audit.json --output-html audit_report.html
```

## Rules implemented (WCAG 2.1 AA subset)

| Rule ID | Check | WCAG |
|---|---|---|
| IMG-ALT | `img` missing/empty `alt` | 1.1.1 |
| H-ORDER | heading levels skip (h2→h4) | 1.3.1 |
| H-MISSING | no `h1` in page | 1.3.1 |
| FORM-LABEL | input/select/textarea without label/aria-label | 1.3.1 / 4.1.2 |
| A-LINK-TEXT | anchor without discernible text | 2.4.4 |
| BTN-NAME | button without accessible name | 4.1.2 |
| LANDMARK | no `main`/`nav`/`header` landmark | 1.3.1 / 2.4.1 |
| LANG | `html` missing `lang` attribute | 3.1.1 |
| TITLE | document missing `<title>` | 2.4.2 |
| TABLE-HEADERS | data table without `th` | 1.3.1 |
| CSS-CONTRAST | foreground/background pair below 4.5:1 (3:1 large) | 1.4.3 |

Contrast is computed only for pairs the scanner can resolve deterministically:
CSS classes/IDs with explicit color+background on the same selector, plus
inline `style="color:...;background:..."`. `currentColor` and inherited-only
cases are reported as UNRESOLVED rather than guessed.

## Fix behavior (`--fix`)

- Adds `alt=""` (decorative) only when the image has no text alternative AND
  has no `role="presentation"`; flagged as LOW-CONFIDENCE — human review advised
- Inserts a missing `lang="en"` and empty `<title>` — HIGH confidence
- Promotes skipped heading levels to the expected level — HIGH confidence
- Adds placeholder `aria-label` on nameless links/buttons derived from
  href/text context — MEDIUM confidence
- Never touches JS, never rewrites structure beyond the rule above
- Every modified file is first copied to `<name>.bak` (one generation)

## Outputs

1. `audit.json`: full violation list (rule, severity, file, line, snippet, fix confidence)
2. `audit_report.html`: standalone dark-themed report (Hotchows branding):
   summary stats, rule-by-rule breakdown, file-by-file listing, fix log

## Execution constraints

- Zero paid APIs; BeautifulSoup + tinycss2 + Jinja2 only
- Read-only by default; mutation only with explicit `--fix`
- Contrast math follows WCAG relative-luminance formula; unresolved pairs are
  listed, not estimated
- Fixer is conservative: LOW/MEDIUM confidence fixes are marked for human review

## Exit codes

- 0 audit completed (violations may exist), 1 runtime failure, 2 bad arguments