a11y-semantics-pass_skill

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