a11y-unit

AI-powered accessibility testing and auto-fixing toolkit for modern web development

🎯 Overview

a11y-unit is the world's first AI-powered accessibility testing toolkit that not only identifies accessibility issues but automatically fixes them. Built for React, Next.js, and modern web development workflows, it combines comprehensive scanning with intelligent auto-remediation powered by our secure cloud AI service.

🚀 Key Features

• 🤖 AI-Powered Auto-Fixing - Automatically generate and apply accessibility fixes using our secure cloud AI service
• 🔧 Intelligent Code Modification - Smart code transformations that preserve your existing logic and styling
• 🔍 Comprehensive Scanning - Test individual components, full applications, and live websites
• 🌐 Multi-Platform Support - Works with React, Next.js, HTML, and any web technology
• 🎯 Git Integration - Automatic branch creation and commit generation for fixes
• 📊 Multiple Output Formats - JSON, terminal reports, GitHub Actions integration
• 🚀 Production Ready - Comprehensive test suite, high coverage, zero lint errors
• 🛠 Developer-Friendly - Seamless integration into existing workflows
• 📦 Language Support - a11y-unit is primarily a Node.js/TypeScript package. Python SDK support is planned for a future release.

📦 Language Support

• ✅ Node.js/TypeScript - Primary package with full feature support
• ✅ Web API - RESTful API for language-agnostic integration
• ✅ Docker Images - Containerized deployment options

📊 Quality Metrics

• ✅ Comprehensive Test Suite - Extensive tests covering all functionality
• ✅ High Coverage - Strong test coverage across packages
• ✅ Zero Lint Errors - Strict code quality standards
• ✅ TypeScript - Full type safety throughout
• ✅ Production Ready - Battle-tested implementation

🚀 Quick Start

Installation

# Install globally
npm install -g a11y-unit

# Or use with npx
npx a11y-unit scan ./src/components

🤖 AI-Powered Auto-Fixing (Premium Feature)

# Scan and automatically fix accessibility issues (requires license key)
a11y-unit scan ./src/components --auto-fix

# Auto-fix with git integration (creates branch + commit)
a11y-unit scan ./src/components --auto-fix --auto-pr

# Scan a live website and auto-fix
a11y-unit scan-url https://your-website.com --auto-fix

Note: AI-powered auto-fixing requires a Premium or Team license. Get your license key →

Basic Usage

# Scan React components
a11y-unit scan ./src/components

# Scan a live website
a11y-unit scan-url https://your-website.com

# Output results as JSON
a11y-unit scan ./src --output json

# GitHub Actions output for CI/CD
a11y-unit scan ./src --output github-actions

# Scan with verbose details
a11y-unit scan-url https://your-website.com --verbose

🤖 AI-Powered Auto-Fixing (Premium Feature)

a11y-unit's revolutionary AI-powered auto-fixing feature uses our secure cloud infrastructure to automatically generate and apply accessibility fixes to your code. This goes beyond traditional linting by actually modifying your source code with intelligent, context-aware solutions.

⚡ How It Works

1. Scan & Detect - Identifies accessibility issues using axe-core
2. Secure Upload - Sends issue context and source code to our secure AI service
3. AI Analysis - Our cloud infrastructure processes fixes using OpenAI GPT models
4. Generate Fix - AI creates structured fix instructions (add attributes, modify styles, etc.)
5. Apply Changes - Automatically modifies your source code with the generated fixes
6. Git Integration - Optionally creates branches and commits for review

🔧 Supported Fix Types

• Add Attributes - Missing alt text, ARIA labels, roles, etc.
• Modify Styles - Color contrast improvements, focus indicators
• Add Elements - Skip links, landmark elements, headings
• Modify Content - Descriptive text, button labels, link text

🛠 Setup Requirements

Premium License Required: AI-powered auto-fixing is available to Premium and Team tier users.

• Free Tier: Basic accessibility scanning only
• Premium/Team: Full AI auto-fixing via our managed infrastructure

# Set your a11y-unit license key
export A11Y_UNIT_LICENSE_KEY="your-license-key-here"

# Or create a .env file
echo "A11Y_UNIT_LICENSE_KEY=your-license-key-here" > .env

Security: Your code is processed securely through our infrastructure. We use industry-standard encryption and do not store your source code.

Licensing

a11y-unit offers both free and premium tiers to suit different needs:

