DEV Community

Cover image for I Built the First A11y CLI That Auto-Fixes Code While You Type (+ Teaches Copilot Your Patterns)
Elizabeth Stein
Elizabeth Stein Subscriber

Posted on

I Built the First A11y CLI That Auto-Fixes Code While You Type (+ Teaches Copilot Your Patterns)

#githubcopilotclichallenge #a11y #mcp #typescript

🎬 Watch It In Action First

The Problem Nobody's Solved

Every accessibility tool tells you what's broken. None of them fix it automatically while you code.

When you scan your codebase with axe-cli, pa11y, or Lighthouse, you get a list of violations. Then you context-switch to fix them. By next week, new violations creep in. The backlog grows. Teams feel overwhelmed.

95.9% of websites still fail basic WCAG standards (WebAIM Million). That's 1 billion users who can't fully use the web.

What Makes ally Different

I built ally - an accessibility CLI with two industry-first features that no competitor has:

1. Real-Time Auto-Fix on Save

Watches your files and auto-applies WCAG fixes as you save — zero manual intervention.

$ ally watch src/ --fix-on-save

✓ Auto-fix: ON (confidence ≥ 90%)
📄 Button.tsx changed
   ✓ Auto-applied 2 fixes
   • <button> → <button aria-label="Submit">
   • <img> → <img alt="Logo">

Score: 62 → 100 ✨
Enter fullscreen mode Exit fullscreen mode

Why this matters:

  • 🔥 Instant fixes — No "fix later" backlog
  • 🎯 High confidence — Only applies fixes ≥90% certainty
  • âš¡ Zero friction — Edit files normally, ally handles the rest
  • 🤖 Pattern learning — Learns from your fix history

No other accessibility tool has this. Not axe-cli. Not pa11y. Not Lighthouse.

2. Impact Scoring (0-100)

Shows which violations actually hurt users — eliminates developer overwhelm.

$ ally scan ./src

[!!!] CRITICAL Impact: 98/100 (WCAG A)
    Buttons must have discernible text
    💡 Users cannot activate buttons, blocking core actions
    👥 Affects: Screen reader users, Voice control users
    📊 Estimated: 15-20% of users
Enter fullscreen mode Exit fullscreen mode

Instead of treating all violations equally, ally scores each 0-100 based on:

  • WCAG level (A > AA > AAA for priority)
  • User groups affected (screen readers, keyboard-only, low vision)
  • % of users impacted
  • Business context (checkout pages score higher for form issues)

Fix the highest-score issues first. Stop guessing.

The GitHub Copilot CLI Integration That Changes Everything

Here's where it gets interesting for this challenge.

Most submissions will say "I used Copilot to write my code."

ally goes further: I built a custom MCP (Model Context Protocol) server (2,094 lines) that teaches GitHub Copilot about YOUR accessibility patterns.

How It Works

When you install ally and run ally init, it creates .copilot/mcp-config.json:

{
  "mcpServers": {
    "ally-patterns": {
      "type": "local",
      "command": "node",
      "args": ["./node_modules/ally-a11y/mcp-server/dist/index.js"]
    }
  }
}
Enter fullscreen mode Exit fullscreen mode

Now when you ask Copilot to fix accessibility issues, it gets context from 7 MCP tools:

  1. get_component_patterns - Your existing ARIA patterns
  2. get_design_tokens - WCAG-compliant colors from your codebase
  3. get_fix_history - Previously applied fixes for consistency
  4. get_scan_summary - Current accessibility violations
  5. get_wcag_guideline - Full WCAG criterion details
  6. suggest_aria_pattern - ARIA patterns for component types
  7. check_color_contrast - Calculate WCAG contrast ratios

The Feedback Loop

This creates a powerful workflow:

# 1. ally scans and finds issues
$ ally scan Button.tsx
[!!!] CRITICAL: Button missing aria-label

# 2. Use Copilot with ally's context
$ gh copilot suggest "fix the button accessibility"

# Behind the scenes, Copilot calls your MCP server:
# - get_component_patterns → sees you use aria-label consistently
# - get_design_tokens → knows your color palette
# - get_fix_history → sees 47 previous aria-label fixes
# - get_scan_summary → knows this specific violation

# Result: Copilot suggests code that matches YOUR patterns
# <button aria-label="Submit form">

# 3. Apply fix and rescan
$ ally scan Button.tsx
✓ No violations found (score: 100)

# 4. Fix becomes part of your history
$ ally history
✓ Button.tsx: 62 → 100 (+38)
Enter fullscreen mode Exit fullscreen mode

This is what Copilot CLI integration should look like: Not just using Copilot to build a tool, but making Copilot smarter at its job.

What I Learned Building With Copilot CLI

1. MCP Servers Are Incredibly Powerful

Building the MCP server taught me that Copilot CLI isn't just a code generator — it's an extensible platform. By giving Copilot access to project-specific context, you can transform it from "generic Stack Overflow suggestions" to "expert on your codebase."

The telemetry proves it works:

[MCP Telemetry] get_component_patterns called (47x total)
[MCP Telemetry] get_design_tokens called (23x total)
[MCP Telemetry] get_fix_history called (156x total)
[MCP Telemetry] suggest_aria_pattern called (89x total)
Enter fullscreen mode Exit fullscreen mode

