@adia-ai/web-components 0.6.21 → 0.6.23

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

@@ -68,16 +68,34 @@
       }
     },
     "examples": [],
-    "keywords": [],
+    "keywords": [
+      "feed-item",
+      "notification",
+      "toast-row",
+      "alert-row",
+      "feed-entry",
+      "notification-card"
+    ],
     "name": "UIFeedItem",
-    "related": [],
+    "related": [
+      "Feed",
+      "Toast",
+      "Alert"
+    ],
     "slots": {
       "body": {
         "description": "Default content slot (also accepts the `text` / `heading` props)"
       }
     },
     "states": {},
-    "synonyms": {},
+    "synonyms": {
+      "feed-item": [
+        "notification-row",
+        "toast-entry",
+        "feed-row",
+        "alert-item"
+      ]
+    },
     "tag": "feed-item-ui",
     "tokens": {},
     "traits": [],

package/components/feed/feed-item.yaml

@@ -48,3 +48,28 @@ slots:
   body:
     description: Default content slot (also accepts the `text` / `heading` props)
 states: {}
+
+keywords:
+  - feed-item
+  - notification
+  - toast-row
+  - alert-row
+  - feed-entry
+  - notification-card
+
+synonyms:
+  feed-item: [notification-row, toast-entry, feed-row, alert-item]
+
+related:
+  - Feed
+  - Toast
+  - Alert
+
+a2ui:
+  rules:
+    - rule: 'One notification entry inside <feed-ui>. Title + description + optional icon + auto-dismiss timer.'
+      reason: 'Feed-channel item primitive.'
+    - rule: 'Typically created programmatically via UIFeed.post(...); do not place declaratively.'
+      reason: 'Imperative ownership.'
+    - rule: 'Different from <alert-ui> (inline persistent) and <toast-ui> (standalone ephemeral); feed-item is feed-scoped.'
+      reason: 'Surface boundary.'

package/components/feed/feed.a2ui.json

@@ -53,12 +53,32 @@
       }
     },
     "examples": [],
-    "keywords": [],
+    "keywords": [
+      "feed",
+      "notification-feed",
+      "activity-stream",
+      "toast-stack",
+      "alert-stack",
+      "snackbar-stack",
+      "notification-channel"
+    ],
     "name": "UIFeedContainer",
-    "related": [],
+    "related": [
+      "FeedItem",
+      "Toast",
+      "Alert"
+    ],
     "slots": {},
     "states": {},
-    "synonyms": {},
+    "synonyms": {
+      "feed": [
+        "notification-feed",
+        "toast-feed",
+        "alert-feed",
+        "activity-feed",
+        "snackbar-stack"
+      ]
+    },
     "tag": "feed-ui",
     "tokens": {},
     "traits": [],

package/components/feed/feed.yaml

@@ -38,3 +38,29 @@ events:
     description: Fired on per-item dismissal (manual close, swipe, or auto-timeout). Bubbles.
 slots: {}
 states: {}
+
+keywords:
+  - feed
+  - notification-feed
+  - activity-stream
+  - toast-stack
+  - alert-stack
+  - snackbar-stack
+  - notification-channel
+
+synonyms:
+  feed: [notification-feed, toast-feed, alert-feed, activity-feed, snackbar-stack]
+
+related:
+  - FeedItem
+  - Toast
+  - Alert
+
+a2ui:
+  rules:
+    - rule: 'Top-layer notification feed channel — singleton per position (top-right, bottom-center, etc.) mounted lazily into document.body.'
+      reason: 'Per docs/specs/feed-channel.md.'
+    - rule: 'Hosts <feed-item-ui> children programmatically via static API (UIFeed.post(...)). Do not place feed-items declaratively.'
+      reason: 'Imperative API ownership.'
+    - rule: 'For inline persistent alerts inside content regions use <alert-ui> instead; feed is ephemeral overlay.'
+      reason: 'Surface boundary.'

package/components/fields/fields.yaml

@@ -54,7 +54,13 @@ tokens:
   --fields-column-gap:
     description: Override the column-gap independently of row-gap.
 a2ui:
