A Next.js-based accessibility testing tool that scans websites for WCAG compliance issues and provides AI-powered fix suggestions.
- Website Scanning: Comprehensive accessibility testing using axe-core
- PDF Reports: Generate detailed accessibility reports in PDF format
- AI Suggestions: Get AI-powered fix suggestions for accessibility issues
- Multiple Scan Modes: Quick, external, and simple scanning options
- Real-time Results: View scan results with severity classifications
First, install dependencies:
npm installSet up environment variables:
# Create .env.local file
OPENAI_API_KEY=your_openai_api_key_hereRun the development server:
npm run devOpen http://localhost:3000 with your browser to see the result.
POST /api/scan
Content-Type: application/json
{
"url": "https://example.com"
}POST /api/report/pdf
Content-Type: application/json
# Option 1: Provide scan data directly
{
"scan": {
"url": "https://example.com",
"timestamp": "2024-01-01T12:00:00.000Z",
"totalIssues": 5,
"issues": [...],
"mode": "quick"
}
}
# Option 2: Provide URL to scan and generate PDF
{
"url": "https://example.com"
}POST /api/suggest
Content-Type: application/json
{
"issue": {
"ruleId": "image-alt",
"message": "Images must have alternate text",
"wcag": "WCAG 2.1 - 1.1.1",
"selector": "body > img",
"htmlSnippet": "<img src='logo.png'>"
},
"tier": "free" // or "paid"
}POST /api/audit
Content-Type: application/json
{
"htmlSnippet": "<html>...</html>",
"axeResults": "{\"violations\": [...]}"
}This endpoint uses GPT-4 to identify additional accessibility issues that automated tools like axe-core might miss, such as:
- Semantic and contextual issues
- Alt text quality and meaning
- Link and button text clarity
- Heading structure problems
- Form labeling improvements
- Plain language considerations
Returns a JSON array of issues with WCAG references and fix suggestions.
A test page is available at /test-audit.html that allows you to try the advanced audit feature with custom HTML and axe-core results.
- Rate Limit: 10 requests per minute
- Response: One-line fix summary
- Cost: Minimal token usage
- Rate Limit: 30 requests per minute
- Response: Detailed summary + code examples + WCAG notes
- Cost: Higher token usage for comprehensive suggestions
PDF reports include:
- Site URL and scan timestamp
- Overall accessibility score (0-100)
- Severity breakdown (Critical, Serious, Moderate, Minor)
- Detailed issue table with WCAG references
- Generated using puppeteer-core + @sparticuz/chromium (Vercel-safe)
| Variable | Description | Required |
|---|---|---|
OPENAI_API_KEY |
OpenAI API key for AI suggestions | Yes |
PLAYWRIGHT_CHROMIUM_EXECUTABLE_PATH |
Chromium path for local development | No |
- puppeteer-core: PDF generation (lightweight)
- @sparticuz/chromium: Chromium for Vercel deployment
- zod: Input validation
- openai: AI suggestions
- axe-core: Accessibility testing
The project includes optimized Vercel configuration:
{
"functions": {
"app/api/scan/route.ts": {
"maxDuration": 60,
"memory": 3008
},
"app/api/report/pdf/route.ts": {
"maxDuration": 20,
"memory": 1024
},
"app/api/suggest/route.ts": {
"maxDuration": 15,
"memory": 512
}
}
}- Add
OPENAI_API_KEYto your Vercel project environment variables - Deploy using Vercel CLI or GitHub integration
- The PDF generation uses @sparticuz/chromium which is safe for Vercel's serverless environment
Generate PDF Report:
curl -X POST https://your-domain.vercel.app/api/report/pdf \
-H "Content-Type: application/json" \
-d '{"url": "https://example.com"}' \
--output report.pdfGet AI Suggestion:
curl -X POST https://your-domain.vercel.app/api/suggest \
-H "Content-Type: application/json" \
-d '{
"issue": {
"ruleId": "image-alt",
"message": "Images must have alternate text",
"wcag": "WCAG 2.1 - 1.1.1",
"selector": "body > img"
},
"tier": "free"
}'The API includes comprehensive error handling:
- Rate Limiting: Automatic rate limiting with clear error messages
- Input Validation: Zod schema validation with helpful error messages
- Service Errors: Graceful handling of OpenAI API and PDF generation errors
- Size Limits: PDF generation bails out if HTML content is too large
- Fork the repository
- Create a feature branch
- Make your changes
- Add tests if applicable
- Submit a pull request
This project is licensed under the MIT License.