bump
This commit is contained in:
Josh at WLTechBlog
425
docs/accessibility_summary_tools.md
Normal file
425
docs/accessibility_summary_tools.md
Normal file
@@ -0,0 +1,425 @@
|
||||
# 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
|
||||
|
||||
Reference in New Issue
Block a user