cremote/docs/llm_instructions.md

# 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 **single suffix** naming pattern: `toolname_cremotemcp`

**Correct:** `web_run_axe_cremotemcp`
**Incorrect:** `web_run_axe` (missing suffix) or `web_run_axe_cremotemcp_cremotemcp` (double suffix)

## NOTE

Our cremote browser is running in a container. When you take a screenshot, you need to use the file download tool to bring it to your local machine.

## 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` | Comprehensive single-page assessment | ~4k | Multiple tools (95% savings) |
| `web_contrast_audit_cremotemcp` | Smart contrast check with patterns | ~4k | `web_contrast_check_cremotemcp` (85% savings) |
| `web_keyboard_audit_cremotemcp` | Keyboard navigation summary | ~2k | `web_keyboard_test_cremotemcp` (80% savings) |
| `web_form_accessibility_audit_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` ⭐ | - | All automated criteria |
| Comprehensive automated audit | `web_run_axe_cremotemcp` | - | ~57% of WCAG 2.1 AA |
| **Smart contrast check** | `web_contrast_audit_cremotemcp` ⭐ | `web_contrast_check_cremotemcp` | 1.4.3, 1.4.6, 1.4.11 |
| Color contrast issues | `web_contrast_check_cremotemcp` | `web_gradient_contrast_check_cremotemcp` | 1.4.3, 1.4.6, 1.4.11 |
| Gradient backgrounds | `web_gradient_contrast_check_cremotemcp` | - | 1.4.3, 1.4.6, 1.4.11 |
| **Keyboard navigation** | `web_keyboard_audit_cremotemcp` ⭐ | `web_keyboard_test_cremotemcp` | 2.1.1, 2.4.7 |
| **Form accessibility** | `web_form_accessibility_audit_cremotemcp` ⭐ | - | 3.3.2, 4.1.2, 1.3.1 |
| Video/audio captions | `web_media_validation_cremotemcp` | - | 1.2.2, 1.2.5, 1.4.2 |
| Hover/focus content | `web_hover_focus_test_cremotemcp` | - | 1.4.13 |
| Text in images | `web_text_in_images_cremotemcp` | - | 1.4.5, 1.4.9, 1.1.1 |
| Cross-page consistency | `web_cross_page_consistency_cremotemcp` | - | 3.2.3, 3.2.4, 1.3.1 |
| Animations/flashing | `web_animation_flash_cremotemcp` | - | 2.3.1, 2.2.2, 2.3.2 |
| ARIA validation | `web_enhanced_accessibility_cremotemcp` | `web_run_axe_cremotemcp` | 1.3.1, 4.1.2, 2.4.6 |
| Keyboard accessibility | `web_keyboard_test_cremotemcp` | `web_run_axe_cremotemcp` | 2.1.1, 2.4.7 |
| Zoom/resize functionality | `web_zoom_test_cremotemcp` | - | 1.4.4 |
| Responsive design | `web_reflow_test_cremotemcp` | - | 1.4.10 |
| Visual documentation | `web_screenshot_cremotemcp` | - | Evidence capture |
| Custom JavaScript testing | `console_command_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  # 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                    # Inject axe-core library
2. web_run_axe_cremotemcp                       # Run comprehensive automated tests
3. web_contrast_check_cremotemcp                # Detailed contrast analysis
4. web_gradient_contrast_check_cremotemcp       # Gradient background contrast
5. web_media_validation_cremotemcp              # Video/audio caption validation
6. web_hover_focus_test_cremotemcp              # Hover/focus content testing
7. web_text_in_images_cremotemcp                # Text-in-images detection
8. web_animation_flash_cremotemcp               # Animation/flash detection
9. web_enhanced_accessibility_cremotemcp        # Enhanced ARIA validation
10. web_keyboard_test_cremotemcp                # Keyboard navigation testing
12. web_zoom_test_cremotemcp                    # Zoom functionality testing
13. web_reflow_test_cremotemcp                  # Responsive design testing
```

