@viraui/react 2026.5.0 → 2026.6.1

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

@@ -19,13 +19,13 @@
   <prop name="renderValue" kind="react">
     <description>Shows the current value beside the label. Pass `true` for Base UI default formatting, or a function matching `Meter.Value` `children` to customize the printed label.</description>
   </prop>
-  <css_var suffix="indicator-color">
+  <prop name="indicator-color" kind="css">
     <description>Determinate meter indicator color.</description>
-  </css_var>
-  <css_var suffix="track-background">
+  </prop>
+  <prop name="track-background" kind="css">
     <description>Meter track background color.</description>
-  </css_var>
-  <css_var suffix="track-size">
+  </prop>
+  <prop name="track-size" kind="css">
     <description>Meter track thickness on the root.</description>
-  </css_var>
+  </prop>
 </props>

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

@@ -1,10 +1,13 @@
 <?xml version="1.0" encoding="UTF-8"?>
 <usage surface="meter">
-  <do>Use for storage usage, battery level, capacity, or score within a known range.</do>
-  <do>Use with a label when the metric needs a visible name.</do>
-  <do>Use with `renderValue` when the formatted value should appear beside the label.</do>
-  <dont>Do not use Meter as an interactive value control.</dont>
-  <dont>Do not use Meter for indeterminate or in-progress work.</dont>
-  <dont>Do not hide the metric label when multiple meters are visible.</dont>
-  <dont>Do not model invalid or disabled meter state; Base UI Meter does not expose those states.</dont>
+  <do>Static capacity / level / score within a known range: storage, battery, quota, health — always a numeric `value`</do>
+  <do>Labeled metrics: `label` + `renderValue` + optional `description`; tune print with Base UI `format` / `locale`</do>
+  <do>Workspace stacks: Stack `rowGap` of Meters — or nest one Meter inside Surface for sheet / tip chrome</do>
+  <do>Rich labels: pass a Stack row (icon + text) as `label` when needed — no custom label CSS</do>
+  <do>Prefer LinearProgress for in-progress or indeterminate tasks (`value={null}`) — Meter has no indeterminate mode</do>
+  <dont>Using Meter as an interactive value control — use Slider</dont>
+  <dont>Using Meter for indeterminate or in-progress work — use LinearProgress</dont>
+  <dont>Modeling invalid or disabled meter state — Base UI Meter exposes neither</dont>
+  <dont>Hiding the metric name when multiple meters share a view</dont>
+  <dont>Passing `value={null}` — Meter `value` is required `number`</dont>
 </usage>

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

@@ -1,15 +1,124 @@
 <?xml version="1.0" encoding="UTF-8"?>
 <patterns surface="popover">
