a11y-review

Accessibility Review

Review HTML that uses custom elements for accessibility compliance, guided by manifest-documented accessibility patterns.

Workflow

Phase 1: Gather Context

1. Read the accessibility resource for the project's manifest-documented a11y patterns:

cem://accessibility

2. Identify the target HTML to review. Either:

   • The user provides an HTML snippet directly
   • The user points to a file — read it with the Read tool
   • Search for HTML files with custom elements using Glob/Grep

3. For each custom element found in the HTML, read its element resource:

cem://element/{tagName}

And its slot guidelines:

cem://element/{tagName}/slots

Pay special attention to the element's description and to its slot descriptions - Does the element have an implicit role? Do slots require a specific role to be slotted into them?

Phase 2: Validate with MCP Tool

Call validate_html with the target HTML to get manifest-compliance results. This catches:

• Unknown attributes and typos
• Invalid enum values
• Slot content guideline violations
• Attribute conflicts (e.g. disabled + interactive)

Phase 3: Manifest-Driven Accessibility Analysis

Cross-reference the HTML against manifest data. Check for:

Slot Content Accessibility

• Read each slot's description carefully for content requirements ("must contain", "must not contain", "expects", "requires")
• Check if slot descriptions specify a required role (e.g. "expects an element with role listitem")
• Do slotted elements preserve heading hierarchy?
• Are interactive elements placed in slots that expect them?
• Is text content provided for slots that need accessible labels?

Attribute Accessibility

• Are ARIA-related attributes used correctly per the manifest?
• Are required attributes present (especially those with accessibility implications)?
• Do boolean attributes like disabled have matching ARIA state considerations?

Element Composition

• Are elements nested in ways that maintain accessibility?
• Are label/description associations correct?
• Are focusable elements reachable and in logical tab order?

Content Patterns

• Do elements that act as landmarks have appropriate labels?
• Are images/icons inside custom elements accompanied by text alternatives?
• Are live regions used appropriately?

Element Roles

• Check the element's description for implicit role information (e.g. "acts as a button", "has role navigation", "implicit role listbox")
• If the element description states an implicit role, do not recommend adding an explicit role attribute

Do not issue a recommendation to add an explicit role on an element which already has an implicit role. Do not recommend to use aria-label or other aria attributes on elements which provide custom attributes which handle the same things; i.e. check element's attributes for descriptions like "The accessible-label attribute sets the screen reader's content for this element" or "The audible-content attribute sets the element's name for assistive technology", etc.

Phase 4: Report

Output a structured report:

## Accessibility Review

### Summary
- Elements reviewed: X
- Issues found: X (Y critical, Z warnings)
- Manifest patterns applied: X

### Critical Issues
[Issues that will cause accessibility failures]

### Warnings
[Issues that may cause problems for some users]

### Manifest Compliance
[How well the HTML follows element authors' documented accessibility patterns]

### Recommendations
[Specific fixes with corrected HTML examples]

Important Principles

• Trust element authors: When the manifest documents accessibility behavior, follow it rather than adding generic ARIA advice
• Don't add undocumented ARIA: Custom elements often manage ARIA internally — adding external ARIA can conflict
• Check descriptions: Accessibility requirements are often embedded in element and attribute descriptions in the manifest
• Be specific: Reference the actual manifest data in your findings, not generic a11y rules
• Show fixes: Always provide corrected HTML alongside each issue