forms

forms — one toolkit, dirty-gated Save, shared error mapping

This skill governs where the form layer fits in a Next.js 16 App Router app: which hook, which rendering layer, which red flags. It does not teach @tanstack/react-form (or react-hook-form) itself — for the library's own API surface defer to the official docs.

The codebase exposes one shared toolkit at lib/forms/ regardless of which underlying library the project picked. Hook names, rendering layer, and error contract are identical across the two — consumer code looks the same. The choice between TanStack Form (default) and react-hook-form is made once at project scaffold time, written to meta.json#stack.forms, and never mixed.

When this skill applies

• The user asks for a "form", "edit panel", "create dialog", "settings page", "save button".
• Orchestrator (dev-flow) routes here after scaffolding a route that needs persistence.
• The user reaches for useState to hold field values, raw useForm (bypassing the toolkit), hand-rolled dirty tracking, inline toast.success/toast.error on submit, or <form onSubmit> that calls fetch/services directly.
• The user asks to audit a Next.js codebase against the form rules.

Contract

This skill follows the dev-flow contract — see references/contracts.md (vendored copy). Key facts:

• Reads meta.json#stack.framework, stack.nextjs_version, stack.forms, stack.ui. For framework = "monorepo", reads the equivalent keys under stack.monorepo.web. stack.forms picks the state library (selection logic); stack.ui picks the rendering primitives (branching table) — the two are independent and both must be resolved before writing code.
• Refuses to apply if any of these is true:
  • stack.framework ∉ {"next", "monorepo"} — non-Next.js targets are out of scope (RN forms use a different ecosystem; refer the user to the React Native form patterns).
  • stack.nextjs_version != "16" — Next.js 15 and earlier have different searchParams, no use(promise) baseline, no revalidatePath/revalidateTag defaults. Refuse to apply rather than silently guess.
  • The project uses Pages Router (pages/ directory exists). App Router only.
  • The project standardizes on a form library other than tanstack-form or react-hook-form (Formik, plain controlled state, etc.). Refuse to mix.
• Appends a history entry to meta.json for every scaffold or edit.
• Does not bump phase — forms live inside the implementation phase and don't gate progression.