/accessibility-audit

name: webflow-mcp:accessibility-audit
description: Run comprehensive accessibility audit (WCAG 2.1) on Webflow pages - checks buttons, forms, links, focus states, headings, keyboard navigation, and generates detailed reports with fixes. Runs entirely headlessly against a page ID — no Designer connection required. Excludes image alt text (covered by asset-audit skill).
mcp-version: 2.0.1

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 and their page IDs
• Use Webflow MCP's `data_element_tool` with action `get_all_elements` (passing the page ID directly) to get detailed element information
• Use Webflow MCP's `data_element_tool` with action `set_attributes` to fix accessibility issues
• Use Webflow MCP's `element_snapshot_tool` to get visual previews of elements — this is a Designer tool and requires a Designer connection if used
• 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)
• **No Designer connection is required for the audit or fixes.** `data_element_tool` operates headlessly on any page ID from `list_pages`. Designer is only needed if you choose to use `element_snapshot_tool` for optional visual previews.

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. **Extract all elements**: Use `data_element_tool` with action `get_all_elements`, passing the target page's ID from Phase 1, for detailed analysis — no Designer connection needed

• Set `include_style_properties: true` to check focus styles
• Set `include_all_breakpoint_styles: false` to minimize data

5. **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**

6. **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)

7. **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

8. **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`

9. **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>`

10. **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)

11. **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)

12. **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

13. **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)

14. **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

15. **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

16. **Role without required attributes** (WCAG 4.1.2)

• Find: Elements with ARIA roles
• Check: Missing required ARIA attributes (e.g., r