Files

Josh at WLTechBlog 8d9300b317 bump

2025-10-03 13:44:58 -05:00

33 KiB

Raw Blame History

LLM Agent Guide: ADA/WCAG Accessibility Testing with Cremote

Purpose

This document provides LLM coding agents with concrete, actionable guidance for using Cremote's accessibility testing tools to conduct ADA/WCAG compliance audits.

⚠️ IMPORTANT: Tool Naming Convention

All cremote MCP tools use the double suffix naming pattern: toolname_cremotemcp_cremotemcp

Correct: web_run_axe_cremotemcp_cremotemcp Incorrect: web_run_axe_cremotemcp

Quick Reference

Token-Efficient Summary Tools (NEW - 2025-10-03)

🚀 RECOMMENDED FOR SITE-WIDE ASSESSMENTS

These tools reduce token usage by 85-95% while providing comprehensive, actionable results:

Tool	Purpose	Token Usage	Replaces
`web_page_accessibility_report_cremotemcp_cremotemcp`	Comprehensive single-page assessment	~4k	Multiple tools (95% savings)
`web_contrast_audit_cremotemcp_cremotemcp`	Smart contrast check with patterns	~4k	`web_contrast_check_cremotemcp_cremotemcp` (85% savings)
`web_keyboard_audit_cremotemcp_cremotemcp`	Keyboard navigation summary	~2k	`web_keyboard_test_cremotemcp_cremotemcp` (80% savings)
`web_form_accessibility_audit_cremotemcp_cremotemcp`	Form accessibility check	~2k	Manual form analysis (75% savings)

Use these for:

Multi-page site assessments (10+ pages possible)
Initial comprehensive audits
Token-constrained environments
Structured, actionable reports

Tool Selection Matrix

Testing Need	Primary Tool	Secondary Tool	WCAG Criteria
Comprehensive page audit	`web_page_accessibility_report_cremotemcp_cremotemcp` ⭐	-	All automated criteria
Comprehensive automated audit	`web_run_axe_cremotemcp_cremotemcp`	-	~57% of WCAG 2.1 AA
Smart contrast check	`web_contrast_audit_cremotemcp_cremotemcp` ⭐	`web_contrast_check_cremotemcp_cremotemcp`	1.4.3, 1.4.6, 1.4.11
Color contrast issues	`web_contrast_check_cremotemcp_cremotemcp`	`web_gradient_contrast_check_cremotemcp_cremotemcp`	1.4.3, 1.4.6, 1.4.11
Gradient backgrounds	`web_gradient_contrast_check_cremotemcp_cremotemcp`	-	1.4.3, 1.4.6, 1.4.11
Keyboard navigation	`web_keyboard_audit_cremotemcp_cremotemcp` ⭐	`web_keyboard_test_cremotemcp_cremotemcp`	2.1.1, 2.4.7
Form accessibility	`web_form_accessibility_audit_cremotemcp_cremotemcp` ⭐	-	3.3.2, 4.1.2, 1.3.1
Video/audio captions	`web_media_validation_cremotemcp_cremotemcp`	-	1.2.2, 1.2.5, 1.4.2
Hover/focus content	`web_hover_focus_test_cremotemcp_cremotemcp`	-	1.4.13
Text in images	`web_text_in_images_cremotemcp_cremotemcp`	-	1.4.5, 1.4.9, 1.1.1
Cross-page consistency	`web_cross_page_consistency_cremotemcp_cremotemcp`	-	3.2.3, 3.2.4, 1.3.1
Sensory instructions	`web_sensory_characteristics_cremotemcp_cremotemcp`	-	1.3.3
Animations/flashing	`web_animation_flash_cremotemcp_cremotemcp`	-	2.3.1, 2.2.2, 2.3.2
ARIA validation	`web_enhanced_accessibility_cremotemcp_cremotemcp`	`web_run_axe_cremotemcp_cremotemcp`	1.3.1, 4.1.2, 2.4.6
Keyboard accessibility	`web_keyboard_test_cremotemcp_cremotemcp`	`web_run_axe_cremotemcp_cremotemcp`	2.1.1, 2.4.7
Zoom/resize functionality	`web_zoom_test_cremotemcp_cremotemcp`	-	1.4.4
Responsive design	`web_reflow_test_cremotemcp_cremotemcp`	-	1.4.10
Visual documentation	`web_screenshot_cremotemcp_cremotemcp`	-	Evidence capture
Custom JavaScript testing	`console_command_cremotemcp_cremotemcp`	-	Advanced scenarios

⭐ = Token-efficient summary tool (recommended for site-wide assessments)

Recommended Testing Sequences

Option 1: Token-Efficient Approach (RECOMMENDED for site-wide assessments)

Single call per page - ~4k tokens:

