@viraui/react 2026.5.0 → 2026.6.1

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

@@ -1,7 +1,192 @@
 <?xml version="1.0" encoding="UTF-8"?>
 <patterns surface="surface">
-  <example title="Surface structure">
-    <tsx><![CDATA[<Surface>…</Surface>]]></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="Nested vibrant chrome (hub nav)">
+    <tsx><![CDATA[
+<Surface hPadding="xs" vPadding="xs" radius="m" border="all" data-vibrant>
+  <Surface radius="auto" color={1} hPadding="xs" vPadding="xs">
+    <Stack render={<nav />} direction="row" vAlign="center" columnGap="xs">
+      <ButtonLink size="s" variant="secondary" href="/hub">
+        Hub
+      </ButtonLink>
+      <ButtonLink size="s" variant="flat" href="/studio">
+        Studio
+      </ButtonLink>
+      <ButtonLink size="s" variant="flat" href="/prompts">
+        Prompts
+      </ButtonLink>
+    </Stack>
+  </Surface>
+</Surface>
+]]></tsx>
+    <notes>From `common/hub-header`. Outer frosted shell (`data-vibrant`) + inner tinted Surface with `radius="auto"` for concentric corners. Nest Surfaces for chrome; Stack owns the row.</notes>
+  </example>
+
+  <example title="Dense control chrome (mode switcher)">
+    <tsx><![CDATA[
+<Surface border="all" radius="m" vPadding="2xs" hPadding="2xs">
+  <ToggleGroup aria-label="Color mode" value={['system']}>
+    <ToggleButton
+      value="light"
+      aria-label="Light"
+      restingIcon={<Sun aria-hidden size="1rem" />}
+      variant="flat"
+      size="s"
+      pressedVariant="secondary"
+    />
+    <ToggleButton
+      value="dark"
+      aria-label="Dark"
+      restingIcon={<MoonStars aria-hidden size="1rem" />}
+      variant="flat"
+      size="s"
+      pressedVariant="secondary"
+    />
+    <ToggleButton
+      value="system"
+      aria-label="System"
+      restingIcon={<DarkLight aria-hidden size="1rem" />}
+      variant="flat"
+      size="s"
+      pressedVariant="secondary"
+    />
+  </ToggleGroup>
+</Surface>
+]]></tsx>
+    <notes>From `common/mode-switcher`. Tight padding tokens on Surface host a ToggleGroup — no custom chrome CSS.</notes>
+  </example>
+
+  <example title="Editor shell (aside + canvas)">
+    <tsx><![CDATA[
+<Stack direction="row" hPadding="m" vPadding={[0, 'm']} columnGap="l" expandChildren>
+  <Surface
+    render={<Stack render={<aside aria-label="Theme controls" />} maxWidth="22rem" expandChildren />}
+    border="all"
+    overflow="hidden"
+    color={1}
+    radius="l"
+  >
+    {/* sidebar sections */}
+    <Surface color={2} data-grow="false">
+      <Separator />
+      <Stack vPadding="s" hPadding="m" rowGap="s" expandChildren>
+        <Stack direction="row" columnGap="s" expandChildren>
+          <Button size="s" variant="secondary">
+            Shuffle
+          </Button>
+          <Button size="s" variant="secondary">
+            Import
+          </Button>
+        </Stack>
+        <Button size="s">Export</Button>
+      </Stack>
+      <Separator />
+      <Stack vPadding="xs" hPadding="m">
+        <Button size="s" variant="flat">
+          Reset all
+        </Button>
+      </Stack>
+    </Surface>
+  </Surface>
+
+  <Surface render={<main />} overflow="hidden" border="all" radius="l">
+    {/* canvas / preview */}
+  </Surface>
+</Stack>
+]]></tsx>
+    <notes>From `editor/editor`. `render` merges Surface chrome onto Stack/`aside`/`main`. Nested `color={2}` footer strip; Separators divide actions. Prefer Surface `overflow` over inline style.</notes>
+  </example>
+
+  <example title="Hover section card (sidebar)">
+    <tsx><![CDATA[
+<Stack hPadding="m">
+  <Surface color={2} hoverColor={3} radius="m" vPadding="s">
+    <Stack rowGap="s" hPadding="m" vPadding={[0, 's']}>
+      <Stack direction="row" vAlign="center" hAlign="space-between" columnGap="s">
+        <Stack direction="row" vAlign="center" columnGap="s">
+          {/* section icon */}
+          <Text size="xs" weight="semibold">
+            Colors
+          </Text>
+        </Stack>
+        {/* trailing addon */}
+      </Stack>
+      <Text tone="muted" size="s">
+        Brand seed and highlight scales.
+      </Text>
+    </Stack>
+    <Stack rowGap="m" hPadding="s" vPadding="xs">
+      {/* controls */}
+    </Stack>
+  </Surface>
+</Stack>
+]]></tsx>
+    <notes>From `editor/sidebar/sidebar-section`. Resting `color={2}` + `hoverColor={3}` for pointer hover. Stack owns header/body spacing.</notes>
+  </example>
+
+  <example title="Preferences panel">
+    <tsx><![CDATA[
+<Surface overflow="hidden" border="all" color={1} radius="l">
+  <Stack rowGap="m">
+    <Stack rowGap="m" hPadding="m" vPadding="m">
+      <Stack columnGap="s" direction="row" hAlign="space-between" vAlign="start">
+        <Stack rowGap="xs">
+          <Title size="6" render={<h2 />}>
+            Preferences
+          </Title>
+          <Text size="s" maxWidth="18rem" tone="muted">
+            Manage your account settings and notifications.
+          </Text>
+        </Stack>
+        <IconButton aria-label="Close" icon={<Xmark />} size="s" variant="secondary" />
+      </Stack>
+
+      <Select label="Default Currency" value="usd">
+        <Select.Option value="usd">United States Dollar</Select.Option>
+        <Select.Option value="eur">Euro</Select.Option>
+      </Select>
+
+      <Surface vPadding="m">
+        <Switch label="Public Statistics" description="Allow others to see activity" />
+      </Surface>
+      <Surface vPadding="m">
+        <Switch label="Email Notifications" description="Monthly reports and updates" />
+      </Surface>
+    </Stack>
+
+    <Surface color={2} hPadding="l" vPadding="m">
+      <Stack columnGap="m" direction="row" hAlign="space-between" vAlign="center">
+        <Button variant="secondary">Reset</Button>
+        <Button>Save Preferences</Button>
+      </Stack>
+    </Surface>
+  </Stack>
+</Surface>
+]]></tsx>
+    <notes>From `editor/preview-grid/blocks/preferences`. Card shell + padded body + tinted footer strip. Inner Surfaces pad Switch rows without inventing layout CSS.</notes>
+  </example>
+
+  <example title="Code block chrome">
+    <tsx><![CDATA[
+<Surface data-vibrant radius="m" border="all" overflow="hidden">
+  <Stack direction="row" hAlign="end" hPadding="xs" vPadding="xs">
+    <ToggleButton
+      aria-label="Copy to clipboard"
+      restingIcon={<Duplicate aria-hidden />}
+      pressedIcon={<CircleCheck aria-hidden color="var(--highlight-green)" />}
+      interpolateIcons
+      data-vibrant
+      variant="secondary"
+    />
+  </Stack>
+  <pre>
+    <code>{`button {
+  border-radius: var(--radius-m);
+}`}</code>
+  </pre>
+</Surface>
+]]></tsx>
+    <notes>From `common/code-block`. Frosted bordered shell; toolbar is Stack. Drop highlighter/theme state — Surface owns chrome only.</notes>
   </example>
 </patterns>

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

