Accessibility

ARIA, names and live regions

Gets names, roles, states and announcements right in any stack to WCAG 2.2 AA as a target - native elements before ARIA, accessible names for icon buttons and links, valid roles and aria-* attributes, aria-hidden used safely, state attributes, live regions for status messages. Use when adding ARIA, building a custom control or toast, labelling icons, or when asked "what will a screen reader say".

fe-a11y-ariaevery web project8 rules91 tokens always loaded, 1070 tokens when used, 1372 tokens in references on demand.

Install

init installs this skill when the project uses every web project. Pick your agent to see where its files land.

npx github:dawidolko/frontend-skills init

Not tested yet with this runner. npx and pnpm dlx are tested; if this one fails, use one of them.

Without --agents, init finds the agents from what the project already has, and asks when it finds none:

How init finds each of the 17 agents

Agent	Found by
Claude Code	`CLAUDE.md` `.claude` `CLAUDE.local.md`
OpenAI Codex	`.codex` `AGENTS.override.md`
Cursor	`.cursor` `.cursorrules`
GitHub Copilot	`.github/copilot-instructions.md` `.github/instructions` `.github/skills` `.github/prompts`
Gemini CLI	`GEMINI.md` `.gemini`
Antigravity CLI	`.agents/rules` `.agent/rules`
Devin / Windsurf	`.devin` `.windsurf` `.windsurfrules`
OpenCode	`opencode.json` `opencode.jsonc` `.opencode`
Cline	`.clinerules` `.cline`
Zed	`.rules` `.zed`
JetBrains Junie	`.junie`
Kiro	`.kiro`
Augment	`.augment` `.augment-guidelines`
Trae	`.trae`
Continue	`.continue`
Amazon Q Developer	`.amazonq`
Aider	`.aider.conf.yml` `CONVENTIONS.md`

Where fe-a11y-aria lands for Claude Code

.claude/skills/fe-a11y-aria/SKILL.mdskill
.claude/skills/fe-a11y-aria/references/aria.mdskill
.claude/rules/fe-a11y-aria.mdrule file
CLAUDE.mdinstruction block

For every agent also: .frontend-skills/profile.json, .frontend-skills/lessons.md and .frontend-skills/install.json.

Planned by the installer itself for the example React project in the repository.

.claude/rules/fe-a11y-aria.md

---
paths:
  - "**/*.html"
  - "**/*.jsx"
  - "**/*.tsx"
  - "**/*.vue"
  - "**/*.svelte"
  - "**/*.astro"
  - "**/*.component.html"
---

# ARIA, names and live regions (frontend-skills)

Gets names, roles, states and announcements right in any stack to WCAG 2.2 AA as a target - native elements before ARIA, accessible names for icon buttons and links, valid roles and aria-* attributes, aria-hidden used safely, state attributes, live regions for status messages. Use when adding ARIA, building a custom control or toast, labelling icons, or when asked "what will a screen reader say".

- Every button and link has a name; icon-only controls get hidden text or `aria-label`, the icon `aria-hidden="true"` (a11y/control-name).
- Use the native element before a role: `<button>`, `<a href>`, `<input type="checkbox">`, `<nav>`, `<h2>` (a11y/prefer-native-element).
- Roles and `aria-*` names must exist in WAI-ARIA 1.2: `aria-labelledby`, never `aria-labeledby` (a11y/aria-valid).
- Never `aria-hidden="true"` on anything focusable or around it; use `inert` or `hidden` (a11y/aria-hidden-focusable).
- Never `aria-label` on a plain `div`, `span` or `p`; label the control or give a fitting role (a11y/aria-label-generic).
- Ids in `aria-labelledby` and `aria-describedby` exist once on the page; generate them with `useId()` (a11y/aria-ref-exists).
- Custom toggles expose state: `aria-expanded`, `aria-pressed`, `aria-checked`, `aria-selected`, `aria-current` (a11y/state-exposed).
- Status messages go into a live region that exists before the text: `role="status"`, `role="alert"` only for urgent errors (a11y/status-message-live).
- The accessible name contains the visible label, best at its start (WCAG 2.5.3); never replace visible words with different ones.
- Never put ARIA on an element to change its look; ARIA changes only what is announced.

Before larger changes, read the full skill: `.claude/skills/fe-a11y-aria/SKILL.md`. Explain any rule id with `npx github:dawidolko/frontend-skills explain <id>`.

The real file

Where fe-a11y-aria lands for OpenAI Codex

.agents/skills/fe-a11y-aria/SKILL.mdskill
.agents/skills/fe-a11y-aria/references/aria.mdskill
AGENTS.mdinstruction block

For every agent also: .frontend-skills/profile.json, .frontend-skills/lessons.md and .frontend-skills/install.json.

OpenAI Codex has no rule files scoped to file types; it reads the skills and the instruction block.

Planned by the installer itself for the example React project in the repository.