1. web_page_accessibility_report_cremotemcp_cremotemcp  # Comprehensive assessment
   - Includes: axe-core, contrast, keyboard, forms
   - Returns: Structured summary with compliance status
   - Token usage: ~4k (vs 80k+ with old approach)

For 10 pages: ~40k tokens total (vs 800k+ with old approach)

Option 2: Detailed Testing Approach (for deep dives)

Use when you need raw data or specific tool features:

1. web_inject_axe_cremotemcp_cremotemcp                    # Inject axe-core library
2. web_run_axe_cremotemcp_cremotemcp                       # Run comprehensive automated tests
3. web_contrast_check_cremotemcp_cremotemcp                # Detailed contrast analysis
4. web_gradient_contrast_check_cremotemcp_cremotemcp       # Gradient background contrast
5. web_media_validation_cremotemcp_cremotemcp              # Video/audio caption validation
6. web_hover_focus_test_cremotemcp_cremotemcp              # Hover/focus content testing
7. web_text_in_images_cremotemcp_cremotemcp                # Text-in-images detection
8. web_sensory_characteristics_cremotemcp_cremotemcp       # Sensory instruction detection
9. web_animation_flash_cremotemcp_cremotemcp               # Animation/flash detection
10. web_enhanced_accessibility_cremotemcp_cremotemcp       # Enhanced ARIA validation
11. web_keyboard_test_cremotemcp_cremotemcp                # Keyboard navigation testing
12. web_zoom_test_cremotemcp_cremotemcp                    # Zoom functionality testing
13. web_reflow_test_cremotemcp_cremotemcp                  # Responsive design testing

Note: For multi-page sites, also run:

14. web_cross_page_consistency_cremotemcp_cremotemcp       # Cross-page consistency

Option 3: Hybrid Approach (balanced)

Use summary tools for initial assessment, detailed tools for specific issues:

1. web_page_accessibility_report_cremotemcp_cremotemcp     # Initial comprehensive assessment
2. If specific issues found:
   a. web_contrast_audit_cremotemcp_cremotemcp             # Deep dive on contrast
   b. web_keyboard_audit_cremotemcp_cremotemcp             # Deep dive on keyboard
   c. web_form_accessibility_audit_cremotemcp_cremotemcp   # Deep dive on forms

Tool Usage Patterns

Pattern 1: Token-Efficient Page Assessment (NEW - RECOMMENDED)

// Single call - comprehensive assessment (~4k tokens)
{
  "tool": "web_page_accessibility_report_cremotemcp_cremotemcp",
  "arguments": {
    "tests": ["all"],  // or ["wcag", "contrast", "keyboard", "forms"]
    "standard": "WCAG21AA",
    "timeout": 30
  }
}

// Returns structured summary with:
// - compliance_status: COMPLIANT, PARTIAL, NON_COMPLIANT
// - overall_score: 0-100
// - legal_risk: LOW, MEDIUM, HIGH, CRITICAL
// - critical_issues, serious_issues, high_issues, medium_issues
// - contrast_summary, keyboard_summary, form_summary
// - estimated_remediation_hours

Pattern 2: Initial Audit (Traditional Approach)

// Step 1: Inject axe-core
{
  "tool": "web_inject_axe_cremotemcp_cremotemcp",
  "arguments": {
    "timeout": 30
  }
}

// Step 2: Run comprehensive tests
{
  "tool": "web_run_axe_cremotemcp_cremotemcp",
  "arguments": {
    "run_only": ["wcag2a", "wcag2aa", "wcag21aa"],
    "timeout": 30
  }
}

// Step 3: Analyze results and run specialized tests based on findings

Pattern 3: Smart Contrast Audit (NEW - RECOMMENDED)

// Token-efficient contrast check with prioritized failures (~4k tokens)
{
  "tool": "web_contrast_audit_cremotemcp_cremotemcp",
  "arguments": {
    "priority_selectors": ["button", "a", "nav", "footer"],
    "threshold": "AA",
    "timeout": 10
  }
}

// Returns:
// - total_checked, passed, failed, pass_rate
// - critical_failures (top 20 with fixes)
// - failure_patterns (grouped similar issues)

Pattern 4: Contrast-Specific Testing (Traditional)

// For pages with known or suspected contrast issues
{
  "tool": "web_contrast_check_cremotemcp_cremotemcp",
  "arguments": {
    "selector": "body",  // Test entire page
    "timeout": 10
  }
}

// For specific sections
{
  "tool": "web_contrast_check_cremotemcp_cremotemcp",
  "arguments": {
    "selector": ".main-content",  // Test specific area
    "timeout": 10
  }
}

Pattern 5: Smart Keyboard Audit (NEW - RECOMMENDED)

// Token-efficient keyboard assessment (~2k tokens)
{
  "tool": "web_keyboard_audit_cremotemcp_cremotemcp",
  "arguments": {
    "check_focus_indicators": true,
    "check_tab_order": true,
    "check_keyboard_traps": true,
    "timeout": 15
  }
}

