@adia-ai/web-components 0.7.28 → 0.8.1

package/components/tag/tag.css

@@ -8,7 +8,7 @@ tag-ui[removable]:not([disabled]):hover {
   :where(:scope) {
     /* ── Tokens ── */
     --tag-bg:           var(--a-bg-muted);
-    --tag-fg:           var(--a-fg);
+    --tag-fg:           var(--md-sys-color-neutral-on-surface);
     --tag-border:       transparent;
     --tag-radius:       var(--a-radius-full);
     --tag-px:           var(--a-space-1-5);
@@ -51,6 +51,16 @@ tag-ui[removable]:not([disabled]):hover {
     box-sizing: border-box;
     display: inline-flex;
     align-items: center;
+    /* align-self: start — TKT-0021. A flex-column ancestor (col-ui
+       defaults to align-items: stretch) otherwise stretches a bare
+       tag-ui to the column's full width; a chip should size to its own
+       content regardless of ancestor. justify-content: center is the
+       matching defensive default badge-ui/button-ui already carry
+       (badge.css/button.css) — if the box is ever wider than its
+       content for any other reason, the label still centers instead of
+       reading left-aligned in an oversized pill. */
+    align-self: start;
+    justify-content: center;
     gap: var(--tag-gap);
     padding: var(--tag-py) var(--tag-px);
     border-radius: var(--tag-radius);
@@ -85,26 +95,28 @@ tag-ui[removable]:not([disabled]):hover {
      metadata-chip surfaces in dense lists. */
   :scope[variant="info"] {
     --tag-bg: var(--a-info-bg);
-    --tag-fg: var(--a-info-fg);
+    --tag-fg: var(--md-sys-color-info-on-info);
   }
 
   :scope[variant="success"] {
     --tag-bg: var(--a-success-bg);
-    --tag-fg: var(--a-success-fg);
+    --tag-fg: var(--md-sys-color-success-on-success);
   }
 
-  /* `--a-warning-bg` is the bright-amber step (semantics.css L3 redirect
-     to `-20-tint`) paired with `--a-warning-fg` (dark brown text) — the
-     canonical caution-tape pair. Pre-v0.6.36 this rule had a local
-     `-20-tint` override; that workaround moved to the token system. */
+  /* Same shape as the sibling families since the Material static-token
+     migration: amber fill + the palette's own fixed-light on-color
+     (`on-warning`, white in both schemes per Material's on-color law).
+     The pre-migration dark-brown-text override is gone — its
+     lower-than-siblings contrast is a known, operator-accepted
+     consequence (TKT-0018, wontfix pending palette adjustment). */
   :scope[variant="warning"] {
     --tag-bg: var(--a-warning-bg);
-    --tag-fg: var(--a-warning-fg);
+    --tag-fg: var(--md-sys-color-warning-on-warning);
   }
 
   :scope[variant="danger"] {
     --tag-bg: var(--a-danger-bg);
-    --tag-fg: var(--a-danger-fg);
+    --tag-fg: var(--md-sys-color-danger-on-danger);
   }
 
   /* `default` (no family) stays as quiet chrome — a stark fg/bg-inverse
@@ -112,7 +124,7 @@ tag-ui[removable]:not([disabled]):hover {
      stamp via `[tone="solid"]` when you want a high-contrast neutral pill. */
   :scope[variant="default"] {
     --tag-bg: var(--a-bg-muted);
-    --tag-fg: var(--a-fg);
+    --tag-fg: var(--md-sys-color-neutral-on-surface);
   }
 
   /* ── Tone modifier — orthogonal to [variant] ──
@@ -122,28 +134,28 @@ tag-ui[removable]:not([disabled]):hover {
      uses as its default. Use on metadata chips in dense lists where the
      saturated default would compete for attention. */
   :scope[tone="muted"][variant="info"] {
-    --tag-bg: var(--a-info-muted);
-    --tag-fg: var(--a-info-text);
+    --tag-bg: var(--md-sys-color-info-container);
+    --tag-fg: var(--md-sys-color-info-on-surface);
   }
   :scope[tone="muted"][variant="success"] {
-    --tag-bg: var(--a-success-muted);
-    --tag-fg: var(--a-success-text);
+    --tag-bg: var(--md-sys-color-success-container);
+    --tag-fg: var(--md-sys-color-success-on-surface);
   }
   :scope[tone="muted"][variant="warning"] {
-    --tag-bg: var(--a-warning-muted);
-    --tag-fg: var(--a-warning-text);
+    --tag-bg: var(--md-sys-color-warning-container);
+    --tag-fg: var(--md-sys-color-warning-on-surface);
   }
   :scope[tone="muted"][variant="danger"] {
-    --tag-bg: var(--a-danger-muted);
-    --tag-fg: var(--a-danger-text);
+    --tag-bg: var(--md-sys-color-danger-container);
+    --tag-fg: var(--md-sys-color-danger-on-surface);
   }
 
   /* `[tone="solid"]` on the neutral default (or no variant) inverts the
      chrome — solid fg-color bg with bg-color text. High-contrast neutral
      stamp. Explicit opt-in; the variant-less default stays quiet chrome. */
   :scope[tone="solid"]:not([variant="info"]):not([variant="success"]):not([variant="warning"]):not([variant="danger"]) {
-    --tag-bg: var(--a-fg);
-    --tag-fg: var(--a-bg);
+    --tag-bg: var(--md-sys-color-neutral-on-surface);
+    --tag-fg: var(--md-sys-color-neutral-background);
   }
 
   /* ── `[tone="outline"]` — transparent bg + family-colored border + text ──
@@ -155,25 +167,25 @@ tag-ui[removable]:not([disabled]):hover {
     --tag-bg: transparent;
   }
   :scope[tone="outline"][variant="info"] {
-    --tag-fg:     var(--a-info-text);
-    --tag-border: var(--a-info-border);
+    --tag-fg:     var(--md-sys-color-info-on-surface);
+    --tag-border: var(--md-sys-color-info-outline);
   }
   :scope[tone="outline"][variant="success"] {
-    --tag-fg:     var(--a-success-text);
-    --tag-border: var(--a-success-border);
+    --tag-fg:     var(--md-sys-color-success-on-surface);
+    --tag-border: var(--md-sys-color-success-outline);
   }
   :scope[tone="outline"][variant="warning"] {
-    --tag-fg:     var(--a-warning-text);
-    --tag-border: var(--a-warning-border);
+    --tag-fg:     var(--md-sys-color-warning-on-surface);
+    --tag-border: var(--md-sys-color-warning-outline);
   }
   :scope[tone="outline"][variant="danger"] {
-    --tag-fg:     var(--a-danger-text);
-    --tag-border: var(--a-danger-border);
+    --tag-fg:     var(--md-sys-color-danger-on-surface);
+    --tag-border: var(--md-sys-color-danger-outline);
   }
   /* Outline on neutral (no family) — fg-muted text + subtle border. */
   :scope[tone="outline"]:not([variant="info"]):not([variant="success"]):not([variant="warning"]):not([variant="danger"]) {
     --tag-fg:     var(--a-fg-muted);
-    --tag-border: var(--a-border);
+    --tag-border: var(--md-sys-color-neutral-outline);
   }
 
   /* Size handled by universal [size] attribute system. */

package/components/tag/tag.test.js

@@ -50,50 +50,43 @@ describe('tag-ui — content: attr(text) gating', () => {
 // ── Tone defaults (solid by default for families; muted as opt-out) ──
 //
 // Default tone is `solid` for family variants — the base `:scope[variant=…]`
-// rules use the saturated-fill pair `--a-{family}-bg` + `--a-{family}-fg`
-// (the chip IS the state). `[tone="muted"]` opts back into the canonical
-// muted pair `--a-{family}-muted` + `--a-{family}-text` (same look as
+// rules pair the saturated `--a-{family}-bg` fill with the palette's own
+// Material on-color `--md-sys-color-{family}-on-{family}` (the chip IS the
+// state). `[tone="muted"]` opts back into the Material container pair
+// `--md-sys-color-{family}-container` + `-on-surface` (same look as
 // <badge-ui>'s default). The `default` (no-family) variant stays quiet
-// chrome unless `[tone="solid"]` is set explicitly (then it inverts
-// to fg/bg for a high-contrast neutral stamp).
+// chrome unless `[tone="solid"]` is set explicitly (then it inverts to a
+// high-contrast neutral stamp). Token names updated for the Material
+// static-token migration (material-color-bridge-contract.md, 2026-07-15).
 
 describe('tag-ui — variant defaults to solid fill', () => {
   it.each([
     ['info'],
     ['success'],
+    ['warning'],
     ['danger'],
-  ])('[variant="%s"] base rule uses --a-{family}-bg + --a-{family}-fg', (family) => {
+  ])('[variant="%s"] base rule uses --a-{family}-bg + --md-sys-color-{family}-on-{family}', (family) => {
     const block = new RegExp(
       `:scope\\[variant="${family}"\\]\\s*\\{[^}]*` +
       `--tag-bg:\\s*var\\(--a-${family}-bg\\)[^}]*` +
-      `--tag-fg:\\s*var\\(--a-${family}-fg\\)`,
+      `--tag-fg:\\s*var\\(--md-sys-color-${family}-on-${family}\\)`,
       's'
     );
     expect(TAG_CSS).toMatch(block);
   });
-
-  it('[variant="warning"] uses the canonical --a-warning-bg + --a-warning-fg pair', () => {
-    // v0.6.36 token-system fix: --a-warning-bg now redirects to
-    // --a-warning-20-tint at the L3 layer (semantics.css), so consumers
-    // can pair `-bg` + `-fg` cleanly without local overrides. The pair
-    // resolves to bright-amber-bg + dark-brown-text in both schemes.
-    expect(TAG_CSS).toMatch(
-      /:scope\[variant="warning"\]\s*\{[^}]*--tag-bg:\s*var\(--a-warning-bg\)[^}]*--tag-fg:\s*var\(--a-warning-fg\)/s
-    );
-  });
 });
 
-describe('tag-ui — [tone="muted"] opts out to canonical muted pair', () => {
+describe('tag-ui — [tone="muted"] opts out to the Material container pair', () => {
   it.each([
     ['info'],
     ['success'],
     ['warning'],
     ['danger'],
-  ])('[tone="muted"][variant="%s"] uses --a-{family}-muted + --a-{family}-text', (family) => {
+  ])('[tone="muted"][variant="%s"] uses -container + -on-surface', (family) => {
     const block = new RegExp(
       `:scope\\[tone="muted"\\]\\[variant="${family}"\\]\\s*\\{[^}]*` +
-      `--tag-bg:\\s*var\\(--a-${family}-muted\\)[^}]*` +
-      `--tag-fg:\\s*var\\(--a-${family}-text\\)`,
+      `--tag-bg:\\s*var\\(--md-sys-color-${family}-container\\)[^}]*` +
+      `--tag-fg:\\s*var\\(--md-sys-color-${family}-on-surface\\)`,
       's'
     );
     expect(TAG_CSS).toMatch(block);
@@ -101,15 +94,15 @@ describe('tag-ui — [tone="muted"] opts out to canonical muted pair', () => {
 });
 
 describe('tag-ui — neutral default + explicit solid stamp', () => {
-  it('[variant="default"] stays quiet chrome (--a-bg-muted + --a-fg)', () => {
+  it('[variant="default"] stays quiet chrome (--a-bg-muted + neutral on-surface)', () => {
     expect(TAG_CSS).toMatch(
-      /:scope\[variant="default"\]\s*\{[^}]*--tag-bg:\s*var\(--a-bg-muted\)[^}]*--tag-fg:\s*var\(--a-fg\)/s
+      /:scope\[variant="default"\]\s*\{[^}]*--tag-bg:\s*var\(--a-bg-muted\)[^}]*--tag-fg:\s*var\(--md-sys-color-neutral-on-surface\)/s
     );
   });
 
-  it('[tone="solid"] without a family inverts to fg/bg high-contrast stamp', () => {
+  it('[tone="solid"] without a family inverts to a high-contrast neutral stamp', () => {
     expect(TAG_CSS).toMatch(
-      /:scope\[tone="solid"\]:not\(\[variant="info"\]\)[\s\S]*?--tag-bg:\s*var\(--a-fg\)[\s\S]*?--tag-fg:\s*var\(--a-bg\)/
+      /:scope\[tone="solid"\]:not\(\[variant="info"\]\)[\s\S]*?--tag-bg:\s*var\(--md-sys-color-neutral-on-surface\)[\s\S]*?--tag-fg:\s*var\(--md-sys-color-neutral-background\)/
     );
   });
 });
@@ -129,16 +122,16 @@ describe('tag-ui — [tone="outline"] strips fill + colors border', () => {
   ])('[tone="outline"][variant="%s"] colors fg + border per family', (family) => {
     const block = new RegExp(
       `:scope\\[tone="outline"\\]\\[variant="${family}"\\]\\s*\\{[^}]*` +
-      `--tag-fg:\\s*var\\(--a-${family}-text\\)[^}]*` +
-      `--tag-border:\\s*var\\(--a-${family}-border\\)`,
+      `--tag-fg:\\s*var\\(--md-sys-color-${family}-on-surface\\)[^}]*` +
+      `--tag-border:\\s*var\\(--md-sys-color-${family}-outline\\)`,
       's'
     );
     expect(TAG_CSS).toMatch(block);
   });
 
-  it('[tone="outline"] on neutral uses --a-fg-muted text + --a-border ring', () => {
+  it('[tone="outline"] on neutral uses --a-fg-muted text + neutral outline ring', () => {
     expect(TAG_CSS).toMatch(
-      /:scope\[tone="outline"\]:not\(\[variant="info"\]\)[\s\S]*?--tag-fg:\s*var\(--a-fg-muted\)[\s\S]*?--tag-border:\s*var\(--a-border\)/
+      /:scope\[tone="outline"\]:not\(\[variant="info"\]\)[\s\S]*?--tag-fg:\s*var\(--a-fg-muted\)[\s\S]*?--tag-border:\s*var\(--md-sys-color-neutral-outline\)/
     );
   });
 });

package/components/tags-input/tags-input.a2ui.json

@@ -227,7 +227,7 @@
     ],
     "slots": {
       "chip": {
-        "description": "Custom chip template — receives `{value, index}` per token.\nWhen absent, each token renders as a default\n`<tag-ui removable text=\"<value>\">`."
+        "description": "Custom per-token chip template (TKT-0023). Provide a single\n`<template slot=\"chip\">` child; it's cloned once per committed\ntoken, with `{{value}}` / `{{index}}` substituted into every text\nnode and attribute value in the clone (e.g.\n`<tag-ui removable text=\"{{value}}\" title=\"Item #{{index}}\">`).\nThe template's first element child is the reconcile unit — data-*\nbookkeeping attrs land on it, so removal / re-render still track\nby position the same way the default chip does. When absent, or\nwhen the template has no element content (malformed), each token\nrenders as the default `<tag-ui removable text=\"<value>\">`.\nReadonly/disabled toggling of the built-in `removable` affordance\nonly applies to the default chip — a custom template always owns\nits own removability, independent of the host's readonly/disabled\nstate."
       }
     },
     "states": [
@@ -261,7 +261,7 @@
         "name": "disabled"
       },
       {
-        "description": "Read-only; chips render without remove affordance.",
+        "description": "Read-only; default chips render without remove affordance (a\ncustom `chip` template owns its own removability and is\nunaffected).",
         "attribute": "readonly",
         "name": "readonly"
       }

package/components/tags-input/tags-input.class.js

@@ -238,6 +238,11 @@ export class UITagsInput extends UIFormElement {
       this.#bindListeners();
       return;
     }
+    // Capture any author-declared chip template (TKT-0023) BEFORE the
+    // wholesale `innerHTML` replacement below, which would otherwise
+    // discard it — the captured reference stays valid (just detached)
+    // across the replacement and gets re-appended after.
+    const chipTemplate = this.querySelector(':scope > template[slot="chip"]');
     const suggestId = `${this.#instanceId}-suggestions`;
     const inputId = `${this.#instanceId}-input`;
     this.innerHTML = `
@@ -257,6 +262,7 @@ export class UITagsInput extends UIFormElement {
       </span>
       <div data-suggestions id="${suggestId}" role="listbox" hidden></div>
     `;
+    if (chipTemplate) this.appendChild(chipTemplate);
     this.#queryRefs();
     this.#bindListeners();
   }
@@ -299,29 +305,38 @@ export class UITagsInput extends UIFormElement {
   }
 
   // ── Render chips ──
+  //
+  // SPEC-042 §chip slot (TKT-0023): an author-provided
+  // `<template slot="chip">` overrides the default `<tag-ui>` render, one
+  // clone per token. `{{value}}` / `{{index}}` are substituted into every
+  // text node and attribute value in the cloned subtree — declarative, no
+  // JS required, so it works from static markup and a2ui-generated pages.
 
   #renderChips() {
     if (!this.#chipList) return;
-    // Reconcile in place: existing chips that still match keep their nodes
-    // (so the user's :hover / :focus / animation states don't flicker on
-    // each typed-character render); excess chips get dropped; new chips
-    // append at the end.
-    const existing = Array.from(this.#chipList.querySelectorAll(':scope > tag-ui'));
+    const template = this.querySelector(':scope > template[slot="chip"]');
+    const mode = template ? 'custom' : 'default';
+    // Reconcile in place: an existing chip at a position keeps its node
+    // when its value + mode haven't changed (so :hover / :focus / animation
+    // states don't flicker on each typed-character render); a changed or
+    // absent position gets a fresh node; excess chips drop; new ones append.
+    const existing = Array.from(this.#chipList.children);
     for (let i = 0; i < this.#value.length; i++) {
       const v = this.#value[i];
-      let chip = existing[i];
-      if (!chip) {
-        chip = document.createElement('tag-ui');
-        chip.setAttribute('role', 'listitem');
-        this.#chipList.appendChild(chip);
-      }
-      chip.setAttribute('text', v);
-      if (this.readonly || this.disabled) {
-        chip.removeAttribute('removable');
-      } else {
-        chip.setAttribute('removable', '');
+      const current = existing[i];
+      const reusable = current && current.dataset.chipMode === mode && current.dataset.chipValue === v;
+      if (reusable) {
+        current.setAttribute('data-index', String(i));
+        if (!template) {
+          if (this.readonly || this.disabled) current.removeAttribute('removable');
+          else current.setAttribute('removable', '');
+        }
+        continue;
       }
-      chip.setAttribute('data-index', String(i));
+      const fresh = template ? this.#buildCustomChip(template, v, i) : this.#buildDefaultChip(v, i);
+      if (current) this.#chipList.replaceChild(fresh, current);
+      else this.#chipList.appendChild(fresh);
+      existing[i] = fresh;
     }
     // Drop overflow chips.
     for (let i = this.#value.length; i < existing.length; i++) {
@@ -329,6 +344,58 @@ export class UITagsInput extends UIFormElement {
     }
   }
 
+  #buildDefaultChip(value, index) {
+    const chip = document.createElement('tag-ui');
+    chip.setAttribute('role', 'listitem');
+    chip.setAttribute('text', value);
+    if (!(this.readonly || this.disabled)) chip.setAttribute('removable', '');
+    chip.setAttribute('data-index', String(index));
+    chip.dataset.chipMode = 'default';
+    chip.dataset.chipValue = value;
+    return chip;
+  }
+
+  #buildCustomChip(template, value, index) {
+    const frag = template.content.cloneNode(true);
+    this.#substitutePlaceholders(frag, value, index);
+    // Reconcile unit = first element child (ignores incidental whitespace
+    // text nodes from formatted template markup).
+    const root = frag.firstElementChild;
+    if (!root) return this.#buildDefaultChip(value, index); // malformed template — degrade to default rather than render nothing
+    root.setAttribute('role', 'listitem');
+    root.setAttribute('data-index', String(index));
+    root.dataset.chipMode = 'custom';
+    root.dataset.chipValue = value;
+    return root;
+  }
+
+  /** Replace `{{value}}` / `{{index}}` in every text node + attribute of
+   *  `root` (a cloned template fragment), in place. Single-pass regex —
+   *  chained `.replaceAll()` calls would let a token whose literal text is
+   *  `{{index}}` get re-matched by the second pass after the first pass
+   *  substitutes it in. */
+  #substitutePlaceholders(root, value, index) {
+    const idxStr = String(index);
+    const substitute = (str) =>
+      str.replace(/\{\{value\}\}|\{\{index\}\}/g, (m) => (m === '{{value}}' ? value : idxStr));
+    const walker = document.createTreeWalker(root, NodeFilter.SHOW_ELEMENT | NodeFilter.SHOW_TEXT);
+    let node;
+    // eslint-disable-next-line no-cond-assign
+    while ((node = walker.nextNode())) {
+      if (node.nodeType === Node.TEXT_NODE) {
+        if (node.data.includes('{{')) {
+          node.data = substitute(node.data);
+        }
+      } else {
+        for (const attr of node.attributes) {
+          if (attr.value.includes('{{')) {
+            attr.value = substitute(attr.value);
+          }
+        }
+      }
+    }
+  }
+
   #renderSuggestions() {
     if (!this.#suggestEl) return;
     const typed = this.#inputEl ? (this.#inputEl.textContent || '').trim().toLowerCase() : '';
@@ -516,7 +583,12 @@ export class UITagsInput extends UIFormElement {
   }
 
   #handleChipRemove(e) {
-    const chip = e.target.closest('tag-ui[data-index]');
+    // `[data-index]` (not `tag-ui[data-index]`) — a chip-slot template
+    // (TKT-0023) may wrap its own `<tag-ui removable>` inside an arbitrary
+    // root element; `data-index` is stamped on whichever node is the
+    // reconcile unit for that position (see `#buildCustomChip`), so
+    // `closest()` finds the right ancestor regardless of its tag name.
+    const chip = e.target.closest('[data-index]');
     if (!chip) return;
     // tag-ui's `remove` CustomEvent bubbles SYNCHRONOUSLY before tag-ui's
     // own `this.remove()` runs (see tag/tag.class.js:59-63 — dispatch then
@@ -525,8 +597,9 @@ export class UITagsInput extends UIFormElement {
     // positional reconcile in `#renderChips()` mutates the WRONG chip's
     // text — visually erasing one or more adjacent chips. Pre-emptively
     // detach the source chip ourselves so the DOM matches `#value` before
-    // render. tag-ui's later `this.remove()` is a harmless no-op on an
-    // already-detached node.
+    // render. tag-ui's later `this.remove()` is a harmless no-op — either
+    // on an already-detached node (default chip == the tag-ui itself), or
+    // on a nested tag-ui whose ancestor `chip` root was just detached.
     e.stopPropagation();
     const idx = Number(chip.dataset.index);
     if (!Number.isInteger(idx)) return;

package/components/tags-input/tags-input.css

@@ -25,10 +25,10 @@
     --tags-input-easing:          var(--a-easing);
 
     /* ── Chip overrides — cascaded into nested <tag-ui> ── */
-    --tags-input-chip-bg-invalid: var(--a-danger-muted);
+    --tags-input-chip-bg-invalid: var(--md-sys-color-danger-container);
 
     /* ── Suggestions popover ── */
-    --tags-input-suggestions-bg:        var(--a-canvas-bright);
+    --tags-input-suggestions-bg:        var(--md-sys-color-neutral-surface-bright);
     --tags-input-suggestions-border:    var(--a-ui-border);
     --tags-input-suggestions-radius:    var(--a-radius);
     --tags-input-suggestions-shadow:    var(--a-shadow-lg);
@@ -169,7 +169,7 @@ tags-input-ui [data-suggestions] {
   padding: var(--a-space-1);
   border: 1px solid var(--a-ui-border);
   border-radius: var(--a-radius);
-  background: var(--a-canvas-bright);
+  background: var(--md-sys-color-neutral-surface-bright);
   box-shadow: var(--a-shadow-lg);
   font-family: inherit;
   font-size: var(--a-ui-size);

package/components/tags-input/tags-input.test.js

@@ -320,6 +320,115 @@ describe('tags-input-ui — disabled / readonly / form', () => {
   });
 });
 
+describe('tags-input-ui — chip slot template (TKT-0023)', () => {
+  beforeEach(() => { document.body.innerHTML = ''; });
+
+  it('with no template, renders the default <tag-ui removable text>', async () => {
+    const el = mount('<tags-input-ui value=\'["a"]\'></tags-input-ui>');
+    await tick();
+    const chip = el.querySelector(':scope > [data-chip-list] > *');
+    expect(chip.tagName.toLowerCase()).toBe('tag-ui');
+    expect(chip.getAttribute('text')).toBe('a');
+    expect(chip.hasAttribute('removable')).toBe(true);
+  });
+
+  it('an author <template slot="chip"> overrides the default render, substituting {{value}}/{{index}}', async () => {
+    const el = mount(`
+      <tags-input-ui value='["alpha","beta"]'>
+        <template slot="chip"><tag-ui removable text="{{value}}" title="Item #{{index}}"></tag-ui></template>
+      </tags-input-ui>
+    `);
+    await tick();
+    const chips = el.querySelectorAll(':scope > [data-chip-list] > *');
+    expect(chips).toHaveLength(2);
+    expect(chips[0].getAttribute('text')).toBe('alpha');
+    expect(chips[0].getAttribute('title')).toBe('Item #0');
+    expect(chips[1].getAttribute('text')).toBe('beta');
+    expect(chips[1].getAttribute('title')).toBe('Item #1');
+  });
+
+  it('the chip template survives the first-connect shell stamp (not wiped by innerHTML replacement)', async () => {
+    const el = mount(`
+      <tags-input-ui value='["x"]'>
+        <template slot="chip"><span class="custom">{{value}}</span></template>
+      </tags-input-ui>
+    `);
+    await tick();
+    expect(el.querySelector(':scope > template[slot="chip"]')).toBeTruthy();
+    const chip = el.querySelector(':scope > [data-chip-list] > .custom');
+    expect(chip?.textContent).toBe('x');
+  });
+
+  it('substitutes {{value}}/{{index}} in attribute values, not just text content', async () => {
+    const el = mount(`
+      <tags-input-ui value='["a","b"]'>
+        <template slot="chip"><span data-slot-value="{{value}}" data-slot-index="{{index}}">{{value}}</span></template>
+      </tags-input-ui>
+    `);
+    await tick();
+    const chips = el.querySelectorAll(':scope > [data-chip-list] > span');
+    expect(chips[0].dataset.slotValue).toBe('a');
+    expect(chips[0].dataset.slotIndex).toBe('0');
+    expect(chips[1].dataset.slotValue).toBe('b');
+    expect(chips[1].dataset.slotIndex).toBe('1');
+  });
+
+  it('reconciles by position: adding a token appends without recreating existing custom chips', async () => {
+    const el = mount(`
+      <tags-input-ui value='["a"]'>
+        <template slot="chip"><span>{{value}}</span></template>
+      </tags-input-ui>
+    `);
+    await tick();
+    const first = el.querySelector(':scope > [data-chip-list] > span');
+    el.addToken('b');
+    await tick();
+    const chips = el.querySelectorAll(':scope > [data-chip-list] > span');
+    expect(chips).toHaveLength(2);
+    expect(chips[0]).toBe(first); // unchanged position — same node, no flicker
+    expect(chips[1].textContent).toBe('b');
+  });
+
+  it('a custom chip participates in removal via a bubbling `remove` event from a nested tag-ui', async () => {
+    const el = mount(`
+      <tags-input-ui value='["a","b"]'>
+        <template slot="chip"><span class="wrap"><tag-ui removable text="{{value}}"></tag-ui></span></template>
+      </tags-input-ui>
+    `);
+    await tick();
+    const nestedTag = el.querySelector(':scope > [data-chip-list] .wrap tag-ui[text="a"]');
+    nestedTag.dispatchEvent(new CustomEvent('remove', { bubbles: true }));
+    await tick();
+    expect(el.value).toEqual(['b']);
+  });
+
+  it('a malformed template (no element content) degrades to the default chip rather than rendering nothing', async () => {
+    const el = mount(`
+      <tags-input-ui value='["a"]'>
+        <template slot="chip">   </template>
+      </tags-input-ui>
+    `);
+    await tick();
+    const chip = el.querySelector(':scope > [data-chip-list] > *');
+    expect(chip.tagName.toLowerCase()).toBe('tag-ui');
+    expect(chip.getAttribute('text')).toBe('a');
+  });
+
+  it('a token literally equal to "{{index}}" is not clobbered by the index substitution pass', async () => {
+    const el = mount(`
+      <tags-input-ui value='["{{index}}","real"]'>
+        <template slot="chip"><span data-slot-index="{{index}}">{{value}}</span></template>
+      </tags-input-ui>
+    `);
+    await tick();
+    const chips = el.querySelectorAll(':scope > [data-chip-list] > span');
+    expect(chips[0].textContent).toBe('{{index}}');
+    expect(chips[0].dataset.slotIndex).toBe('0');
+    expect(chips[1].textContent).toBe('real');
+    expect(chips[1].dataset.slotIndex).toBe('1');
+  });
+});
+
 describe('tags-input-ui — change event', () => {
   beforeEach(() => { document.body.innerHTML = ''; });
 

package/components/tags-input/tags-input.yaml

@@ -186,9 +186,20 @@ events:
 slots:
   chip:
     description: |-
-      Custom chip template — receives `{value, index}` per token.
-      When absent, each token renders as a default
-      `<tag-ui removable text="<value>">`.
+      Custom per-token chip template (TKT-0023). Provide a single
+      `<template slot="chip">` child; it's cloned once per committed
+      token, with `{{value}}` / `{{index}}` substituted into every text
+      node and attribute value in the clone (e.g.
+      `<tag-ui removable text="{{value}}" title="Item #{{index}}">`).
+      The template's first element child is the reconcile unit — data-*
+      bookkeeping attrs land on it, so removal / re-render still track
+      by position the same way the default chip does. When absent, or
+      when the template has no element content (malformed), each token
+      renders as the default `<tag-ui removable text="<value>">`.
+      Readonly/disabled toggling of the built-in `removable` affordance
+      only applies to the default chip — a custom template always owns
+      its own removability, independent of the host's readonly/disabled
+      state.
 states:
   - name: idle
     description: No tokens; no typed text.
@@ -208,7 +219,10 @@ states:
     description: Non-interactive; dimmed.
     attribute: disabled
   - name: readonly
-    description: Read-only; chips render without remove affordance.
+    description: |-
+      Read-only; default chips render without remove affordance (a
+      custom `chip` template owns its own removability and is
+      unaffected).
     attribute: readonly
 traits: []
 tokens:

package/components/text/text.css

@@ -8,7 +8,7 @@
     --text-leading:   var(--a-body-leading);
     --text-tracking:  var(--a-body-tracking);
     --text-case:      var(--a-body-case);
-    --text-color:     var(--a-fg);
+    --text-color:     var(--md-sys-color-neutral-on-surface);
     --text-color-strong:     var(--a-fg-strong);
   }
 
@@ -38,7 +38,7 @@
   }
 
   /* ── Variants ── */
-  :scope[variant="body"]       { --text-family: var(--a-body-family);    --text-weight: var(--a-body-weight);    --text-size: var(--a-body-size);    --text-leading: var(--a-body-leading);    --text-tracking: var(--a-body-tracking);    --text-case: var(--a-body-case);    --text-color: var(--a-fg); }
+  :scope[variant="body"]       { --text-family: var(--a-body-family);    --text-weight: var(--a-body-weight);    --text-size: var(--a-body-size);    --text-leading: var(--a-body-leading);    --text-tracking: var(--a-body-tracking);    --text-case: var(--a-body-case);    --text-color: var(--md-sys-color-neutral-on-surface); }
   :scope[variant="display"]    { --text-family: var(--a-display-family); --text-weight: var(--a-display-weight); --text-size: var(--a-display-size); --text-leading: var(--a-display-leading); --text-tracking: var(--a-display-tracking); --text-case: var(--a-display-case); --text-color: var(--a-display-color); }
   :scope[variant="title"]      { --text-family: var(--a-title-family);   --text-weight: var(--a-title-weight);   --text-size: var(--a-title-size);   --text-leading: var(--a-title-leading);   --text-tracking: var(--a-title-tracking);   --text-case: var(--a-title-case);   --text-color: var(--a-title-color); }
   :scope[variant="heading"]    { --text-family: var(--a-heading-family); --text-weight: var(--a-heading-weight); --text-size: var(--a-heading-size); --text-leading: var(--a-heading-leading); --text-tracking: var(--a-heading-tracking); --text-case: var(--a-heading-case); --text-color: var(--a-heading-color); }
@@ -78,10 +78,10 @@
 
   /* color — default | subtle | strong | accent | danger | success | warning
      (no value = variant default; "default" is an explicit reset). */
-  :scope[color="default"] { --text-color: var(--a-fg); }
+  :scope[color="default"] { --text-color: var(--md-sys-color-neutral-on-surface); }
   :scope[color="subtle"]  { --text-color: var(--a-fg-muted); }
   :scope[color="strong"]  { --text-color: var(--a-fg-strong); }
-  :scope[color="accent"]  { --text-color: var(--a-accent); }
+  :scope[color="accent"]  { --text-color: var(--md-sys-color-primary); }
   :scope[color="danger"]  { --text-color: var(--a-danger-bg); }
   :scope[color="success"] { --text-color: var(--a-success-bg); }
   :scope[color="warning"] { --text-color: var(--a-warning-bg); }