@adia-ai/web-components 0.6.21 → 0.6.22

package/components/button/button.yaml

@@ -139,7 +139,15 @@ tokens:
   --density:
     description: Inherited multiplier for padding
 a2ui:
-  rules: []
+  rules:
+    - rule: 'Canonical clickable affordance — text + optional icon. Variant attribute sets primary/secondary/ghost/destructive intent.'
+      reason: 'Most-used interactive primitive.'
+    - rule: 'Do not repeat the icon''s glyph in text=. Icon provides the symbol; text= carries only the words.'
+      reason: 'Per existing slot.discipline rule — visual redundancy guard.'
+    - rule: 'For navigation (route-change) use <nav-item-ui> or anchor; button-ui is for actions only.'
+      reason: 'Action vs navigation semantics.'
+    - rule: 'For toggleable on/off state use <switch-ui>; for multi-select clusters use <toggle-group-ui> + <toggle-option-ui>.'
+      reason: 'Stateless action vs stateful toggle.'
 anti_patterns:
   - description: >-
       Beginning text= with a symbol that icon= already renders. icon="plus"
@@ -154,6 +162,16 @@ anti_patterns:
       text= carries only the words. Applies to plus / minus / x / check /
       arrow icons.
 examples: []
-keywords: []
-synonyms: {}
+keywords:
+  - button
+  - action
+  - cta
+  - submit
+  - click
+  - primary-action
+  - ghost-button
+  - icon-button
+synonyms:
+  button: [btn, action-button, click-target, control]
+  submit: [form-submit, primary-action]
 related: [Link]

package/components/calendar-picker/calendar-picker.a2ui.json

@@ -2,7 +2,7 @@
   "$schema": "https://json-schema.org/draft/2020-12/schema",
   "$id": "https://adiaui.dev/a2ui/v0_9/components/CalendarPicker.json",
   "title": "CalendarPicker",
