diff --git a/.agents/skills/webjs/references/ui-kit.md b/.agents/skills/webjs/references/ui-kit.md
index ccebddb9e..bc6958bd2 100644
--- a/.agents/skills/webjs/references/ui-kit.md
+++ b/.agents/skills/webjs/references/ui-kit.md
@@ -81,9 +81,9 @@ So the loop is: `add` the component, then query `ui <name>` (MCP) or
 ## Inventory (run `npx webjsdev ui list` or the MCP `ui` tool for the authoritative, current set)
 
 **Tier 1 (class helpers):** accordion, alert, aspect-ratio, avatar, badge,
-breadcrumb, button, card, checkbox, collapsible, input, kbd, label,
-native-select, pagination, popover, progress, radio-group, separator, skeleton,
-switch, table, textarea.
+breadcrumb, button, card, checkbox, collapsible, empty, field, input, kbd,
+label, native-select, pagination, popover, progress, radio-group, separator,
+skeleton, spinner, switch, table, textarea.
 
 **Tier 2 (custom elements, own their ARIA):** alert-dialog, dialog,
 dropdown-menu, hover-card, sonner, tabs, tooltip, plus toggle and toggle-group
@@ -93,6 +93,17 @@ dropdown-menu, hover-card, sonner, tabs, tooltip, plus toggle and toggle-group
 
 - A helper is a function, so compose it: `class=${buttonClass({ variant: 'outline' })}`.
   The unquoted `${...}` is a normal `html` attribute hole.
+- The three states a screen owes its user each have a primitive, so do not hand-roll
+  them. A list or table with no rows renders `empty` (title as a real heading, a
+  description saying what to do next, and the create action). A form field is
+  `field` (`fieldClass()` holding a `<label for>`, the control, `fieldDescriptionClass()`
+  text, and on a validation error `data-invalid="true"`, `aria-invalid` on the control,
+  and a `fieldErrorClass()` message with `role="alert"` whose id the control's
+  `aria-describedby` lists, with the typed value kept). A pending save puts
+  `spinner({ decorative: true })` in a `disabled` + `aria-busy="true"` submit button
+  that keeps its text. The `fieldClass` / `fieldLabelClass` in `components/ui/field.ts`
+  are not the same-named rhythm helpers in `lib/utils/cn.ts`; import each from its own
+  module and alias one if a file needs both.
 - Tier-1 helpers assume the design tokens exist; if a component paints unstyled,
   the tokens are missing (re-run `npx webjsdev ui init` or let `add` self-heal them).
 - Custom elements are display-only-safe at SSR and hydrate in the browser, the
diff --git a/README.md b/README.md
index 5f7c24cf1..581f2c70a 100644
--- a/README.md
+++ b/README.md
@@ -58,7 +58,7 @@ older, unrelated Java framework also used the name WebJS.
 - **Metadata routes are functions rather than static files.** `sitemap.ts`, `robots.ts`, `manifest.ts`, `icon.ts`, and `opengraph-image.ts` generate SEO and PWA metadata dynamically.
 - **REST endpoints come from `route.ts`.** Expose a server action over HTTP by importing it into a `route.ts` handler, or reach for the one-line `route(action)` adapter from `@webjsdev/server`. Input validation is optional.
 - **WebJs is production ready.** CSRF protection, gzip and brotli, HTTP/2, 103 Early Hints, CSP nonces, modulepreload, rate limiting, health probes, graceful shutdown, and streaming Suspense all ship with the framework.
