@viraui/react 2026.5.0 → 2026.6.1

package/dist/specs/components/checkbox/patterns.xml

@@ -1,7 +1,87 @@
 <?xml version="1.0" encoding="UTF-8"?>
 <patterns surface="checkbox">
-  <example title="Checkbox structure">
-    <tsx><![CDATA[<Checkbox label="…" />]]></tsx>
-    <notes>Public assembly hint from legacy guide; not API authority.</notes>
+  <!-- Sources: viraui-app / design-kitchen preview-grid — cleaned (no handlers, no app state). -->
+
+  <example title="Notifications list (select-all)">
+    <tsx><![CDATA[
+<Surface overflow="hidden" border="all" color={1} radius="l">
+  <Stack rowGap="m">
+    <Stack rowGap="m" hPadding="m" vPadding="m">
+      <Stack rowGap="xs" vPadding={[0, 'm']}>
+        <Title size="6" render={<h2 />}>
+          Notifications
+        </Title>
+        <Text size="s" tone="muted">
+          Choose what you want to be notified about.
+        </Text>
+      </Stack>
+
+      <Field.Root name="select-all-notifications">
+        <Checkbox checked label="Select all" />
+      </Field.Root>
+
+      <Field.Root name="transaction-alerts">
+        <Checkbox
+          checked
+          description="Deposits, withdrawals, and transfers."
+          label="Transaction alerts"
+        />
+      </Field.Root>
+
+      <Field.Root name="security-alerts">
+        <Checkbox
+          checked
+          description="Login attempts and account changes."
+          label="Security alerts"
+        />
+      </Field.Root>
+
+      <Field.Root name="goal-milestones">
+        <Checkbox
+          description="Updates at 25%, 50%, 75%, and 100%."
+          label="Goal milestones"
+        />
+      </Field.Root>
+
+      <Field.Root name="market-updates">
+        <Checkbox
+          description="Daily portfolio summary and price alerts."
+          label="Market updates"
+        />
+      </Field.Root>
+    </Stack>
+
+    <Surface color={2} hPadding="l" vPadding="m">
+      <Button>Save Preferences</Button>
+    </Surface>
+  </Stack>
+</Surface>
+]]></tsx>
+    <notes>From `editor/preview-grid/blocks/notifications`. Each option is its own `Field.Root` + `Checkbox` (label/description on the control). Parent can drive `indeterminate` on a select-all row — drop handlers from the hint.</notes>
+  </example>
+
+  <example title="Form footer boolean">
+    <tsx><![CDATA[
+<Stack rowGap="l" hPadding="m" vPadding="m">
+  <Textfield label="Street address" required />
+  <Textfield label="Apt / Suite" />
+
+  <Field.Root name="save-as-default">
+    <Checkbox checked label="Save as default address" />
+  </Field.Root>
+</Stack>
+]]></tsx>
+    <notes>From `editor/preview-grid/blocks/shipping-address`. Standalone boolean under fields — wrap in `Field.Root`; no Fieldset needed without a shared legend.</notes>
+  </example>
+
+  <example title="Disabled on nested surface">
+    <tsx><![CDATA[
+<Surface border="all" color={1} hPadding="s" radius="auto" vPadding="s">
+  <Field.Root disabled name="send-notifications">
+    <Checkbox checked disabled label="Send notifications" />
+  </Field.Root>
+</Surface>
+]]></tsx>
+    <notes>From `editor/preview-grid/blocks/disabled-surface-contrast`. Disable via `Field.Root` and/or `Checkbox` `disabled` so contrast holds on nested Surface colors.</notes>
   </example>
 </patterns>

package/dist/specs/components/checkbox/props.xml

@@ -30,19 +30,19 @@
   <prop name="vPadding" kind="react">
     <description>Sets block padding using one token for both sides or a `[start, end]` tuple.</description>
   </prop>
-  <css_var suffix="background">
+  <prop name="background" kind="css">
     <description>Checkbox control background color.</description>
-  </css_var>
-  <css_var suffix="border-color">
+  </prop>
+  <prop name="border-color" kind="css">
     <description>Checkbox control border color; invalid and checked states override.</description>
-  </css_var>
-  <css_var suffix="indicator-color">
+  </prop>
+  <prop name="indicator-color" kind="css">
     <description>Checkbox check/minus indicator color.</description>
