@viraui/react 2026.5.0 → 2026.6.1

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

@@ -52,37 +52,37 @@
   <prop name="zIndex" kind="react">
     <description>Stacking order for arrow and note via `--vui-annotate-z-index`. Same value on both parts.</description>
   </prop>
-  <css_var suffix="arrow-x">
+  <prop name="arrow-x" kind="css">
     <description>Horizontal arrow offset.</description>
-  </css_var>
-  <css_var suffix="arrow-y">
+  </prop>
+  <prop name="arrow-y" kind="css">
     <description>Vertical arrow offset.</description>
-  </css_var>
-  <css_var suffix="color">
+  </prop>
+  <prop name="color" kind="css">
     <description>Arrow, note, and mark accent color. Defaults to var(--global-foreground).</description>
-  </css_var>
-  <css_var suffix="label-gap">
+  </prop>
+  <prop name="label-gap" kind="css">
     <description>Gap between arrow and note on all sides.</description>
-  </css_var>
-  <css_var suffix="label-max-width">
+  </prop>
+  <prop name="label-max-width" kind="css">
     <description>Max width for the note part.</description>
-  </css_var>
-  <css_var suffix="rotate">
+  </prop>
+  <prop name="rotate" kind="css">
     <description>Note rotation angle.</description>
-  </css_var>
-  <css_var suffix="target-gap">
+  </prop>
+  <prop name="target-gap" kind="css">
     <description>Gap between the target and the arrow.</description>
-  </css_var>
-  <css_var suffix="text-align">
+  </prop>
+  <prop name="text-align" kind="css">
     <description>Text alignment for the note. Defaults to start.</description>
-  </css_var>
-  <css_var suffix="text-x">
+  </prop>
+  <prop name="text-x" kind="css">
     <description>Legacy horizontal note offset custom property. Prefer textOffsetX from React.</description>
-  </css_var>
-  <css_var suffix="text-y">
+  </prop>
+  <prop name="text-y" kind="css">
     <description>Legacy vertical note offset custom property. Prefer textOffsetY from React.</description>
-  </css_var>
-  <css_var suffix="z-index">
+  </prop>
+  <prop name="z-index" kind="css">
     <description>Stacking order for arrow and note. Defaults to auto.</description>
-  </css_var>
+  </prop>
 </props>

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

@@ -1,10 +1,11 @@
 <?xml version="1.0" encoding="UTF-8"?>
 <usage surface="annotate">
-  <do>Call out a word or phrase in marketing, docs, or onboarding copy</do>
-  <do>Add a playful visual annotation without interactive chrome</do>
-  <do>Highlight a target with an optional mark while keeping children as the real content</do>
-  <dont>Using note as the only source of instructions or status</dont>
-  <dont>Nesting Annotate inside overflow-hidden parents without padding for the arrow</dont>
+  <do>Wrap a Button CTA, a Surface graphic (QR / icon tile), or an inline phrase inside Text/Title — children stay the real content</do>
+  <do>Compose onboarding / empty-state callouts inside Stack + Surface shells with Title/Text/Button for the labeled instructions</do>
+  <do>Add optional `mark` highlighter behind the wrapped phrase while keeping `note` decorative</do>
+  <dont>Putting critical instructions or status only in `note` — assistive tech does not announce it; put that copy in Text/Title/Button</dont>
+  <dont>Using Annotate instead of Tooltip/Popover when focus, hover, or keyboard behavior is required</dont>
+  <dont>Nesting Annotate inside `overflow: hidden` parents without room for the arrow and label</dont>
+  <dont>Adding `position: relative` on Annotate — it breaks CSS anchor `position-area` placement</dont>
   <dont>Expecting the label to participate in hit-testing or selection</dont>
-  <dont>Adding position:relative on Annotate — it breaks CSS anchor position-area placement</dont>
 </usage>

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

@@ -1,14 +1,130 @@
 <?xml version="1.0" encoding="UTF-8"?>
 <patterns surface="autocomplete">