-- **WebJs UI is the matching AI-first component library.** Its 32 primitives at [webjs.dev/ui](https://webjs.dev/ui) are written for AI agents, in two tiers: pure class-helper functions (`buttonClass`, `cardClass`, `inputClass`) for visual primitives, plus a small set of stateful custom elements (`<ui-dialog>`, `<ui-tabs>`, `<ui-popover>`) for the cases where state matters. Running `webjs ui add button card dialog` copies the source into your project, so you own it and can edit it. It ships as a hard dependency of `@webjsdev/cli`, so a WebJs app that installed the CLI needs no separate install, and a WebJs app that skipped the global install runs `npm install -D @webjsdev/ui` and `npm install @webjsdev/core` first, then `npx webjsui init` and `npx webjsui add button card dialog`.
+- **WebJs UI is the matching AI-first component library.** Its 35 primitives at [webjs.dev/ui](https://webjs.dev/ui) are written for AI agents, in two tiers: pure class-helper functions (`buttonClass`, `cardClass`, `inputClass`) for visual primitives, plus a small set of stateful custom elements (`<ui-dialog>`, `<ui-tabs>`, `<ui-popover>`) for the cases where state matters. Running `webjs ui add button card dialog` copies the source into your project, so you own it and can edit it. It ships as a hard dependency of `@webjsdev/cli`, so a WebJs app that installed the CLI needs no separate install, and a WebJs app that skipped the global install runs `npm install -D @webjsdev/ui` and `npm install @webjsdev/core` first, then `npx webjsui init` and `npx webjsui add button card dialog`.
 
 ## Quickstart
 
diff --git a/packages/ui/AGENTS.md b/packages/ui/AGENTS.md
index 5f1486d5b..cab957c26 100644
--- a/packages/ui/AGENTS.md
+++ b/packages/ui/AGENTS.md
@@ -1,7 +1,7 @@
 # AGENTS.md : @webjsdev/ui
 
 The webjs **AI-first component library + CLI**, `webjsui init` / `add` /
-`list` / `view` / `diff` / `info` / `build` / `lint`. Ships 32 primitives across two
+`list` / `view` / `diff` / `info` / `build` / `lint`. Ships 35 primitives across two
 tiers: class-helper functions for visual components, custom elements only
 where state matters. Variant names, sizes, and data-attribute conventions
 mirror shadcn so existing shadcn knowledge transfers directly.
@@ -161,7 +161,7 @@ This trap exists ONLY in the marketing site. Scaffolded user apps,
 `examples/blog`, and every other WebJs app keep `components/ui/` as normal
 tracked source, the standard shadcn "you own it" pattern.
 
-## v1 component inventory (32 components)
+## Component inventory (35 components)
 
 | Tier | Component | Surface |
 |---|---|---|
@@ -177,6 +177,9 @@ tracked source, the standard shadcn "you own it" pattern.
 | 1a | `avatar` | `avatarClass`, `avatarImageClass`, `avatarFallbackClass`, `avatarBadgeClass`, `avatarGroupClass`, `avatarGroupCountClass` |
 | 1a | `separator` | `separatorClass({ orientation })` |
 | 1a | `skeleton` | `skeletonClass` |
+| 1a | `spinner` | `spinnerClass`, plus `spinner({ class, label, decorative })`, which returns an `html` inline SVG (the Lucide loader-circle path) with `role="status"` + `aria-label="Loading"`. It imports `html` from `@webjsdev/core` but registers no element, so it stays Tier 1. |
+| 1a | `empty` | `emptyClass`, `emptyHeaderClass`, `emptyMediaClass({ variant })`, `emptyTitleClass`, `emptyDescriptionClass`, `emptyContentClass`. The root has `border-dashed` but no width (shadcn parity), so add `border` for the outline. |
+| 1a | `field` | `fieldSetClass`, `fieldLegendClass({ variant })`, `fieldGroupClass`, `fieldClass({ orientation })`, `fieldContentClass`, `fieldLabelClass`, `fieldTitleClass`, `fieldDescriptionClass`, `fieldErrorClass`, `fieldSeparatorClass`, `fieldSeparatorContentClass`. Invalid state is `data-invalid="true"` on the field plus `aria-invalid` on the control. `fieldClass` and `fieldLabelClass` share their names with the older rhythm helpers in `lib/utils.ts` (copied to `lib/utils/cn.ts`); both sets keep working from their own modules, so a file needing both aliases one. |
 | 1a | `aspect-ratio` | `aspectRatioClass`, use Tailwind `aspect-[16/9]` directly |
 | 1a | `kbd` | `kbdClass`, `kbdGroupClass` |
 | 1a | `table` | `tableContainerClass`, `tableClass`, `tableHeaderClass`, `tableBodyClass`, `tableFooterClass`, `tableRowClass`, `tableHeadClass`, `tableCellClass`, `tableCaptionClass` |
@@ -268,6 +271,9 @@ obligations:
 - `alert`: choose `role="alert"` (urgent) or `role="status"` (polite).
 - `separator`: `role="separator"` + `aria-orientation`, or `role="none"` when decorative.
 - `skeleton`: `aria-hidden="true"` (or `aria-busy` on the region), since it is a placeholder.
+- `spinner`: `spinner()` is a named `role="status"`. Inside a busy button, mark the BUTTON `disabled` + `aria-busy="true"`, keep its visible text, and render `spinner({ decorative: true })` so a second live status is not nested in the button's name.
+- `empty`: a real heading for `emptyTitleClass()`, `aria-hidden` on the decorative media, and `role="status"` on the root only when the empty state answers a user action (a search or filter that matched nothing).
+- `field`: a real `<label for>` per control, `aria-describedby` listing the description id and, when invalid, the error id (only ids that exist), `aria-invalid` on the control, `role="alert"` on the error, and the typed values kept when the server re-renders the form with an error. A radio or checkbox set goes in a `<fieldset>` named by its `<legend>`.
 - `avatar`: an `alt` that names the person, plus the text fallback.
 - `table`: `scope="col"` / `scope="row"` on header cells, and a `<caption>`.
 - `pagination` / `breadcrumb`: a labelled `<nav>`, `aria-current="page"`, and hidden separators / icon-only control names.
diff --git a/packages/ui/README.md b/packages/ui/README.md
index 53a65099d..9948aac9a 100644
--- a/packages/ui/README.md
+++ b/packages/ui/README.md
@@ -8,7 +8,8 @@ function calls, not for a layered React abstraction over every primitive:
 
 - **Tier 1, class-helper functions** (`buttonClass`, `cardClass`,
   `inputClass`, `labelClass`, `alertClass`, `popoverContentClass`,
-  `accordionItemClass`, `collapsibleTriggerClass`, …). Pure functions that
+  `accordionItemClass`, `collapsibleTriggerClass`, `emptyClass`,
+  `fieldClass`, `fieldErrorClass`, `spinnerClass`, …). Pure functions that
   return Tailwind class strings. You spread them onto raw native elements
  , including `<button class=${buttonClass({ variant: 'outline' })}>`,
   `<details name="faq" class=${accordionItemClass()}>`, and
@@ -55,8 +56,9 @@ Tier-1 class helpers return only classes, so the semantic element and ARIA are
 yours to supply. Each one's JSDoc carries an `A11y (required for accessible
 output)` block stating exactly what to add: a name on an icon-only button, a
 role on an alert, `scope` on table headers, `alt` on an avatar image, a
-labelled `<nav>` with `aria-current="page"` on pagination and breadcrumb, and
-so on. Follow that block and the markup is fully accessible.
+labelled `<nav>` with `aria-current="page"` on pagination and breadcrumb,
+`aria-describedby` from a control to its field description and error, a
+disabled `aria-busy` button around a decorative spinner, and so on. Follow that block and the markup is fully accessible.
 
 ## Install
 
diff --git a/packages/ui/packages/registry/components/empty.ts b/packages/ui/packages/registry/components/empty.ts
new file mode 100644
index 000000000..a98604eba
--- /dev/null
+++ b/packages/ui/packages/registry/components/empty.ts
@@ -0,0 +1,88 @@
+/**
+ * Empty: the empty state for a list, table, search result, or any region with
+ * nothing to show yet. Tier-1 class helpers; compose with `<div>` (or a heading
+ * and paragraph) for each subpart.
+ *
+ * shadcn parity:
+ *   Empty                               → emptyClass()
+ *   EmptyHeader                         → emptyHeaderClass()
+ *   EmptyMedia (variant: default | icon) → emptyMediaClass({ variant })
+ *   EmptyTitle                          → emptyTitleClass()
+ *   EmptyDescription                    → emptyDescriptionClass()
+ *   EmptyContent                        → emptyContentClass()
+ *
+ * The root carries `border-dashed` but no border width, exactly as shadcn
+ * does, so it renders borderless by default. Add `border` beside it for the
+ * dashed outline: `class=${cn(emptyClass(), 'border')}`.
+ *
+ * Design tokens used: --muted, --foreground, --muted-foreground, --primary,
+ * --border.
+ *
+ * A11y (required for accessible output):
+ *   Use a REAL HEADING for `emptyTitleClass()`, at the level the surrounding
+ *   document wants (`<h2>` under the page `<h1>`, `<h3>` inside a section). The
+ *   empty state usually replaces the list a heading already introduces, so the
+ *   title is often a level below it.
+ *   The media is decorative: put `aria-hidden="true"` on the icon or
+ *   illustration, since the title already says what is missing.
+ *   The action in `emptyContentClass()` is a real `<a href>` (navigates, e.g.
+ *   to the create page) or a real `<button>` (acts in place). A create action
+ *   that is a form submit keeps working without JavaScript.
+ *   When the empty state appears in response to a user action (a search or a
+ *   filter that matched nothing), put `role="status"` on the root so the change
+ *   is announced; a page that simply loads empty needs no role.
+ *
+ * @example
+ * ```html
+ * <div class=${cn(emptyClass(), 'border')}>
+ *   <div class=${emptyHeaderClass()}>
+ *     <div class=${emptyMediaClass({ variant: 'icon' })}>
+ *       <svg aria-hidden="true" xmlns="http://www.w3.org/2000/svg" viewBox="0 0 24 24" fill="none" stroke="currentColor" stroke-width="2" stroke-linecap="round" stroke-linejoin="round"><path d="M22 12h-6l-2 3h-4l-2-3H2"/><path d="M5.45 5.11 2 12v6a2 2 0 0 0 2 2h16a2 2 0 0 0 2-2v-6l-3.45-6.89A2 2 0 0 0 16.76 4H7.24a2 2 0 0 0-1.79 1.11z"/></svg>
+ *     </div>
+ *     <h3 class=${emptyTitleClass()}>No projects yet</h3>
+ *     <p class=${emptyDescriptionClass()}>Create your first project to get started.</p>
+ *   </div>
+ *   <div class=${emptyContentClass()}>
+ *     <a class=${buttonClass()} href="/projects/new">Create project</a>
+ *   </div>
+ * </div>
+ * ```
+ */
+
+const MEDIA_BASE =
+  'mb-2 flex shrink-0 items-center justify-center [&_svg]:pointer-events-none [&_svg]:shrink-0';
+
+const MEDIA_VARIANTS = {
+  default: 'bg-transparent',
+  icon: "flex size-10 shrink-0 items-center justify-center rounded-lg bg-muted text-foreground [&_svg:not([class*='size-'])]:size-6",
+} as const;
+
+export type EmptyMediaVariant = keyof typeof MEDIA_VARIANTS;
+
+/** Empty root: centred column with generous padding. Add `border` for the dashed outline. */
+export const emptyClass = (): string =>
+  'flex min-w-0 flex-1 flex-col items-center justify-center gap-6 rounded-lg border-dashed p-6 text-center text-balance md:p-12';
+
+/** Empty header: groups the media, title, and description. */
+export const emptyHeaderClass = (): string =>
+  'flex max-w-sm flex-col items-center gap-2 text-center';
+
+/**
+ * Empty media: the icon or illustration above the title. `icon` puts the icon
+ * on a muted tile; `default` leaves it bare (for an avatar or an illustration).
+ * Set `data-variant="<variant>"` on the same element for shadcn parity.
+ */
+export function emptyMediaClass(opts: { variant?: EmptyMediaVariant } = {}): string {
+  return MEDIA_BASE + ' ' + MEDIA_VARIANTS[opts.variant ?? 'default'];
+}
+
+/** Empty title: what is missing, in a few words. */
+export const emptyTitleClass = (): string => 'text-lg font-medium tracking-tight';
+
+/** Empty description: the muted line under the title, saying what to do next. */
+export const emptyDescriptionClass = (): string =>
+  'text-sm/relaxed text-muted-foreground [&>a]:underline [&>a]:underline-offset-4 [&>a:hover]:text-primary';
+
+/** Empty content: the row for the action button(s) or a small form. */
+export const emptyContentClass = (): string =>
+  'flex w-full max-w-sm min-w-0 flex-col items-center gap-4 text-sm text-balance';
diff --git a/packages/ui/packages/registry/components/field.ts b/packages/ui/packages/registry/components/field.ts
new file mode 100644
index 000000000..0180b11ae
--- /dev/null
+++ b/packages/ui/packages/registry/components/field.ts
@@ -0,0 +1,163 @@
+/**
+ * Field: the layout system for a form, a label, a control, its helper text,
+ * and its error message, plus the fieldset, legend, and group that hold many
+ * fields. Tier-1 class helpers; compose with the native elements (`<fieldset>`,
+ * `<legend>`, `<label>`, `<p>`) and the kit's control helpers
+ * (`inputClass()`, `textareaClass()`, `checkboxClass()`, and the rest).
+ *
+ * shadcn parity:
+ *   FieldSet                             → fieldSetClass()
+ *   FieldLegend (variant: legend | label) → fieldLegendClass({ variant })
+ *   FieldGroup                           → fieldGroupClass()
+ *   Field (orientation: vertical | horizontal | responsive) → fieldClass({ orientation })
+ *   FieldContent                         → fieldContentClass()
+ *   FieldLabel                           → fieldLabelClass()
+ *   FieldTitle                           → fieldTitleClass()
+ *   FieldDescription                     → fieldDescriptionClass()
+ *   FieldError                           → fieldErrorClass()
+ *   FieldSeparator                       → fieldSeparatorClass() + fieldSeparatorContentClass()
+ *
+ * Set the shadcn data attributes on the same elements, because the sibling and
+ * group rules key on them: `data-slot="field"` + `data-orientation` on the
+ * field, `data-slot="field-label"` on the label, `data-slot="field-content"`
+ * on the content wrapper, `data-variant` on the legend, and
+ * `data-slot="field-group"` on the group (the `responsive` orientation reads
+ * the group's container width).
+ *
+ * Invalid state: put `data-invalid="true"` on the field, which turns the
+ * field's text destructive (`data-[invalid=true]:text-destructive`), and
+ * `aria-invalid="true"` on the control, which the control helpers style.
+ * Disabled state: `data-disabled="true"` on the field fades its label.
+ *
+ * Not the same as the `fieldClass()` / `fieldLabelClass()` in the `cn()`
+ * helper module (`lib/utils/cn.ts`), which are the older single-field rhythm
+ * helpers (`grid gap-2`). Both keep working. Import each from its own module,
+ * and alias one (`import { fieldClass as fieldStackClass } from ...`) if a file
+ * needs both.
+ *
+ * Design tokens used: --destructive, --muted-foreground, --primary,
+ * --background, --border.
+ *
+ * A11y (required for accessible output):
+ *   Every control has a real `<label for>` (`fieldLabelClass()`), never a
+ *   placeholder alone. A field carries `role="group"` (as shadcn's does) only
+ *   when it holds more than one control; a single-control field needs no role.
+ *   Wire the helper and error text to the control with `aria-describedby`,
+ *   listing the description id and, when invalid, the error id
+ *   (`aria-describedby="email-desc email-error"`). Point it only at ids that
+ *   EXIST on the page, so render the error element only when there is an error.
+ *   On a server validation error, re-render the form with the typed values
+ *   kept (`value=${values.email}`), `data-invalid="true"` on the field,
+ *   `aria-invalid="true"` on the control, and the message in
+ *   `fieldErrorClass()` with `role="alert"`, so the user fixes the one field
+ *   instead of retyping the form. Move focus to the first invalid control.
+ *   Group related controls (a radio set, a checkbox list) in a `<fieldset>`
+ *   with a `<legend>` (`fieldSetClass()` / `fieldLegendClass()`), which names
+ *   the group. A `fieldTitleClass()` element is NOT a label: use it for the
+ *   title inside a choice card whose `<label>` wraps the whole card.
+ *   A decorative separator gets `role="none"`; its text (`or`) stays readable.
+ *
+ * @example
+ * ```html
+ * <form method="post" class="w-full max-w-md">
+ *   <fieldset class=${fieldSetClass()}>
+ *     <legend class=${fieldLegendClass()} data-variant="legend">Profile</legend>
+ *     <p class=${fieldDescriptionClass()}>This is how others see you.</p>
+ *     <div class=${fieldGroupClass()} data-slot="field-group">
+ *       <div class=${fieldClass()} data-slot="field" data-orientation="vertical">
+ *         <label class=${fieldLabelClass()} data-slot="field-label" for="name">Name</label>
+ *         <input class=${inputClass()} id="name" name="name" value="Ada" aria-describedby="name-desc">
+ *         <p class=${fieldDescriptionClass()} id="name-desc">Shown on your public page.</p>
+ *       </div>
+ *       <div class=${fieldClass()} data-slot="field" data-orientation="vertical" data-invalid="true">
+ *         <label class=${fieldLabelClass()} data-slot="field-label" for="email">Email</label>
+ *         <input class=${inputClass()} id="email" name="email" type="email" value="ada@" aria-invalid="true" aria-describedby="email-error">
+ *         <div class=${fieldErrorClass()} id="email-error" role="alert">Enter a valid email address.</div>
+ *       </div>
+ *       <div class=${fieldSeparatorClass()} role="none"><span class=${fieldSeparatorContentClass()}>Notifications</span></div>
+ *       <div class=${fieldClass({ orientation: 'horizontal' })} data-slot="field" data-orientation="horizontal">
+ *         <input class=${checkboxClass()} data-slot="checkbox" type="checkbox" id="digest" name="digest">
+ *         <label class=${fieldLabelClass()} data-slot="field-label" for="digest">Send me a weekly digest</label>
+ *       </div>
+ *     </div>
+ *   </fieldset>
+ * </form>
+ * ```
+ */
+
+export type FieldLegendVariant = 'legend' | 'label';
+export type FieldOrientation = 'vertical' | 'horizontal' | 'responsive';
+
+const LEGEND_VARIANTS = {
+  legend: 'text-base',
+  label: 'text-sm',
+} as const;
+
+const ORIENTATIONS = {
+  vertical: 'flex-col [&>*]:w-full [&>.sr-only]:w-auto',
+  horizontal:
+    'flex-row items-center [&>[data-slot=field-label]]:flex-auto has-[>[data-slot=field-content]]:items-start has-[>[data-slot=field-content]]:[&>[type=checkbox],[type=radio]]:mt-px',
+  responsive:
+    'flex-col @md/field-group:flex-row @md/field-group:items-center [&>*]:w-full @md/field-group:[&>*]:w-auto [&>.sr-only]:w-auto @md/field-group:[&>[data-slot=field-label]]:flex-auto @md/field-group:has-[>[data-slot=field-content]]:items-start @md/field-group:has-[>[data-slot=field-content]]:[&>[type=checkbox],[type=radio]]:mt-px',
+} as const;
+
+/** Field set: a native `<fieldset>` holding a legend and a group of fields. */
+export const fieldSetClass = (): string =>
+  'flex flex-col gap-6 has-[>[data-slot=checkbox-group]]:gap-3 has-[>[data-slot=radio-group]]:gap-3';
+
+/**
+ * Field legend: the `<legend>` naming a field set. `legend` is section-sized,
+ * `label` matches a field label (for a radio or checkbox set). Set
+ * `data-variant="<variant>"` on the same element so a following description
+ * tightens its spacing.
+ */
+export function fieldLegendClass(opts: { variant?: FieldLegendVariant } = {}): string {
+  return 'mb-3 font-medium ' + LEGEND_VARIANTS[opts.variant ?? 'legend'];
+}
+
+/** Field group: stacks fields, and is the container `responsive` fields measure. */
+export const fieldGroupClass = (): string =>
+  'group/field-group @container/field-group flex w-full flex-col gap-7 data-[slot=checkbox-group]:gap-3 [&>[data-slot=field-group]]:gap-4';
+
+/**
+ * Field: one label + control + text unit. `vertical` stacks them, `horizontal`
+ * puts the control beside the label (checkbox, switch), and `responsive` stacks
+ * on a narrow group and goes side by side from the group's `md` width.
+ */
+export function fieldClass(opts: { orientation?: FieldOrientation } = {}): string {
+  return (
+    'group/field flex w-full gap-3 data-[invalid=true]:text-destructive ' +
+    ORIENTATIONS[opts.orientation ?? 'vertical']
+  );
+}
+
+/** Field content: wraps a label and description beside a horizontal control. */
+export const fieldContentClass = (): string =>
+  'group/field-content flex flex-1 flex-col gap-1.5 leading-snug';
+
+/** Field label: the `<label for>` of the control. Fades when the field is data-disabled. */
+export const fieldLabelClass = (): string =>
+  'group/field-label peer/field-label flex w-fit items-center gap-2 text-sm leading-snug font-medium select-none group-data-[disabled=true]/field:opacity-50 peer-disabled:cursor-not-allowed peer-disabled:opacity-50 has-[>[data-slot=field]]:w-full has-[>[data-slot=field]]:flex-col has-[>[data-slot=field]]:rounded-md has-[>[data-slot=field]]:border [&>*]:data-[slot=field]:p-4 has-checked:border-primary has-checked:bg-primary/5 dark:has-checked:bg-primary/10';
+
+/** Field title: label-styled text that is not a `<label>` (a choice card's heading). */
+export const fieldTitleClass = (): string =>
+  'flex w-fit items-center gap-2 text-sm leading-snug font-medium group-data-[disabled=true]/field:opacity-50';
+
+/** Field description: the muted helper text under (or beside) the control. */
+export const fieldDescriptionClass = (): string =>
+  'text-sm leading-normal font-normal text-muted-foreground group-has-[[data-orientation=horizontal]]/field:text-balance last:mt-0 nth-last-2:-mt-1 [[data-variant=legend]+&]:-mt-1.5 [&>a]:underline [&>a]:underline-offset-4 [&>a:hover]:text-primary';
+
+/** Field error: the inline validation message. Give it an id the control's aria-describedby lists. */
+export const fieldErrorClass = (): string => 'text-sm font-normal text-destructive';
+
+/**
+ * Field separator: a horizontal rule between fields, drawn by the element's own
+ * `::before`, with optional centred text in a `fieldSeparatorContentClass()`
+ * span.
+ */
+export const fieldSeparatorClass = (): string =>
+  'relative -my-2 h-5 text-sm group-data-[variant=outline]/field-group:-mb-2 before:absolute before:inset-x-0 before:top-1/2 before:h-px before:bg-border';
+
+/** Field separator content: the text on the separator line (`or`, a section name). */
+export const fieldSeparatorContentClass = (): string =>
+  'relative mx-auto block w-fit bg-background px-2 text-muted-foreground';
diff --git a/packages/ui/packages/registry/components/spinner.ts b/packages/ui/packages/registry/components/spinner.ts
new file mode 100644
index 000000000..17596378e
--- /dev/null
+++ b/packages/ui/packages/registry/components/spinner.ts
@@ -0,0 +1,63 @@
+/**
+ * Spinner: an animated busy indicator. Tier-1 helpers, `spinnerClass()` for
+ * the classes and `spinner()` for the whole inline SVG (the Lucide
+ * loader-circle path, so no icon package is needed). It inherits the text
+ * colour through `currentColor`, so it matches whatever it sits in.
+ *
+ * shadcn parity:
+ *   Spinner  → spinner({ class, label })   (the inline SVG)
+ *            → spinnerClass()              (the classes, for your own SVG)
+ *
+ * Size it with a size utility: `spinner({ class: 'size-6' })` replaces the
+ * default `size-4`.
+ *
+ * Design tokens used: none (it draws in `currentColor`).
+ *
+ * A11y (required for accessible output):
+ *   `spinner()` renders `role="status"` + `aria-label="Loading"`, so a
+ *   standalone spinner is announced. Pass `label` for a more specific name
+ *   (`spinner({ label: 'Loading invoices' })`).
+ *   Inside a BUTTON while a save is running, mark the button itself busy:
+ *   `disabled` (so a second click cannot submit twice) plus `aria-busy="true"`,
+ *   and keep a visible text label ("Saving"). The button's text already says
+ *   what is happening, so pass `decorative: true`, which renders the SVG with
+ *   `aria-hidden="true"` and no role, rather than nesting a second live status
+ *   inside the button's name. Re-enable the button and drop `aria-busy` when
+ *   the save settles, and report the outcome somewhere that is announced (a
+ *   toast, or the form's error text).
+ *   A spinner that replaces a whole region is better as a skeleton when the
+ *   final layout is known, with `aria-busy="true"` on the region.
+ *
+ * @example
+ * ```html
+ * <div class="flex items-center gap-2 text-sm text-muted-foreground">
+ *   ${spinner()} Loading invoices
+ * </div>
+ *
+ * <button class=${buttonClass()} type="submit" disabled aria-busy="true">
+ *   ${spinner({ decorative: true })} Saving
+ * </button>
+ * ```
+ */
+import { html } from '@webjsdev/core';
+import { cn } from '../lib/utils.ts';
+
+/** Spinner classes: `size-4` plus `animate-spin`. Apply to your own `<svg>`. */
+export const spinnerClass = (): string => 'size-4 animate-spin';
+
+/**
+ * The spinner as an inline SVG template. `class` is merged over
+ * `spinnerClass()` (a later size utility wins), `label` names it (default
+ * "Loading"), and `decorative` hides it from assistive tech for use beside
+ * visible text such as a busy button's label.
+ */
+export function spinner(opts: { class?: string; label?: string; decorative?: boolean } = {}) {
+  const cls = cn(spinnerClass(), opts.class);
+  // Branched rather than a nullish `role=${...}` hole: the server renderer
+  // stringifies a null attribute value, so a single template would serve
+  // `role=""` on the decorative form.
+  if (opts.decorative) {
+    return html`<svg data-slot="spinner" aria-hidden="true" xmlns="http://www.w3.org/2000/svg" viewBox="0 0 24 24" fill="none" stroke="currentColor" stroke-width="2" stroke-linecap="round" stroke-linejoin="round" class=${cls}><path d="M21 12a9 9 0 1 1-6.219-8.56" /></svg>`;
+  }
+  return html`<svg data-slot="spinner" role="status" aria-label=${opts.label ?? 'Loading'} xmlns="http://www.w3.org/2000/svg" viewBox="0 0 24 24" fill="none" stroke="currentColor" stroke-width="2" stroke-linecap="round" stroke-linejoin="round" class=${cls}><path d="M21 12a9 9 0 1 1-6.219-8.56" /></svg>`;
+}
diff --git a/packages/ui/packages/registry/registry.json b/packages/ui/packages/registry/registry.json
index 313b368dd..5f7aa33ae 100644
--- a/packages/ui/packages/registry/registry.json
+++ b/packages/ui/packages/registry/registry.json
@@ -232,6 +232,38 @@
         }
       ]
     },
+    {
+      "name": "empty",
+      "type": "registry:ui",
+      "registryDependencies": [
+        "lib-utils"
+      ],
+      "dependencies": [
+        "@webjsdev/core"
+      ],
+      "files": [
+        {
+          "path": "components/empty.ts",
+          "type": "registry:ui"
+        }
+      ]
+    },
+    {
+      "name": "field",
+      "type": "registry:ui",
+      "registryDependencies": [
+        "lib-utils"
+      ],
+      "dependencies": [
+        "@webjsdev/core"
+      ],
+      "files": [
+        {
+          "path": "components/field.ts",
+          "type": "registry:ui"
+        }
+      ]
+    },
     {
       "name": "hover-card",
       "type": "registry:ui",
@@ -410,6 +442,22 @@
         }
       ]
     },
+    {
+      "name": "spinner",
+      "type": "registry:ui",
+      "registryDependencies": [
+        "lib-utils"
+      ],
+      "dependencies": [
+        "@webjsdev/core"
+      ],
+      "files": [
+        {
+          "path": "components/spinner.ts",
+          "type": "registry:ui"
+        }
+      ]
+    },
     {
       "name": "switch",
       "type": "registry:ui",
diff --git a/packages/ui/test/add-command.test.js b/packages/ui/test/add-command.test.js
index 73d7b4769..eca659206 100644
--- a/packages/ui/test/add-command.test.js
+++ b/packages/ui/test/add-command.test.js
@@ -279,6 +279,38 @@ test('add: local-first (no --registry) installs a real component, strips its exa
   }
 });
 
+test('add: local-first installs empty, spinner and field together (#1569)', async () => {
+  globalThis.fetch = async () => { throw new Error('should not fetch (local-first)'); };
+  const d = mkdtempSync(join(tmpdir(), 'webjsui-add-real-'));
+  writeFileSync(join(d, 'components.json'), JSON.stringify({
+    style: 'default',
+    tailwind: { css: 'styles/globals.css', baseColor: 'neutral', cssVariables: true },
+    aliases: { components: 'components', utils: 'lib/utils', ui: 'components/ui', lib: 'lib' },
+  }));
+  const origLog = console.log;
+  console.log = () => {};
+  try {
+    await add.parseAsync(['empty', 'spinner', 'field', '--yes', '--no-deps', '--cwd', d], { from: 'user' });
+    const read = (n) => readFileSync(join(d, 'components', 'ui', `${n}.ts`), 'utf8');
+    assert.match(read('empty'), /export const emptyClass/);
+    assert.match(read('field'), /export function fieldClass/);
+    const spin = read('spinner');
+    assert.match(spin, /export function spinner\(/);
+    assert.match(spin, /from '@webjsdev\/core'/);
+    // The cn import is rewritten to the app's utils alias, not left relative.
+    assert.doesNotMatch(spin, /from '\.\.\/lib\/utils\.ts'/);
+    assert.match(spin, /from '\.\.\/\.\.\/lib\/utils/);
+    for (const n of ['empty', 'spinner', 'field']) {
+      assert.doesNotMatch(read(n), /@example/, `${n}: example stripped`);
+      assert.match(read(n), new RegExp(`npx @webjsdev/ui view ${n}`), `${n}: pointer left`);
+    }
+  } finally {
+    console.log = origLog;
+    globalThis.fetch = origFetch;
+    rmSync(d, { recursive: true });
+  }
+});
+
 test('ensureTheme: returns a failure (does not throw) when css path / baseColor is missing', async () => {
   // Defensive: a direct caller passing an incomplete config must get a
   // structured failure, never a synchronous crash on join(cwd, undefined). #983.
diff --git a/packages/ui/test/class-helpers.test.js b/packages/ui/test/class-helpers.test.js
index 57cb6e711..2bcd79629 100644
--- a/packages/ui/test/class-helpers.test.js
+++ b/packages/ui/test/class-helpers.test.js
@@ -248,3 +248,91 @@ test('native-select: wrapper + select + option helpers', { skip }, async () => {
     assertHelper(mod, name);
   }
 });
+
+// ---------- empty ----------
+
+test('empty: 6 subpart helpers, icon media variant', { skip }, async () => {
+  const mod = await import(join(COMPONENTS_DIR, 'empty.ts'));
+  for (const name of [
+    'emptyClass',
+    'emptyHeaderClass',
+    'emptyMediaClass',
+    'emptyTitleClass',
+    'emptyDescriptionClass',
+    'emptyContentClass',
+  ]) assertHelper(mod, name);
+  assert.match(mod.emptyClass(), /border-dashed/);
+  assert.match(mod.emptyClass(), /md:p-12/);
+  assert.match(mod.emptyHeaderClass(), /max-w-sm/);
+  assert.match(mod.emptyMediaClass(), /bg-transparent/);
+  const icon = mod.emptyMediaClass({ variant: 'icon' });
+  assert.match(icon, /size-10/);
+  assert.match(icon, /rounded-lg/);
+  assert.match(icon, /bg-muted/);
+  assert.match(icon, /text-foreground/);
+  assert.doesNotMatch(icon, /bg-transparent/);
+  assert.match(mod.emptyDescriptionClass(), /text-muted-foreground/);
+});
+
+// ---------- spinner ----------
+
+test('spinner: spinnerClass + an inline SVG that SSRs as a named status', { skip }, async () => {
+  const mod = await import(join(COMPONENTS_DIR, 'spinner.ts'));
+  assert.equal(mod.spinnerClass(), 'size-4 animate-spin');
+  const { renderToString } = await import('@webjsdev/core/server');
+  const out = await renderToString(mod.spinner());
+  assert.match(out, /<svg[^>]*role="status"/);
+  assert.match(out, /aria-label="Loading"/);
+  assert.match(out, /stroke="currentColor"/);
+  assert.match(out, /class="size-4 animate-spin"/);
+  assert.match(out, /M21 12a9 9 0 1 1-6\.219-8\.56/);
+});
+
+test('spinner: a size class replaces the default, label renames it', { skip }, async () => {
+  const mod = await import(join(COMPONENTS_DIR, 'spinner.ts'));
+  const { renderToString } = await import('@webjsdev/core/server');
+  const out = await renderToString(mod.spinner({ class: 'size-6', label: 'Saving' }));
+  assert.match(out, /class="animate-spin size-6"|class="size-6 animate-spin"/);
+  assert.doesNotMatch(out, /size-4/);
+  assert.match(out, /aria-label="Saving"/);
+});
+
+test('spinner: decorative serves aria-hidden and NO empty role or name', { skip }, async () => {
+  const mod = await import(join(COMPONENTS_DIR, 'spinner.ts'));
+  const { renderToString } = await import('@webjsdev/core/server');
+  const out = await renderToString(mod.spinner({ decorative: true }));
+  assert.match(out, /aria-hidden="true"/);
+  assert.doesNotMatch(out, /role=/);
+  assert.doesNotMatch(out, /aria-label=/);
+});
+
+// ---------- field ----------
+
+test('field: 11 subpart helpers with orientation + legend variants', { skip }, async () => {
+  const mod = await import(join(COMPONENTS_DIR, 'field.ts'));
+  for (const name of [
+    'fieldSetClass',
+    'fieldLegendClass',
+    'fieldGroupClass',
+    'fieldClass',
+    'fieldContentClass',
+    'fieldLabelClass',
+    'fieldTitleClass',
+    'fieldDescriptionClass',
+    'fieldErrorClass',
+    'fieldSeparatorClass',
+    'fieldSeparatorContentClass',
+  ]) assertHelper(mod, name);
+  assert.match(mod.fieldClass(), /group\/field/);
+  assert.match(mod.fieldClass(), /data-\[invalid=true\]:text-destructive/);
+  assert.match(mod.fieldClass(), /flex-col/);
+  assert.match(mod.fieldClass({ orientation: 'horizontal' }), /flex-row items-center/);
+  assert.match(mod.fieldClass({ orientation: 'responsive' }), /@md\/field-group:flex-row/);
+  assert.match(mod.fieldLegendClass(), /text-base/);
+  assert.match(mod.fieldLegendClass({ variant: 'label' }), /text-sm/);
+  assert.match(mod.fieldGroupClass(), /@container\/field-group/);
+  assert.match(mod.fieldErrorClass(), /text-destructive/);
+  assert.match(mod.fieldErrorClass(), /text-sm/);
+  assert.match(mod.fieldLabelClass(), /group-data-\[disabled=true\]\/field:opacity-50/);
+  assert.match(mod.fieldDescriptionClass(), /text-muted-foreground/);
+});
diff --git a/packages/ui/test/extract.test.js b/packages/ui/test/extract.test.js
index 9fd62132a..f3b3ad4e5 100644
--- a/packages/ui/test/extract.test.js
+++ b/packages/ui/test/extract.test.js
@@ -58,7 +58,7 @@ test('uiComponent: null for a non-ui / unknown name', () => {
 
 test('uiInventory: one entry per registry:ui component, tier-labelled, sorted', () => {
   const inv = uiInventory();
-  assert.equal(inv.length, 32);
+  assert.equal(inv.length, 35);
   assert.ok(inv.every((c) => c.tier === 1 || c.tier === 2));
   const names = inv.map((c) => c.name);
   assert.deepEqual(names, [...names].sort(), 'inventory is sorted by name');
diff --git a/packages/ui/test/registry-contents.test.js b/packages/ui/test/registry-contents.test.js
index 3a5d5e861..f9e6b04d7 100644
--- a/packages/ui/test/registry-contents.test.js
+++ b/packages/ui/test/registry-contents.test.js
@@ -38,6 +38,7 @@ const V1_COMPONENTS = [
   'dialog', 'alert-dialog', 'popover', 'tooltip', 'hover-card',
   'tabs', 'accordion', 'collapsible',
   'dropdown-menu', 'sonner',
+  'empty', 'spinner', 'field',
 ];
 
 // Components that are Tier 2, must register a custom element.
@@ -59,10 +60,10 @@ function readManifest() {
   return JSON.parse(readFileSync(MANIFEST_PATH, 'utf8'));
 }
 
-test('registry.json exists and enumerates ≥32 v1 components', { skip }, () => {
+test('registry.json exists and enumerates ≥35 components', { skip }, () => {
   const m = readManifest();
   const uiItems = m.items.filter((it) => it.type === 'registry:ui');
-  assert.ok(uiItems.length >= 32, `expected ≥32 registry:ui items, found ${uiItems.length}`);
+  assert.ok(uiItems.length >= 35, `expected ≥35 registry:ui items, found ${uiItems.length}`);
 });
 
 test('every v1 component source file exists and is non-trivial', { skip }, () => {
diff --git a/website/app/ui/[name]/page.ts b/website/app/ui/[name]/page.ts
index c69a2b266..b3d991fb8 100644
--- a/website/app/ui/[name]/page.ts
+++ b/website/app/ui/[name]/page.ts
@@ -50,14 +50,14 @@ import '#modules/ui/components/tooltip.ts';
  * so it is title-cased for the human-facing title only.
  *
  * Each page describes ITSELF rather than inheriting one section description
- * from the layout for all 33 URLs. A set of byte-identical descriptions across
+ * from the layout for all 36 URLs. A set of byte-identical descriptions across
  * a section is exactly the duplicate-content shape this migration exists to
- * avoid, and it would have been self-defeating to introduce 33 of them in a
+ * avoid, and it would have been self-defeating to introduce 36 of them in a
  * change whose stated purpose is search consolidation.
  *
  * The sentence is DERIVED rather than hand-written. The registry carries no
  * per-item description (checked: every `registry:ui` item omits it), so a
- * hand-written map would be 33 more strings to drift out of sync with the kit.
+ * hand-written map would be 36 more strings to drift out of sync with the kit.
  * Tier plus the naming convention is enough to say something true and distinct
  * about every component, and it stays correct when one moves between tiers.
  */
diff --git a/website/app/ui/layout.ts b/website/app/ui/layout.ts
index a04a22bfc..b53b2ad29 100644
--- a/website/app/ui/layout.ts
+++ b/website/app/ui/layout.ts
@@ -26,7 +26,7 @@ import { splitByTier } from '#modules/ui/utils/tier.ts';
  */
 
 const UI_DESCRIPTION =
-  'The AI-first component library for WebJs: 32 primitives in two tiers, class-helper functions for visuals and custom elements only where state matters, source-copied into your project and styled with Tailwind v4.';
+  'The AI-first component library for WebJs: 35 primitives in two tiers, class-helper functions for visuals and custom elements only where state matters, source-copied into your project and styled with Tailwind v4.';
 const UI_OG_TITLE = 'WebJs UI components';
 
 /**
diff --git a/website/modules/ui/utils/component-api.ts b/website/modules/ui/utils/component-api.ts
index 515555cdf..3cf4f441d 100644
--- a/website/modules/ui/utils/component-api.ts
+++ b/website/modules/ui/utils/component-api.ts
@@ -549,7 +549,44 @@ export const COMPONENT_API: Record<string, ComponentApi> = {
     subcomponents: [{ name: 'separatorClass({ orientation })', description: 'Apply to <div role="separator">.' }],
     props: [{ name: 'orientation', type: '"horizontal" | "vertical"', default: '"horizontal"' }],
   },
+  empty: {
+    subcomponents: [
+      { name: 'emptyClass()', description: 'Root. Centred column with generous padding; add border for the dashed outline.' },
+      { name: 'emptyHeaderClass()', description: 'Groups the media, title, and description.' },
+      { name: 'emptyMediaClass({ variant })', description: 'Icon or illustration. variant icon puts the icon on a muted tile.' },
+      { name: 'emptyTitleClass() / emptyDescriptionClass()', description: 'Use a real heading for the title; the description is muted text saying what to do next.' },
+      { name: 'emptyContentClass()', description: 'Row for the action button(s).' },
+    ],
+    props: [{ name: 'variant', type: '"default" | "icon"', default: '"default"', description: 'On emptyMediaClass. Set data-variant on the same element for shadcn parity.' }],
+  },
+  field: {
+    subcomponents: [
+      { name: 'fieldSetClass() / fieldLegendClass({ variant })', description: 'A native <fieldset> and its <legend>, which names a group of fields.' },
+      { name: 'fieldGroupClass()', description: 'Stacks fields, and is the container responsive fields measure.' },
+      { name: 'fieldClass({ orientation })', description: 'One label, control, and text unit. data-invalid="true" turns it destructive.' },
+      { name: 'fieldContentClass()', description: 'Wraps a label and description beside a horizontal control.' },
+      { name: 'fieldLabelClass() / fieldTitleClass()', description: 'The <label for> of the control, or label-styled text that is not a label.' },
+      { name: 'fieldDescriptionClass()', description: 'Muted helper text. Reference its id from the control with aria-describedby.' },
+      { name: 'fieldErrorClass()', description: 'Inline validation message with role="alert", referenced from the control with aria-describedby.' },
+      { name: 'fieldSeparatorClass() / fieldSeparatorContentClass()', description: 'A rule between fields with optional centred text.' },
+    ],
+    props: [
+      { name: 'orientation', type: '"vertical" | "horizontal" | "responsive"', default: '"vertical"', description: 'On fieldClass. Set data-orientation on the same element.' },
+      { name: 'variant', type: '"legend" | "label"', default: '"legend"', description: 'On fieldLegendClass. Set data-variant on the same element.' },
+    ],
+  },
   skeleton: { subcomponents: [{ name: 'skeletonClass()', description: 'Apply to a div with explicit width/height.' }] },
+  spinner: {
+    subcomponents: [
+      { name: 'spinner({ class, label, decorative })', description: 'The inline SVG as an html template, role="status" and aria-label="Loading" by default.' },
+      { name: 'spinnerClass()', description: 'size-4 animate-spin, for your own <svg>.' },
+    ],
+    props: [
+      { name: 'class', type: 'string', description: 'Merged over spinnerClass(), so a size utility replaces size-4.' },
+      { name: 'label', type: 'string', default: '"Loading"', description: 'The accessible name.' },
+      { name: 'decorative', type: 'boolean', default: 'false', description: 'aria-hidden and no role, for beside visible text such as a busy button label.' },
+    ],
+  },
   table: {
     subcomponents: [
       { name: 'tableContainerClass()', description: 'Scroll wrapper.' },
diff --git a/website/modules/ui/utils/examples.ts b/website/modules/ui/utils/examples.ts
index bcdac5a91..6db5afabc 100644
--- a/website/modules/ui/utils/examples.ts
+++ b/website/modules/ui/utils/examples.ts
@@ -53,6 +53,32 @@ import {
 } from '#modules/ui/components/avatar.ts';
 import { separatorClass } from '#modules/ui/components/separator.ts';
 import { skeletonClass } from '#modules/ui/components/skeleton.ts';
+import {
+  emptyClass,
+  emptyHeaderClass,
+  emptyMediaClass,
+  emptyTitleClass,
+  emptyDescriptionClass,
+  emptyContentClass,
+} from '#modules/ui/components/empty.ts';
+import { spinnerClass } from '#modules/ui/components/spinner.ts';
+// field.ts reuses the fieldClass / fieldLabelClass names that lib/utils/cn.ts
+// already exports (the older single-field rhythm helpers the input examples
+// use), so the kit versions are aliased here and swapped in for the field
+// example only, through FIELD_HELPERS below.
+import {
+  fieldSetClass,
+  fieldLegendClass,
+  fieldGroupClass,
+  fieldClass as kitFieldClass,
+  fieldContentClass,
+  fieldLabelClass as kitFieldLabelClass,
+  fieldTitleClass,
+  fieldDescriptionClass,
+  fieldErrorClass,
+  fieldSeparatorClass,
+  fieldSeparatorContentClass,
+} from '#modules/ui/components/field.ts';
 import { aspectRatioClass } from '#modules/ui/components/aspect-ratio.ts';
 import { kbdClass, kbdGroupClass } from '#modules/ui/components/kbd.ts';
 import {
@@ -156,6 +182,9 @@ const HELPERS: Record<string, (...args: never[]) => string> = {
   checkboxClass,
   collapsibleClass, collapsibleContentClass, collapsibleTriggerClass,
   dialogDescriptionClass, dialogFooterClass, dialogHeaderClass, dialogTitleClass,
+  emptyClass, emptyContentClass, emptyDescriptionClass, emptyHeaderClass, emptyMediaClass, emptyTitleClass,
+  fieldContentClass, fieldDescriptionClass, fieldErrorClass, fieldGroupClass, fieldLegendClass,
+  fieldSeparatorClass, fieldSeparatorContentClass, fieldSetClass, fieldTitleClass,
   fieldClass, hintClass, inputClass, kbdClass, kbdGroupClass, labelClass,
   nativeSelectClass, nativeSelectIconClass, nativeSelectWrapperClass,
   paginationClass, paginationContentClass, paginationLinkClass, paginationNextClass, paginationPreviousClass,
@@ -168,12 +197,23 @@ const HELPERS: Record<string, (...args: never[]) => string> = {
   tabsListClass, textareaClass, toggleClass,
 };
 
+// The field example's scope: the kit's fieldClass / fieldLabelClass in place of
+// the cn() module's same-named rhythm helpers. Chosen by comparing the snippet
+// against EXAMPLES.field, so no other example changes what its holes evaluate
+// to, and nothing runs at module scope (a module-scope call would make the
+// elision analyser read this module as client work).
+const FIELD_HELPERS: Record<string, (...args: never[]) => string> = {
+  ...HELPERS,
+  fieldClass: kitFieldClass,
+  fieldLabelClass: kitFieldLabelClass,
+};
+
 // Evaluate one authored call expression such as buttonClass({ variant: 'x' })
 // against HELPERS. Runs server-side only (from the page render), over strings
 // this module authored, never user input. Fails soft to an empty class.
-function evalHole(expr: string): string {
+function evalHole(expr: string, helpers = HELPERS): string {
   try {
-    return String(new Function('H', `return (H.${expr});`)(HELPERS));
+    return String(new Function('H', `return (H.${expr});`)(helpers));
   } catch {
     return '';
   }
@@ -185,6 +225,7 @@ function evalHole(expr: string): string {
 // becomes the call verbatim, and when the hole is the ENTIRE quoted attribute
 // value the quotes are dropped so it reads as the idiomatic unquoted form.
 function buildExample(src: string, mode: 'render' | 'code'): string {
+  const helpers = src === EXAMPLES.field ? FIELD_HELPERS : HELPERS;
   let out = '';
   let i = 0;
   while (i < src.length) {
@@ -206,7 +247,7 @@ function buildExample(src: string, mode: 'render' | 'code'): string {
     const before = src.slice(i, open);
     const expr = src.slice(open + 2, j).trim();
     if (mode === 'render') {
-      out += before + evalHole(expr);
+      out += before + evalHole(expr, helpers);
       i = j + 1;
     } else if (before.endsWith('="') && src[j + 1] === '"') {
       out += before.slice(0, -1) + '${' + expr + '}';
@@ -382,6 +423,63 @@ const EXAMPLES: Record<string, string> = {
     </div>
   `,
 
