@adia-ai/web-components 0.6.21 → 0.6.22

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 ═══════ */
@@ -226,6 +239,31 @@
     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
@@ -238,6 +276,16 @@
     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;
+  }
+
   [data-align="right"] {
     text-align: right;
     justify-content: flex-end;

package/components/table/table.yaml

@@ -229,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

package/components/text/class.js

@@ -25,6 +25,10 @@
  */
 
 import { UIElement } from '../../core/element.js';
+import { parseResponsive, breakpoint } from '../../core/responsive.js';
+
+const _SIZE = { sm: 'var(--a-body-sm)', md: 'var(--a-body-md)', lg: 'var(--a-body-lg)' };
+function _sizeToCss(v) { return _SIZE[v] ?? v; }
 
 export class UIText extends UIElement {
   static properties = {
@@ -52,5 +56,14 @@ export class UIText extends UIElement {
     } else {
       this.style.removeProperty('--_text-lines');
     }
+
+    // Responsive size — e.g. size="sm sm@md lg@lg"
+    const size = this.size;
+    if (size?.includes('@')) {
+      const bp = breakpoint.value; // subscribe only when needed
+      this.style.setProperty('--text-size', _sizeToCss(parseResponsive(size, bp)));
+    } else {
+      this.style.removeProperty('--text-size');
+    }
   }
 }

package/components/text/text.a2ui.json

@@ -36,7 +36,7 @@
       "default": 0
     },
     "size": {
-      "description": "Override the variant's font-size on the body ladder. Maps to --a-body-sm / --a-body-md / --a-body-lg. Permissive: unknown values are no-ops (variant size wins). Added v0.6.18 (FB-10).",
+      "description": "Override the variant's font-size on the body ladder (sm/md/lg → --a-body-sm/md/lg). Accepts `@bp` notation: size=\"sm md@lg\" = sm below lg, md from lg up. Added v0.6.18 (FB-10).",
       "type": "string",
       "enum": [
         "sm",
@@ -154,7 +154,14 @@
         "name": "idle"
       }
     ],
-    "synonyms": {},
+    "synonyms": {
+      "text": [
+        "typography",
+        "prose",
+        "label-text",
+        "paragraph"
+      ]
+    },
     "tag": "text-ui",
     "tokens": {},
     "traits": [],

package/components/text/text.d.ts

@@ -43,7 +43,7 @@ export class UIText extends UIElement {
   color: 'default' | 'subtle' | 'strong' | 'accent' | 'danger' | 'success' | 'warning';
   /** Multi-line clamp count (0 = no clamp) */
   lines: number;
-  /** Override the variant's font-size on the body ladder. Maps to --a-body-sm / --a-body-md / --a-body-lg. Permissive: unknown values are no-ops (variant size wins). Added v0.6.18 (FB-10). */
+  /** Override the variant's font-size on the body ladder (sm/md/lg → --a-body-sm/md/lg). Accepts `@bp` notation: size="sm md@lg" = sm below lg, md from lg up. Added v0.6.18 (FB-10). */
   size: 'sm' | 'md' | 'lg';
   /** When true, applies stronger emphasis (heavier weight + accent color). Styled via :scope[strong] in text.css. Use instead of variant=heading when you want a single emphasized word inline in body copy. */
   strong: boolean;

package/components/text/text.yaml

@@ -22,9 +22,9 @@ props:
     default: 0
   size:
     description: >-
-      Override the variant's font-size on the body ladder. Maps to
-      --a-body-sm / --a-body-md / --a-body-lg. Permissive: unknown values
-      are no-ops (variant size wins). Added v0.6.18 (FB-10).
+      Override the variant's font-size on the body ladder (sm/md/lg → --a-body-sm/md/lg).
+      Accepts `@bp` notation: size="sm md@lg" = sm below lg, md from lg up.
+      Added v0.6.18 (FB-10).
     type: string
     enum: ["sm", "md", "lg"]
     default: ""
@@ -112,7 +112,13 @@ states:
 traits: []
 tokens: {}
 a2ui:
-  rules: []
+  rules:
+    - rule: 'Use for typographic content with semantic role (heading, body, label, caption). Variant attribute sets the role.'
+      reason: 'Token-driven font/size/weight per variant — better than raw <p>/<h*> with overrides.'
+    - rule: 'For inline-flow rich content with multiple paragraphs, use <richtext-ui> instead.'
+      reason: 'Richtext handles paragraph rhythm + rich formatting.'
+    - rule: 'Heading variants (h1, h2, ...) are not auto-tagged — set the role explicitly via variant.'
+      reason: 'Visual variant decoupled from DOM tag.'
 anti_patterns: []
 examples:
   - name: chat-interface
@@ -414,7 +420,8 @@ examples:
       ]
 keywords:
   - text
-synonyms: {}
+synonyms:
+  text: [typography, prose, label-text, paragraph]
 related:
   - avatar
   - input

package/components/textarea/textarea.a2ui.json

@@ -2,7 +2,7 @@
   "$schema": "https://json-schema.org/draft/2020-12/schema",
   "$id": "https://adiaui.dev/a2ui/v0_9/components/Textarea.json",
   "title": "Textarea",
