lukedj78/dev-flow / forms
forms
VerifiedBuild or edit any form in a Next.js 16 App Router app through one shared toolkit in `lib/forms/`, with dirty + valid Save gating — on TanStack Form + Zod (default) or react-hook-form (auto-detected). Use when the user says "form", "edit panel", "create dialog", "settings page", "save button", "dirty state", or reaches for `useState` to hold field values, raw `useForm`, hand-rolled dirty tracking, or inline `toast.success/error` on submit. Also owns multi-step question flows — "questionnaire", "questionario", "survey", "sondaggio", "quiz", "poll", "onboarding flow", "intake form", "wizard", "step-by-step questions", "one question at a time" — which route to the shadcn `<Questionnaire />`. Refuses outside Next.js 16 web. Not for: React Native forms, search boxes that only filter, reads that populate a form (`data-fetching`), or state not bound to form fields (`state-discipline`).
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
useStateto hold field values, rawuseForm(bypassing the toolkit), hand-rolled dirty tracking, inlinetoast.success/toast.erroron submit, or<form onSubmit>that callsfetch/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. Forframework = "monorepo", reads the equivalent keys understack.monorepo.web.stack.formspicks the state library (selection logic);stack.uipicks 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 differentsearchParams, nouse(promise)baseline, norevalidatePath/revalidateTagdefaults. 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-formorreact-hook-form(Formik, plain controlled state, etc.). Refuse to mix.
- Appends a
historyentry tometa.jsonfor every scaffold or edit. - Does not bump
phase— forms live inside the implementation phase and don't gate progression.
The Rule
Every form goes through one shared toolkit at lib/forms/. Every form has an explicit Save button, disabled when there is nothing to save. No auto-save, no save-on-blur, no debounce. Never useState for field values. Never raw useForm (TanStack or RHF) outside the toolkit. Never inline toast.success/toast.error from a form component.
🔴 The Save button is gated on isDirty, not on isValid — and the reason is accessibility, not
taste. See §The Save button is not a validity light below before changing it back.
A "form" is any UI with <input> / <textarea> / <select> / <Checkbox> / <Switch> / <RadioGroup> whose value persists to a backend (POST / PATCH / PUT). Display-only fields, search boxes that only filter, and fire-and-forget toggles that take no field state are not forms.
Two patterns, one toolkit
| Form kind | Hook | Submit trigger | After success |
|---|---|---|---|
| Edit (panel, settings, inline editor) | useEditForm | <Button type="submit">Save</Button> — disabled unless canSave (isDirty && !isSubmitting) | Form stays open. Hook resets baseline to the saved value so isDirty returns to false. |
| Create (dialog, new-record form) | useCreateForm | <Button type="submit">Create</Button> — disabled only while isSubmitting | onSuccess(result) callback fires (close dialog, route, etc.). |
Both share the <FormProvider> + <FormField> rendering layer, the same Zod schema as validator, the same mapFormError error router, and the same <FormActions> button row. The differences: edit gates on isDirty and resets baseline after success; create closes via onSuccess.
The Save button is not a validity light
Start from what goes wrong. Someone opens an edit panel with a screen reader, changes a field, leaves one required field empty, and tabs to Save. Save is disabled. Nothing says why — a disabled button has no error, no description, no reason. They cannot submit, and nothing has told them which field is wrong. The form is a dead end, and no amount of styling the invalid field fixes it, because they never see the styling.
What made it a dead end was the gate. Native HTML announces form errors on the failed submit: the browser blocks the submission, moves focus to the first invalid control, and the screen reader reads that control's error. Disabling Save because the form is invalid deletes that event. The one moment the platform reserved for telling the user what is wrong never happens.
So the gate changed, and the rule is now:
| the form is | Save is | because |
|---|---|---|
unchanged (!isDirty) | disabled | there is genuinely nothing to save, and saying so is honest |
| changed and invalid | enabled | pressing it is how the user finds out what is wrong |
| submitting | disabled | one in-flight save at a time |
state.canSave is isDirty && !isSubmitting. There is no canSubmit any more — the old name
meant isValid && isDirty && !isSubmitting, and a project still reading it gets undefined, which
disables the button permanently. That is deliberate: it breaks loudly in the one place a stale
toolkit copy would otherwise go quiet.
The four things that make a form's errors reach everyone
aria-invalid alone is not an accessible form. All four, and the toolkit owns three of them:
aria-invalidon the control, from the moment the error becomes visible — and explicitly"false"before that, never unset. Firefox and Safari expose an emptyrequiredfield as invalid from page load, so an unset attribute still produces a premature "invalid entry" announcement.aria-describedbypointing at the error message, only while the field is invalid. Text thataria-describedbyreferences is announced even when it is visually hidden, so a permanent reference reads the error out before the user has touched the field.<FormField>mounts<FieldError>on demand and hands the id down, so the reference appears and disappears with it.- One polite live region for the page, whose text changes. ⚠️ shadcn's
<FieldError>rendersrole="alert"and returnsnullwhen there is no error, so today the error node is inserted rather than changed — and a live region that is shown rather than changed is not announced reliably. The region lives in the app shell, not in<FormProvider>: two forms on one page would otherwise give two regions. - Focus to the first invalid control on a failed submit. This is what the new gate buys back.
handleSubmitdoes it; on a long form, focus an error summary instead — a heading followed by a link per invalid field.
The toast is not the live region. mapFormError keeps the toast, and it reports the outcome of
a submit — a rejected save, a server error. Field-level errors raised on blur go to the polite
region. Routing blur errors to the toaster is how a half-filled form produces a stack of toasts.
Sourced from GoogleChrome/modern-web-guidance,
guides/accessibility/accessible-error-announcement.md and
guides/forms/validate-input-after-interaction.md (read 2026-11-18, CC-BY 4.0).
When the error appears
Our field state exposes touched, which is blur alone. The platform's :user-invalid requires
that the user modified the field and left it, or attempted a submit. The difference is visible:
tab straight through an empty required field and touched shows an error, :user-invalid does not.
<FormField> therefore derives invalid as dirty && touched && !isValid, or
submitAttempted && !isValid — the same two conditions the pseudo-class uses. Do not reach for
meta.isTouched directly in a component; the wrapper owns this.
Library branching — stack.forms
The two libraries (TanStack Form + Zod, react-hook-form + Zod) are equally supported by this skill and produce identical consumer code. Only the toolkit implementation differs — neither is a second-class citizen.
meta.json#stack.forms | Hooks | Schema validator | Library docs |
|---|---|---|---|
"tanstack-form" (default when nothing else indicates a preference) | useEditForm + useCreateForm wrap useForm from @tanstack/react-form | Pass schema to validators: { onChange, onBlur } | https://tanstack.com/form/latest |
"react-hook-form" (fully supported; auto-detected when already present) | Same hook names; wrap useForm from react-hook-form with zodResolver | zodResolver(schema) from @hookform/resolvers/zod | https://react-hook-form.com |
The consumer of useEditForm / useCreateForm never imports the underlying library. They get a typed hook with state.isDirty, state.isValid, state.isSubmitting, state.canSave, handleSubmit(), reset(value?), Subscribe(...), and a <form.Field> (TanStack) or <form.Field> (RHF wrapper) equivalent for raw escape-hatch usage.
Selection logic — decide once, up front
Every time this skill runs, resolve stack.forms before touching any form code, in this order:
meta.json#stack.formsis already set ("tanstack-form"or"react-hook-form") → use it. Never override silently, even if the codebase looks mixed — flag drift instead (see violation A in Audit mode).- Unset → auto-detect from the project. Check, in order:
react-hook-form(or@hookform/resolvers) present inpackage.json#dependencies/devDependencies, or existingimport { useForm } from "react-hook-form"/<Controller>usage found in the codebase → the project has already standardized on react-hook-form. Setstack.forms = "react-hook-form"and proceed.@tanstack/react-formpresent inpackage.json, or existingimport { useForm } from "@tanstack/react-form"usage found → the project has already standardized on TanStack Form. Setstack.forms = "tanstack-form"and proceed.
- Ambiguous (both detected) or absent (neither detected, greenfield project) → ask the user once. State the default (
"tanstack-form") and name the alternative; write whichever answer tometa.json#stack.formsbefore scaffolding anything. Do not guess silently in either direction — greenfield with no stated preference is the only case where defaulting without asking is acceptable, and even then, say out loud which one you're about to use.
Write the resolved value to meta.json#stack.forms immediately (Step 1 of the Workflow) so every subsequent run of this skill — and every other dev-flow skill — reads the same answer.
Rendering primitives — stack.ui
stack.forms picks the state-management library; stack.ui (a separate, orthogonal meta.json key) picks what <FormField> and <FormActions> actually render. All code samples in this skill assume stack.ui = "shadcn" (Field / FieldLabel / FieldError / Button) — that assumption must be made explicit, not silently carried over to a project that picked something else.
meta.json#stack.ui | <FormField> renders | <FormActions> renders | Notes |
|---|---|---|---|
"shadcn" / "base-ui" (default; every example above) | shadcn Field + FieldLabel + FieldError (see references/toolkit-tanstack.md / references/toolkit-rhf.md) | shadcn Button | "base-ui" here still means shadcn's component set on the Base UI primitive layer — the Field API is the same. |
"mui" | MUI TextField (or FormControl + InputLabel + FormHelperText for non-text inputs) wired to the same field API the hook exposes (value, setValue, onBlur, touched, isValid, errors, invalid, describedBy) | MUI Button / LoadingButton, gated on the same canSave boolean | The dirty + valid gating logic lives in the hook (useEditForm/useCreateForm), not in <FormField> — swapping shadcn primitives for MUI ones changes zero business logic. Example: <TextField error={touched && !isValid} helperText={touched && errors[0]} label={label} value={value} onChange={(e) => setValue(e.target.value)} onBlur={onBlur} />. |
| anything else (Chakra, Radix vanilla, …) | Not covered by this skill's reference implementations | — | Refuse to silently invent a mapping. Either ask the user which primitives to wire (then treat the result as a project-specific FormField/FormActions implementation, still behind the same hook contract), or use the raw escape hatch until the project has one. |
When scaffolding (scripts/scaffold_lib_forms.py) or hand-writing lib/forms/FormField.tsx for a stack.ui = "mui" project, keep the render-prop shape identical to the shadcn version — only the JSX inside changes.
Golden rule 3 — primitives first (references/contracts.md §Golden rules). Before writing a component, search components/ui/ (shadcn monorepo: packages/ui/src/components/) for a primitive that covers the pattern; if it is there, use it, and if two together cover it, compose them. Never hand-roll one the library ships, never import a second component library, never change a primitive beyond its cva variants and tokens. A truly new primitive needs a recorded exception with its reason (ADR or meta.json#stack_config.primitive_exceptions). For forms specifically: every control is the library's (Field, Input, Textarea, Select, Combobox, Checkbox, Switch, RadioGroup, the date picker composition) — lib/forms/ wraps them for state, it never re-implements one.
Multi-step question flows — <Questionnaire />
shadcn ships a first-party component for the one shape this skill's two patterns don't cover: a sequence of questions asked one at a time (onboarding, intake, quiz, survey). Don't hand-roll it, and don't force it into the edit/create form patterns above — it has its own state machine.
pnpm dlx shadcn@latest add questionnaire
Available for Base UI, React Aria and Radix (the unstyled behaviour lives in @shadcn/react), so it
follows stack.ui_base without extra work.
Questionnaire ← root
├── QuestionnaireProgress
├── QuestionnaireItem ← renders a <fieldset>
│ ├── QuestionnaireTitle ← becomes its <legend>
│ ├── QuestionnaireDescription
│ ├── QuestionnaireChoices
│ │ ├── QuestionnaireChoice
│ │ └── QuestionnaireInput ← freeform answer
│ └── QuestionnaireError
└── QuestionnaireActions
├── QuestionnairePrevious · QuestionnaireSkip · QuestionnaireNext · QuestionnaireSubmit
| You want | You do |
|---|---|
| more than one answer | multiple on the QuestionnaireItem |
| a freeform "other" | add a QuestionnaireInput beside the choices (input: { label, placeholder }) |
| a skippable question | required: false on the item and render <QuestionnaireSkip /> |
| keyboard shortcuts | shortcuts on the item (letters or numbers) |
| conditional questions | the host app disables items that don't apply to earlier answers — the component doesn't branch for you |
⚠️ It serialises natively, which is a real tension with The Rule. Answers come back as
FormData — answers.get("field") for single, answers.getAll("field") for multiple — so a standalone
questionnaire needs no form library at all. That is a legitimate exception, not a violation: the rule
exists to stop hand-rolled useState form state, and here the state machine is the component's. Two
consequences to keep straight:
- Standalone flow (onboarding, survey) → use it as-is, read
FormDataon submit, validate with the same Zod schema you'd have used (see Schemas). Don't wrap it inuseCreateFormfor show. - A questionnaire step inside a larger toolkit form → the
FormDatadoes not flow into the hook by itself. Read it on the step's submit and push the values through the hook's field API, exactly as thestack.ui = "mui"row does for primitives. Never keep two sources of truth for the same answer.
It is also the surface a model asks questions through. In a chat, an AI SDK tool declared with an
outputSchema and no execute parks its call on the client; the UI renders a <Questionnaire />
from the tool input, and the human's answer is returned as the tool output via
addToolOutput({ tool, toolCallId, output }). That is how shadcn's own
chatbot-template does clarifying questions — same
component, same accessibility rules as below, driven by a model instead of a route. Wiring in
design-md-to-app/references/chat-and-typeset.md §Ask-the-user HITL; don't reach for it in an
eve-backed app, where questions arrive on eve's event stream instead.
Accessibility is mostly free, with one exception. The fieldset/legend structure and native
radio/checkbox behaviour come from the component; failed validation moves focus to an answer control. But
QuestionnaireInput has no implicit name — give it a visible label, aria-label, or
aria-labelledby. Ship it without one and shadscan's forms-have-labels will find it, correctly.
Edit form pattern (manual save, dirty-gated)
The save callback calls a Server Action from lib/actions/<entity>.actions.ts — never the service layer directly. Per the data-fetching skill's contract, lib/services/ is server-only code with no "use server" directive; a Client Component cannot import it. The Server Action re-validates with the same Zod schema, calls the service, and revalidates:
// lib/actions/projects.actions.ts
"use server";
import { revalidatePath } from "next/cache";
import { projectsService } from "@/lib/services/projects.service";
import { ProjectSchema, type Project } from "@/lib/types/project";
export async function updateProjectAction(id: string, value: Project) {
const parsed = ProjectSchema.parse(value);
const saved = await projectsService.update(id, parsed);
revalidatePath(`/projects/${id}`);
return saved;
}
"use client";
import { Button } from "@/components/ui/button";
import { Input } from "@/components/ui/input";
import { Textarea } from "@/components/ui/textarea";
import {
FormActions,
FormField,
FormProvider,
useEditForm,
} from "@/lib/forms";
import { updateProjectAction } from "@/lib/actions/projects.actions";
import { type Project, ProjectSchema } from "@/lib/types/project";
export function ProjectEditPanel({ project }: { project: Project }) {
const form = useEditForm<Project>({
schema: ProjectSchema,
defaultValues: project,
save: (value) => updateProjectAction(project.id, value),
});
return (
<FormProvider form={form}>
<form
onSubmit={(e) => {
e.preventDefault();
void form.handleSubmit();
}}
>
<FormField name="name" label="Name">
{(field) => (
<Input
id={String(field.name)}
value={String(field.value ?? "")}
onChange={(e) => field.setValue(e.target.value)}
onBlur={field.onBlur}
aria-invalid={field.invalid}
aria-describedby={field.describedBy}
/>
)}
</FormField>
<FormField name="description" label="Description">
{(field) => (
<Textarea
id={String(field.name)}
value={String(field.value ?? "")}
onChange={(e) => field.setValue(e.target.value)}
onBlur={field.onBlur}
aria-invalid={field.invalid}
aria-describedby={field.describedBy}
/>
)}
</FormField>
<FormActions
submitLabel="Save"
submittingLabel="Saving…"
resetLabel="Reset"
/>
</form>
</FormProvider>
);
}
What the hook owns (never reimplement in components):
- Dirty tracking — drives
state.isDirtyfrom a deep-equal compare of current values vs the current baseline (initialdefaultValueson mount, then the most-recently-saved value). - Submit gating — exposes
state.canSave = isDirty && !isSubmitting.<FormActions>reads it viaform.Subscribe. NotisValid: see §The Save button is not a validity light. - Focus on a failed submit — when validation fails,
handleSubmitfinds the first control the form owns that is[aria-invalid="true"]and focuses it, so its error is announced. This is the half the old gate was deleting. - Announcing a field error — writes the first new error message into the page's polite live region (
announce()fromlib/a11y/announcer.tsx, scaffolded bydesign-md-to-app). One region per page, text changed rather than inserted. - Baseline reset on success — after the
savecallback resolves, callsform.reset(savedValue)so the new clean state is the saved value. Editing back to the just-saved value should leaveisDirty === false. - AbortController on submit — if the user re-submits while a save is in flight, the hook ignores the earlier call's resolution once a newer one starts. Note:
save/submitis passed{ signal }for parity with a raw service call, but a Server Action cannot accept anAbortSignalas an argument — it isn't a serializable value across the server boundary and passing it will throw. Whensavewraps a Server Action (the normal case), ignore the second parameter; the hook's own bookkeeping still guards against acting on a stale response. - Error mapping — thrown errors flow through
mapFormError. Thesavecallback must throw on failure — never catch. - Optional success/error toast — owned by
mapFormError; not by form components.
What the consumer owns:
- The
<form onSubmit>wrapper that callsform.handleSubmit(). - Spreading
aria-invalid={field.invalid}andaria-describedby={field.describedBy}onto the control. Both values come from<FormField>— compute neither in the component. - Calling the entity's Server Action from
save/submit— never the service layer, which is server-only (seedata-fetchingskill).
Create form pattern
Same rule: submit calls a Server Action, not the service directly.
// lib/actions/projects.actions.ts
"use server";
import { revalidatePath } from "next/cache";
import { projectsService } from "@/lib/services/projects.service";
import {
type ProjectCreateInput,
ProjectCreateInputSchema,
} from "@/lib/types/project";
export async function createProjectAction(value: ProjectCreateInput) {
const parsed = ProjectCreateInputSchema.parse(value);
const created = await projectsService.create(parsed);
revalidatePath("/projects");
return created;
}
"use client";
import { Input } from "@/components/ui/input";
import {
FormActions,
FormField,
FormProvider,
useCreateForm,
} from "@/lib/forms";
import { createProjectAction } from "@/lib/actions/projects.actions";
import {
type ProjectCreateInput,
ProjectCreateInputSchema,
} from "@/lib/types/project";
export function CreateProjectForm({
onCreated,
}: {
onCreated: (id: string) => void;
}) {
const form = useCreateForm<ProjectCreateInput, { id: string }>({
schema: ProjectCreateInputSchema,
defaultValues: { name: "", description: "" },
submit: (value) => createProjectAction(value),
onSuccess: (created) => onCreated(created.id),
});
return (
<FormProvider form={form}>
<form onSubmit={(e) => { e.preventDefault(); void form.handleSubmit(); }}>
<FormField name="name" label="Name">
{(field) => (
<Input
value={String(field.value ?? "")}
onChange={(e) => field.setValue(e.target.value)}
onBlur={field.onBlur}
/>
)}
</FormField>
<FormActions submitLabel="Create" submittingLabel="Creating…" />
</form>
</FormProvider>
);
}
Create forms disable the submit button only while isSubmitting — dirty tracking is irrelevant for new records, and validity is not a gate here either, for the same reason as everywhere else: on an empty create form, pressing Create is how the user learns what is required. Some teams still gate on isDirty to stop a submit of an entirely-default form; that's a per-project preference codified once in useCreateForm, never per-component, and it costs the same announcement — if you adopt it, the empty-form case needs its own path.
FormActions
The shared submit/reset button row. Reads form state reactively via form.Subscribe (TanStack) or useFormState-equivalent (RHF) so the rest of the form doesn't re-render when only isDirty/isSubmitting changes:
<FormActions submitLabel="Save" submittingLabel="Saving…" resetLabel="Reset" />
For custom layout (Cancel between Reset and Save, dialog-footer docking, etc.) drop <FormActions> and inline the equivalent subscribe block. The skill ships the subscribe pattern in references/form-actions.md.
Schemas
Schemas live in lib/types/<entity>.ts and are the single source of truth for form and service layer. Use Zod v4:
import * as z from "zod";
export const ProjectSchema = z.object({
id: z.string().uuid(),
name: z.string().trim().min(1).max(120),
description: z.string().trim().max(5000).nullable(),
});
export type Project = z.infer<typeof ProjectSchema>;
export const ProjectCreateInputSchema = ProjectSchema.omit({ id: true });
export type ProjectCreateInput = z.infer<typeof ProjectCreateInputSchema>;
- Edit form → full entity schema.
- Create form → dedicated input schema (
Schema.omit({ id, createdAt, … })). - Partial PATCH →
Schema.partial()if the backend accepts any subset.
Never write a standalone TypeScript type that mirrors a schema. Always z.infer<typeof XSchema>.
Unsaved-changes guard
Edit forms only persist on Save — leaving the route or closing the dialog with isDirty === true silently discards the user's work. Wire a guard at the boundary in lib/forms/:
- Dialog/panel close: subscribe to
form.state.isDirty; prompt before closing (project-shaped —confirm(), shadcn<AlertDialog>, etc.). - Route navigation: in App Router the pragmatic answer is a
beforeunloadfor full-tab close + a custom<Link>wrapper for in-app nav.
The skill flags the requirement; the exact UX is project-shaped.
Error handling
The save / submit callback throws. Do not catch inside it. The hook routes the thrown error through mapFormError:
| Error type | UI action |
|---|---|
SessionExpiredError (HTTP 401) | Redirect to auth refresh route. Never toast. |
ForbiddenError (HTTP 403) | Error toast — the user clicked Save expecting it to work. |
Validation problem (HTTP 422 / RFC 7807 with errors: { field: [...] }) | Per-field server error set on the form + generic toast. |
| Other 4xx / 5xx | Toast the response body's detail or title. |
| Invalid response shape | Toast generic "invalid response". |
TypeError / network failure | Toast generic "network error". Form stays dirty for retry. |
Never wrap save / submit in try/catch. Never call toast.success / toast.error from a form component. Never re-implement the discriminated-union routing inline — extend mapFormError if you need a new case.
On any error the hook does not reset baseline — isDirty stays true.
i18n
If the project uses next-intl (or any other i18n library), all visible strings (labels, placeholders, button text, error messages) route through it. Never inline strings in form code. Add keys as you go. If the project has no i18n setup, flag the cost once at the top of the conversation but allow inline strings.
Red flags / rationalizations
| Rationalization | Counter |
|---|---|
"I just need a useState for one toggle." | Use <FormField name="…"> with <Switch>. The form hook owns it. |
"TanStack's useForm API is fine, I'll call it directly." | No. Always go through useEditForm / useCreateForm — they wire dirty tracking, baseline reset, error mapping, AbortController. Bypassing means each form re-derives the same concerns with a slightly different bug. |
"I'll just import { useForm } from 'react-hook-form' directly." | Same answer — even when stack.forms = "react-hook-form", the consumer-facing hook is useEditForm / useCreateForm. The underlying library is an implementation detail of lib/forms/. |
| "Auto-save would be nicer, I'll debounce 300ms." | No. The contract is explicit Save click. Auto-save changes the failure model (silent partial saves, race conditions) and the UX contract for the whole app. Project-wide decision, not per-component. |
| "I'll save on blur." | Same — save-on-blur is auto-save with a different trigger. |
| "I'll use the other form library here, I know it better." | The project standardizes on one. Mixing form libraries inside one app is a non-starter — toolkit, error mapping, dirty semantics all diverge. |
"I'll track dirty state with my own useState of initial values." | The hook already exposes state.isDirty. Read it via form.Subscribe. |
| "Save button feels weird disabled — I'll always enable it." | A clean form has nothing to save; clicking would either no-op or POST identical data. Disabled is honest. |
| "I'll try/catch the save and toast myself." | Never. Errors flow through mapFormError. Catching swallows the discriminated-union routing and produces inconsistent UX. |
| "I'll show a success toast on every save." | Configure it once in mapFormError. Never toast from a form component. |
| "No AbortController needed — the button is disabled while submitting." | Stale requests can still resolve out-of-order if the user resets and re-submits quickly. Leave the AbortController on. |
"I need per-field errors, I'll safeParse and setState." | The hook already runs the schema as validator. Errors surface via the field meta and render through <FormField>. |
| "This form needs client-side validation and dirty tracking, so I'll skip Server Actions and call the service straight from the component." | Backwards. The form component is inherently client-side (mark the leaf "use client", keep the parent page a Server Component) — but save/submit still must call a Server Action. Services are server-only per the data-fetching skill; a Client Component cannot import lib/services/ at all, with or without this skill's toolkit. |
| "I'll inline copy this once, i18n later." | The "later" pass touches every form. Add the key now. |
Escape hatch — raw library <Field>
Drop to raw <form.Field> (TanStack) or Controller (RHF) — skipping <FormField> wrapping — for:
- File uploads (multipart/form-data, progress, drag-drop UI).
- Multi-step wizard navigation the form layer can't model linearly.
- Inline table-cell editors (one cell, no surrounding
<FormProvider>).
Even when escaping <FormField>, still use useEditForm / useCreateForm and let mapFormError route errors. Still go through i18n. Still gate submit on canSave. 🔴 And the four accessibility requirements are still yours — escaping <FormField> means escaping the wrapper that was wiring aria-invalid, aria-describedby and the announcement for you, so write them by hand. This is the most common place a form loses them.
Toolkit reference
Build once per project. Lives at lib/forms/:
lib/forms/
├── index.ts # public re-exports
├── useEditForm.ts # manual-save hook with dirty tracking + baseline reset
├── useCreateForm.ts # manual-submit hook with onSuccess
├── FormProvider.tsx # React context wrapping the form instance
├── FormField.tsx # shadcn Field + Label + Error, render-prop API
├── FormActions.tsx # Save + Reset buttons, gated via Subscribe
└── mapFormError.ts # discriminated-union error → toast / per-field meta
For the canonical wiring of each file under both library backends (TanStack Form and react-hook-form), see references/toolkit-tanstack.md and references/toolkit-rhf.md.
To scaffold the toolkit in a fresh project run:
python3 scripts/scaffold_lib_forms.py --root <project-root>
The script reads meta.json#stack.forms, picks the matching template, writes the 7 files, prints the npx shadcn@latest add field input textarea select checkbox switch radio-group button label <toast|sonner> line for the missing UI primitives, and appends a history entry to meta.json. The toast backend follows the installed primitive: shadcn's Base UI components/ui/toast.tsx (toast.add, the default for --base base) or components/ui/sonner.tsx (toast.error) — mapFormError.ts is written for the one it finds.
Workflow
Step 1 — verify the contract
Read .workflow/meta.json. Branch:
stack.framework = "next"→ checkstack.nextjs_version = "16"(else refuse). Readstack.formsandstack.ui.stack.framework = "monorepo"→ operate on the web side; checkstack.monorepo.web.framework = "next"andstack.monorepo.web.nextjs_version = "16". Readstack.monorepo.web.formsandstack.monorepo.web.ui.- Anything else → refuse politely, explain why.
Resolve stack.forms per the selection logic above (read if set → auto-detect from the project → ask the user only if ambiguous or absent). Resolve stack.ui similarly by reading it directly; if unset, ask which UI library the project uses before writing <FormField>/<FormActions> code — do not assume shadcn. Write whatever is newly decided back to meta.json before proceeding.
Step 2 — confirm prerequisites
Run the prereq checklist from the Toolkit reference — package.json Next 16, shadcn configured (components.json), the underlying form library installed, lib/forms/index.ts exports the 7 surface items. If the toolkit is missing, run scripts/scaffold_lib_forms.py first.
Step 3 — apply the pattern
For an edit form, follow the Edit form pattern. For a create form, follow the Create form pattern. Both patterns are library-agnostic — the underlying TanStack/RHF binding lives in lib/forms/.
Step 4 — append history
Append to meta.json#history:
{
"skill": "forms",
"ran_at": "<now>",
"outputs": ["app/(app)/projects/[id]/edit-panel.tsx", "lib/types/project.ts"],
"phase_before": "<unchanged>",
"phase_after": "<unchanged>"
}
This skill does not bump phase.
Audit mode
When the user asks "audit my codebase against the forms skill" / "scan for form anti-patterns", produce a report — do not modify code. The detailed audit recipe (greps for each violation, severity rubric, report template) lives in references/audit-recipe.md.
This audit checks our conventions (which library, where the hook lives, how errors surface). Its complement is the shadscan gate, which checks the user-facing outcome — forms-have-labels, field-errors-rendered, invalid-fields-associated-with-errors, async-action-pending-state. Passing this audit does not imply passing that one: a textbook TanStack Form with no <FormLabel> is invisible to the greps below and fails shadscan on the spot.
The 10 violation kinds:
| Code | Violation | Severity |
|---|---|---|
| A | Mixed form libraries (both @tanstack/react-form and react-hook-form in package.json) | high |
| B | Raw useForm outside lib/forms/ | high |
| C | useState bound to form-like inputs | medium |
| D | toast.success/toast.error from a form component | high |
| E | Save-on-blur / debounce / auto-save | medium |
| F | Hand-rolled dirty tracking (initial-values refs, manual diff) | medium |
| G | <form onSubmit> calling fetch/services directly (no form.handleSubmit) | high |
| H | Inline AbortController in form components | medium |
| I | Hardcoded UI strings when i18n is set up | low |
| J | <Button type="submit"> not gated on isDirty (edit forms) | high |
Sources
This skill is heavily inspired by — and extends — the nextjs-forms skill from lusentis/next-skills (MIT-licensed). The original targets TanStack Form + Zod only; this skill adds the meta.json#stack.forms branching layer so the same hook surface (useEditForm / useCreateForm) is also available on top of react-hook-form for teams that prefer it. The discriminated-union error contract, baseline-reset semantics, dirty-gating discipline, and red-flag catalog are preserved.
- Original: https://github.com/lusentis/next-skills/tree/main/skills/nextjs-forms
- TanStack Form: https://tanstack.com/form/latest
- react-hook-form: https://react-hook-form.com
- Zod v4: https://zod.dev
- shadcn/ui
Field: https://ui.shadcn.com/docs/components/field
When in doubt
Re-read this skill, look at the most-recent existing edit form and create form in the codebase, and copy their structure. If the existing forms violate this skill, fix the new one to match the skill (not the existing forms) and flag the drift to the user.
Related skills
| Skill | Stars | Updated | Works with | Status | Install |
|---|---|---|---|---|---|
| slack-gif-creatoranthropics/skillsKnowledge and utilities for creating animated GIFs optimized for Slack. Provides constraints, validation tools, and animation concepts. Use when users request animated GIFs for Slack like "make me a GIF of X doing Y for Slack." | Stars: 198k | Updated | Claude CodeCodex | Verified | Install |
| ponytailDietrichGebert/ponytailLazy senior dev mode for any coding task: the smallest change that fully solves it, and a reply a busy human understands in one read. | Stars: 194k | Updated | Claude CodeCodex | Verified | Install |
| ponytail-debtDietrichGebert/ponytailHarvest every shortcut: comment into one debt ledger, so deferrals get tracked instead of forgotten. One-shot report. | Stars: 194k | Updated | Claude CodeCodex | Verified | Install |
| ponytail-debtDietrichGebert/ponytailList every `shortcut:` comment (and older `ponytail:` ones) as a debt ledger. One-shot report, changes nothing. Use for "ponytail debt", "what did ponytail defer", "list the shortcuts", /ponytail-debt. | Stars: 194k | Updated | Claude CodeCodex | Verified | Install |