Accessibility

Dialogs and modals

Builds modal and non-modal dialogs, alert dialogs, drawers and confirmations that work with keyboard and screen readers (WAI-ARIA APG Dialog pattern) on the native dialog element - name, initial focus, inert background, Escape, focus return. Use when adding a modal, popup, drawer, lightbox, cookie or confirm dialog in any stack, or when asked "make this modal accessible".

fe-a11y-dialogevery web project5 rules82 tokens always loaded, 846 tokens when used, 1280 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-dialog lands for Claude Code

.claude/skills/fe-a11y-dialog/SKILL.mdskill
.claude/skills/fe-a11y-dialog/references/dialog.mdskill
.claude/rules/fe-a11y-dialog.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-dialog.md

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

# Dialogs and modals (frontend-skills)

Builds modal and non-modal dialogs, alert dialogs, drawers and confirmations that work with keyboard and screen readers (WAI-ARIA APG Dialog pattern) on the native dialog element - name, initial focus, inert background, Escape, focus return. Use when adding a modal, popup, drawer, lightbox, cookie or confirm dialog in any stack, or when asked "make this modal accessible".

- Use `<dialog>` with `showModal()` for modals and `show()` for non-modal ones, not a `div role="dialog"` (a11y/dialog-native).
- Every dialog has a name: `aria-labelledby` pointing at its visible heading (a11y/dialog-name).
- On open, focus goes inside; Tab stays inside a modal; Escape closes; on close, focus returns to the trigger (a11y/dialog-focus).
- The page behind a modal is inert, never just `aria-hidden` over focusable content (a11y/aria-hidden-focusable).
- Only an open modal keeps focus inside; a closed one releases it (a11y/no-keyboard-trap).
- A visible close or cancel button is inside the dialog and in the Tab order.
- Confirmations of destructive actions use `role="alertdialog"` with `aria-describedby` on the message, and focus the safe choice.
- Do not open a modal on page load or on hover; open it from a user action.

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

The real file

Where fe-a11y-dialog lands for OpenAI Codex

.agents/skills/fe-a11y-dialog/SKILL.mdskill
.agents/skills/fe-a11y-dialog/references/dialog.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-dialog lands for Cursor

.agents/skills/fe-a11y-dialog/SKILL.mdskill
.agents/skills/fe-a11y-dialog/references/dialog.mdskill
.cursor/rules/fe-a11y-dialog.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-dialog.mdc

---
description: Builds modal and non-modal dialogs, alert dialogs, drawers and confirmations that work with keyboard and screen readers (WAI-ARIA APG Dialog pattern) on the native dialog element - name, initial focus, inert background, Escape, focus return. Use when adding a modal, popup, drawer, lightbox, cookie or confirm dialog in any stack, or when asked "make this modal accessible".
globs: **/*.html, **/*.jsx, **/*.tsx, **/*.vue, **/*.svelte, **/*.astro, **/*.component.html
alwaysApply: false
---

# Dialogs and modals (frontend-skills)

- Use `<dialog>` with `showModal()` for modals and `show()` for non-modal ones, not a `div role="dialog"` (a11y/dialog-native).
- Every dialog has a name: `aria-labelledby` pointing at its visible heading (a11y/dialog-name).
- On open, focus goes inside; Tab stays inside a modal; Escape closes; on close, focus returns to the trigger (a11y/dialog-focus).
- The page behind a modal is inert, never just `aria-hidden` over focusable content (a11y/aria-hidden-focusable).
- Only an open modal keeps focus inside; a closed one releases it (a11y/no-keyboard-trap).
- A visible close or cancel button is inside the dialog and in the Tab order.
- Confirmations of destructive actions use `role="alertdialog"` with `aria-describedby` on the message, and focus the safe choice.
- Do not open a modal on page load or on hover; open it from a user action.

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

The real file

Where fe-a11y-dialog lands for GitHub Copilot

.agents/skills/fe-a11y-dialog/SKILL.mdskill
.agents/skills/fe-a11y-dialog/references/dialog.mdskill
.github/instructions/fe-a11y-dialog.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-dialog.instructions.md

---
applyTo: "**/*.html,**/*.jsx,**/*.tsx,**/*.vue,**/*.svelte,**/*.astro,**/*.component.html"
description: "Builds modal and non-modal dialogs, alert dialogs, drawers and confirmations that work with keyboard and screen readers (WAI-ARIA APG Dialog pattern) on the native dialog element - name, initial focus, inert background, Escape, focus return. Use when adding a modal, popup, drawer, lightbox, cookie or confirm dialog in any stack, or when asked \"make this modal accessible\"."
---

