Kiro-A11y-Agent

An autonomous AI accessibility agent that scans live DOMs, detects WCAG barriers, and auto-generates ready-to-apply code fixes.

Comment

Inspiration

Over 1 billion people worldwide live with some form of disability—whether visual, auditory, motor, or cognitive. Yet, over 96% of the world's top websites still fail basic WCAG (Web Content Accessibility Guidelines) compliance.

Traditional static linters only catch superficial syntax errors (like a missing alt attribute), completely missing the real context: Does alt="image123.jpg" actually help a blind user using a screen reader? Can a motor-impaired user navigate a dynamic modal using only the Tab key? Meanwhile, pasting isolated code snippets into generic AI chatbots doesn't scale across full applications and completely misses the rendered DOM and the browser's native Accessibility Tree.

We were inspired to bridge this gap by building Kiro-A11y-Agent: an autonomous AI accessibility engineer that operates directly in the developer's workflow, seeing the web the way assistive technologies do, and fixing barriers directly in the source code.

What it does

Kiro-A11y-Agent (kiro-a11y) is an autonomous CLI tool and AI agent that audits live URLs or local frontend projects and generates ready-to-apply code patches. It focuses on four critical accessibility pillars:

  1. Visual Contrast & Readability: Extracts computed foreground/background styles and combines deterministic luminance math with Multimodal Vision AI to catch unreadable text over complex backgrounds or gradients.
  2. Silent Interactive Elements: Scans the browser's live Accessibility Tree to identify buttons, links, and form inputs that lack semantic names (aria-label, aria-labelledby, or visible text) and are invisible to screen readers like NVDA or VoiceOver.
  3. Contextual Media Semantics: Identifies missing or unhelpful alt descriptions on images and SVGs, using Vision AI to generate accurate, context-aware descriptions.
  4. Keyboard Focus & Navigation Traps: Detects broken tabindex orders ($\text{tabindex} > 0$) and focus traps that prevent motor-impaired users from navigating without a mouse.

Instead of just outputting a massive PDF of complaints, Kiro-A11y-Agent generates a clean Markdown executive report and auto-patches the HTML/JSX source code with WCAG 2.2 AA compliant fixes.

How we built it

We built Kiro-A11y-Agent from the ground up using Kiro's spec-driven agentic workflow alongside a modular Python architecture:

  • Kiro Spec Mode (requirements.md, design.md, tasks.md): Before writing a single line of code, we used Kiro to structure our product requirements, define our modular architecture (scanner, analyzer, fixer, and cli), and break the implementation down into verifiable engineering tasks.
  • Kiro Steering & Agent Hooks: We configured .kiro/steering/wcag-rules.md to enforce WCAG 2.2 AA standards across all generated code, and set up Kiro Agent Hooks to trigger accessibility checks automatically whenever frontend files are saved.
  • Headless Browser Engine (Playwright): Built an asynchronous scanner in Python that renders JavaScript-heavy applications, captures full-page screenshots, extracts the Chromium accessibility.snapshot() tree, and runs injected DOM filters.
  • Mathematical + Multimodal AI Engine: For contrast validation, we combined AI vision with the official WCAG relative luminance ratio formula:

$$CR = \frac{L_1 + 0.05}{L_2 + 0.05}$$

where $L_1$ is the relative luminance of the lighter color and $L_2$ is the relative luminance of the darker color, ensuring strict compliance thresholds ($CR \ge 4.5:1$ for normal text and $CR \ge 3.0:1$ for large text).

  • Flexible LLM Routing & Rich CLI: Built core/analyzer.py using a flexible OpenAI-compatible SDK wrapper (supporting Claude, OpenAI, Grok, or OpenRouter models via .env) and crafted an interactive terminal UI with Typer and Rich.

Challenges we ran into

  • Token Bloat on Complex DOMs: Sending an entire raw HTML page and a full Accessibility Tree to an LLM quickly exceeds context limits and increases latency. We solved this by writing an injected JavaScript pre-processor inside Playwright that surgically extracts only suspect nodes across our 4 pillars before invoking the AI.
  • Dynamic Hydration Timing: Modern SPAs (React/Next.js) often render empty shells initially. We had to fine-tune our Playwright scanner with wait_until="networkidle" and custom DOM readiness checks so the agent audits the actual interactive interface rather than a loading spinner.
  • Safe Code Patching: Ensuring the AI fixer replaces only the broken accessibility attributes without breaking existing layout styles or event handlers required strict prompt engineering and structured JSON schema outputs.

Accomplishments that we're proud of

  • Turning accessibility auditing from a manual, frustrating post-deployment chore into an automated "shift-left" developer tool that fixes code in seconds.
  • Leveraging Kiro's spec-driven development to go from concept to a working multi-module CLI tool with built-in test suites (tests/broken_page.html) smoothly and systematically.
  • Combining deterministic browser inspection (Accessibility Tree + luminance math) with Multimodal AI so the tool doesn't hallucinate false positives.

What we learned

  • How Assistive Tech Really Works: Building the scanner deepened our understanding of how browsers construct the Accessibility Tree (role, name, state) and why visual appearance alone is never enough for screen reader compatibility.
  • Spec-Driven AI Engineering: Collaborating with Kiro taught us how much faster and cleaner development becomes when you align on specifications and architecture documents before generating implementation code.

What's next for Kiro-A11y-Agent

  • CI/CD GitHub Action Integration: Automatically run kiro-a11y on every Pull Request and suggest inline code commits when WCAG violations are introduced.
  • Simulated Screen Reader Audio Preview: Add a feature that synthesizes how a page sounds on NVDA/VoiceOver so developers can immediately experience their site from a blind user's perspective.
  • Multi-Page Autonomous Crawling: Expand the scanner to autonomously navigate user flows (like checkout funnels and login forms) across an entire domain.

Built With

Share this project:

Updates

Submission history