-  "description": "Multiline text input. The host IS the interactive surface.",
+  "description": "Multi-line text input primitive — the host IS the contenteditable\nsurface (per ADR-0025, no native <textarea> wrapped underneath).\nForm-bearing via UIFormElement: [name], [value], [required],\n[disabled], [readonly], fires `change` on blur and `input` per\nkeystroke. Enter inserts a newline — does NOT fire `submit` (for\nEnter-to-send composers use <chat-input-ui submit-on-enter> inside\n<chat-composer>). Wrap in <field-ui label=\"…\"> for the canonical\nlabeled stack.\n",
   "type": "object",
   "allOf": [
     {
@@ -110,7 +110,12 @@
       "textarea"
     ],
     "name": "UITextarea",
-    "related": [],
+    "related": [
+      "Input",
+      "Field",
+      "ChatInput",
+      "Code"
+    ],
     "slots": {},
     "states": [
       {
@@ -118,7 +123,14 @@
         "name": "idle"
       }
     ],
-    "synonyms": {},
+    "synonyms": {
+      "textarea": [
+        "multiline-input",
+        "text-area",
+        "comment-input",
+        "long-text-input"
+      ]
+    },
     "tag": "textarea-ui",
     "tokens": {},
     "traits": [],

package/components/textarea/textarea.yaml

@@ -6,7 +6,15 @@ tag: textarea-ui
 component: Textarea
 category: layout
 version: 1
-description: Multiline text input. The host IS the interactive surface.
+description: |
+  Multi-line text input primitive — the host IS the contenteditable
+  surface (per ADR-0025, no native <textarea> wrapped underneath).
+  Form-bearing via UIFormElement: [name], [value], [required],
+  [disabled], [readonly], fires `change` on blur and `input` per
+  keystroke. Enter inserts a newline — does NOT fire `submit` (for
+  Enter-to-send composers use <chat-input-ui submit-on-enter> inside
+  <chat-composer>). Wrap in <field-ui label="…"> for the canonical
+  labeled stack.
 props:
   disabled:
     description: Disables interaction, removes contenteditable, and dims the control. Inherited from UIFormElement.
@@ -86,7 +94,31 @@ states:
 traits: []
 tokens: {}
 a2ui:
-  rules: []
+  rules:
+    - >-
+      <textarea-ui> is the canonical multi-line text input. The host
+      IS the contenteditable surface — NEVER use a native <textarea>
+      (banned by ADR-0025).
+    - >-
+      Wrap <textarea-ui> in <field-ui label="…" hint="…" error="…"> for
+      the canonical labeled stack. 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` (on blur after value change) and
+      `input` (per keystroke).
+    - >-
+      Use [rows] to set initial height (default 3) and [resize]
+      (vertical | horizontal | both | none; default vertical) to
+      control user resize. Never substitute a native <textarea> just
+      to get rows / resize.
+    - >-
+      Enter inserts a newline — <textarea-ui> does NOT emit a `submit`
+      event. For Enter-to-send multi-line composers, use
+      <chat-input-ui submit-on-enter> inside <chat-composer>, not
+      textarea-ui.
 anti_patterns: []
 examples:
   - name: basic-textarea
@@ -116,5 +148,10 @@ examples:
       ]
 keywords:
   - textarea
-synonyms: {}
-related: []
+synonyms:
+  textarea: [multiline-input, text-area, comment-input, long-text-input]
+related:
+  - Input
+  - Field
+  - ChatInput
+  - Code

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

@@ -62,12 +62,29 @@
     "composes": [],
     "events": {},
     "examples": [],
-    "keywords": [],
+    "keywords": [
+      "timeline-item",
+      "timeline-row",
+      "activity-entry",
+      "event-entry",
+      "history-row"
+    ],
     "name": "UITimelineItem",
-    "related": [],
+    "related": [
+      "Timeline",
+      "FeedItem",
+      "Stepper"
+    ],
     "slots": {},
     "states": [],
-    "synonyms": {},
+    "synonyms": {
+      "timeline-item": [
+        "timeline-row",
+        "activity-row",
+        "event-row",
+        "history-entry"
+      ]
+    },
     "tag": "timeline-item-ui",
     "tokens": {},
     "traits": [],

package/components/timeline/timeline-item.yaml

@@ -45,3 +45,27 @@ props:
     description: Show a spinner instead of the icon while status=pending.
     type: boolean
     default: false
+
+keywords:
+  - timeline-item
+  - timeline-row
+  - activity-entry
+  - event-entry
+  - history-row
+
+synonyms:
+  timeline-item: [timeline-row, activity-row, event-row, history-entry]
+
+related:
+  - Timeline
+  - FeedItem
+  - Stepper
+
+a2ui:
+  rules:
+    - rule: 'Child of <timeline-ui> — one chronological event with timestamp + content + optional icon dot.'
+      reason: 'Timeline cluster contract.'
+    - rule: 'Different from <stepper-item-ui> (process steps with completion state) — timeline-item is event history.'
+      reason: 'Process vs history.'
+    - rule: 'Order is DOM-order — no auto-sort by timestamp.'
+      reason: 'Author-controlled order.'

package/components/timeline/timeline.a2ui.json

@@ -81,7 +81,14 @@
         "name": "idle"
       }
     ],
-    "synonyms": {},
+    "synonyms": {
+      "timeline": [
+        "activity-log",
+        "event-log",
+        "history",
+        "audit-trail"
+      ]
+    },
     "tag": "timeline-ui",
     "tokens": {},
     "traits": [],