-  <example title="Popover structure">
-    <tsx><![CDATA[<Popover>
-  <Popover.Trigger />
+  <!-- Sources: viraui-app/components + design-kitchen preview-grid — cleaned (no handlers, no portal/preview chrome). -->
+
+  <example title="Notifications sheet">
+    <tsx><![CDATA[
+<Popover>
+  <Popover.Trigger render={<Button variant="secondary">Options</Button>} />
+  <Popover.Sheet title="Options" description="Choose an action">
+    <Stack rowGap="m">
+      <Text render={<p />}>Notification preferences and workspace shortcuts live here.</Text>
+      <Popover.Close render={<Button variant="flat">Done</Button>} />
+    </Stack>
+  </Popover.Sheet>
+</Popover>
+]]></tsx>
+    <notes>Default styled Sheet: Trigger + titled Sheet + body + `Popover.Close`. Portal/Positioner/Popup stay inside Sheet.</notes>
+  </example>
+
+  <example title="Color field picker">
+    <tsx><![CDATA[
+<Popover>
+  <Popover.Trigger
+    nativeButton={false}
+    render={
+      <Textfield
+        readOnly
+        label="Primary"
+        value="oklch(0.55 0.18 250)"
+        fullWidth
+        startAddon={<span aria-hidden style={{ background: 'oklch(0.55 0.18 250)' }} />}
+      />
+    }
+  />
+  <Popover.Sheet title="Pick a color" side="right" align="start">
+    <Stack rowGap="m">
+      {/* ColorArea / HueSlider / format inputs */}
+      <Text size="s" tone="muted">
+        Adjust hue, then commit from the inputs.
+      </Text>
+    </Stack>
+  </Popover.Sheet>
+</Popover>
+]]></tsx>
+    <notes>From `common/color-picker`. Non-button trigger via `nativeButton={false}` + Textfield `render`. Drop chromakit / module CSS from this hint.</notes>
+  </example>
+
+  <example title="Team directory (shared handle)">
+    <tsx><![CDATA[
+const handle = Popover.createHandle<{ name: string; role: string; bio: string; email: string }>();
+
+{/* …row triggers… */}
+<Popover.Trigger
+  handle={handle}
+  openOnHover
+  closeDelay={100}
+  nativeButton={false}
+  payload={member}
+  render={<Avatar alt={member.name} fallback="SC" size="s" src={member.src} />}
+/>
+<Popover.Trigger
+  handle={handle}
+  payload={member}
+  render={
+    <Button size="s" variant="secondary">
+      Details
+    </Button>
+  }
+/>
+
+<Popover handle={handle} open={true}>
+  {({ payload }) => {
+    if (!payload) return null;
+    return (
+      <Popover.Sheet
+        description={payload.role}
+        side="inline-end"
+        title={payload.name}
+        headerAlign="center"
+      >
+        <Stack rowGap="m" hAlign="center">
+          <Avatar alt={payload.name} fallback="SC" size="l" />
+          <Text align="center" tone="muted" size="s" lineHeight="s" maxWidth="25ch">
+            {payload.bio}
+          </Text>
+          <Text align="center" family="mono" size="s">
+            {payload.email}
+          </Text>
+          <Popover.Close
+            render={
+              <Button size="s" variant="secondary">
+                View profile
+              </Button>
+            }
+          />
+        </Stack>
+      </Popover.Sheet>
+    );
+  }}
+</Popover>
+]]></tsx>
+    <notes>From preview-grid `team-directory`. One `createHandle` + trigger `payload` morphs Sheet content. `open={true}` for demo structure.</notes>
+  </example>
+
+  <example title="Unstyled sheet chrome">
+    <tsx><![CDATA[
+<Popover open={true}>
+  <Popover.Trigger render={<Button>Custom chrome</Button>} />
   <Popover.Sheet unstyled>
-    <Popover.Title>…</Popover.Title>
-    <Popover.Description>…</Popover.Description>
-    …
-    <Popover.Close />
+    <Surface color={1} border="all" radius="l" hPadding="m" vPadding="m" data-vibrant>
+      <Stack rowGap="s">
+        <Popover.Title render={<Title size="6" lineHeight="xs" />}>Alpha panel</Popover.Title>
+        <Popover.Description render={<Text tone="muted" render={<p />} />}>
+          With `unstyled`, the consumer owns the popup chrome.
+        </Popover.Description>
+        <Popover.Close render={<Button size="s" variant="secondary">Close</Button>} />
+      </Stack>
+    </Surface>
   </Popover.Sheet>
-</Popover>]]></tsx>
-    <notes>Public assembly hint from legacy guide; not API authority.</notes>
+</Popover>
+]]></tsx>
+    <notes>From Popover stories `Unstyled`. `unstyled` skips built-in Surface/header — compose `Popover.Title` / `Popover.Description` for the accessible name.</notes>
   </example>
 </patterns>

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

@@ -31,7 +31,7 @@
   <prop name="Sheet.unstyled" kind="react">
     <description>Whether to skip the built-in Surface, header, and close chrome and render only the positioning/animation shell (Portal + Positioner + Popup + Viewport).</description>
   </prop>
-  <css_var suffix="content-fade-duration">
+  <prop name="content-fade-duration" kind="css">
     <description>content fade duration custom property on the component root.</description>
-  </css_var>
+  </prop>
 </props>

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

@@ -1,12 +1,13 @@
 <?xml version="1.0" encoding="UTF-8"?>
 <usage surface="popover">
