Accessibility Audit

Builderius Accessibility Audit

Comprehensive WCAG 2.2 accessibility auditing and remediation for Builderius templates using MCP tools.

When to Use This Skill

• Auditing a template for WCAG 2.2 Level AA compliance
• Fixing accessibility issues flagged in an audit
• Reviewing landmark structure and heading hierarchy
• Adding ARIA attributes to interactive components
• Checking Collection loops for accessible patterns
• Ensuring forms have proper labels and error handling
• Verifying image alt text coverage

Important: Use Builderius MCP Tools

ALWAYS use Builderius MCP tools for all operations:

• builderius_builder_get_state → Get all modules, hierarchy, settings, data variables
• builderius_builder_list_tabs → See which template is active
• builderius_builder_update_module_setting → Change tag, content, css settings
• builderius_builder_add_html_attribute → Add aria-*, id, role attributes
• builderius_builder_remove_html_attribute → Remove incorrect attributes
• builderius_builder_add_module_class → Add CSS classes (e.g., skip-navigation)
• builderius_builder_add_module → Add new modules (skip links, labels, etc.)
• builderius_builder_delete_module → Remove inaccessible elements
• builderius_builder_get_css_framework → Check for focus styles, contrast variables

NEVER search the filesystem for module data. The MCP tools are your primary data source.

Audit Workflow

Phase 1: Scope & Extraction

1. Identify the template: Call builderius_builder_list_tabs to confirm which template is active.

2. Extract full module tree: Call builderius_builder_get_state to get:

   • modules — All module definitions with settings (tag, content, htmlAttribute, tagClass)
   • indexes — Parent-child hierarchy (key = parent ID, value = child ID array)
   • indexes.root — Top-level modules

3. Parse the module tree: Build the document outline by traversing indexes from root, reading each module's tag setting to understand the HTML structure.

Phase 2: Accessibility Checks

Run all checks against the extracted module tree. For each issue found, record:

• Module ID and label
• WCAG criterion violated
• Severity (Critical / Major / Minor)
• Issue description
• Recommended fix with specific Builderius tool call

Check 1: Page Landmarks (WCAG 1.3.1)

Verify the template has proper landmark structure:

Severity: Section without aria-labelledby = Major. Missing main = Critical.

Check 2: Heading Hierarchy (WCAG 1.3.1, 2.4.6)

Traverse the module tree in document order and check:

How to check: Collect all modules with tag matching h1–h6. Walk the tree in order. Verify the sequence never jumps more than one level down.

Check 3: Image Alt Text (WCAG 1.1.1)

For every module with tag=img:

In Collection loops: Check the Template's img module. Alt text like {{post_title}} is acceptable but consider adding context: "Movie poster for {{post_title}}".

Check 4: Link Accessibility (WCAG 2.4.4, 4.1.2)

For every module with tag=a:

HtmlCode links: Check contentHtml for <a> tags within HtmlCode modules. Verify they have accessible names, especially icon-only social media links.

Check 5: Button Accessibility (WCAG 4.1.2)

For every module with tag=button:

Check 6: Form Accessibility (WCAG 1.3.1, 4.1.2)

For SmartForm modules and form-related HtmlElements:

Check 7: ARIA Usage (WCAG 4.1.2)

Scan all modules for ARIA attributes in htmlAttribute:

Check 8: List Semantics (WCAG 1.3.1)

Check 9: Focus & Keyboard (WCAG 2.4.7, 2.1.1)

How to check: Review entity CSS and framework CSS for focus styles. Call get_css_framework and search for :focus and :focus-visible rules.

Check 10: Skip Navigation (WCAG 2.4.1)

How to check: Look at first child of root in indexes. Should be an <a> with href="#content" and class skip-navigation.

Check 11: Color & Contrast (WCAG 1.4.3, 1.4.11)

Note: Automated tools cannot fully verify contrast ratios. Flag potential issues and recommend manual testing with axe DevTools or WAVE.

Check 12: HtmlCode Modules (Special Attention)

HtmlCode modules inject raw HTML outside the module system. They bypass all semantic checks:

Phase 3: Scoring

Calculate an accessibility score (0–100):

Start at 100
  Critical issue: -10 points each (min 0)
  Major issue:     -5 points each
  Minor issue:     -2 points each
  Minimum score:    0

Phase 4: Report

Generate a structured report:

=====================================================
ACCESSIBILITY AUDIT: [Template Name]
=====================================================

Score: XX/100

CRITICAL (X issues)
─────────────────────
[A11Y-C1] Missing h1 heading
  Module: (none — missing)
  WCAG: 1.3.1, 2.4.6
  Fix: Add HtmlElement tag=h1 as first child of main

[A11Y-C2] Icon-only links without accessible names
  Module: u95460baf6 "Social Links" (HtmlCode)
  WCAG: 2.4.4, 4.1.2
  Fix: Add aria-label to each <a> in contentHtml

MAJOR (X issues)
─────────────────────
[A11Y-M1] Sections missing aria-labelledby
  Modules: m_tst_section, m_sg_section, u6a1a297d7, ...
  WCAG: 1.3.1
  Fix: Add id to section heading, aria-labelledby to section