-  rules: []
+  rules:
+    - rule: 'Container for form rows. Hosts <field-ui> children (or <row-ui>/<col-ui> with labeled inputs) with consistent label + control + help layout.'
+      reason: 'Form-row layout primitive.'
+    - rule: 'Different from <description-list-ui> (read-only key:value display) — fields-ui is for editable inputs.'
+      reason: 'Read vs write distinction.'
+    - rule: 'For dynamic field arrays (repeat-able rows) compose fields-ui with manual add/remove controls.'
+      reason: 'No built-in repeat affordance.'
 anti_patterns:
   - description: >-
       Don't wrap <field-ui> children in <row-ui wrap> when grid

package/components/footer/footer.a2ui.json

@@ -71,7 +71,13 @@
         "name": "idle"
       }
     ],
-    "synonyms": {},
+    "synonyms": {
+      "footer": [
+        "footer-bar",
+        "footer-row",
+        "bottom-bar"
+      ]
+    },
     "tag": "footer-ui",
     "tokens": {},
     "traits": [],

package/components/footer/footer.yaml

@@ -27,7 +27,31 @@ states:
 traits: []
 tokens: {}
 a2ui:
-  rules: []
+  rules:
+    - >-
+      Use <footer-ui> as the bottom chrome row inside a PRIMITIVE
+      container parent (<card-ui>, <drawer-ui>, <modal-ui>, <page-ui>).
+      Typically holds 1–3 <button-ui> children — the most common pattern
+      is a Cancel / Confirm pair inside <modal-ui> or <drawer-ui>.
+    - >-
+      Use `justify="end"` (default) for Cancel+Confirm and trailing
+      action clusters; `justify="between"` when one action lives left
+      and one right (e.g. Back / Submit); `justify="center"` for
+      single-button confirm flows; `justify="start"` for solo leading
+      actions like Back.
+    - >-
+      Do NOT substitute <footer-ui> for bespoke shell-tier bottom
+      chrome. Inside <admin-sidebar slot="footer"> use <admin-statusbar>;
+      inside <editor-shell> use <editor-statusbar>. <footer-ui> is
+      exclusively the in-container action bar at the primitive tier.
+    - >-
+      Do NOT wrap children in <row-ui> just to align them — the
+      `justify` prop already lays children out horizontally. A nested
+      row-ui double-applies layout and breaks the chrome's gap tokens.
+    - >-
+      Prefer flat <button-ui> children. If you need non-button content
+      (text summary, pagination indicator), keep it as a single flat
+      child so `justify` resolves cleanly.
 anti_patterns: []
 examples:
   - name: chat-interface
@@ -230,7 +254,8 @@ examples:
       ]
 keywords:
   - footer
-synonyms: {}
+synonyms:
+  footer: [footer-bar, footer-row, bottom-bar]
 related:
   - avatar
   - input

package/components/grid/class.js

@@ -19,6 +19,7 @@
  */
 
 import { UIElement } from '../../core/element.js';
