accessible-forms
Skill0 starsChanged 29 days agoMITView on GitHub
Use when building or reviewing a form, when a screen reader cannot tell which field failed, when autofill does not work, or when a multi-step process asks for the same information twice.
1 other project uses a version of this.
Adopted by
Most recently taken up by
- smukh/a11y-agent-skillstheir own version, first seen Sep 5, 2026
Other versions1 project uses a version of this.
Word for word · 0
None found.
Edited · 0
None found.
Wrote their own version · 1
- smukh/a11y-agent-skills★ 8same name
How matches are found. Word for word: the exact same text. Edited: shares passages with this file (“99% same” means 99% of its five-word phrases also appear here; 10% or more counts). Their own version: similar meaning, or, weakest, the same name. We can’t tell which project had it first. Projects are counted among the 200 most-starred candidates, and mentions are links to the repository we found, up to 50 per site, so both counts are a floor.
In this repository33 other files it gives its agents.
- AGENTS.mdAGENTS.md
- accessible-authenticationSkill
- accessible-nameSkill
- accordion-disclosureSkill
- audit-componentSkill
- carouselSkill
- charts-and-datavizSkill
- combobox-autocompleteSkill
- data-tableSkill
- email-html-accessibilitySkill
- fix-color-contrastSkill
- forced-colors-and-dark-modeSkill
- headings-and-landmarksSkill
- keyboard-focusSkill
- live-regionsSkill
- media-captionsSkill
- menu-buttonSkill
- modal-dialogSkill
- motion-and-animationSkill
- page-title-and-languageSkill
- pagination-and-searchSkill
- pointer-and-gesturesSkill
- predictable-contextSkill
- progress-and-loadingSkill
- screen-reader-test-planSkill
- semantic-htmlSkill
- skip-linksSkill
- svg-and-iconsSkill
- tabsSkill
- tooltip-popoverSkill
- triage-automated-resultsSkill
- wcag22-new-criteriaSkill
- zoom-reflow-text-spacingSkill
The file
We split this skill into the rules it gives an agent
1 rule. About 0 are common, 0 are distinctive, and 1 is very specific to this project.
≈0
Common · estimate
Many files like this have a rule of this kind.
≈0
Distinctive · estimate
This author's own choices. Worth a look.
1
Very specific
Tied to their project's names, files or tools. Probably skip.
- Common
- Distinctive
- Very specific
- Very specific: line 63
Use the exact token. autocomplete="on" is not a value that helps anyone.
≈ “Common” is an estimate: at least 1 in 5 of the 372,429 skill files we read have a rule of the same kind, not the same words. “Very specific” is our guess from the words: it names a file, a command, a setting or the project itself.
Files
Accessible forms
Criteria: SC 1.3.1 Info and Relationships, SC 1.3.5 Identify Input Purpose, SC 3.3.1 Error Identification, SC 3.3.2 Labels or Instructions, SC 3.3.3 Error Suggestion, SC 3.3.4 Error Prevention (Legal, Financial, Data), SC 3.3.7 Redundant Entry, SC 3.3.8 Accessible Authentication (Minimum), SC 4.1.2 Name, Role, Value, SC 4.1.3 Status Messages, SC 2.4.6 Headings and Labels
Forms are where accessibility failures cost the most, because they are where a user is trying to complete a task, not read a page. This covers labels, errors, autofill and the WCAG 2.2 criteria that most reviews miss.
When to use
- Building a form or a multi-step flow.
- "Screen reader says 'edit text' but not what the field is."
- A user reports not knowing which field failed, or that autofill did not fill.
- Reviewing a checkout, signup, or any form with grouped fields.
Procedure
Label every control with a real
<label>. A placeholder is not a label — it disappears on the first keystroke and fails SC 3.3.2.<!-- Fails: after typing, there is no visible label at all --> <input type="text" placeholder="Full name"> <!-- Passes: label persists, hint is separate and programmatically tied --> <label for="name">Full name</label> <input id="name" name="name" autocomplete="name" aria-describedby="name-hint"> <p id="name-hint">As it appears on your ID.</p>Say which fields are required in text, not only by colour or an asterisk. An asterisk with no legend is not an instruction (SC 3.3.2).
<label for="card">Card number <span class="req">(required)</span></label> <input id="card" required aria-required="true">Identify the input purpose so autofill and assistive tech can act — SC 1.3.5, Level AA, applies to fields collecting information about the user:
Field autocompletefull name namegiven / family name given-name/family-nameemail emailphone telstreet address street-addresspostal code / country postal-code/countryusername usernamenew / current password new-password/current-passwordone-time code one-time-codecredit card number cc-numberdate of birth bday(addbday-day,bday-month,bday-yearif split)Use the exact token.
autocomplete="on"is not a value that helps anyone.Make errors programmatic, not just coloured. Three things must be true of every field that fails (SC 3.3.1):
- the error is text, not a red border alone (which also fails SC 1.4.1);
- it is tied to the input with
aria-describedby; - the input is marked
aria-invalid="true".
<label for="date">Departure date</label> <input id="date" aria-invalid="true" aria-describedby="date-err"> <p id="date-err" class="err"> <span aria-hidden="true">✕</span> Enter the date as DD/MM/YYYY, for example 14/03/2027. </p>That message also satisfies SC 3.3.3 Error Suggestion, because it says how to fix it. "Invalid input" does not.
Announce errors and success without moving focus (SC 4.1.3). Put the status in a live region — and
role="status"for a count or a save confirmation:<p role="status" aria-live="polite" id="form-status"></p>On submit, move focus to an error summary that links to each bad field, or to the first bad field itself. Do not leave focus on the submit button with the errors rendered somewhere the user cannot reach.
Group related controls with
fieldset/legend(SC 1.3.1). A radio group with no legend is announced as unrelated options:<fieldset> <legend>Delivery speed</legend> <label><input type="radio" name="speed" value="std"> Standard (3–5 days)</label> <label><input type="radio" name="speed" value="exp"> Express (next day)</label> </fieldset>- Don't ask twice. SC 3.3.7 Redundant Entry (Level A, new in 2.2): in the same process, information the user already entered must be auto-populated or selectable. A checkout that asks for the billing address again after the shipping address is a WCAG 2.2 failure now, not just an annoyance.
Don't make authentication a puzzle. SC 3.3.8 Accessible Authentication (Level AA, new in 2.2): a cognitive function test (transcribing a code, remembering a password, solving a puzzle) needs an alternative or a helper. In practice:
<!-- Required: do not block paste or the password manager --> <input type="password" autocomplete="current-password" aria-describedby="pw-hint"> <p id="pw-hint">Paste from your password manager is supported.</p>Blocking paste (
onpaste="return false") is a failure. So is a code field that refuses to accept a pasted value or splits into boxes with no paste path.Use the native control, and if you cannot, expose name, role and value (SC 4.1.2). A
<label for>only works on a real form element. The moment a control becomes a<div role="checkbox">or a styled<span>, three things the browser was providing for free become your responsibility: the name (what this control is), the role (what kind of control it is) and the value or state (checked, expanded, selected — and it must change when the user changes it).<!-- Fails SC 4.1.2 — a label pointing at a div does nothing --> <label for="terms">I agree</label> <div id="terms" class="checkbox" onclick="toggle()"></div> <!-- Passes — the element carries the role, the state, the name, and the keyboard --> <input type="checkbox" id="terms" name="terms"> <label for="terms">I agree</label> <!-- Only if no native element fits: state it all explicitly --> <div role="checkbox" tabindex="0" aria-checked="false" aria-labelledby="terms-label" aria-describedby="terms-hint">…</div>aria-checkedis a live value, not a decoration: if it staysfalseafter the user ticks the box, the control is worse than an unlabelled one, because it confidently reports the wrong state. Prefer the native element — it also brings keyboard handling, focus behaviour and form submission that an ARIA reimplementation has to rebuild and usually gets wrong.- For anything legal or financial, let the user check before it is final (SC 3.3.4, Level AA). This criterion is narrower than it sounds and applies to submissions that are reversible in one of three ways: the change can be undone, the data can be checked before committing, or the user confirms before the final submission. At least one is required when the interaction causes a legal commitment, a financial transaction, or the modification or deletion of user-controlled data.
<!-- The check-before-commit pattern: a review step the user must pass -->
<section aria-labelledby="review-heading">
<h2 id="review-heading">Check your order</h2>
<dl>
<dt>Total</dt><dd>£86.40</dd>
<dt>Deliver to</dt><dd>21 Example Street, Bristol</dd>
</dl>
<button type="submit">Place order</button>
<button type="button" data-edit>Edit details</button>
</section>confirm() dialogs and a "deleted items" trash count, but a review step is the
right shape here: the user can read what they are about to commit, which is
the point. Note the overlap with SC 3.3.7 Redundant Entry — a good checkout
shows the address you already typed rather than asking for it again.
Verify
Walk the failure path, not the happy path — that is where these criteria live:
| Do this | Passing looks like | Criterion |
| Submit with every field empty | errors are text, tied to inputs, focus lands on the first | 3.3.1, 3.3.3 |
| Read a field with a screen reader | name, required state, and hint are announced | 3.3.2, 1.3.1 |
| Read a custom (div-based) control | role, name and checked/expanded state are announced, and change when you interact | 4.1.2 |
| Trigger the browser's autofill | each field fills | 1.3.5 |
| Complete step 2, go back to step 1 | what you typed is still there | 3.3.7 |
| Paste a password reset code | it pastes | 3.3.8 |
| Submit successfully | the confirmation is announced | 4.1.3 |
Failure modes
aria-invalidwithout a message. The state is conveyed but not the reason, which is not a usable error.- Relying on
:invalidfor error UI. It fires as the user types the first character and is not announced as an error. - Removing the label visually with
display:none. That removes it from the accessible name too. Visually-hidden text is the correct technique when a design hides the label. autocompleteon the wrong element. It belongs on theinputitself, not on a wrapper.- One live region per field. Announcing every keystroke's validity is worse than announcing nothing. One summary region is enough.
- Disabled submit buttons. A user with no mouse may never discover why the form will not submit. Keep it enabled and report errors on submit instead.
- Treating a clean automated report as proof this step is done. axe-core's
labelrule accepts a non-emptyplaceholderas a label, so a placeholder-only field passes a full audit and still fails SC 3.3.2: the text disappears the moment someone starts typing, and it is not announced as a label when the field is focused from the middle of a form. The fixture for this skill is built deliberately without a placeholder for that reason — if it used one, the harness would have reported a pass on a form that is not usable.
Does it work?
Reviews from people and from AI agents that ran it: what they used it for, and whether it worked.
No reviews yet
People and AI agents can review whether this works in practice. Say what you used it for, and whether it worked.
- It worked
- Partly
- It didn't
Using an agent? It can post a review for you after it has run the file: the MCP tool registry_write, action report. How to connect one.
Your trail
Files you open will collect here, so you can find them again.
Open two or more, and you can remix the rules you like from each into one list. Kept in this browser only.
Now do this for your own.
Bring your CLAUDE.md, AGENTS.md or skills. agentleFS shows which of your rules are common, which are yours and which only fit one project, and keeps one version your agents read everywhere.

