@adia-ai/web-components 0.6.20 → 0.6.22

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
  *

package/components/skeleton/skeleton.yaml

@@ -6,7 +6,11 @@ tag: skeleton-ui
 component: Skeleton
 category: display
 version: 1
-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.
 props:
   height:
     description: Height of the placeholder.
@@ -38,7 +42,13 @@ states:
 traits: []
 tokens: {}
 a2ui:
-  rules: []
+  rules:
+    - rule: 'Use to placeholder content during loading. Shape via CSS sizing (width/height/border-radius); shimmer is automatic.'
+      reason: 'Purely structural placeholder.'
+    - rule: 'Compose multiple <skeleton-ui> blocks to mock the actual content shape (card-skeleton, row-skeleton, etc.).'
+      reason: 'Better UX than single block — preview structure.'
+    - rule: 'For post-load empty states use <empty-state-ui> instead; skeleton is pre-load only.'
+      reason: 'Different lifecycle phase.'
 anti_patterns: []
 examples:
   - name: loading-skeleton
@@ -145,4 +155,8 @@ synonyms:
     - loading
     - skeleton
     - progress
-related: []
+related:
+  - EmptyState
+  - Card
+  - Table
+  - List

package/components/slider/slider.yaml

@@ -92,7 +92,13 @@ tokens:
   --slider-track-height:
     description: Full track height (scales via universal [size] attribute)
 a2ui:
-  rules: []
+  rules:
+    - rule: 'Single-handle slider for selecting one value in a range. Form-associated; emits numeric change events.'
+      reason: 'Single-value range-input contract.'
+    - rule: 'For two-handle range selection use <range-ui> instead.'
+      reason: 'Single vs range sibling.'
+    - rule: 'Step attribute controls increments; show-value enables an inline value label.'
+      reason: 'Standard slider knobs.'
 anti_patterns: []
 examples:
   - name: slider-range

package/components/stack/stack.a2ui.json

@@ -2,7 +2,7 @@
   "$schema": "https://json-schema.org/draft/2020-12/schema",
   "$id": "https://adiaui.dev/a2ui/v0_9/components/Stack.json",
   "title": "Stack",