+import { parseResponsive, breakpoint } from '../../core/responsive.js';
 
 export class UIGrid extends UIElement {
   static properties = {
@@ -28,4 +29,60 @@ export class UIGrid extends UIElement {
     rowGap:    { type: String, default: '',   reflect: true, attribute: 'row-gap' },
   };
   static template = () => null;
+
+  render() {
+    // Reading breakpoint.value inside render() subscribes this component to
+    // the signal — UIElement re-runs render() whenever the viewport crosses
+    // a breakpoint boundary (and also on prop changes as normal).
+    const bp = breakpoint.value;
+
+    // ── columns ──────────────────────────────────────────────────────────────
+    // Responsive value: JS resolves + writes inline gridTemplateColumns.
+    // Also forces gridAutoFlow:row + gridAutoColumns:auto, overriding the
+    // default CSS which has grid-auto-flow:column (single-row spread) — that
+    // default only makes sense when NO explicit template is set.
+    // Scalar value: clear inline styles, CSS [columns="N"] rules take over.
+    const cols = this.columns;
+    if (cols?.includes('@')) {
+      const resolved = parseResponsive(cols, bp);
+      this.style.gridTemplateColumns = this.#colsToTemplate(resolved);
+      this.style.gridAutoFlow        = resolved ? 'row'  : '';
+      this.style.gridAutoColumns     = resolved ? 'auto' : '';
+    } else {
+      this.style.gridTemplateColumns = '';
+      this.style.gridAutoFlow        = '';
+      this.style.gridAutoColumns     = '';
+    }
+
+    // ── gap ───────────────────────────────────────────────────────────────────
+    // Same pattern: responsive values set inline column/row-gap directly;
+    // scalar values clear those and let the universal [gap="N"] token rules
+    // in tokens.css handle everything via --a-gap.
+    const gap = this.gap;
+    if (gap?.includes('@')) {
+      const v   = parseResponsive(gap, bp);
+      const css = this.#gapToCss(v);
+      this.style.columnGap = css;
+      this.style.rowGap    = css;
+    } else {
+      this.style.columnGap = '';
+      this.style.rowGap    = '';
+    }
+  }
+
+  /** Map a resolved columns value to a CSS grid-template-columns string. */
+  #colsToTemplate(v) {
+    if (!v) return '';
+    if (/^\d+$/.test(v)) return `repeat(${v}, 1fr)`;
+    if (v === 'auto-fill') return 'repeat(auto-fill, minmax(12rem, 1fr))';
+    if (v === 'auto-fit')  return 'repeat(auto-fit,  minmax(12rem, 1fr))';
+    return v; // passthrough for custom template expressions
+  }
+
+  /** Map a resolved gap value to a CSS length / custom-property reference. */
+  #gapToCss(v) {
+    if (!v || v === '0') return '0';
+    if (/^\d+$/.test(v)) return `var(--a-space-${v})`;
+    return `var(--a-gap-${v})`;
+  }
 }

package/components/grid/grid.a2ui.json

@@ -2,7 +2,7 @@
   "$schema": "https://json-schema.org/draft/2020-12/schema",
   "$id": "https://adiaui.dev/a2ui/v0_9/components/Grid.json",
   "title": "Grid",
-  "description": "CSS grid layout primitive. Supports [columns=\"1..6\"] for equal columns, [columns=\"auto-fill\"|\"auto-fit\"] for responsive density, and a per-child [span=\"2..6\"|\"full\"] attribute for asymmetric layouts. Compose a 2:1 split as columns=\"3\" + the wide child span=\"2\"; compose a 3:2 split as columns=\"5\" + span=\"3\" + span=\"2\". Never set grid-template-columns via inline style — use the span attribute on children instead.",
+  "description": "CSS grid layout primitive. Supports [columns=\"1..6\"] for equal columns, [columns=\"auto-fill\"|\"auto-fit\"] for responsive density, and a per-child [span=\"2..6\"|\"full\"] attribute for asymmetric layouts. Both [columns] and [gap] accept responsive `@bp` notation for viewport-driven layout: columns=\"1 2@sm 4@lg\" gives 1 column on xs, 2 from sm, 4 from lg/xl. Compose a 2:1 split as columns=\"3\" + span=\"2\"; 3:2 as columns=\"5\" + span=\"3\" + span=\"2\".",
   "type": "object",
   "allOf": [
     {
@@ -19,7 +19,7 @@
       "default": ""
     },
     "columns": {
-      "description": "Number of columns or grid-template-columns",
+      "description": "Number of equal columns (1–6), \"auto-fill\", or \"auto-fit\". Accepts responsive `@bp` notation: \"1 2@sm 4@lg\" = 1 on xs, 2 from sm, 4 from lg/xl. Unannotated value is the mobile-first base.",
       "type": "string",
       "default": "3"
     },
@@ -27,7 +27,7 @@
       "const": "Grid"
     },
     "gap": {
-      "description": "Grid gap",
+      "description": "Grid gap. Accepts numeric space-scale values (0–12) or named sizes (xs/sm/md/lg/xl). Responsive notation supported: \"2 4@md\" = 2 below md, 4 from md upward.",
       "type": "string",
       "default": "md"
     },

