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
- Get site information: Use Webflow MCP's
data_sites_tool with action list_sites to identify target site
- 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
- 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
- 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
- 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
- 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)
-
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
-
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
-
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>
-
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)
-
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)
-
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
-
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)
-
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
-
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
-
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
-
Categorize all findings:
- Critical: Must fix (blocks access)
- Serious: Should fix (significantly impacts usability)
- Moderate: Consider fixing (improves experience)
-
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
-
Generate severity summary:
- Total issues found
- Breakdown by severity
- Most common issue types
- Pages/sections most affected
Phase 5: Report Generation
-
Create detailed report with specific format:
-
Provide actionable insights:
- Prioritized fix list (critical first)
- Quick wins (easy fixes with big impact)
- Design pattern recommendations
- Resources for learning more
Phase 6: Fix Suggestions & Approval (Optional)
-
Offer to fix issues automatically: Fixes don't require Designer, so offer auto-fixes directly
-
Show preview of fixes:
-
Apply approved fixes: Use data_element_tool with action set_attributes
- Process in batches
- Show progress for large fix sets
- Report success/failure for each
-
Generate post-fix report:
- Issues fixed: X
- Issues remaining: Y
- New accessibility score: XX/100 (improved from YY/100)
Phase 7: Export & Resources (Optional)
-
Offer export formats:
- Markdown (readable documentation)
- JSON (machine-readable for tracking)
- CSV (spreadsheet for team review)
-
Provide resources:
- WCAG 2.1 quick reference links
- Webflow accessibility best practices
- Recommended testing tools (browser extensions, screen readers)
Important Considerations
What This Skill Checks
✅ Button accessibility (labels, roles)
✅ Form input labels and associations
✅ Link semantics and keyboard access
✅ Focus visibility and keyboard navigation
✅ Heading hierarchy and structure
✅ ARIA roles and attributes
✅ Touch target sizes
✅ Interactive element semantics
What This Skill Does NOT Check
❌ Image alt text (use asset-audit skill instead)
❌ Color contrast ratios (requires visual analysis)
❌ Animation/motion preferences
❌ Screen reader testing (needs manual verification)
❌ Content readability (language level, clarity)
Limitations
- Cannot detect visual-only issues (color contrast, small text)
- Cannot test actual screen reader behavior
- Cannot validate content quality or clarity
- Relies on element attributes and structure only
Examples
Example 1: Full Page Audit
User prompt:
Step 1: Site & Page Selection
User response: 1
Step 2: Page Selection
User response: 1
Step 3: Audit Scope
User response: 1
Step 4: Audit Progress
Step 5: Report
Example 2: Multi-Page Audit
User prompt:
Agent response:
User: yes
Progress:
Final Report:
Example 3: Critical Issues Only
User prompt:
Agent response:
Safety Rules
Preview & Confirmation
- Always show detailed issue list before suggesting fixes
- Clearly mark severity levels (critical/serious/moderate)
- Explain impact of each issue in user-friendly terms
- Provide specific WCAG reference for each finding
Granular Approval for Fixes
- Allow user to select which issues to fix
- Warn about fixes that might affect visual design
- Process fixes in batches with progress indicators
- Report success/failure for each fix attempt
Error Handling
- If page cannot be accessed, explain clearly
- If element cannot be modified, suggest manual fix
- Separate automated fixes from manual review items
Validation
- Verify element types before suggesting fixes
- Check if element supports attributes before adding
- Test that suggested fixes are valid for element type
- Warn if fix might break existing functionality
Output Standards
Icons & Formatting
- 🔍 Discovery/Analysis
- 🔄 Processing
- ✅ Pass/Success
- ❌ Fail/Critical Issue
- ⚠️ Warning/Serious Issue
- 💡 Suggestion/Moderate Issue
- 📊 Report/Summary
- 🎯 Priority/Action Item
- 🔴 Critical Priority
- 🟡 Medium Priority
- 🟢 Low Priority
Report Structure
- Clear severity categorization
- Specific element identification with IDs
- Current state vs recommended fix
- WCAG reference for each issue
- Summary with actionable priorities
- Score for measurable progress
Communication
- Use clear, jargon-free language
- Explain WHY something is an issue (impact on users)
- Provide specific, actionable fixes
- Encourage testing with real assistive technology
- Emphasize that automated checks are just the start
Resources to Include
WCAG 2.1 Quick Reference
Webflow Accessibility Resources
- Webflow University: Accessibility best practices
- Using semantic HTML in Webflow
- Adding ARIA attributes in Webflow
Testing Tools
- Keyboard: Tab, Shift+Tab, Enter, Space
- Screen readers: NVDA (Windows), JAWS, VoiceOver (Mac/iOS)
- Browser extensions: axe DevTools, WAVE, Lighthouse
Common Fixes
- Button labels: Always include visible text or aria-label
- Form labels: Use Webflow's label element or aria-label
- Focus styles: Use :focus-visible pseudo-class
- Semantic HTML: Use proper elements (button, a, label)