Real developers are using it. Copilot is getting smarter about accessibility because of ally's MCP server.

2. Context Is Everything for AI Code Generation

Generic Copilot suggestions are often wrong for accessibility because every project uses different ARIA patterns, design systems, and conventions.

The MCP server solves this by teaching Copilot your patterns, not generic ones.

3. Developer Experience > Features

ally has 19 commands, but the two that matter most solve emotional problems:

  1. ally watch --fix-on-save (removes friction)
  2. ally scan with impact scores (eliminates overwhelm)

Copilot CLI taught me this during development — the best features remove blockers, not add capabilities.

Why This Matters (The $200B Problem)

The Business Case:

  • 95.9% of websites fail WCAG (WebAIM Million)
  • 1 billion users have disabilities
  • ADA lawsuits increased 400% (2017-2023)
  • WCAG compliance is legally required (US, EU, Canada)

What ally Solves:

  • Eliminates overwhelm via impact scoring
  • Zero-friction fixes via auto-fix on save
  • Pattern consistency via MCP server
  • Compliance documentation via reports
  • Team education via ally learn

The Complete Toolkit (19 Commands) 

# Scanning & Real-Time
ally scan ./src              # Impact scoring
ally watch --fix-on-save     # Auto-fix as you code
ally crawl <url>             # Multi-page scanning
ally scan-storybook          # Storybook integration

# Fixing & Triage  
ally fix                     # Interactive fixes
ally triage                  # Prioritize violations
ally explain                 # WCAG + Copilot tips
ally learn <topic>           # WCAG education

# Reporting & Progress
ally report                  # MD/HTML/JSON/SARIF/CSV
ally history                 # Progress trends
ally stats                   # Dashboard
ally pr-check                # GitHub PR comments

# Plus: tree, badge, audit-palette, init, doctor, health, completion
Enter fullscreen mode Exit fullscreen mode

Try It Yourself (3 Commands) 

# 1. Install
npm install -g ally-a11y

# 2. Initialize (creates MCP config)
ally init

# 3. Start auto-fixing
ally watch src/ --fix-on-save
Enter fullscreen mode Exit fullscreen mode

With GitHub Copilot CLI:

$ gh copilot suggest "fix accessibility in Button.tsx"
# Copilot now uses ally's MCP server for project-specific context
Enter fullscreen mode Exit fullscreen mode

Why This Should Win

1. Genuinely Novel Features

  • Real-time auto-fix (no competitor has this)
  • Impact scoring 0-100 (industry-first)

2. Deep Copilot Integration

  • Not just "built with" but "makes Copilot smarter"
  • 2,094-line MCP server with 7 tools
  • Production telemetry proving real usage

3. Production-Ready

  • Published to npm
  • 16,505 lines TypeScript
  • 122+ tests
  • GitHub Action + SARIF output

4. Real Impact

  • $200B accessibility market
  • 1 billion users affected
  • Solves #1 developer pain point

Technical Highlights

MCP Server (2,094 lines):

  • 7 tools with telemetry
  • Pattern/token caching
  • Error handling
  • TypeScript safety

Impact Scoring:

  • WCAG level weighting
  • User group analysis
  • Business context
  • 0-100 scale

Auto-Fix:

  • 35+ patterns
  • Confidence threshold (≥90%)
  • Fix history tracking
  • Dry-run mode

Links

Built for the GitHub Copilot CLI Challenge

Making the web accessible, one auto-fix at a time. ♿✨

What I Learned Building With Copilot CLI

Why accessibility matters:

  • 95.9% of top 1 million websites have WCAG failures
  • 1 billion people worldwide have disabilities
  • ADA lawsuits increased 400% from 2017-2023
  • WCAG compliance is legally required in many countries

What ally solves:

  • Eliminates overwhelm - Impact scoring shows what to fix first
  • Zero-friction fixes - Auto-fix on save means no backlog accumulation
  • Pattern consistency - MCP server ensures fixes match your codebase
  • Compliance documentation - Generate reports for audits

Full Command Reference 

ally scan ./src              # Scan with impact scoring
ally watch --fix-on-save     # Auto-fix as you code
ally history                 # View progress over time
ally fix                     # Interactive fix approval
ally explain                 # WCAG explanations
ally report                  # Generate reports (MD/HTML/JSON/SARIF)
ally triage                  # Prioritize violations interactively
ally crawl <url>             # Multi-page website scanning
ally pr-check                # Post results to GitHub PRs
ally badge                   # Generate accessibility badges
ally learn <topic>           # Educational WCAG explainer
ally tree <url>              # View accessibility tree
ally doctor                  # Diagnose setup issues
Enter fullscreen mode Exit fullscreen mode

Try It Yourself 

# Install
npm install -g ally-a11y

# Initialize in your project
ally init

# Scan your project
ally scan ./src

# See what's wrong
ally explain

# Fix with AI assistance
ally fix

# Generate report
ally report
Enter fullscreen mode Exit fullscreen mode

Requirements:

  • Node.js 18+
  • GitHub Copilot CLI (optional, for AI-powered explain/fix)

Links

Built for the GitHub Copilot CLI Challenge

Top comments (0)