package/components/grid/grid.d.ts

@@ -1,5 +1,5 @@
 /**
- * `<grid-ui>` — CSS grid layout primitive. Supports [columns="1..6"] for equal columns, [columns="auto-fill"|"auto-fit"] for responsive density, and a per-child [span="2..6"|"full"] attribute for asymmetric layouts. Compose a 2:1 split as columns="3" + the wide child span="2"; compose a 3:2 split as columns="5" + span="3" + span="2". Never set grid-template-columns via inline style — use the span attribute on children instead.
+ * `<grid-ui>` — CSS grid layout primitive. Supports [columns="1..6"] for equal columns, [columns="auto-fill"|"auto-fit"] for responsive density, and a per-child [span="2..6"|"full"] attribute for asymmetric layouts. Both [columns] and [gap] accept responsive `@bp` notation for viewport-driven layout: columns="1 2@sm 4@lg" gives 1 column on xs, 2 from sm, 4 from lg/xl. Compose a 2:1 split as columns="3" + span="2"; 3:2 as columns="5" + span="3" + span="2".
  *
  * @see https://ui-kit.exe.xyz/site/components/grid
  *
@@ -15,9 +15,9 @@ import { UIElement } from '../../core/element.js';
 export class UIGrid extends UIElement {
   /** Column gap override */
   columnGap: string;
-  /** Number of columns or grid-template-columns */
+  /** Number of equal columns (1–6), "auto-fill", or "auto-fit". Accepts responsive `@bp` notation: "1 2@sm 4@lg" = 1 on xs, 2 from sm, 4 from lg/xl. Unannotated value is the mobile-first base. */
   columns: string;
-  /** Grid gap */
+  /** Grid gap. Accepts numeric space-scale values (0–12) or named sizes (xs/sm/md/lg/xl). Responsive notation supported: "2 4@md" = 2 below md, 4 from md upward. */
   gap: string;
   /** Row gap override */
   rowGap: string;

package/components/grid/grid.yaml

@@ -9,10 +9,11 @@ version: 1
 description: >-
   CSS grid layout primitive. Supports [columns="1..6"] for equal columns,
   [columns="auto-fill"|"auto-fit"] for responsive density, and a per-child
-  [span="2..6"|"full"] attribute for asymmetric layouts. Compose a 2:1 split as
-  columns="3" + the wide child span="2"; compose a 3:2 split as columns="5" +
-  span="3" + span="2". Never set grid-template-columns via inline style — use the
-  span attribute on children instead.
+  [span="2..6"|"full"] attribute for asymmetric layouts. Both [columns] and
+  [gap] accept responsive `@bp` notation for viewport-driven layout:
+  columns="1 2@sm 4@lg" gives 1 column on xs, 2 from sm, 4 from lg/xl.
+  Compose a 2:1 split as columns="3" + span="2"; 3:2 as columns="5" +
+  span="3" + span="2".
 props:
   columnGap:
     description: Column gap override
@@ -20,11 +21,17 @@ props:
     default: ""
     attribute: column-gap
   columns:
-    description: Number of columns or grid-template-columns
+    description: >-
+      Number of equal columns (1–6), "auto-fill", or "auto-fit". Accepts
+      responsive `@bp` notation: "1 2@sm 4@lg" = 1 on xs, 2 from sm, 4
+      from lg/xl. Unannotated value is the mobile-first base.
     type: string
     default: "3"
   gap:
-    description: Grid gap
+    description: >-
+      Grid gap. Accepts numeric space-scale values (0–12) or named sizes
+      (xs/sm/md/lg/xl). Responsive notation supported: "2 4@md" = 2 below
+      md, 4 from md upward.
     type: string
     default: md
   rowGap:
@@ -45,8 +52,9 @@ a2ui:
   rules:
     - >-
       For asymmetric column ratios, use [columns="N"] plus [span="M"] on the child
-      that should be wider. Never set grid-template-columns via style — it bypasses
-      the component API and reads as a local hack.
+      that should be wider. Never set gridTemplateColumns via inline style in
+      compositions — the component's responsive resolver sets it internally for
+      @bp values; direct inline style bypasses that and reads as a local hack.
     - >-
       Canonical ratios: 1:1 → columns="2"; 2:1 → columns="3" + span="2";
       3:1 → columns="4" + span="3"; 3:2 → columns="5" + span="3"+"2";
