AccessGuard AI

An AI-assisted accessibility auditing tool that helps developers identify, understand, and fix common web accessibility issues.

AccessGuard AI analyzes websites against WCAG accessibility guidelines, detects violations, groups repeated issues, calculates accessibility scores, and provides developer-friendly explanations with implementation guidance.

---

Problem

Millions of websites still contain accessibility barriers that prevent people with disabilities from fully accessing digital content.

While existing accessibility scanners can detect issues, they often generate long technical reports that make it difficult for developers to understand:

• What is wrong?
• Why does it matter?
• Who is affected?
• How can it be fixed?

AccessGuard AI transforms accessibility testing into an understandable developer workflow by combining automated analysis with clear explanations and actionable recommendations.

---

Solution

AccessGuard AI provides an end-to-end accessibility auditing pipeline that:

• Crawls websites
• Extracts accessibility-related HTML elements
• Evaluates them against WCAG guidelines
• Groups duplicate violations
• Calculates accessibility scores
• Generates developer-friendly explanations and implementation guidance

Instead of simply listing accessibility errors, AccessGuard AI helps developers understand their impact and how to resolve them.

---

Features

Website Accessibility Scanning

Scans webpages using Playwright and extracts semantic HTML elements for accessibility analysis.

The current implementation evaluates:

• Images
• Forms
• Headings
• Buttons
• Links

---

WCAG Rule Engine

Detects common accessibility issues including:

• Missing alternative text
• Incorrect heading hierarchy
• Unlabeled form controls
• Empty or unclear links
• Buttons without accessible labels

Each issue includes:

• WCAG Success Criterion
• Conformance Level
• Severity
• Affected Elements

Example:

WCAG 1.1.1
Level A
Missing alternative text

---

Smart Issue Grouping

Large websites often contain many identical accessibility violations.

AccessGuard AI groups duplicate issues into a single report showing:

• Number of occurrences
• Example affected elements
• WCAG reference

This keeps reports concise and easier to understand.

---

Accessibility Scoring

Accessibility scores are calculated using:

Passed Checks / Total Checks × 100

The dashboard displays:

• Overall accessibility score
• Category scores
• Total checks
• Failed checks

Example:

Overall Score: 92%

Images: 80%
Forms: 100%
Headings: 90%
Buttons: 100%
Links: 95%

---

AI-Assisted Explanation Engine

Each detected issue includes a structured explanation consisting of:

Problem

Explains what is wrong.

User Impact

Describes how users may be affected.

Recommended Solution

Provides practical remediation guidance.

Corrected Implementation

Shows an example implementation developers can follow.

The explanation module is intentionally isolated from the scanning engine, making it straightforward to extend with future LLM-powered capabilities.

---

Architecture

             Website URL
                  │
                  ▼
        Playwright Web Crawler
                  │
                  ▼
      HTML Accessibility Parser
                  │
                  ▼
         WCAG Rules Engine
                  │
                  ▼
      Issue Deduplication Layer
                  │
                  ▼
      Accessibility Score Engine
                  │
                  ▼
     Explanation Generation Layer
                  │
                  ▼
        React Dashboard Interface

---

Tech Stack

Frontend

• React
• Vite
• Tailwind CSS

Backend

• Python
• FastAPI
• Uvicorn

Accessibility Engine

• Playwright
• BeautifulSoup
• Custom WCAG Rule Engine

Testing

• Pytest

Containerization

• Docker

---

Project Structure

AccessGuard-AI/

├── backend/
│   ├── app/
│   │   ├── ai/
│   │   ├── services/
│   │   ├── routes/
│   │   └── main.py
│   │
│   ├── tests/
│   ├── requirements.txt
│   └── Dockerfile
│
├── frontend/
│   ├── src/
│   ├── public/
│   ├── package.json
│   └── Dockerfile
│
├── docker-compose.yml
├── LICENSE
└── README.md

---

Installation

Prerequisites

• Python 3.10+
• Node.js 18+
• Chromium (installed automatically through Playwright)

---

Backend

cd backend

