skills.rest
arayaroma
arayaromaCOMMUNITY
Explore all skills by this author →
WebsiteGitHub

a11y-semantics-aria

Guides correct use of semantic HTML and ARIA attributes in React components.

Updated Jul 27, 2026
Search Tags:#accessibility#a11y#screen reader#react#semantic html#aria#tsx
One-click install
npx skills add https://github.com/arayaroma/ether --skill a11y-semantics-aria-arayaroma
Or copy as Structured Prompt for Agent▼
Please help me install this Agent Skill.
Skill: a11y-semantics-aria
Source: https://github.com/arayaroma/ether/tree/main/skills/a11y-semantics-aria
Command: npx skills add https://github.com/arayaroma/ether --skill a11y-semantics-aria-arayaroma

SYSTEM DOCUMENTATION & REQUIREMENTS

What problem does it solve? Developers often misuse ARIA attributes or add onClick handlers to divs, producing interfaces that lie to assistive technologies and break keyboard and screen reader support. This Skill provides concrete rules and code patterns for choosing between native semantic HTML and ARIA so components stay accessible. ## Core Features & Use Cases - Semantic HTML over div+ARIA: Enforces the rule that wrong ARIA is worse than no ARIA, with before/after examples for buttons, links, and heading hierarchy. - Labeling patterns: Covers aria-label vs aria-labelledby, aria-describedby for supplementary info, and labeling icon-only buttons. - Live regions and disclosure widgets: Shows correct usage of aria-live (polite vs assertive), aria-expanded, and aria-controls for accordions and status messages. - Anti-pattern detection: Flags common mistakes like aria-label on roleless elements, role="button" without keyboard support, aria-hidden on focusable elements, and positive tabIndex. - Use Case: Before adding an onClick handler to a div or any aria-* attribute to a React component, consult this Skill to verify whether a native element already expresses the intent. ## Quick Start Review this React component and tell me whether it should use semantic HTML or ARIA attributes, fixing any accessibility anti-patterns you find.

Frequently Asked Questions about a11y-semantics-aria

High-intent search queries and answers about installing and using this skill.

FAQPage Schema
When should I use ARIA instead of semantic HTML?▼

Use ARIA only when native HTML semantics cannot express the intent. A native button, anchor, or heading element is always preferable to a div with ARIA, because wrong ARIA misleads assistive technologies about what an element does.

What is the difference between aria-label and aria-labelledby?▼

aria-label takes an inline string and is used when no visible label text exists, such as an icon-only close button. aria-labelledby references the id of another element whose visible text serves as the label, such as a section heading.

How do I make a clickable div accessible in React?▼

Replace the div with a native button element, which provides keyboard support and an accessible role for free. If a custom role is unavoidable, role="button" requires tabIndex={0} plus onKeyDown handling for Enter and Space.

When should I use aria-live polite vs assertive?▼

Use aria-live="polite" for status updates that can wait until the user finishes their current action. Reserve aria-live="assertive" for urgent, blocking errors, since it interrupts the screen reader immediately.

Why is aria-hidden on a focusable element a problem?▼

aria-hidden removes an element from the accessibility tree, but a focusable element can still receive keyboard focus. This traps keyboard users on a control that screen readers cannot perceive, so focusable elements must never be aria-hidden.

Related Skills

Explore More Software Engineering Skills→
tambo-aitambo-ai
11.2k

validating-accessibility

Validates React TSX components against accessibility standards using grep-based violation checks.

Official
Intermediate
ChoreShoreChoreShore

aria-patterns

Apply ARIA roles, states, and properties to interactive components.

Official
Advanced
mgiffordmgifford
39

forms

Ensure form controls have programmatic labels and accessible error messages.

Community
Advanced
SlanyCukrSlanyCukr
2

radix-ui

Provides accessible, unstyled React primitives with built-in ARIA and keyboard navigation for building UI components.

Community
Intermediate