@@ -55,6 +63,12 @@ a2ui:
       The default (no columns attribute) gives equal auto-columns flowing in a
       single row. Prefer the explicit numeric attribute for dashboard rows so the
       layout is predictable when items wrap.
+    - >-
+      For viewport-responsive layouts use `@bp` notation on [columns] and [gap]:
+      columns="1 2@sm 4@lg" gives 1 column on xs, 2 from sm, 4 from lg/xl.
+      Breakpoints (mobile-first, min-width): xs=0, sm=480, md=768, lg=1024,
+      xl=1280. Unannotated value = base (smallest). Each @bp overrides upward
+      until the next larger annotation takes over.
 anti_patterns: []
 examples:
   - name: chart-dashboard

package/components/header/header.a2ui.json

@@ -68,7 +68,14 @@
         "name": "idle"
       }
     ],
-    "synonyms": {},
+    "synonyms": {
+      "header": [
+        "header-bar",
+        "header-row",
+        "top-bar",
+        "chrome-top"
+      ]
+    },
     "tag": "header-ui",
     "tokens": {},
     "traits": [],

package/components/header/header.yaml

@@ -25,7 +25,34 @@ states:
 traits: []
 tokens: {}
 a2ui:
-  rules: []
+  rules:
+    - >-
+      Use <header-ui> as the top chrome row inside a PRIMITIVE container
+      parent: <card-ui>, <drawer-ui>, <modal-ui>, <page-ui>. It is a
+      CSS-only slot stub — no JS, no events. The parent's @scope rules
+      drive layout and styling.
+    - >-
+      Compose with the default slot for the heading (typically
+      <text-ui variant="title">) and slot="action" for trailing controls
+      (button-ui, badge-ui). The slot vocabulary (icon / heading /
+      description / action) is shared with <aside-ui> / <section-ui> /
+      <footer-ui> per ADR-0009.
+    - >-
+      Do NOT substitute <header-ui> for bespoke shell-tier chrome.
+      Inside <admin-content> / <admin-sidebar> use <admin-topbar>;
+      inside <chat-shell> use <chat-header>; inside <editor-shell> use
+      <editor-toolbar>. Those modules carry shell-specific slot
+      vocabulary and CSS that <header-ui> does not. (admin-topbar.yaml
+      codifies this explicitly.)
+    - >-
+      Do NOT wrap header-ui's children in <col-ui> or <row-ui>. The
+      container parent's @scope already lays out
+      default+icon+heading+description+action via slot vocabulary; extra
+      layout primitives fight the chrome styling.
+    - >-
+      The `padding` attribute is a bare boolean — it enables default
+      header padding, but the *scale* is set by the container parent's
+      own `padding` prop. Do not pass numeric values.
 anti_patterns: []
 examples:
   - name: chat-interface
@@ -327,7 +354,8 @@ examples:
       ]
 keywords:
   - header
-synonyms: {}
+synonyms:
+  header: [header-bar, header-row, top-bar, chrome-top]
 related:
   - avatar
   - input

package/components/heatmap/heatmap.yaml

@@ -89,7 +89,13 @@ states:
 traits: []
 tokens: {}
 a2ui:
-  rules: []
+  rules:
+    - rule: 'Grid-cell heatmap visualization (calendar heatmap, density grid). Cells colored by value via OKLCH scale.'
+      reason: 'Data-density visualization.'
+    - rule: 'For continuous time-series use <chart-ui> with appropriate variant; heatmap is for grid-cell density.'
+      reason: 'Chart vs heatmap boundary.'
+    - rule: 'Tooltip on hover shows cell value; click events emit cell coordinates.'
+      reason: 'Interaction contract.'
 anti_patterns: []
 examples:
   - name: basic-heatmap

package/components/icon/icon.a2ui.json