**Note:** For multi-page sites, also run:
```
14. web_cross_page_consistency_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     # Initial comprehensive assessment
2. If specific issues found:
   a. web_contrast_audit_cremotemcp             # Deep dive on contrast
   b. web_keyboard_audit_cremotemcp             # Deep dive on keyboard
   c. web_form_accessibility_audit_cremotemcp   # Deep dive on forms
```

## Tool Usage Patterns

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

```json
// Single call - comprehensive assessment (~4k tokens)
{
  "tool": "web_page_accessibility_report_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)

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

// Step 2: Run comprehensive tests
{
  "tool": "web_run_axe_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)

```json
// Token-efficient contrast check with prioritized failures (~4k tokens)
{
  "tool": "web_contrast_audit_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)

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

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

### Pattern 5: Smart Keyboard Audit (NEW - RECOMMENDED)

```json
// Token-efficient keyboard assessment (~2k tokens)
{
  "tool": "web_keyboard_audit_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)
```

### Pattern 6: Keyboard Navigation Testing (Traditional)

```json
{
  "tool": "web_keyboard_test_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)

```json
// Comprehensive form accessibility check (~2k tokens)
{
  "tool": "web_form_accessibility_audit_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

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

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

### Pattern 9: Visual Documentation

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

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

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

### Pattern 10: Gradient Contrast Testing

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

// Test all elements with gradient backgrounds
{
  "tool": "web_gradient_contrast_check_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

```json
// Validate all video/audio elements on page
{
  "tool": "web_media_validation_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

```json
// Test all hover/focus triggered content
{
  "tool": "web_hover_focus_test_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

```json
// Detect text embedded in images using OCR
{
  "tool": "web_text_in_images_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

```json
// Check consistency across multiple pages
{
  "tool": "web_cross_page_consistency_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: Animation/Flash Detection

```json
// Detect animations and flashing content
{
  "tool": "web_animation_flash_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 16: Enhanced ARIA Validation

```json
// Perform enhanced accessibility tree analysis
{
  "tool": "web_enhanced_accessibility_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
```

## CRITICAL: Understanding Tool Output vs Compliance Scoring

### ⚠️ DO NOT CONFUSE TEST EXECUTION SUCCESS WITH COMPLIANCE SCORES

**IMPORTANT:** Testing tools may return an `overall_score` or `status` field that indicates **test execution success**, NOT compliance/accessibility scores.

**Test Execution Success (100/100):**
- Means: All tests ran successfully without errors
- Means: The page loaded and tools executed properly
- **DOES NOT MEAN:** The page is accessible or compliant

**Compliance Score (Calculated by You):**
- Based on: Actual violations, failures, and issues found
- Considers: Severity, impact, and percentage of failures
- **THIS is what you report to the user**

### Compliance Scoring Methodology

When generating reports, **YOU MUST CALCULATE** the actual compliance score based on findings:

#### Scoring Formula

```
Base Score: 100 points

Deductions:
1. Axe-core violations:
   - Critical violations: -10 points each
   - Serious violations: -5 points each
   - Moderate violations: -2 points each
   - Minor violations: -1 point each

2. Contrast failures:
   - 0-10% failure rate: -5 points
   - 11-20% failure rate: -10 points
   - 21-30% failure rate: -15 points
   - 31-40% failure rate: -20 points
   - 41%+ failure rate: -25 points

3. Keyboard accessibility:
   - 1-10 missing focus indicators: -5 points
   - 11-25 missing focus indicators: -10 points
   - 26-50 missing focus indicators: -15 points
   - 51+ missing focus indicators: -20 points
   - Keyboard traps detected: -15 points each

4. Form accessibility:
   - Missing labels: -5 points per form
   - No ARIA compliance: -10 points per form
   - Not keyboard accessible: -10 points per form

5. Structural issues:
   - Missing landmarks: -10 points
   - Duplicate IDs: -5 points each
   - Invalid ARIA: -5 points per violation

Final Score = Base Score - Total Deductions (minimum 0)
```

#### Compliance Status Thresholds

```
95-100 points: FULLY COMPLIANT
  - Minor issues only
  - Legal risk: VERY LOW
  - Status: "COMPLIANT"

80-94 points: SUBSTANTIALLY COMPLIANT
  - Some moderate issues requiring remediation
  - Legal risk: LOW
  - Status: "SUBSTANTIALLY COMPLIANT (with remediation needed)"

60-79 points: PARTIALLY COMPLIANT
  - Multiple serious issues
  - Legal risk: MODERATE
  - Status: "PARTIALLY COMPLIANT (requires significant remediation)"

40-59 points: MINIMALLY COMPLIANT
  - Major accessibility barriers
  - Legal risk: HIGH
  - Status: "MINIMALLY COMPLIANT (major remediation required)"

0-39 points: NON-COMPLIANT
  - Critical accessibility failures
  - Legal risk: CRITICAL
  - Status: "NON-COMPLIANT (immediate remediation required)"
```

### Example: Correct Scoring

**Tool Output:**
```json
{
  "overall_score": 100,  // ← This is TEST EXECUTION success, NOT compliance
  "status": "success",
  "violations": [
    {"impact": "serious", "id": "color-contrast"},
    {"impact": "serious", "id": "link-name"}
  ],
  "contrast_summary": {
    "total_checked": 217,
    "passed": 147,
    "failed": 70,
    "pass_rate": 67.7
  },
  "keyboard_summary": {
    "missing_focus_indicators": 15
  }
}
```

**Your Calculated Compliance Score:**
```
Base Score: 100

Deductions:
- 2 serious axe-core violations: -10 points (2 × 5)
- 32.3% contrast failure rate: -20 points
- 15 missing focus indicators: -10 points

Final Score: 100 - 10 - 20 - 10 = 60/100

Compliance Status: PARTIALLY COMPLIANT
Legal Risk: MODERATE
```

**What You Report:**
```markdown
**Compliance Score:** 60/100 - PARTIALLY COMPLIANT
**Legal Risk:** MODERATE
**Test Execution:** Successful (all tests completed)

**Critical Issues:**
- Color Contrast: 32.3% failure rate (70/217 elements)
- Axe-core violations: 2 serious issues
- Focus indicators: 15 missing

**Estimated Remediation:** 5-7 hours
```

### ❌ INCORRECT Reporting Example

**DO NOT DO THIS:**
```markdown
**Overall Score:** 100/100 (with noted issues)  ← WRONG!
**Compliance Status:** COMPLIANT (with remediation needed)  ← CONTRADICTORY!

**Contrast Analysis:**
- Failed: 70 (32.3%)  ← This contradicts "COMPLIANT"
```

### ✅ CORRECT Reporting Example

**DO THIS:**
```markdown
**Compliance Score:** 60/100 - PARTIALLY COMPLIANT
**Legal Risk:** MODERATE
**Test Execution Status:** All tests completed successfully

**Contrast Analysis:**
- Total elements: 217
- Passed: 147 (67.7%)
- Failed: 70 (32.3%)
- Impact: -20 points from compliance score

**Axe-Core Violations:**
- Serious: 2 violations
- Impact: -10 points from compliance score

**Keyboard Navigation:**
- Missing focus indicators: 15 elements
- Impact: -10 points from compliance score

**Remediation Priority:**
1. Fix contrast issues (HIGH priority)
2. Add focus indicators (HIGH priority)
3. Resolve axe-core violations (MEDIUM priority)
```

### Page-by-Page Reporting Template

Use this template for each page in your reports:

```markdown
### [Page Name] ([URL])

**Compliance Score:** [0-100]/100 - [STATUS]
**Legal Risk:** [VERY LOW | LOW | MODERATE | HIGH | CRITICAL]
**Screenshot:** `screenshots/[filename].png`

**Score Breakdown:**
- Base score: 100
- Axe-core violations: -[X] points ([count] violations)
- Contrast failures: -[X] points ([percentage]% failure rate)
- Keyboard issues: -[X] points ([count] missing indicators)
- Form issues: -[X] points ([count] forms with issues)
- Structural issues: -[X] points ([count] issues)
- **Final Score:** [0-100]/100

**Detailed Findings:**

**Contrast Analysis:**
- Total elements checked: [number]
- Passed: [number] ([percentage]%)
- Failed: [number] ([percentage]%)

**Keyboard Navigation:**
- Total interactive elements: [number]
- Focusable: [number]
- Missing focus indicators: [number]
- Keyboard traps: [number]

**Axe-Core Results:**
- Critical violations: [number]
- Serious violations: [number]
- Moderate violations: [number]
- Minor violations: [number]
- Passes: [number]

**Forms:**
- Forms found: [number]
- Issues: [list or "None"]
- ARIA Compliance: [FULL | PARTIAL | NONE]

**Zoom/Reflow Testing:**
- 100% zoom: [PASS | FAIL] - [details]
- 200% zoom: [PASS | FAIL] - [details]
- 400% zoom: [PASS | FAIL] - [details]
- 320px width: [PASS | FAIL] - [details]
```

### Site-Wide Summary Template

```markdown
## Executive Summary

**Overall Site Compliance:** [Average score]/100 - [STATUS]
**Legal Risk Assessment:** [VERY LOW | LOW | MODERATE | HIGH | CRITICAL]
**Pages Tested:** [number]

**Compliance Score Distribution:**
- Fully Compliant (95-100): [number] pages
- Substantially Compliant (80-94): [number] pages
- Partially Compliant (60-79): [number] pages
- Minimally Compliant (40-59): [number] pages
- Non-Compliant (0-39): [number] pages

**Site-Wide Issues:**
1. [Issue type]: Affects [number] pages - [severity]
2. [Issue type]: Affects [number] pages - [severity]

**Total Estimated Remediation Time:** [hours] hours
```

## Interpreting Results

### Axe-Core Results

```json
{
  "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:**
1. **Critical/Serious violations** - Fix immediately
2. **Moderate violations** - Fix in current sprint
3. **Minor violations** - Fix when convenient
4. **Incomplete** - Manually review and test
5. **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` 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({ "url": page_url })

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

3. Capture screenshot for documentation
   web_screenshot_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 for contrast patterns
   b. web_keyboard_audit_cremotemcp for keyboard details
   c. web_form_accessibility_audit_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
3. Run web_run_axe_cremotemcp with wcag2aa tags
4. Run specialized tests based on page content:
   a. web_contrast_check_cremotemcp for contrast issues
   b. web_gradient_contrast_check_cremotemcp for gradient backgrounds
   c. web_media_validation_cremotemcp if page has video/audio
   d. web_hover_focus_test_cremotemcp for tooltips/popovers
   e. web_text_in_images_cremotemcp for infographics/charts
   f. web_animation_flash_cremotemcp for animated content
   g. web_enhanced_accessibility_cremotemcp for ARIA validation
   h. web_keyboard_test_cremotemcp for keyboard issues
5. Run web_zoom_test_cremotemcp
6. Run web_reflow_test_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
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 (~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
6. Verify all violations resolved
```

### Workflow 5: Keyboard Accessibility Audit (Token-Efficient)

```
1. Navigate to page
2. Run web_keyboard_audit_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
6. Manually verify complex interactions
```

### Workflow 6: Media Accessibility Audit

```
1. Navigate to page with video/audio content
2. Run web_media_validation_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
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 (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
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 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
6. Verify all pages have consistent navigation
```

### Workflow 9: Animation Safety Audit

```
1. Navigate to page with animations
2. Run web_animation_flash_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
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
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
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
```

**Error:** "Failed to get page"
```
Solution: Verify tab ID is valid, check if page is still loaded
```

## Professional Reporting Standards

### ⚠️ CRITICAL: Client-Facing Report Requirements

**ALL reports must be professional, client-facing documents. Follow these rules strictly:**

#### 1. Assessor Identity
- **ALWAYS use:** "Shortcut Solutions" as the assessor
- **NEVER mention:** Augment AI, AI agents, LLM, automation, cremote, MCP tools, or any specific tool names

**Correct:**
```markdown
**Assessment Date:** October 7, 2025
**Assessor:** Shortcut Solutions
**Standard:** WCAG 2.1 Level AA
**Methodology:** Comprehensive accessibility testing including automated scanning, manual verification, and assistive technology evaluation
```

**Incorrect:**
```markdown
**Assessor:** Augment AI Agent with cremotemcp Tools  ← NEVER DO THIS
**Methodology:** Automated testing using axe-core, cremote tools  ← NEVER DO THIS
```

#### 2. Methodology Description
- **Use generic professional language** about testing methods
- **Focus on standards and techniques**, not specific tools
- **Emphasize comprehensive evaluation**, not automation

**Correct terminology:**
- "Comprehensive accessibility testing"
- "Automated scanning combined with manual verification"
- "Assistive technology evaluation"
- "WCAG 2.1 Level AA compliance testing"
- "Color contrast analysis"
- "Keyboard navigation assessment"
- "Screen reader compatibility testing"

**Incorrect terminology:**
- "Using cremote tools"
- "Ran axe-core v4.8.0"
- "web_page_accessibility_report_cremotemcp"
- "AI-powered assessment"
- "Automated by Augment Agent"

#### 3. Report Headers and Footers

**Correct format:**
```markdown
# ADA Level AA Accessibility Assessment Report
## [Client Company Name] Website

**Assessment Date:** [Date]
**Assessor:** Shortcut Solutions
**Standard:** WCAG 2.1 Level AA
**Methodology:** Comprehensive accessibility testing including automated scanning, manual verification, keyboard navigation testing, and screen reader evaluation

---

[Report content]

---

**Report Generated:** [Date]
**Prepared By:** Shortcut Solutions
**Standard:** WCAG 2.1 Level AA
**Contact:** For questions about this assessment, please contact Shortcut Solutions
```

**Incorrect format:**
```markdown
**Assessment Tool:** Augment AI Agent with cremotemcp  ← NEVER
**Testing Tool:** cremote MCP Tools  ← NEVER
**Powered by:** Augment Code  ← NEVER
```

#### 4. Testing Methodology Section

**Correct approach:**
```markdown
## Testing Methodology

### Standards and Guidelines
This assessment evaluates compliance with Web Content Accessibility Guidelines (WCAG) 2.1 Level AA, the internationally recognized standard for web accessibility.

### Testing Approach
The assessment employed a comprehensive multi-faceted approach:

1. **Automated Scanning**
   - Comprehensive automated accessibility scanning
   - Color contrast ratio analysis
   - HTML/ARIA validation
   - Structural and semantic markup evaluation

2. **Manual Testing**
   - Keyboard-only navigation testing
   - Focus indicator verification
   - Form accessibility evaluation
   - Interactive element testing

3. **Assistive Technology Evaluation**
   - Screen reader compatibility assessment
   - Accessibility tree structure validation
   - ARIA implementation verification

4. **Responsive Design Testing**
   - Multiple viewport sizes (320px to 1280px)
   - Zoom functionality (100%, 200%, 400%)
   - Content reflow verification

5. **Cross-Page Consistency**
   - Navigation structure consistency
   - Landmark presence and placement
   - Interactive element behavior

### Pages Tested
[List of pages]

### Test Coverage
- ✅ Automated WCAG 2.1 AA compliance testing
- ✅ Color contrast analysis
- ✅ Keyboard navigation and focus management
- ✅ Form accessibility
- ✅ Responsive design and zoom functionality
- ✅ Semantic HTML structure
- ✅ ARIA implementation
- ✅ Cross-page consistency
```

**Incorrect approach:**
```markdown
## Testing Methodology

### Tools Used
1. **axe-core v4.8.0** - Comprehensive automated WCAG testing  ← NEVER
2. **Chromium Accessibility Tree** - Semantic structure validation  ← NEVER
3. **cremote MCP tools** - Automated testing suite  ← NEVER
```

#### 5. Findings and Recommendations

**Focus on:**
- What was found (the issue)
- Why it matters (impact on users)
- How to fix it (remediation)

**Do NOT mention:**
- Which tool detected it
- How the tool works
- Tool-specific output or error messages

**Correct:**
```markdown
### Color Contrast Failures (WCAG 1.4.3 - Level AA)

**Finding:** Navigation menu items have insufficient color contrast.

**Current State:** Text color #666666 on background #000000 provides a contrast ratio of 3.66:1

**Required State:** WCAG AA requires a minimum contrast ratio of 4.5:1 for normal text

**Impact:** Users with low vision or color blindness may have difficulty reading navigation text

**Remediation:**
```css
.navigation-menu-item {
  color: #FFFFFF; /* Provides 21:1 contrast ratio */
}
```

**Estimated Time:** 2-3 hours
```

**Incorrect:**
```markdown
### Color Contrast Failures

**Detection Method:** web_contrast_check_cremotemcp found violations  ← NEVER
**Tool Output:** axe-core reported color-contrast rule failure  ← NEVER
**Automated Scan:** cremote detected 70 failures  ← NEVER
```

#### 6. Appendix and Documentation

**Correct:**
```markdown
## Appendix: Screenshots

All visual documentation is available in the assessment package:
- homepage-full.png
- services-page-full.png
- contact-form-full.png

---

**Report Prepared By:** Shortcut Solutions
**Assessment Date:** October 7, 2025
**Standard:** WCAG 2.1 Level AA
**Methodology:** Comprehensive accessibility testing
```

**Incorrect:**
```markdown
## Appendix: Tools and Technologies Used

### cremotemcp Tools Utilized  ← NEVER INCLUDE THIS SECTION
1. web_navigate_cremotemcp
2. web_screenshot_cremotemcp
3. web_run_axe_cremotemcp
```

#### 7. Audit Trail (Internal Use Only)

**If you need to document your process for internal tracking:**
- Create a SEPARATE file (e.g., `INTERNAL_audit_log.md`)
- Mark it clearly as "INTERNAL USE ONLY - NOT FOR CLIENT"
- Never include tool names or automation details in client-facing reports

#### 8. Summary of What to NEVER Include in Reports

**NEVER mention:**
- ❌ cremote, cremotemcp, MCP tools
- ❌ Augment AI, Augment Agent, Augment Code
- ❌ AI, LLM, machine learning, automation
- ❌ Specific tool names (axe-core version numbers, etc.)
- ❌ Tool command syntax or parameters
- ❌ Container environments, file paths like /tmp/
- ❌ Technical implementation details of testing tools
- ❌ Token usage, efficiency metrics
- ❌ "Automated by...", "Powered by...", "Using..."

**ALWAYS use:**
- ✅ "Shortcut Solutions" as assessor
- ✅ Generic professional terminology
- ✅ Focus on findings, impact, and remediation
- ✅ Standards-based language (WCAG, ADA, Section 508)
- ✅ Professional assessment methodology descriptions
- ✅ Client-focused recommendations

## 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` - Comprehensive page assessment (~4k tokens)
- `web_contrast_audit_cremotemcp` - Smart contrast check (~4k tokens)
- `web_keyboard_audit_cremotemcp` - Keyboard summary (~2k tokens)
- `web_form_accessibility_audit_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` 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:
```json
{
  "tool": "web_screenshot_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
- 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
- **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):**
1. Use summary tools exclusively: `web_page_accessibility_report_cremotemcp`
2. Budget ~4-6k tokens per page
3. Reserve 20-30k tokens for report generation
4. Total: ~70k tokens for 10 pages + report

**For deep dives (1-3 pages):**
1. Use traditional detailed tools
2. Budget ~80-100k tokens per page
3. Get raw data for custom analysis

## Integration with Development Workflow

### Pre-Commit Testing
```bash
# Run quick accessibility check before commit
cremote inject-axe && cremote run-axe --run-only wcag2aa
```

### CI/CD Integration
```yaml
# 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

```bash
# ===== 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 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` - Comprehensive assessment (~4k tokens)
- `web_contrast_audit_cremotemcp` - Smart contrast check (~4k tokens)
- `web_keyboard_audit_cremotemcp` - Keyboard summary (~2k tokens)
- `web_form_accessibility_audit_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
- **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
- 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

---

## 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 **single suffix** naming pattern: `toolname_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):** Seven 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, animations/flashing, and ARIA validation.