-  <example title="Autocomplete structure">
-    <tsx><![CDATA[<Autocomplete>
-  <Autocomplete.Item value="…">…</Autocomplete.Item>
-  <Autocomplete.Group label="…" items={[…]}>
+  <!-- Sources: preview-grid autocomplete-search + editor font-autocomplete — cleaned (no handlers, Controllers, i18n, virtualizer CSS). Portal baked in root. -->
+
+  <example title="Teammate search with item addon">
+    <tsx><![CDATA[
+<Autocomplete
+  label="Assign reviewer"
+  description="Pick a teammate who can approve this payout batch."
+  empty="No teammates match that name."
+  placeholder="Search by name…"
+  items={reviewers}
+  itemToStringValue={(person) => person.label}
+  startAddon={<Magnifier aria-hidden size={16} />}
+>
+  {(person) => (
+    <Autocomplete.Item
+      key={person.id}
+      addon={<Avatar alt={person.label} fallback={person.fallback} size="s" src={person.src} />}
+      value={person}
+    >
+      {`${person.label} · ${person.role}`}
+    </Autocomplete.Item>
+  )}
+</Autocomplete>
+]]></tsx>
+    <notes>From preview-grid `autocomplete-search` AssignReviewer. List render fn + `Autocomplete.Item` `addon`. Empty/status are root props — not child parts.</notes>
+  </example>
+
+  <example title="Free-form category suggest">
+    <tsx><![CDATA[
+<Autocomplete
+  label="Expense category"
+  description="Suggest a ledger category — free-form text stays allowed."
+  empty="No category match. Keep typing to create a custom label."
+  placeholder="SaaS, travel, contractors…"
+  items={expenseCategories}
+  itemToStringValue={(category) => category.label}
+  startAddon={<Magnifier aria-hidden size={16} />}
+>
+  {(category) => (
+    <Autocomplete.Item key={category.id} value={category}>
+      {category.label}
+    </Autocomplete.Item>
+  )}
+</Autocomplete>
+]]></tsx>
+    <notes>From preview-grid `autocomplete-search` ExpenseCategory. Flat items; free-form input is the Autocomplete default.</notes>
+  </example>
+
+  <example title="Grouped desks with Collection">
+    <tsx><![CDATA[
+<Autocomplete
+  label="Transfer desk"
+  description="Route an urgent payout to the desk covering that region."
+  empty="No transfer desk matches."
+  placeholder="Paris, Austin, Singapore…"
+  items={transferDesks}
+  itemToStringValue={(desk) => desk.label}
+  startAddon={<Magnifier aria-hidden size={16} />}
+>
+  {(group) => (
+    <Autocomplete.Group key={group.value} items={group.items} label={group.value}>
+      <Autocomplete.Collection>
+        {(desk) => (
+          <Autocomplete.Item key={desk.id} value={desk}>
+            {`${desk.label} · ${desk.hours}`}
+          </Autocomplete.Item>
+        )}
+      </Autocomplete.Collection>
+    </Autocomplete.Group>
+  )}
+</Autocomplete>
+]]></tsx>
+    <notes>From preview-grid `autocomplete-search` TransferDesk. Grouped `items` + `Autocomplete.Group` / `Collection` — public parts only.</notes>
+  </example>
+
+  <example title="Async status + empty">
+    <tsx><![CDATA[
+<Autocomplete
+  label="Search help center"
+  description="Async docs search."
+  empty="No articles for that query."
+  filter={null}
+  items={results}
+  itemToStringValue={(article) => article.title}
+  placeholder="Wire limits, SEPA, tax forms…"
+  startAddon={<Magnifier aria-hidden size={16} />}
+  status={
+    <Stack columnGap="s" direction="row" vAlign="center">
+      <Spinner aria-hidden size="s" />
+      <Text size="xs" tone="muted">
+        Searching help center…
+      </Text>
+    </Stack>
+  }
+>
+  {(article) => (
+    <Autocomplete.Item key={article.id} value={article}>
+      {`${article.title} · ${article.section}`}
+    </Autocomplete.Item>
+  )}
+</Autocomplete>
+]]></tsx>
+    <notes>From preview-grid `autocomplete-search` HelpCenter. Keep `status` mounted; update children when pending/error. `filter={null}` when filtering outside.</notes>
+  </example>
+
+  <example title="Suggested fonts Group">
+    <tsx><![CDATA[
+<Autocomplete
+  label="Heading font"
+  empty="No fonts match."
+  items={suggested}
+  itemToStringValue={(font) => font.family}
+  openOnInputClick
+>
+  <Autocomplete.Group label="Suggested" items={suggested}>
     <Autocomplete.Collection>
-      {(item) => <Autocomplete.Item value={item}>…</Autocomplete.Item>}
+      {(font) => (
+        <Autocomplete.Item key={font.id} value={font}>
+          {font.family}
+        </Autocomplete.Item>
+      )}
     </Autocomplete.Collection>
   </Autocomplete.Group>
-</Autocomplete>]]></tsx>
-    <notes>Public assembly hint from legacy guide; not API authority.</notes>
+</Autocomplete>
+]]></tsx>
+    <notes>From `editor/controls/font-picker/font-autocomplete` browse mode. Suggested group via `Group` + `Collection`; drop virtualizer / preview dwell from the hint.</notes>
   </example>
 </patterns>

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

