Accessibility Auditor

A repeatable workflow for auditing a site with the MyA11yReport MCP, and for knowing exactly which checks a machine can make versus which must be made by a human.

Purpose

Produce a complete, defensible accessibility report for every URL in a site’s sitemap. Automated tools catch a subset of issues; the workflow explicitly hands the rest to a human tester and never pretends the automated pass is the whole story.

Golden rules

1. Start every browser session with start_session and pass the returned sessionId to every subsequent stateful call. Call close_session when done.
2. Get the page list from the sitemap, not from guessing. Recursively read the wp-sitemap-*.xml / sitemap index, then audit every listed URL.
3. Automated results are not findings until validated. Investigate ambiguous axe violations and incomplete (“needs review”) items with the available tools — evaluate for the rendered styles and geometry, check_color_contrast for ratio arithmetic, get_page_snapshot for roles and names. Never eyeball pixel values when a tool exists.
4. Human-in-the-loop is mandatory. Keyboard-navigation, screen-reader compatibility, and image-meaning validation cannot be certified by automation (see §Human-required checks). Always state this in the report.
5. One report per concern, plus a roll-up. Write focused markdown docs and a top-level summary.

Required tools (MyA11yReport MCP)

Workflow

0. Enumerate URLs

Read the sitemap index, then every sub-sitemap, and build the URL list. webfetch works well for the XML; keep the last modification dates.

1. Automated axe-core audit

For each URL: navigate → run_a11y_audit. Record counts by impact, per-rule counts, and each violation’s rule id, help text, and target selectors.

2. Visual consistency check (headers, margins, text sizes)

For each URL, evaluate a script that returns, for every visible heading and the main content container:

• tag, classes, truncated text
• fontSize, fontWeight, lineHeight, fontFamily, color
• marginTop/Bottom, paddingTop/Bottom
• bounding rect (left, right, width, top)
• a histogram of computed font sizes of all leaf text nodes

Then compare across pages: page-title size/weight, heading sizes per level, content width/gutter, body text token, and any one-off font sizes. Flag where the “same” semantic element renders differently by template.

3. Structure & landmarks

get_structure per URL (use include: ["regions","headings"] to avoid dumping huge lists). Report:

• duplicate/unnamed landmarks (especially multiple banner, multiple contentinfo, duplicate nav names)
• heading outline with skipped levels and extra H1s (headingGroups)
• frames (iframes) and nested lists

4. Tab order / focus order

get_tab_order per URL. Report total stops, any positive-tabindex values, any outOfOrder stops, whether “Skip to content” is first, and any unnamed tabbable elements. Cross-check unnamed stops against list_images / axe link-name — the text field is visible text only, so an image link with good alt is not a defect.

5. Images & alt text

list_images per URL (use filter: "missing-alt" for the report; counts always cover every image). Report totals, decorative vs missing-alt vs named, and any alt text >250 chars. Meaning is a human judgement call — flag images whose alt="" may actually be meaningful (see §Human-required checks).

6. Color contrast verification

Take the failing pairs from the axe audit and the palette/backgrounds in use, and run each through check_color_contrast. Confirm failures, and validate the proposed replacement shade against both real backgrounds. Report the ratio and the AA/AAA grades for each pair.

7. Keyboard navigation — HUMAN REQUIRED

Automated tools can list tab stops but cannot verify the experience. A human tester must perform this on the real page:

• Tab / Shift+Tab through the entire page and confirm every interactive element is reachable and in a logical order.
• Verify a visible, consistent focus indicator on every control, including summary/details, links, buttons, and form fields — and that the focus color itself meets non-text contrast (≥3:1).
• Operate every widget without a mouse: menus, accordions/disclosures, tabs, modals, carousels, date pickers.
• Confirm focus management: skip links move focus into main content; modals trap and restore focus; nothing is lost or stranded.
• Check for keyboard traps and unreachable content.
• Verify no outline: none without an equivalent replacement.

Record confirmed issues only after a human reproduces them.

8. Screen-reader compatibility — HUMAN REQUIRED

Automation cannot certify screen-reader output. A human tester must run the platform screen reader on the actual device/OS/browser combinations the site targets, across multiple scenarios. This is required and cannot be replaced by axe, the accessibility tree, or this MCP.

At minimum, test with the screen reader(s) appropriate to the device, for example:

• Windows: NVDA (Firefox + Chrome), JAWS (Chrome/Edge)
• macOS: VoiceOver (Safari + Chrome)
• iOS: VoiceOver (Safari)
• Android: TalkBack (Chrome)

Scenarios to cover (repeat per screen reader + browser):

• Read the page top-to-bottom; confirm headings, landmarks, and reading order make sense and are announced correctly.
• Navigate by headings, landmarks, links, and form fields.
• Operate forms and error states; confirm labels, required state, and errors are announced.
• Trigger dynamic content (menus, accordions, AJAX updates, modals) and confirm announcements / focus behavior.
• Test images: confirm meaningful images announce useful descriptions and decorative images are silent.

9. Image validation — HUMAN REQUIRED

Whether an image is decorative or meaningful, and whether its alt text is accurate, sufficient, and not redundant, requires human judgement and subject-matter expertise. A human must review every image flagged as missing-alt, empty-alt (“decorative”), or with arguable alt text, and decide: decorative → alt=""; meaningful → concise, accurate description; functional (inside a link/button) → describe the destination/action, not the picture.

Human-required checks (summary)

These cannot be completed by automation and must be performed by a human, and called out as such in every report:

1. Keyboard navigation — reachability, logical order, visible focus, widget operation without a mouse, focus management, no traps.
2. Screen-reader compatibility — run the real screen reader on the target device/OS/browser across multiple scenarios (see §8).
3. Image validation — judge whether each image is decorative or meaningful and whether its alt text is accurate and sufficient (see §9).

Automation supports these (tab order, accessibility tree, alt-text inventory) but never concludes them.

Output format

Write focused markdown files and a roll-up:

• auto-a11y-report.md — axe-core findings, rule summary, recommended fixes
• consistency-report.md — headers, margins, text sizes across pages
• structure-report.md — landmarks, headings, lists, frames
• tab-order-report.md — focus order, tabindex, unnamed tabbable elements
• images-alt-text-report.md — image inventory and alt-text status
• color-contrast-verification.md — verified ratios and pass/fail grades
• keyboard-navigation-report.md — human keyboard findings
• accessibility-auditor.md — this workflow / skill

Each report should state the site, sitemap, tools used, scope (URL count, viewport), and link the related reports. Mark human-required items explicitly.