@@ -50,43 +50,43 @@
   <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>Resting surface background on the root.</description>
-  </css_var>
-  <css_var suffix="background-hover">
+  </prop>
+  <prop name="background-hover" kind="css">
     <description>Hover surface background on the root.</description>
-  </css_var>
-  <css_var suffix="border-radius">
+  </prop>
+  <prop name="border-radius" kind="css">
     <description>Uniform corner radius when radius is a single token.</description>
-  </css_var>
-  <css_var suffix="border-radius-bottom-left">
+  </prop>
+  <prop name="border-radius-bottom-left" kind="css">
     <description>Bottom-left corner radius; radius tuple or auto resolves per corner.</description>
-  </css_var>
-  <css_var suffix="border-radius-bottom-right">
+  </prop>
+  <prop name="border-radius-bottom-right" kind="css">
     <description>Bottom-right corner radius; radius tuple or auto resolves per corner.</description>
-  </css_var>
-  <css_var suffix="border-radius-top-left">
+  </prop>
+  <prop name="border-radius-top-left" kind="css">
     <description>Top-left corner radius; radius tuple or auto resolves per corner.</description>
-  </css_var>
-  <css_var suffix="border-radius-top-right">
+  </prop>
+  <prop name="border-radius-top-right" kind="css">
     <description>Top-right corner radius; radius tuple or auto resolves per corner.</description>