MINOR (X issues)
─────────────────────
[A11Y-m1] Movie poster alt duplicates heading
  Module: u9cedc324b "Movie Poster"
  WCAG: 1.1.1
  Fix: Change alt to "Movie poster for {{post_title}}"

=====================================================
SUMMARY
─────────────────────────────────────────────────────
Total: X issues (Y critical, Z major, W minor)
Score: XX/100

Quick Wins:
  1. Add skip navigation link (+10 pts, 2 min)
  2. Add aria-labelledby to sections (+5 pts each)
  3. Add h1 heading (+10 pts, 1 min)
=====================================================

Phase 5: Fix Suggestions

For each issue, provide the exact Builderius tool call to fix it:

Add skip navigation link:

builderius_builder_add_module:
  name: HtmlElement
  label: Skip Navigation
  parentId: (root, index 0 — before Site Header)
  settings: [
    {name: "tag", value: "a"},
    {name: "href", value: "#content"},
    {name: "content", value: "Skip to content"},
    {name: "tagClass", value: ["skip-navigation"]}
  ]

Add aria-labelledby to a section:

builderius_builder_add_html_attribute:
  moduleId: (heading module ID)
  name: id
  value: movies-heading

builderius_builder_add_html_attribute:
  moduleId: (section module ID)
  name: aria-labelledby
  value: movies-heading

Fix alt text on an image:

builderius_builder_add_html_attribute:
  moduleId: u9cedc324b
  name: alt
  value: "Movie poster for {{post_title}}"

Change a div to a semantic element:

builderius_builder_update_module_setting:
  moduleId: m_sg_header
  name: tag
  value: header

Phase 6: Apply Fixes (With Approval)

Always ask the user before applying fixes. Present the fix list and let them choose:

Which fixes would you like me to apply?

[1] Add skip navigation link (Critical fix, safe)
[2] Add h1 heading (Critical fix, safe)
[3] Add aria-labelledby to 7 sections (Major fix, safe)
[4] Change 5 header divs to <header> (Major fix, may affect CSS)
[5] Update movie poster alt text (Minor fix, safe)
[6] Fix HtmlCode social links (Critical fix, requires manual contentHtml edit)

Type numbers to apply (e.g., "1,2,3,5"), "all", or "none"

After applying fixes:

• Report success/failure for each
• Recalculate the score
• Show improvement

WCAG 2.2 Quick Reference

Level A (Must Fix)

Level AA (Should Fix)

Level AAA (Nice to Have)

Builderius-Specific Patterns

Collection Loop Accessibility

Each item in a Collection loop should be individually identifiable:

Collection tag=ul (role=list, aria-label="Movies collection")
  Template
    HtmlElement tag=li
      HtmlElement tag=article (aria-label={{post_title}})
        HtmlElement tag=img (alt="Poster for {{post_title}}")
        HtmlElement tag=h3
          HtmlElement tag=a (href={{{permalink}}}, content={{post_title}})
        HtmlElement tag=p (content={{post_excerpt}})

Component Module Accessibility

Component modules are transparent — they render no wrapper HTML. The accessibility attributes must be on the component's internal modules, not the Component module itself (which has no htmlAttribute setting).

Interactive Modules (Tabs, Accordion, Modal)

Builderius interactive modules render as web components (<builderius-tabs>, <builderius-accordion>, etc.) with built-in keyboard handling. Verify:

• Tabs: Children have role="tab" and role="tabpanel"
• Accordion: Sections have proper aria-expanded states
• Modal: Has aria-modal="true" and focus trapping

HtmlCode Module Risk

HtmlCode injects raw HTML that bypasses all module-level checks. Every HtmlCode module should be manually audited for:

• Missing aria-label on links
• Missing alt on images
• Missing aria-hidden on decorative content
• Interactive elements without keyboard support

What This Skill Checks

• Landmark structure (main, nav, header, footer, section, article)
• Heading hierarchy (h1–h6 order, single h1)
• Image alt text (presence and quality)
• Link and button accessible names
• Form labels and error handling
• ARIA usage (correctness, no redundancy)
• List semantics
• Skip navigation
• Focus visibility
• Color usage (hardcoded vs. variables)
• HtmlCode module content
• Collection loop patterns

What This Skill Does NOT Check

• Actual color contrast ratios (requires visual analysis)
• Animation/motion preferences (prefers-reduced-motion)
• Screen reader behavior (requires manual testing)
• Content readability (language level, clarity)
• Third-party embedded content
• Site Header/Footer component internals (audit those separately)

Testing Resources

• Automated: axe DevTools, WAVE, Lighthouse
• Keyboard: Tab, Shift+Tab, Enter, Space, Escape
• Screen readers: VoiceOver (macOS), NVDA/JAWS (Windows), TalkBack (Android)
• References: WCAG 2.2 Quick Reference, WAI-ARIA Practices
• See references/aria-patterns.md for ARIA implementation patterns
• See references/wcag-checklist.md for audit checklists