AGENTS.md

## Front-end work (frontend-skills)

- Before front-end work, read `.frontend-skills/profile.json` (the stack) and `.frontend-skills/lessons.md` (confirmed conventions of this project; they win over any skill).
- Use the installed `fe-*` skill that matches the files you edit.
- After changing UI code, run `npx github:dawidolko/frontend-skills audit --changed --json` and fix findings at `serious` and above; `explain <rule id>` gives the reason, the source and the fix.
- Name rule ids (such as `a11y/img-alt`) in reviews and commit messages.

The real file

Where fe-a11y-aria lands for Cursor

.agents/skills/fe-a11y-aria/SKILL.mdskill
.agents/skills/fe-a11y-aria/references/aria.mdskill
.cursor/rules/fe-a11y-aria.mdcrule file
AGENTS.mdinstruction block

For every agent also: .frontend-skills/profile.json, .frontend-skills/lessons.md and .frontend-skills/install.json.

Planned by the installer itself for the example React project in the repository.

.cursor/rules/fe-a11y-aria.mdc

---
description: Gets names, roles, states and announcements right in any stack to WCAG 2.2 AA as a target - native elements before ARIA, accessible names for icon buttons and links, valid roles and aria-* attributes, aria-hidden used safely, state attributes, live regions for status messages. Use when adding ARIA, building a custom control or toast, labelling icons, or when asked "what will a screen reader say".
globs: **/*.html, **/*.jsx, **/*.tsx, **/*.vue, **/*.svelte, **/*.astro, **/*.component.html
alwaysApply: false
---

# ARIA, names and live regions (frontend-skills)

- Every button and link has a name; icon-only controls get hidden text or `aria-label`, the icon `aria-hidden="true"` (a11y/control-name).
- Use the native element before a role: `<button>`, `<a href>`, `<input type="checkbox">`, `<nav>`, `<h2>` (a11y/prefer-native-element).
- Roles and `aria-*` names must exist in WAI-ARIA 1.2: `aria-labelledby`, never `aria-labeledby` (a11y/aria-valid).
- Never `aria-hidden="true"` on anything focusable or around it; use `inert` or `hidden` (a11y/aria-hidden-focusable).
- Never `aria-label` on a plain `div`, `span` or `p`; label the control or give a fitting role (a11y/aria-label-generic).
- Ids in `aria-labelledby` and `aria-describedby` exist once on the page; generate them with `useId()` (a11y/aria-ref-exists).
- Custom toggles expose state: `aria-expanded`, `aria-pressed`, `aria-checked`, `aria-selected`, `aria-current` (a11y/state-exposed).
- Status messages go into a live region that exists before the text: `role="status"`, `role="alert"` only for urgent errors (a11y/status-message-live).
- The accessible name contains the visible label, best at its start (WCAG 2.5.3); never replace visible words with different ones.
- Never put ARIA on an element to change its look; ARIA changes only what is announced.

Before larger changes, read the full skill: `.agents/skills/fe-a11y-aria/SKILL.md`. Explain any rule id with `npx github:dawidolko/frontend-skills explain <id>`.

The real file

Where fe-a11y-aria lands for GitHub Copilot

.agents/skills/fe-a11y-aria/SKILL.mdskill
.agents/skills/fe-a11y-aria/references/aria.mdskill
.github/instructions/fe-a11y-aria.instructions.mdrule file
AGENTS.mdinstruction block

For every agent also: .frontend-skills/profile.json, .frontend-skills/lessons.md and .frontend-skills/install.json.

Planned by the installer itself for the example React project in the repository.

.github/instructions/fe-a11y-aria.instructions.md

---
applyTo: "**/*.html,**/*.jsx,**/*.tsx,**/*.vue,**/*.svelte,**/*.astro,**/*.component.html"
description: "Gets names, roles, states and announcements right in any stack to WCAG 2.2 AA as a target - native elements before ARIA, accessible names for icon buttons and links, valid roles and aria-* attributes, aria-hidden used safely, state attributes, live regions for status messages. Use when adding ARIA, building a custom control or toast, labelling icons, or when asked \"what will a screen reader say\"."
---

# ARIA, names and live regions (frontend-skills)

- Every button and link has a name; icon-only controls get hidden text or `aria-label`, the icon `aria-hidden="true"` (a11y/control-name).
- Use the native element before a role: `<button>`, `<a href>`, `<input type="checkbox">`, `<nav>`, `<h2>` (a11y/prefer-native-element).
- Roles and `aria-*` names must exist in WAI-ARIA 1.2: `aria-labelledby`, never `aria-labeledby` (a11y/aria-valid).
- Never `aria-hidden="true"` on anything focusable or around it; use `inert` or `hidden` (a11y/aria-hidden-focusable).
- Never `aria-label` on a plain `div`, `span` or `p`; label the control or give a fitting role (a11y/aria-label-generic).
- Ids in `aria-labelledby` and `aria-describedby` exist once on the page; generate them with `useId()` (a11y/aria-ref-exists).
- Custom toggles expose state: `aria-expanded`, `aria-pressed`, `aria-checked`, `aria-selected`, `aria-current` (a11y/state-exposed).
- Status messages go into a live region that exists before the text: `role="status"`, `role="alert"` only for urgent errors (a11y/status-message-live).
- The accessible name contains the visible label, best at its start (WCAG 2.5.3); never replace visible words with different ones.
- Never put ARIA on an element to change its look; ARIA changes only what is announced.