+  empty: `
+    <div class="\${emptyClass()} border w-full max-w-lg">
+      <div class="\${emptyHeaderClass()}">
+        <div class="\${emptyMediaClass({ variant: 'icon' })}" data-variant="icon">
+          <svg aria-hidden="true" xmlns="http://www.w3.org/2000/svg" viewBox="0 0 24 24" fill="none" stroke="currentColor" stroke-width="2" stroke-linecap="round" stroke-linejoin="round"><path d="M22 12h-6l-2 3h-4l-2-3H2"/><path d="M5.45 5.11 2 12v6a2 2 0 0 0 2 2h16a2 2 0 0 0 2-2v-6l-3.45-6.89A2 2 0 0 0 16.76 4H7.24a2 2 0 0 0-1.79 1.11z"/></svg>
+        </div>
+        <h3 class="\${emptyTitleClass()}">No projects yet</h3>
+        <p class="\${emptyDescriptionClass()}">You have not created any projects. Create your first one to get started.</p>
+      </div>
+      <div class="\${emptyContentClass()}">
+        <a class="\${buttonClass()}" href="#">Create project</a>
+      </div>
+    </div>
+  `,
+
+  spinner: `
+    <div class="flex flex-wrap items-center gap-6">
+      <div class="flex items-center gap-2 text-sm text-muted-foreground">
+        <svg data-slot="spinner" role="status" aria-label="Loading" xmlns="http://www.w3.org/2000/svg" viewBox="0 0 24 24" fill="none" stroke="currentColor" stroke-width="2" stroke-linecap="round" stroke-linejoin="round" class="\${spinnerClass()}"><path d="M21 12a9 9 0 1 1-6.219-8.56" /></svg>
+        Loading invoices
+      </div>
+      <button class="\${buttonClass()}" type="button" disabled aria-busy="true">
+        <svg data-slot="spinner" aria-hidden="true" xmlns="http://www.w3.org/2000/svg" viewBox="0 0 24 24" fill="none" stroke="currentColor" stroke-width="2" stroke-linecap="round" stroke-linejoin="round" class="\${spinnerClass()}"><path d="M21 12a9 9 0 1 1-6.219-8.56" /></svg>
+        Saving
+      </button>
+    </div>
+  `,
+
+  field: `
+    <form class="w-full max-w-md">
+      <fieldset class="\${fieldSetClass()}">
+        <legend class="\${fieldLegendClass()}" data-variant="legend">Profile</legend>
+        <p class="\${fieldDescriptionClass()}">This is how others see you.</p>
+        <div class="\${fieldGroupClass()}" data-slot="field-group">
+          <div class="\${fieldClass()}" data-slot="field" data-orientation="vertical">
+            <label class="\${fieldLabelClass()}" data-slot="field-label" for="field-demo-name">Name</label>
+            <input class="\${inputClass()}" id="field-demo-name" name="name" value="Ada Lovelace" aria-describedby="field-demo-name-desc">
+            <p class="\${fieldDescriptionClass()}" id="field-demo-name-desc">Shown on your public page.</p>
+          </div>
+          <div class="\${fieldClass()}" data-slot="field" data-orientation="vertical" data-invalid="true">
+            <label class="\${fieldLabelClass()}" data-slot="field-label" for="field-demo-email">Email</label>
+            <input class="\${inputClass()}" id="field-demo-email" name="email" type="email" value="ada@" aria-invalid="true" aria-describedby="field-demo-email-error">
+            <div class="\${fieldErrorClass()}" id="field-demo-email-error" role="alert">Enter a valid email address.</div>
+          </div>
+          <div class="\${fieldSeparatorClass()}" role="none"><span class="\${fieldSeparatorContentClass()}">Notifications</span></div>
+          <div class="\${fieldClass({ orientation: 'horizontal' })}" data-slot="field" data-orientation="horizontal">
+            <input class="\${checkboxClass()}" data-slot="checkbox" type="checkbox" id="field-demo-digest" name="digest" checked>
+            <div class="\${fieldContentClass()}" data-slot="field-content">
+              <label class="\${fieldLabelClass()}" data-slot="field-label" for="field-demo-digest">Weekly digest</label>
+              <p class="\${fieldDescriptionClass()}">A summary of activity, every Monday.</p>
+            </div>
+          </div>
+        </div>
+      </fieldset>
+    </form>
+  `,
+
   'aspect-ratio': `
     <div style="aspect-ratio: 16 / 9;" class="\${aspectRatioClass()} max-w-md rounded-md bg-muted flex items-center justify-center text-muted-foreground">
       16:9