@adia-ai/web-components 0.6.20 → 0.6.22

package/components/agent-suggestions/agent-suggestions.yaml

@@ -6,7 +6,13 @@ tag: agent-suggestions-ui
 component: AgentSuggestions
 category: agent
 version: 1
-description: Row of follow-up suggestion chips.
+description: |
+  Row of follow-up suggestion chips presented under an agent response.
+  Each suggestion is a <button-ui> child the user can tap to send the
+  text back as the next prompt. Composes <button-ui> with chip-style
+  visual treatment; the variant + size props cascade to children. Use
+  to lower input friction at the bottom of a chat response; not for
+  permanent navigation (that's <nav-ui>).
 # Per ADR-0027 — primitives that programmatically create other primitives
 # do NOT auto-import them. Consumer (or demo shell) must explicitly import.
 composes:
@@ -50,7 +56,15 @@ states:
 traits: []
 tokens: {}
 a2ui:
-  rules: []
+  rules:
+    - rule: 'Row of follow-up suggestion chips presented under an agent response. User taps to send the chip text as the next prompt.'
+      reason: 'Follow-up pattern.'
+    - rule: 'Hosts <button-ui> children with chip-style variant; auto-applies variant if children don''t set one.'
+      reason: 'Composition behavior.'
+    - rule: 'Different from <agent-questions-ui> (required disambiguation) — suggestions are optional and the agent doesn''t wait.'
+      reason: 'Optional vs gating.'
+    - rule: 'Place at the end of an assistant message in <chat-thread-ui>; not for first-message empty-state suggestions (use <empty-state-ui>).'
+      reason: 'Surface scope.'
 anti_patterns: []
 examples:
   - name: basic
@@ -67,7 +81,8 @@ keywords:
   - chips
   - follow-up
   - quick replies
-synonyms: {}
+synonyms:
+  suggestions: [follow-ups, follow-up-chips, prompts, completions]
 related:
   - agent-questions-ui
   - agent-feedback-bar-ui

package/components/agent-trace/agent-trace.a2ui.json

@@ -2,7 +2,7 @@
   "$schema": "https://json-schema.org/draft/2020-12/schema",
   "$id": "https://adiaui.dev/a2ui/v0_9/components/AgentTrace.json",
   "title": "AgentTrace",
-  "description": "Collapsible metrics + training-feedback panel for an agent turn.",
+  "description": "Collapsible metrics + training-feedback panel for an agent turn. Shows reasoning steps, tool calls, latency, and token counts with a thumbs-up/down feedback affordance. Use inside <chat-thread-ui> message bodies for expert/debug views; hide by default in user-facing chat.",
   "type": "object",
   "allOf": [
     {
@@ -76,7 +76,14 @@
         "name": "idle"
       }
     ],
-    "synonyms": {},
+    "synonyms": {
+      "trace": [
+        "agent-trace",
+        "reasoning-trace",
+        "tool-trace",
+        "agent-log"
+      ]
+    },
     "tag": "agent-trace-ui",
     "tokens": {},
     "traits": [],

package/components/agent-trace/agent-trace.d.ts

@@ -1,5 +1,5 @@
 /**
- * `<agent-trace-ui>` — Collapsible metrics + training-feedback panel for an agent turn.
+ * `<agent-trace-ui>` — Collapsible metrics + training-feedback panel for an agent turn. Shows reasoning steps, tool calls, latency, and token counts with a thumbs-up/down feedback affordance. Use inside <chat-thread-ui> message bodies for expert/debug views; hide by default in user-facing chat.
  *
  * @see https://ui-kit.exe.xyz/site/components/agent-trace
  *

package/components/agent-trace/agent-trace.yaml

@@ -6,7 +6,11 @@ tag: agent-trace-ui
 component: AgentTrace
 category: agent
 version: 1
-description: Collapsible metrics + training-feedback panel for an agent turn.
+description: >-
+  Collapsible metrics + training-feedback panel for an agent turn. Shows
+  reasoning steps, tool calls, latency, and token counts with a
+  thumbs-up/down feedback affordance. Use inside <chat-thread-ui> message
+  bodies for expert/debug views; hide by default in user-facing chat.
 props:
   label:
     description: Fallback summary label.
@@ -36,7 +40,15 @@ requiredIcons:
   - caret-right
   - circle-fill
 a2ui:
-  rules: []
+  rules:
+    - rule: 'Collapsible metrics + training-feedback panel showing reasoning steps, tool calls, latency, and token counts.'
+      reason: 'Diagnostic surface.'
+    - rule: 'Place inside <chat-thread-ui> message bodies for expert/debug views; hide by default in user-facing chat.'
+      reason: 'Audience scope.'
+    - rule: 'Different from <agent-reasoning-ui> (narrative inner monologue) — agent-trace is structured metrics.'
+      reason: 'Structured vs narrative boundary.'
+    - rule: 'Default collapsed=true; expand-on-demand keeps chat-thread visual density low.'
+      reason: 'Density discipline.'
 anti_patterns: []
 examples:
   - name: basic
@@ -54,7 +66,8 @@ keywords:
   - confidence
   - telemetry
   - training feedback
-synonyms: {}
+synonyms:
+  trace: [agent-trace, reasoning-trace, tool-trace, agent-log]
 related:
   - agent-reasoning-ui
   - agent-feedback-bar-ui

package/components/alert/alert.a2ui.json

@@ -2,7 +2,7 @@
   "$schema": "https://json-schema.org/draft/2020-12/schema",
   "$id": "https://adiaui.dev/a2ui/v0_9/components/Alert.json",
   "title": "Alert",
-  "description": "Inline alert banner with optional icon and close button.",
+  "description": "Inline alert banner — a persistent, in-flow notice with icon +\ntitle + description + optional dismiss + slotted action. Variants\nmap to semantic severity (info / success / warning / danger).\nDistinct from <toast-ui> (transient global notification with\nauto-dismiss) and from <empty-state-ui> (zero-data placeholder).\nUse alert-ui for inline contextual notices the user should see\nbefore continuing — form-level errors, banner-style status,\ninline upgrade prompts.\n",
   "type": "object",
   "allOf": [
     {

package/components/alert/alert.css

@@ -99,6 +99,14 @@
     min-width: 0;
   }
 
+  /* Trailing action area — optional single button or small button group.
+     flex-shrink:0 keeps it from collapsing; align-self:start anchors it
+     to the first text line under the `align-items:start` root. */
+  :scope [slot="action"] {
+    flex-shrink: 0;
+    align-self: start;
+  }
+
   /* Close button is a `<button-ui icon="x" variant="ghost" size="sm">`
      stamped by alert.js — it brings its own focus ring, hover state,
      and transitions. Box height matches the leading slot so X and icon

package/components/alert/alert.d.ts

@@ -1,5 +1,13 @@
 /**
- * `<alert-ui>` — Inline alert banner with optional icon and close button.
+ * `<alert-ui>` — Inline alert banner — a persistent, in-flow notice with icon +
+title + description + optional dismiss + slotted action. Variants
+map to semantic severity (info / success / warning / danger).
+Distinct from <toast-ui> (transient global notification with
+auto-dismiss) and from <empty-state-ui> (zero-data placeholder).
+Use alert-ui for inline contextual notices the user should see
+before continuing — form-level errors, banner-style status,
+inline upgrade prompts.
+
  *
  * @see https://ui-kit.exe.xyz/site/components/alert
  *

package/components/alert/alert.yaml

@@ -6,7 +6,15 @@ tag: alert-ui
 component: Alert
 category: container
 version: 1
-description: Inline alert banner with optional icon and close button.
+description: |
+  Inline alert banner — a persistent, in-flow notice with icon +
+  title + description + optional dismiss + slotted action. Variants
+  map to semantic severity (info / success / warning / danger).
+  Distinct from <toast-ui> (transient global notification with
+  auto-dismiss) and from <empty-state-ui> (zero-data placeholder).
+  Use alert-ui for inline contextual notices the user should see
+  before continuing — form-level errors, banner-style status,
+  inline upgrade prompts.
 props:
   closable:
     description: >-
@@ -91,7 +99,13 @@ states:
 traits: []
 tokens: {}
 a2ui:
-  rules: []
+  rules:
+    - rule: 'Inline alert/banner for status messages within a content region. Severity via variant (info, success, warn, error).'
+      reason: 'Canonical inline-alert primitive.'
+    - rule: 'For ephemeral toast notifications use <toast-ui> (or post to <feed-ui>); alert-ui is persistent inline.'
+      reason: 'Ephemeral vs persistent boundary.'
+    - rule: 'For modal-style critical alerts use <modal-ui> with alert content.'
+      reason: 'Inline vs modal.'
 anti_patterns: []
 examples:
   - name: alert-banner

package/components/aside/aside.a2ui.json

@@ -76,7 +76,13 @@
         "name": "idle"
       }
     ],
-    "synonyms": {},
+    "synonyms": {
+      "aside": [
+        "side-region",
+        "side-panel-slot",
+        "secondary-rail"
+      ]
+    },
     "tag": "aside-ui",
     "tokens": {},
     "traits": [],

package/components/aside/aside.yaml

@@ -44,7 +44,37 @@ states:
 traits: []
 tokens: {}
 a2ui:
-  rules: []
+  rules:
+    - >-
+      Use <aside-ui> as a slot stub inside an IN-PAGE primitive
+      container parent (<card-ui>, <drawer-ui>, <modal-ui>, <page-ui>)
+      for two-column layouts with a semantic side region. It ships no
+      behavior; the parent reads [collapsible] and [width] via @scope.
+      Typical contents: <list-ui> / <tree-ui> / <nav-ui variant="section">.
+    - >-
+      Do NOT use <aside-ui> for app-shell sidebars. <admin-shell> no
+      longer reads <aside-ui slot="leading|trailing"> (retired in v0.4.0
+      per ADR-0024). Use the bespoke <admin-sidebar slot="leading|trailing"
+      collapsible resizable> with reflected [collapsed] / [resizing]
+      state. Same rule for <chat-sidebar> under <chat-shell> and
+      <editor-sidebar> under <editor-shell>.
+    - >-
+      Do NOT confuse <aside-ui> with <pane-ui>: aside-ui declares the
+      semantic side role (a11y + parent layout hint); <pane-ui> owns
+      resize / collapse interaction. When you need interactive resize
+      inside an aside, nest <pane-ui resizable> inside.
+    - >-
+      Width hints map to tokens: `width="rail"` ≈ icon-only nav,
+      `width="panel"` ≈ nav with labels, `width="wide"` ≈ workspace
+      pane. Unset defers to the parent default. Only pair `collapsible`
+      with parents that wire a toggle (the prop is a hint, not a
+      behavior).
+    - >-
+      For the settings-page description rail (label + help text on the
+      left, controls on the right) use plain HTML <aside> inside a
+      [data-section] flex layout — see apps/saas/billing and
+      apps/saas/members. That pattern is NOT aside-ui; the primitive
+      is for slotted container parents only.
 anti_patterns: []
 examples:
   - name: card-with-side-nav
@@ -91,7 +121,8 @@ keywords:
   - panel
   - side-region
   - nav-rail
-synonyms: {}
+synonyms:
+  aside: [side-region, side-panel-slot, secondary-rail]
 related:
   - app-shell
   - drawer

package/components/avatar/avatar-group.a2ui.json

@@ -36,12 +36,29 @@
     "composes": [],
     "events": {},
     "examples": [],
-    "keywords": [],
+    "keywords": [
+      "avatar-group",
+      "avatar-stack",
+      "user-group",
+      "facepile",
+      "people-stack",
+      "overflow-avatars"
+    ],
     "name": "UIAvatarGroup",
-    "related": [],
+    "related": [
+      "Avatar",
+      "Tag"
+    ],
     "slots": {},
     "states": [],
-    "synonyms": {},
+    "synonyms": {
+      "avatar-group": [
+        "facepile",
+        "user-stack",
+        "people-pile",
+        "avatar-pile"
+      ]
+    },
     "tag": "avatar-group-ui",
     "tokens": {},
     "traits": [],

package/components/avatar/avatar-group.yaml

@@ -24,3 +24,27 @@ props:
   size:
     description: Forwards to each child <avatar-ui> (xs|sm|md|lg|xl). Empty uses the per-avatar size.
     type: string
+
+keywords:
+  - avatar-group
+  - avatar-stack
+  - user-group
+  - facepile
+  - people-stack
+  - overflow-avatars
+
+synonyms:
+  avatar-group: [facepile, user-stack, people-pile, avatar-pile]
+
+related:
+  - Avatar
+  - Tag
+
+a2ui:
+  rules:
+    - rule: 'Cluster of overlapping <avatar-ui> children with negative-margin stacking + +N overflow indicator.'
+      reason: 'Facepile primitive.'
+    - rule: 'max attribute controls visible-avatar count before +N overflow kicks in.'
+      reason: 'Overflow knob.'
+    - rule: 'For a single user use <avatar-ui> standalone; avatar-group only for 2+ users.'
+      reason: 'Capacity boundary.'

package/components/avatar/avatar.a2ui.json

@@ -2,7 +2,7 @@
   "$schema": "https://json-schema.org/draft/2020-12/schema",
   "$id": "https://adiaui.dev/a2ui/v0_9/components/Avatar.json",
   "title": "Avatar",
-  "description": "Avatar with image → initials → empty fallback chain.",
+  "description": "User-portrait primitive with an image → initials → icon fallback\nchain. Resolves the leading [src] image; on load failure falls back\nto [text]-derived initials; on missing text falls back to a slotted\nor default <icon-ui>. Use for user identity in chat surfaces,\nmember tables, statusbar account chips, comment threads. Pair via\n<avatar-group-ui> for stacked / overflowed sets.\n",
   "type": "object",
   "allOf": [
     {

package/components/avatar/avatar.d.ts

@@ -1,5 +1,11 @@
 /**
- * `<avatar-ui>` — Avatar with image → initials → empty fallback chain.
+ * `<avatar-ui>` — User-portrait primitive with an image → initials → icon fallback
+chain. Resolves the leading [src] image; on load failure falls back
+to [text]-derived initials; on missing text falls back to a slotted
+or default <icon-ui>. Use for user identity in chat surfaces,
+member tables, statusbar account chips, comment threads. Pair via
+<avatar-group-ui> for stacked / overflowed sets.
+
  *
  * @see https://ui-kit.exe.xyz/site/components/avatar
  *

package/components/avatar/avatar.yaml

@@ -6,7 +6,13 @@ tag: avatar-ui
 component: Avatar
 category: display
 version: 1
-description: Avatar with image → initials → empty fallback chain.
+description: |
+  User-portrait primitive with an image → initials → icon fallback
+  chain. Resolves the leading [src] image; on load failure falls back
+  to [text]-derived initials; on missing text falls back to a slotted
+  or default <icon-ui>. Use for user identity in chat surfaces,
+  member tables, statusbar account chips, comment threads. Pair via
+  <avatar-group-ui> for stacked / overflowed sets.
 # Per ADR-0027 — primitives that programmatically create other primitives
 # do NOT auto-import them. Consumer (or demo shell) must explicitly import.
 composes:
@@ -72,7 +78,13 @@ states:
 traits: []
 tokens: {}
 a2ui:
-  rules: []
+  rules:
+    - rule: 'Use for representing a single person, account, or entity. Image, initials, or icon fallback in priority order.'
+      reason: 'Canonical user-identity surface.'
+    - rule: 'For clusters of multiple users, wrap multiple <avatar-ui> in <avatar-group-ui> instead of placing them inline.'
+      reason: 'Group handles overlap-stacking + +N overflow.'
+    - rule: 'Do not embed inside <button-ui> for clickable avatars — make the <avatar-ui> itself the click target with role=''button''.'
+      reason: 'Button-inside-button is invalid; the avatar is the affordance.'
 anti_patterns: []
 examples:
   - name: chat-interface

package/components/badge/badge.a2ui.json

@@ -2,7 +2,7 @@
   "$schema": "https://json-schema.org/draft/2020-12/schema",
   "$id": "https://adiaui.dev/a2ui/v0_9/components/Badge.json",
   "title": "Badge",
-  "description": "Inline pill-shaped badge/tag. Text rendered via CSS attr().",
+  "description": "Inline pill-shaped badge — READ-ONLY status flag, count, or\nnotification dot. Text rendered via CSS `attr(text)`. Distinct from\n<tag-ui>, which is INTERACTIVE / removable and fires a `remove`\nevent. Use badge-ui for status flags (Beta / New / Deprecated),\nnotification counts, and unread indicators; use tag-ui for filter\nchips or user-managed labels.\n",
   "type": "object",
   "allOf": [
     {

package/components/badge/badge.d.ts

@@ -1,5 +1,11 @@
 /**
- * `<badge-ui>` — Inline pill-shaped badge/tag. Text rendered via CSS attr().
+ * `<badge-ui>` — Inline pill-shaped badge — READ-ONLY status flag, count, or
+notification dot. Text rendered via CSS `attr(text)`. Distinct from
+<tag-ui>, which is INTERACTIVE / removable and fires a `remove`
+event. Use badge-ui for status flags (Beta / New / Deprecated),
+notification counts, and unread indicators; use tag-ui for filter
+chips or user-managed labels.
+
  *
  * @see https://ui-kit.exe.xyz/site/components/badge
  *

package/components/badge/badge.yaml

@@ -6,7 +6,13 @@ tag: badge-ui
 component: Badge
 category: display
 version: 1
-description: Inline pill-shaped badge/tag. Text rendered via CSS attr().
+description: |
+  Inline pill-shaped badge — READ-ONLY status flag, count, or
+  notification dot. Text rendered via CSS `attr(text)`. Distinct from
+  <tag-ui>, which is INTERACTIVE / removable and fires a `remove`
+  event. Use badge-ui for status flags (Beta / New / Deprecated),
+  notification counts, and unread indicators; use tag-ui for filter
+  chips or user-managed labels.
 # Per ADR-0027 — primitives that programmatically create other primitives
 # do NOT auto-import them. Consumer (or demo shell) must explicitly import.
 composes:
@@ -70,7 +76,13 @@ states:
 traits: []
 tokens: {}
 a2ui:
-  rules: []
+  rules:
+    - rule: 'Use for small status/count labels attached to another element (notification counts, status pills, version tags).'
+      reason: 'Different from <tag-ui> which is for free-standing taxonomy/filter labels.'
+    - rule: 'Place adjacent to or absolutely-positioned over the badged element, not inside it.'
+      reason: 'Light-DOM positioning; do not nest inside the badged element''s slot.'
+    - rule: 'For dismissable taxonomy labels (filter chips, selected items in multi-select), use <tag-ui> instead.'
+      reason: 'Badge is non-interactive; tag has close affordance.'
 anti_patterns: []
 examples:
   - name: chart-legend

package/components/block/block.a2ui.json

@@ -2,7 +2,7 @@
   "$schema": "https://json-schema.org/draft/2020-12/schema",
   "$id": "https://adiaui.dev/a2ui/v0_9/components/Block.json",
   "title": "Block",
-  "description": "Generic padded/margined content wrapper.",
+  "description": "Generic padded / margined content wrapper. Applies a configurable\npadding + margin scale via [padding] / [margin] attribute props,\nmapping to the canonical spacing tokens. Use as a lightweight\nspacing wrapper when <section-ui> would imply chrome the parent\ncontainer doesn't own. Not a layout primitive (no flex / grid) —\nfor layout use <col-ui> / <row-ui> / <stack-ui> / <grid-ui>.\n",
   "type": "object",
   "allOf": [
     {
@@ -17,7 +17,7 @@
       "const": "Block"
     },
     "margin": {
-      "description": "Margin size",
+      "description": "Margin size (none/xs/sm/md/lg/xl). Accepts `@bp` notation: margin=\"none sm@md\" = no margin below md, sm from md up.",
       "type": "string",
       "enum": [
         "none",
@@ -30,7 +30,7 @@
       "default": "none"
     },
     "padding": {
-      "description": "Padding amount, maps to spacing tokens",
+      "description": "Padding amount (none/xs/sm/md/lg/xl → spacing tokens). Accepts `@bp` notation: padding=\"sm md@lg\" = sm below lg, md from lg up.",
       "type": "string",
       "enum": [
         "none",
@@ -71,7 +71,12 @@
       "developer"
     ],
     "name": "UIBlock",
-    "related": [],
+    "related": [
+      "Section",
+      "Col",
+      "Row",
+      "Stack"
+    ],
     "slots": {},
     "states": [
       {

package/components/block/block.d.ts

@@ -1,5 +1,11 @@
 /**
- * `<block-ui>` — Generic padded/margined content wrapper.
+ * `<block-ui>` — Generic padded / margined content wrapper. Applies a configurable
+padding + margin scale via [padding] / [margin] attribute props,
+mapping to the canonical spacing tokens. Use as a lightweight
+spacing wrapper when <section-ui> would imply chrome the parent
+container doesn't own. Not a layout primitive (no flex / grid) —
+for layout use <col-ui> / <row-ui> / <stack-ui> / <grid-ui>.
+
  *
  * @see https://ui-kit.exe.xyz/site/components/block
  *
@@ -13,8 +19,8 @@
 import { UIElement } from '../../core/element.js';
 
 export class UIBlock extends UIElement {
-  /** Margin size */
+  /** Margin size (none/xs/sm/md/lg/xl). Accepts `@bp` notation: margin="none sm@md" = no margin below md, sm from md up. */
   margin: 'none' | 'xs' | 'sm' | 'md' | 'lg' | 'xl';
-  /** Padding amount, maps to spacing tokens */
+  /** Padding amount (none/xs/sm/md/lg/xl → spacing tokens). Accepts `@bp` notation: padding="sm md@lg" = sm below lg, md from lg up. */
   padding: 'none' | 'xs' | 'sm' | 'md' | 'lg' | 'xl';
 }

