@adia-ai/web-components 0.6.21 → 0.6.22

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

package/components/select/select.a2ui.json

@@ -2,7 +2,7 @@
   "$schema": "https://json-schema.org/draft/2020-12/schema",
   "$id": "https://adiaui.dev/a2ui/v0_9/components/Select.json",
   "title": "Select",
-  "description": "Alias for ChoicePicker. Dropdown select with options.",
+  "description": "Single-select dropdown primitive — the canonical AdiaUI select\ncontrol. Form-bearing via UIFormElement: [name], [value],\n[required], [disabled], fires `change`. Options via native\n<option> / <optgroup> children, programmatic `.options` array, or\nJSON [data-options] (hydrated by <editor-shell>'s wireSelects).\nUse for single-select with > 4 options; for ≤ 4 options use\n<segmented-ui> or <radio-ui>. Multi-select via [multiple searchable].\n",
   "type": "object",
   "allOf": [
     {

package/components/select/select.yaml

@@ -6,7 +6,14 @@ tag: select-ui
 component: Select
 category: input
 version: 1
-description: Alias for ChoicePicker. Dropdown select with options.
+description: |
+  Single-select dropdown primitive — the canonical AdiaUI select
+  control. Form-bearing via UIFormElement: [name], [value],
+  [required], [disabled], fires `change`. Options via native
+  <option> / <optgroup> children, programmatic `.options` array, or
+  JSON [data-options] (hydrated by <editor-shell>'s wireSelects).
+  Use for single-select with > 4 options; for ≤ 4 options use
+  <segmented-ui> or <radio-ui>. Multi-select via [multiple searchable].
 # Per ADR-0027 — primitives that programmatically create other primitives
 # do NOT auto-import them. Consumer (or demo shell) must explicitly import.
 composes:
@@ -166,7 +173,32 @@ tokens: {}
 requiredIcons:
   - caret-up-down
 a2ui:
-  rules: []
+  rules:
+    - >-
+      Use <select-ui> for single-select with > 4 options or any list
+      that benefits from a popover. Prefer <segmented-ui> / <radio-ui>
+      when ≤ 4 visible options fit the row.
+    - >-
+      Compose options via native <option> / <optgroup> children — other
+      tag names are silently ignored (per §225 v0.5.9) and warned once
+      at runtime. Or set `.options` programmatically as an array of
+      `{value, label, disabled?}` (grouped form: `{label, options:[…]}`).
+    - >-
+      For dynamic option lists rendered inside <editor-shell>, set the
+      JSON via the [data-options] attribute — <editor-shell>'s
+      wireSelects() finds select-ui[data-options], JSON.parses the
+      attribute, and assigns `.options` on connect. Useful for
+      static-HTML toolbars where JS hydration would be awkward.
+    - >-
+      <select-ui> owns its own label / hint / error chrome (via
+      [label] / [hint] / [error] props). Only wrap in <field-ui> when
+      you need to share the field-chrome stack with sibling inputs in
+      the same form row group.
+    - >-
+      Enable [searchable] for > 10 options; add [free-text] only when
+      unmatched values are valid (tag entry, email-with-suggestion).
+      Use [multiple searchable] for multi-select rather than
+      authoring a separate multi-select primitive.
 anti_patterns: []
 examples:
   - name: bleed-design-settings

package/components/skeleton/skeleton.a2ui.json

@@ -2,7 +2,7 @@
   "$schema": "https://json-schema.org/draft/2020-12/schema",
   "$id": "https://adiaui.dev/a2ui/v0_9/components/Skeleton.json",
   "title": "Skeleton",
-  "description": "Placeholder shimmer for loading states. Purely presentational.",
+  "description": "Placeholder shimmer for loading states. Purely presentational — animated pulse background with configurable shape via CSS sizing. Use as a structural placeholder while data loads; for zero-state messaging after loading completes use <empty-state-ui> instead.",
   "type": "object",
   "allOf": [
     {
@@ -68,7 +68,12 @@
       "shimmer"
     ],
     "name": "UISkeleton",
-    "related": [],
+    "related": [
+      "EmptyState",
+      "Card",
+      "Table",
+      "List"
+    ],
     "slots": {},
     "states": [
       {

package/components/skeleton/skeleton.d.ts

@@ -1,5 +1,5 @@
 /**
- * `<skeleton-ui>` — Placeholder shimmer for loading states. Purely presentational.
+ * `<skeleton-ui>` — Placeholder shimmer for loading states. Purely presentational — animated pulse background with configurable shape via CSS sizing. Use as a structural placeholder while data loads; for zero-state messaging after loading completes use <empty-state-ui> instead.
  *
  * @see https://ui-kit.exe.xyz/site/components/skeleton
  *