# Dialogs and modals (frontend-skills)

- Use `<dialog>` with `showModal()` for modals and `show()` for non-modal ones, not a `div role="dialog"` (a11y/dialog-native).
- Every dialog has a name: `aria-labelledby` pointing at its visible heading (a11y/dialog-name).
- On open, focus goes inside; Tab stays inside a modal; Escape closes; on close, focus returns to the trigger (a11y/dialog-focus).
- The page behind a modal is inert, never just `aria-hidden` over focusable content (a11y/aria-hidden-focusable).
- Only an open modal keeps focus inside; a closed one releases it (a11y/no-keyboard-trap).
- A visible close or cancel button is inside the dialog and in the Tab order.
- Confirmations of destructive actions use `role="alertdialog"` with `aria-describedby` on the message, and focus the safe choice.
- Do not open a modal on page load or on hover; open it from a user action.

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

The real file

Where fe-a11y-dialog lands for Gemini CLI

.agents/skills/fe-a11y-dialog/SKILL.mdskill
.agents/skills/fe-a11y-dialog/references/dialog.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-dialog lands for Antigravity CLI

.agents/skills/fe-a11y-dialog/SKILL.mdskill
.agents/skills/fe-a11y-dialog/references/dialog.mdskill
.agents/rules/fe-a11y-dialog.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-dialog.md

---
trigger: glob
globs: "**/*.html, **/*.jsx, **/*.tsx, **/*.vue, **/*.svelte, **/*.astro, **/*.component.html"
description: "Builds modal and non-modal dialogs, alert dialogs, drawers and confirmations that work with keyboard and screen readers (WAI-ARIA APG Dialog pattern) on the native dialog element - name, initial focus, inert background, Escape, focus return. Use when adding a modal, popup, drawer, lightbox, cookie or confirm dialog in any stack, or when asked \"make this modal accessible\"."
---

# Dialogs and modals (frontend-skills)

- Use `<dialog>` with `showModal()` for modals and `show()` for non-modal ones, not a `div role="dialog"` (a11y/dialog-native).
- Every dialog has a name: `aria-labelledby` pointing at its visible heading (a11y/dialog-name).
- On open, focus goes inside; Tab stays inside a modal; Escape closes; on close, focus returns to the trigger (a11y/dialog-focus).
- The page behind a modal is inert, never just `aria-hidden` over focusable content (a11y/aria-hidden-focusable).
- Only an open modal keeps focus inside; a closed one releases it (a11y/no-keyboard-trap).
- A visible close or cancel button is inside the dialog and in the Tab order.
- Confirmations of destructive actions use `role="alertdialog"` with `aria-describedby` on the message, and focus the safe choice.
- Do not open a modal on page load or on hover; open it from a user action.

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

The real file

Where fe-a11y-dialog lands for Devin / Windsurf

.agents/skills/fe-a11y-dialog/SKILL.mdskill
.agents/skills/fe-a11y-dialog/references/dialog.mdskill
.devin/rules/fe-a11y-dialog.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-dialog.md

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

# Dialogs and modals (frontend-skills)