• Free Tier: Basic accessibility scanning (no AI auto-fixing)
• Premium Tier: Full AI-powered auto-fixing, unlimited fixes, JSON/HTML export, and CI integration
• Team Tier: All premium features plus team collaboration tools and priority support

Getting a License Key

1. Visit a11y-unit.dev to purchase a license
2. Choose your tier (Premium or Team)
3. Complete the checkout process
4. Your license key will be provided immediately
5. Set your license key as an environment variable:

export A11Y_UNIT_LICENSE_KEY="your-license-key-here"

Premium users benefit from our managed AI infrastructure with no additional API key setup required.

Note: You do not need to configure Supabase credentials. The Supabase integration is used internally to manage license validation and shared API keys. Simply provide your license key and the service handles the rest.

Lost Your License Key?

Visit a11y-unit.dev/lost-key to recover your license keys by email.

🔧 Troubleshooting

If you encounter issues with a11y-unit:

1. License Key Issues

   • Ensure your license key is correct and active
   • Check that A11Y_UNIT_LICENSE_KEY environment variable is properly set
   • Verify your license hasn't expired at a11y-unit.dev

2. AI Auto-Fixing Not Working

   • Confirm you have a Premium or Team license (Free tier doesn't include AI features)
   • Check your internet connection for secure communication with our AI service
   • Large files may take longer to process

3. Scanning Issues

   • Ensure your files are valid HTML/JSX/TSX
   • Check file permissions and accessibility
   • Verify the target directory exists

4. Installation Problems

   • Try reinstalling: npm uninstall -g a11y-unit && npm install -g a11y-unit
   • Check Node.js version compatibility (requires Node 16+)
   • Verify npm permissions for global installs

For additional help, please check our GitHub Issues or open a new issue.

💡 Example Auto-Fix Session

$ a11y-unit scan example.html --auto-fix

🔍 Scanning example.html...
✅ Found 3 accessibility issues

🤖 Generating AI fixes...
✅ Generated 3 fixes using gpt-3.5-turbo

🔧 Applying fixes...
✅ Added alt="User profile image" to <img> element
✅ Improved color contrast from #ccc to #1a365d
✅ Added aria-label="Close dialog" to button

📝 Summary: Fixed 3/3 issues successfully

🎯 Git Integration

Use --auto-pr to automatically create git branches and commits:

$ a11y-unit scan src/ --auto-fix --auto-pr

🔧 Applying fixes...
✅ Fixed 5 accessibility issues

🌿 Created branch: a11y-fixes-2024-07-22-15-30
📝 Committed changes: "Fix accessibility issues in 3 files"

💡 Next steps:
  git checkout a11y-fixes-2024-07-22-15-30
  git push origin a11y-fixes-2024-07-22-15-30
  # Create pull request for review

📋 Output Formats

a11y-unit supports three output formats to fit different use cases:

Terminal Output (Default)

Human-readable output with colors and formatting, perfect for development:

a11y-unit scan ./src/components
# Found 2 accessibility issues
#
# src/Button.jsx:
#   - color-contrast: Elements must have sufficient color contrast
#     Help: https://dequeuniversity.com/rules/axe/4.8/color-contrast
#   💡 AI Suggestion (high): Use a darker shade of blue (#1a365d) for better contrast
#
# src/Image.jsx:
#   - image-alt: Images must have alternate text
#     Help: https://dequeuniversity.com/rules/axe/4.8/image-alt
#   💡 AI Suggestion (high): Add descriptive alt text like "User profile photo"

JSON Output

Structured data perfect for programmatic use and integration:

a11y-unit scan ./src --output json

[
  {
    "file": "src/Button.jsx",
    "issues": [
      {
        "id": "color-contrast",
        "description": "Elements must have sufficient color contrast",
        "impact": "serious",
        "helpUrl": "https://dequeuniversity.com/rules/axe/4.8/color-contrast",
        "aiSuggestion": {
          "suggestion": "Use a darker shade of blue (#1a365d) for better contrast",
          "confidence": "high",
          "reasoning": "Current contrast ratio is 2.1:1, needs to be at least 4.5:1"
        }
      }
    ]
  }
]

GitHub Actions Output

CI/CD integration with automatic error annotations in pull requests:

a11y-unit scan ./src --output github-actions --ai

::error file=src/Button.jsx,line=1,col=1::color-contrast: Elements must have sufficient color contrast (AI Suggestion: Use a darker shade of blue (#1a365d) for better contrast)
::error file=src/Image.jsx,line=1,col=1::image-alt: Images must have alternate text (AI Suggestion: Add descriptive alt text like "User profile photo")

AI-Powered Suggestions

Enable intelligent accessibility recommendations with the --ai flag:

# Get AI suggestions for fixing issues
a11y-unit scan ./src --ai

# Combine with any output format
a11y-unit scan ./src --output json --ai
a11y-unit scan ./src --output github-actions --ai

🌐 Live Site Scanning Examples

Our live site scanning has been tested on real websites with excellent results:

Single URL Scanning

# Scan a single website
$ a11y-unit scan-url https://example.com

🔍 Scanning: https://example.com
📊 Compliance Score: 84/100
🚨 Total Issues: 3
   Critical: 0
   Serious: 1
   Moderate: 2
   Minor: 0

Detailed Issue Analysis

# Get detailed issue breakdown
$ a11y-unit scan-url https://example.com --verbose

🔍 Scanning: https://example.com
📊 Compliance Score: 84/100
🚨 Total Issues: 3
   Critical: 0
   Serious: 1
   Moderate: 2
   Minor: 0

📋 Issues found:
1. [SERIOUS] Ensures every HTML document has a lang attribute
   Help: <html> element must have a lang attribute
   More info: https://dequeuniversity.com/rules/axe/4.8/html-has-lang?application=axeAPI

2. [MODERATE] Ensures the document has a main landmark
   Help: Document should have one main landmark
   More info: https://dequeuniversity.com/rules/axe/4.8/landmark-one-main?application=axeAPI

3. [MODERATE] Ensures all page content is contained by landmarks
   Help: All page content should be contained by landmarks
   More info: https://dequeuniversity.com/rules/axe/4.8/region?application=axeAPI

Multi-URL Crawling

# Scan multiple URLs concurrently
$ a11y-unit scan-url https://w3.org https://httpbin.org

🕷️  Crawling 2 URLs...
📊 Overall Compliance Score: 89/100
🚨 Total Issues Across All Pages: 5
   Critical: 0
   Serious: 1
   Moderate: 4
   Minor: 0

📄 Per-page results:
1. ✅ https://w3.org - Score: 100/100 (0 issues)
2. ⚠️  https://httpbin.org - Score: 78/100 (5 issues)

JSON Output for CI/CD

# Perfect for automated pipelines
$ a11y-unit scan-url https://example.com --output json

{
  "url": "https://example.com",
  "pages": [
    {
      "url": "https://example.com",
      "issues": [
        {
          "id": "html-has-lang",
          "description": "Ensures every HTML document has a lang attribute",
          "help": "<html> element must have a lang attribute",
          "helpUrl": "https://dequeuniversity.com/rules/axe/4.8/html-has-lang",
          "impact": "serious",
          "nodes": [{
            "html": "<html>",
            "target": ["html"],
            "failureSummary": "Fix any of the following:\n  The <html> element does not have a lang attribute"
          }]
        }
      ],
      "issueCount": 3,
      "criticalIssues": 0,
      "seriousIssues": 1,
      "moderateIssues": 2,
      "minorIssues": 0
    }
  ],
  "summary": {
    "totalPages": 1,
    "totalIssues": 3,
    "criticalIssues": 0,
    "seriousIssues": 1,
    "moderateIssues": 2,
    "minorIssues": 0,
    "complianceScore": 84
  }
}

Real-World Test Results

| Website | Compliance Score | Issues Found | Notes | | --------------- | ---------------- | ------------ | ---------------------------------------- | | w3.org | 100/100 🏆 | 0 | Perfect accessibility (W3C standards) | | example.com | 84/100 | 3 | Missing lang attribute, no landmarks | | httpbin.org | 78/100 | 5 | Color contrast, heading structure issues | | github.com | N/A | CSP Error | Content Security Policy blocks injection |

🚀 CI/CD Integration

🚀 GitHub Actions Integration

a11y-unit supports GitHub Actions output format for integration with your CI/CD pipeline:

name: Accessibility Testing
on: [push, pull_request]
jobs:
  a11y-test:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v3
      - name: Install a11y-unit
        run: npm install -g a11y-unit
      - name: Run accessibility scan
        run: a11y-unit scan . --output github-actions

Note: This provides formatted output for GitHub Actions but requires manual workflow setup.

Error Annotations in PRs

When using --output github-actions, accessibility issues will automatically appear as annotations in your pull requests:

Integration with Other CI Systems

# Jenkins, GitLab CI, CircleCI, etc.
a11y-unit scan ./src --output json > accessibility-report.json

# Parse results and fail build if critical issues found
if [ $(jq '[.[].issues[] | select(.impact == "critical")] | length' accessibility-report.json) -gt 0 ]; then
  echo "Critical accessibility issues found!"
  exit 1
fi

🚀 CI/CD and Publishing

This project uses GitHub Actions for continuous integration and automated publishing to npm:

• CI Workflow: Runs tests, linting, and type checking on all pull requests and pushes to main/develop branches
• Publish Workflow: Automatically publishes to npm when a new GitHub release is created

To publish a new version:

1. Update the version in package.json
2. Update CHANGELOG.md with release notes
3. Create a new GitHub release with a tag matching the version (e.g., v1.2.3)
4. The publish workflow will automatically publish to npm

🛠 Development

Prerequisites

• Node.js >= 18.0.0

Setup

# Clone the repository
git clone https://github.com/TJLSmith0831/a11y-unit.git
cd a11y-unit

# Install dependencies
pnpm install

# Run tests
pnpm test

# Build the package
pnpm build

# Run linting
pnpm lint

Project Structure

a11y-unit/
├── src/                # Source code
│   ├── auto-fixer.ts      # AI-powered fix generation & application
│   ├── scanner.ts         # Accessibility issue detection
│   ├── ai-service.ts      # OpenAI API integration
│   ├── cli.ts             # CLI commands with --auto-fix & --auto-pr
│   ├── index.ts           # Public API exports
│   └── __tests__/         # Comprehensive test suite (105 tests)
├── bin/                # CLI entry point
│   └── a11y-unit.js
├── test-openai.ts      # OpenAI API integration test script
└── package.json        # Package configuration

Testing Philosophy

This project follows strict Test-Driven Development (TDD):

• ✅ All features must have tests before implementation
• ✅ 100% test coverage for core logic
• ✅ Tests are colocated with source code
• ✅ No code ships without passing tests

Running Tests

# Run all tests
pnpm test

# Run tests in watch mode
pnpm test:watch

# Run tests with coverage
pnpm test:coverage

# Run tests for specific package
pnpm --filter @a11y-unit/core test

🔧 Configuration

Create an a11y.config.js file in your project root:

module.exports = {
  // Rules to run
  rules: {
    'button-name': { enabled: true },
    'img-alt': { enabled: true },
    'color-contrast': { enabled: true },
  },

  // Output format
  format: 'terminal', // 'terminal' | 'json' | 'github-actions'

  // Scan options
  includeWarnings: false,
  includeNotices: false,

  // File patterns to scan
  include: ['src/**/*.{js,jsx,ts,tsx}'],
  exclude: ['node_modules/**', 'dist/**'],
};

📖 API Reference

Core Package

import { scanHTML, scanURL } from 'a11y-unit';

// Scan HTML string
const issues = await scanHTML('<button>Click me</button>');

// Scan live URL
const issues = await scanURL('https://example.com');

// Scan with options
const issues = await scanHTML(html, {
  rules: { 'button-name': { enabled: true } },
  includeWarnings: true,
});

CLI Usage

# Basic scanning
a11y-unit scan <path-or-url>

# Options
a11y-unit scan ./src \
  --format json \
  --output results.json \
  --rules button-name,img-alt \
  --include-warnings

# Help
a11y-unit --help
a11y-unit scan --help

🤝 Contributing

We welcome contributions! Please see our Contributing Guide for details.

Development Workflow

1. Fork the repository
2. Create a feature branch: git checkout -b feature/amazing-feature
3. Write tests for your changes (TDD approach)
4. Implement your changes
5. Ensure all tests pass: pnpm test
6. Commit your changes: git commit -m 'feat: add amazing feature'
7. Push to the branch: git push origin feature/amazing-feature
8. Open a Pull Request

Commit Convention

We use Conventional Commits:

• feat: - New features
• fix: - Bug fixes
• docs: - Documentation changes
• test: - Test changes
• refactor: - Code refactoring
• chore: - Build process or auxiliary tool changes

📄 License

This project is licensed under the MIT License - see the LICENSE file for details.

🙏 Acknowledgments

• axe-core - The accessibility engine that powers our scans
• Playwright - For browser automation and live site testing
• React and Next.js communities

🔗 Links

• Changelog
• Contributing