Skip to content
Skills Library
Design & UX · Testing

a11y-debugging

/a11y-debugging

Uses Chrome DevTools MCP for accessibility (a11y) debugging and auditing based on web.dev guidelines. Use when testing semantic HTML, ARIA labels, focus states, keyboard navigation, tap targets, and color contrast.

Repository
artemis ↗
Licence
MIT
Last repository change
25.10.2026

Assessment and security

95/ 100Class: good
Format20 / 25
Frontmatter with name and description, valid name, description up to 1,024 characters, name matching the folder.
Discoverability25 / 25
Description explains when to use the skill, has a reasonable length and uses third person.
Content35 / 35
At least 150 words and at most 500 lines, headings, step lists, examples or code.
Hygiene15 / 15
No placeholders such as TODO, no Windows paths, with a licence.
Riskno signals detected in the scan
Files in this package
3
Scripts
0
HTML comments
0
URLs in SKILL.md
2
Deprecation

No signals detected. Repository changed on 25.10.2026, without references to retired models or APIs.

Licence

MIT, open: use and modify while retaining author attribution.

What it does and when to use it

Uses Chrome DevTools MCP for accessibility (a11y) debugging and auditing based on web.dev guidelines. Use when testing semantic HTML, ARIA labels, focus states, keyboard navigation, tap targets, and color contrast.

Original author description

Uses Chrome DevTools MCP for accessibility (a11y) debugging and auditing based on web.dev guidelines. Use when testing semantic HTML, ARIA labels, focus states, keyboard navigation, tap targets, and color contrast.

How it works

  1. Core Concepts
  2. Workflow Patterns
  3. Troubleshooting
Original SKILL.md headings · 86 lines, 720 words
SKILL.md preview
---
name: a11y-debugging
description: Uses Chrome DevTools MCP for accessibility (a11y) debugging and auditing based on web.dev guidelines. Use when testing semantic HTML, ARIA labels, focus states, keyboard navigation, tap targets, and color contrast.
---

## Core Concepts

**Accessibility Tree vs DOM**: Visually hiding an element (e.g., `CSS opacity: 0`) behaves differently for screen readers than `display: none` or `aria-hidden="true"`. The `take_snapshot` tool returns the accessibility tree of the page, which represents what assistive technologies "see", making it the most reliable source of truth for semantic structure.

**Reading web.dev documentation**: If you need to research specific accessibility guidelines (like `https://web.dev/articles/accessible-tap-targets`), you can append `.md.txt` to the URL (e.g., `https://web.dev/articles/accessible-tap-targets.md.txt`) to fetch the clean, raw markdown version. This is much easier to read!

## Workflow Patterns

### 1. Automated Audit (Lighthouse)

Start by running a Lighthouse accessibility audit to get a comprehensive baseline. This tool provides a high-level score and lists specific failing elements with remediation advice.

1.  Run the audit:
    - Set `mode` to `"navigation"` to refresh the page and capture load issues.
    - Set `outputDirPath` (e.g., `/tmp/lh-report`) to save the full JSON report.
2.  **Analyze the Summary**:
    - Check `scores` (0-1 scale). A score < 1 indicates violations.
    - Review `audits.failed` count.
3.  **Review the Report (CRITICAL)**:
    - **Parsing**: Do not read the entire file line-by-line. Use a CLI tool like `jq` or a Node.js one-liner to filter for failures:
      ```bash
      # Extract failing audits with their details
      node -e "const r=require('./report.json'); Object.values(r.audits).filter(a=>a.score!==null && a.score<1).forEach(a=>console.log(JSON.stringify({id:a.id, title:a.title, items:a.details?.items})))"
      ```
    - This efficiently extracts the `selector` and `snippet` of failing elements without loading the full report into context.

### 2. Browser Issues & Audits

Chrome automatically checks for common accessibility problems. Use `list_console_messages` to check for these native audits:

- `types`: `["issue"]`
- `includePreservedMessages`: `true` (to catch issues that occurred during page load)

This often reveals missing labels, invalid ARIA attributes, and other critical errors without manual investigation.

### 3. Semantics & Structure

The accessibility tree exposes the heading hierarchy and semantic landmarks.

1.  Navigate to the page.
2.  Use `take_snapshot` to capture the accessibility tree.
3.  **Check Heading Levels**: Ensure heading levels (`h1`, `h2`, `h3`, etc.) are logical and do not skip levels. The snapshot will include heading roles.
4.  **Content Reordering**: Verify that the DOM order (which drives the accessibility tree) matches the visual reading order. Use `take_screenshot` to inspect the visual layout and compare it against the snapshot structure to catch CSS floats or absolute positioning that jumbles the logical flow.