Before larger changes, read the full skill: `.agents/skills/fe-a11y-aria/SKILL.md`. Explain any rule id with `npx github:dawidolko/frontend-skills explain <id>`.

The real file

Where fe-a11y-aria lands for Gemini CLI

.agents/skills/fe-a11y-aria/SKILL.mdskill
.agents/skills/fe-a11y-aria/references/aria.mdskill
GEMINI.mdinstruction block

For every agent also: .frontend-skills/profile.json, .frontend-skills/lessons.md and .frontend-skills/install.json.

Gemini CLI: Gemini CLI was replaced by Antigravity CLI for unpaid tiers on 2026-06-18; choose "antigravity" too if you use it.

Gemini CLI has no rule files scoped to file types; it reads the skills and the instruction block.

Planned by the installer itself for the example React project in the repository.

GEMINI.md

## Front-end work (frontend-skills)

- Before front-end work, read `.frontend-skills/profile.json` (the stack) and `.frontend-skills/lessons.md` (confirmed conventions of this project; they win over any skill).
- Use the installed `fe-*` skill that matches the files you edit.
- After changing UI code, run `npx github:dawidolko/frontend-skills audit --changed --json` and fix findings at `serious` and above; `explain <rule id>` gives the reason, the source and the fix.
- Name rule ids (such as `a11y/img-alt`) in reviews and commit messages.

The real file

Where fe-a11y-aria lands for Antigravity CLI

.agents/skills/fe-a11y-aria/SKILL.mdskill
.agents/skills/fe-a11y-aria/references/aria.mdskill
.agents/rules/fe-a11y-aria.mdrule file
AGENTS.mdinstruction block

For every agent also: .frontend-skills/profile.json, .frontend-skills/lessons.md and .frontend-skills/install.json.

Planned by the installer itself for the example React project in the repository.

.agents/rules/fe-a11y-aria.md

---
trigger: glob
globs: "**/*.html, **/*.jsx, **/*.tsx, **/*.vue, **/*.svelte, **/*.astro, **/*.component.html"
description: "Gets names, roles, states and announcements right in any stack to WCAG 2.2 AA as a target - native elements before ARIA, accessible names for icon buttons and links, valid roles and aria-* attributes, aria-hidden used safely, state attributes, live regions for status messages. Use when adding ARIA, building a custom control or toast, labelling icons, or when asked \"what will a screen reader say\"."
---

# ARIA, names and live regions (frontend-skills)

- Every button and link has a name; icon-only controls get hidden text or `aria-label`, the icon `aria-hidden="true"` (a11y/control-name).
- Use the native element before a role: `<button>`, `<a href>`, `<input type="checkbox">`, `<nav>`, `<h2>` (a11y/prefer-native-element).
- Roles and `aria-*` names must exist in WAI-ARIA 1.2: `aria-labelledby`, never `aria-labeledby` (a11y/aria-valid).
- Never `aria-hidden="true"` on anything focusable or around it; use `inert` or `hidden` (a11y/aria-hidden-focusable).
- Never `aria-label` on a plain `div`, `span` or `p`; label the control or give a fitting role (a11y/aria-label-generic).
- Ids in `aria-labelledby` and `aria-describedby` exist once on the page; generate them with `useId()` (a11y/aria-ref-exists).
- Custom toggles expose state: `aria-expanded`, `aria-pressed`, `aria-checked`, `aria-selected`, `aria-current` (a11y/state-exposed).
- Status messages go into a live region that exists before the text: `role="status"`, `role="alert"` only for urgent errors (a11y/status-message-live).
- The accessible name contains the visible label, best at its start (WCAG 2.5.3); never replace visible words with different ones.
- Never put ARIA on an element to change its look; ARIA changes only what is announced.

Before larger changes, read the full skill: `.agents/skills/fe-a11y-aria/SKILL.md`. Explain any rule id with `npx github:dawidolko/frontend-skills explain <id>`.

The real file

Where fe-a11y-aria lands for Devin / Windsurf

.agents/skills/fe-a11y-aria/SKILL.mdskill
.agents/skills/fe-a11y-aria/references/aria.mdskill
.devin/rules/fe-a11y-aria.mdrule file
AGENTS.mdinstruction block

