Agent skill
Everything this site argues, packaged so a coding agent can load it. Most accessibility barriers are not missing ARIA — they are a native element that got replaced by a div and then partially rebuilt. An agent that knows this reaches for the element instead.
Install it
A skill is a folder: one SKILL.md holding the rules, plus reference files the agent opens only when the task calls for them. Drop it wherever your tool loads skills from — for Claude Code that is ~/.claude/skills/.
git clone https://github.com/ThomasSweet/a11y-foundation
cp -r a11y-foundation/skills/accessible-by-default ~/.claude/skills/What it tells an agent
Mostly one instruction in different shapes: use the thing that already does the job. Eight of the swaps it asks for:
- A modal Use
<dialog> + showModal()Not a div plus a focus-trap library - A menu or a tooltip Use
popoverNot a div plus a click-outside handler - Expand and collapse Use
<details> / <summary>Not a div plus aria-expanded plus height JS - A dropdown Use
<select>Not a div with listbox roles - Anything clickable Use
<button>Not a div with a click handler - Anything that navigates Use
<a href>Not a button that calls the router - A field label Use
<label for>Not a placeholder, or aria-label alone - Validation styling Use
:user-valid / :user-invalidNot toggling classes on every keystroke
Each native element arrives with keyboard behaviour, focus management, a role, a name, and conventions the user already knows. A rebuilt version starts at zero and has to earn all of it back. That gap is where the barriers come from.
What’s in it
- SKILL.md
- The decisions: what to reach for, what never to break, how to guard a feature that is not Baseline yet, and the ways this usually goes wrong.
- references/wcag-criteria.md
- The success criteria most often broken by hand-built components, each with its requirement and who pays when it is missed.
- references/modern-css.md
- Every feature in the showcase, grouped by Baseline tier, with the guard it needs, if any, and the accessibility problem it solves.
- references/css-snippets.md
- The accessible implementation of each one, free of this project’s tokens and mixins, so it is copy-paste ready.
The three reference files are generated from the same registries this site renders, and a check in CI fails when the committed copy falls behind, so the skill cannot quietly drift from the demos you can click here.
A note on shelf life
The rules are the durable part. They describe what the web platform does, and that moves slowly. How agents load skills is new and moving fast, so the install path and the file layout above may already be behind by the time you read this. If the mechanics do not match what your tool expects, treat the folder in the repository as the source of truth — the guidance inside it transfers either way.