@adia-ai/web-components 0.6.21 → 0.6.23

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

@@ -87,7 +87,11 @@
       "menu"
     ],
     "name": "UINavGroup",
-    "related": [],
+    "related": [
+      "Nav",
+      "NavItem",
+      "Accordion"
+    ],
     "slots": {
       "default": {
         "description": "Children — typically <nav-item-ui> rows."
@@ -106,7 +110,13 @@
         "name": "open"
       }
     ],
-    "synonyms": {},
+    "synonyms": {
+      "nav-group": [
+        "nav-section",
+        "sidebar-group",
+        "menu-group"
+      ]
+    },
     "tag": "nav-group-ui",
     "tokens": {},
     "traits": [],

package/components/nav-group/nav-group.yaml

@@ -72,10 +72,44 @@ states:
 traits: []
 tokens: {}
 a2ui:
-  rules: []
+  rules:
+    - >-
+      Composition: <nav-group-ui> MUST be a direct child of <nav-ui>
+      (or standalone with explicit variant="section" outside a rail).
+      Default slot accepts <nav-item-ui> children; do NOT wrap them in
+      layout primitives — selection, keyboard, and the section-variant
+      cascade all rely on direct descendancy.
+    - >-
+      Variant cascade: when parent <nav-ui variant="section">, this
+      group inherits section styling (static kicker header, children
+      always visible) via CSS — without touching its JS state. Set
+      [variant="section"] explicitly only when there is no <nav-ui>
+      parent, OR to override a primary-rail context.
+    - >-
+      Collapsibility: primary variant — [collapsible] (default true)
+      toggles [open] via header click / Enter / Space; fires
+      `group-toggle` event with detail {text, open}. When the parent
+      <nav-ui> is collapsed to icon-only, the header opens a popover
+      with this group's children instead. Section variant ignores
+      [open] / [collapsible] (children always visible).
+    - >-
+      Decision rule: use <nav-group-ui> to group ≥2 related navigation
+      links under one label inside <nav-ui>. For a single link, use
+      <nav-item-ui> directly. For switching sub-views inside one page,
+      use <tabs-ui> / <tab-ui>, never <nav-group-ui>.
+    - >-
+      Anti-patterns: do NOT nest <nav-group-ui> inside another
+      <nav-group-ui> (flatten the hierarchy or split into two groups).
+      Do NOT place non-<nav-item-ui> content in the default slot. Do
+      NOT use it as a generic disclosure — for that use <accordion-ui>
+      or <details>.
 anti_patterns: []
 examples: []
 
 keywords: [nav, navigation, group, sidebar, menu]
-synonyms: {}
-related: []
+synonyms:
+  nav-group: [nav-section, sidebar-group, menu-group]
+related:
+  - Nav
+  - NavItem
+  - Accordion

package/components/nav-item/nav-item.a2ui.json

@@ -95,7 +95,12 @@
       "sidebar"
     ],
     "name": "UINavItem",
-    "related": [],
+    "related": [
+      "Nav",
+      "NavGroup",
+      "Button",
+      "Tab"
+    ],
     "slots": {
       "default": {
         "description": "Optional override of the default icon + text + badge stamping."
@@ -115,7 +120,13 @@
         "name": "disabled"
       }
     ],
-    "synonyms": {},
+    "synonyms": {
+      "nav-item": [
+        "nav-link",
+        "sidebar-item",
+        "menu-link"
+      ]
+    },
     "tag": "nav-item-ui",
     "tokens": {},
     "traits": [],

package/components/nav-item/nav-item.yaml

@@ -78,10 +78,47 @@ states:
 traits: []
 tokens: {}
 a2ui:
-  rules: []
+  rules:
+    - >-
+      Composition: <nav-item-ui> MUST be a direct child of <nav-ui> or
+      <nav-group-ui>. Never wrap in <col-ui> / <row-ui> / <li> / <a> —
+      the item is already a focusable, accessible link element;
+      wrapping breaks selection, ARIA, and the section-variant CSS
+      cascade.
+    - >-
+      Variant cascade: when an ancestor <nav-ui variant="section"> (or
+      sibling-group with section variant) is present, this item
+      inherits section styling (flat row, no reserved icon space when
+      icon absent, left-edge selected accent) via CSS. Set
+      [variant="section"] explicitly only when used standalone outside
+      a section rail, or [variant="primary"] to override the cascade
+      for a single highlighted item.
+    - >-
+      Selection: [selected] is set by the parent <nav-ui>'s select()
+      method; do NOT set it on multiple items simultaneously. Provide
+      [value] as a route or anchor; consumers listen for `nav-select`
+      on <nav-ui> rather than per-item.
+    - >-
+      Decision rule: use <nav-item-ui> for a single navigable link
+      (route or anchor). For an in-page view toggle, use <tab-ui>. For
+      a popover menu action, use <menu-item-ui>. For an action button
+      styled like a nav row, use <button-ui variant="ghost"> — not
+      <nav-item-ui>.
+    - >-
+      Authoring options: default stamping renders icon+text+badge from
+      attributes. Named slots `icon`, `text`, `trailing` are also
+      supported for custom content (e.g. a `<kbd slot="trailing">⌘K</kbd>`
+      shortcut hint on a command-trigger item — see the admin-shell
+      playground). Do NOT nest <nav-item-ui> inside another
+      <nav-item-ui>.
 anti_patterns: []
 examples: []
 
 keywords: [nav, navigation, item, link, sidebar]
-synonyms: {}
-related: []
+synonyms:
+  nav-item: [nav-link, sidebar-item, menu-link]
+related:
+  - Nav
+  - NavGroup
+  - Button
+  - Tab

package/components/noodles/noodles.a2ui.json

@@ -156,7 +156,10 @@
       "noodles"
     ],
     "name": "UINoodles",
-    "related": [],
+    "related": [
+      "Canvas",
+      "EditorCanvas"
+    ],
     "slots": {},
     "states": [
       {
@@ -169,7 +172,14 @@
         "name": "disabled"
       }
     ],
-    "synonyms": {},
+    "synonyms": {
+      "noodles": [
+        "connection-curve",
+        "wire",
+        "edge-line",
+        "bezier-wire"
+      ]
+    },
     "tag": "noodles-ui",
     "tokens": {
       "--noodles-duration": {

package/components/noodles/noodles.yaml

@@ -118,7 +118,15 @@ tokens:
   --noodles-easing:
     description: Easing function for noodle animations
 a2ui:
-  rules: []
+  rules:
+    - rule: 'SVG connection lines between children with declared ports — bezier (default), step, or straight curves.'
+      reason: 'Node-graph connector primitive.'
+    - rule: 'Place inside <canvas-ui> with port-declaring children (nodes); noodles draws connections between matching port refs.'
+      reason: 'Canvas + ports composition.'
+    - rule: 'editable attribute enables drag-to-connect interactions; default is render-only.'
+      reason: 'Read vs write mode.'
+    - rule: 'For data-flow visualizations only — for general-purpose lines/shapes use raw SVG.'
+      reason: 'Scope discipline.'
 anti_patterns: []
 examples:
   - name: basic-noodles
@@ -146,5 +154,8 @@ examples:
       ]
 keywords:
   - noodles
-synonyms: {}
-related: []
+synonyms:
+  noodles: [connection-curve, wire, edge-line, bezier-wire]
+related:
+  - Canvas
+  - EditorCanvas

package/components/option-card/option-card.yaml

@@ -160,7 +160,33 @@ tokens:
   --option-card-easing:
     description: Transition easing.
 a2ui:
-  rules: []
+  rules:
+    - >-
+      Use <option-card-ui> for one-of-N choices where each option
+      needs a heading + description, a leading icon, or both
+      (onboarding personas, plan tiers, source pickers). Use
+      <radio-ui> for dense forms with short labels and no
+      descriptions. Use <segmented-ui> for compact horizontal
+      single-select with short labels.
+    - >-
+      Group siblings by sharing the same [name] attribute — they
+      auto-form a radiogroup. Form participation is implicit via
+      UIFormElement: submits `name=value` with parent form. Wrap the
+      group in <col-ui gap="2"> for default layout or <grid-ui> for
+      [layout="tile"] hero pickers.
+    - >-
+      Set [checked] on the recommended / default option. Never leave
+      the group with zero checked at first paint unless [required] is
+      set and the form intentionally demands a deliberate choice.
+    - >-
+      Use [layout="tile"] only for hero pickers (3–4 options max)
+      where the icon is a primary brand cue (plan tiers, role pickers).
+      Use [layout="default"] (left-indicator) for everything else.
+    - >-
+      Put conditional follow-up inputs (a <textarea-ui> on "Other", a
+      <select-ui> on "Custom") in the default slot — the spillover
+      content auto-hides when the card is not checked. Do NOT
+      duplicate this visibility logic in JS.
 anti_patterns: []
 examples:
   - name: use-case-picker

package/components/otp-input/otp-input.yaml

@@ -54,7 +54,30 @@ states:
 traits: []
 tokens: {}
 a2ui:
-  rules: []
+  rules:
+    - >-
+      Use <otp-input-ui> for any fixed-length verification code (TOTP,
+      email / SMS OTP, MFA enrollment) — NOT <input-ui type="number">.
+      otp-input-ui provides per-digit focus management, paste-splitting
+      of full codes, and the `complete` event that fires exactly once
+      when all digits are filled.
+    - >-
+      Always set [autocomplete="one-time-code"] so iOS / Android
+      keyboards surface inbound SMS codes via the platform autofill UI.
+    - >-
+      Listen for `complete` to auto-submit (fires exactly once per
+      fill cycle), and `change` / `input` for live validation. Form
+      participation is implicit via UIFormElement: [name] for
+      FormData; [disabled] reflects.
+    - >-
+      Default [length=6]. Use [length=4] only for legacy 4-digit SMS
+      codes and [length=8] for backup codes. Never compose two
+      <otp-input-ui> side-by-side — use a single one with the right
+      length.
+    - >-
+      Canonical placement: inside a <col-ui align="center"> beneath a
+      description text. Do NOT wrap in <field-ui> — otp-input-ui has
+      no label slot and visual centering is the canonical chrome.
 anti_patterns: []
 examples:
 - name: otp-form

package/components/page/page.a2ui.json

@@ -99,7 +99,13 @@
         "name": "header-stuck"
       }
     ],