@@ -57,25 +57,25 @@
   <prop name="status" kind="react">
     <description>Content rendered inside baked `Autocomplete.Status` (async / limit messaging). Keep the slot mounted; update children when status changes.</description>
   </prop>
-  <css_var suffix="control-group-background">
+  <prop name="control-group-background" kind="css">
     <description>Autocomplete control group background.</description>
-  </css_var>
-  <css_var suffix="control-group-border-color">
+  </prop>
+  <prop name="control-group-border-color" kind="css">
     <description>Autocomplete control group 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>Autocomplete control group corner radius.</description>
-  </css_var>
-  <css_var suffix="control-group-color">
+  </prop>
+  <prop name="control-group-color" kind="css">
     <description>Autocomplete control group foreground color.</description>
-  </css_var>
-  <css_var suffix="input-height">
+  </prop>
+  <prop name="input-height" kind="css">
     <description>Autocomplete control group block size.</description>
-  </css_var>
-  <css_var suffix="list-border-radius">
+  </prop>
+  <prop name="list-border-radius" kind="css">
     <description>Popup list border radius custom property on the popup root.</description>
-  </css_var>
-  <css_var suffix="list-padding">
+  </prop>
+  <prop name="list-padding" kind="css">
     <description>Popup list padding custom property used for scroll padding.</description>
-  </css_var>
+  </prop>
 </props>

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

@@ -1,11 +1,16 @@
 <?xml version="1.0" encoding="UTF-8"?>
 <usage surface="autocomplete">
   <do>Suggest options while allowing free-form text in the input</do>
-  <do>Filterable tag, movie, or docs search with optional empty and status copy</do>
-  <do>Grouped suggestion lists via Autocomplete.Group and Collection</do>
-  <do>Async or limited result lists that need polite status announcements</do>
+  <do>Prefer Autocomplete over Select when users may type a value not in the list (tags, categories, search)</do>
+  <do>Form section: Fieldset legend + Autocomplete with sibling Textfield/Select when they share one section — Stack owns gap</do>
+  <do>Fill a form column via a parent Stack `fullWidth` / `expandChildren` (Autocomplete has no `fullWidth` prop) — not CSS `width: 100%`</do>
+  <do>`startAddon` / `endAddon` for leading/trailing chrome (same control-group pattern as Textfield) — IconButton/Button addons use `size=&quot;s&quot;` and `type=&quot;button&quot;`</do>
+  <do>Grouped suggestion lists via `Autocomplete.Group` + `Autocomplete.Collection`; item rows via `Autocomplete.Item` `addon` (e.g. Avatar)</do>
+  <do>Async or limited result lists: pass `empty` for no-match copy; keep root `status` mounted and update its children — Spinner + Text inside `status` is fine</do>
   <do>Custom portal host (iframe preview, shadow root, or app overlay root) via `container` on the portal-owning public part</do>
-  <dont>Expecting Select-like closed selection state</dont>
-  <dont>Leaving the input without label or aria-label</dont>
-  <dont>Conditionally unmounting Empty or Status instead of updating their children</dont>
+  <dont>Expecting Select-like closed selection from a fixed list — use Select when the value must be one of the options</dont>
+  <dont>Leaving the input without `label` or `aria-label`</dont>
+  <dont>Conditionally dropping the `status` prop instead of updating its children — baked Status stays mounted</dont>
+  <dont>Inventing `width: 100%` / `w-full` CSS on Autocomplete when a parent Stack can own the fill</dont>
+  <dont>Wrapping a lone Autocomplete in Fieldset when its own label is enough</dont>
 </usage>

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