-  </css_var>
-  <css_var suffix="radius">
+  </prop>
+  <prop name="radius" kind="css">
     <description>Checkbox control corner radius.</description>
-  </css_var>
-  <css_var suffix="size">
+  </prop>
+  <prop name="size" kind="css">
     <description>Checkbox control box size; size presets adjust footprint and radius.</description>
-  </css_var>
+  </prop>
 </props>

package/dist/specs/components/checkbox/usage.xml

@@ -1,10 +1,15 @@
 <?xml version="1.0" encoding="UTF-8"?>
 <usage surface="checkbox">
-  <do>Single boolean fields wrapped in Field.Root with optional label and helper text — no Fieldset required</do>
+  <do>Standalone boolean under form fields — wrap each Checkbox in Field.Root; put label/description on Checkbox (no Fieldset without a shared legend)</do>
+  <do>Form footers with Textfield rows in a Stack — Field.Root &gt; Checkbox for “save as default” style booleans</do>
+  <do>Multi-select with shared legend or group copy — Field.Root &gt; Fieldset render={&lt;CheckboxGroup /&gt;} with Checkbox children</do>
   <do>CheckboxGroup alone inside Field.Root when each Checkbox has its own label and no shared group legend is needed</do>
-  <do>Multi-select sets with shared legend or group copy — Field.Root &gt; Fieldset render={&lt;CheckboxGroup /&gt;} with Checkbox children</do>
-  <do>Invalid and disabled states with Switch-parity focus treatment</do>
-  <dont>Rendering a checkbox without label and without aria-label</dont>
-  <dont>Using Checkbox without Field.Root for standalone validated fields</dont>
-  <dont>Expecting description to stay visible when invalid without an error message</dont>
+  <do>Settings / notification lists inside Surface + Stack — one Field.Root + Checkbox per row; drive select-all with Base UI `indeterminate` when needed</do>
+  <do>Settings row without built-in copy — Stack `direction=&quot;row&quot;` `hAlign=&quot;space-between&quot;` + Text + Checkbox (`aria-label` if unlabeled)</do>
+  <dont>Rendering a checkbox without `label` and without `aria-label`</dont>
+  <dont>Using Checkbox without Field.Root for standalone named or validated fields</dont>
+  <dont>Expecting `description` to stay visible when invalid without an `error` message</dont>
+  <dont>Mutually exclusive options — use Radio + RadioGroup</dont>
+  <dont>Putting group legend, description, or validation on CheckboxGroup props — use Field.Root and Fieldset</dont>
+  <dont>Assuming Fieldset is mandatory for every CheckboxGroup — add it only for shared legend or group copy</dont>
 </usage>

package/dist/specs/components/chip/patterns.xml

@@ -1,7 +1,78 @@
 <?xml version="1.0" encoding="UTF-8"?>
 <patterns surface="chip">
