forms · diff
git:20260331.f09d889 to git:20260722.125074b
278 added, 167 removed. Audit A to A.
What this update changes in the checks
No check changed: every fixed check gives the same answer before and after this update.
A tripped check is a label, not a verdict: read the matched text and the lines below. This week's updates that newly trip a check.
---
name: forms
description: >
Load this skill whenever the project contains forms, inputs, selects,
checkboxes, radio buttons, text areas, or any validation flow. Under no
circumstances create a form without visible labels, error identification, and
keyboard accessibility. Absolutely always associate every input with a label
and provide clear, accessible error messages.
---
# Forms Accessibility Skill
> **Canonical source**: `examples/FORMS_ACCESSIBILITY_BEST_PRACTICES.md` in `mgifford/ACCESSIBILITY.md`
> This skill is derived from that file. When in doubt, the example is authoritative.
Apply these rules when implementing or reviewing any form, input, or validation flow.
**Only load this skill if the project contains forms.**
---
## Core Mandate
- All users must be able to understand, complete, and submit forms with assistive
- technologies, keyboard-only input, and varying cognitive needs.
+ Forms must be understandable and operable with keyboards, touch, speech input,
+ screen readers, screen magnification, browser autofill, password managers, and
+ other assistive technologies. Requirements apply to initial entry, validation,
+ recovery, review, submission, and authentication. Users must be able to
+ complete time-limited forms when a time limit is not essential, and complete
+ the form at 200%/400% zoom without losing content or functionality.
+ Prefer native HTML controls. Build a custom widget only when native controls
+ cannot meet the documented requirement, and implement the applicable keyboard,
+ focus, name, role, state, and value behaviour.
+
---
## Severity Scale (this skill)
| Level | Meaning |
| --- | --- |
| **Critical** | Blocks task completion entirely for one or more disability groups |
| **Serious** | Significantly impairs access; workaround unreasonable to expect |
| **Moderate** | Creates friction; workaround exists and is not too burdensome |
| **Minor** | Best-practice gap; marginal impact on access |
+ Do not assign severity from the violated rule alone — determine it from the
+ actual form and task. Consider: whether the defect blocks submission or
+ recovery; whether it affects authentication, payment, health, legal, safety,
+ or essential public services; how many users/controls are affected; whether a
+ reasonable workaround exists; whether it comes from a shared component; and
+ whether data can be lost.
+
---
## Critical: Labels
Every form control must have a programmatically associated label.
**Missing labels are Critical** — screen reader users cannot identify the field.
* Never use placeholder text as the sole label — it disappears on input, fails
contrast requirements, and is not reliably announced by all screen readers
* Required fields must be identified in text, not by colour alone
+ * A control nested inside its own `<label>` is also valid
+ * Use `aria-label`/`aria-labelledby` only when a visible HTML label is not
+ practical, and ensure the accessible name includes the words users can see
+ (speech-input users identify controls by their visible label)
+ * Controls whose content already supplies a name (e.g., `<button>Save</button>`)
+ don't need a separate label
```html
<!-- Bad: placeholder as only label — CRITICAL issue -->
<input type="email" placeholder="Email address">
<!-- Good: explicit label -->
<label for="email">
Email address <span class="visually-hidden">(required)</span>
</label>
<input type="email" id="email" autocomplete="email" required>
```
**On `aria-required`:** Do not add `aria-required="true"` to native inputs
that already have the HTML `required` attribute — it is redundant and adds
noise to the accessibility tree. Use `aria-required` only on custom widgets
(e.g., `role="combobox"`, `role="listbox"`) that cannot use the native attribute.
+ **Required/optional fields:** explain how required fields are identified
+ before the first field (e.g., "Fields marked 'required' must be completed").
+ Don't rely on an asterisk or colour alone. Don't mark every optional field
+ when marking the smaller set of required fields would be clearer, or vice versa.
+
---
## Critical: Error Identification
Errors must be programmatically associated with their field.
**Absent error identification is Critical** — blind users receive no indication
something is wrong.
- * Mark invalid fields with `aria-invalid="true"`
+ * Mark invalid fields with `aria-invalid="true"` after validation determines
+ they are invalid; remove the invalid state and error association after correction
* Error messages must be specific and actionable — not just "invalid input"
- * Never use colour alone to indicate an error
- * Associate the error message with the field via `aria-describedby`
+ * Never use colour or an icon alone to indicate an error
+ * Associate the error message with the field via `aria-describedby` (or a
+ tested `aria-errormessage` implementation); preserve any existing hint association
+ * Keep the entered value unless security requires otherwise
```html
<label for="email">Email address</label>
- <input type="email" id="email"
- aria-describedby="email-error"
- aria-invalid="true">
- <span id="email-error" role="alert">
- Enter a valid email address, for example: name@example.com
- </span>
+ <p id="email-hint">We will send the receipt to this address.</p>
+ <input id="email" name="email" type="email" autocomplete="email"
+ aria-invalid="true" aria-describedby="email-hint email-error">
+ <p id="email-error">
+ <strong>Error:</strong> Enter an email address in the format name@example.com.
+ </p>
```
- Remove `aria-invalid` and the error message once the field is corrected.
+ Do not put `role="alert"` on error text that is already present when the page
+ loads — a live region only announces changes made *after* it is established.
+ Avoid combining several competing announcement mechanisms without AT testing.
---
## Critical: Error Summary
- For multi-error submissions, provide a focused error summary so keyboard and
- screen reader users are immediately oriented to what went wrong.
- **No error summary on multi-error forms is Critical.**
+ Provide an error summary when several fields can fail, the form is long,
+ errors may be outside the viewport, or users would otherwise have difficulty
+ locating them. **No error summary on multi-error, long, or complex forms is Critical.**
```html
- <div role="alert" aria-labelledby="error-heading"
- tabindex="-1" id="error-summary">
- <h2 id="error-heading">There are 2 errors in this form</h2>
+ <div id="error-summary" tabindex="-1" aria-labelledby="error-heading">
+ <h2 id="error-heading">There are 2 errors</h2>
<ul>
- <li><a href="#email">Email address – enter a valid email</a></li>
- <li><a href="#dob">Date of birth – enter a real date</a></li>
+ <li><a href="#email">Email address: enter a valid email address</a></li>
+ <li><a href="#dob-day">Date of birth: enter a real date</a></li>
</ul>
</div>
```
- Move focus to `#error-summary` immediately after a failed submit.
- Each link in the list must take focus directly to the affected field.
+ * Place the summary before or at the beginning of the form; insert it after a
+ failed submission and move focus to it
+ * Use links that identify both the field and the problem; activating a link
+ must move focus to the relevant control
+ * Keep the inline field message as well as the summary; update the heading
+ count when errors change
+ * Avoid adding `role="alert"` when focus movement already causes a clear
+ announcement, unless testing shows an additional live announcement helps
+ * Focus movement is a deliberate response to the submit action — don't move
+ focus on every inline validation change
---
## Critical: Do Not Block Paste
Never block paste, copy, or standard keyboard actions on any input.
**Blocking paste is Critical** — users with motor disabilities and those who use
password managers cannot re-type credentials they cannot physically type.
---
+ ## Serious: Accessible Authentication (WCAG 3.3.8)
+
+ Authentication must not require users to remember, manipulate, or transcribe
+ information unless a conforming alternative or assistance mechanism exists.
+ At minimum:
+
+ * Allow password managers to identify and fill username/password fields
+ * Allow copy and paste into username, password, and verification-code fields
+ — do not split a one-time code into controls that prevent pasting the whole code
+ * Do not ask for selected characters from a password
+ * Use appropriate autocomplete tokens (`username`, `current-password`, `new-password`,
+ `one-time-code`)
+ * Provide a multi-factor path that doesn't require unsupported transcription
+ or a cognitive puzzle; account recovery must meet the same requirements as login
+ * If a CAPTCHA or cognitive test is used, evaluate it against WCAG 3.3.8 and
+ provide an applicable alternative
+
+ ```html
+ <label for="username">Email address</label>
+ <input id="username" name="username" type="email" autocomplete="username">
+ <label for="password">Password</label>
+ <input id="password" name="password" type="password" autocomplete="current-password">
+ <button type="button" aria-controls="password" aria-pressed="false">
+ Show password
+ </button>
+ ```
+
+ A show-password button must update its visible label/pressed state
+ consistently, preserve focus, and not clear the value.
+
+ ---
+
## Serious: Grouping Related Controls
Use `<fieldset>` + `<legend>` for related controls.
**Missing grouping is Serious** — radio and checkbox groups become unintelligible
without a group label.
```html
<fieldset>
<legend>Notification preferences</legend>
<label><input type="checkbox" name="email-notify"> Email</label>
<label><input type="checkbox" name="sms-notify"> SMS</label>
</fieldset>
```
+ Keep legends concise; don't use `<fieldset>` solely for visual styling. For a
+ checkbox set that allows multiple selections, state that users may select
+ more than one.
+
---
## Serious: Input Types
- Use the most specific applicable input type. This surfaces the correct virtual
- keyboard on mobile and provides semantic meaning to AT.
+ Choose `type`, `autocomplete`, and `inputmode` independently according to what
+ the value means. This surfaces the correct virtual keyboard on mobile and
+ provides semantic meaning to AT.
- | Need | Use | Avoid |
- | --- | --- | --- |
- | Email address | `type="email"` | `type="text"` |
- | Phone number | `type="tel"` | `type="number"` |
- | Search | `type="search"` | `type="text"` |
- | Web URL | `type="url"` | `type="text"` |
- | Password | `type="password"` | `type="text"` |
- | Date | See date guidance below | `type="text"` alone |
+ | Information | Recommended control |
+ | --- | --- |
+ | Email address | `type="email" autocomplete="email"` |
+ | Telephone number | `type="tel" autocomplete="tel"` |
+ | Website address | `type="url" autocomplete="url"` |
+ | Search query | `type="search"` |
+ | Current / new password | `type="password" autocomplete="current-password"` / `"new-password"` |
+ | One-time code | One text input, `autocomplete="one-time-code" inputmode="numeric"` |
+ | Numeric quantity with increment/decrement semantics | `type="number"` |
+ | Numeric-looking identifier, postal code, card number | `type="text"` with matching `inputmode`/`autocomplete` |
- ### `type="number"` — use with caution
+ ### Do not treat all digits as numbers
- `type="number"` has inconsistent screen reader support and unexpected behaviour
- (scroll wheel changes values, non-numeric characters silently stripped).
- **Prefer `type="text"` with `inputmode="numeric"` and `pattern="[0-9]*"`**
- for quantities, codes, and amounts:
+ Use `type="number"` only for values on which mathematical operations make
+ sense and `min`/`max`/`step` are useful — never for identifiers or values that
+ may contain leading zeros:
```html
- <!-- Good: text input with numeric keyboard on mobile -->
<label for="quantity">Quantity</label>
- <input type="text" id="quantity"
- inputmode="numeric"
- pattern="[0-9]*"
- autocomplete="off">
+ <input id="quantity" name="quantity" type="number" min="1" max="20" step="1">
- <!-- Only use type="number" when the stepper arrows are genuinely useful
- and the value range is small and well-defined -->
+ <label for="postal-code">Postal code</label>
+ <input id="postal-code" name="postal-code" type="text" autocomplete="postal-code">
```
- ### Date inputs
+ `inputmode` requests a virtual keyboard; it does not validate the value. Add
+ `pattern` only when the resulting constraint and error message are correct for
+ every accepted value — do not assume all users enter ASCII digits.
- Native `<input type="date">` has reasonable accessibility support in modern
- browsers but inconsistent screen reader announcement. Evaluate against your
- AT support matrix before using.
+ ### Date inputs
- For complex date ranges or date pickers, prefer three separate labelled inputs
- (day/month/year) over a custom calendar widget — they work with all AT without
- JavaScript:
+ Use a native `<input type="date">` when it meets the product's locale,
+ browser, and AT requirements — test the actual implementation. For dates like
+ date of birth, separate labelled text inputs are often easier to understand
+ and validate than a native date picker or custom calendar widget:
```html
<fieldset>
<legend>Date of birth</legend>
+ <p id="dob-hint">For example, 23 4 1980.</p>
<label for="dob-day">Day</label>
- <input type="text" id="dob-day" inputmode="numeric"
- pattern="[0-9]{1,2}" autocomplete="bday-day"
- aria-describedby="dob-hint">
+ <input id="dob-day" name="dob-day" inputmode="numeric"
+ autocomplete="bday-day" aria-describedby="dob-hint">
<label for="dob-month">Month</label>
- <input type="text" id="dob-month" inputmode="numeric"
- pattern="[0-9]{1,2}" autocomplete="bday-month">
+ <input id="dob-month" name="dob-month" inputmode="numeric" autocomplete="bday-month">
<label for="dob-year">Year</label>
- <input type="text" id="dob-year" inputmode="numeric"
- pattern="[0-9]{4}" autocomplete="bday-year">
- <p id="dob-hint">For example: 23 4 1980</p>
+ <input id="dob-year" name="dob-year" inputmode="numeric" autocomplete="bday-year">
</fieldset>
```
- ### `<select>` — single
-
- Native `<select>` is well-supported by all AT. Use it for choosing one option
- from a known, bounded list.
-
- ```html
- <label for="country">Country</label>
- <select id="country" autocomplete="country-name">
- <option value="">Select a country</option>
- <option value="ca">Canada</option>
- <option value="us">United States</option>
- </select>
- ```
-
- Always include a blank/placeholder option as the first `<option>` when no
- default is appropriate — do not use `selected` to pre-select a value unless
- it genuinely reflects the user's likely choice.
-
- ### `<select multiple>`
+ Do not build a custom calendar dialog unless users need calendar-based
+ selection; if one is required, implement and test the complete dialog and
+ grid keyboard interaction (see the APG Date Picker pattern).
- `<select multiple>` has **poor usability** for many users, including those
- with motor and cognitive disabilities. The multi-select interaction (hold Shift
- or Ctrl while clicking) is non-obvious and keyboard-unfriendly.
+ ### `<select>` — single
- **Prefer checkboxes inside a `<fieldset>` for multiple selection** unless the
- list is very long and a search/filter is provided:
+ Native `<select>` is well-supported by all AT. Always include a blank/placeholder
+ option as the first `<option>` when no default is appropriate.
- ```html
- <!-- Prefer this over <select multiple> -->
- <fieldset>
- <legend>Topics (select all that apply)</legend>
- <label><input type="checkbox" name="topic" value="html"> HTML</label>
- <label><input type="checkbox" name="topic" value="css"> CSS</label>
- <label><input type="checkbox" name="topic" value="js"> JavaScript</label>
- </fieldset>
- ```
+ ### Multiple selection
- If `<select multiple>` must be used, add visible instructions:
- `<p id="select-hint">Hold Ctrl (or Cmd on Mac) to select multiple options.</p>`
- and reference it with `aria-describedby`.
+ `<select multiple>` has poor discoverability (Shift/Ctrl-click) and is
+ keyboard-unfriendly. **Prefer checkboxes inside a `<fieldset>`** for a short,
+ known list. `<select multiple>` may be appropriate for expert interfaces but
+ must be usability-tested with the intended audience; if used, add visible
+ instructions (`Hold Ctrl (or Cmd on Mac) to select multiple options.`) referenced
+ via `aria-describedby`.
### `<datalist>`
- `<datalist>` provides autocomplete suggestions for a text input. It is
- natively keyboard accessible and announced by most screen readers, but
- announcement quality varies — test with your AT matrix.
-
- ```html
- <label for="browser">Preferred browser</label>
- <input type="text" id="browser"
- list="browsers"
- autocomplete="off"
- aria-describedby="browser-hint">
- <datalist id="browsers">
- <option value="Chrome">
- <option value="Firefox">
- <option value="Safari">
- <option value="Edge">
- </datalist>
- <p id="browser-hint" class="visually-hidden">
- Start typing to see suggestions, or type your own value.
- </p>
- ```
-
- Note: `<datalist>` is not a replacement for a fully accessible combobox when
- the suggestion list is the only valid set of values. Use `role="combobox"` with
- the [APG Combobox pattern](https://www.w3.org/WAI/ARIA/apg/patterns/combobox/)
- when the input must be constrained to the list.
+ Provides autocomplete suggestions for a text input; natively keyboard
+ accessible but announcement quality varies — test with your AT matrix. Not a
+ replacement for a fully accessible combobox when the suggestion list is the
+ only valid set of values — use `role="combobox"` with the
+ [APG Combobox pattern](https://www.w3.org/WAI/ARIA/apg/patterns/combobox/) instead.
---
## Serious: Autocomplete for Personal Data
Missing `autocomplete` on personal-data fields is **Serious** — it directly
impacts users with motor disabilities and cognitive conditions who rely on
- autofill to avoid retyping.
+ autofill to avoid retyping. The label, `name`, `type`, and autocomplete token
+ should describe the same purpose.
```html
<input type="text" id="name" autocomplete="name">
<input type="email" id="email" autocomplete="email">
<input type="tel" id="phone" autocomplete="tel">
- <input type="text" id="street" autocomplete="street-address">
+ <textarea id="street" autocomplete="street-address"></textarea>
<input type="text" id="city" autocomplete="address-level2">
<input type="text" id="postal" autocomplete="postal-code">
- <input type="password" id="current-pass" autocomplete="current-password">
- <input type="password" id="new-pass" autocomplete="new-password">
```
- Full list of valid `autocomplete` token values:
- [WCAG 1.3.5 Input Purposes](https://www.w3.org/TR/WCAG21/#input-purposes)
+ Test autofill without assuming `autocomplete="off"` will or should disable
+ password managers and browser assistance. Full token list:
+ [WCAG 1.3.5 Input Purposes](https://www.w3.org/TR/WCAG21/#input-purposes).
---
+ ## Serious: Buttons and Submission Controls
+
+ * Every button must have a clear name describing its result; always specify
+ `type` (a `<button>` inside a form defaults to `submit`)
+ * Distinguish primary submission from secondary actions; avoid vague labels
+ like "Go" or "Continue" when a more specific label is practical
+ * Do not permanently disable the submit button merely because the form is
+ incomplete — users must be able to discover validation errors and recover
+ * Prevent duplicate submissions without removing status information or
+ trapping focus
+
+ ---
+
## Serious: Async & Status Feedback
- * Use `aria-live="polite"` for non-critical updates (character counts, inline validation)
- * Use `aria-live="assertive"` **only** for blocking failures — it interrupts
- the screen reader immediately
- * Announce submission success and failure to AT
+ * Use `aria-live="polite"` / `role="status"` for routine progress and
+ successful completion; reserve assertive announcements for urgent
+ information that cannot wait
+ * Keep visible status text available long enough to read
+ * If submission navigates to a new page, provide a descriptive page title and
+ heading there
+ * Do not announce every keystroke, character-count change, or validation
+ state unless necessary at that moment
**Silent async failures are Serious** — screen reader users have no indication
the action completed or failed.
---
## Serious: 3.3.4 Error Prevention — Legal, Financial, Data
- For forms that result in legal commitments, financial transactions, or permanent
- data changes, users must be able to do at least one of:
+ For forms that create legal commitments, financial transactions, test
+ responses, or changes to user-controlled data, provide at least one:
- * **Check** — review their input before final submission
- * **Correct** — reverse, cancel, or modify the submission afterwards
- * **Confirm** — an explicit confirmation step before the action is finalised
+ * **Reversible** — the submission can be undone
+ * **Checked** — data is checked for errors and the user can correct them
+ * **Confirmed** — the user can review, confirm, and correct before final submission
```html
- <!-- Confirmation step pattern -->
<h2>Review your order</h2>
<dl>
- <dt>Item</dt><dd>Annual plan</dd>
+ <dt>Plan</dt><dd>Annual plan</dd>
<dt>Amount</dt><dd>$120.00</dd>
</dl>
- <button type="submit">Confirm and pay</button>
<a href="/cart">Edit order</a>
+ <button type="submit">Confirm and pay $120.00</button>
```
- **Absent error prevention on financial/legal forms is Serious.** It may become
- **Critical** in regulated contexts (financial services, legal agreements, medical
- data) where the error cannot be undone.
+ **Absent error prevention on financial/legal forms is Serious**; it may become
+ **Critical** in regulated contexts (financial services, legal agreements,
+ medical data) where the error cannot be undone.
---
+ ## Serious: Redundant Entry (WCAG 3.3.7)
+
+ Do not clear valid information after a validation error. Within the same
+ multi-step process, information previously entered or supplied must be
+ auto-populated or available for selection unless re-entry is essential,
+ required for security, or no longer valid. Examples: "Billing address is the
+ same as shipping address" option; carry an account identifier into later
+ steps; preserve a search query on the results page. Protect personal
+ information while preserving it — 3.3.7 does not require storing information
+ between separate sessions.
+
+ ---
+
## Moderate: Instructions
- Provide concise instructions before complex input groups.
- This is **Moderate** — most users can infer requirements, but users with cognitive
- disabilities benefit from upfront guidance.
+ Provide concise instructions before complex input groups, associated via
+ `aria-describedby`. This is **Moderate** — most users can infer requirements,
+ but users with cognitive disabilities benefit from upfront guidance.
* Place instructions before the input, not after
- * Provide format examples for unusual inputs: `Date: DD/MM/YYYY`
- * Associate instructions with the field via `aria-describedby`
+ * State format, units, accepted file types, limits, and case sensitivity when relevant
+ * Do not hide essential instructions in placeholder text or a tooltip
+ * Do not require users to infer a format from an example alone
+ * Ensure instructions remain available while entering and reviewing information
---
- ## Moderate: Session Timeout Warning
+ ## Moderate: Time Limits and Session Timeout
- If the form session can expire, users **must** be warned before timeout occurs
- (WCAG 2.2.1 Timing Adjustable). Give at least 20 seconds to extend the session,
- and the warning itself must be accessible to AT.
+ Avoid time limits unless essential (WCAG 2.2.1). For an inactivity timeout
+ using warn-and-extend:
+ * Warn before expiry; give at least 20 seconds to extend via a simple action;
+ permit extension at least ten times
+ * Explain whether data will be lost; announce and display the warning
+ * Move focus into a correctly implemented modal dialog; return focus to the
+ previous location after it closes
+
```html
- <!-- Timeout warning — inject when ~2 minutes remain -->
- <div role="alertdialog" aria-modal="true"
- aria-labelledby="timeout-title" tabindex="-1" id="timeout-dialog">
+ <dialog id="timeout-dialog" aria-labelledby="timeout-title">
<h2 id="timeout-title">Your session will expire in 2 minutes</h2>
- <p>You will lose any unsaved form data.</p>
+ <p>Your unsaved information will be lost.</p>
<button type="button" id="extend-session">Stay signed in</button>
- </div>
+ <button type="button" id="sign-out">Sign out</button>
+ </dialog>
```
- Move focus to the warning dialog. On "Stay signed in", reset the timer and
- return focus to where the user was.
-
- Session timeout is **Moderate** for informational forms; **Critical** for
- transactional or legal submissions where data loss cannot be recovered.
+ Open a native `<dialog>` with `showModal()` where supported — `aria-modal`
+ alone does not create modal behaviour, manage focus, make the rest of the page
+ inert, or provide Escape handling. Session timeout is **Moderate** for
+ informational forms; **Critical** for transactional or legal submissions where
+ data loss cannot be recovered.
---
## Moderate: Validation Timing
* Validate on submit at minimum
* Inline validation on blur (field exit) is acceptable when clearly scoped to
the field just left — do not validate fields the user has not yet visited
* Avoid disruptive real-time validation while the user is actively typing
---
+ ## Moderate: Visual Layout and Interaction
+
+ * Meet text and non-text contrast for controls, borders, instructions,
+ placeholders, errors, focus indicators, and disabled states
+ * Do not use colour alone for required, invalid, selected, success, or warning states
+ * Provide visible focus indicators; reflow without horizontal scrolling at 320px
+ * Support text-spacing overrides without clipping/overlap
+ * Provide adequate target sizes and spacing for touch/pointer input
+ * Do not obscure focused fields with sticky headers, virtual keyboards, or
+ validation overlays
+ * Do not change context merely because a control receives focus or a value
+ changes, unless users were advised of that behaviour
+
+ ---
+
+ ## Testing Expectations
+
+ * **Keyboard:** complete and submit using only the keyboard; operate every
+ custom widget per its documented pattern; confirm focus order is logical;
+ trigger errors and follow every error-summary link; confirm modal warnings
+ contain focus and return it; test copy/paste/undo/redo/password-manager entry
+ * **Screen readers / speech input:** confirm each control's name, role, state,
+ value, hint, and error are understandable; required/invalid states are
+ announced; grouped controls include their shared question; status updates
+ announced once and remain visible; visible labels included in accessible names
+ * **Magnification/reflow/touch:** 200%/400% zoom; 320px viewport; text-spacing
+ overrides; touch targets and on-screen keyboard; browser autofill
+ * **Validation/recovery:** submit empty and partially/fully invalid forms;
+ correct errors out of summary order; confirm valid values are preserved;
+ test server-side errors, network errors, expired sessions, duplicate submissions
+ * **Authentication:** complete login with autofill/password manager; paste a
+ complete password and one-time code; test every MFA/recovery path; confirm
+ previously entered info is preserved in later steps
+
+ **Automated checks** can catch missing names, invalid ARIA, contrast failures,
+ and some state problems, but cannot determine whether instructions are
+ understandable, errors are useful, or the complete process is usable. Include
+ HTML validation, accessibility-tree/accessible-name assertions, axe-core,
+ keyboard interaction tests for custom widgets, focus-placement tests, and
+ paste tests for authentication fields. Test server-rendered errors as well as
+ client-side validation.
+
+ ---
+
## Definition of Done Checklist
* [ ] All controls have programmatically associated `<label>`
* [ ] No placeholder-only labels
* [ ] `required` used on native inputs; `aria-required` not added redundantly
* [ ] Required state communicated in text (not colour alone)
* [ ] `<fieldset>`/`<legend>` used for grouped controls
* [ ] Appropriate `autocomplete` values on personal-data fields
* [ ] Paste and standard keyboard actions not blocked
* [ ] `<select multiple>` replaced with checkboxes where feasible
- * [ ] `type="text" inputmode="numeric"` used in preference to `type="number"`
- for quantities/codes (unless stepper is genuinely needed)
+ * [ ] `type="number"` used only where math/stepper semantics apply
* [ ] Date inputs tested with target AT matrix
* [ ] `<datalist>` usage tested with AT; constrained inputs use APG Combobox pattern
* [ ] `aria-invalid` set on invalid fields; removed when corrected
* [ ] Error messages are specific, actionable, and associated via `aria-describedby`
* [ ] Error summary present and receives focus on failed submit
* [ ] Async success/failure announced to screen readers
* [ ] Legal/financial/data-change forms have check/correct/confirm step (3.3.4)
- * [ ] Session timeout warned before expiry with accessible dialog
+ * [ ] Multi-step forms avoid redundant entry (3.3.7)
+ * [ ] Authentication supports paste, password managers, and avoids cognitive puzzles (3.3.8)
+ * [ ] Session timeout warned before expiry with accessible native `<dialog>`
* [ ] No colour-only indication of any state
* [ ] Keyboard and screen reader walkthrough passes
---
## Key WCAG Criteria
* 1.3.1 Info and Relationships (A)
* 1.3.5 Identify Input Purpose (AA) — **Serious if absent on personal-data fields**
+ * 2.2.1 Timing Adjustable (A)
* 3.3.1 Error Identification (A) — **Critical if absent**
* 3.3.2 Labels or Instructions (A) — **Critical if absent**
* 3.3.3 Error Suggestion (AA)
* 3.3.4 Error Prevention — legal, financial, data (AA) — **Serious if absent**
+ * 3.3.7 Redundant Entry (A)
+ * 3.3.8 Accessible Authentication Minimum (AA)
---
## References
* [Full best practices guide](https://github.com/mgifford/ACCESSIBILITY.md/blob/main/examples/FORMS_ACCESSIBILITY_BEST_PRACTICES.md)
+ * [WAI Forms Tutorial](https://www.w3.org/WAI/tutorials/forms/)
* [WAI-ARIA APG — Combobox pattern](https://www.w3.org/WAI/ARIA/apg/patterns/combobox/)
- * [WAI-ARIA APG — Date Picker pattern](https://www.w3.org/WAI/ARIA/apg/patterns/dialog-modal/examples/datepicker-dialog/)
+ * [WAI-ARIA APG — Date Picker Dialog example](https://www.w3.org/WAI/ARIA/apg/patterns/dialog-modal/examples/datepicker-dialog/)
* [WCAG 1.3.5 Input Purposes — full autocomplete token list](https://www.w3.org/TR/WCAG21/#input-purposes)
- * [WCAG 2.2 Understanding 3.3.1 Error Identification](https://www.w3.org/WAI/WCAG22/Understanding/error-identification.html)
- * [WCAG 2.2 Understanding 3.3.4 Error Prevention](https://www.w3.org/WAI/WCAG22/Understanding/error-prevention-legal-financial-data.html)
- * [WCAG 2.2 Understanding 2.2.1 Timing Adjustable](https://www.w3.org/WAI/WCAG22/Understanding/timing-adjustable.html)
+ * [Understanding 3.3.4 Error Prevention](https://www.w3.org/WAI/WCAG22/Understanding/error-prevention-legal-financial-data.html)
+ * [Understanding 3.3.7 Redundant Entry](https://www.w3.org/WAI/WCAG22/Understanding/redundant-entry.html)
+ * [Understanding 3.3.8 Accessible Authentication](https://www.w3.org/WAI/WCAG22/Understanding/accessible-authentication-minimum.html)
> **Standards horizon:** These rules target WCAG 2.2 AA. WCAG 3.0 is in
> development; its proposed APCA contrast model may affect error-state colour
> choices but core labelling, grouping, and error requirements are expected to
> carry forward.
> Monitor: <https://www.w3.org/TR/wcag-3.0/>