@@ -1,7 +1,82 @@
 <?xml version="1.0" encoding="UTF-8"?>
 <patterns surface="avatar">
-  <example title="Avatar structure">
-    <tsx><![CDATA[<Avatar fallback="AB" />]]></tsx>
-    <notes>Public assembly hint from legacy guide; not API authority.</notes>
+  <!-- Sources: viraui-app/components — cleaned (no handlers, no portal chrome, no app-only state). -->
+
+  <example title="Autocomplete item addon">
+    <tsx><![CDATA[
+<Autocomplete
+  empty="No teammates match that name."
+  itemToStringValue={(person) => person.label}
+  items={reviewers}
+  label="Assign reviewer"
+  placeholder="Search by name…"
+>
+  {(person) => (
+    <Autocomplete.Item
+      key={person.id}
+      addon={<Avatar alt={person.label} fallback={person.fallback} size="s" src={person.src} />}
+      value={person}
+    >
+      {`${person.label} · ${person.role}`}
+    </Autocomplete.Item>
+  )}
+</Autocomplete>
+]]></tsx>
+    <notes>From `editor/preview-grid/blocks/autocomplete-search` AssignReviewerField. Small Avatar as Autocomplete.Item `addon`. Drop portal props and controlled value handlers.</notes>
+  </example>
+
+  <example title="Account menu profile row">
+    <tsx><![CDATA[
+<Stack columnGap="s" direction="row" vAlign="center">
+  <Avatar alt="Maya Chen" fallback="MC" size="s" src="https://example.com/maya.jpg" />
+  <Stack rowGap="s">
+    <Text weight="semibold">Maya Chen</Text>
+    <Text size="s" tone="muted">
+      maya@ledger.io
+    </Text>
+  </Stack>
+</Stack>
+]]></tsx>
+    <notes>From `editor/preview-grid/blocks/menu-account` ProfileSummary. Compact row: Avatar + name/email column. Use `size="m"` in the open menu header copy of the same cluster.</notes>
+  </example>
+
+  <example title="Directory list row">
+    <tsx><![CDATA[
+<Surface color={2} radius="m" hPadding="m" vPadding="m">
+  <Stack columnGap="m" direction="row" hAlign="space-between" vAlign="center">
+    <Stack columnGap="m" direction="row" vAlign="center">
+      <Avatar alt="Sarah Chen" fallback="SC" size="s" src="https://example.com/sarah.jpg" />
+      <Stack rowGap="xs">
+        <Text weight="semibold">Sarah Chen</Text>
+        <Text size="s" tone="muted">
+          Product Design
+        </Text>
+      </Stack>
+    </Stack>
+    <Button size="s" variant="secondary">
+      Details
+    </Button>
+  </Stack>
+</Surface>
+]]></tsx>
+    <notes>From `editor/preview-grid/blocks/team-directory` row. Leading Avatar + text column + trailing action. Drop Popover/Badge/Tooltip kitchen chrome from this hint.</notes>
+  </example>
+
+  <example title="Profile sheet hero">
+    <tsx><![CDATA[
+<Stack rowGap="m" hAlign="center">
+  <Avatar alt="Sarah Chen" fallback="SC" size="l" src="https://example.com/sarah.jpg" />
+  <Text align="center" render={<p />} tone="muted" size="s" lineHeight="s" maxWidth="25ch">
+    Leads design systems and interaction patterns across the portfolio experience.
+  </Text>
+  <Text align="center" family="mono" size="s">
+    sarah@ledger.io
+  </Text>
+  <Button size="s" variant="secondary">
+    View profile
+  </Button>
+</Stack>
+]]></tsx>
+    <notes>From `editor/preview-grid/blocks/team-directory` Popover.Sheet body. Large Avatar as profile hero. Drop shared Popover handle / portal wiring.</notes>
   </example>
 </patterns>

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

@@ -23,16 +23,16 @@
   <prop name="src" kind="react">
     <description>Supplies the avatar image source URL.</description>
   </prop>
-  <css_var suffix="background">
+  <prop name="background" kind="css">
     <description>Root background fill behind image or fallback.</description>