-  <example title="Chip structure">
-    <tsx><![CDATA[<Chip>Label</Chip>]]></tsx>
-    <notes>Public assembly hint from legacy guide; not API authority.</notes>
+  <!-- Sources: viraui-app/components — cleaned (no handlers, no app-only chrome). Chip = non-interactive label; actions use Button/IconButton. -->
+
+  <example title="Status row with addons">
+    <tsx><![CDATA[
+<Stack columnGap="s" rowGap="s" direction="row" wrap>
+  <Chip variant="green">Live</Chip>
+  <Chip variant="blue" addon={<Spinner size="s" />} addonPosition="end">
+    Deploying
+  </Chip>
+  <Chip variant="yellow">Queued</Chip>
+  <Chip variant="red" addon={<Xmark size={14} />}>
+    Failed
+  </Chip>
+  <Chip variant="salmon">Rolled back</Chip>
+</Stack>
+]]></tsx>
+    <notes>From `editor/preview-grid/blocks/environment-variables` deployStatuses. Highlight variants + optional `addon` / `addonPosition`. Non-interactive — no click handlers.</notes>
+  </example>
+
+  <example title="Pending status with mark">
+    <tsx><![CDATA[
+<Stack rowGap="m" hPadding="m" vPadding="m">
+  <Stack rowGap="s">
+    <Text size="s" tone="muted">
+      Claimable Balance
+    </Text>
+    <Title size="1" lineHeight="s">
+      $0.00
+    </Title>
+  </Stack>
+  <Chip variant="outline" addon={<CircleCross size={8} color="var(--highlight-yellow)" />}>
+    Pending Setup
+  </Chip>
+</Stack>
+]]></tsx>
+    <notes>From `editor/preview-grid/blocks/claimable-balance`. Outline Chip + small leading status mark.</notes>
+  </example>
+
+  <example title="Metadata tag on row">
+    <tsx><![CDATA[
+<Stack direction="row" vAlign="center" columnGap="m" hAlign="space-between">
+  <Stack data-grow rowGap="s">
+    <Text weight="semibold">Acme Corp</Text>
+    <Text family="mono" size="xs" tone="muted">
+      ACME · NASDAQ
+    </Text>
+  </Stack>
+  <Stack direction="row" data-grow="false" columnGap="m" vAlign="center">
+    <Chip variant="outline">Stock</Chip>
+    <Text weight="semibold" size="s">
+      $184.20
+    </Text>
+  </Stack>
+</Stack>
+]]></tsx>
+    <notes>From `editor/preview-grid/blocks/holdings` HoldingRow. Outline Chip as kind/metadata beside values.</notes>
+  </example>
+
+  <example title="Centered caption chip">
+    <tsx><![CDATA[
+<Stack hAlign="center" vPadding={['l', 's']} expandChildren>
+  <Chip variant="blue">+3000 more icons</Chip>
+</Stack>
+]]></tsx>
+    <notes>From `editor/preview-grid/blocks/action-toolbar` footer. Single highlight Chip as caption under a grid.</notes>
+  </example>
+
+  <example title="Button addon (inverted)">
+    <tsx><![CDATA[
+<Button variant="primary" addon={<Chip data-mode="inverted">New</Chip>} addonPosition="end" pill>
+  Notifications
+</Button>
+]]></tsx>
+    <notes>Cross-ref button `usage.xml` / `props.xml`. Primary Chip inside primary Button needs `data-mode="inverted"` so fill contrasts.</notes>
   </example>
 </patterns>

package/dist/specs/components/chip/props.xml

@@ -25,25 +25,25 @@
   <prop name="variant" kind="react">
     <description>Selects the visual treatment for the chip.</description>
   </prop>
-  <css_var suffix="background">
+  <prop name="background" kind="css">
     <description>Chip fill; variant presets via data attributes.</description>
-  </css_var>
-  <css_var suffix="border-color">
+  </prop>
+  <prop name="border-color" kind="css">
     <description>Chip border color.</description>
-  </css_var>
-  <css_var suffix="color">
+  </prop>
+  <prop name="color" kind="css">
     <description>Chip label and icon color.</description>
-  </css_var>
-  <css_var suffix="color-bg-opacity">
+  </prop>
+  <prop name="color-bg-opacity" kind="css">
     <description>Highlight variant background opacity mix.</description>
-  </css_var>
-  <css_var suffix="color-border-opacity">
+  </prop>
+  <prop name="color-border-opacity" kind="css">
     <description>Highlight variant border opacity mix.</description>
-  </css_var>
-  <css_var suffix="height">
+  </prop>
+  <prop name="height" kind="css">
     <description>Fixed chip block size.</description>
-  </css_var>
-  <css_var suffix="icon-size">
+  </prop>
+  <prop name="icon-size" kind="css">
     <description>Decorative addon icon size.</description>
-  </css_var>
+  </prop>
 </props>

package/dist/specs/components/chip/usage.xml

@@ -1,11 +1,15 @@
 <?xml version="1.0" encoding="UTF-8"?>
 <usage surface="chip">
   <do>Short, non-interactive labels that need a compact pill treatment</do>