package/components/block/block.yaml

@@ -6,10 +6,18 @@ tag: block-ui
 component: Block
 category: layout
 version: 1
-description: Generic padded/margined content wrapper.
+description: |
+  Generic padded / margined content wrapper. Applies a configurable
+  padding + margin scale via [padding] / [margin] attribute props,
+  mapping to the canonical spacing tokens. Use as a lightweight
+  spacing wrapper when <section-ui> would imply chrome the parent
+  container doesn't own. Not a layout primitive (no flex / grid) —
+  for layout use <col-ui> / <row-ui> / <stack-ui> / <grid-ui>.
 props:
   margin:
-    description: Margin size
+    description: >-
+      Margin size (none/xs/sm/md/lg/xl). Accepts `@bp` notation:
+      margin="none sm@md" = no margin below md, sm from md up.
     type: string
     default: none
     enum:
@@ -20,7 +28,9 @@ props:
       - lg
       - xl
   padding:
-    description: Padding amount, maps to spacing tokens
+    description: >-
+      Padding amount (none/xs/sm/md/lg/xl → spacing tokens). Accepts `@bp`
+      notation: padding="sm md@lg" = sm below lg, md from lg up.
     type: string
     default: md
     enum:
@@ -40,7 +50,13 @@ tokens:
   --block-padding:
     description: Override padding value
 a2ui:
-  rules: []
+  rules:
+    - rule: 'Generic semantic block — use for arbitrary content groupings without strong layout semantics.'
+      reason: 'Lowest-specificity layout primitive.'
+    - rule: 'For row/column layouts use <row-ui> / <col-ui>; for grid use <stack-ui>; block is for content-flow groupings.'
+      reason: 'Decision rule vs layout siblings.'
+    - rule: 'Block-ui does not impose padding/gap by default — wrap in <section-ui> if you want chrome.'
+      reason: 'Composition discipline.'
 anti_patterns: []
 examples:
   - name: basic-block
@@ -112,4 +128,8 @@ synonyms:
     - code
     - block
     - command
-related: []
+related:
+  - Section
+  - Col
+  - Row
+  - Stack

package/components/block/class.js

@@ -22,6 +22,10 @@
  */
 
 import { UIElement } from '../../core/element.js';
+import { parseResponsive, breakpoint } from '../../core/responsive.js';
+
+const _SPACE = { none: '0', xs: 'var(--a-space-1)', sm: 'var(--a-space-2)', md: 'var(--a-space-4)', lg: 'var(--a-space-6)', xl: 'var(--a-space-10)' };
+function _spaceToCss(v) { return _SPACE[v] ?? (/^\d+$/.test(v ?? '') ? `var(--a-space-${v})` : v ?? ''); }
 
 export class UIBlock extends UIElement {
   static properties = {
@@ -30,4 +34,23 @@ export class UIBlock extends UIElement {
   };
 
   static template = () => null;
+
+  render() {
+    const padding = this.padding;
+    const margin  = this.margin;
+    const anyR    = padding?.includes('@') || margin?.includes('@');
+    const bp      = anyR ? breakpoint.value : '';
+
+    if (padding?.includes('@')) {
+      this.style.setProperty('--block-padding', _spaceToCss(parseResponsive(padding, bp)));
+    } else {
+      this.style.removeProperty('--block-padding');
+    }
+
+    if (margin?.includes('@')) {
+      this.style.setProperty('--block-margin', _spaceToCss(parseResponsive(margin, bp)));
+    } else {
+      this.style.removeProperty('--block-margin');
+    }
+  }
 }

package/components/breadcrumb/breadcrumb.a2ui.json

@@ -65,7 +65,11 @@
       "back"
     ],
     "name": "UIBreadcrumb",