-  </css_var>
-  <css_var suffix="border-style">
+  </prop>
+  <prop name="border-style" kind="css">
     <description>Border style when border is enabled.</description>
-  </css_var>
-  <css_var suffix="overflow">
+  </prop>
+  <prop name="overflow" kind="css">
     <description>Root overflow behavior.</description>
-  </css_var>
-  <css_var suffix="padding-block-end">
+  </prop>
+  <prop name="padding-block-end" kind="css">
     <description>Block-end padding when padding is enabled.</description>
-  </css_var>
-  <css_var suffix="padding-block-start">
+  </prop>
+  <prop name="padding-block-start" kind="css">
     <description>Block-start padding when padding is enabled.</description>
-  </css_var>
-  <css_var suffix="padding-inline-end">
+  </prop>
+  <prop name="padding-inline-end" kind="css">
     <description>Inline-end padding when padding is enabled.</description>
-  </css_var>
-  <css_var suffix="padding-inline-start">
+  </prop>
+  <prop name="padding-inline-start" kind="css">
     <description>Inline-start padding when padding is enabled.</description>
-  </css_var>
+  </prop>
 </props>

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

@@ -1,16 +1,19 @@
 <?xml version="1.0" encoding="UTF-8"?>
 <usage surface="surface">
-  <do>Group content with base-level background and contrast border</do>
+  <do>Group content with base-level background and contrast border — nest Stack for child gaps (Surface has no gap prop)</do>
+  <do>Login/signup shell: Surface (or `Stack render={&lt;Surface … /&gt;}`) hosts Tabs + Textfield(s) + Button (+ optional Fieldset) — chrome + layout via props, 0 custom CSS</do>
+  <do>Accept Stack as host via their `render={&lt;Surface … /&gt;}` so border/fill/radius share one DOM node — prefer over inventing chrome CSS (see package pattern `stack-as-surface`)</do>
+  <do>Settings / preferences panels: Surface card + Stack body + Switch/Checkbox rows (optionally padded inner Surfaces) + Button footer strip</do>
   <do>Frosted glass panels with `data-vibrant` — omit `color` for page-level shell or pass `color` for a tinted fill</do>