// Returns:
// - status: PASS, PARTIAL, FAIL
// - total_interactive, focusable
// - issues (categorized by type and severity)
// - recommendation (actionable next steps)

{
  "tool": "web_keyboard_test_cremotemcp_cremotemcp",
  "arguments": {
    "timeout": 10
  }
}

// Analyze output for:
// - not_focusable: Elements that should be keyboard accessible but aren't
// - no_focus_indicator: Elements missing visible focus indicators
// - keyboard_trap: Elements that trap keyboard focus

Pattern 7: Form Accessibility Audit (NEW)

// Comprehensive form accessibility check (~2k tokens)
{
  "tool": "web_form_accessibility_audit_cremotemcp_cremotemcp",
  "arguments": {
    "form_selector": "",  // Empty = all forms
    "timeout": 10
  }
}

// Returns:
// - forms_found
// - forms[] with:
//   - id, fields count
//   - issues (missing labels, contrast, etc.)
//   - aria_compliance: FULL, PARTIAL, NONE
//   - keyboard_accessible, required_fields_marked

Pattern 8: Zoom and Responsive Testing

// Test zoom levels (WCAG 1.4.4)
{
  "tool": "web_zoom_test_cremotemcp_cremotemcp",
  "arguments": {
    "zoom_levels": [1.0, 2.0, 4.0],
    "timeout": 10
  }
}

// Test responsive breakpoints (WCAG 1.4.10)
{
  "tool": "web_reflow_test_cremotemcp_cremotemcp",
  "arguments": {
    "widths": [320, 768, 1280],
    "timeout": 10
  }
}

Pattern 9: Visual Documentation

// Capture baseline
{
  "tool": "web_screenshot_cremotemcp_cremotemcp",
  "arguments": {
    "output": "/tmp/baseline.png",
    "timeout": 5
  }
}

// Capture at 200% zoom
{
  "tool": "web_screenshot_cremotemcp_cremotemcp",
  "arguments": {
    "output": "/tmp/zoom-200.png",
    "zoom_level": 2.0,
    "timeout": 5
  }
}

// Capture mobile view
{
  "tool": "web_screenshot_cremotemcp_cremotemcp",
  "arguments": {
    "output": "/tmp/mobile-320.png",
    "width": 320,
    "height": 568,
    "timeout": 5
  }
}

Pattern 10: Gradient Contrast Testing

// Test specific element with gradient background
{
  "tool": "web_gradient_contrast_check_cremotemcp_cremotemcp",
  "arguments": {
    "selector": ".hero-section",
    "timeout": 10
  }
}

// Test all elements with gradient backgrounds
{
  "tool": "web_gradient_contrast_check_cremotemcp_cremotemcp",
  "arguments": {
    "selector": "body",  // Scans entire page
    "timeout": 10
  }
}

// Analyze output for:
// - worst_case_ratio: Minimum contrast found across gradient
// - best_case_ratio: Maximum contrast found across gradient
// - wcag_aa_pass: Whether it meets WCAG AA standards
// - wcag_aaa_pass: Whether it meets WCAG AAA standards

Pattern 11: Media Validation

// Validate all video/audio elements on page
{
  "tool": "web_media_validation_cremotemcp_cremotemcp",
  "arguments": {
    "timeout": 10
  }
}

// Analyze output for:
// - missing_captions: Videos without caption tracks
// - missing_audio_descriptions: Videos without audio description tracks
// - inaccessible_tracks: Track files that cannot be loaded
// - autoplay_violations: Videos that autoplay without controls

Pattern 12: Hover/Focus Content Testing

// Test all hover/focus triggered content
{
  "tool": "web_hover_focus_test_cremotemcp_cremotemcp",
  "arguments": {
    "timeout": 10
  }
}

// Analyze output for:
// - not_dismissible: Content that cannot be dismissed with Escape key
// - not_hoverable: Tooltip disappears when hovering over it
// - not_persistent: Content disappears too quickly
// - native_title_tooltip: Using native title attribute (violation)

Pattern 13: Text-in-Images Detection

// Detect text embedded in images using OCR
{
  "tool": "web_text_in_images_cremotemcp_cremotemcp",
  "arguments": {
    "timeout": 30  // OCR is CPU-intensive, allow more time
  }
}

// Analyze output for:
// - missing_alt: Images with text but no alt text
// - insufficient_alt: Images with text but inadequate alt text
// - detected_text: Actual text found in the image
// - recommendations: Specific suggestions for each image

Pattern 14: Cross-Page Consistency

// Check consistency across multiple pages
{
  "tool": "web_cross_page_consistency_cremotemcp_cremotemcp",
  "arguments": {
    "urls": [
      "https://example.com/",
      "https://example.com/about",
      "https://example.com/contact",
      "https://example.com/services"
    ],
    "timeout": 10  // Per page
  }
}