python -m venv venv

source venv/bin/activate

pip install -r requirements.txt

playwright install chromium

uvicorn app.main:app --reload

Backend:

http://localhost:8000

---

Frontend

cd frontend

npm install

npm run dev

Frontend:

http://localhost:5173

---

Testing

Run the complete backend test suite:

cd backend

source venv/bin/activate

pytest tests/ -v

Current automated tests cover:

• Accessibility rule validation
• Issue grouping
• Accessibility scoring
• Parser resilience
• Report schema validation

---

Supported Platforms

AccessGuard AI has been developed and tested on:

• macOS
• Linux
• Windows (WSL recommended)

---

Testing Instructions

To evaluate the project:

1. Start the backend server.
2. Start the frontend application.
3. Open the dashboard.
4. Enter a public website URL.
5. Run an accessibility scan.
6. Review:

• Accessibility score
• WCAG issues
• AI-assisted explanations
• Suggested implementation guidance

---

Development Process: Codex & GPT-5.6

How Codex Accelerated Development

AccessGuard AI was developed using Codex as an AI coding assistant throughout the project.

Rather than generating the application end-to-end, Codex accelerated iterative development by assisting with:

• Planning the overall project architecture
• Bootstrapping the React and FastAPI applications
• Implementing backend service modules
• Refactoring code into reusable components
• Debugging frontend and backend integration issues
• Writing and refining automated tests
• Reviewing code quality and suggesting improvements

Development followed an incremental milestone-based workflow:

1. Project setup and architecture
2. Backend API implementation
3. Website crawling with Playwright
4. HTML parsing and semantic extraction
5. WCAG rule engine
6. Accessibility scoring
7. Frontend dashboard
8. Testing and refinement

Each milestone was implemented, tested, and reviewed before moving to the next stage.

---

How GPT-5.6 Was Used

GPT-5.6 acted as a technical design and engineering assistant during development.

It was used to:

• Explore architectural alternatives
• Review implementation decisions
• Debug backend and frontend issues
• Improve API design
• Refactor code for maintainability
• Review accessibility analysis logic
• Suggest improvements to testing and project structure
• Help prepare documentation and project presentation

All implementation decisions were reviewed before being incorporated into the final project.

---

Key Engineering Decisions

Deterministic Accessibility Analysis

Accessibility evaluation requires predictable and reproducible results.

For this reason, the core auditing pipeline is deterministic rather than LLM-driven.

Website crawling, HTML parsing, WCAG rule evaluation, and accessibility scoring are implemented as dedicated modules with explicit logic.

This provides consistent, repeatable results regardless of external AI services.

---

Modular AI-Ready Architecture

The explanation layer is intentionally isolated from the scanning pipeline.

Separating explanation generation from accessibility analysis allows future integration of LLM-based capabilities without modifying the core auditing engine.

Potential future enhancements include:

• Context-aware accessibility explanations
• Framework-specific implementation examples
• AI-generated remediation guidance
• Personalized developer recommendations

This modular architecture keeps the accessibility scanner reliable while allowing AI capabilities to evolve independently.

---

Current Limitations

AccessGuard AI is currently an MVP.

Current limitations include:

• Single-page website analysis
• No automated multi-page crawling
• No keyboard navigation simulation
• No advanced visual contrast analysis
• Template-based explanation engine

---

Future Improvements

Planned enhancements include:

• LLM-powered contextual accessibility explanations
• Framework-specific remediation examples
• Multi-page website crawling
• Automated color contrast analysis
• Keyboard accessibility testing
• Accessibility trend tracking
• Persistent scan history
• Exportable accessibility reports

---

Screenshots

Accessibility Dashboard

---

Accessibility Report

---

Issue Explanation

---

Why AccessGuard AI?

Accessibility tools should not only identify what is broken.

They should help developers understand why accessibility matters and provide practical guidance for improving their applications.

AccessGuard AI aims to transform accessibility auditing from a technical checklist into a developer-focused engineering workflow that encourages more inclusive software.

---

License

This project is released under the MIT License.