webflow-mcp:accessibility-audit

What this skill does

# Accessibility Audit

Comprehensive WCAG 2.1 accessibility audit for Webflow pages with detailed issue detection and actionable fixes.

## Important Note

**ALWAYS use Webflow MCP tools for all operations:**
- Use Webflow MCP's `webflow_guide_tool` to get best practices before starting
- Use Webflow MCP's `data_sites_tool` with action `list_sites` to identify available sites
- Use Webflow MCP's `data_sites_tool` with action `get_site` to retrieve site details
- Use Webflow MCP's `data_pages_tool` with action `list_pages` to get all pages
- Use Webflow MCP's `element_tool` with action `get_all_elements` to get detailed element information (requires Designer)
- Use Webflow MCP's `element_tool` with action `add_or_update_attribute` to fix accessibility issues (requires Designer)
- Use Webflow MCP's `element_snapshot_tool` to get visual previews of elements
- DO NOT use any other tools or methods for Webflow operations
- All tool calls must include the required `context` parameter (15-25 words, third-person perspective)
- **Designer connection required** - This skill needs Designer to access element attributes and styles

## Instructions

### Phase 1: Site & Page Selection
1. **Get site information**: Use Webflow MCP's `data_sites_tool` with action `list_sites` to identify target site
2. **Ask for page selection**:
   - If user provides page ID, use it directly
   - Otherwise, use `data_pages_tool` with action `list_pages` to show available pages
   - Let user select which page(s) to audit
3. **Confirm audit scope**: Ask user what to check:
   - Full audit (all accessibility checks)
   - Critical issues only (WCAG Level A)
   - Specific categories (forms, buttons, navigation, etc.)

### Phase 2: Element Extraction & Analysis
4. **Ensure Designer is connected**: Before proceeding, verify Webflow Designer is open and connected
   - If not connected, instruct user to open Designer and connect
   - This is required to access element attributes and styles
5. **Switch to target page**: Use `de_page_tool` with action `switch_page` to navigate to the page being audited
6. **Extract all elements**: Use `element_tool` with action `get_all_elements` for detailed analysis
   - Set `include_style_properties: true` to check focus styles
   - Set `include_all_breakpoint_styles: false` to minimize data
7. **Parse element data**: Identify interactive and content elements:
   - Buttons (Button, LinkBlock with button role)
   - Links (TextLink, Link, LinkBlock)
   - Form inputs (Input, Select, Textarea)
   - Headings (Heading elements with levels)
   - Interactive divs/spans (check for onClick or interactive roles)
   - Images (Image elements) - **SKIP for this audit**
8. **Extract attributes for each element**:
   - ARIA attributes (aria-label, aria-describedby, role, tabIndex)
   - DOM attributes (id, domId, href, type, placeholder)
   - Text content
   - Style properties (outline, border for focus states)
   - Element metadata (canHaveAttributes, tag name)

### Phase 3: Accessibility Checks

#### Critical Issues (Must Fix - WCAG Level A)
9. **Icon-only buttons without labels** (WCAG 4.1.2)
   - Find: Button elements with no text content
   - Check: Missing `aria-label` or `aria-labelledby`
   - Impact: Screen readers cannot identify button purpose
   - Fix: Add `aria-label` attribute with descriptive text

10. **Form inputs without labels** (WCAG 1.3.1)
    - Find: Input, Select, Textarea elements
    - Check: Missing associated label or `aria-label`
    - Impact: Users don't know what input is for
    - Fix: Add `aria-label` or associate with `<label>` using `id`

11. **Non-semantic click handlers** (WCAG 2.1.1)
    - Find: Div or Span elements (identified by element type)
    - Check: Interactive behavior without proper role/keyboard support
    - Impact: Not keyboard accessible, screen readers miss interactivity
    - Fix: Add `role="button"`, `tabIndex="0"`, suggest using real `<button>`

12. **Links without destination** (WCAG 2.1.1)
    - Find: Link elements with no `href` attribute
    - Check: Links that only use onClick without href
    - Impact: Not keyboard accessible, breaks browser features
    - Fix: Add proper `href` or convert to button