// Analyze output for:
// - common_navigation: Links present on all pages
// - inconsistent_pages: Pages missing common navigation
// - landmark_issues: Missing or multiple main/header/footer landmarks
// - navigation_issues: Inconsistent navigation structure

Pattern 15: Sensory Characteristics Detection

// Detect instructions relying on sensory characteristics
{
  "tool": "web_sensory_characteristics_cremotemcp_cremotemcp",
  "arguments": {
    "timeout": 10
  }
}

// Analyze output for:
// - color_only: "Click the red button" (violation)
// - shape_only: "Press the round icon" (violation)
// - sound_only: "Listen for the beep" (violation)
// - location_visual: "See above" (warning)
// - size_only: "Click the large button" (warning)

Pattern 16: Animation/Flash Detection

// Detect animations and flashing content
{
  "tool": "web_animation_flash_cremotemcp_cremotemcp",
  "arguments": {
    "timeout": 10
  }
}

// Analyze output for:
// - flashing_content: Content flashing > 3 times per second (violation)
// - no_pause_control: Autoplay animation > 5s without controls (violation)
// - rapid_animation: Fast infinite animations (warning)
// - animation_types: CSS, GIF, video, canvas, SVG

Pattern 17: Enhanced ARIA Validation

// Perform enhanced accessibility tree analysis
{
  "tool": "web_enhanced_accessibility_cremotemcp_cremotemcp",
  "arguments": {
    "timeout": 10
  }
}

// Analyze output for:
// - missing_accessible_name: Interactive elements without labels
// - aria_hidden_interactive: Interactive elements with aria-hidden
// - invalid_tabindex: Elements with invalid tabindex values
// - landmark_issues: Multiple landmarks without distinguishing labels

Interpreting Results

Axe-Core Results

{
  "violations": [
    {
      "id": "color-contrast",
      "impact": "serious",  // critical, serious, moderate, minor
      "description": "Elements must have sufficient color contrast",
      "nodes": [
        {
          "html": "<p class=\"text-gray\">Low contrast text</p>",
          "target": [".text-gray"],
          "failureSummary": "Fix any of the following:\n  Element has insufficient color contrast of 3.2:1 (foreground color: #808080, background color: #ffffff, font size: 12.0pt (16px), font weight: normal). Expected contrast ratio of 4.5:1"
        }
      ]
    }
  ],
  "passes": [...],      // Tests that passed
  "incomplete": [...],  // Tests requiring manual review
  "inapplicable": [...]  // Tests not applicable to this page
}

Action Priority:

Critical/Serious violations - Fix immediately
Moderate violations - Fix in current sprint
Minor violations - Fix when convenient
Incomplete - Manually review and test
Passes - Document for compliance

Contrast Check Results

WCAG AA Violations:
  - p:nth-of-type(3): 3.2:1 (required: 4.5:1)
    Text: This text has insufficient contrast
    Colors: rgb(128, 128, 128) on rgb(255, 255, 255)

Remediation:

Darken foreground color or lighten background
Use contrast ratio calculator to find compliant colors
Test with web_contrast_check_cremotemcp_cremotemcp after fixes

Keyboard Test Results

High Severity Issues:
  - not_focusable: Interactive element is not keyboard focusable
    Element: div[role="button"]
  - no_focus_indicator: Interactive element lacks visible focus indicator
    Element: button.submit-btn

Remediation:

not_focusable: Add tabindex="0" or use semantic HTML (<button> instead of <div>)
no_focus_indicator: Add CSS :focus styles with visible outline/border
keyboard_trap: Review JavaScript event handlers and focus management

Zoom Test Results

Zoom 400% ✗ FAIL:
  Horizontal Scroll: true
  Overflowing Elements: 3
  Text Readable: true

Remediation:

Use responsive units (rem, em, %) instead of fixed pixels
Implement CSS media queries for zoom levels
Test with max-width: 100% on images and containers

Reflow Test Results

320px Width ✗ FAIL:
  Horizontal Scroll: true
  Responsive Layout: false
  Overflowing Elements: 5

Remediation:

Implement mobile-first responsive design
Use CSS Grid or Flexbox with flex-wrap
Test with overflow-x: hidden cautiously (may hide content)

Common Workflows

Workflow 1: Token-Efficient Site-Wide Assessment (NEW - RECOMMENDED)

Best for: Multi-page sites, comprehensive audits, token-constrained environments

For each page (10+ pages possible within 200k token limit):

1. Navigate to page
   web_navigate_cremotemcp_cremotemcp({ "url": page_url })

2. Get comprehensive assessment (~4k tokens)
   web_page_accessibility_report_cremotemcp_cremotemcp({
     "tests": ["all"],
     "standard": "WCAG21AA",
     "timeout": 30
   })