-  "description": "Grid overlay layout — children stack on top of each other.",
+  "description": "Grid-overlay layout primitive — children stack on TOP of each\nother in a single grid cell (z-axis layering). Distinct from\n<col-ui> (vertical) / <row-ui> (horizontal) / <grid-ui> (2D\ngrid with cells). Use stack-ui for badge overlays on avatars,\nabsolute-positioned UI on top of charts, loading spinners over\ncontent, or any case where children must occupy the same physical\nspace. [align] controls how children align within the shared\ncell.\n",
   "type": "object",
   "allOf": [
     {
@@ -42,7 +42,11 @@
       "stack"
     ],
     "name": "UIStack",
-    "related": [],
+    "related": [
+      "Col",
+      "Row",
+      "Grid"
+    ],
     "slots": {
       "default": {
         "description": "Default slot — primary child content."
@@ -54,7 +58,14 @@
         "name": "idle"
       }
     ],
-    "synonyms": {},
+    "synonyms": {
+      "stack": [
+        "overlay-stack",
+        "z-stack",
+        "grid-overlay",
+        "layer"
+      ]
+    },
     "tag": "stack-ui",
     "tokens": {},
     "traits": [],

package/components/stack/stack.d.ts

@@ -1,5 +1,13 @@
 /**
- * `<stack-ui>` — Grid overlay layout — children stack on top of each other.
+ * `<stack-ui>` — Grid-overlay layout primitive — children stack on TOP of each
+other in a single grid cell (z-axis layering). Distinct from
+<col-ui> (vertical) / <row-ui> (horizontal) / <grid-ui> (2D
+grid with cells). Use stack-ui for badge overlays on avatars,
+absolute-positioned UI on top of charts, loading spinners over
+content, or any case where children must occupy the same physical
+space. [align] controls how children align within the shared
+cell.
+
  *
  * @see https://ui-kit.exe.xyz/site/components/stack
  *

package/components/stack/stack.yaml

@@ -6,7 +6,15 @@ tag: stack-ui
 component: Stack
 category: layout
 version: 1
-description: Grid overlay layout — children stack on top of each other.
+description: |
+  Grid-overlay layout primitive — children stack on TOP of each
+  other in a single grid cell (z-axis layering). Distinct from
+  <col-ui> (vertical) / <row-ui> (horizontal) / <grid-ui> (2D
+  grid with cells). Use stack-ui for badge overlays on avatars,
+  absolute-positioned UI on top of charts, loading spinners over
+  content, or any case where children must occupy the same physical
+  space. [align] controls how children align within the shared
+  cell.
 props:
   align:
     description: Alignment of stacked items
@@ -22,7 +30,13 @@ states:
 traits: []
 tokens: {}
 a2ui:
-  rules: []
+  rules:
+    - rule: 'Overlay/layer stacking container — children occupy the same area, stacked on the z-axis.'
+      reason: 'Different from row/col which lay out side-by-side.'
+    - rule: 'Use for overlapping content (image + overlay, badge-over-avatar, drop-shadow stacks).'
+      reason: 'Z-axis composition.'
+    - rule: 'Do not use for vertical content flow — that''s <col-ui>. Stack-ui is overlap-only.'
+      reason: 'Naming pitfall (stack ≠ vstack).'
 anti_patterns: []
 examples:
   - name: basic-stack
@@ -50,5 +64,9 @@ examples:
       ]
 keywords:
   - stack
-synonyms: {}
-related: []
+synonyms:
+  stack: [overlay-stack, z-stack, grid-overlay, layer]
+related:
+  - Col
+  - Row
+  - Grid

package/components/stat/stat.a2ui.json

@@ -2,7 +2,7 @@
   "$schema": "https://json-schema.org/draft/2020-12/schema",
   "$id": "https://adiaui.dev/a2ui/v0_9/components/Stat.json",
   "title": "Stat",
-  "description": "Metric/KPI display — value + label + optional change indicator and trend.",
+  "description": "Metric/KPI display — value + label + optional change indicator and trend icon. Renders as a stacked block with prominent value and small caption; supports positive/negative delta coloring. Use inside dashboard cards or summary headers; for inline percentages or progress use <progress-ui>.",
   "type": "object",
   "allOf": [
     {
@@ -87,7 +87,11 @@
       "scoreboard"
     ],
     "name": "UIStat",
-    "related": [],
+    "related": [
+      "Card",
+      "Badge",
+      "Progress"
+    ],
     "slots": {
       "change": {
         "description": "Child content region for the `change` slot."

package/components/stat/stat.css

@@ -13,8 +13,8 @@
     --stat-icon-fg:      var(--a-fg-muted);
 
     /* ── Spacing ── */
-    --stat-column-gap:   var(--a-space-3);
-    --stat-row-gap:      var(--a-space-2);
+    --stat-column-gap:   var(--a-gap);
+    --stat-row-gap:      var(--a-gap-sm);
   }
 
   :scope {
@@ -74,6 +74,9 @@
     color: var(--stat-label-fg);
     line-height: 1.4;
     min-width: 0;
+    overflow: hidden;
+    text-overflow: ellipsis;
+    white-space: nowrap;
   }
 
   /* ── Change delta (under value) ── */

package/components/stat/stat.d.ts

