# 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