-  </css_var>
-  <css_var suffix="foreground">
+  </prop>
+  <prop name="foreground" kind="css">
     <description>Root foreground color for fallback content.</description>
-  </css_var>
-  <css_var suffix="radius">
+  </prop>
+  <prop name="radius" kind="css">
     <description>Corner radius on the root; size presets also adjust this.</description>
-  </css_var>
-  <css_var suffix="size">
+  </prop>
+  <prop name="size" kind="css">
     <description>Avatar inline and block size on the root.</description>
-  </css_var>
+  </prop>
 </props>

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

@@ -1,7 +1,13 @@
 <?xml version="1.0" encoding="UTF-8"?>
 <usage surface="avatar">
-  <do>Show a user or entity photo with text or image fallback</do>
-  <do>Display profile chips from xs through large sizes</do>
+  <do>Show a user or entity photo with `src`, `alt`, and `fallback` (initials or icon)</do>
+  <do>Pick footprint with `size` (`xs`–`l`) — not child layout or custom width CSS</do>
+  <do>Profile row: Stack row + Avatar + Text column (name / muted email)</do>
+  <do>Account menu: Avatar inside `Menu.Trigger` chip (Stack/button + Text); wrap Menu in Surface for chrome — Menu owns popup, do not nest in Popover</do>
+  <do>Presence: wrap Avatar in Badge with `show` + `color`; keep name/role in nearby Text</do>
+  <do>List pickers: small Avatar as Autocomplete.Item / Select option `addon`</do>
+  <do>Directory / sheet hero: Avatar + Text (+ Button) inside Surface or Stack — size `l` for hero, `s` for rows</do>
+  <dont>Treating Avatar as a control — put Menu, Popover, or Button around it when the row is interactive</dont>
+  <dont>Omitting meaningful `alt` when the image conveys identity</dont>
   <dont>Relying on Avatar children for layout sizing</dont>
-  <dont>Omitting meaningful alt text when the image conveys identity</dont>
 </usage>

package/dist/specs/components/avatar-group/patterns.xml

@@ -1,7 +1,69 @@
 <?xml version="1.0" encoding="UTF-8"?>
 <patterns surface="avatar-group">
-  <example title="AvatarGroup structure">
-    <tsx><![CDATA[<AvatarGroup avatars={[{ fallback: "AB" }]} />]]></tsx>
-    <notes>Public assembly hint from legacy guide; not API authority.</notes>
+  <!-- Sources: viraui-app/components — cleaned (no handlers, no kitchen Annotate/Badge chrome). -->
+
+  <example title="Contributors with overflow">
+    <tsx><![CDATA[
+<Surface overflow="hidden" border="all" color={1} radius="l">
+  <Stack rowGap="m" hPadding="m" vPadding="m">
+    <Title size="6" render={<h2 />}>
+      Contributors
+    </Title>
+    <AvatarGroup
+      avatars={[
+        { alt: 'Contributor 1', fallback: 'A', src: 'https://example.com/a.jpg' },
+        { alt: 'Contributor 2', fallback: 'B', src: 'https://example.com/b.jpg' },
+        { alt: 'Contributor 3', fallback: 'C', src: 'https://example.com/c.jpg' },
+        { alt: 'Contributor 4', fallback: 'D', src: 'https://example.com/d.jpg' },
+        { alt: 'Contributor 5', fallback: 'E', src: 'https://example.com/e.jpg' },
+        { alt: 'Contributor 6', fallback: 'F', src: 'https://example.com/f.jpg' },
+        { alt: 'Contributor 7', fallback: 'G', src: 'https://example.com/g.jpg' },
+        { alt: 'Contributor 8', fallback: 'H', src: 'https://example.com/h.jpg' },
+        { alt: 'Contributor 9', fallback: 'I', src: 'https://example.com/i.jpg' },
+        { alt: 'Contributor 10', fallback: 'J', src: 'https://example.com/j.jpg' },
+        { alt: 'Contributor 11', fallback: 'K', src: 'https://example.com/k.jpg' },
+        { alt: 'Contributor 12', fallback: 'L', src: 'https://example.com/l.jpg' },
+        { alt: 'Contributor 13', fallback: 'M', src: 'https://example.com/m.jpg' },
+        { alt: 'Contributor 14', fallback: 'N', src: 'https://example.com/n.jpg' },
+      ]}
+      maxVisible={13}
+      overflowText="+810"
+      size="s"
+    />
+  </Stack>
+</Surface>
+]]></tsx>
+    <notes>From `editor/preview-grid/blocks/contributors`. Pass `overflowText` explicitly — AvatarGroup does not derive hidden-count labels. Shared `size` on the group; never per-avatar sizes.</notes>
+  </example>
+
+  <example title="Empty team invite cluster">
+    <tsx><![CDATA[
+<Surface border="all" color={1} radius="l" hPadding="m" vPadding="m">
+  <Stack
+    rowGap="m"
+    hPadding="l"
+    vPadding="2xl"
+    hAlign="center"
+    render={<Surface border="all" borderStyle="dashed" radius="l" />}
+  >
+    <AvatarGroup
+      avatars={[
+        { alt: 'Team member one', fallback: 'AL', src: 'https://example.com/al.jpg' },
+        { alt: 'Team member two', fallback: 'MR', src: 'https://example.com/mr.jpg' },
+        { alt: 'Team member three', fallback: 'EV', src: 'https://example.com/ev.jpg' },
+      ]}
+      size="m"
+    />
+    <Title align="center" size="5" render={<h3 />}>
+      No Team Members
+    </Title>
+    <Text size="s" align="center" maxWidth="14rem" tone="muted">
+      Invite your team to collaborate on this project.
+    </Text>
+    <Button>Invite Members</Button>
+  </Stack>
+</Surface>
+]]></tsx>
+    <notes>From `editor/preview-grid/blocks/empty-team`. Medium AvatarGroup as empty-state media. Replaced inline dashed border style with `Stack render={&lt;Surface borderStyle="dashed" …/&gt;}`. Drop Annotate/Badge kitchen chrome.</notes>
   </example>
 </patterns>

