shortcut/cremote
1
0
Fork 0
Code Issues Pull Requests Packages Projects Releases Wiki Activity

bump

Browse Source
This commit is contained in:
Josh at WLTechBlog
2025-10-16 10:54:37 -05:00
parent ccd8c77a3e
commit 4d55acca95
45 changed files with 8499 additions and 2416 deletions
Download Patch File Download Diff File Expand all files Collapse all files

299
docs/llm_instructions.md
View File

@@ -1,256 +1,91 @@
# LLM Agent Guide: ADA/WCAG Accessibility Testing with Cremote
# Cremote MCP: Accessibility Testing Guide
## Purpose
This document provides LLM coding agents with concrete, actionable guidance for using Cremote's accessibility testing tools to conduct ADA/WCAG compliance audits.
## Tool Naming
All tools use suffix `_cremotemcp`: `web_run_axe_cremotemcp` (NOT `web_run_axe` or `web_run_axe_cremotemcp_cremotemcp`)
## ⚠️ IMPORTANT: Tool Naming Convention
All cremote MCP tools use the **single suffix** naming pattern: `toolname_cremotemcp`
## Container File Handling
Browser runs in container. File transfers are automatic:
- **Screenshots**: Specify local path → auto-downloads from container
- **Uploads**: Pass local path to `web_interact_cremotemcp` action="upload" → auto-transfers to container
- **Browser downloads**: Use `file_download_cremotemcp` to transfer from container
**Correct:** `web_run_axe_cremotemcp`
**Incorrect:** `web_run_axe` (missing suffix) or `web_run_axe_cremotemcp_cremotemcp` (double suffix)
## Token-Efficient Tools (Use First)
| Tool | Tokens | Use Case |
|------|--------|----------|
| `web_page_accessibility_report_cremotemcp` | ~4k | Full page audit (axe+contrast+keyboard+forms) |
| `web_contrast_audit_cremotemcp` | ~4k | Contrast failures with patterns |
| `web_keyboard_audit_cremotemcp` | ~2k | Keyboard navigation summary |
| `web_form_accessibility_audit_cremotemcp` | ~2k | Form accessibility |
## NOTE
## Tool Selection
| Need | Tool | WCAG |
|------|------|------|
| Full page audit | `web_page_accessibility_report_cremotemcp` | All |
| Automated audit | `web_run_axe_cremotemcp` | ~57% WCAG 2.1 AA |
| Contrast | `web_contrast_audit_cremotemcp` | 1.4.3, 1.4.6, 1.4.11 |
| Gradient contrast | `web_gradient_contrast_check_cremotemcp` | 1.4.3, 1.4.6, 1.4.11 |
| Keyboard | `web_keyboard_audit_cremotemcp` | 2.1.1, 2.4.7 |
| Forms | `web_form_accessibility_audit_cremotemcp` | 3.3.2, 4.1.2, 1.3.1 |
| Media captions | `web_media_validation_cremotemcp` | 1.2.2, 1.2.5, 1.4.2 |
| Hover/focus | `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 | `web_cross_page_consistency_cremotemcp` | 3.2.3, 3.2.4 |
| Animations | `web_animation_flash_cremotemcp` | 2.3.1, 2.2.2 |
| ARIA | `web_enhanced_accessibility_cremotemcp` | 1.3.1, 4.1.2 |
| Zoom | `web_zoom_test_cremotemcp` | 1.4.4 |
| Responsive | `web_reflow_test_cremotemcp` | 1.4.10 |
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.
## Testing Sequences
## 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:**
### Multi-page (10+ pages): Use token-efficient tools
```
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)
Per page: web_page_accessibility_report_cremotemcp (~4k tokens)
Total 10 pages: ~40k tokens
```
**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:**
### Single page deep dive: Use detailed tools
```
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
1. web_inject_axe_cremotemcp
2. web_run_axe_cremotemcp
3. web_contrast_check_cremotemcp
4. web_keyboard_test_cremotemcp
5. web_zoom_test_cremotemcp
6. web_reflow_test_cremotemcp
```
**Note:** For multi-page sites, also run:
## Usage Examples
### Full page audit (~4k tokens)
```
14. web_cross_page_consistency_cremotemcp # Cross-page consistency
web_page_accessibility_report_cremotemcp:
tests: ["all"]
standard: "WCAG21AA"
timeout: 30
Returns: compliance_status, overall_score, legal_risk, issues by severity, remediation_hours
```
#### Option 3: Hybrid Approach (balanced)
**Use summary tools for initial assessment, detailed tools for specific issues:**
### Contrast audit (~4k tokens)
```
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
web_contrast_audit_cremotemcp:
priority_selectors: ["button", "a", "nav"]
threshold: "AA"
Returns: pass_rate, critical_failures (top 20), failure_patterns
```
## 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
### Keyboard audit (~2k tokens)
```
web_keyboard_audit_cremotemcp:
check_focus_indicators: true
check_tab_order: true
check_keyboard_traps: true
Returns: status, issues by type/severity, recommendations
```
### 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
### Form audit (~2k tokens)
```
### 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
web_form_accessibility_audit_cremotemcp:
form_selector: "" # all forms
Returns: forms with issues, aria_compliance, keyboard_accessible
```
### Pattern 8: Zoom and Responsive Testing