playbooks

home / skills / velcrafting / codex-skills / a11y-semantics-pass

a11y-semantics-pass skill

/skills/frontend/a11y-semantics-pass

This skill ensures UI changes meet accessibility standards by validating semantics, labels, focus, and ARIA usage across components.

npx playbooks add skill velcrafting/codex-skills --skill a11y-semantics-pass

Review the files below or copy the command above to add this skill to your agents.

Files (1)
SKILL.md
2.2 KB
---
name: a11y-semantics-pass
description: Improve semantics and accessibility coverage for UI changes (roles, labels, focus, keyboard, ARIA correctness).
metadata:
  short-description: A11y + semantic audit
  layer: frontend
  mode: write
  idempotent: true
---

# 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`

Overview

This skill improves semantics and accessibility coverage for UI changes by auditing and fixing markup, labels, focus, keyboard support, and ARIA usage. It performs a focused pass over affected components or routes to meet baseline accessibility expectations without introducing new features or visual redesigns.

How this skill works

I inspect the target UI surface and the recent changeset to identify accessibility regressions and semantic issues. I prefer semantic HTML first, ensure every interactive control has an accessible name, verify keyboard navigation and focus management for dialogs/menus, and apply ARIA only when necessary and correct. I update markup and attributes, optionally adjust tests to use role/name queries, and leave concise code comments where tradeoffs are required.

When to use it

  • After a UI change that touches controls, dialogs, or navigation
  • When accessibility coverage or semantic correctness has regressed
  • Before shipping a release that includes interactive UI changes
  • When tests indicate missing role/name queries or flaky focus behavior

Best practices

  • Prefer native semantic elements (button, label, nav, main) before ARIA
  • Ensure every interactive element has an accessible name and unique role where applicable
  • Verify tab order and support for Enter/Space on actionable controls
  • Manage focus for open/close flows: focus on open, restore on close
  • Limit ARIA usage to cases where semantics cannot be expressed natively
  • Update automated tests to query by role and accessible name when possible

Example use cases

  • Convert div-based click handlers to real buttons with proper accessible names
  • Fix dialog opening so focus moves into the dialog and is restored on close
  • Add labels or aria-labels to form controls missing accessible names
  • Adjust keyboard handlers so Enter/Space activate custom control widgets
  • Replace ARIA-only solutions with semantic elements or wrapper-level fixes for component libraries

FAQ

Will this skill change visual layout or styles?

No. The pass focuses on semantics and accessibility attributes, not visual redesigns or styling changes.

What if a component library abstracts markup?

I apply fixes at the wrapper or integration layer using library-supported props and document any deviations for maintainers.