cremote/docs/accessibility_summary_tools.md

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:

{
  "tab": "optional-tab-id",
  "tests": ["wcag", "contrast", "keyboard", "forms"],  // or ["all"]
  "standard": "WCAG21AA",  // default
  "include_screenshots": false,  // default
  "timeout": 30  // seconds
}

Returns:

{
  "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:

// 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:

{
  "tab": "optional-tab-id",
  "priority_selectors": ["button", "a", "nav", "footer"],
  "threshold": "AA",  // or "AAA"
  "timeout": 10
}

Returns:

{
  "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:

// 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:

{
  "tab": "optional-tab-id",
  "check_focus_indicators": true,
  "check_tab_order": true,
  "check_keyboard_traps": true,
  "timeout": 15
}

Returns:

{
  "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:

// 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:

{
  "tab": "optional-tab-id",
  "form_selector": "form#contact",  // optional, defaults to all forms
  "timeout": 10
}

Returns:

{
  "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:

// 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:

// 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:

// 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):

// 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):

// 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

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

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