For every agent also: .frontend-skills/profile.json, .frontend-skills/lessons.md and .frontend-skills/install.json.

Devin / Windsurf: Devin CLI also reads .cursor/rules; with Cursor chosen too, the CLI sees both rule files of a skill.

Planned by the installer itself for the example React project in the repository.

.devin/rules/fe-a11y-aria.md

---
trigger: glob
globs: "**/*.html,**/*.jsx,**/*.tsx,**/*.vue,**/*.svelte,**/*.astro,**/*.component.html"
---

# ARIA, names and live regions (frontend-skills)

Gets names, roles, states and announcements right in any stack to WCAG 2.2 AA as a target - native elements before ARIA, accessible names for icon buttons and links, valid roles and aria-* attributes, aria-hidden used safely, state attributes, live regions for status messages. Use when adding ARIA, building a custom control or toast, labelling icons, or when asked "what will a screen reader say".

- Every button and link has a name; icon-only controls get hidden text or `aria-label`, the icon `aria-hidden="true"` (a11y/control-name).
- Use the native element before a role: `<button>`, `<a href>`, `<input type="checkbox">`, `<nav>`, `<h2>` (a11y/prefer-native-element).
- Roles and `aria-*` names must exist in WAI-ARIA 1.2: `aria-labelledby`, never `aria-labeledby` (a11y/aria-valid).
- Never `aria-hidden="true"` on anything focusable or around it; use `inert` or `hidden` (a11y/aria-hidden-focusable).
- Never `aria-label` on a plain `div`, `span` or `p`; label the control or give a fitting role (a11y/aria-label-generic).
- Ids in `aria-labelledby` and `aria-describedby` exist once on the page; generate them with `useId()` (a11y/aria-ref-exists).
- Custom toggles expose state: `aria-expanded`, `aria-pressed`, `aria-checked`, `aria-selected`, `aria-current` (a11y/state-exposed).
- Status messages go into a live region that exists before the text: `role="status"`, `role="alert"` only for urgent errors (a11y/status-message-live).
- The accessible name contains the visible label, best at its start (WCAG 2.5.3); never replace visible words with different ones.
- Never put ARIA on an element to change its look; ARIA changes only what is announced.

Before larger changes, read the full skill: `.agents/skills/fe-a11y-aria/SKILL.md`. Explain any rule id with `npx github:dawidolko/frontend-skills explain <id>`.

The real file

Where fe-a11y-aria lands for OpenCode

.agents/skills/fe-a11y-aria/SKILL.mdskill
.agents/skills/fe-a11y-aria/references/aria.mdskill
AGENTS.mdinstruction block

For every agent also: .frontend-skills/profile.json, .frontend-skills/lessons.md and .frontend-skills/install.json.

OpenCode has no rule files scoped to file types; it reads the skills and the instruction block.

Planned by the installer itself for the example React project in the repository.

AGENTS.md

## Front-end work (frontend-skills)

- Before front-end work, read `.frontend-skills/profile.json` (the stack) and `.frontend-skills/lessons.md` (confirmed conventions of this project; they win over any skill).
- Use the installed `fe-*` skill that matches the files you edit.
- After changing UI code, run `npx github:dawidolko/frontend-skills audit --changed --json` and fix findings at `serious` and above; `explain <rule id>` gives the reason, the source and the fix.
- Name rule ids (such as `a11y/img-alt`) in reviews and commit messages.

The real file

Where fe-a11y-aria lands for Cline

.claude/skills/fe-a11y-aria/SKILL.mdskill
.claude/skills/fe-a11y-aria/references/aria.mdskill
.clinerules/fe-a11y-aria.mdrule file
AGENTS.mdinstruction block

For every agent also: .frontend-skills/profile.json, .frontend-skills/lessons.md and .frontend-skills/install.json.

Cline: If .clinerules is a single file rather than a folder, Cline rule files are not written; skills still are.

Planned by the installer itself for the example React project in the repository.

.clinerules/fe-a11y-aria.md

---
paths:
  - "**/*.html"
  - "**/*.jsx"
  - "**/*.tsx"
  - "**/*.vue"
  - "**/*.svelte"
  - "**/*.astro"
  - "**/*.component.html"
---

# ARIA, names and live regions (frontend-skills)

Gets names, roles, states and announcements right in any stack to WCAG 2.2 AA as a target - native elements before ARIA, accessible names for icon buttons and links, valid roles and aria-* attributes, aria-hidden used safely, state attributes, live regions for status messages. Use when adding ARIA, building a custom control or toast, labelling icons, or when asked "what will a screen reader say".