-  <do>Popup or card chrome with optional hover background</do>
-  <do>Compose with Elevator for animated elevation transitions</do>
-  <do>Set radius to a token on the outermost Surface that needs rounded corners</do>
-  <do>Set radius to a four-value tuple [top-left, top-right, bottom-right, bottom-left] when corners need different token radii</do>
-  <do>Set radius=&quot;auto&quot; on a nested Surface when its parent Surface has a radius so each corner subtracts the nearest ancestor padding and stays concentric</do>
-  <do>Stack nested auto-radius Surfaces recursively; context still resolves through wrapper layout such as Stack</do>
-  <dont>Overwriting transition shorthand without composing box-shadow when data-elevation is present</dont>
-  <dont>Assuming hoverColor applies on touch devices</dont>
-  <dont>Reusing the parent token radius on nested Surfaces instead of radius=&quot;auto&quot; when concentric corners are required</dont>
-  <dont>Expecting radius=&quot;auto&quot; to inherit a token when the nearest ancestor Surface has no radius set</dont>
-  <dont>Using viewport media queries when @container surface queries against the rendered Surface inline-size would match the design intent</dont>
+  <do>Compose with Elevator for animated elevation — Surface has no `elevation` prop</do>
+  <do>Inset content with `hPadding` / `vPadding` — nest Stack/Grid for child gaps</do>
+  <do>Set `radius` to a token (or four-value tuple) on the outermost Surface that needs rounded corners; `radius=&quot;auto&quot;` on nested Surfaces for concentric corners</do>
+  <dont>Passing `elevation={…}` on Surface — wrap with Elevator / `getElevationProps`</dont>
+  <dont>Inventing CSS `padding` / `gap` on this root when public padding props (and nested Stack) cover it</dont>
+  <dont>Inventing `width: 100%` on Surface when a parent Stack `fullWidth` can own the fill</dont>
+  <dont>Overwriting transition shorthand without composing box-shadow when `data-elevation` is present</dont>
+  <dont>Assuming `hoverColor` applies on touch devices</dont>
+  <dont>Reusing the parent token radius on nested Surfaces instead of `radius=&quot;auto&quot;` when concentric corners are required</dont>
+  <dont>Expecting `radius=&quot;auto&quot;` to inherit a token when the nearest ancestor Surface has no radius set</dont>
+  <dont>Using viewport media queries when `@container surface` against this Surface&apos;s inline-size matches the design intent</dont>
 </usage>

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

@@ -1,7 +1,77 @@
 <?xml version="1.0" encoding="UTF-8"?>
 <patterns surface="switch">
-  <example title="Switch structure">
-    <tsx><![CDATA[<Switch label="…" />]]></tsx>
-    <notes>Public assembly hint from legacy guide; not API authority.</notes>
+  <!-- Sources: viraui-app / design-kitchen preview-grid — cleaned (no handlers, no studio store). -->
+
+  <example title="Preferences rows">
+    <tsx><![CDATA[
+<Surface overflow="hidden" border="all" color={1} radius="l">
+  <Stack rowGap="m" hPadding="m" vPadding="m">
+    <Stack rowGap="xs">
+      <Title size="6" render={<h2 />}>
+        Preferences
+      </Title>
+      <Text size="s" maxWidth="18rem" tone="muted">
+        Manage your account settings and notifications.
+      </Text>
+    </Stack>
+
+    <Surface vPadding="m">
+      <Switch
+        checked
+        label="Public Statistics"
+        description="Allow others to see activity"
+      />
+    </Surface>
+    <Surface vPadding="m">
+      <Switch
+        checked
+        label="Email Notifications"
+        description="Monthly reports and updates"
+      />
+    </Surface>
+  </Stack>
+</Surface>
+]]></tsx>
+    <notes>From `editor/preview-grid/blocks/preferences`. Labeled Switch with `description` in a padded Surface row — settings on/off, not a toolbar toggle.</notes>
+  </example>
+
+  <example title="Effect card (padded small)">
+    <tsx><![CDATA[
+<Surface border="all" radius="s" color={1}>
+  <Switch
+    label="Shadows"
+    description="Elevate interactive surfaces"
+    checked
+    vPadding="m"
+    hPadding="m"
+    size="s"
+  />
+</Surface>
+]]></tsx>
+    <notes>From `editor/controls/effect-toggles/effect-toggle`. Switch owns padding via `hPadding`/`vPadding`; Surface is border chrome only. Prefer `size="s"` for dense editor lists.</notes>
+  </example>
+
+  <example title="Header power switch">
+    <tsx><![CDATA[
+<Stack columnGap="m" direction="row" hAlign="space-between" vAlign="start">
+  <Stack rowGap="xs">
+    <Title size="6" render={<h2 />}>
+      Studio EQ
+    </Title>
+    <Text size="s" tone="muted">
+      7-band output equalizer
+    </Text>
+  </Stack>
+  <Switch aria-label="Enable equalizer" checked />
+</Stack>
+]]></tsx>
+    <notes>From `editor/preview-grid/blocks/equalizer` (+ `kitchen-island`). Icon-free header control — unlabeled Switch needs `aria-label`. Kitchen Island omits aria-label in app (prefer always naming unlabeled switches).</notes>
+  </example>
+
+  <example title="Disabled on nested surface">
+    <tsx><![CDATA[
+<Switch checked disabled label="Dark shipping mode" />
+]]></tsx>
+    <notes>From `editor/preview-grid/blocks/disabled-surface-contrast`. Pair with surrounding Surface color steps to verify disabled contrast.</notes>
   </example>
 </patterns>

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

