LazyCats-dev/ao3-podfic-posting-helper / .agent/skills/frontend-a11y
frontend-a11y
VerifiedWrite minimal, accessible web UI without over-engineering, adapting to whatever stack the project uses — React, Vue, Svelte, Angular, web components, or plain HTML. Use this skill on every project and every task that writes or reviews markup or components, builds forms, adds interactive elements like buttons, dialogs, accordions, or tabs, or audits code for accessibility — even when the user never mentions accessibility, and even inside a framework, CMS, or design system. It's non-negotiable regardless of project type, stack, or deadline. About to reach for ARIA attributes, a dialog library, a focus-trap package, or a headless UI component? Use this skill first.
| File | Kind | Size |
|---|---|---|
| SKILL.md | skill md | 27.7 KB |
| evals/evals.json | config | 12.9 KB |
| references/angular.md | markdown | 2.5 KB |
| references/aria.md | markdown | 503.4 KB |
| references/css.md | markdown | 7.4 KB |
| references/patterns.md | markdown | 8.3 KB |
| references/react.md | markdown | 3.7 KB |
| references/standards.md | markdown | 1.2 KB |
| references/svelte.md | markdown | 2.4 KB |
| references/vue.md | markdown | 2.9 KB |
| references/wcag.json | config | 141.1 KB |
| references/web-components.md | markdown | 2.8 KB |
references/web-components.md
View on GitHub# Web Components (and Lit / Stencil)
The HTML/CSS rules in `SKILL.md` all hold inside a component's template. The complications come from the **Shadow DOM boundary**, which changes how names, roles, and references work. Prefer native `<button>`, `<dialog>`, `<details>`, `<label>` inside your shadow root too.
## ID references don't cross the shadow boundary
This is the defining web-components a11y trap. `aria-labelledby`, `aria-describedby`, `aria-controls`, `aria-activedescendant`, and `for` all resolve ids **within a single tree**. An id inside your shadow root is invisible to the light DOM (and vice versa), so a control in one root cannot point at a label in another. Cross-root ARIA (the "reference target" proposal) is not yet universally supported — don't rely on it.
Practical consequences:
- Keep an element and everything it references (its label, its description, its controlled panel) in the **same** root.
- Content passed via `<slot>` stays in the light DOM, so light-DOM ids can reference each other normally — associate a slotted `<label>` and `<input>` on the author's side.
## Set roles and state with ElementInternals
To give the *host* element semantics without leaking implementation ids, use `attachInternals()` and the ARIAMixin properties. These set the accessibility role/state directly on the element, no attribute-id plumbing required.
```js
class MyToggle extends HTMLElement {
#internals = this.attachInternals();
connectedCallback() {
this.#internals.role = "switch";
this.#internals.ariaChecked = "false";
this.tabIndex = 0; // custom interactive elements aren't focusable by default
}
}
```
## Form-associated custom elements
For a custom control that participates in a form, set `static formAssociated = true` and use `ElementInternals`: `setFormValue()` to submit a value, `setValidity()` for validation, and the `aria*` props for state. This is how a custom input gets real label association and form semantics.
## Focus and the boundary
- Custom interactive elements need an explicit `tabindex` — they aren't focusable just because they handle clicks.
- Set `delegatesFocus: true` in `attachShadow({ mode: "open", delegatesFocus: true })` so focusing the host forwards focus to the first focusable element inside.
- Native `<dialog>` + `showModal()` works inside a shadow root and keeps its focus trap.
## Lit / Stencil specifics
- Lit: bind ARIA with `aria-expanded=${open}` in the template; state on the host still goes through `ElementInternals`. Watch that `render()` output lands in the shadow root — the id-reference rule above applies to it.
- Stencil: `@Prop({ reflect: true })` mirrors a prop to an attribute so it's visible/stylable in the DOM; use it for state you need to expose. Set `shadow: true` deliberately, knowing the id-boundary tradeoff.
Related skills
| Skill | Stars | Updated | Works with | Status | Install |
|---|---|---|---|---|---|
| rea-analysis-optimizationmorluto/reaOptimize REA providers and shared analysis workflows for agent context, latency, CPU, and memory while preserving correctness and Evidence. Use for analysis bottlenecks and cache or query design; CI/test-suite optimization belongs to rea-ci-tests-audit. | Stars: 471k | Updated | Claude CodeCodex | Verified | Install |
| rea-ci-tests-auditmorluto/reaAudit REA CI and test suites for correctness, fixture drift, false passes, and measured performance; use for suite or workflow investigations and efficiency changes, rather than ordinary feature testing or a single test failure. | Stars: 471k | Updated | Claude CodeCodex | Verified | Install |
| rea-tool-designmorluto/reaAudit, investigate, design, or change REA investigation tools, CLI/MCP contracts, provider capabilities, and Evidence semantics. | Stars: 471k | Updated | Claude CodeCodex | Verified | Install |
| ponytail-auditDietrichGebert/ponytailQuality audit of the whole repo: bugs, security, real load, missing tests, speed, and what to delete. Most important first. | Stars: 194k | Updated | Claude CodeCodex | Verified | Install |