-  <do>Metadata, category, status, or inline tag-like presentation</do>
-  <do>Color-coded badges using the semantic highlight palette</do>
-  <do>Polymorphic label content that should render as div by default or as another semantic tag through render</do>
-  <dont>Using Chip as a button replacement for clickable actions</dont>
-  <dont>Expecting addonPosition to have any effect when addon is omitted</dont>
+  <do>Metadata, category, status, or inline tag-like presentation in Stack rows with Text / Title</do>
+  <do>Color-coded status via highlight `variant` values (`green`, `red`, `yellow`, …) or `primary` / `secondary` / `outline`</do>
+  <do>Primary Chip as Button `addon` — set `data-mode=&quot;inverted&quot;` on the Chip when the Button is primary so fills contrast</do>
+  <do>Equal-width Chip clusters: wrap in Stack with `fullWidth` and/or `expandChildren` — never per-Chip width CSS</do>
+  <do>Polymorphic label root via `render` (default `div`)</do>
+  <dont>Using Chip as a button replacement for clickable actions — use Button or IconButton</dont>
+  <dont>Expecting `addonPosition` to have any effect when `addon` is omitted</dont>
   <dont>Introducing custom size variants instead of the fixed compact height</dont>
-  <dont>Re-adding a one-off destructive variant instead of using the red highlight color</dont>
+  <dont>Re-adding a one-off destructive variant instead of `variant=&quot;red&quot;`</dont>
+  <dont>Primary Chip inside a primary Button without `data-mode=&quot;inverted&quot;` — chip fill matches the button and disappears</dont>
+  <dont>Inventing `width: 100%` / `w-full` CSS on Chip when a parent Stack `fullWidth` / `expandChildren` can own the fill</dont>
 </usage>

package/dist/specs/components/clamp-text/patterns.xml

@@ -1,7 +1,4 @@
 <?xml version="1.0" encoding="UTF-8"?>
 <patterns surface="clamp-text">
-  <example title="ClampText structure">
-    <tsx><![CDATA[<ClampText>…</ClampText>]]></tsx>
-    <notes>Public assembly hint from legacy guide; not API authority.</notes>
-  </example>
+  <!-- Skip: zero viraui-app and design-kitchen usage. Package stories cover Text/Title compose; no consumer extract to promote. -->
 </patterns>

package/dist/specs/components/clamp-text/props.xml

@@ -21,7 +21,7 @@
   <prop name="rows" kind="react">
     <description>Sets how many lines of text remain visible before truncation.</description>
   </prop>
-  <css_var suffix="rows">
+  <prop name="rows" kind="css">
     <description>WebKit line-clamp row count on the root.</description>
-  </css_var>
+  </prop>
 </props>

package/dist/specs/components/clamp-text/usage.xml

@@ -1,8 +1,11 @@
 <?xml version="1.0" encoding="UTF-8"?>
 <usage surface="clamp-text">
-  <do>Single- or multi-line ellipsis in constrained layouts</do>
-  <do>Clamp Text or Title roots through render</do>
-  <do>Inline or block clamped typography</do>
-  <dont>Using ClampText as a heading primitive without Title render</dont>
-  <dont>Expecting children-driven sizing instead of rows</dont>
+  <do>Single- or multi-line ellipsis — set `rows` (default 1); pass `inline` for inline `-webkit-inline-box`</do>
+  <do>Compose typography through `render`: ClampText `render={&lt;Text tone=&quot;muted&quot; size=&quot;s&quot; /&gt;}` or `render={&lt;Title size=… render={&lt;h* /&gt;} /&gt;}`</do>
+  <do>Constrain width with parent Surface / Stack (`fullWidth` / `maxWidth` on Text/Title) — ClampText only owns line count</do>
+  <do>Pick ClampText when overflow must truncate; FitText when short copy must scale to fill width; Title alone when no clamp/fit needed</do>
+  <dont>Using ClampText as a heading primitive without Title via `render`</dont>
+  <dont>Expecting children or font size to drive truncation — `rows` sets visible lines</dont>
+  <dont>Using ClampText for fit-to-width scaling — that is FitText</dont>
+  <dont>Relying on clamped copy alone for critical instructions or legal text</dont>
 </usage>

package/dist/specs/components/dialog/patterns.xml

@@ -1,19 +1,140 @@
 <?xml version="1.0" encoding="UTF-8"?>
 <patterns surface="dialog">