-    "synonyms": {},
+    "synonyms": {
+      "page": [
+        "page-container",
+        "route-surface",
+        "content-surface"
+      ]
+    },
     "tag": "page-ui",
     "tokens": {},
     "traits": [],

package/components/page/page.yaml

@@ -74,7 +74,13 @@ states:
 traits: []
 tokens: {}
 a2ui:
-  rules: []
+  rules:
+    - rule: 'Top-level page container — wraps an entire route''s content surface.'
+      reason: 'Page-level chrome primitive.'
+    - rule: 'Inside <admin-shell-ui>, <chat-shell-ui>, or <editor-shell-ui>, use the shell''s own body slot instead; page-ui is for standalone routes without shell chrome.'
+      reason: 'Shell hosting precedence.'
+    - rule: 'Hosts arbitrary children — no enforced child contract.'
+      reason: 'Generic container.'
 anti_patterns: []
 examples:
   - name: prose-page
@@ -139,7 +145,8 @@ keywords:
   - padding
   - prose-page
   - dashboard-page
-synonyms: {}
+synonyms:
+  page: [page-container, route-surface, content-surface]
 related:
   - app-shell
   - card

package/components/pagination/pagination.a2ui.json

@@ -2,7 +2,7 @@
   "$schema": "https://json-schema.org/draft/2020-12/schema",
   "$id": "https://adiaui.dev/a2ui/v0_9/components/Pagination.json",
   "title": "Pagination",
