@adia-ai/web-components 0.6.20 → 0.6.22

package/components/table/cell-types.js

@@ -6,6 +6,19 @@ function registerCellType(name, config) {
   cellTypes[name] = config;
 }
 
+// text-overflow:ellipsis on a flex container doesn't reach text nodes —
+// they become anonymous flex items that the container can't truncate.
+// Wrapping in a <span> gives CSS a real element to target.
+function _t(cell, text) {
+  let s = cell.firstElementChild;
+  if (!s || s.tagName !== 'SPAN') {
+    cell.replaceChildren();
+    s = cell.appendChild(document.createElement('span'));
+  }
+  s.textContent = text;
+  cell.title = text;
+}
+
 // Sort functions
 export const sortFns = {
   basic: (a, b) => (a < b ? -1 : a > b ? 1 : 0),
@@ -22,7 +35,7 @@ export const sortFns = {
 // 1. text (default)
 registerCellType('text', {
   render(value, row, cell) {
-    cell.textContent = value ?? '';
+    _t(cell, String(value ?? ''));
   },
   format(value) {
     return String(value ?? '');
@@ -34,8 +47,7 @@ registerCellType('text', {
 // 2. number
 registerCellType('number', {
   render(value, row, cell) {
-    cell.textContent =
-      value != null ? new Intl.NumberFormat().format(value) : '';
+    _t(cell, value != null ? new Intl.NumberFormat().format(value) : '');
   },
   format(value) {
     return String(value ?? '');
@@ -47,13 +59,13 @@ registerCellType('number', {
 // 3. currency
 registerCellType('currency', {
   render(value, row, cell, meta) {
-    cell.textContent =
+    _t(cell,
       value != null
         ? new Intl.NumberFormat('en-US', {
             style: 'currency',
             currency: meta?.currency || 'USD',
           }).format(value)
-        : '';
+        : '');
   },
   format(value, row, meta) {
     return value != null
@@ -70,7 +82,7 @@ registerCellType('currency', {
 // 4. percent
 registerCellType('percent', {
   render(value, row, cell) {
-    cell.textContent = value != null ? `${value}%` : '';
+    _t(cell, value != null ? `${value}%` : '');
   },
   format(value) {
     return value != null ? `${value}%` : '';
@@ -84,9 +96,9 @@ const dateFmtOpts = { year: 'numeric', month: 'short', day: 'numeric' };
 
 registerCellType('date', {
   render(value, row, cell) {
-    cell.textContent = value
+    _t(cell, value
       ? new Intl.DateTimeFormat('en-US', dateFmtOpts).format(new Date(value))
-      : '';
+      : '');
   },
   format(value) {
     return value
@@ -108,11 +120,11 @@ const datetimeFmtOpts = {
 
 registerCellType('datetime', {
   render(value, row, cell) {
-    cell.textContent = value
+    _t(cell, value
       ? new Intl.DateTimeFormat('en-US', datetimeFmtOpts).format(
           new Date(value)
         )
-      : '';
+      : '');
   },
   format(value) {
     return value
@@ -188,6 +200,7 @@ registerCellType('avatar', {
     const span = wrapper.querySelector('span');
     av.setAttribute('text', String(value ?? ''));
     span.textContent = String(value ?? '');
+    cell.title = String(value ?? '');
   },
   format(value) {
     return String(value ?? '');

package/components/table/class.js

@@ -111,6 +111,7 @@ export class UITable extends UIElement {
     selectable: { type: Boolean, default: false, reflect: true },
     expandable: { type: Boolean, default: false, reflect: true },
     striped:    { type: Boolean, default: false, reflect: true },
+    wrap:       { type: Boolean, default: false, reflect: true },
     raw:        { type: Boolean, default: false, reflect: true },
     density:    { type: String,  default: 'standard', reflect: true },
     paginate:   { type: Number,  default: 0,     reflect: true },
@@ -806,13 +807,17 @@ export class UITable extends UIElement {
           cell.innerHTML = result;
         }
       } else if (typeof col.format === 'function') {
-        cell.textContent = col.format(value, data);
+        const t = col.format(value, data);
+        cell.appendChild(Object.assign(document.createElement('span'), { textContent: t }));
+        cell.title = t;
       } else {
         const typeDef = cellTypes[col.type || 'text'];
         if (typeDef?.render) {
           typeDef.render(value, data, cell, col.meta);
         } else {
-          cell.textContent = value != null ? value : '';
+          const t = value != null ? String(value) : '';
+          cell.appendChild(Object.assign(document.createElement('span'), { textContent: t }));
+          cell.title = t;
         }
       }
 
@@ -827,6 +832,11 @@ export class UITable extends UIElement {
         cell.setAttribute('data-pinned', col.pinned);
       }
 
+      // Wrap (per-column opt-in to multi-line cell content)
+      if (col.wrap) {
+        cell.setAttribute('data-wrap', '');
+      }
+
       cells.push(cell);
     }
 

package/components/table/table.a2ui.json

@@ -14,7 +14,7 @@
   ],
   "properties": {
     "columns": {
-      "description": "Column definitions. Array of {key, label, type?, width?, minWidth?, maxWidth?, flex?, sortable?, resizable?, filterable?, pinned?, hidden?, accessor?, format?, render?, sortFn?, filterType?, meta?}. Alternative to declarative <col-def> children.",
+      "description": "Column definitions. Array of {key, label, type?, width?, minWidth?, maxWidth?, flex?, sortable?, resizable?, filterable?, pinned?, hidden?, wrap?, accessor?, format?, render?, sortFn?, filterType?, meta?}. Alternative to declarative <col-def> children.",
       "type": "array",
       "default": []
     },
@@ -75,6 +75,11 @@
       "description": "Alternate row background colors for visual scanning.",
       "type": "boolean",
       "default": false
+    },
+    "wrap": {
+      "description": "Allow body-cell content to wrap onto multiple lines. Default is single-line with ellipsis truncation (matches the row convention shared by <select-ui> + <nav-item-ui>); long unbreakable strings clip gracefully rather than rewrapping the row. With [wrap], row height auto-grows to fit wrapped content. For surgical opt-in on a single column, set [data-wrap] on the cell / col-def instead.",
+      "type": "boolean",
+      "default": false
     }
   },
   "required": [

package/components/table/table.css

@@ -2,7 +2,7 @@
   :where(:scope) {
     /* ── Tokens ── */
     --table-font-size:        var(--a-ui-size);
-    --table-heading-size:     var(--a-ui-sm);
+    --table-heading-size:     var(--a-ui-xs);
     --table-heading-weight:   var(--a-weight-medium);
     --table-heading-tracking: 0.06em;
     --table-heading-fg:       var(--a-fg-muted);
@@ -165,6 +165,19 @@
     letter-spacing: var(--table-heading-tracking);
     white-space: nowrap;
     position: relative;
+    display: flex;
+    align-items: center;
+  }
+
+  /* Label span truncates; sort icon + filter button remain visible.
+     Cannot put overflow:hidden on the columnheader itself — it would
+     clip the position:absolute filter dropdown. */
+  [role="columnheader"] > span {
+    flex: 1;
+    min-width: 0;
+    overflow: hidden;
+    text-overflow: ellipsis;
+    white-space: nowrap;
   }
 
   /* ═══════ Sortable headers ═══════ */
@@ -216,6 +229,60 @@
     padding: var(--table-py) var(--table-px);
     border-bottom: 1px solid var(--table-border);
     min-width: 0;
+    /* Default: single line with ellipsis. Authors opt in to wrapping
+       via [wrap] on the host (whole table) or [data-wrap] on a column /
+       individual cell. Matches `<select-ui>` / `<nav-item-ui>` single-line
+       row convention; long unbreakable strings (URLs, IDs) clip gracefully
+       rather than rewrapping the row. */
+    white-space: nowrap;
+    overflow: hidden;
+    text-overflow: ellipsis;
+  }
+
+  /* text-overflow on a flex container doesn't reach text nodes (anonymous
+     flex items). Built-in cell types now wrap text in <span>; link type
+     creates <a>; avatar/progress composite types use row-ui > span. */
+  [data-body] [role="gridcell"] > span,
+  [data-body] [role="gridcell"] > a {
+    min-width: 0;
+    flex: 1;
+    overflow: hidden;
+    text-overflow: ellipsis;
+    white-space: nowrap;
+  }
+
+  [data-body] [role="gridcell"] > row-ui {
+    min-width: 0;
+    overflow: hidden;
+  }
+
+  [data-body] [role="gridcell"] > row-ui > span {
+    flex: 1;
+    min-width: 0;
+    overflow: hidden;
+    text-overflow: ellipsis;
+    white-space: nowrap;
+  }
+
+  /* Wrap opt-in: per-table (all body cells) or per-cell (one column).
+     Restores the legacy `overflow-wrap: anywhere` behavior so wrapped
+     content can break inside long unbroken tokens (URLs, IDs). Row
+     height auto-grows to fit. */
+  :scope[wrap] [data-body] [role="gridcell"],
+  [data-body] [role="gridcell"][data-wrap] {
+    white-space: normal;
+    overflow: visible;
+    text-overflow: clip;
+    overflow-wrap: anywhere;
+  }
+
+  :scope[wrap] [data-body] [role="gridcell"] > span,
+  :scope[wrap] [data-body] [role="gridcell"] > a,
+  [data-body] [role="gridcell"][data-wrap] > span,
+  [data-body] [role="gridcell"][data-wrap] > a {
+    white-space: normal;
+    overflow: visible;
+    text-overflow: clip;
     overflow-wrap: anywhere;
   }
 

package/components/table/table.d.ts

@@ -86,7 +86,7 @@ export interface TableSortEventDetail {
 export type TableSortEvent = CustomEvent<TableSortEventDetail>;
 
 export class UITable extends UIElement {
-  /** Column definitions. Array of {key, label, type?, width?, minWidth?, maxWidth?, flex?, sortable?, resizable?, filterable?, pinned?, hidden?, accessor?, format?, render?, sortFn?, filterType?, meta?}. Alternative to declarative <col-def> children. */
+  /** Column definitions. Array of {key, label, type?, width?, minWidth?, maxWidth?, flex?, sortable?, resizable?, filterable?, pinned?, hidden?, wrap?, accessor?, format?, render?, sortFn?, filterType?, meta?}. Alternative to declarative <col-def> children. */
   columns: unknown[];
   /** Row records. Array of plain objects keyed to columns[].key. */
   data: unknown[];
@@ -108,6 +108,8 @@ export class UITable extends UIElement {
   sortable: boolean;
   /** Alternate row background colors for visual scanning. */
   striped: boolean;
+  /** Allow body-cell content to wrap onto multiple lines. Default is single-line with ellipsis truncation (matches the row convention shared by <select-ui> + <nav-item-ui>); long unbreakable strings clip gracefully rather than rewrapping the row. With [wrap], row height auto-grows to fit wrapped content. For surgical opt-in on a single column, set [data-wrap] on the cell / col-def instead. */
+  wrap: boolean;
 
   addEventListener<K extends keyof HTMLElementEventMap>(
     type: K,

package/components/table/table.test.js

@@ -172,3 +172,67 @@ describe('table-ui — v0.6.18 loading=skeleton-rows (FB-12 P2)', () => {
     expect(afterHeader.children.length).toBe(3);
   });
 });
+
+/**
+ * Body-cell wrap default + opt-in paths (PATCH-class behavior change).
+ *
+ * Default: cells truncate single-line with ellipsis (the CSS rule sets
+ * white-space: nowrap; overflow: hidden; text-overflow: ellipsis). Three
+ * opt-in surfaces lift the truncation:
+ *   - host [wrap] attribute (reflected from the `wrap` prop)
+ *   - col.wrap=true in columns[] → renderer sets [data-wrap] on each
+ *     body cell in that column
+ *   - [data-wrap] directly on a hand-authored <td>
+ *
+ * Tests lock the attribute contract; CSS-rule application is covered by
+ * the source-grep stylistic invariants of table.css.
+ */
+describe('table-ui — wrap default + opt-in', () => {
+  beforeEach(() => { document.body.innerHTML = ''; });
+
+  it('host [wrap] attribute reflects from the wrap property', async () => {
+    const el = mount('<table-ui></table-ui>');
+    el.columns = COLS;
+    el.data = ROWS;
+    await raf();
+    expect(el.hasAttribute('wrap')).toBe(false);
+    el.wrap = true;
+    await raf();
+    expect(el.hasAttribute('wrap')).toBe(true);
+    el.wrap = false;
+    await raf();
+    expect(el.hasAttribute('wrap')).toBe(false);
+  });
+
+  it('col.wrap=true marks body cells in that column with [data-wrap]', async () => {
+    const el = mount('<table-ui></table-ui>');
+    el.columns = [
+      { key: 'id',    label: 'ID' },
+      { key: 'name',  label: 'Name', wrap: true },
+      { key: 'email', label: 'Email' },
+    ];
+    el.data = ROWS;
+    await raf();
+    const bodyRows = el.querySelectorAll(':scope > [data-body] > [role="row"]');
+    expect(bodyRows.length).toBe(2);
+    for (const row of bodyRows) {
+      const cells = row.querySelectorAll('[role="gridcell"]');
+      expect(cells.length).toBe(3);
+      expect(cells[0].hasAttribute('data-wrap')).toBe(false);
+      expect(cells[1].hasAttribute('data-wrap')).toBe(true);
+      expect(cells[2].hasAttribute('data-wrap')).toBe(false);
+    }
+  });
+
+  it('omitting col.wrap leaves all body cells without [data-wrap]', async () => {
+    const el = mount('<table-ui></table-ui>');
+    el.columns = COLS;
+    el.data = ROWS;
+    await raf();
+    const cells = el.querySelectorAll(':scope > [data-body] [role="gridcell"]');
+    expect(cells.length).toBeGreaterThan(0);
+    for (const cell of cells) {
+      expect(cell.hasAttribute('data-wrap')).toBe(false);
+    }
+  });
+});

package/components/table/table.yaml

@@ -19,7 +19,7 @@ composes:
   - badge-ui
 props:
   columns:
-    description: Column definitions. Array of {key, label, type?, width?, minWidth?, maxWidth?, flex?, sortable?, resizable?, filterable?, pinned?, hidden?, accessor?, format?, render?, sortFn?, filterType?, meta?}. Alternative to declarative <col-def> children.
+    description: Column definitions. Array of {key, label, type?, width?, minWidth?, maxWidth?, flex?, sortable?, resizable?, filterable?, pinned?, hidden?, wrap?, accessor?, format?, render?, sortFn?, filterType?, meta?}. Alternative to declarative <col-def> children.
     type: array
     default: []
   data:
@@ -76,6 +76,17 @@ props:
     description: Alternate row background colors for visual scanning.
     type: boolean
     default: false
+  wrap:
+    description: >-
+      Allow body-cell content to wrap onto multiple lines. Default is
+      single-line with ellipsis truncation (matches the row convention
+      shared by <select-ui> + <nav-item-ui>); long unbreakable strings
+      clip gracefully rather than rewrapping the row. With [wrap], row
+      height auto-grows to fit wrapped content. For surgical opt-in on
+      a single column, set [data-wrap] on the cell / col-def instead.
+    type: boolean
+    default: false
+    reflect: true
 events:
   cell-click:
     description: Fired when a data cell is clicked. detail carries the cell location + value.
@@ -218,7 +229,33 @@ requiredIcons:
   - funnel-simple
   - funnel-simple-fill
 a2ui:
-  rules: []
+  rules:
+    - >-
+      Canonical composition: wrap <table-ui> in <card-ui><section bleed>
+      for edge-to-edge tables. The [bleed] removes section padding so
+      columns span the full card width (see apps/saas/members,
+      billing, admin-dashboard).
+    - >-
+      Pair with <table-toolbar-ui for="<table-id>"> for any table that
+      needs search / filter / sort / columns visibility. Do NOT
+      re-implement those affordances in the card header — the toolbar
+      auto-wires search/filter/sort/columns changes into the bound
+      table.
+    - >-
+      Cells truncate single-line by default (v0.6.21 §403
+      truncate-default). Opt out per-table with [wrap] for whole-table
+      multiline, or per-cell with [data-wrap] on a single column /
+      cell.
+    - >-
+      Use [raw] in production app consumers — it disables the demo
+      seed data so the table renders only consumer-provided rows /
+      columns / data props.
+    - >-
+      Listen for the `sort` event with detail.key + detail.dir (NOT
+      .column / .direction). `cell-click` detail carries {key, row,
+      value, dataIndex}. Per ADR-0027, table-ui composes check-ui,
+      icon-ui, progress-ui, pagination-ui, skeleton-ui, badge-ui —
+      consumer pages must explicitly import the ones they use.
 anti_patterns: []
 examples:
   - name: api-key-table

package/components/table-toolbar/table-toolbar.yaml

@@ -118,7 +118,33 @@ requiredIcons:
   - arrow-down
   - caret-up-down
 a2ui:
-  rules: []
+  rules:
+    - >-
+      Pair <table-toolbar-ui> with <table-ui> via [for="<table-id>"]
+      (or rely on first-sibling fallback when both are inside the
+      same parent). One toolbar per table. Do NOT also use
+      <card-ui>'s <header> on the same card — that produces a doubled
+      chrome row.
+    - >-
+      All four affordances (search, filter, sort, columns) default ON.
+      Opt out individually via [no-search] / [no-filter] / [no-sort]
+      / [no-columns]. The previous [searchable] / [filterable]
+      attributes are deprecated — do NOT emit them.
+    - >-
+      Place the toolbar ABOVE the <card-ui> containing the table-ui,
+      or use [variant="card"] when standing alone outside a card-ui
+      parent (the variant wraps the toolbar in card-style chrome).
+    - >-
+      Use slot="action" (or [slot="actions"]) for trailing primary
+      buttons (Invite, Export, +New). Use [text] / [count] props for
+      the left cluster, or slotted [slot="title"] / [slot="count"]
+      when content is markup (a <span> + <badge-ui>, etc.).
+    - >-
+      Listen for toolbar events (`search`, `filter-change`,
+      `sort-change`, `columns-change`) only to mirror state to URL /
+      persistence / analytics. The toolbar already wires its changes
+      into the bound table — you don't need to manually update the
+      table.
 anti_patterns: []
 examples:
   - name: members-toolbar

package/components/tabs/tab.a2ui.json

@@ -44,12 +44,26 @@
     "composes": [],
     "events": {},
     "examples": [],
-    "keywords": [],
+    "keywords": [
+      "tab",
+      "tab-panel",
+      "view-switcher-child",
+      "tabs-child"
+    ],
     "name": "UITab",
-    "related": [],
+    "related": [
+      "Tabs",
+      "Nav",
+      "Segmented"
+    ],
     "slots": {},
     "states": [],
-    "synonyms": {},
+    "synonyms": {
+      "tab": [
+        "view-tab",
+        "switcher-tab"
+      ]
+    },
     "tag": "tab-ui",
     "tokens": {},
     "traits": [],

package/components/tabs/tab.yaml

@@ -31,3 +31,42 @@ props:
     description: Whether the tab is selectable.
     type: boolean
     default: false
+
+a2ui:
+  rules:
+    - >-
+      <tab-ui> only renders inside <tabs-ui>. Never use it standalone.
+      The parent reads each tab's [text] + [icon] + [value] to render
+      the button strip; the tab's default slot is the panel content
+      that the parent auto-hides when inactive.
+    - >-
+      [value] is required and must be unique among siblings — the
+      parent <tabs-ui> matches its own [value] against each
+      <tab-ui>[value] to decide which is active. [text] is the visible
+      button label; optional [icon] is a Phosphor icon name shown
+      leading the label.
+    - >-
+      Use the default slot for panel content. Inactive <tab-ui>
+      children are auto-hidden by the parent's [hidden] toggling; do
+      NOT set [hidden] yourself unless you want to remove the button
+      from the strip entirely (i.e. a temporarily-disabled tab whose
+      strip button shouldn't render at all).
+    - >-
+      Use [disabled] to keep a tab visible in the strip but
+      non-selectable. Do not pair <tab-ui> with <button-ui> wrappers —
+      the strip button is parent-rendered. Do not nest <tab-ui> inside
+      another <tab-ui>.
+
+keywords:
+  - tab
+  - tab-panel
+  - view-switcher-child
+  - tabs-child
+
+related:
+  - Tabs
+  - Nav
+  - Segmented
+
+synonyms:
+  tab: [view-tab, switcher-tab]

package/components/tabs/tabs.a2ui.json

@@ -2,7 +2,7 @@
   "$schema": "https://json-schema.org/draft/2020-12/schema",
   "$id": "https://adiaui.dev/a2ui/v0_9/components/Tabs.json",
   "title": "Tabs",
-  "description": "Tabbed panel switcher. Renders button strip from child tab-ui elements.",
+  "description": "Tabbed panel switcher. Renders a button strip from child <tab-ui> elements and toggles their associated panel via the active attribute. Use for switching between equivalent peer views in one region; for navigation between routes use <nav-ui> instead.",
   "type": "object",
   "allOf": [
     {

package/components/tabs/tabs.d.ts

@@ -1,5 +1,5 @@
 /**
- * `<tabs-ui>` — Tabbed panel switcher. Renders button strip from child tab-ui elements.
+ * `<tabs-ui>` — Tabbed panel switcher. Renders a button strip from child <tab-ui> elements and toggles their associated panel via the active attribute. Use for switching between equivalent peer views in one region; for navigation between routes use <nav-ui> instead.
  *
  * @see https://ui-kit.exe.xyz/site/components/tabs
  *

package/components/tabs/tabs.yaml

@@ -6,7 +6,11 @@ tag: tabs-ui
 component: Tabs
 category: container
 version: 1
-description: Tabbed panel switcher. Renders button strip from child tab-ui elements.
+description: >-
+  Tabbed panel switcher. Renders a button strip from child <tab-ui>
+  elements and toggles their associated panel via the active attribute.
+  Use for switching between equivalent peer views in one region; for
+  navigation between routes use <nav-ui> instead.
 # Per ADR-0027 — primitives that programmatically create other primitives
 # do NOT auto-import them. Consumer (or demo shell) must explicitly import.
 composes:
@@ -76,7 +80,37 @@ tokens:
   --tabs-radius:
     description: Override base border radius
 a2ui:
-  rules: []
+  rules:
+    - >-
+      Decision rule: use <tabs-ui> when switching VIEWS within the same
+      logical page (no route change, no URL change). For navigating
+      AWAY (different page / route / anchor), use <nav-ui> instead. For
+      a form-control segmented selector that returns a value, use
+      <segmented-ui>.
+    - >-
+      Children of <tabs-ui> MUST be <tab-ui> elements. The button strip
+      is rendered from each child's [text] + optional [icon]; the
+      parent auto-toggles [hidden] on inactive <tab-ui> children. Do
+      not place arbitrary markup directly inside <tabs-ui> — wrap it
+      in <tab-ui>.
+    - >-
+      Canonical placements: inside <card-ui>'s <header> for in-card
+      section switching; inside <editor-canvas-toolbar> for editor
+      sub-views (see the editor sub-views recipe in patterns-recipes.md);
+      or standalone as an in-page switcher. When standalone, wire
+      sibling <div data-view="…"> panels via the `change` event
+      (detail.value); for tabs whose content lives inside the <tab-ui>
+      child, the auto-hide handles visibility.
+    - >-
+      Set [value] to the initially active tab. If omitted, the first
+      non-disabled <tab-ui> becomes active on connect. Set
+      [orientation="vertical"] for left-rail tab strips.
+    - >-
+      Variant caveat: only [variant="bordered"] is implemented (adds a
+      subtle divider). [variant="underline"] is widely used in source
+      but is equivalent to default (no-op). [variant="pills"] and
+      [variant="segmented"] are declared in the enum but NOT styled —
+      do NOT emit them; for a form-style selector use <segmented-ui>.
 anti_patterns: []
 examples:
   - name: tabs-panels

package/components/tag/tag.a2ui.json

@@ -2,7 +2,7 @@
   "$schema": "https://json-schema.org/draft/2020-12/schema",
   "$id": "https://adiaui.dev/a2ui/v0_9/components/Tag.json",
   "title": "Tag",
-  "description": "Inline tag/chip with optional dismiss button.",
+  "description": "Inline INTERACTIVE chip / pill with optional dismiss affordance.\nText rendered via CSS `attr(text)`. Use for filter chips\n(removable=true + `remove` event), autocomplete tokens, and\nuser-managed labels. Distinct from <badge-ui>, which is READ-ONLY\nand includes the [status] shorthand for Beta / New / Deprecated\nmarkers — badge-ui has no remove event. For navigation grouping\nuse <nav-group-ui>; for inline command actions use\n<action-list-ui>.\n",
   "type": "object",
   "allOf": [
     {
@@ -97,7 +97,11 @@
       "pill"
     ],
     "name": "UITag",
-    "related": [],
+    "related": [
+      "Badge",
+      "NavGroup",
+      "ActionList"
+    ],
     "slots": {},
     "states": [
       {

package/components/tag/tag.d.ts

@@ -1,5 +1,13 @@
 /**
- * `<tag-ui>` — Inline tag/chip with optional dismiss button.
+ * `<tag-ui>` — Inline INTERACTIVE chip / pill with optional dismiss affordance.
+Text rendered via CSS `attr(text)`. Use for filter chips
+(removable=true + `remove` event), autocomplete tokens, and
+user-managed labels. Distinct from <badge-ui>, which is READ-ONLY
+and includes the [status] shorthand for Beta / New / Deprecated
+markers — badge-ui has no remove event. For navigation grouping
+use <nav-group-ui>; for inline command actions use
+<action-list-ui>.
+
  *
  * @see https://ui-kit.exe.xyz/site/components/tag
  *

package/components/tag/tag.yaml

@@ -6,7 +6,15 @@ tag: tag-ui
 component: Tag
 category: display
 version: 1
-description: Inline tag/chip with optional dismiss button.
+description: |
+  Inline INTERACTIVE chip / pill with optional dismiss affordance.
+  Text rendered via CSS `attr(text)`. Use for filter chips
+  (removable=true + `remove` event), autocomplete tokens, and
+  user-managed labels. Distinct from <badge-ui>, which is READ-ONLY
+  and includes the [status] shorthand for Beta / New / Deprecated
+  markers — badge-ui has no remove event. For navigation grouping
+  use <nav-group-ui>; for inline command actions use
+  <action-list-ui>.
 props:
   disabled:
     description: Disables interaction and dims the tag.
@@ -64,7 +72,31 @@ tokens: {}
 requiredIcons:
   - x
 a2ui:
-  rules: []
+  rules:
+    - >-
+      Use <tag-ui> for INTERACTIVE / DISMISSABLE labels — filter chips,
+      autocomplete tokens, user-managed labels. Tag-ui fires a `remove`
+      event when [removable] is set. For READ-ONLY status flags
+      (counts, Beta / New / Deprecated markers, notification dots) use
+      <badge-ui> instead — badge has no remove event and includes the
+      [status] shorthand.
+    - >-
+      Set [removable] and listen for the `remove` event (detail:
+      {text, value}) when the tag represents a user-applied filter or
+      selection that can be cleared.
+    - >-
+      [variant] maps to semantic state of the underlying record:
+      success = active / approved, warning = pending,
+      danger = blocked / error, info = neutral-emphasis. Default
+      (no variant) for unlabeled categories.
+    - >-
+      Use [size="sm"] for inline-with-text contexts (doc page headers,
+      table cells, badges next to titles); [size="md"] (default) for
+      filter-bar chips and standalone tag rows.
+    - >-
+      Group multiple tags inside a <row-ui gap="2"> — never stack them
+      vertically; vertical lists of dismissable items are an
+      <action-list-ui> use case, not <tag-ui>.
 anti_patterns: []
 examples:
   - name: basic-tag
@@ -131,4 +163,7 @@ synonyms:
   pill:
     - badge
     - tag
-related: []
+related:
+  - Badge
+  - NavGroup
+  - ActionList