@adia-ai/web-components 0.6.20 → 0.6.22

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

package/components/radio/radio.a2ui.json

@@ -2,7 +2,7 @@
   "$schema": "https://json-schema.org/draft/2020-12/schema",
   "$id": "https://adiaui.dev/a2ui/v0_9/components/Radio.json",
   "title": "Radio",
-  "description": "Radio button with pure CSS dot. Groups by name attribute. Form-associated.",
+  "description": "Radio button with pure CSS dot. Groups by name attribute (one selected value per group); form-associated and emits standard change events. Use for single-select option groups in forms; for richer styling or button-style options use <segment-ui> inside <segmented-ui> instead.",
   "type": "object",
   "allOf": [
     {

package/components/radio/radio.yaml

@@ -6,7 +6,11 @@ tag: radio-ui
 component: Radio
 category: input
 version: 1
-description: Radio button with pure CSS dot. Groups by name attribute. Form-associated.
+description: >-
+  Radio button with pure CSS dot. Groups by name attribute (one selected
+  value per group); form-associated and emits standard change events. Use
+  for single-select option groups in forms; for richer styling or
+  button-style options use <segment-ui> inside <segmented-ui> instead.
 props:
   name:
     description: Form control name for form data submission
@@ -109,6 +113,10 @@ tokens:
 a2ui:
   rules:
     - "Self-labeling widget — use the [label] attribute directly; do NOT wrap in <field-ui>. The widget renders its own label inline via CSS attr() pattern. For radio groups, the canonical pattern is a column of bare <radio-ui label='…'> elements sharing a [name=] — no field-ui wrapper around each radio."
+    - rule: 'Use the [name] attribute to group radios — exactly one is selected per name group; form-associated.'
+      reason: 'Standard radio-group semantics; name= is the group key.'
+    - rule: 'For button-style single-select clusters (visually richer) use <segmented-ui> + <segment-ui> instead.'
+      reason: 'Visual + interaction sibling distinction.'
 anti_patterns:
   - description: Wrapping a radio-ui in field-ui. The widget already self-labels.
     wrong: |

package/components/range/range.yaml

@@ -80,7 +80,13 @@ tokens:
   --range-value-color:
     description: Value text color
 a2ui:
-  rules: []
+  rules:
+    - rule: 'Two-handle slider for selecting a range (min + max). Form-associated; emits two-value change events.'
+      reason: 'Range-input contract.'
+    - rule: 'Different from <slider-ui> (single value) — use range when both endpoints matter.'
+      reason: 'Single vs range distinction.'
+    - rule: 'Step attribute controls handle increments; min/max set the bound rails.'
+      reason: 'Standard range knobs.'
 anti_patterns: []
 examples:
   - name: price-range-filter

package/components/rating/rating.a2ui.json

@@ -92,7 +92,10 @@
       "like"
     ],
     "name": "UIRating",
-    "related": [],
+    "related": [
+      "Field",
+      "AgentFeedbackBar"
+    ],
     "slots": {},
     "states": [
       {

package/components/rating/rating.yaml

@@ -61,7 +61,13 @@ states:
 traits: []
 tokens: {}
 a2ui:
-  rules: []
+  rules:
+    - rule: 'Star/icon-based ordinal rating input. Form-associated; emits numeric value 0..max via change events.'
+      reason: 'Rating-input contract.'
+    - rule: 'For thumbs-up/down agent feedback use <agent-feedback-bar-ui> instead — different semantics + visual.'
+      reason: 'Surface boundary.'
+    - rule: 'max attribute sets the scale (default 5); allow-half attribute enables half-step granularity.'
+      reason: 'Configuration knobs.'
 anti_patterns: []
 examples: []
 keywords:
@@ -79,4 +85,6 @@ synonyms:
     - star rating
     - review score
     - feedback rating
-related: []
+related:
+  - Field
+  - AgentFeedbackBar

package/components/richtext/richtext.a2ui.json

@@ -2,7 +2,7 @@
   "$schema": "https://json-schema.org/draft/2020-12/schema",
   "$id": "https://adiaui.dev/a2ui/v0_9/components/RichText.json",
   "title": "RichText",
-  "description": "Renders markdown to styled HTML.",
+  "description": "Markdown-to-HTML rendering primitive — converts the [markdown] prop\n(or fetched [src] content) into styled HTML using the canonical\nprose tokens. Used for rendering LLM responses inside chat surfaces,\narticle bodies, and documentation pages. Distinct from <code-ui>\n(syntax-highlighted code), <textarea-ui> (interactive editor), and\n<text-ui> (single-line typography). Not a Markdown editor — for\nediting use a CodeMirror-backed <code-ui language=\"markdown\"\neditable>.\n",
   "type": "object",
   "allOf": [
     {
@@ -62,7 +62,11 @@
       "richtext"
     ],
     "name": "UIRichText",
-    "related": [],
+    "related": [
+      "Code",
+      "Text",
+      "Textarea"
+    ],
     "slots": {
       "default": {
         "description": "Default slot — primary child content."

package/components/richtext/richtext.d.ts

@@ -1,5 +1,13 @@
 /**
- * `<richtext-ui>` — Renders markdown to styled HTML.
+ * `<richtext-ui>` — Markdown-to-HTML rendering primitive — converts the [markdown] prop
+(or fetched [src] content) into styled HTML using the canonical
+prose tokens. Used for rendering LLM responses inside chat surfaces,
+article bodies, and documentation pages. Distinct from <code-ui>
+(syntax-highlighted code), <textarea-ui> (interactive editor), and
+<text-ui> (single-line typography). Not a Markdown editor — for
+editing use a CodeMirror-backed <code-ui language="markdown"
+editable>.
+
  *
  * @see https://ui-kit.exe.xyz/site/components/richtext
  *

package/components/richtext/richtext.yaml

@@ -4,7 +4,15 @@ tag: richtext-ui
 component: RichText
 category: forms
 version: 1
-description: Renders markdown to styled HTML.
+description: |
+  Markdown-to-HTML rendering primitive — converts the [markdown] prop
+  (or fetched [src] content) into styled HTML using the canonical
+  prose tokens. Used for rendering LLM responses inside chat surfaces,
+  article bodies, and documentation pages. Distinct from <code-ui>
+  (syntax-highlighted code), <textarea-ui> (interactive editor), and
+  <text-ui> (single-line typography). Not a Markdown editor — for
+  editing use a CodeMirror-backed <code-ui language="markdown"
+  editable>.
 props:
   markdown:
     description: 'Component property: markdown.'
@@ -24,7 +32,13 @@ states:
 traits: []
 tokens: {}
 a2ui:
-  rules: []
+  rules:
+    - rule: 'Rich-text display + editor primitive. Renders paragraphs, lists, headings, and inline formatting; contenteditable when editable= is set.'
+      reason: 'Per ADR-0025, no native <textarea> for rich text.'
+    - rule: 'Different from <text-ui> (single semantic block) — richtext handles multi-paragraph + inline marks.'
+      reason: 'Capacity boundary.'
+    - rule: 'For plain code use <code-ui> or richtext with code variant; for chat input use <chat-composer-ui>.'
+      reason: 'Specialized siblings.'
 anti_patterns: []
 examples:
 - name: basic-richtext
@@ -51,4 +65,7 @@ synonyms:
   - markdown
   - md-render
   - rich-text
-related: []
+related:
+  - Code
+  - Text
+  - Textarea

package/components/row/class.js

@@ -20,6 +20,7 @@
 
 import { UIElement } from '../../core/element.js';
 import { draggable } from '../../traits/draggable/draggable.js';
+import { parseResponsive, breakpoint } from '../../core/responsive.js';
 
 export class UIRow extends UIElement {
   static properties = {
@@ -47,4 +48,37 @@ export class UIRow extends UIElement {
       this.#dragAttached = true;
     }
   }
+
+  render() {
+    const gap     = this.gap;
+    const align   = this.align;
+    const justify = this.justify;
+    const anyR    = gap?.includes('@') || align?.includes('@') || justify?.includes('@');
+    const bp      = anyR ? breakpoint.value : '';
+
+    if (gap?.includes('@')) {
+      this.style.setProperty('--row-gap', _gapToCss(parseResponsive(gap, bp)));
+    } else {
+      this.style.removeProperty('--row-gap');
+    }
+
+    if (align?.includes('@')) {
+      this.style.setProperty('--row-align', _flexAlign(parseResponsive(align, bp)));
+    } else {
+      this.style.removeProperty('--row-align');
+    }
+
+    if (justify?.includes('@')) {
+      this.style.setProperty('--row-justify', _flexJustify(parseResponsive(justify, bp)));
+    } else {
+      this.style.removeProperty('--row-justify');
+    }
+  }
 }
+
+const _ALIGN   = { start: 'flex-start', end: 'flex-end', center: 'center', stretch: 'stretch', baseline: 'baseline' };
+const _JUSTIFY = { start: 'flex-start', end: 'flex-end', center: 'center', between: 'space-between', 'space-between': 'space-between', 'space-around': 'space-around' };
+
+function _gapToCss(v)    { return (!v || v === '0') ? '0' : /^\d+$/.test(v) ? `var(--a-space-${v})` : `var(--a-gap-${v})`; }
+function _flexAlign(v)   { return _ALIGN[v]   ?? v; }
+function _flexJustify(v) { return _JUSTIFY[v] ?? v; }

package/components/row/row.a2ui.json

@@ -2,7 +2,7 @@
   "$schema": "https://json-schema.org/draft/2020-12/schema",
   "$id": "https://adiaui.dev/a2ui/v0_9/components/Row.json",
   "title": "Row",
-  "description": "Flex row layout primitive.",
+  "description": "Flex row layout primitive — horizontal stack of children with\n[gap] / [align] / [justify] / [grow] / [wrap]. The horizontal\ncounterpart to <col-ui>. Use <row-ui> for horizontal toolbars,\ninline-control clusters, button groups, table cells. For action\nclusters inside chrome containers (<header-ui> / <footer-ui>) use\nthe parent's [slot=\"action\"] convention instead — the chrome scope\nalready lays out actions correctly without wrapping in row-ui.\n",
   "type": "object",
   "allOf": [
     {
@@ -14,7 +14,7 @@
   ],
   "properties": {
     "align": {
-      "description": "Align items",
+      "description": "Cross-axis alignment (start/center/end/stretch/baseline). Accepts `@bp` notation: align=\"start center@sm\".",
       "type": "string",
       "default": "center"
     },
@@ -27,7 +27,7 @@
       "default": false
     },
     "gap": {
-      "description": "Gap between children. Accepts either the named scale (xs/sm/md/lg/xl) or a numeric rung on the spacing scale (\"1\"…\"16\").",
+      "description": "Gap between children. Named scale (xs/sm/md/lg/xl) or numeric spacing rung (\"1\"…\"16\"). Accepts `@bp` notation: gap=\"2 4@md\".",
       "type": "string",
       "default": "md"
     },
@@ -37,7 +37,7 @@
       "default": false
     },
     "justify": {
-      "description": "Justify content",
+      "description": "Main-axis justify (start/center/end/between/space-between/space-around). Accepts `@bp` notation: justify=\"start between@md\".",
       "type": "string",
       "default": "start"
     },
@@ -90,7 +90,13 @@
         "name": "idle"
       }
     ],
-    "synonyms": {},
+    "synonyms": {
+      "row": [
+        "hstack",
+        "horizontal-stack",
+        "hbox"
+      ]
+    },
     "tag": "row-ui",
     "tokens": {},
     "traits": [],

package/components/row/row.d.ts

@@ -1,5 +1,12 @@
 /**
- * `<row-ui>` — Flex row layout primitive.
+ * `<row-ui>` — Flex row layout primitive — horizontal stack of children with
+[gap] / [align] / [justify] / [grow] / [wrap]. The horizontal
+counterpart to <col-ui>. Use <row-ui> for horizontal toolbars,
+inline-control clusters, button groups, table cells. For action
+clusters inside chrome containers (<header-ui> / <footer-ui>) use
+the parent's [slot="action"] convention instead — the chrome scope
+already lays out actions correctly without wrapping in row-ui.
+
  *
  * @see https://ui-kit.exe.xyz/site/components/row
  *
@@ -13,15 +20,15 @@
 import { UIElement } from '../../core/element.js';
 
 export class UIRow extends UIElement {
-  /** Align items */
+  /** Cross-axis alignment (start/center/end/stretch/baseline). Accepts `@bp` notation: align="start center@sm". */
   align: string;
   /** Enables drag handle + cursor:grab. Wires the draggable trait; dispatches drag-end. */
   draggable: boolean;
-  /** Gap between children. Accepts either the named scale (xs/sm/md/lg/xl) or a numeric rung on the spacing scale ("1"…"16"). */
+  /** Gap between children. Named scale (xs/sm/md/lg/xl) or numeric spacing rung ("1"…"16"). Accepts `@bp` notation: gap="2 4@md". */
   gap: string;
   /** Fills remaining space in a flex parent. CSS-only attribute via :scope[grow] in row.css. */
   grow: boolean;
-  /** Justify content */
+  /** Main-axis justify (start/center/end/between/space-between/space-around). Accepts `@bp` notation: justify="start between@md". */
   justify: string;
   /** Enable flex wrap */
   wrap: boolean;

package/components/row/row.yaml

@@ -6,10 +6,19 @@ tag: row-ui
 component: Row
 category: layout
 version: 1
-description: Flex row layout primitive.
+description: |
+  Flex row layout primitive — horizontal stack of children with
+  [gap] / [align] / [justify] / [grow] / [wrap]. The horizontal
+  counterpart to <col-ui>. Use <row-ui> for horizontal toolbars,
+  inline-control clusters, button groups, table cells. For action
+  clusters inside chrome containers (<header-ui> / <footer-ui>) use
+  the parent's [slot="action"] convention instead — the chrome scope
+  already lays out actions correctly without wrapping in row-ui.
 props:
   align:
-    description: Align items
+    description: >-
+      Cross-axis alignment (start/center/end/stretch/baseline). Accepts
+      `@bp` notation: align="start center@sm".
     type: string
     default: center
   draggable:
@@ -19,8 +28,8 @@ props:
     reflect: true
   gap:
     description: >-
-      Gap between children. Accepts either the named scale (xs/sm/md/lg/xl)
-      or a numeric rung on the spacing scale ("1"…"16").
+      Gap between children. Named scale (xs/sm/md/lg/xl) or numeric spacing
+      rung ("1"…"16"). Accepts `@bp` notation: gap="2 4@md".
     type: string
     default: md
   grow:
@@ -29,7 +38,9 @@ props:
     default: false
     reflect: true
   justify:
-    description: Justify content
+    description: >-
+      Main-axis justify (start/center/end/between/space-between/space-around).
+      Accepts `@bp` notation: justify="start between@md".
     type: string
     default: start
   wrap:
@@ -46,7 +57,13 @@ states:
 traits: []
 tokens: {}
 a2ui:
-  rules: []
+  rules:
+    - rule: 'Horizontal-stack flex container. Children flow left-to-right with token-driven gap.'
+      reason: 'Canonical horizontal layout.'
+    - rule: 'Pair with <col-ui> for vertical layouts; both share the same gap-token contract.'
+      reason: 'Layout symmetry.'
+    - rule: 'Wrap attribute enables flex-wrap; default is nowrap.'
+      reason: 'Single-line vs multi-line knob.'
 anti_patterns: []
 examples:
   - name: chat-interface
@@ -348,7 +365,8 @@ examples:
       ]
 keywords:
   - row
-synonyms: {}
+synonyms:
+  row: [hstack, horizontal-stack, hbox]
 related:
   - avatar
   - input

package/components/search/search.a2ui.json

@@ -94,7 +94,11 @@
       "combobox"
     ],
     "name": "UISearch",
-    "related": [],
+    "related": [
+      "Input",
+      "Command",
+      "Select"
+    ],
     "slots": {
       "clear": {
         "description": "Clear button (shown when value is non-empty)"

package/components/search/search.yaml

@@ -71,7 +71,13 @@ tokens:
   --search-radius:
     description: Input border radius
 a2ui:
-  rules: []
+  rules:
+    - rule: 'Search-input variant of <input-ui> with built-in search icon + clear affordance.'
+      reason: 'Search-input canonical primitive.'
+    - rule: 'For command-palette interactions use <command-ui> (which composes search + menu).'
+      reason: 'Specialized command surface.'
+    - rule: 'Emits input events on each keystroke; debounce in the consumer for live-search.'
+      reason: 'Standard event model.'
 anti_patterns: []
 examples:
   - name: basic-search
@@ -153,4 +159,7 @@ synonyms:
     - search
     - command
     - palette
-related: []
+related:
+  - Input
+  - Command
+  - Select

package/components/section/section.a2ui.json

@@ -70,7 +70,13 @@
         "name": "idle"
       }
     ],
-    "synonyms": {},
+    "synonyms": {
+      "section": [
+        "section-region",
+        "body-region",
+        "content-section"
+      ]
+    },
     "tag": "section-ui",
     "tokens": {},
     "traits": [],

package/components/section/section.yaml

@@ -27,7 +27,40 @@ states:
 traits: []
 tokens: {}
 a2ui:
-  rules: []
+  rules:
+    - >-
+      Use <section-ui> as the content body region inside a primitive
+      container parent (<card-ui>, <drawer-ui>, <modal-ui>, <page-ui>)
+      OR inside the body region of a bespoke shell-tier sidebar
+      (<admin-sidebar> nav body — site/index.html and the admin-shell
+      playground use this canonically). It is a CSS-only chrome stub
+      for ADR-0009 slot vocabulary; the parent's @scope handles padding
+      and borders.
+    - >-
+      `scroll` is a CONDITIONAL attribute. It makes section-ui the
+      scroll container ONLY inside <card-ui> / <drawer-ui> / <modal-ui>.
+      Inside <page-ui> and shell-tier hosts (<admin-shell>,
+      <admin-page-body>) it is a no-op — those parents own their own
+      scroll surface. Never nest <section-ui scroll> inside another
+      scroll container (nested scroll is a UX anti-pattern).
+    - >-
+      Use `bleed` to remove section padding so children reach the
+      card / drawer edges — typical for cover images, full-width charts,
+      or media galleries (apps/saas/members.contents.html uses this
+      pattern to wrap <table-ui raw>). Mix bleed and non-bleed sections
+      in the same card to alternate edge-to-edge media with padded
+      prose.
+    - >-
+      Do NOT substitute <section-ui> for bespoke shell-tier body
+      regions. Inside <admin-page> use <admin-page-body>; inside
+      <admin-content> use the bespoke children. <section-ui> is
+      reserved for the primitive container chrome triad + the
+      <admin-sidebar> nav body.
+    - >-
+      <section-ui> is the right place for layout primitives
+      (<col-ui>, <row-ui>, <grid-ui>) that organize body content. Do
+      NOT put those layout primitives inside <header-ui> or <footer-ui>
+      — the parent's chrome scope already lays those rows out.
 anti_patterns: []
 examples:
   - name: chat-interface
@@ -329,7 +362,8 @@ examples:
       ]
 keywords:
   - section
-synonyms: {}
+synonyms:
+  section: [section-region, body-region, content-section]
 related:
   - avatar
   - input

package/components/segment/segment.a2ui.json

@@ -2,7 +2,7 @@
   "$schema": "https://json-schema.org/draft/2020-12/schema",
   "$id": "https://adiaui.dev/a2ui/v0_9/components/Segment.json",
   "title": "Segment",
-  "description": "Individual segment option, child of segmented-ui.",
+  "description": "Individual segment child of <segmented-ui> — carries the [value],\n[text], optional [icon], and [selected] state for one option in\na horizontal segmented selector. Distinct from <tab-ui> (a view\nswitcher's child) and <option> (native option for <select-ui>).\nUse segment-ui only as a direct child of <segmented-ui>; never\nstandalone.\n",
   "type": "object",
   "allOf": [
     {
@@ -99,7 +99,13 @@
         "name": "disabled"
       }
     ],
-    "synonyms": {},
+    "synonyms": {
+      "segment": [
+        "segment-button",
+        "segmented-option",
+        "option-button"
+      ]
+    },
     "tag": "segment-ui",
     "tokens": {},
     "traits": [],

package/components/segment/segment.d.ts

@@ -1,5 +1,11 @@
 /**
- * `<segment-ui>` — Individual segment option, child of segmented-ui.
+ * `<segment-ui>` — Individual segment child of <segmented-ui> — carries the [value],
+[text], optional [icon], and [selected] state for one option in
+a horizontal segmented selector. Distinct from <tab-ui> (a view
+switcher's child) and <option> (native option for <select-ui>).
+Use segment-ui only as a direct child of <segmented-ui>; never
+standalone.
+
  *
  * @see https://ui-kit.exe.xyz/site/components/segment
  *

package/components/segment/segment.yaml

@@ -6,7 +6,13 @@ tag: segment-ui
 component: Segment
 category: navigation
 version: 1
-description: Individual segment option, child of segmented-ui.
+description: |
+  Individual segment child of <segmented-ui> — carries the [value],
+  [text], optional [icon], and [selected] state for one option in
+  a horizontal segmented selector. Distinct from <tab-ui> (a view
+  switcher's child) and <option> (native option for <select-ui>).
+  Use segment-ui only as a direct child of <segmented-ui>; never
+  standalone.
 # Per ADR-0027 — primitives that programmatically create other primitives
 # do NOT auto-import them. Consumer (or demo shell) must explicitly import.
 composes:
@@ -46,7 +52,13 @@ states:
 traits: []
 tokens: {}
 a2ui:
-  rules: []
+  rules:
+    - rule: 'Child of <segmented-ui> — one selectable option button in a single-select group.'
+      reason: 'Cluster contract.'
+    - rule: 'Different from <toggle-option-ui> (which is multi-select inside <toggle-group-ui>).'
+      reason: 'Single vs multi-select sibling distinction.'
+    - rule: 'Selected state managed by parent <segmented-ui> via active attribute; do not set selected directly on segment.'
+      reason: 'Parent owns selection state.'
 anti_patterns: []
 examples:
   - name: segmented-control
@@ -220,6 +232,7 @@ examples:
       ]
 keywords:
   - segment
-synonyms: {}
+synonyms:
+  segment: [segment-button, segmented-option, option-button]
 related:
   - segmented-control

package/components/segmented/segmented.a2ui.json

@@ -53,7 +53,12 @@
       "button-group"
     ],
     "name": "UISegmented",
-    "related": [],
+    "related": [
+      "Segment",
+      "ToggleGroup",
+      "Tabs",
+      "Radio"
+    ],
     "slots": {
       "default": {
         "description": "Child segment-ui elements that form the toggle group. Children MUST be segment-ui — bare segment tags render text but are silently ignored for the sliding indicator and role/aria-checked state."

package/components/segmented/segmented.css

@@ -32,6 +32,11 @@
     grid-auto-columns: 1fr;
     align-items: stretch;
     position: relative;
+    /* Allow shrinking inside flex/grid containers (e.g. card header action
+       slot). Without this, inline-grid never shrinks below its max-content
+       width and the control overflows rather than triggering the per-segment
+       ::after text-overflow:ellipsis rules. */
+    min-width: 0;
     /* Children use `position: relative; z-index: 1` (segments) so they
        paint above the absolute indicator. Without an own stacking context
        here, those z-indexed children escape into the parent context and

package/components/segmented/segmented.yaml

@@ -24,7 +24,13 @@ states:
 traits: []
 tokens: {}
 a2ui:
-  rules: []
+  rules:
+    - rule: 'Single-select segmented control. Hosts <segment-ui> children; exactly one selected at a time.'
+      reason: 'Single-select cluster contract.'
+    - rule: 'For multi-select use <toggle-group-ui> + <toggle-option-ui> instead.'
+      reason: 'Selection model boundary.'
+    - rule: 'Use for view-mode switches (grid/list, light/dark) or short filter sets (3-5 options); for longer sets use <tabs-ui> or <select-ui>.'
+      reason: 'Capacity guidance.'
 anti_patterns: []
 examples:
 - name: basic-segmented
@@ -116,4 +122,8 @@ synonyms:
   tags:
   - SegmentedControl
   - Segmented
-related: []
+related:
+  - Segment
+  - ToggleGroup
+  - Tabs
+  - Radio