@@ -27,22 +27,22 @@
   <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="thumb-background">
+  <prop name="thumb-background" kind="css">
     <description>Switch thumb background color.</description>
-  </css_var>
-  <css_var suffix="thumb-inset">
+  </prop>
+  <prop name="thumb-inset" kind="css">
     <description>Inset between thumb and track edges.</description>
-  </css_var>
-  <css_var suffix="thumb-size">
+  </prop>
+  <prop name="thumb-size" kind="css">
     <description>Switch thumb size derived from track block size.</description>
-  </css_var>
-  <css_var suffix="track-background">
+  </prop>
+  <prop name="track-background" kind="css">
     <description>Switch track background color.</description>
-  </css_var>
-  <css_var suffix="track-block-size">
+  </prop>
+  <prop name="track-block-size" kind="css">
     <description>Switch track block size; size presets adjust track and thumb.</description>
-  </css_var>
-  <css_var suffix="track-radius">
+  </prop>
+  <prop name="track-radius" kind="css">
     <description>Switch track corner radius.</description>
-  </css_var>
+  </prop>
 </props>

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

@@ -1,8 +1,13 @@
 <?xml version="1.0" encoding="UTF-8"?>
 <usage surface="switch">
-  <do>Boolean on/off settings with optional label and helper text</do>
-  <do>Compact small or medium track sizes</do>
-  <do>Invalid and disabled states with Textfield-parity focus treatment</do>
-  <dont>Rendering a switch without label and without aria-label</dont>
-  <dont>Expecting description to stay visible when invalid without an error message</dont>
+  <do>Boolean on/off settings with Switch `label` and optional `description` — Switch owns its Field.Root (name/invalid/disabled pass through)</do>
+  <do>Preferences panels — Surface + Stack rows of labeled Switches (padding via Switch `hPadding`/`vPadding` or a padded Surface host)</do>
+  <do>Settings row with external copy — Stack `direction=&quot;row&quot;` `hAlign=&quot;space-between&quot;` + Text/Title stack + Switch; unlabeled Switch needs `aria-label`</do>
+  <do>Compact tracks with `size=&quot;s&quot;` or `size=&quot;m&quot;` (default `s`)</do>
+  <do>Pair with Checkbox when the choice is multi-select or a form boolean, not an immediate on/off setting</do>
+  <dont>Rendering a switch without `label` and without `aria-label`</dont>
+  <dont>Expecting `description` to stay visible when invalid without an `error` message</dont>
+  <dont>Expecting size or variant beyond medium and small</dont>
+  <dont>Wrapping Switch in another Field.Root — Switch already renders Field.Root</dont>
+  <dont>Inventing row layout CSS when Stack `direction=&quot;row&quot;` / `hAlign=&quot;space-between&quot;` covers the settings row</dont>
 </usage>

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