-  <example title="Dialog structure">
-    <tsx><![CDATA[<Dialog.Provider>
-  <Dialog.IndentBackground />
-  <Dialog.Indent>
-    …
-    <Dialog>
-      <Dialog.Trigger />
-      <Dialog.Sheet title="…">
-        …
-        <Dialog.Close />
-      </Dialog.Sheet>
-    </Dialog>
-  </Dialog.Indent>
-</Dialog.Provider>]]></tsx>
-    <notes>Public assembly hint from legacy guide; not API authority.</notes>
+  <!-- Sources: viraui-app/components + design-kitchen preview-grid — cleaned (no handlers, no portal/preview chrome). -->
+
+  <example title="App shell indent providers">
+    <tsx><![CDATA[
+<Dialog.Provider>
+  <Dialog.IndentBackground>
+    <Dialog.Indent>
+      <Tooltip.Provider>
+        {/* app tree */}
+      </Tooltip.Provider>
+    </Dialog.Indent>
+  </Dialog.IndentBackground>
+</Dialog.Provider>
+]]></tsx>
+    <notes>From `providers/providers` (+ preview `preview-providers`). Wrap shell once so sheets can indent the page. Portal/backdrop live inside `Dialog.Sheet` — not public parts.</notes>
+  </example>
+
+  <example title="Import preset form">
+    <tsx><![CDATA[
+<Dialog>
+  <Dialog.Trigger
+    render={
+      <Button size="s" variant="secondary" addon={<FileArrowIn />}>
+        Import
+      </Button>
+    }
+  />
+  <Dialog.Sheet
+    title="Import preset"
+    description="Paste preset code."
+    showCloseButton
+    headerAlign="center"
+  >
+    <Stack rowGap="m" hAlign="center" hPadding="m" vPadding={['s', 0]}>
+      <Textfield size={40} placeholder="Paste preset…" aria-label="Preset code" />
+      <Stack direction="row" hAlign="end" columnGap="s">
+        <Button>Apply</Button>
+        <Dialog.Close render={<Button variant="secondary">Cancel</Button>} />
+      </Stack>
+    </Stack>
+  </Dialog.Sheet>
+</Dialog>
+]]></tsx>
+    <notes>From `editor/import-preset-dialog`. Trigger + titled Sheet + body Stack + `Dialog.Close`. Drop open-state wiring.</notes>
+  </example>
+
+  <example title="Export sheet with snap points">
+    <tsx><![CDATA[
+<Dialog open={true} snapPoints={[0.35, 1]} snapPoint={0.35}>
+  <Dialog.Trigger render={<Button size="l">Export</Button>} />
+  <Dialog.Sheet
+    title="Export theme"
+    description="Download or share your preset."
+    showCloseButton
+    headerAlign="center"
+    maxContentWidth="min(950px, 90vw)"
+  >
+    <Stack rowGap="m" hPadding="m" vPadding={['s', 0]}>
+      <Stack direction="row" hAlign="center" columnGap="m">
+        <Button size="l" addon={<FileDownload />}>
+          Download
+        </Button>
+        <ButtonLink size="l" variant="secondary" href="#">
+          Share
+        </ButtonLink>
+        <Button size="l" variant="secondary" addon={<Code2 />}>
+          View code
+        </Button>
+      </Stack>
+      <Stack vPadding={['s', '3xl']}>
+        <Textfield fitContent readOnly value="vira-preset_…" aria-label="Preset code" />
+      </Stack>
+      {/* optional Tabs preview below */}
+    </Stack>
+  </Dialog.Sheet>
+</Dialog>
+]]></tsx>
+    <notes>From `editor/export-dialog`. Snap points live on `Dialog` root; Sheet owns title/close. `open={true}` for demo structure only.</notes>
+  </example>
+
+  <example title="Adjust goal (nested sheet)">
+    <tsx><![CDATA[
+<Dialog open={true}>
+  <Dialog.Trigger render={<Button>Adjust Goal</Button>} />
+  <Dialog.Sheet
+    headerAlign="center"
+    title="Move Goal"
+    description="Set your daily activity goal."
+  >
+    <Stack hAlign="center" rowGap="3xl" hPadding="l">
+      <Stack direction="row" hAlign="center" vAlign="center" columnGap="l" expandChildren>
+        <IconButton aria-label="Decrease goal" icon={<Minus />} size="l" variant="secondary" />
+        <Stack hAlign="center" rowGap="2xs">
+          <Title align="center" size="display" lineHeight="s" whiteSpace="nowrap">
+            350
+          </Title>
+          <Text align="center" size="xs" tone="muted">
+            CALORIES/DAY
+          </Text>
+        </Stack>
+        <IconButton aria-label="Increase goal" icon={<Plus />} size="l" variant="secondary" />
+      </Stack>
+
+      <Dialog>
+        <Dialog.Trigger render={<Button variant="secondary">Goal tips</Button>} />
+        <Dialog.Sheet
+          headerAlign="center"
+          title="Goal tips"
+          description="Nested sheet — Escape closes this layer only."
+        >
+          <Stack hPadding="l" rowGap="m">
+            <Surface color={2} radius="l" hPadding="m" vPadding="m">
+              <Text size="s" tone="muted">
+                Pick a target you can clear on ordinary weeks.
+              </Text>
+            </Surface>
+            <Dialog.Close render={<Button variant="secondary">Got it</Button>} />
+          </Stack>
+        </Dialog.Sheet>
+      </Dialog>
+
+      <Stack columnGap="s" direction="row" expandChildren>
+        <Dialog.Close render={<Button size="l">Submit</Button>} />
+        <Dialog.Close
+          render={
+            <Button size="l" variant="secondary">
+              Cancel
+            </Button>
+          }
+        />
+      </Stack>
+    </Stack>
+  </Dialog.Sheet>
+</Dialog>
+]]></tsx>
+    <notes>From preview-grid `daily-activity-goal`. Nest a second `Dialog` inside Sheet children for drill-down. Drop Meter/Beam kitchen chrome from this hint.</notes>
   </example>
 </patterns>

