@tailor-platform/app-shell 1.13.0 → 1.14.0

package/skills/app-shell-patterns/references/fundamental/components.md

@@ -433,7 +433,7 @@ const table = useDataTable({
 
 **Column alignment:** each `Column` accepts **`align`** (`"left" | "right"`) applied to both header and body cell. Numeric `type` columns (`"number"`, `"money"`) default to `"right"` automatically so digits align on the decimal place — pass `align="left"` to opt out; everything else defaults to `"left"`.
 
-**Metadata path:** Prefer `createColumnHelper` + `inferColumns(tableMetadata.order)` (`@tailor-platform/app-shell-sdk-plugin` codegen) when available so enum/datetime/string filters bind to the right editors.
+**Metadata path:** Prefer `createColumnHelper` + `inferColumns(tableMetadata.order)` (`@tailor-platform/sdk-plugin-app-shell` codegen) when available so enum/datetime/string filters bind to the right editors.
 
 **Bucket tabs / segmented UX:** AppShell defines **toolbar chips**, not lifecycle tabs. When design places **`Tabs`** (All / Draft / …) inside the card, compose them **above** `DataTable.Root` and synchronize tab-driven bucket state with **`useCollectionVariables`** (`variables.query` / filters)—see **`patterns/list/dense-scan.md`**.
 
@@ -619,13 +619,41 @@ const table = useDataTable({
 
 ## Forms
 
+> **Which form stack?** AppShell's `Form` / `Field` / `Fieldset` wrap Base UI primitives and are the
+> default — they need no extra dependency. They own **accessibility wiring and visual state only**
+> (`htmlFor`, `aria-describedby`, `data-invalid` / `data-dirty` / `data-touched`); they do **not** own
+> your values. React Hook Form is **optional** and consumer-installed — reach for it only when a form
+> genuinely needs cross-field validation, field arrays, or a Zod resolver. The two compose; they are
+> not alternatives. `react-hook-form` stopped being a runtime dependency in 1.4.0; it is a dev-only
+> dependency of the package today, used to test the RHF integration contracts — if you use it,
+> install it in your own app.
+
 ### `Form`
 
 > Full API: [https://raw.githubusercontent.com/tailor-platform/app-shell/refs/heads/main/docs/components/form.md](https://raw.githubusercontent.com/tailor-platform/app-shell/refs/heads/main/docs/components/form.md)
 
 **Import:** `import { Form } from '@tailor-platform/app-shell'`
-**Purpose:** Form root wired to react-hook-form. Use with `Field`, `Fieldset`, and Zod for validation.
-**API:** `FormProps` — `errors`, `actionsRef`, `validationMode`, `noValidate`, plus a namespace exposing form-related sub-helpers. Generic over `FormValues`.
+**Purpose:** Form root that wraps Base UI's form primitive. Provides shared validation context for
+child `Field.Root`s, consolidated error display, and server-error routing by field `name`.
+**API:** `FormProps` — `onFormSubmit`, `onSubmit`, `errors`, `actionsRef`, `validationMode`,
+`noValidate`, `id`. Generic over `FormValues`.
+**Actions outside the form:** give the `Form` an `id` and point a detached submit button at it with
+the native `form` attribute. This is how a page-header Save reaches a body form (1.13.0+):
+
+```tsx
+<Layout.Header
+  title="Create product"
+  actions={[<Button key="save" type="submit" form="product-form">Save</Button>]}
+/>
+<Form id="product-form" onFormSubmit={save}>…</Form>
+```
+
+**Submit:** use `onFormSubmit(values)` — it receives parsed form values and is the default. Use the
+low-level `onSubmit` **only** when handing the native event to React Hook Form's `handleSubmit`.
+**Never** hand-roll `<form onSubmit={e => new FormData(e.currentTarget)}>` — that skips validation
+and error routing.
+**Server errors:** pass `errors={{ fieldName: "message" }}`; they route to the matching
+`Field.Error` and clear when the user edits that field.
 **Example:** see `form/single-page.md`.
 **Used in patterns:** all `form/*`.
 
@@ -633,9 +661,71 @@ const table = useDataTable({
 
 **Import:** `import { Field } from '@tailor-platform/app-shell'`
 **Purpose:** Single form field with label + control + error message wiring.
-**API:** Compound. Wraps any input control (`Input`, `Select`, `Combobox`, etc.) and binds it to react-hook-form via `name`.
+**API:** Compound — `Field.Root`, `Field.Label`, `Field.Control`, `Field.Description`, `Field.Error`,
+`Field.Validity`. `Field.Root` establishes a context boundary; every Base UI-backed AppShell control
+placed inside it inherits label association, `aria-describedby`, `disabled`, and invalid state
+automatically.
+**`Field.Control` is already a styled input** — write `<Field.Control />`, not
+`<Field.Control render={<Input />} />`. `Input` and `Field.Control` share the same base classes, so
+the `render` form just double-wraps. Reach for `Input` directly when you need a control outside a
+`Field.Root`, or when the value is React-controlled.
+**RHF interop (optional):** `Field.Root` accepts `isTouched`, `isDirty`, `invalid`, and `error`,
+matching RHF's `fieldState` shape — so `<Field.Root {...fieldState}>` works with no adapter.
 **Used in patterns:** all `form/*`.
 
+### How values reach your submit handler
+
+There are three separate mechanisms. Picking the wrong mental model is the most common
+form mistake, so be explicit about which one a screen uses.
+
+**1. `Form` + `Field.Root` → `onFormSubmit` (the default).** `onFormSubmit` does **not** read
+`FormData`; it collects values from the `Field.Root`s registered inside the `Form`, keyed by each
+field's `name`. Every AppShell control works this way once wrapped in a `Field.Root name="…"` —
+including `Select`, `Combobox`, and `Autocomplete`. They need **no `name` of their own and no React
+state**:
+
+```tsx
+<Form onFormSubmit={(values) => save(values)}>
+  <Field.Root name="category">
+    <Field.Label>Category</Field.Label>
+    <Select items={CATEGORIES} placeholder="Select category" />
+  </Field.Root>
+</Form>
+```
+
+**2. Native submission** — a plain `<form>`, `new FormData(form)`, or a server action. This reads the
+DOM, so each control needs its own `name`. `Select`, `Combobox`, and `Autocomplete` gained `name`
+(plus `form`, `required`, `inputRef`) in 1.13.0; before that they contributed nothing to a native
+payload.
+
+**3. React Hook Form** — optional, consumer-installed. RHF owns the values; drive the control with
+`value` / `onValueChange` from a `Controller` and spread `fieldState` onto `Field.Root`. Warranted
+for cross-field validation, field arrays, or a Zod resolver — not for ordinary CRUD forms.
+
+#### Object items
+
+Under mechanism 1, a non-string item is serialised into the submitted value:
+
+| Item shape                             | Value in `onFormSubmit`              |
+| -------------------------------------- | ------------------------------------ |
+| `string`                               | the string                           |
+| `{ value, label }`                     | `value`, automatically               |
+| any other object                       | **JSON string** — usually not wanted |
+| any other object + `itemToStringValue` | whatever that function returns       |
+
+So for arbitrary objects, pass `itemToStringValue` to choose the submitted key. It is distinct from
+`mapItem`, which controls what the user sees:
+
+```tsx
+<Combobox
+  items={warehouses}
+  mapItem={(w) => ({ label: w.name, key: String(w.id) })}
+  itemToStringValue={(w) => String(w.id)}
+/>
+```
+
+Multi-select submits an array.
+
 ### `Fieldset`
 
 **Import:** `import { Fieldset } from '@tailor-platform/app-shell'`

package/skills/app-shell-patterns/references/fundamental/graphql.md

@@ -108,7 +108,7 @@ For `pnpm gql-tada:check` to pass, always destructure with optional chaining and
 
 For **standard list pages**, do not hand-roll only `first` / `after`. Compose AppShell **`DataTable`** + **`useCollectionVariables`** + **`useDataTable`**: derive query variables from `variables.pagination`, `variables.query`, `variables.order`, map `edges` / `pageInfo` / `total` into `useDataTable`’s `data`. See **`patterns/list/dense-scan.md`** and **`components.md` → DataTable**.
 
-When `@tailor-platform/app-shell-sdk-plugin` codegen is enabled, pass generated **`tableMetadata`** into **`useCollectionVariables`** so `variables.query` / `variables.order` are typed against your Tailor GraphQL inputs (upstream **data-table.md** Typed query variables).
+When `@tailor-platform/sdk-plugin-app-shell` codegen is enabled, pass generated **`tableMetadata`** into **`useCollectionVariables`** so `variables.query` / `variables.order` are typed against your Tailor GraphQL inputs (upstream **data-table.md** Typed query variables).
 
 ## Mutations and cache invalidation
 

package/skills/app-shell-patterns/references/patterns/form-modal.md

@@ -4,7 +4,7 @@ name: Modal Form
 category: pattern
 subcategory: form
 description: Default form pattern for Create/Edit — keeps user in context on the parent screen
-requiredImports: [Dialog, Button, Form, Field, Input]
+requiredImports: [Dialog, Button, Form, Field, Layout]
 tags: [form, modal, dialog, create, edit, inline-add]
 do:
   - Default for most Create and Edit forms — keeps user in context on parent screen
@@ -30,10 +30,16 @@ dont:
 
 ```tsx
 /* pattern: form/modal */
-import { Button, Dialog, Input, Field } from "@tailor-platform/app-shell";
+import { Button, Dialog, Field, Form } from "@tailor-platform/app-shell";
+
+type Address = {
+  label: string;
+  street: string;
+  city: string;
+};
 
 type Props = {
-  onSave: (data: { label: string; street: string; city: string }) => void;
+  onSave: (data: Address) => void;
 };
 
 export default function ModalForm({ onSave }: Props) {
@@ -45,36 +51,34 @@ export default function ModalForm({ onSave }: Props) {
           <Dialog.Title>Add address</Dialog.Title>
           <Dialog.Description>Add a shipping address to this order.</Dialog.Description>
         </Dialog.Header>
-        <form
-          onSubmit={(e) => {
-            e.preventDefault();
-            const formData = new FormData(e.currentTarget);
-            onSave({
-              label: formData.get("label") as string,
-              street: formData.get("street") as string,
-              city: formData.get("city") as string,
-            });
-          }}
-        >
+        {/*
+         * `Form` + `onFormSubmit` replaces a hand-rolled `<form onSubmit>` +
+         * `FormData`: values arrive parsed, and validation runs before the
+         * handler fires. Every text field is uncontrolled — no state needed.
+         */}
+        <Form<Address> noValidate onFormSubmit={(values) => onSave(values)}>
           <div className="space-y-4 py-4">
             <Field.Root name="label">
               <Field.Label>Label</Field.Label>
-              <Field.Control render={<Input />} />
+              <Field.Control required placeholder="Head office" />
+              <Field.Error match="valueMissing">Label is required.</Field.Error>
             </Field.Root>
             <Field.Root name="street">
               <Field.Label>Street</Field.Label>
-              <Field.Control render={<Input />} />
+              <Field.Control required />
+              <Field.Error match="valueMissing">Street is required.</Field.Error>
             </Field.Root>
             <Field.Root name="city">
               <Field.Label>City</Field.Label>
-              <Field.Control render={<Input />} />
+              <Field.Control required />
+              <Field.Error match="valueMissing">City is required.</Field.Error>
             </Field.Root>
           </div>
           <Dialog.Footer>
             <Dialog.Close render={<Button variant="ghost" />}>Cancel</Dialog.Close>
             <Button type="submit">Save</Button>
           </Dialog.Footer>
-        </form>
+        </Form>
       </Dialog.Content>
     </Dialog.Root>
   );
@@ -85,13 +89,18 @@ export default function ModalForm({ onSave }: Props) {
 
 ```tsx
 /* pattern: form/modal (route-driven variant) */
-import { Button, Dialog, Input, Layout, Field } from "@tailor-platform/app-shell";
+import { useState } from "react";
+import { Button, Dialog, Field, Form, Layout } from "@tailor-platform/app-shell";
+
+type ProductDraft = {
+  name: string;
+};
 
 type Props = {
   isCreateOpen: boolean;
   onNavigateToCreate: () => void;
   onNavigateToList: () => void;
-  onSave: (data: { name: string }) => void;
+  onSave: (data: ProductDraft) => Promise<{ errors?: Record<string, string> }>;
 };
 
 /**
@@ -105,6 +114,21 @@ export default function ModalFormRouted({
   onNavigateToList,
   onSave,
 }: Props) {
+  // Server-side validation errors, keyed by field `name`. `Form` routes each
+  // one to the matching `Field.Error` and clears it when the user edits that
+  // field — so failures never need their own alert banner.
+  const [errors, setErrors] = useState<Record<string, string>>({});
+
+  const handleSubmit = async (values: ProductDraft) => {
+    const result = await onSave(values);
+    if (result.errors) {
+      setErrors(result.errors);
+      return;
+    }
+    setErrors({});
+    onNavigateToList();
+  };
+
   return (
     <Layout>
       <Layout.Header
@@ -127,26 +151,23 @@ export default function ModalFormRouted({
           <Dialog.Header>
             <Dialog.Title>Create product</Dialog.Title>
           </Dialog.Header>
-          <form
-            onSubmit={(e) => {
-              e.preventDefault();
-              const formData = new FormData(e.currentTarget);
-              onSave({ name: formData.get("name") as string });
-            }}
-          >
+          <Form<ProductDraft> noValidate errors={errors} onFormSubmit={handleSubmit}>
             <div className="space-y-4 py-4">
               <Field.Root name="name">
                 <Field.Label>Name</Field.Label>
-                <Field.Control render={<Input />} />
+                <Field.Control required />
+                {/* Catch-all: renders the native message, a `match` message, or
+                    the server error routed in via the `errors` prop above. */}
+                <Field.Error />
               </Field.Root>
             </div>
             <Dialog.Footer>
-              <Button variant="ghost" onClick={onNavigateToList}>
+              <Button type="button" variant="ghost" onClick={onNavigateToList}>
                 Cancel
               </Button>
               <Button type="submit">Save</Button>
             </Dialog.Footer>
-          </form>
+          </Form>
         </Dialog.Content>
       </Dialog.Root>
     </Layout>
@@ -159,6 +180,36 @@ export default function ModalFormRouted({
 - Dialog renders full-screen sheet below 1024px; centered max-w-md at 1024–1280px
 - Route-driven variant requires both parent path and create/edit path to render the same component
 - `onOpenChange` must navigate back — just calling `setOpen(false)` leaves the URL broken
+- Use `<Form onFormSubmit>`, never a bare `<form onSubmit>` — see **Form state** below
+- Cancel must be `type="button"`; inside a `<Form>` an untyped `<button>` defaults to `submit`
+
+## Form state
+
+Applies to every `form/*` pattern. Full detail in **`components.md`** → Forms.
+
+`form/composer` follows all of this too, with one documented exception noted below: its body is
+controlled, because a composer reads the value during render to gate its submit and swap its
+placeholder.
+
+- **`Form` + `Field` is the default stack.** They wrap Base UI and ship with AppShell — no extra
+  dependency.
+- **Submit via `onFormSubmit(values)`.** It fires only after validation passes. Do not hand-roll
+  `<form onSubmit>` + `new FormData(...)` — that skips validation and server-error routing.
+- **`onFormSubmit` reads registered `Field.Root`s, not the DOM.** So every control — including
+  `Select`, `Combobox`, and `Autocomplete` — just needs wrapping in a `Field.Root name="…"`. They
+  need **no `name` of their own and no `useState`**. Mirroring field values into React state is the
+  most common thing to get wrong here. The exception is a value the component must read _during
+  render_ — a submit gate, a dependent placeholder, a live character count. That state is
+  load-bearing, not mirrored; see `form/composer`.
+- **`Field.Control` is already a styled input.** Write `<Field.Control />`, not
+  `<Field.Control render={<Input />} />`.
+- **Object items need `itemToStringValue`.** Items shaped `{ value, label }` submit `value`
+  automatically; any other object submits as a JSON string unless you supply it.
+- **Server errors go through `Form`'s `errors` prop**, keyed by field `name` — not a toast or a
+  banner. They clear when the user edits the field.
+- **React Hook Form is optional**, consumer-installed, and only warranted for cross-field
+  validation, field arrays, or a Zod resolver. It composes with `Field`: drive the control from a
+  `Controller` and spread `fieldState` onto `Field.Root`.
 
 ## Anti-patterns
 
@@ -167,3 +218,6 @@ export default function ModalFormRouted({
 - Save closes the dialog but parent state is stale — wire refetch or optimistic update
 - Building a routed Create/Edit page when the design didn't explicitly call for one — modal is the default
 - Registering the create path as a separate top-level route — that unmounts the parent list
+- Reaching for React Hook Form on a form this size — `onFormSubmit` already covers it
+- Holding a `Select`/`Combobox` value in `useState` just to submit it — `Field.Root` already does
+- Surfacing API validation failures in a toast or banner instead of routing them via `errors`

package/skills/app-shell-patterns/references/patterns/form-sectioned.md

@@ -4,7 +4,7 @@ name: Sectioned Form
 category: pattern
 subcategory: form
 description: Complex form with 15+ fields organized into named fieldset sections
-requiredImports: [Layout, Form, Fieldset, Field, Input, Select, Combobox, Button]
+requiredImports: [Layout, Card, Form, Fieldset, Field, Combobox, Button]
 tags: [form, sections, fieldset, settings, complex]
 do:
   - Form is complex with 15+ fields or multiple grouped sections (Identity, Pricing, Inventory)
@@ -26,10 +26,26 @@ dont:
 
 ```tsx
 /* pattern: form/sectioned */
-import { Button, Layout, Input, Select, Field, Fieldset } from "@tailor-platform/app-shell";
+import { Button, Card, Combobox, Field, Fieldset, Form, Layout } from "@tailor-platform/app-shell";
+
+const CURRENCIES = ["USD", "EUR", "GBP", "JPY"];
+
+const WAREHOUSES = [
+  { id: 1, name: "Tokyo DC" },
+  { id: 2, name: "Osaka DC" },
+  { id: 3, name: "Nagoya DC" },
+];
+
+const SECTIONS = [
+  { id: "identity", title: "Identity", description: "How the product is named and referenced." },
+  { id: "pricing", title: "Pricing", description: "List price and the currency it is quoted in." },
+  { id: "inventory", title: "Inventory", description: "Opening stock and replenishment trigger." },
+];
+
+const anchorIdFor = (id: string) => `section-${id}`;
 
 type Props = {
-  onSave: (data: Record<string, string>) => void;
+  onSave: (data: Record<string, unknown>) => void;
   onCancel: () => void;
 };
 
@@ -42,71 +58,105 @@ export default function SectionedForm({ onSave, onCancel }: Props) {
           <Button key="cancel" variant="outline" onClick={onCancel}>
             Cancel
           </Button>,
-          <Button key="save" type="submit" form="sectioned-form">
+          <Button key="save" type="submit" form="product-settings-form">
             Save
           </Button>,
         ]}
       />
       <Layout.Column>
-        <form
-          id="sectioned-form"
-          onSubmit={(e) => {
-            e.preventDefault();
-            const formData = new FormData(e.currentTarget);
-            const entries: Record<string, string> = {};
-            formData.forEach((value, key) => {
-              entries[key] = value as string;
-            });
-            onSave(entries);
-          }}
-          className="space-y-8"
+        <Form
+          id="product-settings-form"
+          noValidate
+          className="space-y-4"
+          onFormSubmit={(values) => onSave(values)}
         >
-          <Fieldset.Root>
-            <Fieldset.Legend>Identity</Fieldset.Legend>
-            <div className="space-y-4">
-              <Field.Root name="name">
-                <Field.Label>Name</Field.Label>
-                <Field.Control render={<Input />} />
-              </Field.Root>
-              <Field.Root name="sku">
-                <Field.Label>SKU</Field.Label>
-                <Field.Control render={<Input />} />
-              </Field.Root>
-              <Field.Root name="description">
-                <Field.Label>Description</Field.Label>
-                <Field.Control render={<Input />} />
-              </Field.Root>
-            </div>
-          </Fieldset.Root>
-
-          <Fieldset.Root>
-            <Fieldset.Legend>Pricing</Fieldset.Legend>
-            <div className="space-y-4">
-              <Field.Root name="price">
-                <Field.Label>Price</Field.Label>
-                <Field.Control render={<Input type="number" />} />
-              </Field.Root>
-              <Field.Root name="currency">
-                <Field.Label>Currency</Field.Label>
-                <Select items={["USD", "EUR", "GBP", "JPY"]} placeholder="Select currency" />
-              </Field.Root>
-            </div>
-          </Fieldset.Root>
-
-          <Fieldset.Root>
-            <Fieldset.Legend>Inventory</Fieldset.Legend>
-            <div className="space-y-4">
-              <Field.Root name="quantity">
-                <Field.Label>Initial quantity</Field.Label>
-                <Field.Control render={<Input type="number" />} />
-              </Field.Root>
-              <Field.Root name="reorderPoint">
-                <Field.Label>Reorder point</Field.Label>
-                <Field.Control render={<Input type="number" />} />
-              </Field.Root>
-            </div>
-          </Fieldset.Root>
-        </form>
+          {/* Anchor nav — each entry targets its section's Card by id. */}
+          <nav aria-label="Sections" className="flex gap-4 text-sm">
+            {SECTIONS.map((section) => (
+              <a
+                key={section.id}
+                href={`#${anchorIdFor(section.id)}`}
+                className="text-muted-foreground hover:text-foreground"
+              >
+                {section.title}
+              </a>
+            ))}
+          </nav>
+
+          <Card.Root id={anchorIdFor("identity")}>
+            <Card.Header title={SECTIONS[0].title} description={SECTIONS[0].description} />
+            <Card.Content>
+              <Fieldset.Root className="grid gap-4 md:grid-cols-2">
+                <Field.Root name="name">
+                  <Field.Label>Name</Field.Label>
+                  <Field.Control required />
+                  <Field.Error match="valueMissing">Name is required.</Field.Error>
+                </Field.Root>
+                <Field.Root name="sku">
+                  <Field.Label>SKU</Field.Label>
+                  <Field.Control required />
+                  <Field.Error match="valueMissing">SKU is required.</Field.Error>
+                </Field.Root>
+                <Field.Root name="description" className="md:col-span-2">
+                  <Field.Label>Description</Field.Label>
+                  <Field.Control />
+                </Field.Root>
+              </Fieldset.Root>
+            </Card.Content>
+          </Card.Root>
+
+          <Card.Root id={anchorIdFor("pricing")}>
+            <Card.Header title={SECTIONS[1].title} description={SECTIONS[1].description} />
+            <Card.Content>
+              <Fieldset.Root className="grid gap-4 md:grid-cols-2">
+                <Field.Root name="price">
+                  <Field.Label>Price</Field.Label>
+                  <Field.Control type="number" required min={0} step="0.01" />
+                  <Field.Error match="valueMissing">Price is required.</Field.Error>
+                </Field.Root>
+                <Field.Root name="currency">
+                  <Field.Label>Currency</Field.Label>
+                  <Combobox items={CURRENCIES} defaultValue="USD" placeholder="Select currency" />
+                  <Field.Error />
+                </Field.Root>
+              </Fieldset.Root>
+            </Card.Content>
+          </Card.Root>
+
+          <Card.Root id={anchorIdFor("inventory")}>
+            <Card.Header title={SECTIONS[2].title} description={SECTIONS[2].description} />
+            <Card.Content>
+              <Fieldset.Root className="grid gap-4 md:grid-cols-2">
+                <Field.Root name="quantity">
+                  <Field.Label>Initial quantity</Field.Label>
+                  <Field.Control type="number" required min={0} />
+                  <Field.Error match="valueMissing">Initial quantity is required.</Field.Error>
+                </Field.Root>
+                <Field.Root name="reorderPoint">
+                  <Field.Label>Reorder point</Field.Label>
+                  <Field.Control type="number" min={0} />
+                  <Field.Description>
+                    Leave blank to disable replenishment alerts.
+                  </Field.Description>
+                </Field.Root>
+                {/*
+                 * Object items would otherwise reach `onFormSubmit` as JSON.
+                 * `itemToStringValue` picks the field to submit; `mapItem`
+                 * stays responsible for what the user sees.
+                 */}
+                <Field.Root name="warehouse">
+                  <Field.Label>Default warehouse</Field.Label>
+                  <Combobox
+                    items={WAREHOUSES}
+                    mapItem={(w) => ({ label: w.name, key: String(w.id) })}
+                    itemToStringValue={(w) => String(w.id)}
+                    placeholder="Select warehouse"
+                  />
+                </Field.Root>
+              </Fieldset.Root>
+            </Card.Content>
+          </Card.Root>
+        </Form>
       </Layout.Column>
     </Layout>
   );
@@ -117,10 +167,32 @@ export default function SectionedForm({ onSave, onCancel }: Props) {
 
 - Max ~6 sections — more than that is too hard to scan; promote to `form/wizard`
 - Required-marker convention must be consistent across all sections
-- Section legends must match anchor-nav labels
+- One `Card.Root` per section, titled via `Card.Header title` + `description`; `Fieldset.Root`
+  inside supplies the field grouping and the responsive grid
+- Save/Cancel belong in `Layout.Header`, wired with `<Button type="submit" form="…">` matching the
+  `Form`'s `id` (requires 1.13.0+)
+- Section headings must match anchor-nav labels — derive both from one `SECTIONS` array so they
+  cannot drift
+- A single `<Form>` wraps every section — do not nest a `Form` per section
+
+## Form state
+
+Rules that apply to every `form/*` pattern are in **`components.md`** → Forms, with a worked example
+in **`form/modal`** → Form state: `Form` + `Field` is the default stack, submit via `onFormSubmit`,
+dropdowns need only a wrapping `Field.Root` (no `name`, no state), server errors route through
+`errors`, and React Hook Form is an optional escape hatch.
+
+At 15+ fields the temptation to reach for a form library is strongest, and it is usually wrong:
+every field here — text, number, and dropdown alike — is uncontrolled and arrives through
+`onFormSubmit`. The only per-field extra is `itemToStringValue` on dropdowns whose items are
+objects rather than strings.
 
 ## Anti-patterns
 
 - More than ~6 sections — hard to scan; promote to `form/wizard`
 - Required-marker convention varies between sections — pick one rule and apply everywhere
-- Section legends that don't match anchor-nav labels
+- Section headings that don't match anchor-nav labels
+- A separate `<Form>` per section — submit and validation then fragment across the page
+- Mirroring field values into `useState` to "keep the payload together" — `onFormSubmit` already
+  returns the whole payload
+- Submitting an object-valued dropdown without `itemToStringValue` — the value arrives as JSON