-  "description": "Page navigation with prev/next buttons, page numbers, and ellipsis.",
+  "description": "Page navigation with prev/next buttons, page numbers, and ellipsis. Emits page-change events when buttons are clicked; visible page-number range is automatically truncated for high page counts. Use below tables, card grids, or list views; for cursor-based pagination use a custom load-more <button-ui> instead.",
   "type": "object",
   "allOf": [
     {

package/components/pagination/pagination.d.ts

@@ -1,5 +1,5 @@
 /**
- * `<pagination-ui>` — Page navigation with prev/next buttons, page numbers, and ellipsis.
+ * `<pagination-ui>` — Page navigation with prev/next buttons, page numbers, and ellipsis. Emits page-change events when buttons are clicked; visible page-number range is automatically truncated for high page counts. Use below tables, card grids, or list views; for cursor-based pagination use a custom load-more <button-ui> instead.
  *
  * @see https://ui-kit.exe.xyz/site/components/pagination
  *

package/components/pagination/pagination.yaml

@@ -6,7 +6,12 @@ tag: pagination-ui
 component: Pagination
 category: navigation
 version: 1
-description: Page navigation with prev/next buttons, page numbers, and ellipsis.
+description: >-
+  Page navigation with prev/next buttons, page numbers, and ellipsis.
+  Emits page-change events when buttons are clicked; visible page-number
+  range is automatically truncated for high page counts. Use below tables,
+  card grids, or list views; for cursor-based pagination use a custom
+  load-more <button-ui> instead.
 props:
   page:
     description: Current active page number.
@@ -38,7 +43,13 @@ states:
 traits: []
 tokens: {}
 a2ui:
-  rules: []
+  rules:
+    - rule: 'Renders below tables, card grids, or list views for paginated data. Emits page-change events.'
+      reason: 'Standard pagination affordance.'
+    - rule: 'For cursor-based / infinite-scroll patterns use a custom load-more <button-ui> instead; pagination-ui is offset-based.'
+      reason: 'Pagination model boundary.'
+    - rule: 'Page-number range auto-truncates with ellipsis for high counts; set siblings= to control visible window size.'
+      reason: 'Layout knob.'
 anti_patterns: []
 examples:
   - name: data-table-view

package/components/pane/pane.a2ui.json

@@ -2,7 +2,7 @@
   "$schema": "https://json-schema.org/draft/2020-12/schema",
   "$id": "https://adiaui.dev/a2ui/v0_9/components/Pane.json",
   "title": "Pane",
-  "description": "Collapsible, resizable panel.",
+  "description": "Collapsible, resizable content panel — drag-resize handle on the\ninner edge when [side=\"leading\"] / [side=\"trailing\"], [resizable]\nopt-in. Used standalone for resizable two-pane layouts, or wrapped\nby <editor-sidebar> / <admin-sidebar> which DELEGATE drag to the\ninner pane-ui rather than reimplementing it. See pane.yaml's\na2ui.rules for the full composition contract.\n",
   "type": "object",
   "allOf": [
     {

package/components/pane/pane.d.ts

@@ -1,5 +1,11 @@
 /**
- * `<pane-ui>` — Collapsible, resizable panel.
+ * `<pane-ui>` — Collapsible, resizable content panel — drag-resize handle on the
+inner edge when [side="leading"] / [side="trailing"], [resizable]
+opt-in. Used standalone for resizable two-pane layouts, or wrapped
+by <editor-sidebar> / <admin-sidebar> which DELEGATE drag to the
+inner pane-ui rather than reimplementing it. See pane.yaml's
+a2ui.rules for the full composition contract.
+
  *
  * @see https://ui-kit.exe.xyz/site/components/pane
  *

package/components/pane/pane.yaml

@@ -4,7 +4,13 @@ tag: pane-ui
 component: Pane
 category: layout
 version: 1
-description: Collapsible, resizable panel.
+description: |
+  Collapsible, resizable content panel — drag-resize handle on the
+  inner edge when [side="leading"] / [side="trailing"], [resizable]
+  opt-in. Used standalone for resizable two-pane layouts, or wrapped
+  by <editor-sidebar> / <admin-sidebar> which DELEGATE drag to the
+  inner pane-ui rather than reimplementing it. See pane.yaml's
+  a2ui.rules for the full composition contract.
 # Per ADR-0027 — primitives that programmatically create other primitives
 # do NOT auto-import them. Consumer (or demo shell) must explicitly import.
 composes:
@@ -63,7 +69,32 @@ tokens: {}
 requiredIcons:
   - caret-right
 a2ui:
-  rules: []
+  rules:
+    - >-
+      pane-ui is a resizable / collapsible content panel. As a standalone
+      primitive (no [side] attribute), it carries its own four-sided
+      chrome and a right-edge resize grabber. As a horizontal-sibling
+      child of a layout container (set [side="leading"] or
+      [side="trailing"]), the chrome and grabber move to the inner
+      edge so adjacent panes share a single seam.
+    - >-
+      Wrapped by <editor-sidebar slot="leading|trailing"> inside
+      <editor-shell>, and by <admin-sidebar slot="leading|trailing">
+      inside <admin-shell>. The bespoke sidebar owns [collapsed] /
+      [resizing] reflected state + localStorage persistence; the inner
+      pane-ui owns the physical drag. Don't reimplement drag in the
+      bespoke sidebar — delegate to <pane-ui resizable>.
+    - >-
+      Inner shape inside a pane-ui is the conventional
+      <header> + <section> + optional <footer> slot pattern. Headers
+      carry [slot="action"] button clusters; sections hold the
+      navigator tree, inspector form rows, or other primary content.
+    - >-
+      For a standalone resizable two-pane layout (no shell), nest panes
+      directly inside a flex row — both with [side]-typed chrome —
+      and the resize handle will live on the seam between them. For
+      a non-resizable summary pane (a fixed-width detail rail), drop
+      [resizable] and pane-ui collapses to a static container.
 anti_patterns: []
 examples:
 - name: markdown-editor

package/components/pipeline-status/pipeline-status.a2ui.json

@@ -2,7 +2,7 @@
   "$schema": "https://json-schema.org/draft/2020-12/schema",
   "$id": "https://adiaui.dev/a2ui/v0_9/components/PipelineStatus.json",
   "title": "PipelineStatus",
-  "description": "<pipeline-status-ui> — Single updating pipeline status indicator.",
+  "description": "Single updating pipeline status indicator showing current step and progress. Renders inline as a status pill with optional progress bar; updates via the status property. Use for long-running agent or build pipelines; for multi-step wizards use <stepper-ui> instead.",
   "type": "object",
   "allOf": [
     {
@@ -70,7 +70,11 @@
       "status"
     ],
     "name": "UIPipelineStatus",
-    "related": [],
+    "related": [
+      "AgentTrace",
+      "Stepper",
+      "StepProgress"
+    ],
     "slots": {
       "default": {
         "description": "Default slot — primary child content."

package/components/pipeline-status/pipeline-status.d.ts

@@ -1,5 +1,5 @@
 /**
- * `<pipeline-status-ui>` — <pipeline-status-ui> — Single updating pipeline status indicator.
+ * `<pipeline-status-ui>` — Single updating pipeline status indicator showing current step and progress. Renders inline as a status pill with optional progress bar; updates via the status property. Use for long-running agent or build pipelines; for multi-step wizards use <stepper-ui> instead.
  *
  * @see https://ui-kit.exe.xyz/site/components/pipeline-status
  *

package/components/pipeline-status/pipeline-status.yaml

@@ -4,7 +4,11 @@ tag: pipeline-status-ui
 component: PipelineStatus
 category: agent
 version: 1
-description: <pipeline-status-ui> — Single updating pipeline status indicator.
+description: >-
+  Single updating pipeline status indicator showing current step and
+  progress. Renders inline as a status pill with optional progress bar;
+  updates via the status property. Use for long-running agent or build
+  pipelines; for multi-step wizards use <stepper-ui> instead.
 props:
   complete:
     description: 'Component property: complete.'
@@ -28,7 +32,15 @@ states:
 traits: []
 tokens: {}
 a2ui:
-  rules: []
+  rules:
+    - rule: 'Single updating pipeline status indicator — status pill with optional progress bar.'
+      reason: 'Long-running task indicator.'
+    - rule: 'stage + complete + message attributes drive the current display state.'
+      reason: 'State contract.'
+    - rule: 'For multi-step wizards use <stepper-ui>; for chronological history use <timeline-ui>; pipeline-status is a single current-state pill.'
+      reason: 'Sibling boundary.'
+    - rule: 'Renders inline — place inside toolbars, status bars, or agent message bodies.'
+      reason: 'Composition contract.'
 anti_patterns: []
 examples:
 - name: basic-pipeline-status
@@ -58,4 +70,7 @@ synonyms:
   - job-status
   - deploy-status
   - pipeline-indicator
-related: []
+related:
+  - AgentTrace
+  - Stepper
+  - StepProgress

package/components/popover/popover.yaml

@@ -46,7 +46,36 @@ states:
 traits: []
 tokens: {}
 a2ui:
-  rules: []
+  rules:
+    - >-
+      <popover-ui> wraps a focusable trigger (slot="trigger", typically
+      <button-ui>) + arbitrary interactive content (slot="content").
+      Never put bare text in slot="trigger" — it must be focusable so
+      keyboard users can open the popover.
+    - >-
+      Decision rule vs adjacent surfaces. (a) For a list of action
+      items use <menu-ui> instead — menu-ui is the specialized
+      popover with role=menu + roving tabindex. (b) For read-only
+      hover hints use <tooltip-ui>. (c) For centered focus-trapping
+      dialogs use <modal-ui>. (d) For edge-anchored multi-field forms
+      use <drawer-ui>. popover-ui is the GENERAL anchored surface for
+      everything else (inline forms, color pickers, theme panels,
+      export menus with non-action content).
+    - >-
+      Use [placement="bottom-end"] for topbar overflow / settings
+      buttons; [placement="bottom-start"] for inline form fields;
+      top-* variants when trigger sits low in the viewport
+      (statusbar). [gap] (default 4px) controls offset from anchor.
+    - >-
+      [trigger="hover"] is for non-essential disclosure only — never
+      use it for popovers containing inputs, destructive actions, or
+      anything the user must interact with via keyboard. Default
+      [trigger="click"] for everything interactive.
+    - >-
+      Do NOT nest <modal-ui> or <drawer-ui> inside slot="content";
+      popovers are non-modal anchored surfaces, not dialog hosts.
+      Stacking dialog surfaces inside a popover breaks focus
+      management.
 anti_patterns: []
 examples:
   - name: popover-demo

package/components/progress/progress.a2ui.json

@@ -2,7 +2,7 @@
   "$schema": "https://json-schema.org/draft/2020-12/schema",
   "$id": "https://adiaui.dev/a2ui/v0_9/components/Progress.json",
   "title": "Progress",
-  "description": "Progress indicator. Bar (default) or spinner. Value < 0 = indeterminate.",
+  "description": "Progress indicator with bar (default) or spinner variant. Value < 0 marks indeterminate state showing animated activity instead of a fill. Use inside <progress-row-ui> for labeled task lists or standalone for global loading indicators; for percent-complete inline displays use <stat-ui> instead.",
   "type": "object",
   "allOf": [
     {

package/components/progress/progress.d.ts

@@ -1,5 +1,5 @@
 /**
- * `<progress-ui>` — Progress indicator. Bar (default) or spinner. Value < 0 = indeterminate.
+ * `<progress-ui>` — Progress indicator with bar (default) or spinner variant. Value < 0 marks indeterminate state showing animated activity instead of a fill. Use inside <progress-row-ui> for labeled task lists or standalone for global loading indicators; for percent-complete inline displays use <stat-ui> instead.
  *
  * @see https://ui-kit.exe.xyz/site/components/progress
  *

package/components/progress/progress.yaml

@@ -4,7 +4,12 @@ tag: progress-ui
 component: Progress
 category: display
 version: 1
-description: Progress indicator. Bar (default) or spinner. Value < 0 = indeterminate.
+description: >-
+  Progress indicator with bar (default) or spinner variant. Value < 0
+  marks indeterminate state showing animated activity instead of a fill.
+  Use inside <progress-row-ui> for labeled task lists or standalone for
+  global loading indicators; for percent-complete inline displays use
+  <stat-ui> instead.
 props:
   value:
     description: Current progress. 0..max (or 0..1 when max omitted). null = indeterminate (legacy -1 accepted for back-compat).
@@ -36,7 +41,13 @@ states:
 traits: []
 tokens: {}
 a2ui:
-  rules: []
+  rules:
+    - rule: 'Use for in-progress task feedback with known or indeterminate state. Value < 0 = indeterminate animation.'
+      reason: 'Same primitive for both modes; consumer controls via value.'
+    - rule: 'For labeled task lists (multiple progress bars with row labels), use <progress-row-ui> instead.'
+      reason: 'Progress-row composes <progress-ui> + label + value display.'
+    - rule: 'Spinner variant (variant=''spinner'') for circular loading indicators; bar variant default for linear.'
+      reason: 'Two visual modes.'
 anti_patterns: []
 examples:
 - name: dashboard

package/components/progress-row/progress-row.a2ui.json

@@ -70,7 +70,11 @@
       "row"
     ],
     "name": "UIProgressRow",
-    "related": [],
+    "related": [
+      "Progress",
+      "StepProgress",
+      "List"
+    ],
     "slots": {
       "label": {
         "description": "Label region — control label."
@@ -85,7 +89,13 @@
         "name": "idle"
       }
     ],
-    "synonyms": {},
+    "synonyms": {
+      "progress-row": [
+        "task-row",
+        "progress-line",
+        "labeled-progress"
+      ]
+    },
     "tag": "progress-row-ui",
     "tokens": {},
     "traits": [],

package/components/progress-row/progress-row.yaml

@@ -48,7 +48,13 @@ states:
 traits: []
 tokens: {}
 a2ui:
-  rules: []
+  rules:
+    - rule: 'Labeled progress row — composes a label + <progress-ui> + optional value display in one horizontal row.'
+      reason: 'Common form for task-list progress.'
+    - rule: 'For standalone progress bars without a row context use <progress-ui> directly.'
+      reason: 'Composition boundary.'
+    - rule: 'Inside lists (multiple tasks with progress) stack multiple progress-rows in a <col-ui>.'
+      reason: 'Composition pattern.'
 anti_patterns: []
 examples:
   - name: basic-progress-row
@@ -80,5 +86,9 @@ keywords:
   - progress-row
   - progress
   - row
-synonyms: {}
-related: []
+synonyms:
+  progress-row: [task-row, progress-line, labeled-progress]
+related:
+  - Progress
+  - StepProgress
+  - List