package/dist/specs/components/dialog/props.xml

@@ -43,7 +43,7 @@
   <prop name="Sheet.title" kind="react">
     <description>Accessible dialog title rendered as the modal heading.</description>
   </prop>
-  <css_var suffix="max-block-size">
+  <prop name="max-block-size" kind="css">
     <description>Max block size of Dialog.Sheet popup root.</description>
-  </css_var>
+  </prop>
 </props>

package/dist/specs/components/dialog/usage.xml

@@ -1,12 +1,14 @@
 <?xml version="1.0" encoding="UTF-8"?>
 <usage surface="dialog">
-  <do>Focused tasks or confirmations that interrupt the current page without navigation</do>
-  <do>Short forms or read-only content that needs a modal layer above the app</do>
-  <do>Bottom sheets where swipe dismissal or snap points are useful (pass `snapPoints`, `snapPoint`/`onSnapPointChange`, or `defaultSnapPoint` directly on `Dialog`)</do>
-  <do>Drill-down sheet flows (for example settings sub-pages) by nesting a `Dialog` inside `Dialog.Sheet` children</do>
-  <do>App-shell indent effects by wrapping page content in `Dialog.Provider`, `Dialog.IndentBackground`, and `Dialog.Indent`</do>
-  <do>Custom portal host (iframe preview, shadow root, or app overlay root) via `container` on the portal-owning public part</do>
+  <do>Page-blocking edge sheets for focused tasks, confirmations, or short forms — not anchored hints (Popover) or command lists (Menu)</do>
+  <do>Compose `Dialog.Trigger` (`render` Button/IconButton) + titled `Dialog.Sheet` + body Stack (Textfield, Button, Tabs, …) + `Dialog.Close` for footer actions</do>
+  <do>Bottom-sheet snap/swipe: pass `snapPoints`, `snapPoint`/`onSnapPointChange`, or `defaultSnapPoint` on `Dialog` root</do>
+  <do>Drill-down flows by nesting another `Dialog` inside `Dialog.Sheet` children (Escape closes the inner layer only)</do>
+  <do>App-shell indent: wrap page once in `Dialog.Provider`, `Dialog.IndentBackground`, and `Dialog.Indent`</do>
+  <do>Custom portal host (iframe preview, shadow root, or app overlay root) via `container` on `Dialog.Sheet`</do>
   <dont>Opening a sheet without `title` copy for assistive technologies</dont>
   <dont>Relying only on backdrop press or swipe when a footer action is the primary close path</dont>
-  <dont>Using Dialog when a centered non-gesture modal is enough and a future Dialog primitive is available</dont>
+  <dont>Expecting public Portal / Backdrop / Viewport / Popup / Title / Description parts — they live inside `Dialog.Sheet`</dont>
+  <dont>Using Dialog for small anchored panels (Popover) or action menus (Menu)</dont>
+  <dont>Using Dialog for centered non-edge modals that should not slide from the screen edge</dont>
 </usage>