-    "related": [],
+    "related": [
+      "AdminTopbar",
+      "Nav",
+      "Tabs"
+    ],
     "slots": {},
     "states": [
       {

package/components/breadcrumb/breadcrumb.yaml

@@ -40,7 +40,35 @@ states:
 traits: []
 tokens: {}
 a2ui:
-  rules: []
+  rules:
+    - >-
+      Canonical placement: render <breadcrumb-ui> inside <admin-topbar>
+      for hierarchical page-context display. It is the topbar's heading
+      region — typically preceded by a sidebar-toggle <button-ui
+      icon="sidebar" variant="ghost" size="sm"> and followed by topbar
+      actions in [slot="action"]. The host stamps role="navigation" +
+      aria-label="Breadcrumb" automatically.
+    - >-
+      Child shape: each crumb is either an <a href> (ancestor link) or
+      a plain <span> (terminal / non-link current page). The LAST child
+      is the current page and MUST be a plain <span> — the component
+      auto-applies aria-current="page" and disables pointer events on
+      it. Optional first child may be an <icon-ui> (or <a> wrapping
+      one with aria-label) for an app / home glyph.
+    - >-
+      Separator + overflow: do NOT insert your own separator elements
+      ([data-sep] spans are stamped automatically between children).
+      For deep trails (4+ items) prefer the `collapse` attribute over
+      manual truncation; tune visible edges with [collapse-keep-leading]
+      / [collapse-keep-trailing]. Collapsed middle crumbs are presented
+      as a `…` <menu-ui data-overflow> popover.
+    - >-
+      Decision rule: <breadcrumb-ui> is read-only PATH-CONTEXT display
+      ("where am I"). For primary navigation (sidebar) use <nav-ui> +
+      <nav-item-ui> inside <admin-sidebar>. For switching sub-views
+      within a page use <tabs-ui>. Never use <breadcrumb-ui> as the
+      primary navigation control or wrap navigation controls (selects,
+      tabs, form controls) inside it.
 anti_patterns: []
 examples:
   - name: breadcrumb-nav
@@ -101,4 +129,7 @@ synonyms:
     - tabs
     - menu
     - pagination
-related: []
+related:
+  - AdminTopbar
+  - Nav
+  - Tabs