---
name: velcrafting/a11y-semantics-pass
source: https://app.decimal.ai/s/velcrafting-a11y-semantics-pass@1/SKILL.md
source_sha256: 03a22f4eb1e7
---

# Skill: frontend/a11y-semantics-pass

## Purpose
Ensure UI changes meet baseline accessibility and semantic correctness by addressing:
- semantic HTML usage
- labels and names
- keyboard navigation
- focus management
- ARIA only when necessary and correct

This skill is a pass over existing UI, not feature work.

---

## Inputs
- Target UI surface (components/routes)
- Recent changeset or affected controls
- Repo profile (preferred): `<repo>/REPO_PROFILE.json` (testing/tooling hints)

---

## Outputs
- Updated markup and attributes improving accessibility
- Optional test updates (e.g., testing-library queries by role/name)
- Notes in code comments if tradeoffs are required

---

## Non-goals
- Visual redesign
- Adding new features
- Introducing new dependencies unless repo standard

---

## Workflow
1) Prefer semantic elements first (button, label, fieldset, nav, main).
2) Ensure every interactive control has an accessible name.
3) Ensure keyboard support:
   - tab order sensible
   - enter/space behavior correct
4) Manage focus for dialogs/menus/wizards:
   - focus on open
   - restore focus on close
5) Use ARIA only when needed; avoid “ARIA soup”.
6) Update tests to query by role/name where applicable.
7) Run validations from profile.

---

## Checks
- Interactive elements have accessible names
- Keyboard navigation works for primary flows
- Focus behavior is not broken for dialogs/menus
- Tests still pass; prefer role-based queries where present

---

## Failure modes
- Component library abstracts markup → apply fixes at the wrapper level or use library-supported props.
- Conflicting patterns → follow existing repo standard and document deviations.
- Unclear expected keyboard behavior → ask minimal clarifying question.

---

## Telemetry
Log:
- skill: `frontend/a11y-semantics-pass`
- files_touched
- areas: `labels | focus | keyboard | semantics | aria`
- outcome: `success | partial | blocked`