Accessibility Agent (A11y Agent)

An intelligent accessibility checking and auto-fixing agent for modern web and .NET applications following WCAG 2.2 Level AA compliance standards.

🎯 Features

• Multi-Language Support: VB.NET, React, JavaScript, CSS, HTML

• WCAG 2.2 Compliance: Full coverage of the four POUR principles:

  • Perceivable: Color contrast, alt text, keyboard accessibility
  • Operable: Keyboard navigation, focus management, touch targets
  • Understandable: Semantic HTML, form labels, error handling
  • Robust: Valid code, ARIA implementation, assistive technology support

• Smart Detection & Fixing:

  • Automated accessibility issue detection
  • Intelligent code transformation for remediation
  • Context-aware fixes preserving code functionality
  • Batch processing across entire repositories

• Comprehensive Testing:

  • Static code analysis
  • Color contrast validation
  • Form accessibility checks
  • Semantic HTML verification
  • ARIA attribute validation

📋 Project Structure

accessibility-agent/
├── Core/
│   ├── AccessibilityAnalyzer.cs      # Main analysis engine
│   ├── IssueDetector.cs              # WCAG issue detection
│   ├── CodeTransformer.cs            # Intelligent code fixing
│   └── AccessibilityRules.cs         # WCAG 2.2 rules definitions
├── Detectors/
│   ├── HtmlAccessibilityDetector.cs  # HTML semantic analysis
│   ├── ReactAccessibilityDetector.cs # React-specific checks
│   ├── CssAccessibilityDetector.cs   # CSS contrast & visual checks
│   ├── JavaScriptDetector.cs         # JS keyboard & event handling
│   └── VBNetDetector.cs              # VB.NET ASP.NET analysis
├── Fixers/
│   ├── HtmlAccessibilityFixer.cs     # HTML semantic fixes
│   ├── ReactAccessibilityFixer.cs    # React prop additions
│   ├── CssAccessibilityFixer.cs      # CSS contrast improvements
│   ├── JavaScriptFixer.cs            # JS keyboard handler implementation
│   └── VBNetFixer.cs                 # VB.NET control fixes
├── Models/
│   ├── AccessibilityIssue.cs         # Issue representation
│   ├── CodeLocation.cs               # File location tracking
│   └── FixSuggestion.cs              # Fix recommendation
├── Utilities/
│   ├── ColorContrastChecker.cs       # WCAG contrast validation
│   ├── WcagRuleEngine.cs             # Rule evaluation
│   ├── Logger.cs                     # Issue logging
│   └── FileProcessor.cs              # Multi-file handling
├── Tests/
│   └── AccessibilityTests.cs         # Unit tests
├── Program.cs                        # CLI entry point
├── appsettings.json                  # Configuration
└── wcag-rules.json                   # WCAG 2.2 rules database

🚀 Quick Start

Installation

# Clone the repository
git clone https://github.com/yourusername/accessibility-agent.git
cd accessibility-agent

# Build the project
dotnet build

# Run the accessibility checker
dotnet run -- --scan ./path/to/project --mode analyze

Analyze Your Codebase

# Scan for accessibility issues
dotnet run -- --scan ./src --mode analyze --report

# Generate detailed report
dotnet run -- --scan ./src --report-format json --output report.json

# Check specific file types
dotnet run -- --scan ./src --file-types "*.cs,*.jsx,*.css" --mode analyze

Auto-Fix Accessibility Issues

# Fix issues automatically
dotnet run -- --scan ./src --mode fix --backup

# Fix specific issue types
dotnet run -- --scan ./src --fix-types "semantic-html,aria-labels,color-contrast"

# Review changes before applying
dotnet run -- --scan ./src --mode analyze --suggest-fixes

📊 Supported WCAG 2.2 Checks

Perceivable (1.x)

• 1.1 Text Alternatives - Alt text for images, captions for video
• 1.4 Distinguishable - Color contrast (4.5:1 normal, 3:1 large)
• 1.3 Adaptable - Semantic HTML, proper heading hierarchy

Operable (2.x)

• 2.1 Keyboard Accessible - All functionality available via keyboard
• 2.4 Navigable - Skip links, focus management, visible focus indicators
• 2.4.3 Focus Order - Logical tab order, focus trapping in modals
• 2.5 Input Modalities - Touch targets (44x44px minimum), gesture alternatives

Understandable (3.x)