Builds modal and non-modal dialogs, alert dialogs, drawers and confirmations that work with keyboard and screen readers (WAI-ARIA APG Dialog pattern) on the native dialog element - name, initial focus, inert background, Escape, focus return. Use when adding a modal, popup, drawer, lightbox, cookie or confirm dialog in any stack, or when asked "make this modal accessible".

- Use `<dialog>` with `showModal()` for modals and `show()` for non-modal ones, not a `div role="dialog"` (a11y/dialog-native).
- Every dialog has a name: `aria-labelledby` pointing at its visible heading (a11y/dialog-name).
- On open, focus goes inside; Tab stays inside a modal; Escape closes; on close, focus returns to the trigger (a11y/dialog-focus).
- The page behind a modal is inert, never just `aria-hidden` over focusable content (a11y/aria-hidden-focusable).
- Only an open modal keeps focus inside; a closed one releases it (a11y/no-keyboard-trap).
- A visible close or cancel button is inside the dialog and in the Tab order.
- Confirmations of destructive actions use `role="alertdialog"` with `aria-describedby` on the message, and focus the safe choice.
- Do not open a modal on page load or on hover; open it from a user action.

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

The real file

Where fe-a11y-dialog lands for OpenCode

.agents/skills/fe-a11y-dialog/SKILL.mdskill
.agents/skills/fe-a11y-dialog/references/dialog.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-dialog lands for Cline

.claude/skills/fe-a11y-dialog/SKILL.mdskill
.claude/skills/fe-a11y-dialog/references/dialog.mdskill
.clinerules/fe-a11y-dialog.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-dialog.md

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

# Dialogs and modals (frontend-skills)

Builds modal and non-modal dialogs, alert dialogs, drawers and confirmations that work with keyboard and screen readers (WAI-ARIA APG Dialog pattern) on the native dialog element - name, initial focus, inert background, Escape, focus return. Use when adding a modal, popup, drawer, lightbox, cookie or confirm dialog in any stack, or when asked "make this modal accessible".

- Use `<dialog>` with `showModal()` for modals and `show()` for non-modal ones, not a `div role="dialog"` (a11y/dialog-native).
- Every dialog has a name: `aria-labelledby` pointing at its visible heading (a11y/dialog-name).
- On open, focus goes inside; Tab stays inside a modal; Escape closes; on close, focus returns to the trigger (a11y/dialog-focus).
- The page behind a modal is inert, never just `aria-hidden` over focusable content (a11y/aria-hidden-focusable).
- Only an open modal keeps focus inside; a closed one releases it (a11y/no-keyboard-trap).
- A visible close or cancel button is inside the dialog and in the Tab order.
- Confirmations of destructive actions use `role="alertdialog"` with `aria-describedby` on the message, and focus the safe choice.
- Do not open a modal on page load or on hover; open it from a user action.

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

The real file

Where fe-a11y-dialog lands for Zed

.agents/skills/fe-a11y-dialog/SKILL.mdskill
.agents/skills/fe-a11y-dialog/references/dialog.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-dialog lands for JetBrains Junie

.agents/skills/fe-a11y-dialog/SKILL.mdskill
.agents/skills/fe-a11y-dialog/references/dialog.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-dialog lands for Kiro

.kiro/skills/fe-a11y-dialog/SKILL.mdskill
.kiro/skills/fe-a11y-dialog/references/dialog.mdskill
.kiro/steering/fe-a11y-dialog.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-dialog.md

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

# Dialogs and modals (frontend-skills)

Builds modal and non-modal dialogs, alert dialogs, drawers and confirmations that work with keyboard and screen readers (WAI-ARIA APG Dialog pattern) on the native dialog element - name, initial focus, inert background, Escape, focus return. Use when adding a modal, popup, drawer, lightbox, cookie or confirm dialog in any stack, or when asked "make this modal accessible".