-  <do>Anchored quick actions or contextual hints next to a triggering control</do>
-  <do>Lightweight forms or confirmations that float beside the trigger without blocking the page</do>
-  <do>Multi-trigger panels that swap content with direction-aware animations using `Popover.createHandle` and trigger `payload`</do>
-  <do>Hover-revealed hints via `openOnHover` with `delay` and `closeDelay`</do>
-  <do>Fully custom popup chrome via `Sheet` `unstyled` composed with `Popover.Title` and `Popover.Description`</do>
-  <do>Custom portal host (iframe preview, shadow root, or app overlay root) via `container` on the portal-owning public part</do>
-  <dont>Opening a popover without `title` copy for assistive technologies</dont>
-  <dont>Rendering heavy or scroll-bound content that belongs in a Dialog</dont>
+  <do>Anchored quick actions, lightweight forms, or contextual hints beside a trigger — not page-blocking sheets (Dialog) or command lists (Menu)</do>
+  <do>Compose `Popover.Trigger` + titled `Popover.Sheet` + body Stack / Text / Button; close with `Popover.Close`</do>
+  <do>Non-button triggers via `nativeButton={false}` + `render` (e.g. Textfield or Avatar)</do>
+  <do>Multi-trigger content morph: `Popover.createHandle` + trigger `payload` (optional `openOnHover` / `delay` / `closeDelay`)</do>
+  <do>Custom popup chrome with `Sheet` `unstyled` + consumer Surface/Stack + `Popover.Title` / `Popover.Description`</do>
+  <do>Custom portal host (iframe preview, shadow root, or app overlay root) via `container` on `Popover.Sheet`</do>
+  <dont>Opening a popover without `title` copy (styled Sheet) or `Popover.Title` (`unstyled`) for assistive technologies</dont>
+  <dont>Rendering heavy, scroll-bound, or nested drill-down content that belongs in Dialog</dont>
+  <dont>Wrapping Menu for account/action lists — Menu already owns portal, positioning, and list keyboard behavior</dont>
   <dont>Expecting `Popover.Arrow` (it is intentionally not exported or rendered)</dont>
 </usage>

package/dist/specs/components/progressive-blur/meta.xml

@@ -1,6 +1,6 @@
 <?xml version="1.0" encoding="UTF-8"?>
 <meta id="progressive-blur" title="ProgressiveBlur" category="effect" shared_contract="progressive-blur">
-  <summary>Decorative stacked backdrop-filter overlay that ramps blur from one edge toward the opposite edge.</summary>
+  <summary>Decorative stacked backdrop-filter overlay that ramps blur from one edge toward the opposite edge. GPU/memory-heavy — use sparingly; prefer one focal instance per view.</summary>
   <exports>
     <export name="ProgressiveBlur" />
   </exports>

package/dist/specs/components/progressive-blur/patterns.xml

@@ -1,7 +1,4 @@
 <?xml version="1.0" encoding="UTF-8"?>
 <patterns surface="progressive-blur">
-  <example title="ProgressiveBlur structure">
-    <tsx><![CDATA[<ProgressiveBlur />]]></tsx>
-    <notes>Public assembly hint from legacy guide; not API authority.</notes>
-  </example>
+  <!-- Skip: zero viraui-app and design-kitchen usage. Stories are fixed overlay / prop matrix demos — no teachable Vira composition extract. -->
 </patterns>

package/dist/specs/components/progressive-blur/props.xml

@@ -22,7 +22,7 @@
   <prop name="steps" kind="react">
     <description>Sets the number of internal blur layers. Values are clamped to `2..16`.</description>
   </prop>
-  <css_var suffix="amount">
+  <prop name="amount" kind="css">
     <description>Sets the maximum blur radius applied to the first layer at the selected edge.</description>
-  </css_var>
+  </prop>
 </props>

package/dist/specs/components/progressive-blur/usage.xml

@@ -1,10 +1,11 @@
 <?xml version="1.0" encoding="UTF-8"?>
 <usage surface="progressive-blur">
-  <do>Edge scrims on cards, sheets, heroes, or scroll regions where content should fade into blur</do>
-  <do>Glass or vibrant surfaces that need directional legibility without a hard blur cutoff</do>
-  <do>Decorative atmosphere where the parent owns semantics and layout positioning</do>
-  <dont>Stacking many full-viewport ProgressiveBlur instances on one screen</dont>
-  <dont>Driving layout size or scroll behavior from inside the overlay component</dont>
-  <dont>Embedding layout positioning rules inside the component stylesheet</dont>
+  <do>Overlay on a Surface or Stack region the parent owns — parent sets non-static `position`, inset, size, and z-index; ProgressiveBlur does not create a containing block</do>
+  <do>Edge scrim on glass / `data-vibrant` Surface heroes, sheets, or scroll regions where content should fade into blur</do>
+  <do>Keep semantics and layout on Surface/Stack/Title/Text children underneath — ProgressiveBlur is decorative atmosphere only</do>
+  <do>Use sparingly — stacked `backdrop-filter` is GPU/memory-heavy; prefer one focal overlay per view</do>
   <dont>Leaving the ProgressiveBlur root `position: static` so absolute layers escape the intended overlay box</dont>