- Every button and link has a name; icon-only controls get hidden text or `aria-label`, the icon `aria-hidden="true"` (a11y/control-name).
- Use the native element before a role: `<button>`, `<a href>`, `<input type="checkbox">`, `<nav>`, `<h2>` (a11y/prefer-native-element).
- Roles and `aria-*` names must exist in WAI-ARIA 1.2: `aria-labelledby`, never `aria-labeledby` (a11y/aria-valid).
- Never `aria-hidden="true"` on anything focusable or around it; use `inert` or `hidden` (a11y/aria-hidden-focusable).
- Never `aria-label` on a plain `div`, `span` or `p`; label the control or give a fitting role (a11y/aria-label-generic).
- Ids in `aria-labelledby` and `aria-describedby` exist once on the page; generate them with `useId()` (a11y/aria-ref-exists).
- Custom toggles expose state: `aria-expanded`, `aria-pressed`, `aria-checked`, `aria-selected`, `aria-current` (a11y/state-exposed).
- Status messages go into a live region that exists before the text: `role="status"`, `role="alert"` only for urgent errors (a11y/status-message-live).
- The accessible name contains the visible label, best at its start (WCAG 2.5.3); never replace visible words with different ones.
- Never put ARIA on an element to change its look; ARIA changes only what is announced.

Before larger changes, read the full skill: `.claude/skills/fe-a11y-aria/SKILL.md`. Explain any rule id with `npx github:dawidolko/frontend-skills explain <id>`.

The real file

Where fe-a11y-aria lands for Zed

.agents/skills/fe-a11y-aria/SKILL.mdskill
.agents/skills/fe-a11y-aria/references/aria.mdskill
CLAUDE.mdinstruction block

For every agent also: .frontend-skills/profile.json, .frontend-skills/lessons.md and .frontend-skills/install.json.

Zed: Zed reads only the first instruction file of its list; the block is placed in that file.

Zed has no rule files scoped to file types; it reads the skills and the instruction block.

Planned by the installer itself for the example React project in the repository.

CLAUDE.md

## Front-end work (frontend-skills)

- Before front-end work, read `.frontend-skills/profile.json` (the stack) and `.frontend-skills/lessons.md` (confirmed conventions of this project; they win over any skill).
- Use the installed `fe-*` skill that matches the files you edit.
- After changing UI code, run `npx github:dawidolko/frontend-skills audit --changed --json` and fix findings at `serious` and above; `explain <rule id>` gives the reason, the source and the fix.
- Name rule ids (such as `a11y/img-alt`) in reviews and commit messages.

The real file

Where fe-a11y-aria lands for JetBrains Junie

.agents/skills/fe-a11y-aria/SKILL.mdskill
.agents/skills/fe-a11y-aria/references/aria.mdskill
AGENTS.mdinstruction block

For every agent also: .frontend-skills/profile.json, .frontend-skills/lessons.md and .frontend-skills/install.json.

JetBrains Junie: Junie reads .agents/skills only in a trusted project.

JetBrains Junie has no rule files scoped to file types; it reads the skills and the instruction block.

Planned by the installer itself for the example React project in the repository.

AGENTS.md

## Front-end work (frontend-skills)

- Before front-end work, read `.frontend-skills/profile.json` (the stack) and `.frontend-skills/lessons.md` (confirmed conventions of this project; they win over any skill).
- Use the installed `fe-*` skill that matches the files you edit.
- After changing UI code, run `npx github:dawidolko/frontend-skills audit --changed --json` and fix findings at `serious` and above; `explain <rule id>` gives the reason, the source and the fix.
- Name rule ids (such as `a11y/img-alt`) in reviews and commit messages.

The real file

Where fe-a11y-aria lands for Kiro

.kiro/skills/fe-a11y-aria/SKILL.mdskill
.kiro/skills/fe-a11y-aria/references/aria.mdskill
.kiro/steering/fe-a11y-aria.mdrule file
AGENTS.mdinstruction block

For every agent also: .frontend-skills/profile.json, .frontend-skills/lessons.md and .frontend-skills/install.json.

Planned by the installer itself for the example React project in the repository.

.kiro/steering/fe-a11y-aria.md

---
inclusion: fileMatch
fileMatchPattern: ["**/*.html", "**/*.jsx", "**/*.tsx", "**/*.vue", "**/*.svelte", "**/*.astro", "**/*.component.html"]
---

# ARIA, names and live regions (frontend-skills)

Gets names, roles, states and announcements right in any stack to WCAG 2.2 AA as a target - native elements before ARIA, accessible names for icon buttons and links, valid roles and aria-* attributes, aria-hidden used safely, state attributes, live regions for status messages. Use when adding ARIA, building a custom control or toast, labelling icons, or when asked "what will a screen reader say".