- Use `<dialog>` with `showModal()` for modals and `show()` for non-modal ones, not a `div role="dialog"` (a11y/dialog-native).
- Every dialog has a name: `aria-labelledby` pointing at its visible heading (a11y/dialog-name).
- On open, focus goes inside; Tab stays inside a modal; Escape closes; on close, focus returns to the trigger (a11y/dialog-focus).
- The page behind a modal is inert, never just `aria-hidden` over focusable content (a11y/aria-hidden-focusable).
- Only an open modal keeps focus inside; a closed one releases it (a11y/no-keyboard-trap).
- A visible close or cancel button is inside the dialog and in the Tab order.
- Confirmations of destructive actions use `role="alertdialog"` with `aria-describedby` on the message, and focus the safe choice.
- Do not open a modal on page load or on hover; open it from a user action.

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

The real file

Where fe-a11y-dialog lands for Augment

.agents/skills/fe-a11y-dialog/SKILL.mdskill
.agents/skills/fe-a11y-dialog/references/dialog.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-dialog lands for Trae

.trae/skills/fe-a11y-dialog/SKILL.mdskill
.trae/skills/fe-a11y-dialog/references/dialog.mdskill
.trae/rules/fe-a11y-dialog.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-dialog.md

---
description: "Builds modal and non-modal dialogs, alert dialogs, drawers and confirmations that work with keyboard and screen readers (WAI-ARIA APG Dialog pattern) on the native dialog element - name, initial focus, inert background, Escape, focus return. Use when adding a modal, popup, drawer, lightbox, cookie or confirm dialog in any stack, or when asked \"make this modal accessible\"."
globs: **/*.html,**/*.jsx,**/*.tsx,**/*.vue,**/*.svelte,**/*.astro,**/*.component.html
alwaysApply: false
---

# Dialogs and modals (frontend-skills)

- Use `<dialog>` with `showModal()` for modals and `show()` for non-modal ones, not a `div role="dialog"` (a11y/dialog-native).
- Every dialog has a name: `aria-labelledby` pointing at its visible heading (a11y/dialog-name).
- On open, focus goes inside; Tab stays inside a modal; Escape closes; on close, focus returns to the trigger (a11y/dialog-focus).
- The page behind a modal is inert, never just `aria-hidden` over focusable content (a11y/aria-hidden-focusable).
- Only an open modal keeps focus inside; a closed one releases it (a11y/no-keyboard-trap).
- A visible close or cancel button is inside the dialog and in the Tab order.
- Confirmations of destructive actions use `role="alertdialog"` with `aria-describedby` on the message, and focus the safe choice.
- Do not open a modal on page load or on hover; open it from a user action.

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

The real file

Where fe-a11y-dialog lands for Continue

.frontend-skills/skills/fe-a11y-dialog/SKILL.mdskill
.frontend-skills/skills/fe-a11y-dialog/references/dialog.mdskill
.continue/rules/fe-a11y-dialog.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-dialog.md

---
name: "Dialogs and modals"
description: "Builds modal and non-modal dialogs, alert dialogs, drawers and confirmations that work with keyboard and screen readers (WAI-ARIA APG Dialog pattern) on the native dialog element - name, initial focus, inert background, Escape, focus return. Use when adding a modal, popup, drawer, lightbox, cookie or confirm dialog in any stack, or when asked \"make this modal accessible\"."
globs: ["**/*.html", "**/*.jsx", "**/*.tsx", "**/*.vue", "**/*.svelte", "**/*.astro", "**/*.component.html"]
alwaysApply: false
---

# Dialogs and modals (frontend-skills)

- Use `<dialog>` with `showModal()` for modals and `show()` for non-modal ones, not a `div role="dialog"` (a11y/dialog-native).
- Every dialog has a name: `aria-labelledby` pointing at its visible heading (a11y/dialog-name).
- On open, focus goes inside; Tab stays inside a modal; Escape closes; on close, focus returns to the trigger (a11y/dialog-focus).
- The page behind a modal is inert, never just `aria-hidden` over focusable content (a11y/aria-hidden-focusable).
- Only an open modal keeps focus inside; a closed one releases it (a11y/no-keyboard-trap).
- A visible close or cancel button is inside the dialog and in the Tab order.
- Confirmations of destructive actions use `role="alertdialog"` with `aria-describedby` on the message, and focus the safe choice.
- Do not open a modal on page load or on hover; open it from a user action.

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

