Remediation Flow

How file remediation works, with a focus on images and alt text.

Overview

Remediation takes existing HTML (or content fetched from a URL) and fixes accessibility issues to meet WCAG 2.1 AA. The system supports three input modes:

Single HTML file — POST /api/remediate/html
Batch HTML files — POST /api/remediate/batch (up to 50 files, returns ZIP)
URL scan — POST /api/remediate/url (fetches a URL, discovers linked files, audits and remediates)

Step-by-Step Flow

1. Pre-Audit (URL mode only)

For URL remediation, the system runs a WCAG audit on the fetched HTML before any changes. If the file already passes (zero violations), it is marked “No Issues” and skipped. Only files that fail the audit proceed to remediation.

2. Image Alt Text Generation

The first remediation step scans the HTML for <img> tags that need alt text.

An image is flagged as needing alt text when:

The alt attribute is completely missing
The alt attribute is empty (alt="")
The alt text is a generic placeholder: "image", "picture", "img1", etc.

For each flagged image, the system:

Checks if the image is a base64 data URL (inline). If so, extracts the base64 data directly.
If the image is an external URL (http://...), fetches it and converts to base64.
Sends the image data to a vision AI model with this prompt:

Describe this image for a screen reader user. Be concise but informative. Include what the image shows, any visible text, and the purpose or context if apparent. Keep the description under 125 characters if possible. Do not start with “Image of” or “Picture of”.
Replaces the original alt attribute (or adds one) with the AI-generated description.

Supported vision models (configurable per request):

Model	Provider	Default
`gemini-flash`	Google Gemini 1.5 Flash	Yes
`gpt-4o-mini`	OpenAI	No
`claude-haiku`	Anthropic Claude 3 Haiku	No
`claude-sonnet`	Anthropic Claude Sonnet	No

If the image cannot be fetched or the AI call fails, the image is skipped silently and the original alt (or lack thereof) is preserved.

3. Static Accessibility Fixes

After image remediation, the system applies structural fixes:

Fix	What it does
Language attribute	Adds `lang="en"` to `<html>` if missing
Heading hierarchy	Fixes skipped heading levels (e.g., h1 → h4 becomes h1 → h2)
Main landmark	Wraps body content in `<main>` if no `<main>` element exists
Table headers	Adds `scope="col"` to `<th>` elements missing a scope
Link names	Adds `aria-label` to image-only links using the image’s alt text
Skip navigation	Adds a skip-to-content link after `<body>` if missing

Each fix can be toggled on/off via the request options (fixHeadings, fixLandmarks, fixTables, fixLinks, fixForms).

4. Post-Audit

After all fixes are applied, the system runs the WCAG validator on the remediated HTML. The result includes:

Violations — issues that cause the audit to fail (e.g., missing alt attribute entirely)
Warnings — issues flagged for review but that don’t fail the audit (e.g., empty alt text, missing h1)

A file passes the audit when it has zero violations.

5. Output

The response includes:

The remediated HTML
Count of images remediated
List of fixes applied
WCAG audit result (pass/fail, violations, warnings)
Processing time

For URL mode, the output also includes a downloadable ZIP containing:

Remediated HTML files (root level)
Original HTML files (original/ directory)
Discovered CSS/JS assets
A standalone wcag-report.html with before/after audit details

Images and Alt Text: What Counts as a Violation vs. Warning

Condition	Classification	Fails Audit?
`<img>` with no `alt` attribute at all	Violation (critical)	Yes
`<img alt="">` (empty alt)	Warning	No
`<img alt="image">` or similar placeholder	Treated as needing remediation	N/A (gets replaced by AI)

Current Limitation

Images with alt="" are treated as warnings, not violations. Per WCAG, alt="" is valid for decorative images. The system currently cannot distinguish decorative images from content images, so it flags these as warnings for manual review rather than failing the audit.

During remediation, images with empty or placeholder alt text do get sent to the vision model for alt text generation. So even though alt="" doesn’t fail the audit, the remediator will still attempt to generate a description for it.

Architecture

┌─────────────┐     ┌──────────────────┐     ┌─────────────────┐
│  Frontend    │────▶│  /api/remediate/* │────▶│  html-remediator │
│  (Upload or  │     │  (Hono route)     │     │                  │
│   URL scan)  │     └──────────────────┘     │  1. Extract imgs │
└─────────────┘                               │  2. Vision AI    │
                                              │  3. Static fixes │
                                              │  4. WCAG audit   │
                                              └─────────────────┘

Key files:

workers/api/src/routes/remediate.ts — API endpoints
workers/api/src/services/html-remediator.ts — Core remediation logic + alt text generation
workers/api/src/services/wcag-validator.ts — Full WCAG 2.1 AA validator (26 rules)