@tailor-platform/app-shell 1.15.0 → 1.17.0

package/skills/app-shell-patterns/references/migrations.md

@@ -1,3 +1,5 @@
+<!-- GENERATED by docs-kit from docs-src/guides/migrations.docs.outline.md — do not edit by hand. -->
+
 # Migrations
 
 Every change that requires you to edit your application before or after upgrading, newest first.
@@ -8,6 +10,8 @@ Each entry states which versions are affected, what breaks, how to detect it, an
 
 | Version       | Change                                                                                                                       |
 | ------------- | ---------------------------------------------------------------------------------------------------------------------------- |
+| 1.17.0        | [Status and alert tokens now resolve to the colour roles](#1170-status-and-alert-tokens-now-resolve-to-the-colour-roles)     |
+| 1.15.0        | [Base UI 1.8.0 breaks closed-`Select` and dialog-click tests](#1150-base-ui-180-breaks-closed-select-and-dialog-click-tests) |
 | 1.12.0        | [`DateField` / `DatePicker` field chrome moved to `Field.Root`](#1120-datefield--datepicker-field-chrome-moved-to-fieldroot) |
 | 1.11.0        | [React 19.2.7 and React Router v8 required](#1110-react-1927-and-react-router-v8-are-now-required)                           |
 | 1.11.0        | [Non-modal `Sheet` renders no backdrop](#1110-non-modal-sheet-no-longer-renders-a-backdrop)                                  |
@@ -18,6 +22,57 @@ Each entry states which versions are affected, what breaks, how to detect it, an
 | 1.0.2         | [`Toaster` no longer accepts `richColors`](#102-toaster-no-longer-accepts-richcolors)                                        |
 | before 1.0    | [Pre-1.0 breaking changes](#before-10)                                                                                       |
 
+## 1.17.0: status and alert tokens now resolve to the colour roles
+
+**Applies to:** apps that use `bg-status-*`, `text-status-*` or `bg-alert-*` utilities, and apps whose theme overrides `--status-*`, `--alert-*` or `--destructive` to recolour `Badge`, `Alert`, `CsvImporter` or `MetricCard`.
+
+1.17.0 adds semantic colour roles, `--{info|success|warning|danger|neutral}-{surface|surface-hover|border|solid|solid-hover|text|contrast|indicator}`, bridged as Tailwind colours such as `bg-success-surface` and `text-danger-text`. The old `--status-*` and `--alert-*` tokens still exist and still work, but they no longer hold their own colours: each one now resolves to a role (for example `--status-completed` is `var(--success-solid)`). They are deprecated and will be removed in the next major. Nothing errors. Three things change silently:
+
+- **Colours change.** `bg-status-*` and `bg-alert-*` resolve to the role values. For example `bg-status-completed` is `#15803d` instead of `#22c55e`. `--status-default` follows `--muted-foreground` instead of a fixed `#737373`.
+- **Component recolouring moves to the roles.** `Badge`, `Alert`, `CsvImporter` and `MetricCard` read the roles directly. A theme that overrides `--status-*` or `--alert-*` no longer changes these components; override `--{intent}-*` instead. `Badge` `error` / `subtle-error` and `Alert` `error` read `--danger-*`, so overriding `--destructive` no longer reaches them either. `Button variant="destructive"` and `text-destructive` still follow `--destructive`.
+- **`text-status-*` loses contrast in dark mode.** The `--status-*` values are now the step-9 fills, which are below 4.5:1 as text on the dark card.
+
+How to detect it: search the app for `status-`, `alert-` and theme overrides of `--status-`, `--alert-` and `--destructive`. Compare `Badge` and `Alert` in light and dark mode after upgrading.
+
+What to change:
+
+- Replace `text-status-completed` with `text-success-text`, `text-status-attention` with `text-warning-text`, `text-status-danger` with `text-danger-text`, and `text-status-neutral` with `text-info-text`.
+- Replace `bg-status-completed/10 border-status-completed/30` style tints with `bg-success-surface border-success-border`. The same applies to the other intents and to `bg-alert-*` / `border-alert-*`.
+- In a theme that recolours the status components, set the roles (`--success-solid`, `--danger-text`, ...) instead of `--status-*`, `--alert-*` or `--destructive`.
+
+The roles are documented in [Styling & theming](https://github.com/tailor-platform/app-shell/blob/main/docs/concepts/styling-theming.md#semantic-color-roles). The decision record is `decisions/semantic-color-roles.md`.
+
+## 1.15.0: Base UI 1.8.0 breaks closed-`Select` and dialog-click tests
+
+**Applies to:** apps with unit tests that assert `Select` options without opening the `Select`, and apps with Playwright tests that click buttons inside a `Dialog` or `AlertDialog`.
+
+1.15.0 updates the bundled `@base-ui/react` from 1.6.0 to 1.8.0 (1.12.0 to 1.14.0 used 1.6.0). The AppShell API is unchanged and the app behaves the same for the people using it. Two upstream behaviour changes do break tests that relied on the old behaviour, so an app that changes nothing can still go red in CI after upgrading. The fix is in the tests, not the app.
+
+### `Select` options are not in the DOM until it opens
+
+A closed `Select` used to render its options into the DOM. It no longer does, so a test that asserts option text with `getByText` on a closed `Select` fails with "Unable to find an element".
+
+Open the `Select` first, then wait for the option:
+
+```tsx
+await userEvent.click(screen.getByRole("combobox", { name: "Auto Renewal Period" }));
+expect(await screen.findByText("1 Month")).toBeInTheDocument();
+```
+
+### Dialog scroll lock can move a button under a Playwright click
+
+Opening a `Dialog` or `AlertDialog` applies a scroll lock that shifts the layout slightly. Playwright can judge a button stable and then click where it used to be, so the click lands on the backdrop and closes the dialog. The test then times out waiting for the dialog, and the Playwright call log shows the click being retried after "element was detached from the DOM".
+
+Press the button instead of clicking it. `press` does not use coordinates, so the layout shift cannot affect it:
+
+```ts
+const confirm = page.getByRole("alertdialog").getByRole("button", { name: "Delete" });
+await expect(confirm).toBeVisible();
+await confirm.press("Enter");
+```
+
+Do not reach for `click({ force: true })`. It only skips Playwright's stability check, and the click can still miss.
+
 ## 1.12.0: `DateField` / `DatePicker` field chrome moved to `Field.Root`
 
 **Applies to:** apps passing `label`, `description`, `errorMessage`, or `hideTimeZone` to `DateField` or `DatePicker`.

package/skills/app-shell-patterns/references/pages/{detail.md → document-detail.md}

@@ -1,34 +1,11 @@
 ---
-slug: page/detail
-name: Detail Page
-category: page
+title: Document Detail Page
 description: The screen for a single record — its summary, its contents, the records around it, and the actions available on it
-requiredImports:
-  [
-    Layout,
-    DescriptionCard,
-    Card,
-    Table,
-    Badge,
-    Alert,
-    ActionPanel,
-    ActivityCard,
-    Grid,
-    MetricCard,
-    DocumentProgressCard,
-  ]
-tags: [detail, record, document, single-record, actions, related-records, two-column, line-items]
-do:
-  - A screen showing exactly one record — an order, a receipt, an invoice, a supplier, an item
-  - The record has a lifecycle someone moves it through, or other records created from it
-  - Someone reading the record needs to understand its current state, and may want to act on it
-dont:
-  - The screen shows a set of records — that is a collection
-  - The record is a row's worth of fields, better opened in a Sheet from the list it belongs to
-  - Creating a new record — that is a form; this pattern is for reading and amending one that already exists
 ---
 
-# page/detail
+<!-- GENERATED by docs-kit from docs-src/pages/document-detail.docs.outline.md — do not edit by hand. -->
+
+# Document Detail Page
 
 The screen for a **single record**. Two columns: the record itself on the left,
 and on the right the actions available on it plus the context that sits around
@@ -206,7 +183,7 @@ time, and the record is unblocked only once every one is released.
 ### 4. Line items
 
 `Card.Root` → `Card.Header` (title, plus a one-line description where the
-columns need explaining) → `Card.Content className="px-0!"` → `Table.Root`.
+columns need explaining) → `Card.Content padding="none"` → `Table.Root`.
 
 Fetch the line items with the record, sorted explicitly so the order is stable
 across reloads, and render them as a plain `Table`. For the typical document —
@@ -796,7 +773,7 @@ export default function PurchaseOrderDetailPage({
       would have been a link field on the summary instead. */}
       <Card.Root>
         <Card.Header title="Source requisitions" />
-        <Card.Content className="px-0!">
+        <Card.Content padding="none">
           <Table.Root>
             <Table.Header>
               <Table.Row>
@@ -831,7 +808,7 @@ export default function PurchaseOrderDetailPage({
       enough to page. No container padding; the cells inset themselves. */}
       <Card.Root>
         <Card.Header title="Line items" />
-        <Card.Content className="px-0!">
+        <Card.Content padding="none">
           {order.lineItems.length === 0 ? (
             <p className="px-6 text-sm text-muted-foreground">No line items on this order.</p>
           ) : (
@@ -898,7 +875,7 @@ export default function PurchaseOrderDetailPage({
       relationship is possible, so the reader learns it exists. */}
       <Card.Root>
         <Card.Header title="Goods receipts" />
-        <Card.Content className="px-0!">
+        <Card.Content padding="none">
           {order.goodsReceipts.length === 0 ? (
             <p className="px-6 text-sm text-muted-foreground">
               No goods receipts linked to this order.
@@ -1020,7 +997,7 @@ export default function PurchaseOrderDetailPage({
                   title="Journal entry"
                   description="Booked when this order was posted."
                 />
-                <Card.Content className="px-0!">
+                <Card.Content padding="none">
                   <Table.Root>
                     <Table.Header>
                       <Table.Row>
@@ -1119,7 +1096,7 @@ enforced across every detail screen once settled.
 ## Constraints
 
 - **Every main-column section sits in a `Card.Root`** — except `DescriptionCard`, which contains itself, and `Alert`, which is a banner. No bare `<div>` sections.
-- **A table in a card needs ONE geometry change, not two.** Zero the card's padding (`Card.Content className="px-0!"`, or drop `Card.Content`) and leave the table container alone. `Table.Head` and `Table.Cell` already inset their own first and last cells by 24px; padding on the table container stacks on top of that and pushes the first column 24px right of the card title.
+- **A table in a card goes in `Card.Content padding="none"`, and nothing else changes.** Don't drop `Card.Content` or zero its padding with a class instead: the prop also keeps row backgrounds inside the card's rounded corners and removes a nested `DataTable`'s own border. Leave the table container alone too. `Table.Head` and `Table.Cell` already inset their own first and last cells by 24px; padding on the table container stacks on top of that and pushes the first column 24px right of the card title.
 - **Bare `YYYY-MM-DD` dates must not use `type: "date"`.** `DescriptionCard` hands the value to `new Date(...)`, which reads a date-only string as UTC midnight and renders the previous day west of Greenwich. Pre-format those as text via `render`. Real timestamps keep `type: "date"`, with `emptyBehavior: "hide"` when nullable.
 - **`ActionPanel` is workflow-only.** No navigation, no "view related record" — those are links in the cards that hold them.
 - **Never rely on a query cap to bound the line-items table.** If the cap can be reached, page the lines.

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

@@ -1,20 +1,11 @@
 ---
-slug: pattern/form/composer
-name: Composer
-category: pattern
-subcategory: form
+title: Composer
 description: Free-text composer — a multi-line input above a trailing action row, for notes, replies, and comments submitted in place
-requiredImports: [Card, Textarea, Button, Checkbox]
-tags: [composer, textarea, note, reply, comment, actions, discard, send]
-do:
-  - A free-text box the user fills and submits in place — add a note, reply on a thread, leave a comment, give a rejection reason
-  - The prose IS the interaction; any other controls only qualify how the text is submitted
-dont:
-  - The text is one field among many on a record form — use form/modal, form/single-page or form/sectioned with a Textarea field
-  - A chat input where Enter sends and there is no Discard — use the `AIChat` component instead
 ---
 
-# pattern/form/composer
+<!-- GENERATED by docs-kit from docs-src/patterns/form-composer.docs.outline.md — do not edit by hand. -->
+
+# Composer
 
 ## When to Use
 
@@ -60,35 +51,36 @@ Leave it empty and the buttons still sit correctly at the right; `justify-betwee
 
 ## Page Implementation
 
-```tsx
-/* pattern: form/composer */
-import { useState } from "react";
-import { Button, Card, Checkbox, Textarea } from "@tailor-platform/app-shell";
-
-type Props = {
-  onSubmit: (body: string, internal: boolean) => void;
-  submitting?: boolean;
-};
+<example-preview name="form-composer"></example-preview>
 
-export default function Composer({ onSubmit, submitting = false }: Props) {
+```tsx
+function FormComposer() {
   const [body, setBody] = useState("");
   const [internal, setInternal] = useState(false);
+  const [errors, setErrors] = useState<Record<string, string>>({});
+
+  const handleSubmit = () => {
+    window.alert(`Sending ${internal ? "internal note" : "reply"}: ${body}`);
+    setErrors({});
+    setBody("");
+  };
 
   return (
     <Card.Root>
       <Card.Content>
-        <div className="space-y-3">
-          <Textarea
-            aria-label="Reply"
-            value={body}
-            onChange={(e) => setBody(e.target.value)}
-            placeholder={internal ? "Internal context for teammates…" : "Reply to customer…"}
-            rows={4}
-          />
+        <Form noValidate errors={errors} onFormSubmit={handleSubmit} className="space-y-3">
+          <Field.Root name="body">
+            <Field.Label className="sr-only">Reply</Field.Label>
+            <Textarea
+              required
+              rows={4}
+              value={body}
+              onChange={(event) => setBody(event.target.value)}
+              placeholder={internal ? "Internal context for teammates…" : "Reply to customer…"}
+            />
+            <Field.Error />
+          </Field.Root>
           <div className="flex items-center justify-between gap-2">
-            {/* Options slot — 0..N controls that qualify the submission. An
-                internal-note toggle here; swap for an attachment button, a
-                visibility Select, a template picker, or drop it entirely. */}
             <div className="flex min-w-0 items-center gap-2">
               <Checkbox
                 label="Internal note (not sent to customer)"
@@ -96,39 +88,43 @@ export default function Composer({ onSubmit, submitting = false }: Props) {
                 onCheckedChange={setInternal}
               />
             </div>
-            {/* Action slot — fixed shape: optional ghost Discard, then exactly
-                one primary submit. Never more than one primary. */}
             <div className="flex shrink-0 gap-2">
               <Button
+                type="button"
                 variant="ghost"
-                onClick={() => setBody("")}
-                disabled={body.length === 0 || submitting}
+                onClick={() => {
+                  setBody("");
+                  setErrors({});
+                }}
+                disabled={body.length === 0}
               >
                 Discard
               </Button>
-              <Button
-                onClick={() => onSubmit(body, internal)}
-                disabled={body.trim().length === 0 || submitting}
-              >
-                {submitting ? "Sending…" : "Send"}
+              <Button type="submit" disabled={body.trim().length === 0}>
+                Send
               </Button>
             </div>
           </div>
-        </div>
+        </Form>
       </Card.Content>
     </Card.Root>
   );
 }
 ```
 
+<!-- source: composer.tsx -->
+
 ## Constraints
 
 - The body control is `Textarea`, never `Input` — `Input` is locked to `h-9` and clips prose to one 36px line.
 - Size the body with `rows` (3–5 is the usual range). Do not override its height with classes: `astw:` is internal to AppShell, and `Textarea`'s supported sizing API is `rows`.
-- The `Textarea` needs an accessible name. There is usually no visible label in a composer, so pass `aria-label`; a placeholder is not a label.
+- The `Textarea` needs an accessible name. There is usually no visible label in a composer, so use a `sr-only` `Field.Label`; a placeholder is not a label. Prefer this over `aria-label` — the `Field.Root` is already there, and a real label keeps the error and description wiring available.
 - One primary `Button` in the action row. Discard is `ghost`, and any left-side action is `ghost` too.
 - The action row is one row at every width — the left side shrinks, the buttons do not wrap under the body.
 - Disable the submit on empty or whitespace-only input, and disable both buttons while `submitting`.
+- The composer is a `Form`, not a bare widget. The body sits in a `Field.Root name="…"`, Send is `type="submit"`, and Discard is `type="button"` — inside a `<Form>` an untyped `<button>` defaults to `submit`.
+- Keep the body **controlled**. It is read during render to gate Send and to swap the placeholder, which a submit-time handler cannot do. This is the one `form/*` pattern where field state is load-bearing rather than redundant.
+- Route server rejections (moderation, rate limit, thread closed) through `Form`'s `errors` prop into `Field.Error`, not a toast. A composer that can be rejected needs somewhere for the reason to land next to the text the user still has.
 - Wrap the composer in `Card.Root` when it sits among other cards (a detail page, the end of a thread). A composer that is already inside a `Sheet` or `Dialog` body does not need its own card.
 
 ## Anti-patterns
@@ -139,4 +135,6 @@ export default function Composer({ onSubmit, submitting = false }: Props) {
 - The action row stacked above the `Textarea`, or the buttons wrapped onto their own line — the composer stops reading as one unit.
 - A left-side toggle that silently changes what the submit does without changing the submit's own affordance — if "internal note" changes the destination, the placeholder (or the label) should say so.
 - Submit enabled on an empty body, so the user can post nothing.
+- A bare `<div>` of controls with an `onClick` submit — no `Form`, so a server rejection has nowhere to go and the body has no field identity.
+- Clearing the body on a _failed_ submit — the user loses what they wrote. Clear only after the submit succeeds.
 - A body so tall (`rows={12}`) that the action row falls below the fold — the composer stops reading as one unit.

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

@@ -1,23 +1,11 @@
 ---
-slug: pattern/form/modal
-name: Modal Form
-category: pattern
-subcategory: form
+title: Modal Form
 description: Default form pattern for Create/Edit — keeps user in context on the parent screen
-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
-  - Inline add of a related entity from another screen (add address from order detail)
-  - Quick configuration changes and single-purpose forms (rename, change status)
-  - Any form the design hasn't explicitly called out as a full-page routed screen
-dont:
-  - Design explicitly calls for a full-page (non-overlay) routed Create or Edit
-  - Form is complex with 15+ fields or multiple grouped sections — use form/sectioned
-  - Multi-stage flow with per-step validation — use form/wizard
 ---
 
-# pattern/form/modal
+<!-- GENERATED by docs-kit from docs-src/patterns/form-modal.docs.outline.md — do not edit by hand. -->
+
+# Modal Form
 
 ## When to Use
 
@@ -28,21 +16,10 @@ dont:
 
 ## Page Implementation
 
-```tsx
-/* pattern: form/modal */
-import { Button, Dialog, Field, Form } from "@tailor-platform/app-shell";
-
-type Address = {
-  label: string;
-  street: string;
-  city: string;
-};
+<example-preview name="modal-form"></example-preview>
 
-type Props = {
-  onSave: (data: Address) => void;
-};
-
-export default function ModalForm({ onSave }: Props) {
+```tsx
+function ModalForm() {
   return (
     <Dialog.Root>
       <Dialog.Trigger render={<Button />}>Add address</Dialog.Trigger>
@@ -52,15 +29,17 @@ export default function ModalForm({ onSave }: Props) {
           <Dialog.Description>Add a shipping address to this order.</Dialog.Description>
         </Dialog.Header>
         {/*
-         * `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.
+         * `onFormSubmit` fires only after validation passes and receives the
+         * registered field values — no `<form onSubmit>` + `new FormData(...)`.
          */}
-        <Form<Address> noValidate onFormSubmit={(values) => onSave(values)}>
-          <div className="space-y-4 py-4">
+        <Form<AddressDraft>
+          noValidate
+          onFormSubmit={(values) => window.alert(`Saving ${values.label}`)}
+        >
+          <div className="flex flex-col gap-4 py-4">
             <Field.Root name="label">
               <Field.Label>Label</Field.Label>
-              <Field.Control required placeholder="Head office" />
+              <Field.Control required />
               <Field.Error match="valueMissing">Label is required.</Field.Error>
             </Field.Root>
             <Field.Root name="street">
@@ -75,7 +54,7 @@ export default function ModalForm({ onSave }: Props) {
             </Field.Root>
           </div>
           <Dialog.Footer>
-            <Dialog.Close render={<Button variant="ghost" />}>Cancel</Dialog.Close>
+            <Dialog.Close render={<Button type="button" variant="ghost" />}>Cancel</Dialog.Close>
             <Button type="submit">Save</Button>
           </Dialog.Footer>
         </Form>
@@ -87,82 +66,47 @@ export default function ModalForm({ onSave }: Props) {
 
 ## Route-driven Variant
 
-```tsx
-/* pattern: form/modal (route-driven variant) */
-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: ProductDraft) => Promise<{ errors?: Record<string, string> }>;
-};
-
-/**
- * Route-driven modal: the form has its own URL but renders as a popup
- * over the list. Both `/products` and `/products/create` render this
- * same component — the parent list stays visible underneath.
- */
-export default function ModalFormRouted({
-  isCreateOpen,
-  onNavigateToCreate,
-  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();
-  };
+The route-driven variant renders the same component at both the parent path and the `create` / `edit` path, with `onOpenChange` navigating back so the URL stays in sync.
 
+<example-preview name="modal-form-routed"></example-preview>
+
+```tsx
+function ModalFormRouted() {
+  const [isCreateOpen, setCreateOpen] = useState(false);
   return (
     <Layout>
       <Layout.Header
         title="Products"
         actions={[
-          <Button key="create" onClick={onNavigateToCreate}>
+          <Button key="create" onClick={() => setCreateOpen(true)}>
             Create
           </Button>,
         ]}
       />
       <Layout.Column>{/* products list — see list/dense-scan */}</Layout.Column>
 
-      <Dialog.Root
-        open={isCreateOpen}
-        onOpenChange={(open) => {
-          if (!open) onNavigateToList();
-        }}
-      >
+      <Dialog.Root open={isCreateOpen} onOpenChange={setCreateOpen}>
         <Dialog.Content>
           <Dialog.Header>
             <Dialog.Title>Create product</Dialog.Title>
           </Dialog.Header>
-          <Form<ProductDraft> noValidate errors={errors} onFormSubmit={handleSubmit}>
-            <div className="space-y-4 py-4">
+          <Form<ProductDraft>
+            noValidate
+            onFormSubmit={(values) => {
+              window.alert(`Saving ${values.name}`);
+              setCreateOpen(false);
+            }}
+          >
+            <div className="flex flex-col gap-4 py-4">
               <Field.Root name="name">
                 <Field.Label>Name</Field.Label>
                 <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.Error match="valueMissing">Name is required.</Field.Error>
               </Field.Root>
             </div>
             <Dialog.Footer>
-              <Button type="button" variant="ghost" onClick={onNavigateToList}>
+              {/* Inside a `<Form>` an untyped button submits — Cancel must be `type="button"`. */}
+              <Button type="button" variant="ghost" onClick={() => setCreateOpen(false)}>
                 Cancel
               </Button>
               <Button type="submit">Save</Button>
@@ -194,7 +138,8 @@ 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.
+  `<form onSubmit>` + `new FormData(...)` — that bypasses `Form`'s field 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

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

@@ -1,21 +1,11 @@
 ---
-slug: pattern/form/sectioned
-name: Sectioned Form
-category: pattern
-subcategory: form
+title: Sectioned Form
 description: Complex form with 15+ fields organized into named fieldset sections
-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)
-  - Configure-style settings pages with named boundaries
-dont:
-  - Simple Create/Edit — use form/modal (the default)
-  - Routed Create/Edit at moderate size with no grouping — use form/single-page
-  - Step-gated validation across stages — use form/wizard
 ---
 
-# pattern/form/sectioned
+<!-- GENERATED by docs-kit from docs-src/patterns/form-sectioned.docs.outline.md — do not edit by hand. -->
+
+# Sectioned Form
 
 ## When to Use
 
@@ -24,32 +14,14 @@ dont:
 
 ## Page Implementation
 
-```tsx
-/* pattern: form/sectioned */
-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" },
-];
+<example-preview name="form-sectioned"></example-preview>
 
-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, unknown>) => void;
-  onCancel: () => void;
-};
+```tsx
+function FormSectioned() {
+  const onSave = (values: Record<string, unknown>) =>
+    window.alert(`Saving ${Object.keys(values).length} fields`);
+  const onCancel = () => {};
 
-export default function SectionedForm({ onSave, onCancel }: Props) {
   return (
     <Layout>
       <Layout.Header
@@ -163,6 +135,8 @@ export default function SectionedForm({ onSave, onCancel }: Props) {
 }
 ```
 
+<!-- source: sectioned-form.tsx -->
+
 ## Constraints
 
 - Max ~6 sections — more than that is too hard to scan; promote to `form/wizard`

package/skills/app-shell-patterns/references/patterns/form-single-page.md

@@ -1,21 +1,11 @@
 ---
-slug: pattern/form/single-page
-name: Single Page Form
-category: pattern
-subcategory: form
+title: Single Page Form
 description: Routed full-page form for moderate field count (6-15) without natural sectioning
-requiredImports: [Layout, Form, Field, Textarea, Select, Button]
-tags: [form, page, create, edit, routed]
-do:
-  - A routed Create or Edit page that the design has explicitly called out (e.g. /orders/create)
-  - Moderate field count (roughly 6-15) without natural sectioning, completed in one pass
-dont:
-  - Default Create/Edit with no explicit routing requirement — use form/modal (the default)
-  - 15+ fields or grouped concerns — use form/sectioned
-  - Multi-stage flow — use form/wizard
 ---
 
-# pattern/form/single-page
+<!-- GENERATED by docs-kit from docs-src/patterns/form-single-page.docs.outline.md — do not edit by hand. -->
+
+# Single Page Form
 
 ## When to Use
 
@@ -24,26 +14,13 @@ dont:
 
 ## Page Implementation
 
-```tsx
-/* pattern: form/single-page */
-import { Button, Field, Form, Textarea, Layout, Select } from "@tailor-platform/app-shell";
-
-const CATEGORIES = ["Electronics", "Furniture", "Clothing", "Food"];
+<example-preview name="form-single-page"></example-preview>
 
-type ProductDraft = {
-  name: string;
-  sku: string;
-  category: string;
-  price: string;
-  description: string;
-};
-
-type Props = {
-  onSave: (data: ProductDraft) => void;
-  onCancel: () => void;
-};
+```tsx
+function FormSinglePage() {
+  const onSave = (values: ProductDraft) => window.alert(`Saving ${values.name}`);
+  const onCancel = () => {};
 
-export default function SinglePageForm({ onSave, onCancel }: Props) {
   return (
     <Layout>
       {/*
@@ -107,6 +84,8 @@ export default function SinglePageForm({ onSave, onCancel }: Props) {
 }
 ```
 
+<!-- source: single-page-form.tsx -->
+
 ## Constraints
 
 - Single column full width below 1024px; single column max-w constrained at 1024–1280px