+  <dont>Driving layout size or scroll behavior from inside the overlay</dont>
+  <dont>Scattering ProgressiveBlur across many cards or stacking full-viewport instances</dont>
+  <dont>Using ProgressiveBlur as standalone loading or status feedback without a labeled parent region</dont>
 </usage>

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

@@ -1,9 +1,59 @@
 <?xml version="1.0" encoding="UTF-8"?>
 <patterns surface="radio">
-  <example title="Radio structure">
-    <tsx><![CDATA[<RadioGroup>
-  <Radio value="…" label="…" />
-</RadioGroup>]]></tsx>
-    <notes>Public assembly hint from legacy guide; not API authority.</notes>
+  <!-- Sources: viraui-app / design-kitchen preview-grid — cleaned (no handlers, no selection-driven color CSS). -->
+  <!-- Compound: Radio lives inside RadioGroup (exported from this folder). Group legend/copy → Field.Root + Fieldset render={&lt;RadioGroup /&gt;}. -->
+
+  <example title="Card option RadioGroup">
+    <tsx><![CDATA[
+<Field.Root name="receiving-method">
+  <Fieldset label="Receiving Method" render={<RadioGroup value="bank-transfer" />}>
+    <Stack columnGap="m" vAlign="start" direction="row" expandChildren>
+      <Surface border="all" radius="s" color={2}>
+        <Radio
+          description="SWIFT / IBAN"
+          label="Bank Transfer"
+          value="bank-transfer"
+          hPadding="m"
+          vPadding="m"
+        />
+      </Surface>
+      <Surface border="all" radius="s">
+        <Radio
+          description="Instant Payout"
+          label="PayPal"
+          value="paypal"
+          hPadding="m"
+          vPadding="m"
+        />
+      </Surface>
+    </Stack>
+  </Fieldset>
+</Field.Root>
+]]></tsx>
+    <notes>From `editor/preview-grid/blocks/payout-preferences`. `Fieldset render={&lt;RadioGroup /&gt;}` owns the group; each `Radio` sits in a Surface card with `hPadding`/`vPadding`. App may tint the selected card — pattern shows the selected Surface already `color={2}`.</notes>
+  </example>
+
+  <example title="Compact Fieldset group">
+    <tsx><![CDATA[
+<Field.Root name="mode">
+  <Fieldset label="Mode" render={<RadioGroup value="manual" />}>
+    <Radio label="Auto" value="auto" />
+    <Radio label="Manual" value="manual" />
+  </Fieldset>
+</Field.Root>
+]]></tsx>
+    <notes>From `editor/preview-grid/blocks/disabled-surface-contrast` (enabled shape). Shared legend via Fieldset; RadioGroup stacks options with default `rowGap`. Add `disabled` on Field.Root / Fieldset / RadioGroup together when showing disabled contrast.</notes>
+  </example>
+
+  <example title="Disabled Fieldset RadioGroup">
+    <tsx><![CDATA[
+<Field.Root disabled name="mode">
+  <Fieldset disabled label="Mode" render={<RadioGroup disabled value="manual" />}>
+    <Radio label="Auto" value="auto" />
+    <Radio label="Manual" value="manual" />
+  </Fieldset>
+</Field.Root>
+]]></tsx>
+    <notes>From `editor/preview-grid/blocks/disabled-surface-contrast`. Mirror `disabled` on Field.Root, Fieldset, and RadioGroup so the whole set greys out on nested Surfaces.</notes>
   </example>
 </patterns>

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

@@ -29,16 +29,16 @@
   <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>Radio control background color.</description>
-  </css_var>
-  <css_var suffix="border-color">
+  </prop>
+  <prop name="border-color" kind="css">
     <description>Radio control border color; resting default is transparent (same as Checkbox); checked, invalid, and disabled states override.</description>
-  </css_var>
-  <css_var suffix="indicator-color">
+  </prop>
+  <prop name="indicator-color" kind="css">
     <description>Radio selected-disk indicator color.</description>