• 3.1 Readable - Lang attribute, clear language
• 3.2 Predictable - Consistent navigation, no unexpected changes
• 3.3 Input Assistance - Form labels, error messages, required field indicators

Robust (4.x)

• 4.1 Compatible - Valid HTML, proper ARIA roles/states
• 4.1.2 Name, Role, Value - Accessible names for all components
• 4.1.3 Status Messages - Proper ARIA live regions for updates

🛠️ CLI Commands

# Analyze repository
dotnet run -- --scan <path> --mode analyze [--report]

# Fix issues
dotnet run -- --scan <path> --mode fix [--backup] [--dry-run]

# Generate report
dotnet run -- --scan <path> --report-format [json|html|csv] --output <file>

# Check specific rules
dotnet run -- --scan <path> --rules "1.4.3,2.1.1,3.3.1"

# Exclude files/patterns
dotnet run -- --scan <path> --exclude "node_modules,*.min.js,vendor"

# View detailed issue info
dotnet run -- --scan <path> --verbose

📝 Configuration

Edit appsettings.json to customize behavior:

{
  "AccessibilitySettings": {
    "WcagLevel": "AA",
    "MinimumContrastRatio": 4.5,
    "MinimumTouchTargetSize": 44,
    "CheckReactProps": true,
    "CheckSemanticHtml": true,
    "CheckFormLabels": true,
    "CheckColorContrast": true,
    "CheckKeyboardNav": true,
    "AutoFixEnabled": true,
    "BackupFiles": true,
    "MaxFileSizeKb": 1000
  },
  "FilePatterns": {
    "HtmlFiles": "*.html,*.cshtml,*.razor",
    "ReactFiles": "*.jsx,*.tsx",
    "CssFiles": "*.css,*.scss,*.less",
    "JavaScriptFiles": "*.js,*.ts",
    "VBNetFiles": "*.vb"
  },
  "ExcludePatterns": [
    "node_modules",
    "dist",
    "build",
    "bin",
    "obj",
    "*.min.js",
    "vendor"
  ]
}

🔍 Example Issues Detected

✗ No Alt Text on Images

<!-- Before (ISSUE) -->
<img src="logo.png" />

<!-- After (FIXED) -->
<img src="logo.png" alt="Company logo" />

✗ Missing Form Labels

// Before (ISSUE)
<input type="email" placeholder="Enter email" />

// After (FIXED)
<label htmlFor="email-input">Email Address</label>
<input id="email-input" type="email" placeholder="Enter email" />

✗ Low Color Contrast

/* Before (ISSUE) - 3:1 contrast */
color: #999999;
background: #ffffff;

/* After (FIXED) - 4.5:1 contrast */
color: #555555;
background: #ffffff;

✗ Missing Keyboard Support

// Before (ISSUE)
<div onClick={handleClick}>Submit</div>

// After (FIXED)
<button onClick={handleClick} onKeyDown={(e) => e.key === 'Enter' && handleClick()}>
  Submit
</button>

✗ Missing ARIA Labels

<!-- Before (ISSUE) -->
<button id="menu-btn">≡</button>

<!-- After (FIXED) -->
<button id="menu-btn" aria-label="Toggle navigation menu" aria-expanded="false">
  ≡
</button>

📈 Report Generation

Generate comprehensive accessibility reports:

# JSON Report
dotnet run -- --scan ./src --report-format json --output a11y-report.json

# HTML Report with visual dashboard
dotnet run -- --scan ./src --report-format html --output a11y-report.html

# CSV for spreadsheet analysis
dotnet run -- --scan ./src --report-format csv --output a11y-issues.csv

Report Contents

• Total issues found by severity (Critical, Major, Minor)
• Issues grouped by WCAG criterion
• File-by-file breakdown
• Suggested fixes with examples
• Compliance percentage

🧪 Testing

Run the test suite:

dotnet test

🤝 Contributing

This project uses WCAG 2.2 specifications and the Accessibility Handbook. Contributions are welcome!

📚 Resources

• WCAG 2.2 Guidelines
• WebAIM Contrast Checker
• React Accessibility
• MDN Accessibility
• A11y Project

📄 License

MIT License - See LICENSE file for details

🙏 Acknowledgments

Built following the Accessibility Handbook principles and WCAG 2.2 standards to ensure inclusive digital experiences for everyone.

---

Last Updated: January 28, 2026 Version: 1.0.0 Status: Active Development