package/dist/specs/components/avatar-group/props.xml

@@ -24,16 +24,16 @@
   <prop name="size" kind="react">
     <description>Selects the shared avatar footprint for every rendered avatar.</description>
   </prop>
-  <css_var suffix="gap-size">
+  <prop name="gap-size" kind="css">
     <description>Cutout gap used by overlap clip-path math.</description>
-  </css_var>
-  <css_var suffix="item-radius">
+  </prop>
+  <prop name="item-radius" kind="css">
     <description>Corner radius applied to grouped avatar items.</description>
-  </css_var>
-  <css_var suffix="overlap-distance">
+  </prop>
+  <prop name="overlap-distance" kind="css">
     <description>Negative margin overlap between adjacent avatars.</description>
-  </css_var>
-  <css_var suffix="size">
+  </prop>
+  <prop name="size" kind="css">
     <description>Rendered avatar size used for overlap layout.</description>
-  </css_var>
+  </prop>
 </props>

package/dist/specs/components/avatar-group/usage.xml

@@ -1,10 +1,13 @@
 <?xml version="1.0" encoding="UTF-8"?>
 <usage surface="avatar-group">
-  <do>Show a compact list of people or entities with consistent avatar sizing</do>
-  <do>Display overlapping identity clusters in horizontal or vertical layouts</do>
-  <do>Collapse long avatar lists into a final overflow pill such as +15 or +9938</do>
-  <dont>Passing per-avatar size values instead of using the group size prop</dont>
-  <dont>Expecting AvatarGroup to derive hidden-count labels instead of passing overflowText directly</dont>
-  <dont>Expecting grouped avatars to always render as circles — items keep theme radius/squircle via --vui-avatar-group-item-radius</dont>
-  <dont>Using non-positive maxVisible values expecting truncation</dont>
+  <do>Show overlapping people/entity clusters with shared group `size` and `avatars` payloads</do>
+  <do>Choose overlap axis with `direction` (`horizontal` or `vertical`)</do>
+  <do>Truncate long lists: positive `maxVisible` plus explicit `overflowText` (e.g. `+15`) — group does not invent the count label</do>
+  <do>Empty / invite states: AvatarGroup + Title + Text + Button inside Surface (optional dashed Surface via Stack `render`)</do>
+  <do>Contributors strip: AvatarGroup under Title inside Surface — Stack `rowGap` / padding owns spacing</do>
+  <dont>Passing per-avatar `size` — group applies one shared size to every item</dont>
+  <dont>Expecting AvatarGroup to derive hidden-count labels instead of passing `overflowText`</dont>
+  <dont>Using non-positive `maxVisible` expecting truncation</dont>
+  <dont>Expecting grouped avatars to always render as circles — items keep theme radius/squircle via `--vui-avatar-group-item-radius`</dont>
+  <dont>Using AvatarGroup for interactive per-item actions — map Avatar rows with Menu/Button instead</dont>
 </usage>

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