- Every button and link has a name; icon-only controls get hidden text or `aria-label`, the icon `aria-hidden="true"` (a11y/control-name).
- Use the native element before a role: `<button>`, `<a href>`, `<input type="checkbox">`, `<nav>`, `<h2>` (a11y/prefer-native-element).
- Roles and `aria-*` names must exist in WAI-ARIA 1.2: `aria-labelledby`, never `aria-labeledby` (a11y/aria-valid).
- Never `aria-hidden="true"` on anything focusable or around it; use `inert` or `hidden` (a11y/aria-hidden-focusable).
- Never `aria-label` on a plain `div`, `span` or `p`; label the control or give a fitting role (a11y/aria-label-generic).
- Ids in `aria-labelledby` and `aria-describedby` exist once on the page; generate them with `useId()` (a11y/aria-ref-exists).
- Custom toggles expose state: `aria-expanded`, `aria-pressed`, `aria-checked`, `aria-selected`, `aria-current` (a11y/state-exposed).
- Status messages go into a live region that exists before the text: `role="status"`, `role="alert"` only for urgent errors (a11y/status-message-live).
- The accessible name contains the visible label, best at its start (WCAG 2.5.3); never replace visible words with different ones.
- Never put ARIA on an element to change its look; ARIA changes only what is announced.

Before larger changes, read the full skill: `.kiro/skills/fe-a11y-aria/SKILL.md`. Explain any rule id with `npx github:dawidolko/frontend-skills explain <id>`.

The real file

Where fe-a11y-aria lands for Augment

.agents/skills/fe-a11y-aria/SKILL.mdskill
.agents/skills/fe-a11y-aria/references/aria.mdskill
AGENTS.mdinstruction block

For every agent also: .frontend-skills/profile.json, .frontend-skills/lessons.md and .frontend-skills/install.json.

Augment has no rule files scoped to file types; it reads the skills and the instruction block.

Planned by the installer itself for the example React project in the repository.

AGENTS.md

## Front-end work (frontend-skills)

- Before front-end work, read `.frontend-skills/profile.json` (the stack) and `.frontend-skills/lessons.md` (confirmed conventions of this project; they win over any skill).
- Use the installed `fe-*` skill that matches the files you edit.
- After changing UI code, run `npx github:dawidolko/frontend-skills audit --changed --json` and fix findings at `serious` and above; `explain <rule id>` gives the reason, the source and the fix.
- Name rule ids (such as `a11y/img-alt`) in reviews and commit messages.

The real file

Where fe-a11y-aria lands for Trae

.trae/skills/fe-a11y-aria/SKILL.mdskill
.trae/skills/fe-a11y-aria/references/aria.mdskill
.trae/rules/fe-a11y-aria.mdrule file
AGENTS.mdinstruction block

For every agent also: .frontend-skills/profile.json, .frontend-skills/lessons.md and .frontend-skills/install.json.

Trae: Trae reads AGENTS.md only after it is enabled in its settings.

Planned by the installer itself for the example React project in the repository.

.trae/rules/fe-a11y-aria.md

---
description: "Gets names, roles, states and announcements right in any stack to WCAG 2.2 AA as a target - native elements before ARIA, accessible names for icon buttons and links, valid roles and aria-* attributes, aria-hidden used safely, state attributes, live regions for status messages. Use when adding ARIA, building a custom control or toast, labelling icons, or when asked \"what will a screen reader say\"."
globs: **/*.html,**/*.jsx,**/*.tsx,**/*.vue,**/*.svelte,**/*.astro,**/*.component.html
alwaysApply: false
---

# ARIA, names and live regions (frontend-skills)

- Every button and link has a name; icon-only controls get hidden text or `aria-label`, the icon `aria-hidden="true"` (a11y/control-name).
- Use the native element before a role: `<button>`, `<a href>`, `<input type="checkbox">`, `<nav>`, `<h2>` (a11y/prefer-native-element).
- Roles and `aria-*` names must exist in WAI-ARIA 1.2: `aria-labelledby`, never `aria-labeledby` (a11y/aria-valid).
- Never `aria-hidden="true"` on anything focusable or around it; use `inert` or `hidden` (a11y/aria-hidden-focusable).
- Never `aria-label` on a plain `div`, `span` or `p`; label the control or give a fitting role (a11y/aria-label-generic).
- Ids in `aria-labelledby` and `aria-describedby` exist once on the page; generate them with `useId()` (a11y/aria-ref-exists).
- Custom toggles expose state: `aria-expanded`, `aria-pressed`, `aria-checked`, `aria-selected`, `aria-current` (a11y/state-exposed).
- Status messages go into a live region that exists before the text: `role="status"`, `role="alert"` only for urgent errors (a11y/status-message-live).
- The accessible name contains the visible label, best at its start (WCAG 2.5.3); never replace visible words with different ones.
- Never put ARIA on an element to change its look; ARIA changes only what is announced.

Before larger changes, read the full skill: `.trae/skills/fe-a11y-aria/SKILL.md`. Explain any rule id with `npx github:dawidolko/frontend-skills explain <id>`.

The real file

Where fe-a11y-aria lands for Continue

.frontend-skills/skills/fe-a11y-aria/SKILL.mdskill
.frontend-skills/skills/fe-a11y-aria/references/aria.mdskill
.continue/rules/fe-a11y-aria.mdrule file

For every agent also: .frontend-skills/profile.json, .frontend-skills/lessons.md and .frontend-skills/install.json.

Planned by the installer itself for the example React project in the repository.

.continue/rules/fe-a11y-aria.md

---
name: "ARIA, names and live regions"
description: "Gets names, roles, states and announcements right in any stack to WCAG 2.2 AA as a target - native elements before ARIA, accessible names for icon buttons and links, valid roles and aria-* attributes, aria-hidden used safely, state attributes, live regions for status messages. Use when adding ARIA, building a custom control or toast, labelling icons, or when asked \"what will a screen reader say\"."
globs: ["**/*.html", "**/*.jsx", "**/*.tsx", "**/*.vue", "**/*.svelte", "**/*.astro", "**/*.component.html"]
alwaysApply: false
---

