Accessibility Audit

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

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

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

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

1. 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)

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

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

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

1. 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)

1. 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)

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

1. 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)

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

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

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

1. Categorize all findings:

• Critical: Must fix (blocks access)
• Serious: Should fix (significantly impacts usability)
• Moderate: Consider fixing (improves experience)

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

1. Generate severity summary:

• Total issues found
• Breakdown by severity
• Most common issue types
• Pages/sections most affected

Phase 5: Report Generation

1. 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
• Serious: X issues
• Moderate: X issues