-  </css_var>
-  <css_var suffix="size">
+  </prop>
+  <prop name="size" kind="css">
     <description>Radio control size; size presets adjust footprint.</description>
-  </css_var>
+  </prop>
 </props>

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

@@ -1,12 +1,15 @@
 <?xml version="1.0" encoding="UTF-8"?>
 <usage surface="radio">
-  <do>Single selection from a small set of related options inside RadioGroup</do>
+  <do>Single selection from a small related set — always nest Radio inside RadioGroup</do>
   <do>RadioGroup alone inside Field.Root when each Radio has its own label and no shared group legend is needed</do>
-  <do>Field.Root &gt; Fieldset render={&lt;RadioGroup&lt;Value&gt; /&gt;} when the group needs a shared legend, description, or error</do>
-  <do>Card-style or custom layouts where each option is wrapped in Surface or consumer markup</do>
+  <do>Shared legend, group description, or group error — Field.Root &gt; Fieldset render={&lt;RadioGroup&lt;Value&gt; /&gt;} with Radio children</do>
+  <do>Card-style options — wrap each Radio in Surface `border=&quot;all&quot;` (optional `color` on the selected card); Radio owns `hPadding`/`vPadding`; lay cards in Stack `direction=&quot;row&quot;` `expandChildren`</do>
   <do>Typed option unions with RadioGroup&lt;&apos;ssd&apos; | &apos;hdd&apos;&gt; for value, defaultValue, and onValueChange safety</do>
   <dont>Rendering Radio outside RadioGroup</dont>
-  <dont>Putting invalid or error on a single Radio instead of the enclosing Field.Root and Fieldset</dont>
-  <dont>Omitting the RadioGroup generic when option value props form a restricted union</dont>
-  <dont>Importing @viraui/react/radio/radio.css or other component CSS subpaths in consumer bootstrap</dont>
+  <dont>Putting `invalid` or group `error` on a single Radio — use enclosing Field.Root and Fieldset</dont>
+  <dont>Omitting the RadioGroup generic when option values form a restricted union</dont>
+  <dont>Assuming Fieldset is mandatory for every RadioGroup — add it only for shared legend or group copy</dont>
+  <dont>Independent booleans or multi-select — use Checkbox / CheckboxGroup or Switch</dont>
+  <dont>Inventing card border/gap CSS when Surface `border` and Stack gap/`expandChildren` cover the layout</dont>
+  <dont>Importing `@viraui/react/radio/radio.css` or other component CSS subpaths in consumer bootstrap</dont>
 </usage>

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

@@ -1,13 +1,129 @@
 <?xml version="1.0" encoding="UTF-8"?>
 <patterns surface="select">
