forms
Building Fields, Validation, and Submission
The default posture: one column, a persistent label above every field, a real <form> element, validation on blur and then on change, and the error rendered directly beneath the field that caused it. Forms are where users do real work and they notice every rough edge — the label that doesn't focus its input, the page that zooms on iOS, the submit that fires twice, the Enter key that does nothing. None of these are hard; they are only easy to forget. Start from the semantics the platform gives you and add as little as the design requires. This skill owns construction — layout, timing, autofill tokens, submit handling. a11y owns the contract the finished form must honour: tab order, focus management, :focus-visible, ARIA, and live-region announcements. When a rule concerns what the assistive stack hears rather than how the field is built, it belongs there, not here.
Work inside the form stack the project already has. Look for React Hook Form, Formik, TanStack Form, native FormData with a server action, or a hand-rolled useState per field; look for a schema layer (Zod, Valibot, Yup) and an existing <Field> / <FormItem> wrapper. Wire your validation into the resolver that is already there. A second validation library — or client rules that silently disagree with the server schema — produces fields that pass locally and fail on submit, which is the worst error state a form can have.
Quick Reference
| Topic | Reference | Open it when |
|---|---|---|
Per-field-type recipes: input type, inputmode, autocomplete token, validation timing, and error string for email, password, OTP, phone, number, date, search, select, file, textarea, address |
references/field-recipes.md |
Open it whenever you are building a specific field type and need its exact attribute set, rather than deciding a general rule. |
Core Principles
-
The label is persistent, sits above the field, and focuses it. A placeholder is not a label: it disappears the instant typing starts, exactly when the reminder is needed, and it leaves autofill nothing stable to bind to. Wire it with
<label for="email">+id="email", or wrap the input. Exception: a lone search box with a visible icon may carry a visually hidden label — hidden, never absent. -
Validate on blur, then on change once an error is showing. Flagging a field while the user is mid-way through their first attempt shouts "invalid email" after one character. Once the error exists, switch that field to validating on every change so it clears the moment it is fixed: reward early, punish late. Exception: purely additive live feedback — a password strength meter, a character counter — may update on change from the start because it never accuses.