-  "description": "Date picker with trigger button and popover calendar grid. Form-associated.",
+  "description": "Date picker with trigger button and popover calendar grid. Form-associated input emitting ISO date string via change events; supports min/max and disabled-date masks. Use for single-date input in forms; for date ranges compose two pickers or use a dedicated range component.",
   "type": "object",
   "allOf": [
     {

package/components/calendar-picker/calendar-picker.yaml

@@ -4,7 +4,12 @@ tag: calendar-picker-ui
 component: CalendarPicker
 category: input
 version: 1
-description: Date picker with trigger button and popover calendar grid. Form-associated.
+description: >-
+  Date picker with trigger button and popover calendar grid.
+  Form-associated input emitting ISO date string via change events;
+  supports min/max and disabled-date masks. Use for single-date input in
+  forms; for date ranges compose two pickers or use a dedicated range
+  component.
 props:
   name:
     description: Form field name
@@ -76,7 +81,13 @@ requiredIcons:
   - caret-left
   - caret-right
 a2ui:
-  rules: []
+  rules:
+    - rule: 'Form-associated date input. Trigger button + popover calendar grid; emits ISO date string via change events.'
+      reason: 'Standard date-picker contract.'
+    - rule: 'Use for single-date input. For date ranges compose two pickers or use a dedicated range component.'
+      reason: 'Single-value scope.'
+    - rule: 'min/max attributes constrain selectable range; disabled-dates accepts a function or date list.'
+      reason: 'Constraint knobs.'
 anti_patterns: []
 examples:
 - name: date-picker

package/components/canvas/canvas.a2ui.json

@@ -2,7 +2,7 @@
   "$schema": "https://json-schema.org/draft/2020-12/schema",
   "$id": "https://adiaui.dev/a2ui/v0_9/components/Canvas.json",
   "title": "Canvas",
-  "description": "A2UI rendering surface.",
+  "description": "A2UI rendering surface — the canonical mount point that consumes a\nDocStore / A2UI document and renders the component tree from it.\nThe runtime's <a2ui-root> typically wraps a canvas-ui internally\nfor the preview pane in <editor-canvas>. Use for embedding live\nA2UI output inside a custom editor, playground, or preview surface;\nnot for generic in-page canvases (use HTML <canvas> for drawing).\n",
   "type": "object",
   "allOf": [
     {
@@ -46,7 +46,11 @@
       "canvas"
     ],
     "name": "UICanvas",
-    "related": [],
+    "related": [
+      "A2uiRoot",
+      "GenRoot",
+      "EditorCanvas"
+    ],
     "slots": {
       "default": {
         "description": "Default slot — primary child content."

package/components/canvas/canvas.yaml

@@ -4,7 +4,13 @@ tag: canvas-ui
 component: Canvas
 category: agent
 version: 1
-description: A2UI rendering surface.
+description: |
+  A2UI rendering surface — the canonical mount point that consumes a
+  DocStore / A2UI document and renders the component tree from it.
+  The runtime's <a2ui-root> typically wraps a canvas-ui internally
+  for the preview pane in <editor-canvas>. Use for embedding live
+  A2UI output inside a custom editor, playground, or preview surface;
+  not for generic in-page canvases (use HTML <canvas> for drawing).
 # Per ADR-0027 — primitives that programmatically create other primitives
 # do NOT auto-import them. Consumer (or demo shell) must explicitly import.
 # <canvas-ui> composes only cross-package primitives (a2ui-root + theme-ui);
@@ -34,7 +40,15 @@ states:
 traits: []
 tokens: {}
 a2ui:
-  rules: []
+  rules:
+    - rule: 'A2UI rendering surface — consumes a DocStore / A2UI document and renders the component tree from it.'
+      reason: 'Runtime mount point.'
+    - rule: 'Typically wrapped by <a2ui-root> internally; for direct-mount use <canvas-ui> as the root.'
+      reason: 'Mount-point hierarchy.'
+    - rule: 'Do not place static children inside — the runtime owns the rendered DOM.'
+      reason: 'Reserved DOM region.'
+    - rule: 'theme attribute scopes the AdiaUI token theme to the canvas subtree.'
+      reason: 'Theme isolation knob.'
 anti_patterns: []
 examples:
 - name: basic-canvas
@@ -48,4 +62,7 @@ synonyms:
   tags:
   - render-surface
   - a2ui-host
-related: []
+related:
+  - A2uiRoot
+  - GenRoot
+  - EditorCanvas

package/components/card/card.css

@@ -182,9 +182,13 @@
   /* Column templates — match gen-ui-kit pattern. Direct-child `:has(> …)` so
      nested [slot="icon"] inside a composite (e.g. <avatar-ui>) can't trigger
      the icon column by accident. */
-  & > header:has(> [slot="icon"]):has(> [slot="action"])         { grid-template-columns: max-content 1fr max-content; }
+  /* `auto` on the action column = minmax(min-content, max-content): takes
+     max-content size when space allows, shrinks to min-content when the card
+     is narrow. This lets segmented-ui / button groups in the action slot
+     compress and show per-segment ellipsis rather than overflowing. */
+  & > header:has(> [slot="icon"]):has(> [slot="action"])         { grid-template-columns: max-content 1fr auto; }
   & > header:has(> [slot="icon"]):not(:has(> [slot="action"]))   { grid-template-columns: max-content 1fr; }
-  & > header:not(:has(> [slot="icon"])):has(> [slot="action"])   { grid-template-columns: 1fr max-content; }
+  & > header:not(:has(> [slot="icon"])):has(> [slot="action"])   { grid-template-columns: 1fr auto; }
   & > header:not(:has(> [slot="icon"])):not(:has(> [slot="action"])) { grid-template-columns: 1fr; }
 
   /* Unslotted children (zettel fragment injection, etc.) — each on its own row,
@@ -249,6 +253,7 @@
     display: flex;
     align-items: center;
     gap: var(--card-header-gap);
+    min-width: 0; /* allow flex children (segmented-ui, button) to shrink */
   }
 
   /* ═══════ Section (body) ═══════
@@ -271,6 +276,22 @@
     padding: 0;
   }
 
+  /* Flex-column growth for bleed chart cards (sparklines, area, line).
+     Switches the card to a column flex container so the bleed section
+     can flex-grow to fill remaining height after the header. The chart
+     then uses height:100% to fill the section. Only activates when a
+     chart-ui is a direct child of a bleed section — no effect on other
+     card layouts. */
+  :scope:has(> section[bleed] > chart-ui) {
+    display: flex;
+    flex-direction: column;
+  }
+
+  :scope:has(> section[bleed] > chart-ui) > section[bleed] {
+    flex: 1;
+    min-height: 0;
+  }
+
   /* ═══════ Footer ═══════
      Margin-based inset. Flex row for actions.
      [divider] adds top border.

package/components/card/card.yaml

@@ -97,6 +97,18 @@ a2ui:
     content (tables, charts); [padding] adds a canvas-scrim background for hero regions.
   - 'Footer with a [slot="description"] + [slot="action"] pair triggers justify-content: space-between — useful for a "Last
     saved …" note on the left and a Save/Cancel button group on the right.'
+  - >-
+    Do NOT substitute <card-ui> for shell/page containers. <admin-page>,
+    <admin-content>, and <page-ui> own routed page layout; <card-ui> is
+    a localized bordered surface that lives INSIDE them. For overlays
+    use <modal-ui> (centered) or <drawer-ui> (edge-anchored) — both
+    share the same 4-stub <header>/<section>/<footer> vocabulary.
+  - >-
+    Use [raw] when a parent already owns the surface chrome (e.g. an
+    auth screen centred on the viewport — see apps/user-flow/auth).
+    Use [elevation] 0–3 for shadow depth; [variant="ghost"|"flat"] to
+    remove shadow without removing structure. [draggable] emits a
+    drag-end event; only enable on cards meant to move.
 anti_patterns: []
 examples:
 - name: chat-interface

package/components/chart/chart.css

@@ -611,9 +611,11 @@
   }
 
   /* ── Sparkline container ──
-     When host has explicit height, fill it; otherwise give a sensible
-     default of 2rem so the sparkline still has room to breathe. */
+     `height: 100%` fills an explicit parent height (e.g. when the
+     containing section is a flex-grow item inside card-ui). Falls
+     back to `min-height: 2rem` when the parent has no explicit height. */
   :scope[type="sparkline"] {
+    height: 100%;
     min-height: 2rem;
   }
 

package/components/chart/chart.yaml

@@ -172,7 +172,15 @@ states:
 traits: []
 tokens: {}
 a2ui:
-  rules: []
+  rules:
+    - rule: 'Declarative SVG chart supporting 18 types via the type attribute (bar, line, pie, donut, radar, area, ...).'
+      reason: 'Polymorphic chart primitive.'
+    - rule: 'For density-grid visualizations (calendar heatmap, etc.) use <heatmap-ui> instead.'
+      reason: 'Specialized sibling.'
+    - rule: 'Pair with <chart-legend-ui [for]=...> for keyboard-toggleable series legends; otherwise use the built-in inline legend.'
+      reason: 'Legend composition.'
+    - rule: 'title + empty slots for chart chrome; canvas slot for chart-internal overlays.'
+      reason: 'Slot contract.'
 anti_patterns: []
 examples:
   - name: chart-dashboard

package/components/chart-legend/chart-legend.yaml

@@ -95,7 +95,13 @@ states:
 traits: []
 tokens: {}
 a2ui:
-  rules: []
+  rules:
+    - rule: 'Standalone legend primitive — a row of <badge-ui>+<swatch-ui> chips that are keyboard-focusable and click-toggleable.'
+      reason: 'Legend pattern.'
+    - rule: 'Pairs with <chart-ui> via [for] id-ref (auto-bidirectional series toggling) or via items= for standalone use.'
+      reason: 'Composition contract.'
+    - rule: 'position attribute (top|bottom|left|right) places legend relative to its chart; static= disables interactivity.'
+      reason: 'Layout + interaction knobs.'
 anti_patterns: []
 examples:
   - name: standalone-with-items

package/components/chat-thread/chat-thread.a2ui.json

@@ -2,7 +2,7 @@
   "$schema": "https://json-schema.org/draft/2020-12/schema",
   "$id": "https://adiaui.dev/a2ui/v0_9/components/ChatThread.json",
   "title": "ChatThread",
-  "description": "Minimal chat-thread container.",
+  "description": "Primitive chat message thread surface — a minimal scroll container\nfor ad-hoc message rendering. Distinct from the bespoke shell\nchild <chat-thread> (module-tier, lives inside <chat-shell>, owns\nscroll-to-bottom + [streaming] + [empty] reflected state). Use\nchat-thread-ui when embedding chat-like rows OUTSIDE a chat-shell\n(e.g. a comment thread inside <card-ui>); use <chat-thread> when\nauthoring a chat-shell.\n",
   "type": "object",
   "allOf": [
     {
@@ -87,7 +87,11 @@
       "support"
     ],
     "name": "UIChatThread",
-    "related": [],
+    "related": [
+      "ChatThread",
+      "List",
+      "Feed"
+    ],
     "slots": {
       "default": {
         "description": "Default slot — primary child content."

package/components/chat-thread/chat-thread.d.ts

@@ -1,5 +1,12 @@
 /**
- * `<chat-thread-ui>` — Minimal chat-thread container.
+ * `<chat-thread-ui>` — Primitive chat message thread surface — a minimal scroll container
+for ad-hoc message rendering. Distinct from the bespoke shell
+child <chat-thread> (module-tier, lives inside <chat-shell>, owns
+scroll-to-bottom + [streaming] + [empty] reflected state). Use
+chat-thread-ui when embedding chat-like rows OUTSIDE a chat-shell
+(e.g. a comment thread inside <card-ui>); use <chat-thread> when
+authoring a chat-shell.
+
  *
  * @see https://ui-kit.exe.xyz/site/components/chat-thread
  *

package/components/chat-thread/chat-thread.yaml

@@ -6,7 +6,14 @@ tag: chat-thread-ui
 component: ChatThread
 category: agent
 version: 1
-description: Minimal chat-thread container.
+description: |
+  Primitive chat message thread surface — a minimal scroll container
+  for ad-hoc message rendering. Distinct from the bespoke shell
+  child <chat-thread> (module-tier, lives inside <chat-shell>, owns
+  scroll-to-bottom + [streaming] + [empty] reflected state). Use
+  chat-thread-ui when embedding chat-like rows OUTSIDE a chat-shell
+  (e.g. a comment thread inside <card-ui>); use <chat-thread> when
+  authoring a chat-shell.
 props:
   streaming:
     description: "Component property: streaming."
@@ -31,7 +38,15 @@ states:
 traits: []
 tokens: {}
 a2ui:
-  rules: []
+  rules:
+    - rule: 'Primitive chat-message scroll container — ad-hoc message rendering surface.'
+      reason: 'Lowest-friction chat surface.'
+    - rule: 'Different from the bespoke <chat-thread> (module-tier, lives inside <chat-shell-ui>, owns scroll + load-more affordances).'
+      reason: 'Primitive vs cluster-child boundary.'
+    - rule: 'Hosts arbitrary children — typical content: agent + user message blocks, <agent-feedback-bar-ui>, <agent-suggestions-ui>.'
+      reason: 'Composition pattern.'
+    - rule: 'streaming attribute hints the consumer to show a streaming indicator (composes well with <stream-ui> children).'
+      reason: 'Streaming UX.'
 anti_patterns: []
 examples:
   - name: basic-chat
@@ -234,4 +249,7 @@ synonyms:
     - faq
     - accordion
     - chat
-related: []
+related:
+  - ChatThread
+  - List
+  - Feed

package/components/check/check.a2ui.json

@@ -2,7 +2,7 @@
   "$schema": "https://json-schema.org/draft/2020-12/schema",
   "$id": "https://adiaui.dev/a2ui/v0_9/components/Check.json",
   "title": "Check",
-  "description": "Checkbox. The host IS the control.",
+  "description": "Checkbox primitive — the host IS the control (per ADR-0025, no\nnative <input> wrapped underneath). Form-bearing via UIFormElement:\n[name], [value], [checked] (reflect), [indeterminate], [required],\n[disabled]. Wrap in <field-ui label=\"…\" hint=\"…\"> for the canonical\nlabeled stack, or set inline [label] / [hint] props. Distinct from\n<switch-ui> (binary on/off toggle) — use check-ui for opt-in lists\nand form acknowledgements, switch-ui for setting-style toggles.\n",
   "type": "object",
   "allOf": [
     {
@@ -88,7 +88,11 @@
       "check"
     ],
     "name": "UICheck",
-    "related": [],
+    "related": [
+      "Switch",
+      "Radio",
+      "Field"
+    ],
     "slots": {
       "box": {
         "description": "Visual checkbox indicator"
@@ -111,7 +115,13 @@
         "name": "disabled"
       }
     ],
-    "synonyms": {},
+    "synonyms": {
+      "checkbox": [
+        "check",
+        "tickbox",
+        "boolean-input"
+      ]
+    },
     "tag": "check-ui",
     "tokens": {
       "--check-box-background": {

package/components/check/check.yaml

@@ -6,7 +6,14 @@ tag: check-ui
 component: Check
 category: layout
 version: 1
-description: Checkbox. The host IS the control.
+description: |
+  Checkbox primitive — the host IS the control (per ADR-0025, no
+  native <input> wrapped underneath). Form-bearing via UIFormElement:
+  [name], [value], [checked] (reflect), [indeterminate], [required],
+  [disabled]. Wrap in <field-ui label="…" hint="…"> for the canonical
+  labeled stack, or set inline [label] / [hint] props. Distinct from
+  <switch-ui> (binary on/off toggle) — use check-ui for opt-in lists
+  and form acknowledgements, switch-ui for setting-style toggles.
 props:
   name:
     description: Form field name
@@ -78,6 +85,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. Wrapping breaks the consent-row layout (see field-ui anti_patterns)."
+    - rule: 'Three states supported: unchecked (default), checked (via [checked]), and indeterminate (via [indeterminate]); form-associated.'
+      reason: 'Per ADR-0025 — host IS the control, no wrapped <input>.'
+    - rule: 'For binary on/off toggles where visual switch metaphor matters, use <switch-ui> instead; check-ui is for multi-select sets and form-acceptance gates.'
+      reason: 'Decision rule vs switch sibling.'
 anti_patterns:
   - description: Wrapping a check-ui in field-ui. The widget already self-labels.
     wrong: |
@@ -114,5 +125,9 @@ examples:
       ]
 keywords:
   - check
-synonyms: {}
-related: []
+synonyms:
+  checkbox: [check, tickbox, boolean-input]
+related:
+  - Switch
+  - Radio
+  - Field

package/components/code/code.a2ui.json

@@ -2,7 +2,7 @@
   "$schema": "https://json-schema.org/draft/2020-12/schema",
   "$id": "https://adiaui.dev/a2ui/v0_9/components/Code.json",
   "title": "Code",
-  "description": "Inline or block code display with optional language label and copy button.",
+  "description": "Inline or block code display with optional language label and copy button. Renders preformatted text with monospace font and code-block tokens; syntax highlighting is opt-in via the language attribute. Use for code snippets in documentation, chat, or artifact panes; for editable code use <richtext-ui> with a code variant.",
   "type": "object",
   "allOf": [
     {

package/components/code/code.yaml

@@ -6,7 +6,12 @@ tag: code-ui
 component: Code
 category: display
 version: 1
-description: Inline or block code display with optional language label and copy button.
+description: >-
+  Inline or block code display with optional language label and copy
+  button. Renders preformatted text with monospace font and code-block
+  tokens; syntax highlighting is opt-in via the language attribute. Use
+  for code snippets in documentation, chat, or artifact panes; for
+  editable code use <richtext-ui> with a code variant.
 props:
   inline:
     description: Inline code (vs block)
@@ -112,7 +117,13 @@ states:
 traits: []
 tokens: {}
 a2ui:
-  rules: []
+  rules:
+    - rule: 'Inline (default) for short tokens in prose; block variant (display=''block'') for multi-line snippets.'
+      reason: 'Tag is the same; CSS variant switches between inline-flow and block context.'
+    - rule: 'Do not use for editable code — use <richtext-ui> with code variant or a dedicated editor primitive.'
+      reason: 'Code-ui is read-only display only.'
+    - rule: 'Inside <agent-artifact-ui> blocks for agent-emitted code snippets; lang= sets syntax-highlighting hint.'
+      reason: 'Canonical artifact-pane code rendering.'
 anti_patterns: []
 examples:
   - name: code-block

package/components/col/class.js

@@ -18,6 +18,7 @@
  */
 
 import { UIElement } from '../../core/element.js';
+import { parseResponsive, breakpoint } from '../../core/responsive.js';
 
 export class UICol extends UIElement {
   static properties = {
@@ -27,4 +28,42 @@ export class UICol extends UIElement {
     grow:    { type: Boolean, default: false,    reflect: true },
   };
   static template = () => null;
+
+  render() {
+    const gap     = this.gap;
+    const align   = this.align;
+    const justify = this.justify;
+    // Only subscribe to breakpoint when at least one prop uses @bp notation.
+    const anyR    = gap?.includes('@') || align?.includes('@') || justify?.includes('@');
+    const bp      = anyR ? breakpoint.value : '';
+
+    if (gap?.includes('@')) {
+      this.style.setProperty('--col-gap', _gapToCss(parseResponsive(gap, bp)));
+    } else {
+      this.style.removeProperty('--col-gap');
+    }
+
+    if (align?.includes('@')) {
+      const v = parseResponsive(align, bp);
+      this.style.setProperty('--col-align', _flexAlign(v));
+      this.style.textAlign = _textAlign(v);
+    } else {
+      this.style.removeProperty('--col-align');
+      this.style.textAlign = '';
+    }
+
+    if (justify?.includes('@')) {
+      this.style.setProperty('--col-justify', _flexJustify(parseResponsive(justify, bp)));
+    } else {
+      this.style.removeProperty('--col-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 _textAlign(v)    { return { start: 'start', center: 'center', end: 'end' }[v] ?? ''; }
+function _flexJustify(v)  { return _JUSTIFY[v] ?? v; }

package/components/col/col.a2ui.json

@@ -2,7 +2,7 @@
   "$schema": "https://json-schema.org/draft/2020-12/schema",
   "$id": "https://adiaui.dev/a2ui/v0_9/components/Col.json",
   "title": "Col",
-  "description": "Flex column layout primitive.",
+  "description": "Flex column layout primitive — vertical stack of children with\n[gap] / [align] / [justify] / [grow]. The most common layout\nprimitive in the repo. Use <col-ui> for vertical stacks, <row-ui>\nfor horizontal rows, <stack-ui> for overlay (children stack on top\nof each other in a grid), <grid-ui> for 2D grids. Composes inside\n<section-ui> for in-card layout; do NOT use as a child of\n<header-ui> / <footer-ui> (the chrome scope already lays out\nslots).\n",
   "type": "object",
   "allOf": [
     {
@@ -14,7 +14,7 @@
   ],
   "properties": {
     "align": {
-      "description": "Align items",
+      "description": "Cross-axis alignment (start/center/end/stretch). Accepts `@bp` notation: align=\"stretch center@sm\" applies stretch below sm, center from sm up.",
       "type": "string",
       "default": "stretch"
     },
@@ -22,7 +22,7 @@
       "const": "Col"
     },
     "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\", mapped to --a-space-N).",
+      "description": "Gap between children. Named scale (xs/sm/md/lg/xl) or numeric spacing rung (\"1\"…\"16\", mapped to --a-space-N). Accepts `@bp` notation: gap=\"2 4@md\" = 2 below md, 4 from md upward.",
       "type": "string",
       "default": "md"
     },
@@ -32,7 +32,7 @@
       "default": false
     },
     "justify": {
-      "description": "Justify content",
+      "description": "Main-axis justify (start/center/end/space-between/space-around). Accepts `@bp` notation: justify=\"start space-between@md\".",
       "type": "string",
       "default": "start"
     }
@@ -81,7 +81,14 @@
         "name": "idle"
       }
     ],
-    "synonyms": {},
+    "synonyms": {
+      "column": [
+        "col",
+        "vstack",
+        "vertical-stack",
+        "vbox"
+      ]
+    },
     "tag": "col-ui",
     "tokens": {},
     "traits": [],

package/components/col/col.d.ts

@@ -1,5 +1,13 @@
 /**
- * `<col-ui>` — Flex column layout primitive.
+ * `<col-ui>` — Flex column layout primitive — vertical stack of children with
+[gap] / [align] / [justify] / [grow]. The most common layout
+primitive in the repo. Use <col-ui> for vertical stacks, <row-ui>
+for horizontal rows, <stack-ui> for overlay (children stack on top
+of each other in a grid), <grid-ui> for 2D grids. Composes inside
+<section-ui> for in-card layout; do NOT use as a child of
+<header-ui> / <footer-ui> (the chrome scope already lays out
+slots).
+
  *
  * @see https://ui-kit.exe.xyz/site/components/col
  *
@@ -13,12 +21,12 @@
 import { UIElement } from '../../core/element.js';
 
 export class UICol extends UIElement {
-  /** Align items */
+  /** Cross-axis alignment (start/center/end/stretch). Accepts `@bp` notation: align="stretch center@sm" applies stretch below sm, center from sm up. */
   align: string;
-  /** Gap between children. Accepts either the named scale (xs/sm/md/lg/xl) or a numeric rung on the spacing scale ("1"…"16", mapped to --a-space-N). */
+  /** Gap between children. Named scale (xs/sm/md/lg/xl) or numeric spacing rung ("1"…"16", mapped to --a-space-N). Accepts `@bp` notation: gap="2 4@md" = 2 below md, 4 from md upward. */
   gap: string;
   /** Fills remaining space in a flex parent (e.g. inside a Row). CSS-only attribute via :scope[grow] in col.css. */
   grow: boolean;
-  /** Justify content */
+  /** Main-axis justify (start/center/end/space-between/space-around). Accepts `@bp` notation: justify="start space-between@md". */
   justify: string;
 }

package/components/col/col.yaml

@@ -6,16 +6,27 @@ tag: col-ui
 component: Col
 category: layout
 version: 1
-description: Flex column layout primitive.
+description: |
+  Flex column layout primitive — vertical stack of children with
+  [gap] / [align] / [justify] / [grow]. The most common layout
+  primitive in the repo. Use <col-ui> for vertical stacks, <row-ui>
+  for horizontal rows, <stack-ui> for overlay (children stack on top
+  of each other in a grid), <grid-ui> for 2D grids. Composes inside
+  <section-ui> for in-card layout; do NOT use as a child of
+  <header-ui> / <footer-ui> (the chrome scope already lays out
+  slots).
 props:
   align:
-    description: Align items
+    description: >-
+      Cross-axis alignment (start/center/end/stretch). Accepts `@bp` notation:
+      align="stretch center@sm" applies stretch below sm, center from sm up.
     type: string
     default: stretch
   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", mapped to --a-space-N).
+      Gap between children. Named scale (xs/sm/md/lg/xl) or numeric spacing
+      rung ("1"…"16", mapped to --a-space-N). Accepts `@bp` notation:
+      gap="2 4@md" = 2 below md, 4 from md upward.
     type: string
     default: md
   grow:
@@ -24,7 +35,9 @@ props:
     default: false
     reflect: true
   justify:
-    description: Justify content
+    description: >-
+      Main-axis justify (start/center/end/space-between/space-around).
+      Accepts `@bp` notation: justify="start space-between@md".
     type: string
     default: start
 events: {}
@@ -37,7 +50,13 @@ states:
 traits: []
 tokens: {}
 a2ui:
-  rules: []
+  rules:
+    - rule: 'Vertical-stack flex container. Children flow top-to-bottom with token-driven gap.'
+      reason: 'Canonical vertical layout.'
+    - rule: 'Pair with <row-ui> for horizontal layouts; both share the same gap-token contract.'
+      reason: 'Layout symmetry.'
+    - rule: 'Set align/justify attributes for cross-axis / main-axis alignment; default is start/start.'
+      reason: 'Standard flex knobs.'
 anti_patterns: []
 examples:
   - name: chat-interface
@@ -340,7 +359,8 @@ examples:
 keywords:
   - column
   - col
-synonyms: {}
+synonyms:
+  column: [col, vstack, vertical-stack, vbox]
 related:
   - avatar
   - input