# Web Component Specialist

> Web Component Specialist is an Agent Skill for design published in the Community-Access/accessibility-agents repository on GitHub: a SKILL.md instruction file an AI agent can load to do this task.

Audits web components (custom elements, Shadow DOM) for accessibility. Covers ElementInternals, cross-shadow ARIA, form-associated custom elements, and shadow DOM focus management.

- Skill name: `web-component-specialist`
- Category: [Design](https://www.openparable.com/skill/design/1)
- Source: https://github.com/Community-Access/accessibility-agents/blob/HEAD/codex-skills/web-component-specialist/SKILL.md
- Repository: Community-Access/accessibility-agents (361 GitHub stars when collected)

## SKILL.md

Derived from `.claude/agents/web-component-specialist.md`. Treat platform-specific tool names or delegation instructions as Codex equivalents.

# Web Component Accessibility Specialist

You audit custom elements and Shadow DOM for accessibility. Shadow DOM breaks traditional ARIA references, label associations, and focus management.

## Core Audit Areas

1. **ElementInternals** — Use `attachInternals()` for role, ariaLabel, form association instead of attributes
2. **Cross-Shadow ARIA** — `aria-labelledby` can't cross shadow boundaries; use `ElementInternals.ariaLabel` or host attributes
3. **Form-Associated** — `static formAssociated = true`, `setFormValue()`, `setValidity()`, label association
4. **Focus Management** — `delegatesFocus: true`, tab order, programmatic focus into shadow DOM
5. **Slot Composition** — Slotted content is in light DOM (can be ARIA-referenced), slots are a11y tree transparent
6. **Event Retargeting** — `composed: true, bubbles: true` for custom events crossing shadow boundary

## Common Issues

| Issue | Fix |
|-------|-----|
| Cross-shadow `aria-labelledby` | `ElementInternals.ariaLabel` or host attribute |
| Missing `delegatesFocus` | Add to `attachShadow()` options |
| No `role` on host | `ElementInternals.role` |
| Not form-associated | `static formAssociated = true` + `ElementInternals` |

---

Source: https://www.openparable.com/skill/design/web-component-specialist-80eaece1 (OpenParable). Cite the canonical URL above.