### 4. Labels, Forms & Text Alternatives

1.  Locate buttons, inputs, and images in the `take_snapshot` output.
2.  Ensure interactive elements have an accessible name (e.g., a button should not just say `""` if it only contains an icon).
3.  **Orphaned Inputs**: Verify that all form inputs have associated labels. Use `evaluate_script` with the **"Find Orphaned Form Inputs" snippet** found in [references/a11y-snippets.md](references/a11y-snippets.md).
4.  Check images for `alt` text.

### 5. Focus & Keyboard Navigation

Testing "keyboard traps" and proper focus management without visual feedback relies on tracking the focused element.

1.  Use the `press_key` tool with `"Tab"` or `"Shift+Tab"` to move focus.
2.  Use `take_snapshot` to capture the updated accessibility tree.
3.  Locate the element marked as focused in the snapshot to verify focus moved to the expected interactive element.
4.  If a modal opens, focus must move into the modal and "trap" within it until closed.

### 6. Tap Targets and Visuals

According to web.dev, tap targets should be at least 48x48 pixels with sufficient spacing. Since the accessibility tree doesn't show sizes, use `evaluate_script` with the **"Measure Tap Target Size" snippet** found in [references/a11y-snippets.md](references/a11y-snippets.md).

_Pass the element's `uid` from the snapshot as an argument to `evaluate_script`._

### 7. Color Contrast

To verify color contrast ratios, start by checking for native accessibility issues:

1.  Call `list_console_messages` with `types: ["issue"]`.
2.  Look for "Low Contrast" issues in the output.

If native audits do not report issues (which may happen in some headless environments) or if you need to check a specific element manually, use `evaluate_script` with the **"Check Color Contrast" snippet** found in [references/a11y-snippets.md](references/a11y-snippets.md).

### 8. Global Page Checks

Verify document-level accessibility settings often missed in component testing using the **"Global Page Checks" snippet** found in [references/a11y-snippets.md](references/a11y-snippets.md).

## Troubleshooting

If standard a11y queries fail or the `evaluate_script` snippets return unexpected results:

- **Visual Inspection**: If automated scripts cannot determine contrast (e.g., text over gradient images or complex backgrounds), use `take_screenshot` to capture the element. While models cannot measure exact contrast ratios from images, they can visually assess legibility and identify obvious issues.
Files in this package (3)
  • SKILL.json 1 KB
  • SKILL.md 6 KB
  • references/a11y-snippets.md 3 KB

Versions

RepositoryScoreLicence
This page · 420company/artemis95MIT
chromedevtools/chrome-devtools-mcp100Apache-2.0
zenobi-us/dotfiles100MIT

Database snapshot: 13.11.2026 · package version 6189ec48c4d0 (SHA-256 digest of the entire package)

Downloads in the last 30 days: 0 · ranking

Report a problem with this skill: harmful content, incorrect descriptions or an author’s removal request.

Similar skills

  • 90dev-accessibility-audit
    Use to audit web/app accessibility, including semantics, keyboard flow, focus, labels, ARIA, contrast, and responsive behavior.
  • 90a11y-audit
    Audit and fix website accessibility to WCAG 2.2 AA — semantic HTML, keyboard navigation, focus, labels, alt text, color contrast, ARIA, and screen-reader behavior — in React/Next.js, Vue, or plain HTML. Use whenever the user mentions accessibility, a11y, WCAG, screen readers,…
  • 90fixing-accessibility
    Audit, fix, or verify interface accessibility including semantics, labels, keyboard access, focus, dialogs, forms, announcements, contrast, and reduced motion. Use for accessibility questions or concrete defects; a targeted repair does not require a whole-product audit.
  • 90fixing-accessibility
    Audit, fix, or verify interface accessibility including semantics, labels, keyboard access, focus, dialogs, forms, announcements, contrast, and reduced motion. Use for accessibility questions or concrete defects; a targeted repair does not require a whole-product audit.
  • 90wp-accessible-ui-review
    Review a WordPress theme or page for accessibility: focus states, keyboard use, ARIA, color contrast, headings, alt text and reduced motion, and report findings with file:line and fixes. Use when the user asks for an accessibility, WCAG or a11y check. Works in Claude Code,…
  • 100fixing-accessibility
    Audit and fix HTML accessibility issues including ARIA labels, keyboard navigation, focus management, color contrast, and form errors. Use when adding interactive controls, forms, dialogs, or reviewing WCAG compliance.

Feedback and reports

Your message goes to Bartosz Sokoliński. An email address is needed only for a reply. See the privacy policy.