# ARIA, names and live regions (frontend-skills)

- Every button and link has a name; icon-only controls get hidden text or `aria-label`, the icon `aria-hidden="true"` (a11y/control-name).
- Use the native element before a role: `<button>`, `<a href>`, `<input type="checkbox">`, `<nav>`, `<h2>` (a11y/prefer-native-element).
- Roles and `aria-*` names must exist in WAI-ARIA 1.2: `aria-labelledby`, never `aria-labeledby` (a11y/aria-valid).
- Never `aria-hidden="true"` on anything focusable or around it; use `inert` or `hidden` (a11y/aria-hidden-focusable).
- Never `aria-label` on a plain `div`, `span` or `p`; label the control or give a fitting role (a11y/aria-label-generic).
- Ids in `aria-labelledby` and `aria-describedby` exist once on the page; generate them with `useId()` (a11y/aria-ref-exists).
- Custom toggles expose state: `aria-expanded`, `aria-pressed`, `aria-checked`, `aria-selected`, `aria-current` (a11y/state-exposed).
- Status messages go into a live region that exists before the text: `role="status"`, `role="alert"` only for urgent errors (a11y/status-message-live).
- The accessible name contains the visible label, best at its start (WCAG 2.5.3); never replace visible words with different ones.
- Never put ARIA on an element to change its look; ARIA changes only what is announced.

Before larger changes, read the full skill: `.frontend-skills/skills/fe-a11y-aria/SKILL.md`. Explain any rule id with `npx github:dawidolko/frontend-skills explain <id>`.

The real file

Where fe-a11y-aria lands for Amazon Q Developer

.frontend-skills/skills/fe-a11y-aria/SKILL.mdskill
.frontend-skills/skills/fe-a11y-aria/references/aria.mdskill
.amazonq/rules/frontend-skills.mdinstruction block

For every agent also: .frontend-skills/profile.json, .frontend-skills/lessons.md and .frontend-skills/install.json.

Amazon Q Developer: Amazon Q Developer IDE plugins reach end of support on 2027-04-30; AWS points to Kiro.

Amazon Q Developer has no rule files scoped to file types; it reads the skills and the instruction block.

Planned by the installer itself for the example React project in the repository.

.amazonq/rules/frontend-skills.md

## Front-end work (frontend-skills)

- Before front-end work, read `.frontend-skills/profile.json` (the stack) and `.frontend-skills/lessons.md` (confirmed conventions of this project; they win over any skill).
- Use the installed `fe-*` skill that matches the files you edit.
- After changing UI code, run `npx github:dawidolko/frontend-skills audit --changed --json` and fix findings at `serious` and above; `explain <rule id>` gives the reason, the source and the fix.
- Name rule ids (such as `a11y/img-alt`) in reviews and commit messages.

### Skills

- `fe-a11y-aria` (ARIA, names and live regions): when editing `**/*.html`, `**/*.jsx`, `**/*.tsx`, `**/*.vue`, `**/*.svelte`, `**/*.astro`, `**/*.component.html`, first read `.frontend-skills/skills/fe-a11y-aria/SKILL.md`.

The real file

Where fe-a11y-aria lands for Aider

.frontend-skills/skills/fe-a11y-aria/SKILL.mdskill
.frontend-skills/skills/fe-a11y-aria/references/aria.mdskill
CONVENTIONS.mdinstruction block
.aider.conf.ymlconfig

For every agent also: .frontend-skills/profile.json, .frontend-skills/lessons.md and .frontend-skills/install.json.

Aider has no rule files scoped to file types; it reads the skills and the instruction block.

Planned by the installer itself for the example React project in the repository.

CONVENTIONS.md

## Front-end work (frontend-skills)

- Before front-end work, read `.frontend-skills/profile.json` (the stack) and `.frontend-skills/lessons.md` (confirmed conventions of this project; they win over any skill).
- Use the installed `fe-*` skill that matches the files you edit.
- After changing UI code, run `npx github:dawidolko/frontend-skills audit --changed --json` and fix findings at `serious` and above; `explain <rule id>` gives the reason, the source and the fix.
- Name rule ids (such as `a11y/img-alt`) in reviews and commit messages.