@@ -1,5 +1,5 @@
 /**
- * `<stat-ui>` — Metric/KPI display — value + label + optional change indicator and trend.
+ * `<stat-ui>` — Metric/KPI display — value + label + optional change indicator and trend icon. Renders as a stacked block with prominent value and small caption; supports positive/negative delta coloring. Use inside dashboard cards or summary headers; for inline percentages or progress use <progress-ui>.
  *
  * @see https://ui-kit.exe.xyz/site/components/stat
  *

package/components/stat/stat.yaml

@@ -9,7 +9,11 @@ composes:
 component: Stat
 category: display
 version: 1
-description: Metric/KPI display — value + label + optional change indicator and trend.
+description: >-
+  Metric/KPI display — value + label + optional change indicator and trend
+  icon. Renders as a stacked block with prominent value and small caption;
+  supports positive/negative delta coloring. Use inside dashboard cards or
+  summary headers; for inline percentages or progress use <progress-ui>.
 props:
   change:
     description: Change indicator text (e.g. '+12%', '-3%')
@@ -86,7 +90,13 @@ tokens:
   --stat-value-weight:
     description: Font weight for the primary value
 a2ui:
-  rules: []
+  rules:
+    - rule: 'Use for prominent metric/KPI displays inside dashboard cards. Value + label + optional delta indicator.'
+      reason: 'Canonical metric primitive — dashboard surfaces compose 3-6 of these.'
+    - rule: 'For inline percent/progress displays use <progress-ui>; stat is for standalone metrics, progress for completion bars.'
+      reason: 'Different visual + semantic role.'
+    - rule: 'Delta indicator uses positive/negative semantic tokens; pass change= attribute with sign.'
+      reason: 'Built-in trend coloring; no manual styling needed.'
 anti_patterns: []
 examples:
   - name: basic-stat
@@ -220,4 +230,7 @@ synonyms:
     - metric
     - chart
     - stat
-related: []
+related:
+  - Card
+  - Badge
+  - Progress

package/components/step-progress/step-progress.yaml

@@ -45,7 +45,13 @@ states:
 traits: []
 tokens: {}
 a2ui:
-  rules: []
+  rules:
+    - rule: 'Compact step indicator — N dots/segments showing current step out of total.'
+      reason: 'Minimal stepper visualization.'
+    - rule: 'Different from <stepper-ui> (labeled, expanded) — step-progress is dense and label-free.'
+      reason: 'Density boundary.'
+    - rule: 'For multi-task progress bars (multiple labeled rows) use <progress-row-ui> stack.'
+      reason: 'Different layout.'
 anti_patterns: []
 
 examples:

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

@@ -53,9 +53,19 @@
     "composes": [],
     "events": {},
     "examples": [],
-    "keywords": [],
+    "keywords": [
+      "stepper-item",
+      "step",
+      "wizard-step",
+      "progress-step",
+      "step-row"
+    ],
     "name": "UIStepperItem",
-    "related": [],
+    "related": [
+      "Stepper",
+      "Timeline",
+      "StepProgress"
+    ],
     "slots": {
       "description": {
         "description": "Custom description content; falls through to `[description]` prop if not slotted."
@@ -65,7 +75,14 @@
       }
     },
     "states": [],
-    "synonyms": {},
+    "synonyms": {
+      "stepper-item": [
+        "step",
+        "wizard-step",
+        "progress-step",
+        "checkpoint"
+      ]
+    },
     "tag": "stepper-item-ui",
     "tokens": {},
     "traits": [],

package/components/stepper/stepper-item.yaml

@@ -43,3 +43,27 @@ slots:
     description: Custom label content; falls through to `[text]` prop if not slotted.
   description:
     description: Custom description content; falls through to `[description]` prop if not slotted.
+
+keywords:
+  - stepper-item
+  - step
+  - wizard-step
+  - progress-step
+  - step-row
+
+synonyms:
+  stepper-item: [step, wizard-step, progress-step, checkpoint]
+
+related:
+  - Stepper
+  - Timeline
+  - StepProgress
+
+a2ui:
+  rules:
+    - rule: 'Child of <stepper-ui> — one numbered step with label + complete/current/upcoming state.'
+      reason: 'Cluster contract.'
+    - rule: 'State driven by parent''s active-index; do not set state directly on stepper-item.'
+      reason: 'Parent owns step progression.'
+    - rule: 'For chronological events (no completion semantics) use <timeline-item-ui> instead.'
+      reason: 'Stepper is process; timeline is history.'

package/components/stepper/stepper.a2ui.json

@@ -2,7 +2,7 @@
   "$schema": "https://json-schema.org/draft/2020-12/schema",
   "$id": "https://adiaui.dev/a2ui/v0_9/components/Stepper.json",
   "title": "Stepper",
-  "description": "Wizard / process stepper — parent step index drives numbered children.",
+  "description": "Wizard / process stepper — parent step index drives numbered children's complete/current/upcoming states automatically. Renders horizontally as a labeled step bar with connectors. Use for multi-step forms, onboarding, or pipelines; for read-only event history use <timeline-ui> instead.",
   "type": "object",
   "allOf": [
     {

package/components/stepper/stepper.d.ts

@@ -1,5 +1,5 @@
 /**
- * `<stepper-ui>` — Wizard / process stepper — parent step index drives numbered children.
+ * `<stepper-ui>` — Wizard / process stepper — parent step index drives numbered children's complete/current/upcoming states automatically. Renders horizontally as a labeled step bar with connectors. Use for multi-step forms, onboarding, or pipelines; for read-only event history use <timeline-ui> instead.
  *
  * @see https://ui-kit.exe.xyz/site/components/stepper
  *

package/components/stepper/stepper.yaml

@@ -6,7 +6,12 @@ tag: stepper-ui
 component: Stepper
 category: navigation
 version: 1
-description: Wizard / process stepper — parent step index drives numbered children.
+description: >-
+  Wizard / process stepper — parent step index drives numbered children's
+  complete/current/upcoming states automatically. Renders horizontally as
+  a labeled step bar with connectors. Use for multi-step forms,
+  onboarding, or pipelines; for read-only event history use <timeline-ui>
+  instead.
 # Per ADR-0027 — primitives that programmatically create other primitives
 # do NOT auto-import them. Consumer (or demo shell) must explicitly import.
 composes:
@@ -30,7 +35,13 @@ states:
 traits: []
 tokens: {}
 a2ui:
-  rules: []
+  rules:
+    - rule: 'Hosts <stepper-item-ui> children with a parent active-index driving complete/current/upcoming states.'
+      reason: 'Process visualization cluster.'
+    - rule: 'Use for wizards, onboarding flows, multi-step forms.'
+      reason: 'Surface examples.'
+    - rule: 'For read-only event history use <timeline-ui>; stepper requires forward progress semantics.'
+      reason: 'Decision rule vs timeline.'
 anti_patterns: []
 examples:
   - name: basic

package/components/stream/stream.a2ui.json

@@ -68,7 +68,11 @@
       "stream"
     ],
     "name": "UIStream",
-    "related": [],
+    "related": [
+      "ChatThreadUI",
+      "Text",
+      "Code"
+    ],
     "slots": {
       "default": {
         "description": "Default slot — primary child content."
@@ -80,7 +84,13 @@
         "name": "idle"
       }
     ],
-    "synonyms": {},
+    "synonyms": {
+      "stream": [
+        "streaming-text",
+        "live-text",
+        "incremental-text"
+      ]
+    },
     "tag": "stream-ui",
     "tokens": {
       "--stream-color": {

package/components/stream/stream.yaml

@@ -50,7 +50,15 @@ tokens:
   --stream-line-height:
     description: Line height
 a2ui:
-  rules: []
+  rules:
+    - rule: 'Renders an AsyncIterable<string> as streaming text — canonical for LLM token streaming.'
+      reason: 'Streaming primitive.'
+    - rule: 'Place inside <chat-thread-ui> message bodies for LLM responses; standalone for log tailing.'
+      reason: 'Composition pattern.'
+    - rule: 'pace attribute controls typewriter-effect speed; hide-cursor disables the blinking caret.'
+      reason: 'Visual knobs.'
+    - rule: 'For static (post-stream) display use <text-ui> or <richtext-ui>; stream-ui assumes live token feed.'
+      reason: 'Live vs static.'
 anti_patterns: []
 examples:
   - name: streaming-response
@@ -87,5 +95,9 @@ examples:
       ]
 keywords:
   - stream
-synonyms: {}
-related: []
+synonyms:
+  stream: [streaming-text, live-text, incremental-text]
+related:
+  - ChatThreadUI
+  - Text
+  - Code

package/components/swatch/swatch.yaml

@@ -150,7 +150,13 @@ tokens:
   --swatch-select-ring:
     description: Color of the focus + selected ring when [selectable] is set.
 a2ui:
-  rules: []
+  rules:
+    - rule: 'Use to display a single color sample with optional label. For interactive color picking use <color-picker-ui>.'
+      reason: 'Swatch is read-only display; picker is input.'
+    - rule: 'Inside design-token displays or palette grids; not for general decoration.'
+      reason: 'Semantic purpose: color sample.'
+    - rule: 'Color value accepts hex, rgb, hsl, or oklch; oklch preferred for AdiaUI token alignment.'
+      reason: 'Canonical color space.'
 anti_patterns: []
 examples:
   - name: basic-swatch

package/components/swiper/swiper.yaml

@@ -95,7 +95,13 @@ states:
 traits: []
 tokens: {}
 a2ui:
-  rules: []
+  rules:
+    - rule: 'Horizontal slide carousel with touch + arrow nav. Hosts arbitrary children as slides.'
+      reason: 'Slide-based content discovery.'
+    - rule: 'For tab-switched peer views use <tabs-ui>; swiper is for content browsing, not panel switching.'
+      reason: 'Different interaction model.'
+    - rule: 'Set autoplay attribute for timed-rotation; otherwise user-driven only.'
+      reason: 'Affordance knob.'
 anti_patterns: []
 examples:
 - name: image-carousel

package/components/switch/switch.a2ui.json

@@ -2,7 +2,7 @@
   "$schema": "https://json-schema.org/draft/2020-12/schema",
   "$id": "https://adiaui.dev/a2ui/v0_9/components/Switch.json",
   "title": "Switch",
-  "description": "Toggle switch. The host IS the control.",
+  "description": "Toggle switch primitive — binary on/off control where the host IS\nthe control (per ADR-0025, no native <input type=\"checkbox\"> wrapped\nunderneath). Form-bearing via UIFormElement: [name], [value],\n[checked] (reflect), [required], [disabled]. Distinct from <check-ui>\n— use switch-ui for setting-style toggles (notifications on/off,\ndark mode, feature flags), check-ui for opt-in lists, terms\nacceptance, multi-select rows.\n",
   "type": "object",
   "allOf": [
     {
@@ -95,7 +95,11 @@
       "switch"
     ],
     "name": "UISwitch",
-    "related": [],
+    "related": [
+      "Check",
+      "Radio",
+      "Field"
+    ],
     "slots": {
       "hint": {
         "description": "Help text below the label"

package/components/switch/switch.yaml

@@ -4,7 +4,14 @@ tag: switch-ui
 component: Switch
 category: layout
 version: 1
-description: Toggle switch. The host IS the control.
+description: |
+  Toggle switch primitive — binary on/off control where the host IS
+  the control (per ADR-0025, no native <input type="checkbox"> wrapped
+  underneath). Form-bearing via UIFormElement: [name], [value],
+  [checked] (reflect), [required], [disabled]. Distinct from <check-ui>
+  — use switch-ui for setting-style toggles (notifications on/off,
+  dark mode, feature flags), check-ui for opt-in lists, terms
+  acceptance, multi-select rows.
 props:
   name:
     description: Form field name
@@ -86,6 +93,10 @@ a2ui:
     inline via CSS attr() pattern. For settings rows (label-left, switch-right), put the descriptive text in switch-ui's own
     [label] attribute; do not introduce a field-ui wrapper. For descriptive helper text below the switch, use <text-ui variant='caption'>
     as a sibling — not field-ui's hint slot.
+  - rule: 'Binary on/off only — no third state. For tri-state controls use <check-ui> with [indeterminate].'
+    reason: 'State-model boundary vs check-ui.'
+  - rule: 'Use for settings toggles, feature flags, mode switches; for form gates / consent / multi-select use <check-ui> instead.'
+    reason: 'Semantic role — switch = setting, check = selection/acceptance.'
 anti_patterns:
 - description: Wrapping a switch-ui in field-ui. The widget already self-labels.
   wrong: "<field-ui inline label=\"Email notifications\">\n  <switch-ui></switch-ui>\n</field-ui>\n"
@@ -140,4 +151,7 @@ synonyms:
   tags:
   - Toggle
   - Switch
-related: []
+related:
+  - Check
+  - Radio
+  - Field