-  <example title="Select structure">
-    <tsx><![CDATA[<Select>
-  <Select.Option value="…">…</Select.Option>
-  <Select.Group label="…">
-    <Select.Option value="…">…</Select.Option>
-  </Select.Group>
+  <!-- Sources: viraui-app controls + preview-grid — cleaned (no handlers, Controllers, i18n). Trigger/Portal baked in root — use Select.Option / Group / Separator only. -->
+
+  <example title="Labeled currency list">
+    <tsx><![CDATA[
+<Select label="Preferred Currency" defaultValue="usd" items={currencyOptions}>
+  <Select.Option value="usd">United States Dollar</Select.Option>
+  <Select.Option value="eur">Euro</Select.Option>
+  <Select.Option value="gbp">British Pound</Select.Option>
+</Select>
+]]></tsx>
+    <notes>From preview-grid `payout-threshold`. Flat options under root; no `Select.Trigger` — chrome is baked.</notes>
+  </example>
+
+  <example title="Address pair with Textfield">
+    <tsx><![CDATA[
+<Stack columnGap="m" direction="row" expandChildren>
+  <Textfield label="City" defaultValue="San Francisco" />
+  <Select label="State" defaultValue="california" items={stateOptions}>
+    <Select.Option value="california">California</Select.Option>
+    <Select.Option value="new-york">New York</Select.Option>
+    <Select.Option value="texas">Texas</Select.Option>
+  </Select>
+</Stack>
+]]></tsx>
+    <notes>From preview-grid `shipping-address`. Row `expandChildren` shares width with sibling Textfield.</notes>
+  </example>
+
+  <example title="Invite role beside email">
+    <tsx><![CDATA[
+<Stack columnGap="s" direction="row" vAlign="end" expandChildren>
+  <Textfield aria-label="Invite email" defaultValue="alex@example.com" />
+  <Select aria-label="Invite role" defaultValue="editor" alignListWithTrigger items={teamRoleOptions}>
+    <Select.Option value="editor">Editor</Select.Option>
+    <Select.Option value="viewer">Viewer</Select.Option>
+    <Select.Option value="admin">Admin</Select.Option>
+  </Select>
+</Stack>
+]]></tsx>
+    <notes>From preview-grid `invite-team`. `alignListWithTrigger` keeps popup width with trigger; `vAlign="end"` lines up with unlabeled Textfield.</notes>
+  </example>
+
+  <example title="Order type with description">
+    <tsx><![CDATA[
+<Select
+  label="Order Type"
+  defaultValue="market-order"
+  items={orderTypeOptions}
+  alignListWithTrigger
+  description="Market orders execute at the current price."
+>
+  <Select.Option value="market-order">Market Order</Select.Option>
+  <Select.Option value="limit-order">Limit Order</Select.Option>
+</Select>
+]]></tsx>
+    <notes>From preview-grid `buy-investment`. Field helper via `description` prop.</notes>
+  </example>
+
+  <example title="Corner shape with custom trigger addon">
+    <tsx><![CDATA[
+<Select
+  label="Corner shape"
+  defaultValue="round"
+  items={cornerShapeItems}
+  alignListWithTrigger={false}
+  addon={<ChevronExpandY aria-hidden size="1rem" />}
+>
+  <Select.Option value="round">Round</Select.Option>
+  <Select.Option value="squircle">Squircle</Select.Option>
+  <Select.Option value="bevel">Bevel</Select.Option>
+</Select>
+]]></tsx>
+    <notes>From `editor/controls/corner-shape-select`. Root `addon` replaces default chevron chrome; prefer `alignListWithTrigger={false}` when options get leading adornment.</notes>
+  </example>
+
+  <example title="Scale list with Separator">
+    <tsx><![CDATA[
+<Select label="Radius scale" defaultValue="default" items={scaleItems} alignListWithTrigger={false}>
+  <Select.Option value="default">Default</Select.Option>
   <Select.Separator />
-</Select>]]></tsx>
-    <notes>Public assembly hint from legacy guide; not API authority.</notes>
+  <Select.Option value="compact">Compact</Select.Option>
+  <Select.Option value="comfortable">Comfortable</Select.Option>
+  <Select.Option value="spacious">Spacious</Select.Option>
+</Select>
+]]></tsx>
+    <notes>From `editor/controls/scale-control`. `Select.Separator` after the theme-default option.</notes>
+  </example>
+
+  <example title="Grouped regions">
+    <tsx><![CDATA[
+<Select label="Preferred currency" placeholder="Select currency" items={currencyItems}>
+  <Select.Group label="Europe">
+    <Select.Option value="eur">Euro</Select.Option>
+    <Select.Option value="gbp">British Pound</Select.Option>
+  </Select.Group>
+  <Select.Group label="Americas">
+    <Select.Option value="usd">US Dollar</Select.Option>
+    <Select.Option value="cad">Canadian Dollar</Select.Option>
+  </Select.Group>
+</Select>
+]]></tsx>
+    <notes>From Select stories `Grouped`. `Select.Group` takes required `label`; options nest inside.</notes>
+  </example>
+
+  <example title="Option with leading addon">
+    <tsx><![CDATA[
+<Select label="Primary color" defaultValue="blue" items={primaryItems} alignListWithTrigger={false}>
+  <Select.Option value="blue" addon={<Stack direction="row" columnGap="2xs">{/* swatches */}</Stack>}>
+    Blue
+  </Select.Option>
+  <Select.Option value="custom" addon={<EyeDropper aria-hidden size={10} />}>
+    Custom
+  </Select.Option>
+</Select>
+]]></tsx>
+    <notes>From `editor/controls/primary-color-select` (+ option). Leading `Select.Option` `addon` is decorative; keep `alignListWithTrigger={false}`.</notes>
+  </example>
+
+  <example title="Disabled on surface">
+    <tsx><![CDATA[
+<Select disabled label="Role" defaultValue="editor">
+  <Select.Option value="editor">Editor</Select.Option>
+  <Select.Option value="viewer">Viewer</Select.Option>
+</Select>
+]]></tsx>
+    <notes>From preview-grid `disabled-surface-contrast`. Disabled root + options; no portal props in the hint.</notes>
   </example>
 </patterns>

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