3. Capture screenshot for documentation
   web_screenshot_cremotemcp_cremotemcp({
     "output": "screenshots/page-name.png"
   })

4. Analyze results:
   - compliance_status: COMPLIANT, PARTIAL, NON_COMPLIANT
   - legal_risk: LOW, MEDIUM, HIGH, CRITICAL
   - critical_issues, serious_issues (prioritize fixes)
   - estimated_remediation_hours

5. If deep dive needed on specific issues:
   a. web_contrast_audit_cremotemcp_cremotemcp for contrast patterns
   b. web_keyboard_audit_cremotemcp_cremotemcp for keyboard details
   c. web_form_accessibility_audit_cremotemcp_cremotemcp for form issues

Total per page: ~4-6k tokens (vs 80k+ with traditional approach)
Total for 10 pages: ~50k tokens (vs 800k+ with traditional approach)

Workflow 2: Comprehensive New Page Audit (Traditional - Detailed)

Best for: Single page deep dives, when you need raw data

1. Navigate to page
2. Run web_inject_axe_cremotemcp_cremotemcp
3. Run web_run_axe_cremotemcp_cremotemcp with wcag2aa tags
4. Run specialized tests based on page content:
   a. web_contrast_check_cremotemcp_cremotemcp for contrast issues
   b. web_gradient_contrast_check_cremotemcp_cremotemcp for gradient backgrounds
   c. web_media_validation_cremotemcp_cremotemcp if page has video/audio
   d. web_hover_focus_test_cremotemcp_cremotemcp for tooltips/popovers
   e. web_text_in_images_cremotemcp_cremotemcp for infographics/charts
   f. web_sensory_characteristics_cremotemcp_cremotemcp for instructional content
   g. web_animation_flash_cremotemcp_cremotemcp for animated content
   h. web_enhanced_accessibility_cremotemcp_cremotemcp for ARIA validation
   i. web_keyboard_test_cremotemcp_cremotemcp for keyboard issues
5. Run web_zoom_test_cremotemcp_cremotemcp
6. Run web_reflow_test_cremotemcp_cremotemcp
7. Capture screenshots for documentation
8. Generate comprehensive report with all findings

Total per page: ~80-100k tokens

Workflow 3: Regression Testing

1. Navigate to page
2. Run web_run_axe_cremotemcp_cremotemcp
3. Compare results with baseline
4. If new violations:
   a. Run specialized tests for affected areas
   b. Capture screenshots showing issues
5. Report regressions

Workflow 4: Contrast-Focused Audit (Token-Efficient)

1. Navigate to page
2. Run web_contrast_audit_cremotemcp_cremotemcp (~4k tokens)
3. Analyze:
   - critical_failures (top 20 with worst ratios)
   - failure_patterns (grouped similar issues)
4. For each pattern:
   a. Capture screenshot of example
   b. Document current and required contrast ratios
   c. Suggest color adjustments for all instances
5. After fixes, re-run web_contrast_audit_cremotemcp_cremotemcp
6. Verify all violations resolved

Workflow 5: Keyboard Accessibility Audit (Token-Efficient)

1. Navigate to page
2. Run web_keyboard_audit_cremotemcp_cremotemcp (~2k tokens)
3. Analyze:
   - status: PASS, PARTIAL, FAIL
   - issues categorized by type and severity
   - recommendation for next steps
4. For each issue:
   a. Document element and issue type
   b. Suggest remediation (tabindex, semantic HTML, focus styles)
5. After fixes, re-run web_keyboard_audit_cremotemcp_cremotemcp
6. Manually verify complex interactions

Workflow 6: Media Accessibility Audit

1. Navigate to page with video/audio content
2. Run web_media_validation_cremotemcp_cremotemcp
3. For each media element:
   a. Check for caption tracks (WCAG 1.2.2 Level A)
   b. Check for audio description tracks (WCAG 1.2.5 Level AA)
   c. Verify track files are accessible
   d. Check for autoplay violations (WCAG 1.4.2 Level A)
4. Document missing captions/descriptions
5. After fixes, re-run web_media_validation_cremotemcp_cremotemcp
6. Manually verify caption accuracy (not automated)

Workflow 7: Text-in-Images Audit

1. Navigate to page with images
2. Run web_text_in_images_cremotemcp_cremotemcp (allow 30s timeout for OCR)
3. For each image with detected text:
   a. Review detected text vs alt text
   b. If alt text missing: Add comprehensive alt text
   c. If alt text insufficient: Expand to include all text
   d. Consider using real text instead of images
4. Capture screenshots of problematic images
5. After fixes, re-run web_text_in_images_cremotemcp_cremotemcp
6. Verify all images with text have adequate alt text

Workflow 8: Multi-Page Consistency Audit