@@ -1,7 +1,61 @@
 <?xml version="1.0" encoding="UTF-8"?>
 <patterns surface="badge">
-  <example title="Badge structure">
-    <tsx><![CDATA[<Badge>{child}</Badge>]]></tsx>
-    <notes>Public assembly hint from legacy guide; not API authority.</notes>
+  <!-- Sources: viraui-app / design-kitchen preview-grid — cleaned. Badge = status-dot overlay only; labeled tags use Chip. -->
+
+  <example title="CTA with attention dot">
+    <tsx><![CDATA[
+<Surface border="all" color={1} radius="l" hPadding="m" vPadding="m">
+  <Stack
+    rowGap="m"
+    hPadding="l"
+    vPadding="2xl"
+    hAlign="center"
+    render={<Surface border="all" borderStyle="dashed" radius="l" />}
+  >
+    <AvatarGroup
+      avatars={[
+        { alt: '', fallback: 'AL' },
+        { alt: '', fallback: 'MR' },
+        { alt: '', fallback: 'EV' },
+      ]}
+      size="m"
+    />
+    <Title align="center" size="5" render={<h3 />}>
+      No Team Members
+    </Title>
+    <Text size="s" align="center" maxWidth="14rem" tone="muted">
+      Invite your team to collaborate on this project.
+    </Text>
+    <Badge show color="green">
+      <Button>Invite Members</Button>
+    </Badge>
+  </Stack>
+</Surface>
+]]></tsx>
+    <notes>From `editor/preview-grid/blocks/empty-team`. Badge wraps Button; `show` + `color` drive the corner dot. Drop Annotate kitchen chrome. Meaning stays on the button label.</notes>
+  </example>
+
+  <example title="Avatar online indicator">
+    <tsx><![CDATA[
+<Badge color="green" show>
+  <Avatar alt="Sarah Chen" fallback="SC" size="s" src="…" />
+</Badge>
+]]></tsx>
+    <notes>From `editor/preview-grid/blocks/team-directory` member rows. Default position `top-end`. Dot is decorative — name/role live in nearby Text.</notes>
+  </example>
+
+  <example title="Control with notify dot">
+    <tsx><![CDATA[
+<Badge show color="yellow">
+  <ToggleButton
+    aria-label="Mute notifications"
+    restingIcon={<BellSlash />}
+    pressedIcon={<BellOn />}
+    size="s"
+    variant="secondary"
+  />
+</Badge>
+]]></tsx>
+    <notes>From `editor/preview-grid/blocks/team-directory` header. Yellow attention dot on a ToggleButton. App may toggle `show` with pressed state — pattern shows on state.</notes>
   </example>
 </patterns>

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

@@ -22,16 +22,16 @@
   <prop name="size" kind="react">
     <description>Diameter of the status dot via `--vui-badge-size`.</description>
   </prop>
-  <css_var suffix="color">
+  <prop name="color" kind="css">
     <description>Status-dot accent color. Defaults to var(--global-primary).</description>
-  </css_var>
-  <css_var suffix="position-x">
+  </prop>
+  <prop name="position-x" kind="css">
     <description>Horizontal status-dot anchor. Position presets set it to 0% for start or 100% for end.</description>
-  </css_var>
-  <css_var suffix="position-y">
+  </prop>
+  <prop name="position-y" kind="css">
     <description>Vertical status-dot anchor. Position presets set it to 0% for top or 100% for bottom.</description>
-  </css_var>
-  <css_var suffix="size">
+  </prop>
+  <prop name="size" kind="css">
     <description>Status-dot diameter. Defaults to 0.5rem.</description>
-  </css_var>
+  </prop>
 </props>