### Skills

- `fe-a11y-aria` (ARIA, names and live regions): when editing `**/*.html`, `**/*.jsx`, `**/*.tsx`, `**/*.vue`, `**/*.svelte`, `**/*.astro`, `**/*.component.html`, first read `.frontend-skills/skills/fe-a11y-aria/SKILL.md`.

The real file

How to use it

Once installed, the agent loads the skill by itself when a task matches its description. You can also ask for it in your own words, for example:

Phrases from the skill description that make the agent pick it:

what will a screen reader say

And to check and fix the work:

Use the fe-a11y-aria skill on this file.
Run the front-end audit on what I changed and fix everything serious.
Explain a11y/control-name and fix it here.

Rules it teaches

a11y/control-name
Every button and link has an accessible name; icon-only controls get visually hidden text or aria-label.
criticalstaticWCAG 4.1.2, 2.4.4
a11y/prefer-native-element
Use the native element instead of a role it already provides (button, a href, input, h1–h6, nav, main, ul, li).
minorstaticWCAG 4.1.2
a11y/aria-valid
Every role value is a real WAI-ARIA role and every aria-* attribute name exists (aria-labelledby, not aria-labeledby).
seriousstaticWCAG 4.1.2
a11y/aria-hidden-focusable
aria-hidden="true" is never on a focusable element or on an element that contains one.
seriousstaticWCAG 4.1.2
a11y/aria-label-generic
aria-label and aria-labelledby go on controls, landmarks and named roles, never on a plain div, span or p.
seriousstaticWCAG 4.1.2
a11y/aria-ref-exists
Ids named in aria-labelledby, aria-describedby and aria-errormessage exist in the page and are unique.
seriousstaticWCAG 1.3.1, 4.1.2
a11y/state-exposed
Custom toggles, disclosures and selections expose their state (aria-expanded, aria-pressed, aria-checked, aria-selected).
seriousmanualWCAG 4.1.2
a11y/status-message-live
Messages that appear without moving focus (saved, results, errors, progress) are announced through a live region.
seriousmanualWCAG 4.1.3

The rule digest

This part is copied into each agent's scoped rule file, so it stands on its own:

Every button and link has a name; icon-only controls get hidden text or aria-label, the icon aria-hidden="true" (a11y/control-name).
Use the native element before a role: <button>, <a href>, <input type="checkbox">, <nav>, <h2> (a11y/prefer-native-element).
Roles and aria-* names must exist in WAI-ARIA 1.2: aria-labelledby, never aria-labeledby (a11y/aria-valid).
Never aria-hidden="true" on anything focusable or around it; use inert or hidden (a11y/aria-hidden-focusable).
Never aria-label on a plain div, span or p; label the control or give a fitting role (a11y/aria-label-generic).
Ids in aria-labelledby and aria-describedby exist once on the page; generate them with useId() (a11y/aria-ref-exists).
Custom toggles expose state: aria-expanded, aria-pressed, aria-checked, aria-selected, aria-current (a11y/state-exposed).
Status messages go into a live region that exists before the text: role="status", role="alert" only for urgent errors (a11y/status-message-live).
The accessible name contains the visible label, best at its start (WCAG 2.5.3); never replace visible words with different ones.
Never put ARIA on an element to change its look; ARIA changes only what is announced.

Steps the agent follows

Ask first: is there a native element? dialog, details, select, input type="range", progress, meter, search. Use it and stop.
When there is none, follow the APG pattern for the widget (role, required children, states, keys) and the skills fe-a11y-dialog, fe-a11y-menus, fe-a11y-tabs-accordion, fe-a11y-combobox.
Name things in this order: visible text, aria-labelledby to visible text, aria-label, and never title or placeholder alone.
Bind every state attribute to the same variable that drives the visual state, so they cannot drift apart.
For async results, keep one polite live region per page area (<p role="status">) in the layout; write text into it; clear it after a few seconds only if the text stays visible elsewhere.

How the agent checks the work

npx github:dawidolko/frontend-skills audit --changed finds unnamed icon buttons and links, invalid roles and attributes, aria-hidden over focusable content, labels on generic elements and broken id references.
audit --url <page> adds axe-core's name and ARIA rules on the rendered page, where names that come from components are known.
By hand: listen with a screen reader (VoiceOver, NVDA) to each changed control and message: name, role, state, and the announcement after an action.

Checked by the audit

The static checks of these rules run in audit; this is a real session on the example project:

Terminal recording: audit lists findings by severity with rule ids and file:line, and fails at serious. — `audit`: counts by severity, each rule with its first location, the exit code.

Reference files

references/aria.md1372 tokens

SKILL.md on GitHub