Forms And Validation

Instructions

When to Use

• Use for accessible forms with zod + Server Actions or client submit.
• Prefer api-handbook for pure JSON APIs without forms.
• Prefer accessibility-audit for a full WCAG pass after the form ships.

Build or audit forms with zod and accessible markup.

Decision: Server Action vs client submit vs API

1. Choose pattern: Server Action with useActionState (React 19) or legacy useFormState naming in older docs - match repo and installed react types.
2. Single zod schema (or layered: base + refine); map flatten().fieldErrors to fields by name.
3. Labels, htmlFor, aria-invalid, aria-describedby for errors; no placeholder-only labels.
4. Disable double-submit; optimistic UI only when the user asks; show pending state.
5. File uploads: size limits and accept list in UI copy; validate again on the server.
6. Auth: Server Actions that mutate must re-check session/RBAC (auth-handbook); never trust hidden role fields.
7. CSRF / cookies: same-site cookies + Server Actions are the default story; document exceptions.

Outcomes

• Schema snippet + error wiring plan + a11y checklist + pattern choice.

Output Rules

Show field error mapping table (field → zod path). Prefer small diffs.

Scope and boundaries

• In scope: one multi-field form or wizard step.
• Out of scope: payment PCI scope (payments-handbook), captcha vendor selection unless the user names one.

Safety

• repo-files: edit form components only; no .env values.

Troubleshooting

• Next 15 form types: align with current react types from the lockfile.
• Hydration on date pickers: prefer server default string + client parse in an island.
• Empty fieldErrors: ensure zod path names match name= attributes.
• Action succeeds but UI stale: add revalidatePath / tags (server-caching-handbook).

Related skills

• api-handbook - Route Handler APIs behind forms
• client-data-fetching - client mutation patterns
• accessibility-audit - accessible error messaging
• auth-handbook - authorize mutations

GitHub: https://github.com/bh611627/skillcodex/tree/main/skills/forms-and-validation/SKILL.md
npm: https://www.npmjs.com/package/@skillcodex/skills