package/dist/specs/components/elevator/patterns.xml

@@ -1,7 +1,58 @@
 <?xml version="1.0" encoding="UTF-8"?>
 <patterns surface="elevator">
-  <example title="Elevator structure">
-    <tsx><![CDATA[<Elevator resting={1}>…</Elevator>]]></tsx>
-    <notes>Public assembly hint from legacy guide; not API authority.</notes>
+  <!-- Sources: viraui-app/components — cleaned (no handlers, no i18n, no app-only chrome). -->
+
+  <example title="Elevated placeholder card">
+    <tsx><![CDATA[
+<Elevator resting={1}>
+  <Surface border="all" overflow="hidden" radius="l">
+    <Stack hPadding="m" rowGap="s" vPadding="m">
+      <Skeleton animate={false} aria-hidden height="8rem" radius="m" width="100%" />
+      <Skeleton animate={false} aria-hidden height="1rem" radius="full" width="70%" />
+      <Skeleton animate={false} aria-hidden height="0.75rem" radius="m" width="45%" />
+    </Stack>
+  </Surface>
+</Elevator>
+]]></tsx>
+    <notes>From `prompts/prompts-info-state` PlaceholderCard. Elevator merges elevation hooks onto the Surface root — no extra wrapper DOM for shadow.</notes>
+  </example>
+
+  <example title="Elevated card wall cell">
+    <tsx><![CDATA[
+<Elevator resting={1}>
+  <Surface border="all" hoverColor={3} color={2} radius="m">
+    <Stack expandChildren hPadding="l" vPadding="l" rowGap="s">
+      <Title size="5" render={<h3 />}>
+        Atlas
+      </Title>
+      <Text tone="muted" size="s">
+        Short block for baseline column packing.
+      </Text>
+    </Stack>
+  </Surface>
+</Elevator>
+]]></tsx>
+    <notes>Same compose shape as Grid/Masonry story cards and the prompts backdrop tiles. Resting elevation on Surface; hoverColor is Surface chrome, not Elevator hover.</notes>
+  </example>
+
+  <example title="Hover lift on Surface">
+    <tsx><![CDATA[
+<Elevator resting={1} hover={4}>
+  <Surface
+    color={1}
+    radius="m"
+    hPadding="l"
+    vPadding="l"
+    border="all"
+    render={<Stack rowGap="s" minWidth="14rem" />}
+  >
+    <Text size="m">Elevated card</Text>
+    <Text size="s" tone="muted">
+      Hover to lift from 1 to 4
+    </Text>
+  </Surface>
+</Elevator>
+]]></tsx>
+    <notes>Idiomatic Elevator + Surface pair (`hover` elevation). Prefer this over inventing box-shadow CSS. App uses resting-only on placeholders; hover lift matches docs/demo compose.</notes>
   </example>
 </patterns>

package/dist/specs/components/elevator/usage.xml

@@ -1,8 +1,11 @@
 <?xml version="1.0" encoding="UTF-8"?>
 <usage surface="elevator">
-  <do>Apply resting and optional hover elevation to existing elements</do>
-  <do>Compose animated box-shadow transitions with data-elevation hooks</do>
-  <do>Use getElevationProps when you need the mapping directly</do>
-  <dont>Wrapping invalid or non-element nodes</dont>
-  <dont>Overwriting child transition shorthand without composing box-shadow</dont>
+  <do>Wrap a Surface (with nested Stack/Title/Text) — Elevator merges `data-elevation` hooks onto the child root with no extra wrapper DOM</do>
+  <do>Prefer Elevator over inventing box-shadow CSS; Surface has no `elevation` prop</do>
+  <do>Set `resting` and optional `hover` for animated lift on interactive cards</do>
+  <do>Use `getElevationProps` when you need the same `data-elevation` / style mapping without the Elevator component</do>
+  <dont>Passing `elevation={…}` on Surface — wrap with Elevator or spread `getElevationProps`</dont>
+  <dont>Hand-authoring parallel elevation shadows instead of preflight `data-elevation` hooks</dont>
+  <dont>Wrapping invalid or non-element nodes expecting elevation — only valid element children receive merged props</dont>
+  <dont>Overwriting child `transition` shorthand without composing `box-shadow` when elevation hooks are present</dont>
 </usage>