1. Identify key pages to test (home, about, contact, services, etc.)
2. Run web_cross_page_consistency_cremotemcp_cremotemcp with all URLs
3. Analyze common navigation elements
4. For each inconsistent page:
   a. Document missing navigation links
   b. Check landmark structure (header, footer, main, nav)
   c. Verify navigation order consistency
5. After fixes, re-run web_cross_page_consistency_cremotemcp_cremotemcp
6. Verify all pages have consistent navigation

Workflow 9: Animation Safety Audit

1. Navigate to page with animations
2. Run web_animation_flash_cremotemcp_cremotemcp
3. For each animation:
   a. Check flash rate (must be ≤ 3 flashes/second)
   b. Check for pause/stop controls (if > 5 seconds)
   c. Verify autoplay behavior
4. For violations:
   a. Reduce flash rate or remove flashing
   b. Add pause/stop controls
   c. Disable autoplay or add controls
5. After fixes, re-run web_animation_flash_cremotemcp_cremotemcp
6. Verify no flashing content exceeds 3 flashes/second

Workflow 10: ARIA Validation Audit

1. Navigate to page with interactive elements
2. Run web_enhanced_accessibility_cremotemcp_cremotemcp
3. For each element with issues:
   a. Missing accessible name: Add aria-label or visible text
   b. aria-hidden on interactive: Remove aria-hidden
   c. Invalid tabindex: Use 0 or -1
   d. Multiple landmarks: Add distinguishing labels
4. Capture screenshots of problematic elements
5. After fixes, re-run web_enhanced_accessibility_cremotemcp_cremotemcp
6. Verify all interactive elements have accessible names

Error Handling

Common Errors and Solutions

Error: "Failed to inject library"

Solution: Check network connectivity, try alternative CDN, or increase timeout

Error: "Evaluation timed out"

Solution: Increase timeout parameter, test on smaller page sections

Error: "No tab available"

Solution: Navigate to a page first using web_navigate_cremotemcp_cremotemcp

Error: "Failed to get page"

Solution: Verify tab ID is valid, check if page is still loaded

Best Practices for LLM Agents

1. Use Token-Efficient Tools for Site-Wide Assessments (NEW)

For multi-page sites, always use the summary tools first:

web_page_accessibility_report_cremotemcp_cremotemcp - Comprehensive page assessment (~4k tokens)
web_contrast_audit_cremotemcp_cremotemcp - Smart contrast check (~4k tokens)
web_keyboard_audit_cremotemcp_cremotemcp - Keyboard summary (~2k tokens)
web_form_accessibility_audit_cremotemcp_cremotemcp - Form analysis (~2k tokens)

Benefits:

85-95% token reduction
10+ pages testable vs 3 pages
Structured, actionable results
Compliance status and legal risk assessment

2. Start with Comprehensive Assessment

Use web_page_accessibility_report_cremotemcp_cremotemcp as your foundation. It combines axe-core, contrast, keyboard, and form tests in a single call with intelligent summarization.

3. Test in Logical Order

Token-Efficient Summary → Deep Dive (if needed) → Visual (zoom, reflow) → Documentation (screenshots)

4. Provide Context in Reports

When reporting issues, include:

WCAG criterion violated
Severity/impact level (CRITICAL, SERIOUS, HIGH, MEDIUM)
Specific element(s) affected
Current state (e.g., contrast ratio 3.2:1)
Required state (e.g., contrast ratio 4.5:1)
Suggested remediation
Estimated remediation hours (from summary tools)

5. Capture Evidence

Always capture screenshots when documenting issues:

{
  "tool": "web_screenshot_cremotemcp_cremotemcp",
  "arguments": {
    "output": "/tmp/issue-contrast-button.png"
  }
}

6. Verify Fixes

After suggesting fixes, re-run the relevant tests to verify resolution:

1. Suggest fix
2. Wait for implementation
3. Re-run specific test (use summary tool for efficiency)
4. Confirm issue resolved

7. Know the Limitations

These tools cannot test:

Semantic meaning of content
Cognitive load
Caption accuracy (speech-to-text validation) - Only presence is checked
Complex user interactions
Context-dependent issues (some sensory characteristics need human judgment)
Video frame-by-frame flash analysis (simplified estimation used)
Complex ARIA widget validation (basic validation only)

Always recommend manual testing with assistive technologies for comprehensive audits.

Tool-Specific Limitations:

Summary Tools: Limit examples to 3 per issue, group similar issues into patterns
Gradient Contrast: Complex gradients (radial, conic) may not be fully analyzed
Media Validation: Cannot verify caption accuracy, only presence
Hover/Focus: May miss custom implementations using non-standard patterns
Text-in-Images: OCR struggles with stylized fonts, handwriting, low contrast
Cross-Page: Requires 2+ pages, may flag intentional variations
Sensory Characteristics: Context-dependent, may have false positives
Animation/Flash: Simplified flash rate estimation, no actual frame analysis
Enhanced A11y: Simplified reference validation, doesn't check all ARIA states

