Skip to content
Merged
Show file tree
Hide file tree
Changes from all commits
Commits
File filter

Filter by extension

Filter by extension

Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
91 changes: 91 additions & 0 deletions .agents/skills/a11y-debugging/SKILL.md
Original file line number Diff line number Diff line change
@@ -0,0 +1,91 @@
---
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.
metadata:
github-path: skills/a11y-debugging
github-pinned: ec0abfc80568b9585299d739debb8869fabd710f
github-ref: ec0abfc80568b9585299d739debb8869fabd710f
github-repo: https://github.com/ChromeDevTools/chrome-devtools-mcp
github-tree-sha: 83d677e8a36b891d8e0badc37bd60526ff3bbff3
name: a11y-debugging
---
## Core Concepts

**Page Targeting**: Page-scoped tools (`take_snapshot`, `list_console_messages`, `evaluate_script`, `press_key`, `take_screenshot`, `lighthouse_audit`, etc.) require a `pageId` parameter. Retrieve available page IDs using `list_pages` or from `new_page`.

**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.
- Omit `outputDirPath` to save reports to the default temporary directory (the exact path to `report.json` is returned under `Reports`), or set `outputDirPath` to a directory within the workspace.
2. **Analyze the Summary**:
- In the default text output, category scores use a 0-100 scale (100 is a perfect score), followed by `Passed: N` and `Failed: N` audit counts.
- If the server was started with `--experimentalStructuredContent`, inspect `summary.scores[].score` (0-1 scale) and `summary.audits.failed` in the structured content instead.
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 from the report path returned by `lighthouse_audit`:
```bash
# Extract failing audits with their details (replace with report.json path from tool response)
node -e "const r=require('<path/to/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, use the **"Check Color Contrast" snippet** found in [references/a11y-snippets.md](references/a11y-snippets.md) with `evaluate_script`.

### 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.
92 changes: 92 additions & 0 deletions .agents/skills/a11y-debugging/references/a11y-snippets.md
Original file line number Diff line number Diff line change
@@ -0,0 +1,92 @@
# Accessibility Debugging Snippets

Use these JavaScript snippets with the `evaluate_script` tool.

## 1. Find Orphaned Form Inputs

Finds form inputs that lack an associated label (no `label[for]`, `aria-label`, `aria-labelledby`, or wrapping `<label>`).

```js
() =>
Array.from(document.querySelectorAll('input, select, textarea'))
.filter(i => {
const hasId = i.id && document.querySelector(`label[for="${i.id}"]`);
const hasAria =
i.getAttribute('aria-label') || i.getAttribute('aria-labelledby');
return !hasId && !hasAria && !i.closest('label');
})
.map(i => ({
tag: i.tagName,
id: i.id,
name: i.name,
placeholder: i.placeholder,
}));
```

## 2. Measure Tap Target Size

Returns the bounding box dimensions of an element. Pass the element's `uid` from the snapshot as an argument to `evaluate_script`.

```js
el => {
const rect = el.getBoundingClientRect();
return {width: rect.width, height: rect.height};
};
```

## 3. Check Color Contrast

Approximates the contrast ratio between an element's text color and background color. Pass the element's `uid` to test against WCAG AA (4.5:1 for normal text, 3:1 for large text).

**Note**: This uses a simplified algorithm and may not account for transparency, gradients, or background images. For production-grade auditing, consider injecting `axe-core`.

```js
el => {
function getRGB(colorStr) {
const match = colorStr.match(/rgba?\((\d+),\s*(\d+),\s*(\d+)/);
return match
? [parseInt(match[1]), parseInt(match[2]), parseInt(match[3])]
: [255, 255, 255];
}
function luminance(r, g, b) {
const a = [r, g, b].map(function (v) {
v /= 255;
return v <= 0.03928 ? v / 12.92 : Math.pow((v + 0.055) / 1.055, 2.4);
});
return a[0] * 0.2126 + a[1] * 0.7152 + a[2] * 0.0722;
}

const style = window.getComputedStyle(el);
const fg = getRGB(style.color);
let bg = getRGB(style.backgroundColor);

const l1 = luminance(fg[0], fg[1], fg[2]);
const l2 = luminance(bg[0], bg[1], bg[2]);
const ratio = (Math.max(l1, l2) + 0.05) / (Math.min(l1, l2) + 0.05);

return {
color: style.color,
bg: style.backgroundColor,
contrastRatio: ratio.toFixed(2),
};
};
```

## 4. Global Page Checks

Checks document-level accessibility settings often missed in component testing.

```js
() => ({
lang:
document.documentElement.lang ||
'MISSING - Screen readers need this for pronunciation',
title: document.title || 'MISSING - Required for context',
viewport:
document.querySelector('meta[name="viewport"]')?.content ||
'MISSING - Check for user-scalable=no (bad practice)',
reducedMotion: window.matchMedia('(prefers-reduced-motion: reduce)').matches
? 'Enabled'
: 'Disabled',
});
```
Loading
Loading