#### Serious Issues (Should Fix - WCAG Level AA)
13. **Focus outline removed without replacement** (WCAG 2.4.7)
    - Find: Elements with `outline: none` style
    - Check: No visible alternative focus indicator
    - Impact: Keyboard users can't see focus
    - Fix: Add visible focus style (border, box-shadow, background change)

14. **Missing keyboard handlers** (WCAG 2.1.1)
    - Find: Elements with onClick handlers
    - Check: Missing onKeyDown for Enter/Space keys
    - Impact: Not usable with keyboard alone
    - Fix: Add keyboard event handlers

15. **Touch target too small** (WCAG 2.5.5)
    - Find: Clickable elements (buttons, links)
    - Check: Width or height < 44px
    - Impact: Hard to tap on mobile devices
    - Fix: Increase padding or min-width/min-height to 44px

#### Moderate Issues (Consider Fixing)
16. **Heading hierarchy problems** (WCAG 1.3.1)
    - Find: Heading elements (h1-h6)
    - Check: Skipped levels (h1 → h3, skipping h2)
    - Impact: Confusing document structure
    - Fix: Use proper sequential heading levels

17. **Positive tabIndex** (WCAG 2.4.3)
    - Find: Elements with tabIndex > 0
    - Check: Disrupts natural tab order
    - Impact: Confusing keyboard navigation
    - Fix: Use tabIndex="0" or "-1" only, let natural DOM order work

18. **Role without required attributes** (WCAG 4.1.2)
    - Find: Elements with ARIA roles
    - Check: Missing required ARIA attributes (e.g., role="button" without tabIndex)
    - Impact: Incomplete accessibility semantics
    - Fix: Add required attributes for role

### Phase 4: Issue Categorization & Scoring
19. **Categorize all findings**:
    - Critical: Must fix (blocks access)
    - Serious: Should fix (significantly impacts usability)
    - Moderate: Consider fixing (improves experience)

20. **Calculate accessibility score** (0-100):
    - Start at 100
    - Critical issue: -10 points each
    - Serious issue: -5 points each
    - Moderate issue: -2 points each
    - Minimum score: 0

21. **Generate severity summary**:
    - Total issues found
    - Breakdown by severity
    - Most common issue types
    - Pages/sections most affected

### Phase 5: Report Generation
22. **Create detailed report** with specific format:
    ```
    ═══════════════════════════════════════════════════
    ACCESSIBILITY AUDIT: [Page Name]
    ═══════════════════════════════════════════════════

    CRITICAL (X issues)
    ───────────────────
    [A11Y] Element: Button "Submit"
      Issue: Button missing accessible name
      Location: Form section, element ID: {component: "abc", element: "xyz"}
      Current: <button><CloseIcon /></button>
      Fix: Add aria-label="Close"
      WCAG: 4.1.2 Name, Role, Value

    [A11Y] Element: Input field
      Issue: Form input without label
      Location: Contact form, element ID: {component: "def", element: "uvw"}
      Current: <input type="email" />
      Fix: Add aria-label="Email address" or associate with <label>
      WCAG: 1.3.1 Info and Relationships

    SERIOUS (X issues)
    ──────────────────
    [A11Y] Element: Link "Read more"
      Issue: Focus outline removed without visible alternative
      Location: Blog section
      Current: outline: none
      Fix: Add visible focus style (e.g., border: 2px solid blue)
      WCAG: 2.4.7 Focus Visible

    MODERATE (X issues)
    ───────────────────
    [A11Y] Element: Heading
      Issue: Heading hierarchy skipped (h1 → h3)
      Location: Article section
      Current: <h3>Subsection</h3> after <h1>Title</h1>
      Fix: Change to <h2> or add intermediate h2
      WCAG: 1.3.1 Info and Relationships

    ═══════════════════════════════════════════════════
    SUMMARY
    ───────────────────────────────────────────────────
    Total Issues: X
    - Critical: X issues