@@ -2,7 +2,7 @@
   "$schema": "https://json-schema.org/draft/2020-12/schema",
   "$id": "https://adiaui.dev/a2ui/v0_9/components/Icon.json",
   "title": "Icon",
-  "description": "SVG icon from the icon registry. Renders inline SVG from getIcon().",
+  "description": "SVG icon from the icon registry. Renders inline SVG from getIcon() lookups with size + color token support; the canonical icon primitive throughout AdiaUI. Use for all icon needs; do not embed raw SVG or image-based icons in composed components.",
   "type": "object",
   "allOf": [
     {
@@ -84,7 +84,14 @@
         "name": "idle"
       }
     ],
-    "synonyms": {},
+    "synonyms": {
+      "icon": [
+        "glyph",
+        "phosphor-icon",
+        "ui-icon",
+        "symbol"
+      ]
+    },
     "tag": "icon-ui",
     "tokens": {},
     "traits": [],

package/components/icon/icon.d.ts

@@ -1,5 +1,5 @@
 /**
- * `<icon-ui>` — SVG icon from the icon registry. Renders inline SVG from getIcon().
+ * `<icon-ui>` — SVG icon from the icon registry. Renders inline SVG from getIcon() lookups with size + color token support; the canonical icon primitive throughout AdiaUI. Use for all icon needs; do not embed raw SVG or image-based icons in composed components.
  *
  * @see https://ui-kit.exe.xyz/site/components/icon
  *

package/components/icon/icon.yaml

@@ -6,7 +6,11 @@ tag: icon-ui
 component: Icon
 category: display
 version: 1
-description: SVG icon from the icon registry. Renders inline SVG from getIcon().
+description: >-
+  SVG icon from the icon registry. Renders inline SVG from getIcon()
+  lookups with size + color token support; the canonical icon primitive
+  throughout AdiaUI. Use for all icon needs; do not embed raw SVG or
+  image-based icons in composed components.
 props:
   name:
     description: Icon name from registry
@@ -40,7 +44,31 @@ states:
 traits: []
 tokens: {}
 a2ui:
-  rules: []
+  rules:
+    - >-
+      [name] must be a registered Phosphor key (e.g. "house", "gear",
+      "trash", "warning-circle"). Free-form names render empty. When
+      unsure, default to a semantically obvious glyph (check, x,
+      warning-circle, info).
+    - >-
+      Set [label] when the icon is the ONLY content of an interactive
+      control (icon-only button); omit [label] when icon is decorative
+      beside a text label. The host stamps role="img" + aria-label
+      when [label] is set.
+    - >-
+      Use named [size] tokens (sm | md | lg | xl) — px / rem values
+      only when matching a strict design spec. [size="xl"] is
+      conventional for empty-state hero icons; [size="md"] is the
+      default for inline use.
+    - >-
+      Use slot="icon" on parent primitives (<button-ui>, <badge-ui>,
+      <alert-ui>, <list-item-ui>, <input-ui>, <nav-item-ui>, every
+      chrome bar) — do NOT bare-render <icon-ui> beside text in a
+      <row-ui> when the parent supports the [slot="icon"] convention.
+    - >-
+      Use [weight="fill"] for selected / active toggles,
+      [weight="regular"] (default) for inactive. Do not mix weights
+      in the same set; the visual inconsistency reads as a bug.
 anti_patterns: []
 examples:
   - name: command-palette
@@ -234,7 +262,8 @@ examples:
       ]
 keywords:
   - icon
-synonyms: {}
+synonyms:
+  icon: [glyph, phosphor-icon, ui-icon, symbol]
 related:
   - input
   - empty-state

package/components/image/image.yaml

@@ -70,7 +70,13 @@ states:
 traits: []
 tokens: {}
 a2ui:
-  rules: []
+  rules:
+    - rule: 'Use for content images (illustrations, screenshots, user-uploaded photos). For icons use <icon-ui>; for embedded artifacts use <embed-ui>.'
+      reason: 'Icon is registry-driven; embed is iframe-style; image is plain src.'
+    - rule: 'Set aspect-ratio attribute to lock dimensions and prevent layout shift during load.'
+      reason: 'CLS prevention; canonical perf knob.'
+    - rule: 'For decorative-only images, set alt='''' and aria-hidden=''true'' so screen readers skip them.'
+      reason: 'Accessibility — decorative vs informative distinction.'
 anti_patterns: []
 examples:
   - name: bleed-design-settings

package/components/input/input.yaml

@@ -236,7 +236,35 @@ tokens:
   --input-transition:
     description: Override transition timing
 a2ui:
-  rules: []
+  rules:
+    - >-
+      <input-ui> is the canonical single-line text input. The host IS
+      the contenteditable surface — NEVER wrap a native <input>. The
+      sole exception is type="password", which internally uses a real
+      <input type="password"> for masking (per ADR-0025).
+    - >-
+      Wrap <input-ui> in <field-ui label="…" hint="…" error="…"> for
+      the canonical stacked label / hint / error chrome. The inline
+      [label] / [hint] / [error] props are also supported on the
+      primitive for compact use.
+    - >-
+      Form participation is implicit via UIFormElement. Set [name] for
+      FormData submission; [required] / [disabled] / [readonly]
+      reflect; listen for `change` (blur or Enter commit) and `input`
+      (per keystroke). `submit` event fires when Enter commits the
+      value (used by <chat-composer>'s `composer-submit` forwarding).
+    - >-
+      For numeric input use [type="number"] with [min] [max] [step]
+      [precision] [prefix] / [suffix] — this stamps a contenteditable
+      surface + <button-ui> / <icon-ui> stepper column with ARIA
+      spinbutton semantics. Read `el.valueAsNumber` for the parsed
+      Number. Never substitute a native <input type="number">.
+    - >-
+      Inside <chat-composer>, the canonical inner input is
+      <chat-input-ui submit-on-enter> (chat variant subclass — owns
+      the submit-on-enter contract explicitly). The plain <input-ui>
+      primitive already fires `submit` on Enter, but only chat-input-ui
+      reflects the [submit-on-enter] attribute.
 anti_patterns: []
 examples:
 - name: quantity-stepper

package/components/inspector/inspector.a2ui.json

@@ -2,7 +2,7 @@
   "$schema": "https://json-schema.org/draft/2020-12/schema",
   "$id": "https://adiaui.dev/a2ui/v0_9/components/Inspector.json",
   "title": "Inspector",
-  "description": "Developer tools pane for inspecting A2UI state.",
+  "description": "Developer-tools pane for inspecting A2UI runtime state — composes\n<tabs-ui> + <code-ui> to show the live document JSON, rendered\nHTML, and event log for the bound <canvas-ui> / <a2ui-root>. The\nright-pane inspector of the a2ui-editor app. Use inside an\n<editor-sidebar slot=\"trailing\"> for debugging A2UI playgrounds;\nnot for end-user inspector panes (build those bespoke with\n<field-ui> + form rows per the editor-inspector-pane recipe in\npatterns-recipes.md).\n",
   "type": "object",
   "allOf": [
     {
@@ -46,7 +46,12 @@
       "inspector"
     ],
     "name": "UIInspector",
-    "related": [],
+    "related": [
+      "A2uiRoot",
+      "EditorSidebar",
+      "Code",
+      "Tabs"
+    ],
     "slots": {
       "default": {
         "description": "Default slot — primary child content."

package/components/inspector/inspector.d.ts

@@ -1,5 +1,13 @@
 /**
- * `<inspector-ui>` — Developer tools pane for inspecting A2UI state.
+ * `<inspector-ui>` — Developer-tools pane for inspecting A2UI runtime state — composes
+<tabs-ui> + <code-ui> to show the live document JSON, rendered
+HTML, and event log for the bound <canvas-ui> / <a2ui-root>. The
+right-pane inspector of the a2ui-editor app. Use inside an
+<editor-sidebar slot="trailing"> for debugging A2UI playgrounds;
+not for end-user inspector panes (build those bespoke with
+<field-ui> + form rows per the editor-inspector-pane recipe in
+patterns-recipes.md).
+
  *
  * @see https://ui-kit.exe.xyz/site/components/inspector
  *