Access4U
An accessibility scanner that uses axe-core and AI to detect WCAG violations, explain them in plain language, and generate corrected code—with visual diffs and before/after previews.
Images must have alt text
Color contrast ratio 2.1:1
Form input missing label
AI generating fixes...
+ <img src="hero.jpg" alt="Team meeting">
Overview
The Problem
Developers publish inaccessible web content unknowingly. Existing audit tools flag WCAG violations but don't explain what they mean or how to fix them — leaving developers to interpret cryptic error codes on their own.
The Solution
Run axe-core in a hidden iframe (client-side, no server needed), then send violations to Gemini AI with generateObject() to get plain-language explanations and corrected code — displayed as visual diffs with before/after previews.
My Role
Sole developer — designed the iframe audit architecture, built the AI analysis pipeline with structured output, created the contrast engine, visual diff system, PDF/JSON export, and a Chrome browser extension.
Key Deliverables
Accessibility scanner with AI explanations and code fixes, visual before/after diffs, contrast ratio matrix, PDF and JSON report export, URL scanning with screenshots, and a Chrome extension for importing audit data.
Architecture & Design Decisions
Every choice was driven by one goal: make accessibility auditing fast, understandable, and actionable — without requiring a server or storing any data.
Key Technical Decisions
Client-Side axe-core
Running axe-core in a hidden iframe (srcdoc, same-origin) means no server-side Puppeteer or headless browser needed — the entire audit happens in the user's browser, keeping the app stateless and fast.
generateObject() Over streamText()
AI fixes need to map back to specific violation IDs. generateObject() returns structured JSON that can be programmatically matched to each violation, while streamText() would require fragile parsing.
Hidden + Visible Iframes
A hidden iframe runs the audit (same-origin for axe-core access), while a visible iframe shows the preview. When AI fixes are available, a split before/after view lets users compare both versions.
No Database, No Auth
Access4U is a stateless tool — paste HTML, get results. No user accounts or stored data means zero privacy concerns and simpler architecture. Every scan is ephemeral.
AI Provider Abstraction
An abstraction layer (ai-provider.ts) lets the app switch between Gemini and Spike.land with a single env var. New providers can be added without touching the core scanning logic.
Engineering Principles
Scan First, Explain Second
Run the deterministic axe-core audit before involving AI — never let the model guess at violations
Show, Don't Tell
Visual diffs and before/after previews communicate fixes better than text descriptions alone
Stay Stateless
No database, no auth, no stored data — every scan is self-contained and ephemeral
Structured Output
Use generateObject() with Zod schemas so AI responses are always valid, parseable JSON
How It Works
Four steps from input to actionable fixes — the entire pipeline runs client-side except for the AI analysis call.
Input
Paste raw HTML or enter a URL. The URL scanner fetches the page content and captures a screenshot for reference.
Scan
axe-core runs in a hidden iframe (srcdoc, same-origin) and returns every WCAG violation with severity, affected elements, and rule IDs.
Analyze
Violations are sent to Gemini AI via generateObject(). The model returns plain-language explanations and corrected code for each violation.
Output
Results appear as visual diffs (before/after code), a live preview with split view, contrast matrix, and exportable PDF/JSON reports.
Development Process
Accessibility Engine
Built the iframe-based axe-core runner. HTML is loaded into a hidden iframe via srcdoc (same-origin), axe-core runs against the DOM, and violations are extracted with severity, selectors, and rule metadata.
AI Pipeline
Integrated Gemini via AI SDK's generateObject() with Zod schemas. Each violation gets a plain-language explanation and corrected code. Built an abstraction layer so providers (Gemini, Spike.land) are swappable via env var.
Visual Diff & Preview
Added react-diff-viewer-continued for side-by-side code diffs. Built a split iframe preview (before/after) so users can visually confirm fixes. Created the colour extractor and contrast ratio calculator.
Export & Extension
Added PDF export via jsPDF and JSON download for CI integration. Built a Chrome browser extension that lets users import audit data directly from any page they're browsing.
Key Technical Features
Seven capabilities that make accessibility auditing fast, understandable, and actionable.
Client-Side Auditing
axe-core runs entirely in the browser via a hidden iframe — no server-side Puppeteer or headless browser needed. Keeps the app stateless and fast.
AI-Powered Explanations
Gemini AI explains each violation in plain language and generates corrected code using generateObject() for structured, reliable output.
Visual Code Diffs
react-diff-viewer-continued shows side-by-side before/after diffs for every fix, so developers can see exactly what changed and why.
Live Before/After Preview
Split iframe view renders the original and fixed HTML side by side, letting users visually confirm that fixes work correctly.
Contrast Matrix
Extracts colour pairs from rendered HTML and calculates WCAG contrast ratios, flagging combinations that fail AA or AAA thresholds.
PDF & JSON Export
Generate downloadable reports via jsPDF for stakeholders or JSON files for CI/CD pipeline integration.
Chrome Extension
A browser extension that lets users import audit data from any page directly into Access4U for analysis and AI-powered fixes.
Tech Stack & Architecture
Four layers working together—from the accessibility engine to the export pipeline.
Frontend
- •Next.js 16 App Router
- •React 19
- •Tailwind CSS v4
- •react-diff-viewer-continued
Accessibility Engine
- •axe-core (client-side)
- •Hidden iframe (srcdoc)
- •Colour extractor
- •Contrast ratio calculator
AI Layer
- •Google Gemini
- •AI SDK (generateObject)
- •Zod structured output
- •Provider abstraction layer
Tools & Export
- •jsPDF for PDF reports
- •JSON export for CI/CD
- •Chrome browser extension
- •URL scanner + screenshots
Learnings & Outcomes
What I Learned
- Hidden iframes with srcdoc give you same-origin access for DOM auditing without needing a server — a powerful pattern for client-side tools
- generateObject() with Zod schemas turns unreliable AI text into structured, typed JSON you can program against
- Showing visual diffs alongside plain-language explanations makes accessibility fixes understandable to any developer, not just WCAG experts
- Building an AI provider abstraction early paid off when adding Spike.land — the core logic didn't change at all
- Contrast ratio calculations require extracting computed styles from rendered HTML, not just parsing CSS — the colour extractor handles inheritance and defaults
- Browser extensions need careful message passing design — the import flow from extension to web app taught me about cross-context communication
Skills Demonstrated
Try Access4U
Scan any HTML for accessibility violations and get AI-powered fixes.