@@ -1,14 +1,119 @@
 <?xml version="1.0" encoding="UTF-8"?>
 <patterns surface="tabs">
-  <example title="Tabs structure">
-    <tsx><![CDATA[<Tabs>
+  <!-- Sources: viraui-app/components + preview-grid — cleaned (no handlers, no app-only chrome). Compound parts: Tabs, Tabs.List, Tabs.Tab, Tabs.Viewport, Tabs.Panel. -->
+
+  <example title="Export preview tabs (CSS / JSONC)">
+    <tsx><![CDATA[
+<Tabs defaultValue="css">
   <Tabs.List>
-    <Tabs.Tab value="a">…</Tabs.Tab>
+    <Tabs.Tab value="css">CSS</Tabs.Tab>
+    <Tabs.Tab value="jsonc">JSONC</Tabs.Tab>
   </Tabs.List>
   <Tabs.Viewport>
-    <Tabs.Panel value="a">…</Tabs.Panel>
+    <Tabs.Panel value="css">
+      <Stack vPadding="m">{/* code preview */}</Stack>
+    </Tabs.Panel>
+    <Tabs.Panel value="jsonc">
+      <Stack vPadding="m">{/* code preview */}</Stack>
+    </Tabs.Panel>
   </Tabs.Viewport>
-</Tabs>]]></tsx>
-    <notes>Public assembly hint from legacy guide; not API authority.</notes>
+</Tabs>
+]]></tsx>
+    <notes>From `editor/export-dialog`. Canonical compound order: List → Tab(s), then Viewport → Panel(s) with matching `value`. Drop Suspense/`inert`/snap-point chrome from this hint.</notes>
+  </example>
+
+  <example title="Clone repository (stretch list)">
+    <tsx><![CDATA[
+<Surface border="all" color={1} radius="xl" hPadding="m" vPadding="m" overflow="hidden">
+  <Tabs defaultValue="local" listAlignment="stretch">
+    <Tabs.List>
+      <Tabs.Tab value="codespaces">Codespaces</Tabs.Tab>
+      <Tabs.Tab value="local">Local</Tabs.Tab>
+    </Tabs.List>
+
+    <Tabs.Viewport>
+      <Tabs.Panel value="codespaces">
+        <Stack vPadding="m" expandChildren>
+          <Surface border="all" color={2} radius="l" hPadding="m" vPadding="l">
+            <Text tone="muted">Create a cloud workspace from this repository.</Text>
+          </Surface>
+        </Stack>
+      </Tabs.Panel>
+
+      <Tabs.Panel value="local">
+        <Stack vPadding={['m', 0]} rowGap="m" expandChildren>
+          <Surface border="all" radius="m" hPadding="m" vPadding="m">
+            <Stack rowGap="m">
+              <Textfield
+                aria-label="Repository clone URL"
+                readOnly
+                value="https://github.com/vira-soft/vira-ui.git"
+                endAddon={<Duplicate size={16} />}
+              />
+              <Text tone="muted">Clone using the web URL.</Text>
+            </Stack>
+          </Surface>
+
+          <Stack hAlign="start" rowGap="2xs">
+            <Button addon={<CircleImage size={18} />} variant="flat" size="s">
+              Open with GitHub Desktop
+            </Button>
+            <Button addon={<ArrowDown size={18} />} variant="flat" size="s">
+              Download ZIP
+            </Button>
+          </Stack>
+        </Stack>
+      </Tabs.Panel>
+    </Tabs.Viewport>
+  </Tabs>
+</Surface>
+]]></tsx>
+    <notes>From preview-grid `clone-repository`. `listAlignment="stretch"` fills the list chrome. Prefer Surface `overflow` prop over inline style.</notes>
+  </example>
+
+  <example title="Category tabs (prompts)">
+    <tsx><![CDATA[
+<Tabs defaultValue="landing">
+  <Tabs.List>
+    <Tabs.Tab value="landing">Landing pages</Tabs.Tab>
+    <Tabs.Tab value="application">Applications</Tabs.Tab>
+    <Tabs.Tab value="ecommerce">E-Commerce</Tabs.Tab>
+  </Tabs.List>
+  <Tabs.Viewport>
+    <Tabs.Panel value="landing">{/* info / empty state */}</Tabs.Panel>
+    <Tabs.Panel value="application">
+      <Text>Applications</Text>
+    </Tabs.Panel>
+    <Tabs.Panel value="ecommerce">
+      <Text>E-Commerce</Text>
+    </Tabs.Panel>
+  </Tabs.Viewport>
+</Tabs>
+]]></tsx>
+    <notes>From `prompts/prompts-tabs`. Same List/Viewport/Panel assembly. Drop `disabled` demo flags unless the product truly locks a tab.</notes>
+  </example>
+
+  <example title="Tab addons (start / end)">
+    <tsx><![CDATA[
+<Tabs defaultValue="general">
+  <Tabs.List>
+    <Tabs.Tab addon={<Quickstart />} value="general">
+      General
+    </Tabs.Tab>
+    <Tabs.Tab addon={<Chip variant="green">New</Chip>} addonPosition="end" value="billing">
+      Billing
+    </Tabs.Tab>
+    <Tabs.Tab addon={<MoonStars />} value="goals">
+      Goals
+    </Tabs.Tab>
+  </Tabs.List>
+  <Tabs.Viewport>
+    <Tabs.Panel value="general">{/* … */}</Tabs.Panel>
+    <Tabs.Panel value="billing">{/* … */}</Tabs.Panel>
+    <Tabs.Panel value="goals">{/* … */}</Tabs.Panel>
+  </Tabs.Viewport>
+</Tabs>
+]]></tsx>
+    <notes>From `tabs` stories (addon coverage). `Tab.addon` / `addonPosition` are decorative — keep visible text as the accessible label; do not use addon-only tabs.</notes>
   </example>
 </patterns>

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