@@ -53,31 +53,31 @@
   <prop name="ref" kind="react">
     <description>Ref forwarded to the select trigger button.</description>
   </prop>
-  <css_var suffix="control-group-background">
+  <prop name="control-group-background" kind="css">
     <description>Trigger background fill.</description>
-  </css_var>
-  <css_var suffix="control-group-border-color">
+  </prop>
+  <prop name="control-group-border-color" kind="css">
     <description>Trigger border color; invalid state overrides.</description>
-  </css_var>
-  <css_var suffix="control-group-border-radius">
+  </prop>
+  <prop name="control-group-border-radius" kind="css">
     <description>Trigger corner radius.</description>
-  </css_var>
-  <css_var suffix="control-group-color">
+  </prop>
+  <prop name="control-group-color" kind="css">
     <description>Trigger text and icon color.</description>
-  </css_var>
-  <css_var suffix="input-height">
+  </prop>
+  <prop name="input-height" kind="css">
     <description>Select trigger block size.</description>
-  </css_var>
-  <css_var suffix="list-border-radius">
+  </prop>
+  <prop name="list-border-radius" kind="css">
     <description>list border radius custom property on the component root.</description>
-  </css_var>
-  <css_var suffix="list-padding">
+  </prop>
+  <prop name="list-padding" kind="css">
     <description>list padding custom property on the component root.</description>
-  </css_var>
-  <css_var suffix="trigger-padding-inline-end">
+  </prop>
+  <prop name="trigger-padding-inline-end" kind="css">
     <description>Trigger inline-end padding.</description>
-  </css_var>
-  <css_var suffix="trigger-padding-inline-start">
+  </prop>
+  <prop name="trigger-padding-inline-start" kind="css">
     <description>Trigger inline-start padding.</description>
-  </css_var>
+  </prop>
 </props>

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

@@ -1,14 +1,15 @@
 <?xml version="1.0" encoding="UTF-8"?>
 <usage surface="select">
-  <do>Choose one value from a predefined list with label and helper copy</do>
-  <do>Grouped or separated option lists</do>
-  <do>Rich option rows with a leading decorative addon and multi-line label content</do>
-  <do>Trigger chrome aligned with Textfield control shell</do>
-  <do>Select fields inside Fieldset when they share a section legend with other inputs</do>
+  <do>Choose one value from a predefined closed list with label and helper copy</do>
+  <do>Prefer Select over Autocomplete when the value must be one of the options (no free-form text)</do>
+  <do>Form section: Fieldset legend + Select beside Textfield/Textarea siblings — Stack owns gap</do>
+  <do>Equal-width rows with Textfield (city/state, email + role): parent Stack `direction=&quot;row&quot;` + `expandChildren` — Select has no `fullWidth` prop</do>
+  <do>Span a form column via a parent Stack `fullWidth` — not CSS `width: 100%` on the Select root</do>
+  <do>Grouped or separated option lists via `Select.Group` / `Select.Separator`; rich rows via `Select.Option` `addon`</do>
   <do>Custom portal host (iframe preview, shadow root, or app overlay root) via `container` on the portal-owning public part</do>
-  <dont>Expecting multi-select or combobox behavior</dont>
-  <dont>Leaving the trigger without label or aria-label</dont>
-  <dont>Never set the size prop (if present) of Buttons, IconButtons or other interactive elements passed as addon other than small</dont>
-  <dont>Using the Select component as a combobox, use Autocomplete instead.</dont>
-  <dont>Leaving alignListWithTrigger enabled when options have a leading addon</dont>
+  <dont>Expecting multi-select, free-form filter, or combobox behavior — use Autocomplete for suggest + free text</dont>
+  <dont>Leaving the trigger without `label` or `aria-label`</dont>
+  <dont>Inventing `width: 100%` / `w-full` CSS on Select when a parent Stack `fullWidth` / `expandChildren` can own the fill</dont>
+  <dont>Leaving `alignListWithTrigger` enabled when options have a leading addon — prefer `alignListWithTrigger={false}`</dont>
+  <dont>Wrapping a lone Select in Fieldset when its own label is enough</dont>
 </usage>