agentleFS
AdilSiddiquiHQAdilSiddiquiHQ/a11y-skills/skills/accessible-forms/SKILL.md

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

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
  1. Very specific:

    Use the exact token. autocomplete="on" is not a value that helps anyone.

    line 63

≈ “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.

Keep what fits and drop the rest. Your version, ready for your agents.
Files
SKILL.md

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

  1. 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>
  2. 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">
  3. 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:

    Fieldautocomplete
    full namename
    given / family namegiven-name / family-name
    emailemail
    phonetel
    street addressstreet-address
    postal code / countrypostal-code / country
    usernameusername
    new / current passwordnew-password / current-password
    one-time codeone-time-code
    credit card numbercc-number
    date of birthbday (add bday-day, bday-month, bday-year if split)

    Use the exact token. autocomplete="on" is not a value that helps anyone.

  4. 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.

  5. 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.

  6. 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>
  7. 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.
  8. 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.

  9. 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-checked is a live value, not a decoration: if it stays false after 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.

  10. 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 thisPassing looks likeCriterion
Submit with every field emptyerrors are text, tied to inputs, focus lands on the first3.3.1, 3.3.3
Read a field with a screen readername, required state, and hint are announced3.3.2, 1.3.1
Read a custom (div-based) controlrole, name and checked/expanded state are announced, and change when you interact4.1.2
Trigger the browser's autofilleach field fills1.3.5
Complete step 2, go back to step 1what you typed is still there3.3.7
Paste a password reset codeit pastes3.3.8
Submit successfullythe confirmation is announced4.1.3

Failure modes

  • aria-invalid without a message. The state is conveyed but not the reason, which is not a usable error.
  • Relying on :invalid for 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.
  • autocomplete on the wrong element. It belongs on the input itself, 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 label rule accepts a non-empty placeholder as 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.

Download now (ZIP)

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
What did you use it for? e.g. Reviewing pull requests in a Rails app

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.