Skip to content

LazyCats-dev/ao3-podfic-posting-helper / .agent/skills/frontend-a11y

frontend-a11y

Verified

Write 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.

FileKindSize
SKILL.mdskill md27.7 KB
evals/evals.jsonconfig12.9 KB
references/angular.mdmarkdown2.5 KB
references/aria.mdmarkdown503.4 KB
references/css.mdmarkdown7.4 KB
references/patterns.mdmarkdown8.3 KB
references/react.mdmarkdown3.7 KB
references/standards.mdmarkdown1.2 KB
references/svelte.mdmarkdown2.4 KB
references/vue.mdmarkdown2.9 KB
references/wcag.jsonconfig141.1 KB
references/web-components.mdmarkdown2.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.
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: 471kUpdated Claude CodeCodexVerifiedInstall
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: 471kUpdated Claude CodeCodexVerifiedInstall
rea-tool-designmorluto/reaAudit, investigate, design, or change REA investigation tools, CLI/MCP contracts, provider capabilities, and Evidence semantics.Stars: 471kUpdated Claude CodeCodexVerifiedInstall
ponytail-auditDietrichGebert/ponytailQuality audit of the whole repo: bugs, security, real load, missing tests, speed, and what to delete. Most important first.Stars: 194kUpdated Claude CodeCodexVerifiedInstall