8. Token Management Strategy

For site-wide assessments (10+ pages):

Use summary tools exclusively: web_page_accessibility_report_cremotemcp_cremotemcp
Budget ~4-6k tokens per page
Reserve 20-30k tokens for report generation
Total: ~70k tokens for 10 pages + report

For deep dives (1-3 pages):

Use traditional detailed tools
Budget ~80-100k tokens per page
Get raw data for custom analysis

Integration with Development Workflow

Pre-Commit Testing

# Run quick accessibility check before commit
cremote inject-axe && cremote run-axe --run-only wcag2aa

CI/CD Integration

# Run full accessibility suite in CI
- cremote inject-axe
- cremote run-axe > axe-results.json
- cremote contrast-check > contrast-results.txt
- cremote keyboard-test > keyboard-results.txt
- cremote zoom-test > zoom-results.txt
- cremote reflow-test > reflow-results.txt

Pull Request Reviews

1. Run accessibility tests on PR branch
2. Compare with main branch baseline
3. Report new violations in PR comments
4. Block merge if critical violations found

Quick Command Reference

# ===== TOKEN-EFFICIENT SUMMARY TOOLS (NEW - RECOMMENDED) =====

# Comprehensive page assessment (~4k tokens)
cremote page-accessibility-report --tests all --standard WCAG21AA

# Smart contrast audit (~4k tokens)
cremote contrast-audit --priority-selectors "button,a,nav" --threshold AA

# Keyboard navigation audit (~2k tokens)
cremote keyboard-audit --check-focus-indicators --check-tab-order

# Form accessibility audit (~2k tokens)
cremote form-accessibility-audit

# ===== TRADITIONAL DETAILED TOOLS =====

# Inject axe-core
cremote inject-axe

# Run comprehensive tests
cremote run-axe --run-only wcag2a,wcag2aa,wcag21aa

# Check contrast
cremote contrast-check --selector body

# Check gradient contrast
cremote gradient-contrast-check --selector .hero-section

# Validate media captions/descriptions
cremote media-validation

# Test hover/focus content
cremote hover-focus-test

# Detect text in images with OCR
cremote text-in-images

# Check cross-page consistency
cremote cross-page-consistency --urls "https://example.com/,https://example.com/about"

# Detect sensory characteristics
cremote sensory-characteristics

# Detect animations and flashing
cremote animation-flash

# Enhanced ARIA validation
cremote enhanced-accessibility

# Test keyboard navigation
cremote keyboard-test

# Test zoom levels
cremote zoom-test --zoom-levels 1.0,2.0,4.0

# Test responsive design
cremote reflow-test --widths 320,768,1280

# Capture screenshot
cremote screenshot --output /tmp/screenshot.png

# Capture screenshot at zoom level
cremote screenshot --output /tmp/zoom-200.png --zoom-level 2.0

# Capture screenshot at specific viewport
cremote screenshot --output /tmp/mobile.png --width 320 --height 568

# Get accessibility tree
cremote get-accessibility-tree --include-contrast true

# Execute custom JavaScript with library injection
cremote console-command --command "axe.run()" --inject-library axe

Resources

WCAG 2.1 Quick Reference: https://www.w3.org/WAI/WCAG21/quickref/
Axe-Core Rules: https://github.com/dequelabs/axe-core/blob/develop/doc/rule-descriptions.md
Contrast Ratio Calculator: https://contrast-ratio.com/
WebAIM Resources: https://webaim.org/resources/

Coverage Summary

Automated WCAG 2.1 Level AA Coverage: ~93%

The cremote platform provides comprehensive automated testing with two approaches:

Token-Efficient Summary Tools (NEW - 2025-10-03)

Best for: Site-wide assessments, multi-page audits

web_page_accessibility_report_cremotemcp_cremotemcp - Comprehensive assessment (~4k tokens)
web_contrast_audit_cremotemcp_cremotemcp - Smart contrast check (~4k tokens)
web_keyboard_audit_cremotemcp_cremotemcp - Keyboard summary (~2k tokens)
web_form_accessibility_audit_cremotemcp_cremotemcp - Form analysis (~2k tokens)

Benefits:

85-95% token reduction
10+ pages testable (vs 3 pages with traditional tools)
Structured, actionable results
Compliance status and legal risk assessment

Traditional Detailed Tools

Best for: Deep dives, raw data analysis

Core Tools: Axe-core, contrast checking, keyboard testing, zoom/reflow testing
Phase 1 Tools: Gradient contrast, media validation, hover/focus testing
Phase 2 Tools: Text-in-images, cross-page consistency, sensory characteristics
Phase 3 Tools: Animation/flash detection, enhanced ARIA validation

