enhance-web-forms

enhance-web-forms — Production-Quality Forms

Degree of freedom: MIXED. Schema and state-machine judgment [HIGH freedom]; a11y probes and playwright walks [LOW freedom — run exactly].

Forms are where users hand you their data and where apps most often feel broken: unlabeled fields, validation that fires on every keystroke, errors screen readers never announce, a submit button that does nothing visible for three seconds, and no recovery when the request fails. This skill fixes all of that on real forms in the repo.

A form is done when it is accessible, validated on both sides, gives feedback for every state, and recovers from failure. Compile-clean is not done.

Before any browser interaction, read protocol-browser-anti-stall and apply it.

How to reason

1. Inventory — forms, library, schema; bow out if none
2. Structure — programmatic labels, types, error association
3. Parity — one schema both sides; blur + submit, not every keystroke
4. States — submitting / success / error / unsaved; recover on failure

Worked example

Inventory: signup uses raw <form> + inline if (!email); API validates with zod. Structure: htmlFor labels; autocomplete="email"; aria-invalid + summary. Parity: share the zod schema; validate on blur/submit; map "email taken" to the field. States: submit disables + aria-busy; values preserved on 500; dirty-nav warn.

Self-critique before reporting

• Labeled — placeholder is never the only name
• Both sides — client and server rules match; error shapes map to fields
• Walked — empty, invalid, valid, and server-error paths in the browser
• Right owner — page/flow UX beyond the form → enhance-web-ux; WCAG sweep → audit-accessibility

---

Phase 0 — Detect the stack and inventory forms [HIGH freedom]

cat package.json | grep -iE "react-hook-form|formik|@tanstack/react-form|final-form|zod|yup|valibot|superstruct"
rg -n "<form|onSubmit|useForm|handleSubmit" -g "*.{tsx,jsx,vue,svelte}" -l