426 lines
10 KiB
Markdown
426 lines
10 KiB
Markdown
# Accessibility Summary Tools
|
|
|
|
## Overview
|
|
|
|
The cremote MCP server now includes specialized accessibility summary tools that dramatically reduce token usage while providing actionable accessibility assessment results. These tools process raw accessibility data server-side and return only the critical findings in a structured, token-efficient format.
|
|
|
|
## Token Savings
|
|
|
|
| Tool | Old Approach | New Approach | Token Savings |
|
|
|------|--------------|--------------|---------------|
|
|
| Page Assessment | ~80k tokens | ~4k tokens | **95%** |
|
|
| Contrast Check | ~30k tokens | ~4k tokens | **85%** |
|
|
| Keyboard Test | ~10k tokens | ~2k tokens | **80%** |
|
|
| Form Analysis | ~8k tokens | ~2k tokens | **75%** |
|
|
|
|
**Total Site Assessment (10 pages):**
|
|
- Old: 280k+ tokens (only 3 pages possible)
|
|
- New: 32k tokens (10+ pages possible)
|
|
- **Savings: 89%**
|
|
|
|
---
|
|
|
|
## Tools
|
|
|
|
### 1. `web_page_accessibility_report_cremotemcp_cremotemcp`
|
|
|
|
**Purpose:** Single-call comprehensive page accessibility assessment
|
|
|
|
**Description:** Combines multiple accessibility tests (axe-core, contrast, keyboard, forms) and returns only critical findings in a token-efficient format. This is the primary tool for page-level assessments.
|
|
|
|
**Parameters:**
|
|
```json
|
|
{
|
|
"tab": "optional-tab-id",
|
|
"tests": ["wcag", "contrast", "keyboard", "forms"], // or ["all"]
|
|
"standard": "WCAG21AA", // default
|
|
"include_screenshots": false, // default
|
|
"timeout": 30 // seconds
|
|
}
|
|
```
|
|
|
|
**Returns:**
|
|
```json
|
|
{
|
|
"url": "https://example.com",
|
|
"timestamp": "2025-10-03T15:56:23Z",
|
|
"compliance_status": "NON_COMPLIANT", // COMPLIANT, PARTIAL, NON_COMPLIANT
|
|
"overall_score": 65, // 0-100
|
|
"legal_risk": "HIGH", // LOW, MEDIUM, HIGH, CRITICAL
|
|
|
|
"critical_issues": [
|
|
{
|
|
"wcag": "1.4.4",
|
|
"title": "Viewport zoom disabled",
|
|
"description": "User scaling disabled with user-scalable=0",
|
|
"impact": "critical",
|
|
"count": 1,
|
|
"examples": ["meta[name='viewport']"],
|
|
"remediation": "Remove user-scalable=0 from viewport meta tag"
|
|
}
|
|
],
|
|
|
|
"serious_issues": [...],
|
|
"high_issues": [...],
|
|
"medium_issues": [...],
|
|
|
|
"contrast_summary": {
|
|
"total_checked": 310,
|
|
"passed": 225,
|
|
"failed": 85,
|
|
"pass_rate": "72.6%",
|
|
"critical_failures": [
|
|
{
|
|
"selector": "button.submit",
|
|
"text": "Send Message",
|
|
"ratio": 2.71,
|
|
"required": 4.5,
|
|
"fg_color": "#ffffff",
|
|
"bg_color": "#17a8e3",
|
|
"fix": "Use #0d7db8 for background"
|
|
}
|
|
]
|
|
},
|
|
|
|
"keyboard_summary": {
|
|
"total_interactive": 65,
|
|
"focusable": 31,
|
|
"missing_focus_indicator": 31,
|
|
"keyboard_traps": 0,
|
|
"issues": [...]
|
|
},
|
|
|
|
"form_summary": {...},
|
|
"estimated_remediation_hours": 8
|
|
}
|
|
```
|
|
|
|
**Example Usage:**
|
|
```javascript
|
|
// Test all aspects of a page
|
|
web_page_accessibility_report_cremotemcp_cremotemcp({
|
|
"tests": ["all"],
|
|
"standard": "WCAG21AA"
|
|
})
|
|
|
|
// Test only specific aspects
|
|
web_page_accessibility_report_cremotemcp_cremotemcp({
|
|
"tests": ["wcag", "contrast"],
|
|
"timeout": 20
|
|
})
|
|
```
|
|
|
|
---
|
|
|
|
### 2. `web_contrast_audit_cremotemcp_cremotemcp`
|
|
|
|
**Purpose:** Smart contrast checking with prioritized failures
|
|
|
|
**Description:** Returns only failures and common patterns, significantly reducing token usage compared to full contrast check. Prioritizes specific selectors (buttons, links, navigation).
|
|
|
|
**Parameters:**
|
|
```json
|
|
{
|
|
"tab": "optional-tab-id",
|
|
"priority_selectors": ["button", "a", "nav", "footer"],
|
|
"threshold": "AA", // or "AAA"
|
|
"timeout": 10
|
|
}
|
|
```
|
|
|
|
**Returns:**
|
|
```json
|
|
{
|
|
"total_checked": 310,
|
|
"passed": 225,
|
|
"failed": 85,
|
|
"pass_rate": "72.6%",
|
|
"critical_failures": [
|
|
{
|
|
"selector": "footer p",
|
|
"text": "Copyright 2025",
|
|
"ratio": 2.70,
|
|
"required": 4.5,
|
|
"fg_color": "#666666",
|
|
"bg_color": "#242424",
|
|
"fix": "Change #666666 to #999999 or lighter"
|
|
}
|
|
],
|
|
"failure_patterns": {
|
|
"footer_text": {
|
|
"count": 31,
|
|
"ratio": 2.70,
|
|
"fix": "Change #666666 to #999999"
|
|
},
|
|
"nav_links": {
|
|
"count": 12,
|
|
"ratio": 2.75,
|
|
"fix": "Change #2ea3f2 to #1a7db8"
|
|
}
|
|
}
|
|
}
|
|
```
|
|
|
|
**Example Usage:**
|
|
```javascript
|
|
// Prioritize interactive elements
|
|
web_contrast_audit_cremotemcp_cremotemcp({
|
|
"priority_selectors": ["button", "a", "nav", "footer"],
|
|
"threshold": "AA"
|
|
})
|
|
```
|
|
|
|
---
|
|
|
|
### 3. `web_keyboard_audit_cremotemcp_cremotemcp`
|
|
|
|
**Purpose:** Keyboard navigation assessment with actionable results
|
|
|
|
**Description:** Returns summary of issues rather than full element lists, reducing token usage by ~80%.
|
|
|
|
**Parameters:**
|
|
```json
|
|
{
|
|
"tab": "optional-tab-id",
|
|
"check_focus_indicators": true,
|
|
"check_tab_order": true,
|
|
"check_keyboard_traps": true,
|
|
"timeout": 15
|
|
}
|
|
```
|
|
|
|
**Returns:**
|
|
```json
|
|
{
|
|
"status": "FAIL", // PASS, PARTIAL, FAIL
|
|
"total_interactive": 65,
|
|
"focusable": 31,
|
|
"issues": [
|
|
{
|
|
"type": "missing_focus_indicators",
|
|
"severity": "HIGH",
|
|
"count": 31,
|
|
"description": "31 elements lack visible focus indicators",
|
|
"fix": "Add visible :focus styles with outline or border",
|
|
"examples": ["a.nav-link", "button.submit"]
|
|
}
|
|
],
|
|
"tab_order_issues": [],
|
|
"recommendation": "Add visible focus indicators to all interactive elements."
|
|
}
|
|
```
|
|
|
|
**Example Usage:**
|
|
```javascript
|
|
// Full keyboard audit
|
|
web_keyboard_audit_cremotemcp_cremotemcp({
|
|
"check_focus_indicators": true,
|
|
"check_tab_order": true,
|
|
"check_keyboard_traps": true
|
|
})
|
|
```
|
|
|
|
---
|
|
|
|
### 4. `web_form_accessibility_audit_cremotemcp_cremotemcp`
|
|
|
|
**Purpose:** Comprehensive form accessibility check
|
|
|
|
**Description:** Analyzes labels, ARIA attributes, keyboard accessibility, and contrast issues for forms.
|
|
|
|
**Parameters:**
|
|
```json
|
|
{
|
|
"tab": "optional-tab-id",
|
|
"form_selector": "form#contact", // optional, defaults to all forms
|
|
"timeout": 10
|
|
}
|
|
```
|
|
|
|
**Returns:**
|
|
```json
|
|
{
|
|
"forms_found": 1,
|
|
"forms": [
|
|
{
|
|
"id": "forminator-form-31560",
|
|
"fields": 6,
|
|
"issues": [
|
|
{
|
|
"type": "missing_labels",
|
|
"severity": "SERIOUS",
|
|
"count": 6,
|
|
"description": "6 fields lack proper labels",
|
|
"fix": "Add <label> elements or aria-label attributes"
|
|
},
|
|
{
|
|
"type": "submit_button_contrast",
|
|
"severity": "SERIOUS",
|
|
"ratio": 2.71,
|
|
"description": "Submit button has insufficient contrast",
|
|
"fix": "Change button background to #0d7db8"
|
|
}
|
|
],
|
|
"aria_compliance": "PARTIAL",
|
|
"keyboard_accessible": true,
|
|
"required_fields_marked": true
|
|
}
|
|
]
|
|
}
|
|
```
|
|
|
|
**Example Usage:**
|
|
```javascript
|
|
// Audit all forms on page
|
|
web_form_accessibility_audit_cremotemcp_cremotemcp({})
|
|
|
|
// Audit specific form
|
|
web_form_accessibility_audit_cremotemcp_cremotemcp({
|
|
"form_selector": "form#contact-form"
|
|
})
|
|
```
|
|
|
|
---
|
|
|
|
## Recommended Workflow
|
|
|
|
### For Single Page Assessment:
|
|
```javascript
|
|
// 1. Navigate to page
|
|
web_navigate_cremotemcp_cremotemcp({ "url": "https://example.com" })
|
|
|
|
// 2. Get comprehensive report (4k tokens)
|
|
web_page_accessibility_report_cremotemcp_cremotemcp({
|
|
"tests": ["all"],
|
|
"standard": "WCAG21AA"
|
|
})
|
|
|
|
// 3. Take screenshot if needed
|
|
web_screenshot_cremotemcp_cremotemcp({ "output": "/tmp/page.png" })
|
|
```
|
|
|
|
### For Multi-Page Site Assessment:
|
|
```javascript
|
|
// For each page:
|
|
// 1. Navigate
|
|
web_navigate_cremotemcp_cremotemcp({ "url": page_url })
|
|
|
|
// 2. Get summary report (3-4k tokens per page)
|
|
web_page_accessibility_report_cremotemcp_cremotemcp({
|
|
"tests": ["wcag", "contrast", "keyboard"],
|
|
"timeout": 20
|
|
})
|
|
|
|
// Total: ~35k tokens for 10 pages (vs 280k+ with old approach)
|
|
```
|
|
|
|
---
|
|
|
|
## Migration Guide
|
|
|
|
### Old Approach (High Token Usage):
|
|
```javascript
|
|
// 80k+ tokens per page
|
|
web_inject_axe_cremotemcp_cremotemcp()
|
|
web_run_axe_cremotemcp_cremotemcp() // 50k tokens
|
|
web_contrast_check_cremotemcp_cremotemcp() // 30k tokens
|
|
web_keyboard_test_cremotemcp_cremotemcp() // 10k tokens
|
|
```
|
|
|
|
### New Approach (Low Token Usage):
|
|
```javascript
|
|
// 4k tokens per page
|
|
web_page_accessibility_report_cremotemcp_cremotemcp({
|
|
"tests": ["all"]
|
|
})
|
|
```
|
|
|
|
---
|
|
|
|
## Technical Details
|
|
|
|
### Server-Side Processing
|
|
All heavy processing is done in the daemon:
|
|
1. Runs axe-core, contrast checks, keyboard tests
|
|
2. Processes and summarizes results
|
|
3. Returns only actionable findings
|
|
4. Limits examples to 3 per issue
|
|
5. Groups similar issues into patterns
|
|
|
|
### Token Optimization Strategies
|
|
1. **Violations Only**: Returns only failures, not passes
|
|
2. **Limited Examples**: Max 3 examples per issue type
|
|
3. **Pattern Detection**: Groups similar failures
|
|
4. **Prioritization**: Focuses on high-impact issues
|
|
5. **Structured Summaries**: Consistent, compact format
|
|
|
|
---
|
|
|
|
## Best Practices
|
|
|
|
1. **Use `web_page_accessibility_report` for initial assessment**
|
|
- Covers all major WCAG criteria
|
|
- Provides overall compliance status
|
|
- Estimates remediation effort
|
|
|
|
2. **Use specialized tools for deep dives**
|
|
- `web_contrast_audit` for detailed contrast analysis
|
|
- `web_keyboard_audit` for keyboard-specific issues
|
|
- `web_form_accessibility_audit` for form-heavy pages
|
|
|
|
3. **Batch page testing**
|
|
- Test 10+ pages within token limits
|
|
- Use consistent test parameters
|
|
- Aggregate findings across pages
|
|
|
|
4. **Screenshot strategically**
|
|
- Only capture critical violations
|
|
- Use element screenshots for specific issues
|
|
- Store in dedicated screenshots folder
|
|
|
|
---
|
|
|
|
## Troubleshooting
|
|
|
|
### Issue: Timeout errors
|
|
**Solution:** Increase timeout parameter for complex pages
|
|
```javascript
|
|
web_page_accessibility_report_cremotemcp_cremotemcp({
|
|
"tests": ["all"],
|
|
"timeout": 60 // Increase from default 30
|
|
})
|
|
```
|
|
|
|
### Issue: Missing axe-core
|
|
**Solution:** The tool automatically injects axe-core, no manual injection needed
|
|
|
|
### Issue: Form not found
|
|
**Solution:** Verify form selector or omit to scan all forms
|
|
```javascript
|
|
web_form_accessibility_audit_cremotemcp_cremotemcp({
|
|
"form_selector": "" // Empty = all forms
|
|
})
|
|
```
|
|
|
|
---
|
|
|
|
## Future Enhancements
|
|
|
|
Planned improvements:
|
|
1. Site-wide crawl and assessment tool
|
|
2. Caching of repeated checks
|
|
3. Incremental testing (only test what changed)
|
|
4. Custom rule configuration
|
|
5. Export to multiple report formats
|
|
|
|
---
|
|
|
|
## Support
|
|
|
|
For issues or questions:
|
|
1. Check daemon logs for detailed error messages
|
|
2. Verify cremotedaemon is running
|
|
3. Test with simple pages first
|
|
4. Review docs/llm_instructions.md for project guidelines
|
|
|