The real file

Where fe-a11y-dialog lands for Amazon Q Developer

.frontend-skills/skills/fe-a11y-dialog/SKILL.mdskill
.frontend-skills/skills/fe-a11y-dialog/references/dialog.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-dialog` (Dialogs and modals): when editing `**/*.html`, `**/*.jsx`, `**/*.tsx`, `**/*.vue`, `**/*.svelte`, `**/*.astro`, `**/*.component.html`, first read `.frontend-skills/skills/fe-a11y-dialog/SKILL.md`.

The real file

Where fe-a11y-dialog lands for Aider

.frontend-skills/skills/fe-a11y-dialog/SKILL.mdskill
.frontend-skills/skills/fe-a11y-dialog/references/dialog.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-dialog` (Dialogs and modals): when editing `**/*.html`, `**/*.jsx`, `**/*.tsx`, `**/*.vue`, `**/*.svelte`, `**/*.astro`, `**/*.component.html`, first read `.frontend-skills/skills/fe-a11y-dialog/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:

make this modal accessible

And to check and fix the work:

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

Rules it teaches

a11y/dialog-native
Build dialogs on the native <dialog> element opened with showModal() rather than a div with role="dialog".
minorstaticWCAG 2.4.3, 4.1.2
a11y/dialog-name
Every dialog has an accessible name, usually aria-labelledby pointing at its visible heading.
seriousstaticWCAG 4.1.2
a11y/dialog-focus
A modal moves focus inside on open, keeps Tab inside, closes on Escape, and returns focus to the control that opened it.
seriousmanualWCAG 2.4.3, 2.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/no-keyboard-trap
Keyboard focus can always leave a component with Tab, Shift+Tab or Escape; only an open modal keeps focus inside.
criticalmanualWCAG 2.1.2

The rule digest

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

Use <dialog> with showModal() for modals and show() for non-modal ones, not a div role="dialog" (a11y/dialog-native).
Every dialog has a name: aria-labelledby pointing at its visible heading (a11y/dialog-name).
On open, focus goes inside; Tab stays inside a modal; Escape closes; on close, focus returns to the trigger (a11y/dialog-focus).
The page behind a modal is inert, never just aria-hidden over focusable content (a11y/aria-hidden-focusable).
Only an open modal keeps focus inside; a closed one releases it (a11y/no-keyboard-trap).
A visible close or cancel button is inside the dialog and in the Tab order.
Confirmations of destructive actions use role="alertdialog" with aria-describedby on the message, and focus the safe choice.
Do not open a modal on page load or on hover; open it from a user action.

Steps the agent follows

Check the project's UI library first (Radix, React Aria, Reka UI, bits-ui, Angular CDK Dialog, Headless UI): if it provides a dialog, use it the documented way instead of writing one.
Otherwise write <dialog aria-labelledby="id"> with a heading, content and a <form method="dialog"> for the close buttons; open it from a <button type="button"> with showModal().
Set initial focus with autofocus on the right element inside the dialog: the first field, or the least destructive button.
Keep the trigger in a variable and focus it in the close event if the browser did not.
Style the overlay with ::backdrop; stop background scroll with body:has(dialog[open]) { overflow: hidden; }.
For a side drawer or full-screen menu, use the same <dialog>; for a small popup next to its trigger without blocking the page, use popover.

How the agent checks the work

npx github:dawidolko/frontend-skills audit --changed finds unnamed dialogs, div dialogs and aria-hidden over focusable content.
By hand: open with the keyboard, Tab and Shift+Tab around (focus stays inside), press Escape (it closes, focus is back on the trigger), and listen with a screen reader (name and role are read on open).

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/dialog.md1280 tokens

SKILL.md on GitHub