@@ -18,7 +18,7 @@
   <prop name="Tab.addonPosition" kind="react">
     <description>Controls whether the addon appears before or after the label.</description>
   </prop>
-  <css_var suffix="translate-amount">
+  <prop name="translate-amount" kind="css">
     <description>Panel entry translate distance for tab transitions.</description>
-  </css_var>
+  </prop>
 </props>

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

@@ -1,8 +1,12 @@
 <?xml version="1.0" encoding="UTF-8"?>
 <usage surface="tabs">
-  <do>Switching between related views in the same surface</do>
-  <do>Compact horizontal segmented navigation</do>
-  <do>Decorative start/end addons on tab labels without changing accessible names</do>
+  <do>Switch related views in one surface — not primary app routes or link nav</do>
+  <do>Login/signup (or similar) form swap: wrap Tabs in Surface; panels hold Stack with Textfield(s) + Button (+ optional Fieldset) — use Stack `rowGap` / `fullWidth` / `expandChildren` and Textfield `fullWidth`; invent 0 width/gap CSS</do>
+  <do>Compound order: `Tabs.List` → `Tabs.Tab`(s), then `Tabs.Viewport` → `Tabs.Panel`(s) with matching `value`</do>
+  <do>Fill list chrome with `listAlignment=&quot;stretch&quot;`; center/end via `listAlignment` on the root</do>
+  <do>Decorative `Tab` `addon` / `addonPosition` beside a visible text label</do>
   <dont>Using addons as the only visible label for a tab</dont>
   <dont>Trying to compose a separate public `Tabs.Indicator`; the indicator is owned by `Tabs.List`</dont>
+  <dont>Inventing panel width/gap/padding CSS when Stack inside `Tabs.Panel` can own spacing and fill</dont>
+  <dont>Vertical tab layouts in v1 styled targets</dont>
 </usage>