What's Automated (93%):

HTML structure and semantics
Color contrast (simple and gradient backgrounds)
Form labels and validation
Heading structure
Link text and purpose
Image alt text (presence and adequacy)
Keyboard accessibility
Focus indicators
ARIA attributes and roles
Landmark structure
Video/audio captions (presence)
Text-in-images detection
Cross-page consistency
Sensory characteristics
Animation/flash safety
Zoom and responsive design

What Requires Manual Testing (7%):

Caption accuracy (speech-to-text)
Complex cognitive assessments
Subjective content quality
Advanced ARIA widget validation
Video content frame analysis
Context-dependent sensory instructions

Token Usage Comparison

Approach	Single Page	10 Pages	Pages Possible in 200k Budget
Summary Tools (NEW)	~4k tokens	~40k tokens	40+ pages
Traditional Detailed	~80k tokens	~800k tokens	2-3 pages
Savings	95%	95%	13x more pages

For LLM Agents: This guide is designed for programmatic use. Always provide specific, actionable recommendations based on test results. Include WCAG criterion numbers, severity levels, and concrete remediation steps in your reports.

⚠️ IMPORTANT: All cremote MCP tools use the double suffix naming pattern: toolname_cremotemcp_cremotemcp

LATEST UPDATE (2025-10-03): Four new token-efficient summary tools have been added, reducing token usage by 85-95% and enabling comprehensive site-wide assessments. These tools provide structured, actionable results with compliance status, legal risk assessment, and remediation estimates. Use these tools for all multi-page assessments.

PREVIOUS UPDATE (2025-10-02): Eight automated testing tools were added, increasing coverage from 70% to 93%. These tools provide enhanced detection for gradient contrast, media accessibility, hover/focus content, text-in-images, cross-page consistency, sensory characteristics, animations/flashing, and ARIA validation.

33 KiB Raw Blame History

LLM Agent Guide: ADA/WCAG Accessibility Testing with Cremote

Purpose

⚠️ IMPORTANT: Tool Naming Convention

Quick Reference

Token-Efficient Summary Tools (NEW - 2025-10-03)

Tool Selection Matrix

Recommended Testing Sequences

Option 1: Token-Efficient Approach (RECOMMENDED for site-wide assessments)

Option 2: Detailed Testing Approach (for deep dives)

Option 3: Hybrid Approach (balanced)

Tool Usage Patterns

Pattern 1: Token-Efficient Page Assessment (NEW - RECOMMENDED)

Pattern 2: Initial Audit (Traditional Approach)

Pattern 3: Smart Contrast Audit (NEW - RECOMMENDED)

Pattern 4: Contrast-Specific Testing (Traditional)

Pattern 5: Smart Keyboard Audit (NEW - RECOMMENDED)

Pattern 6: Keyboard Navigation Testing (Traditional)

Pattern 7: Form Accessibility Audit (NEW)

Pattern 8: Zoom and Responsive Testing

Pattern 9: Visual Documentation

Pattern 10: Gradient Contrast Testing

Pattern 11: Media Validation

Pattern 12: Hover/Focus Content Testing

Pattern 13: Text-in-Images Detection

Pattern 14: Cross-Page Consistency

Pattern 15: Sensory Characteristics Detection

Pattern 16: Animation/Flash Detection

Pattern 17: Enhanced ARIA Validation

Interpreting Results

Axe-Core Results

Contrast Check Results

Keyboard Test Results

Zoom Test Results

Reflow Test Results

Common Workflows

Workflow 1: Token-Efficient Site-Wide Assessment (NEW - RECOMMENDED)

Workflow 2: Comprehensive New Page Audit (Traditional - Detailed)

Workflow 3: Regression Testing

Workflow 4: Contrast-Focused Audit (Token-Efficient)

Workflow 5: Keyboard Accessibility Audit (Token-Efficient)

Workflow 6: Media Accessibility Audit

Workflow 7: Text-in-Images Audit

Workflow 8: Multi-Page Consistency Audit

Workflow 9: Animation Safety Audit

Workflow 10: ARIA Validation Audit

Error Handling

Common Errors and Solutions

Best Practices for LLM Agents

1. Use Token-Efficient Tools for Site-Wide Assessments (NEW)

2. Start with Comprehensive Assessment

3. Test in Logical Order

4. Provide Context in Reports

5. Capture Evidence

6. Verify Fixes

7. Know the Limitations

8. Token Management Strategy

Integration with Development Workflow

Pre-Commit Testing

CI/CD Integration

Pull Request Reviews

Quick Command Reference

Resources

Coverage Summary

Token-Efficient Summary Tools (NEW - 2025-10-03)

Traditional Detailed Tools

Token Usage Comparison

33 KiB

Raw Blame History