28 chapters · 170 min

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., role=”button” without tabIndex)
    • Impact: Incomplete accessibility semantics
    • Fix: Add required attributes for role

Phase 4: Issue Categorization & Scoring

17. Categorize all findings:

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

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

19. Generate severity summary:

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

Phase 5: Report Generation

20. Create detailed report with specific format:

    Copy

    ═══════════════════════════════════════════════════
    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
    
    Accessibility Score: XX/100
    
    Most Common Issues:
    1. [Issue type] - X occurrences
    2. [Issue type] - X occurrences
    3. [Issue type] - X occurrences
    ═══════════════════════════════════════════════════

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

22. Offer to fix issues automatically: Fixes don’t require Designer, so offer auto-fixes directly

23. Show preview of fixes:

    Copy

    Which issues would you like to fix?
    
    [1] ✓ Add aria-label to Submit button
        Element: Button in contact form
        Fix: Add aria-label="Submit contact form"
        Safe: Yes (adding attribute only)
    
    [2] ✓ Add aria-label to email input
        Element: Input in contact form
        Fix: Add aria-label="Email address"
        Safe: Yes
    
    [3] ⚠️ Fix heading hierarchy
        Element: h3 in article section
        Fix: Change heading level from h3 to h2
        Safe: May affect visual styling
    
    Type numbers to skip (e.g., "3"), "all" for all, "none" to cancel

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

25. Generate post-fix report:

    • Issues fixed: X
    • Issues remaining: Y
    • New accessibility score: XX/100 (improved from YY/100)

Phase 7: Export & Resources (Optional)

26. Offer export formats:

    • Markdown (readable documentation)
    • JSON (machine-readable for tracking)
    • CSV (spreadsheet for team review)

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

1. Clear severity categorization
2. Specific element identification with IDs
3. Current state vs recommended fix
4. WCAG reference for each issue
5. Summary with actionable priorities
6. 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

• https://www.w3.org/WAI/WCAG21/quickref/ (opens in a new tab)

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)