Codex

How every form page — a record being created or edited as the page's whole purpose — is built. The kit is src/components/form-page/ (+ @/components/ui/field for field anatomy); the living example is /labs/layout/form. Same contract as data-view.md: the kit enforces what it can with defaults, this file records the rest.

Scope: whole-page create/edit flows. A filter control in a toolbar, a search box, an inline-editable table cell are NOT this class — they belong to their own page's law. A settings page is a sibling class with its own future law (grouped navigation, per-section apply semantics); don't stretch this one over it.

A form is an interview, and an interview happens in one column. Reading a form is a top-to-bottom activity: every column added is a chance to submit half an interview. So the form is ONE feature in ONE standard Card on a NARROW measure (max-w-2xl), sections stacked with dashed seams, the action footer last — and the only sanctioned multi-column is FormRow, two SHORT, RELATED fields sharing a line (first / last name), which still stacks on phones.

const schema = z.object({ … });                    // schema first
type Values = z.infer<typeof schema>;              // the type derives

const form = useForm<Values>({ resolver: zodResolver(schema), defaultValues });
useUnsavedGuard(form.formState.isDirty);

<FormShell onSubmit={form.handleSubmit(onSubmit)}>
  <FormSection title="Identity" description="…">
    <Field data-invalid={!!errors.name}>
      <FieldLabel htmlFor="name">Name</FieldLabel>
      <Input id="name" {...form.register("name")} aria-invalid={!!errors.name} />
      <FieldDescription>…</FieldDescription>
      <FieldError errors={[errors.name]} />
    </Field>
    <FormRow>…two related short fields…</FormRow>
  </FormSection>
  <FormSection title="…">…</FormSection>
  <FormFooter dirty={form.formState.isDirty}>
    <Button variant="outline" type="button" disabled={!isDirty} onClick={() => form.reset()}>Reset</Button>
    <Button type="submit" disabled={!isDirty || isSubmitting}>Save</Button>
  </FormFooter>
</FormShell>

• Schema first. The zod schema is the single source of shape, constraint and message; the TS type derives from it (z.infer), and there is no hand-written validation beside it (repo-wide rule, enforced here).
• Dirty is the form's status system. Submit disabled until something changed; Reset discards exactly what the readout warns about; a successful save calls reset(values) so the clean state is re-baselined, not faked. useUnsavedGuard covers tab-close — and because the App Router can't intercept in-app links, the footer's readout is the real guard.
• Errors live under their field, at submit time. Validate on submit; re-validate the offending field as the user fixes it (RHF's default). No toast-as-validation, no error summary banner for a form this size — the eye is already in the column.
• A submit has three outcomes, all visible: disabled (nothing to save), field errors (the interview isn't done), or a toast + re-baselined form (saved). Silence is never one of them.
• Selection controls state their consequences. A radio/switch whose label alone is ambiguous carries a FieldDescription — the one-line cost of not making the user guess.
• No sticky footer. At max-w-2xl the footer is never far; pinning it would cover fields on small screens for no gain. If a form grows long enough to argue for one, it has outgrown one page — split the sections.

1. Write the zod schema and defaults; infer the type.
2. useForm + zodResolver; wire useUnsavedGuard(isDirty).
3. Compose FormShell → FormSections → ui/field anatomy per field; register inputs, Controller for Select / Radio / Switch.
4. Footer: Reset + submit, both gated on isDirty; submit toasts and reset(values) on success.
5. Register the route and extend the feature ledger.

• A form spread over two columns, or a wide Card (max-w-2xl is the law).
• Validation logic beside the schema, or browser-native validation bubbles.
• A submit that's always enabled, or a save that doesn't re-baseline dirty.
• Errors surfaced in a toast or a summary banner instead of under the field.
• A sticky action bar on a single-card form.
• Solid seams between sections (dashed, like every region seam in a card).