@adia-ai/web-components 0.6.16 → 0.6.18

package/CHANGELOG.md

@@ -1,5 +1,95 @@
 # Changelog — @adia-ai/web-components
 
+## [0.6.18] — 2026-05-21
+
+### Added — `[data-scheme]` attribute on `toggle-scheme-ui` (FB-14)
+
+- **`toggle-scheme-ui` now writes the `[data-scheme]` attribute** on the target
+  element alongside the existing `color-scheme` inline style. `styles/themes.css`
+  selects on `[data-scheme="light|dark|system"]`; consumer CSS patterned after
+  it never fired because the component wrote only the inline style.
+  `#writeTarget()` sets the attribute, `#clearTargetOverride()` removes it —
+  paired with the style so the two never diverge. Non-breaking: consumers
+  relying on the `color-scheme` style alone are unaffected. (~6 LOC `class.js`.)
+
+### Added — `button-ui` text/icon symbol-duplication warning (FB-15)
+
+- **`button-ui` emits a one-shot `console.warn`** when `text=` begins with a
+  symbol that `icon=` already renders — e.g. `text="+ New Item" icon="plus"`
+  renders a doubled `+`. Covers the high-frequency `plus` / `minus` / `x` /
+  `check` / `arrow-*` collisions. Warning-only (WeakSet-guarded, GC-friendly);
+  the button still renders and `text=` is never mutated. `button.yaml` gains the
+  matching `anti_patterns` entry so A2UI validators flag it at generation time.
+  (~36 LOC `class.js` + `button.yaml` + a2ui regen.)
+
+### Added — Loading state as first-class citizen (FB-12 P2)
+
+- **`stat-ui loading` prop.** New `loading: Boolean` (reflect: true). When set,
+  the value + change slots render `<skeleton-ui>` shimmer placeholders and the
+  host gets `aria-busy="true"`. Label and icon are preserved as static
+  metadata. Toggle off when data arrives — slot textContent setters restore
+  cleanly. `composes:` now includes `skeleton-ui`. (~28 LOC `stat.js` + 9 LOC
+  `stat.yaml` + a2ui chunk regen.)
+- **`table-ui` skeleton rows.** `loading=true` now renders N ghost
+  `[data-skeleton-row]` rows (N = `paginate` capped at 8, else 5) instead of
+  the legacy `<progress-ui>` overlay. Header + columns stay intact so layout
+  is preserved while data fetches. Cell widths cycle 60/80/70/50/90% so rows
+  read as natural data. Host gets `aria-busy="true"`. `composes:` now
+  includes `skeleton-ui`. Fixes yaml-vs-impl drift: the yaml description
+  always promised "skeleton rows" since the initial cut; the impl only
+  shipped the overlay. (~42 LOC `class.js` rewrite of `#renderOverlays` +
+  CSS rewrite of the `:scope[loading] [data-body]` rule.)
+
+### Added — `text-ui` overlay attributes (FB-10)
+
+- **`size` / `color` / `weight` / `text-align` props on `text-ui`.** Pre-v0.6.18
+  the skill documented an overlay API (`<text-ui color="subtle" size="sm"
+  weight="semibold" text-align="center">`) but the substrate ignored those
+  attributes — they were valid HTML but no-op CSS. v0.6.18 implements them
+  as `:scope[attr="value"]` rules that override the `--text-*` CSS vars set
+  by `[variant]`. Enums:
+  - `size` — `sm | md | lg` → `--a-body-sm | --a-body-md | --a-body-lg`
+  - `color` — `default | subtle | strong | accent | danger | success | warning`
+  - `weight` — `regular | medium | semibold | bold`
+  - `text-align` — `start | center | end | justify` (sets `text-align` directly;
+    only takes effect when text-ui is block-like)
+  Permissive: unknown values are no-ops (variant default wins). Substrate now
+  matches the skill's already-documented intent.
+
+### Tests
+
+- 9 new tests in `stat.test.js` (FB-12 P2 #1 coverage).
+- 9 new tests in `table.test.js` (FB-12 P2 #3 coverage; uses RAF-based settle
+  helper because table-ui renders via `requestAnimationFrame`, not microtasks).
+- 18 new tests in `text.test.js` for the overlay attributes (attribute
+  reflection × 18 values + CSS rule presence × 18 + 3 enum-vs-CSS
+  consistency checks + permissive-fallback smoke).
+- **Total: 99/99 passing** (text 82 + stat 9 + table 9 — the existing text
+  variant tests still pass alongside the new overlay tests).
+
+### Deferred (see `outbox/FEEDBACK-12--...--followup.md`)
+
+- **`chart-ui` `loading` prop (FB-12 P2 #2)** — design decision upstream.
+  `chart.examples.html` documents intentional "compose loading wrappers"
+  pattern; pivoting in a patch cut would silently lock in a direction.
+- **`skeleton-ui` `variant` reconcile (FB-12 P3)** — two valid dispositions
+  (purge a2ui corpus refs / implement prop) need maintainer signoff.
+
+### No-op (FB-11 P3 substrate)
+
+- Verified that `import { UIFeed } from '@adia-ai/web-components/components/feed/class'`
+  resolves correctly via the existing `./components/*/class` exports pattern.
+  No package.json change needed. The original ticket flagged
+  `/components/feed/feed.js` as failing — confirmed (Node exports wildcards
+  can't substitute `*` across multiple path segments) but the `/class`
+  shorthand is the canonical path and works today. Skill v2.11.0 documents
+  this.
+
+## [0.6.17] — 2026-05-21
+
+### Maintenance
+- **Lockstep version bump only.** No source changes in this package; bumped to maintain the 9-package version coherence enforced by `scripts/release/check-lockstep.mjs`. Substantive v0.6.17 work shipped in `@adia-ai/web-modules` — collapsed-sidebar rules grew a forgiving fallback block for vanilla HTML consumers (`<button class="nav-item">`, `[slot="heading"]`) so text labels don't overflow the 48px rail. See `packages/web-modules/CHANGELOG.md#0617--2026-05-21` for details.
+
 ## [0.6.16] — 2026-05-21
 
 ### Maintenance

package/components/button/button.a2ui.json

@@ -96,7 +96,14 @@
   ],
   "unevaluatedProperties": false,
   "x-adiaui": {
-    "anti_patterns": [],
+    "anti_patterns": [
+      {
+        "description": "Beginning text= with a symbol that icon= already renders. icon=\"plus\" paints a Phosphor \"+\" glyph; text=\"+ New Item\" then renders the literal \"+\" too, so the symbol appears twice ([+ icon] [+ New Item]).",
+        "right": "<button-ui text=\"New Claim\" icon=\"plus\" variant=\"primary\"></button-ui>\n",
+        "rule": "Do not repeat the icon's glyph in text=. The icon provides the symbol; text= carries only the words. Applies to plus / minus / x / check / arrow icons.",
+        "wrong": "<button-ui text=\"+ New Claim\" icon=\"plus\" variant=\"primary\"></button-ui>\n"
+      }
+    ],
     "category": "action",
     "composes": [
       "icon-ui"

package/components/button/button.yaml

@@ -140,7 +140,19 @@ tokens:
     description: Inherited multiplier for padding
 a2ui:
   rules: []
-anti_patterns: []
+anti_patterns:
+  - description: >-
+      Beginning text= with a symbol that icon= already renders. icon="plus"
+      paints a Phosphor "+" glyph; text="+ New Item" then renders the literal
+      "+" too, so the symbol appears twice ([+ icon] [+ New Item]).
+    wrong: |
+      <button-ui text="+ New Claim" icon="plus" variant="primary"></button-ui>
+    right: |
+      <button-ui text="New Claim" icon="plus" variant="primary"></button-ui>
+    rule: >-
+      Do not repeat the icon's glyph in text=. The icon provides the symbol;
+      text= carries only the words. Applies to plus / minus / x / check /
+      arrow icons.
 examples: []
 keywords: []
 synonyms: {}

package/components/button/class.js

@@ -16,6 +16,19 @@
 import { UIElement, signal, html } from '../../core/element.js';
 import { getIcon } from '../../core/icons.js';
 
+// FEEDBACK-15: highest-frequency icon ⇄ text-prefix collisions. When an
+// author writes e.g. text="+ New Item" icon="plus", the Phosphor glyph and
+// the literal symbol both render — a doubled "+". Map is intentionally a
+// curated high-frequency set, not exhaustive; the warning is non-breaking.
+const ICON_TEXT_PREFIXES = {
+  plus:          ['+', '＋'],
+  minus:         ['-', '−', '–'],
+  x:             ['×', 'x ', 'X '],
+  check:         ['✓', '✔'],
+  'arrow-right': ['→', '>'],
+  'arrow-left':  ['←', '<'],
+};
+
 export class UIButton extends UIElement {
   static properties = {
     text:     { type: String,  default: '', reflect: true },
@@ -57,6 +70,26 @@ export class UIButton extends UIElement {
       }
     }
 
+    // FEEDBACK-15: warn when text= begins with a symbol that icon= already
+    // renders (e.g. text="+ New Claim" icon="plus" → a doubled "+"). One-shot
+    // per element via WeakSet; warning-only — the button still renders. The
+    // text value is never mutated (text="+1" with no icon is a valid label).
+    if (this.icon && this.text) {
+      const prefixes = ICON_TEXT_PREFIXES[this.icon];
+      if (prefixes && prefixes.some((p) => this.text.startsWith(p))) {
+        if (!UIButton.#dupSymbolWarned.has(this)) {
+          UIButton.#dupSymbolWarned.add(this);
+          // eslint-disable-next-line no-console
+          console.warn(
+            `[button-ui] text="${this.text}" begins with a symbol that ` +
+            `icon="${this.icon}" already renders — the glyph appears twice. ` +
+            `Drop the leading symbol from text= (the icon provides it).`,
+            this,
+          );
+        }
+      }
+    }
+
     // §184 (v0.5.5, FEEDBACK-08 §8): icon-only a11y warning + title→aria-label
     // auto-derive. Two complementary mechanisms (consumer chooses):
     //   (a) When [title="Undo"] is set on an icon-only button without an
@@ -97,6 +130,9 @@ export class UIButton extends UIElement {
   // is gone the entry is collected.
   static #a11yWarned = new WeakSet();
 
+  // FEEDBACK-15: one-shot set for the text/icon symbol-duplication warning.
+  static #dupSymbolWarned = new WeakSet();
+
   #onClick = (e) => {
     if (this.disabled) { e.stopPropagation(); return; }
     if (this.type === 'submit') {

package/components/stat/stat.a2ui.json

@@ -31,6 +31,11 @@
       "type": "string",
       "default": ""
     },
+    "loading": {
+      "description": "Renders skeleton-ui shimmer placeholders in place of the value and change slots while data is fetching. Sets aria-busy=\"true\" on the host. Label and icon are preserved (they're static metadata, not fetched data). Toggle back to false when data arrives.",
+      "type": "boolean",
+      "default": false
+    },
     "trend": {
       "description": "Trend direction or narrative subtitle. Canonical values color the change badge (up=success, down=danger, neutral/flat=muted); any other string renders as caption-style text under the primary value.",
       "type": "string",
@@ -50,7 +55,8 @@
     "anti_patterns": [],
     "category": "display",
     "composes": [
-      "icon-ui"
+      "icon-ui",
+      "skeleton-ui"
     ],
     "events": {},
     "examples": [

package/components/stat/stat.d.ts

@@ -19,6 +19,8 @@ export class UIStat extends UIElement {
   icon: string;
   /** Eyebrow label describing the metric */
   label: string;
+  /** Renders skeleton-ui shimmer placeholders in place of the value and change slots while data is fetching. Sets aria-busy="true" on the host. Label and icon are preserved (they're static metadata, not fetched data). Toggle back to false when data arrives. */
+  loading: boolean;
   /** Trend direction or narrative subtitle. Canonical values color the change badge (up=success, down=danger, neutral/flat=muted); any other string renders as caption-style text under the primary value. */
   trend: string;
   /** The primary metric value to display */

package/components/stat/stat.js

@@ -12,11 +12,12 @@ import { UIElement } from '../../core/element.js';
 
 class UIStat extends UIElement {
   static properties = {
-    value:  { type: String, default: '',  reflect: true },
-    label:  { type: String, default: '',  reflect: true },
-    change: { type: String, default: '',  reflect: true },
-    trend:  { type: String, default: '',  reflect: true },
-    icon:   { type: String, default: '',  reflect: true },
+    value:   { type: String,  default: '',    reflect: true },
+    label:   { type: String,  default: '',    reflect: true },
+    change:  { type: String,  default: '',    reflect: true },
+    trend:   { type: String,  default: '',    reflect: true },
+    icon:    { type: String,  default: '',    reflect: true },
+    loading: { type: Boolean, default: false, reflect: true },
   };
 
   static template = () => null;
@@ -59,6 +60,34 @@ class UIStat extends UIElement {
   render() {
     if (!this.#valueEl) return;
 
+    // ── Loading state ──
+    // When [loading], render skeleton-ui into the value + change slots and set
+    // aria-busy on the host. Label is preserved (it's static metadata, not
+    // fetched data). Icon is preserved too. When loading flips to false on
+    // first non-empty value write, slots restore to text content automatically.
+    if (this.loading) {
+      this.setAttribute('aria-busy', 'true');
+      // Use innerHTML so skeleton-ui auto-registers via the barrel; consumers
+      // who tree-shake skeleton-ui out will see plain shimmer-less placeholders.
+      // Width 60% / 40% / 2em / 1em chosen to roughly mirror the rendered
+      // value+change visual mass without being so wide as to look like text.
+      this.#valueEl.textContent = '';
+      this.#valueEl.innerHTML = '<skeleton-ui width="60%" height="2em" radius="sm"></skeleton-ui>';
+      this.#changeEl.textContent = '';
+      this.#changeEl.innerHTML = '<skeleton-ui width="40%" height="1em" radius="sm"></skeleton-ui>';
+      this.#changeEl.hidden = false;
+      // Icon stays as-is (metadata, not data).
+      if (this.icon) {
+        this.#iconEl.setAttribute('name', this.icon);
+        this.#iconEl.hidden = false;
+      } else {
+        this.#iconEl.hidden = true;
+      }
+      this.#labelEl.textContent = this.label;
+      return;
+    }
+
+    this.removeAttribute('aria-busy');
     this.#valueEl.textContent = this.value;
     this.#labelEl.textContent = this.label;
 

package/components/stat/stat.test.js

@@ -0,0 +1,108 @@
+/**
+ * stat-ui — focused unit tests for the v0.6.18 `loading` boolean prop
+ * (FB-12 P2 resolution).
+ *
+ * Pre-v0.6.18: stat-ui rendered empty/zero values during data fetch with no
+ * visual indication. Consumers were forced to hand-roll skeleton-card
+ * workarounds with their own `@keyframes` CSS — duplicating skeleton-ui.
+ *
+ * v0.6.18 adds `loading: Boolean`. When set:
+ *   - value + change slots render <skeleton-ui> shimmer placeholders
+ *   - aria-busy="true" on the host
+ *   - label + icon (static metadata) are preserved
+ *   - toggling off restores text content + clears aria-busy
+ */
+
+import { describe, it, expect, beforeEach } from 'vitest';
+import '../../core/element.js';
+import './stat.js';
+// skeleton-ui is referenced by stat-ui at runtime when [loading]; load it so
+// the element gets defined (otherwise the inner <skeleton-ui> stays an
+// HTMLUnknownElement, which is still observable in the DOM but the assertions
+// below want to confirm registration via tagName.)
+import '../skeleton/skeleton.js';
+
+const tick = () => new Promise((r) => queueMicrotask(r));
+
+function mount(html) {
+  const wrap = document.createElement('div');
+  wrap.innerHTML = html;
+  document.body.appendChild(wrap);
+  return wrap.firstElementChild;
+}
+
+describe('stat-ui — v0.6.18 loading prop (FB-12 P2)', () => {
+  beforeEach(() => { document.body.innerHTML = ''; });
+
+  it('defaults loading to false; no aria-busy on host', async () => {
+    const el = mount('<stat-ui label="Total" value="1,234"></stat-ui>');
+    await tick();
+    expect(el.loading).toBe(false);
+    expect(el.hasAttribute('loading')).toBe(false);
+    expect(el.getAttribute('aria-busy')).toBeNull();
+  });
+
+  it('reflects [loading] attribute to the property', () => {
+    const el = mount('<stat-ui label="Total" loading></stat-ui>');
+    expect(el.loading).toBe(true);
+    expect(el.hasAttribute('loading')).toBe(true);
+  });
+
+  it('sets aria-busy="true" on host when [loading]', async () => {
+    const el = mount('<stat-ui label="Total" loading></stat-ui>');
+    await tick();
+    expect(el.getAttribute('aria-busy')).toBe('true');
+  });
+
+  it('renders a <skeleton-ui> inside the value slot when [loading]', async () => {
+    const el = mount('<stat-ui label="Total" loading></stat-ui>');
+    await tick();
+    const valueSlot = el.querySelector(':scope > [slot="value"]');
+    expect(valueSlot).not.toBeNull();
+    const sk = valueSlot.querySelector('skeleton-ui');
+    expect(sk).not.toBeNull();
+    expect(sk.tagName.toLowerCase()).toBe('skeleton-ui');
+  });
+
+  it('renders a <skeleton-ui> inside the change slot when [loading]', async () => {
+    const el = mount('<stat-ui label="Total" loading></stat-ui>');
+    await tick();
+    const changeSlot = el.querySelector(':scope > [slot="change"]');
+    expect(changeSlot).not.toBeNull();
+    expect(changeSlot.hidden).toBe(false);
+    const sk = changeSlot.querySelector('skeleton-ui');
+    expect(sk).not.toBeNull();
+  });
+
+  it('preserves label text content when [loading] (label is static metadata)', async () => {
+    const el = mount('<stat-ui label="Total Users" loading></stat-ui>');
+    await tick();
+    const labelSlot = el.querySelector(':scope > [slot="label"]');
+    expect(labelSlot.textContent).toBe('Total Users');
+  });
+
+  it('restores value + change text + clears aria-busy when loading toggles off', async () => {
+    const el = mount('<stat-ui label="Total" loading></stat-ui>');
+    await tick();
+    // Now flip off + add real values
+    el.removeAttribute('loading');
+    el.setAttribute('value', '1,234');
+    el.setAttribute('change', '+12%');
+    await tick();
+    expect(el.getAttribute('aria-busy')).toBeNull();
+    expect(el.querySelector(':scope > [slot="value"]').textContent).toBe('1,234');
+    expect(el.querySelector(':scope > [slot="change"]').textContent).toBe('+12%');
+    // skeleton-ui children should be gone (textContent setter clobbers innerHTML)
+    expect(el.querySelector(':scope > [slot="value"] skeleton-ui')).toBeNull();
+    expect(el.querySelector(':scope > [slot="change"] skeleton-ui')).toBeNull();
+  });
+
+  it('keeps icon visible when [loading] if icon prop is set', async () => {
+    const el = mount('<stat-ui label="Total" icon="users" loading></stat-ui>');
+    await tick();
+    const iconSlot = el.querySelector(':scope > [slot="icon"]');
+    expect(iconSlot).not.toBeNull();
+    expect(iconSlot.hidden).toBe(false);
+    expect(iconSlot.getAttribute('name')).toBe('users');
+  });
+});

package/components/stat/stat.yaml

@@ -5,6 +5,7 @@ name: UIStat
 tag: stat-ui
 composes:
   - icon-ui
+  - skeleton-ui
 component: Stat
 category: display
 version: 1
@@ -22,6 +23,14 @@ props:
     description: Eyebrow label describing the metric
     type: string
     default: ""
+  loading:
+    description: >-
+      Renders skeleton-ui shimmer placeholders in place of the value and change
+      slots while data is fetching. Sets aria-busy="true" on the host. Label
+      and icon are preserved (they're static metadata, not fetched data).
+      Toggle back to false when data arrives.
+    type: boolean
+    default: false
   trend:
     description: >-
       Trend direction or narrative subtitle. Canonical values color the change

package/components/table/class.js

@@ -844,18 +844,52 @@ export class UITable extends UIElement {
     let loadingEl = this.querySelector(':scope > [data-loading]');
 
     if (this.loading) {
-      // Show loading overlay
-      if (!loadingEl) {
-        loadingEl = document.createElement('div');
-        loadingEl.setAttribute('data-loading', '');
-        const prog = document.createElement('progress-ui');
-        prog.setAttribute('indeterminate', '');
-        loadingEl.appendChild(prog);
-        body.after(loadingEl);
+      // Skeleton rows: render N ghost rows of <skeleton-ui> cells inside the
+      // body rowgroup. Preserves table layout (header + columns intact) while
+      // signalling pending data. aria-busy on host announces the busy state.
+      // Old behavior (progress-ui spinner overlay) hid the table layout — the
+      // yaml description always promised "skeleton rows", impl shipped overlay
+      // (yaml-vs-impl drift fixed in v0.6.18 per FB-12 P2).
+      this.setAttribute('aria-busy', 'true');
+      // Real rows reconciled above already cleared if data is empty; if data
+      // is present, leave it but layer skeletons on top of the body. Simpler:
+      // always replace body children with skeleton rows when loading.
+      const visCols = this.#visibleColumns;
+      const skeletonRowCount = this.paginate > 0 ? Math.min(this.paginate, 8) : 5;
+      const totalCellCount =
+        (this.expandable ? 1 : 0) +
+        (this.selectable ? 1 : 0) +
+        visCols.length;
+
+      // Remove all existing body children (real rows + detail rows) — they're
+      // replaced by skeleton rows while loading.
+      while (body.firstChild) body.firstChild.remove();
+
+      for (let r = 0; r < skeletonRowCount; r++) {
+        const row = document.createElement('div');
+        row.setAttribute('role', 'row');
+        row.setAttribute('data-skeleton-row', '');
+        for (let c = 0; c < totalCellCount; c++) {
+          const cell = document.createElement('div');
+          cell.setAttribute('role', 'gridcell');
+          const sk = document.createElement('skeleton-ui');
+          // Vary width across cells so the row reads as natural data rows,
+          // not a uniform bar. Pattern: 60% / 80% / 70% / 50% / 90%, cycling.
+          const widths = ['60%', '80%', '70%', '50%', '90%'];
+          sk.setAttribute('width', widths[c % widths.length]);
+          sk.setAttribute('height', '1em');
+          sk.setAttribute('radius', 'sm');
+          cell.appendChild(sk);
+          row.appendChild(cell);
+        }
+        body.appendChild(row);
       }
+      // Remove legacy overlay if it lingers from a prior render.
+      if (loadingEl) loadingEl.remove();
       if (emptyEl) emptyEl.remove();
     } else if (this.#data.length === 0) {
       // Show empty state
+      this.removeAttribute('aria-busy');
       if (!emptyEl) {
         emptyEl = document.createElement('div');
         emptyEl.setAttribute('data-empty', '');
@@ -870,6 +904,7 @@ export class UITable extends UIElement {
       if (loadingEl) loadingEl.remove();
     } else {
       // Remove both overlays
+      this.removeAttribute('aria-busy');
       if (emptyEl) emptyEl.remove();
       if (loadingEl) loadingEl.remove();
     }

package/components/table/table.a2ui.json

@@ -42,7 +42,7 @@
       "default": false
     },
     "loading": {
-      "description": "Shows a loading overlay and skeleton rows. Sets aria-busy=\"true\". Data updates are deferred until loading is set back to false.",
+      "description": "Renders N ghost skeleton rows in place of the body data (count derived from `paginate` if set, else 5). Header + columns stay intact so the table layout is preserved while data fetches. Sets aria-busy=\"true\" on the host. Data updates are deferred until loading is set back to false.",
       "type": "boolean",
       "default": false
     },
@@ -89,6 +89,7 @@
       "icon-ui",
       "progress-ui",
       "pagination-ui",
+      "skeleton-ui",
       "badge-ui"
     ],
     "events": {

package/components/table/table.css

@@ -364,13 +364,29 @@
     color: var(--table-fg-disabled);
   }
 
-  /* ═══════ Loading ═══════ */
-
-  :scope[loading] [data-body] {
-    opacity: 0.5;
+  /* ═══════ Loading (skeleton rows) ═══════
+     Skeleton rows replace real rows while [loading] is set on the host
+     (see class.js #renderOverlays). Each row is a [data-skeleton-row]
+     containing <skeleton-ui> cells. Inherit body-row layout so column
+     widths track the header, then suppress hover/striping/click states
+     (no real data to interact with). */
+
+  [data-body] > [data-skeleton-row] {
     pointer-events: none;
   }
 
+  [data-body] > [data-skeleton-row]:hover {
+    background: transparent;
+  }
+
+  :scope[striped] [data-body] > [data-skeleton-row]:nth-child(even) {
+    background: transparent;
+  }
+
+  /* No-op the dim-when-loading rule the old overlay relied on: with skeleton
+     rows, the body IS the loading affordance — dimming it would just blur
+     the shimmer. */
+
   /* ═══════ Filter UI ═══════ */
 
   [data-filter-btn] {

package/components/table/table.d.ts

@@ -86,7 +86,7 @@ export class UITable extends UIElement {
   density: 'compact' | 'standard' | 'comfortable';
   /** Enable row expansion */
   expandable: boolean;
-  /** Shows a loading overlay and skeleton rows. Sets aria-busy="true". Data updates are deferred until loading is set back to false. */
+  /** Renders N ghost skeleton rows in place of the body data (count derived from `paginate` if set, else 5). Header + columns stay intact so the table layout is preserved while data fetches. Sets aria-busy="true" on the host. Data updates are deferred until loading is set back to false. */
   loading: boolean;
   /** Rows per page. 0 = show all rows without pagination. When > 0, renders a pagination bar below the table. */
   paginate: number;

package/components/table/table.test.js

@@ -0,0 +1,174 @@
+/**
+ * table-ui — focused unit tests for the v0.6.18 loading=skeleton-rows
+ * behavior change (FB-12 P2 resolution).
+ *
+ * Pre-v0.6.18: `loading=true` rendered a `<progress-ui>` spinner overlay
+ * inside the body via `[data-loading]`. The yaml description always said
+ * "Shows a loading overlay AND skeleton rows" but the impl only did the
+ * overlay — yaml-vs-impl drift since the initial table cut.
+ *
+ * v0.6.18 changes the loading branch to render N ghost skeleton rows
+ * (N = paginate if set, else 5) inside the [data-body] rowgroup. Header +
+ * columns stay intact so layout is preserved. Sets aria-busy="true" on the
+ * host. Old `[data-loading]` overlay element is removed if it lingers.
+ *
+ * Note: table-ui needs columns + data set imperatively (via the .columns /
+ * .data properties on the element) — declarative <col-def> children also
+ * work but require the col-def element to be registered first. Tests use
+ * the imperative path.
+ */
+
+import { describe, it, expect, beforeEach } from 'vitest';
+import '../../core/element.js';
+import './table.js';
+import '../skeleton/skeleton.js';
+
+const tick = () => new Promise((r) => queueMicrotask(r));
+const raf = () => new Promise((r) => requestAnimationFrame(() => requestAnimationFrame(r)));
+
+function mount(html) {
+  const wrap = document.createElement('div');
+  wrap.innerHTML = html;
+  document.body.appendChild(wrap);
+  return wrap.firstElementChild;
+}
+
+const COLS = [
+  { key: 'id',    label: 'ID' },
+  { key: 'name',  label: 'Name' },
+  { key: 'email', label: 'Email' },
+];
+const ROWS = [
+  { id: 1, name: 'Alice', email: 'alice@acme.com' },
+  { id: 2, name: 'Bob',   email: 'bob@acme.com' },
+];
+
+describe('table-ui — v0.6.18 loading=skeleton-rows (FB-12 P2)', () => {
+  beforeEach(() => { document.body.innerHTML = ''; });
+
+  it('renders skeleton rows in [data-body] when [loading] is set', async () => {
+    const el = mount('<table-ui></table-ui>');
+    el.columns = COLS;
+    el.data = ROWS;
+    await tick();
+    el.setAttribute('loading', '');
+    await tick();
+    const body = el.querySelector(':scope > [data-body]');
+    expect(body).not.toBeNull();
+    const skRows = body.querySelectorAll('[data-skeleton-row]');
+    expect(skRows.length).toBeGreaterThan(0);
+  });
+
+  it('sets aria-busy="true" on the host when [loading]', async () => {
+    const el = mount('<table-ui></table-ui>');
+    el.columns = COLS;
+    el.data = ROWS;
+    await tick();
+    el.setAttribute('loading', '');
+    await tick();
+    expect(el.getAttribute('aria-busy')).toBe('true');
+  });
+
+  it('replaces real body rows with skeleton rows when [loading]', async () => {
+    const el = mount('<table-ui></table-ui>');
+    el.columns = COLS;
+    el.data = ROWS;
+    // table-ui uses requestAnimationFrame in #requestRender(), not microtasks.
+    // queueMicrotask-based tick() won't drain RAF callbacks — must await raf().
+    // Loop up to 5 RAF cycles in case the initial mount needs multiple renders
+    // to settle (columns set → render → data set → render).
+    for (let i = 0; i < 5; i++) {
+      await raf();
+      const body = el.querySelector(':scope > [data-body]');
+      if (body && body.children.length >= 2) break;
+    }
+    const body = el.querySelector(':scope > [data-body]');
+    expect(body).not.toBeNull();
+    // Real rows present (2)
+    const realRows = body.querySelectorAll(':scope > [role="row"]:not([data-skeleton-row])');
+    expect(realRows.length).toBe(2);
+    el.setAttribute('loading', '');
+    await raf();
+    // Real rows gone, skeleton rows present
+    expect(body.querySelectorAll(':scope > [role="row"]:not([data-skeleton-row])').length).toBe(0);
+    expect(body.querySelectorAll(':scope > [data-skeleton-row]').length).toBeGreaterThan(0);
+  });
+
+  it('each skeleton row has cell count matching column count', async () => {
+    const el = mount('<table-ui></table-ui>');
+    el.columns = COLS;  // 3 columns
+    el.data = ROWS;
+    await tick();
+    el.setAttribute('loading', '');
+    await tick();
+    const skRow = el.querySelector('[data-skeleton-row]');
+    expect(skRow.children.length).toBe(3);
+  });
+
+  it('each skeleton cell contains a <skeleton-ui> shimmer element', async () => {
+    const el = mount('<table-ui></table-ui>');
+    el.columns = COLS;
+    el.data = ROWS;
+    await tick();
+    el.setAttribute('loading', '');
+    await tick();
+    const skCells = el.querySelectorAll('[data-skeleton-row] > [role="gridcell"]');
+    expect(skCells.length).toBeGreaterThan(0);
+    for (const cell of skCells) {
+      const sk = cell.querySelector('skeleton-ui');
+      expect(sk).not.toBeNull();
+      expect(sk.tagName.toLowerCase()).toBe('skeleton-ui');
+    }
+  });
+
+  it('does NOT render a [data-loading] overlay element (old behavior removed)', async () => {
+    const el = mount('<table-ui></table-ui>');
+    el.columns = COLS;
+    el.data = ROWS;
+    await tick();
+    el.setAttribute('loading', '');
+    await tick();
+    // Old impl created <div data-loading> with <progress-ui> child.
+    // v0.6.18 does NOT — skeleton rows ARE the loading affordance.
+    expect(el.querySelector(':scope > [data-loading]')).toBeNull();
+  });
+
+  it('restores real rows + clears aria-busy when loading toggles off', async () => {
+    const el = mount('<table-ui></table-ui>');
+    el.columns = COLS;
+    el.data = ROWS;
+    await tick();
+    el.setAttribute('loading', '');
+    await tick();
+    el.removeAttribute('loading');
+    await tick();
+    expect(el.getAttribute('aria-busy')).toBeNull();
+    expect(el.querySelectorAll('[data-body] > [data-skeleton-row]').length).toBe(0);
+    expect(el.querySelectorAll('[data-body] > [role="row"]').length).toBe(2);
+  });
+
+  it('skeleton row count tracks paginate when set, capped at 8', async () => {
+    const el = mount('<table-ui paginate="3"></table-ui>');
+    el.columns = COLS;
+    el.data = ROWS;
+    await tick();
+    el.setAttribute('loading', '');
+    await tick();
+    expect(el.querySelectorAll('[data-body] > [data-skeleton-row]').length).toBe(3);
+  });
+
+  it('preserves header row when [loading]', async () => {
+    const el = mount('<table-ui></table-ui>');
+    el.columns = COLS;
+    el.data = ROWS;
+    await tick();
+    const beforeHeader = el.querySelector(':scope > [data-header]');
+    expect(beforeHeader).not.toBeNull();
+    el.setAttribute('loading', '');
+    await tick();
+    const afterHeader = el.querySelector(':scope > [data-header]');
+    expect(afterHeader).not.toBeNull();
+    // Header cells unchanged in count
+    expect(afterHeader.children.length).toBe(3);
+  });
+});

package/components/table/table.yaml

@@ -15,6 +15,7 @@ composes:
   - icon-ui
   - progress-ui
   - pagination-ui
+  - skeleton-ui
   - badge-ui
 props:
   columns:
@@ -39,8 +40,11 @@ props:
     type: boolean
     default: false
   loading:
-    description: Shows a loading overlay and skeleton rows. Sets aria-busy="true". Data updates are
-      deferred until loading is set back to false.
+    description: >-
+      Renders N ghost skeleton rows in place of the body data (count derived
+      from `paginate` if set, else 5). Header + columns stay intact so the
+      table layout is preserved while data fetches. Sets aria-busy="true" on
+      the host. Data updates are deferred until loading is set back to false.
     type: boolean
     default: false
     reflect: true

package/components/text/class.js

@@ -28,10 +28,20 @@ import { UIElement } from '../../core/element.js';
 
 export class UIText extends UIElement {
   static properties = {
-    variant:  { type: String,  default: 'body', reflect: true },
-    strong:   { type: Boolean, default: false, reflect: true },
-    truncate: { type: Boolean, default: false, reflect: true },
-    lines:    { type: Number,  default: 0, reflect: true },
+    variant:    { type: String,  default: 'body', reflect: true },
+    strong:     { type: Boolean, default: false, reflect: true },
+    truncate:   { type: Boolean, default: false, reflect: true },
+    lines:      { type: Number,  default: 0,     reflect: true },
+    // ── v0.6.18 (FB-10) — finer-control overrides on top of `variant` ──
+    // Pre-v0.6.18, sizing/coloring/weighting required choosing a different
+    // `variant` (e.g. `label-sm` → `caption`). The skill already documents
+    // an intuitive overlay API (color="subtle", size="sm", weight="semibold",
+    // text-align="center"); v0.6.18 implements it. Each prop is an
+    // attribute selector in text.css that overrides the variant default.
+    size:       { type: String,  default: '',    reflect: true },
+    color:      { type: String,  default: '',    reflect: true },
+    weight:     { type: String,  default: '',    reflect: true },
+    'text-align': { type: String, default: '',   reflect: true },
   };
 
   static template = () => null;

package/components/text/text.a2ui.json

@@ -13,6 +13,20 @@
     }
   ],
   "properties": {
+    "color": {
+      "description": "Override the variant's color token. Permissive: unknown values are no-ops (variant color wins). Added v0.6.18 (FB-10).",
+      "type": "string",
+      "enum": [
+        "default",
+        "subtle",
+        "strong",
+        "accent",
+        "danger",
+        "success",
+        "warning"
+      ],
+      "default": ""
+    },
     "component": {
       "const": "Text"
     },
@@ -21,11 +35,32 @@
       "type": "number",
       "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).",
+      "type": "string",
+      "enum": [
+        "sm",
+        "md",
+        "lg"
+      ],
+      "default": ""
+    },
     "strong": {
       "description": "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.",
       "type": "boolean",
       "default": false
     },
+    "text-align": {
+      "description": "Override text alignment. Note: text-ui defaults to display:inline, so this only takes effect when text-ui is block-like (wrapping or parent display:block/grid). Added v0.6.18 (FB-10).",
+      "type": "string",
+      "enum": [
+        "start",
+        "center",
+        "end",
+        "justify"
+      ],
+      "default": ""
+    },
     "textContent": {
       "description": "Display text content. The main payload field for Text components extracted from HTML.",
       "$ref": "common_types.json#/$defs/DynamicString"
@@ -67,6 +102,17 @@
         "section": "Inline form-group / navlist heading (visual rank H4). Small-cap. Use for form group labels, nav list headings.",
         "subsection": "Sub-landmark within a section (visual rank H3). 14px / semibold. Use for card titles within a section."
       }
+    },
+    "weight": {
+      "description": "Override the variant's font-weight. Maps to --a-weight / --a-weight-medium / --a-weight-semibold / --a-weight-bold. Permissive: unknown values are no-ops (variant weight wins). Added v0.6.18 (FB-10).",
+      "type": "string",
+      "enum": [
+        "regular",
+        "medium",
+        "semibold",
+        "bold"
+      ],
+      "default": ""
     }
   },
   "required": [

package/components/text/text.css

@@ -61,6 +61,47 @@
   :scope[variant="deck"]       { --text-family: var(--a-deck-family);       --text-weight: var(--a-deck-weight);       --text-size: var(--a-deck-size);       --text-leading: var(--a-deck-leading);       --text-tracking: var(--a-deck-tracking);       --text-case: var(--a-deck-case);       --text-color: var(--a-deck-color); }
   :scope[variant="metric"]     { --text-family: var(--a-metric-family);     --text-weight: var(--a-metric-weight);     --text-size: var(--a-metric-size);     --text-leading: var(--a-metric-leading);     --text-tracking: var(--a-metric-tracking);     --text-case: var(--a-metric-case);     --text-color: var(--a-metric-color); }
 
+  /* ── v0.6.18 (FB-10) — finer-control overrides on top of `variant` ──
+     The skill always documented an overlay API (color="subtle",
+     size="sm", weight="semibold", text-align="center"). Pre-v0.6.18 these
+     attributes existed only as documentation — text-ui ignored them and
+     rendered the variant default. v0.6.18 implements them as attribute
+     selectors that override the `--text-*` CSS variables set by [variant].
+     Each is intentionally permissive: unknown values fall back to the
+     variant's value rather than throwing. Authoring `<text-ui color="...">`
+     with an unknown color = no-op (variant color wins). */
+
+  /* size — sm | md | lg (md is the body default ~15-16px) */
+  :scope[size="sm"]  { --text-size: var(--a-body-sm); }
+  :scope[size="md"]  { --text-size: var(--a-body-md); }
+  :scope[size="lg"]  { --text-size: var(--a-body-lg); }
+
+  /* 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="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="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); }
+
+  /* weight — regular | medium | semibold | bold */
+  :scope[weight="regular"]  { --text-weight: var(--a-weight); }
+  :scope[weight="medium"]   { --text-weight: var(--a-weight-medium); }
+  :scope[weight="semibold"] { --text-weight: var(--a-weight-semibold); }
+  :scope[weight="bold"]     { --text-weight: var(--a-weight-bold); }
+
+  /* text-align — start | center | end | justify */
+  :scope[text-align="start"]   { text-align: start; }
+  :scope[text-align="center"]  { text-align: center; }
+  :scope[text-align="end"]     { text-align: end; }
+  :scope[text-align="justify"] { text-align: justify; }
+  /* Note: `<text-ui>` defaults to display:inline. text-align only takes
+     effect when text-ui itself is block-like (e.g. via wrapping or a
+     `display: block`/`grid` parent). The override-attribute pattern keeps
+     the inline default but lets consumers flip alignment with one attr. */
+
   /* ── Truncation (single-line) ── */
   :scope[truncate] {
     overflow: hidden;

package/components/text/text.d.ts

@@ -39,8 +39,12 @@ export type UITextVariant =
   | 'code';
 
 export class UIText extends UIElement {
+  /** Override the variant's color token. Permissive: unknown values are no-ops (variant color wins). Added v0.6.18 (FB-10). */
+  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). */
+  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;
   /** Display text content. The main payload field for Text components extracted from HTML. */
@@ -57,4 +61,6 @@ For semantic headings, wrap with native `<h1>`-`<h6>` OR add
 labels (eyebrows, kickers, captions, deck), the presentational default
 is correct. The §221k chooser guide in USAGE.md documents picker heuristics. */
   variant: UITextVariant;
+  /** Override the variant's font-weight. Maps to --a-weight / --a-weight-medium / --a-weight-semibold / --a-weight-bold. Permissive: unknown values are no-ops (variant weight wins). Added v0.6.18 (FB-10). */
+  weight: 'regular' | 'medium' | 'semibold' | 'bold';
 }

package/components/text/text.test.js

@@ -110,3 +110,93 @@ describe('text-ui §210 — variant enum vs CSS rule completeness', () => {
     }
   });
 });
+
+// ─────────────────────────────────────────────────────────────────────
+// v0.6.18 (FB-10) — overlay attributes on top of `variant`
+// ─────────────────────────────────────────────────────────────────────
+
+describe('text-ui v0.6.18 — overlay props (FB-10)', () => {
+  beforeEach(() => { document.body.innerHTML = ''; });
+
+  // ── Attribute reflection: each new prop reflects to the host ──
+  it.each([
+    ['size', 'sm'],
+    ['size', 'md'],
+    ['size', 'lg'],
+    ['color', 'subtle'],
+    ['color', 'strong'],
+    ['color', 'accent'],
+    ['color', 'danger'],
+    ['color', 'success'],
+    ['color', 'warning'],
+    ['color', 'default'],
+    ['weight', 'regular'],
+    ['weight', 'medium'],
+    ['weight', 'semibold'],
+    ['weight', 'bold'],
+    ['text-align', 'start'],
+    ['text-align', 'center'],
+    ['text-align', 'end'],
+    ['text-align', 'justify'],
+  ])('<text-ui %s="%s"> reflects the attribute', async (prop, value) => {
+    const el = mount(`<text-ui ${prop}="${value}">x</text-ui>`);
+    await tick();
+    expect(el.getAttribute(prop)).toBe(value);
+  });
+
+  // ── CSS-side: every documented value has a :scope[attr="value"] rule ──
+  const sizes = ['sm', 'md', 'lg'];
+  const colors = ['default', 'subtle', 'strong', 'accent', 'danger', 'success', 'warning'];
+  const weights = ['regular', 'medium', 'semibold', 'bold'];
+  const aligns = ['start', 'center', 'end', 'justify'];
+
+  it.each(sizes)('text.css ships :scope[size="%s"] rule', (s) => {
+    expect(TEXT_CSS).toMatch(new RegExp(`:scope\\[size="${s}"\\]`));
+  });
+
+  it.each(colors)('text.css ships :scope[color="%s"] rule', (c) => {
+    expect(TEXT_CSS).toMatch(new RegExp(`:scope\\[color="${c}"\\]`));
+  });
+
+  it.each(weights)('text.css ships :scope[weight="%s"] rule', (w) => {
+    expect(TEXT_CSS).toMatch(new RegExp(`:scope\\[weight="${w}"\\]`));
+  });
+
+  it.each(aligns)('text.css ships :scope[text-align="%s"] rule', (a) => {
+    expect(TEXT_CSS).toMatch(new RegExp(`:scope\\[text-align="${a}"\\]`));
+  });
+
+  // ── yaml-vs-impl consistency: every prop in the a2ui enum has a CSS rule ──
+  it('a2ui.json color enum matches CSS rules 1:1', () => {
+    const colorEnum = TEXT_A2UI.properties.color?.enum ?? [];
+    expect(colorEnum.sort()).toEqual([...colors].sort());
+    for (const c of colorEnum) {
+      expect(TEXT_CSS).toMatch(new RegExp(`:scope\\[color="${c}"\\]`));
+    }
+  });
+
+  it('a2ui.json size enum matches CSS rules 1:1', () => {
+    const sizeEnum = TEXT_A2UI.properties.size?.enum ?? [];
+    expect(sizeEnum.sort()).toEqual([...sizes].sort());
+    for (const s of sizeEnum) {
+      expect(TEXT_CSS).toMatch(new RegExp(`:scope\\[size="${s}"\\]`));
+    }
+  });
+
+  it('a2ui.json weight enum matches CSS rules 1:1', () => {
+    const weightEnum = TEXT_A2UI.properties.weight?.enum ?? [];
+    expect(weightEnum.sort()).toEqual([...weights].sort());
+    for (const w of weightEnum) {
+      expect(TEXT_CSS).toMatch(new RegExp(`:scope\\[weight="${w}"\\]`));
+    }
+  });
+
+  // ── Permissive fallback: unknown values are no-ops (no JS error) ──
+  it('unknown color value renders without throwing', async () => {
+    const el = mount('<text-ui color="banana">x</text-ui>');
+    await tick();
+    expect(el.getAttribute('color')).toBe('banana');
+    // The variant default wins; no CSS rule matches "banana". Test the
+    // shape: no thrown error during mount, no console.error.
+  });
+});

package/components/text/text.yaml

@@ -8,20 +8,56 @@ category: display
 version: 1
 description: Typography wrapper that applies role tokens. Supports truncation and line clamping.
 props:
+  color:
+    description: >-
+      Override the variant's color token. Permissive: unknown values are
+      no-ops (variant color wins). Added v0.6.18 (FB-10).
+    type: string
+    enum: ["default", "subtle", "strong", "accent", "danger", "success", "warning"]
+    default: ""
+    reflect: true
   lines:
     description: Multi-line clamp count (0 = no clamp)
     type: number
     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).
+    type: string
+    enum: ["sm", "md", "lg"]
+    default: ""
+    reflect: true
   strong:
     description: 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.
     type: boolean
     default: false
     reflect: true
+  text-align:
+    description: >-
+      Override text alignment. Note: text-ui defaults to display:inline,
+      so this only takes effect when text-ui is block-like (wrapping or
+      parent display:block/grid). Added v0.6.18 (FB-10).
+    type: string
+    enum: ["start", "center", "end", "justify"]
+    default: ""
+    reflect: true
   truncate:
     description: Single-line truncation with ellipsis. Ignored when `lines` is set.
     type: boolean
     default: false
     reflect: true
+  weight:
+    description: >-
+      Override the variant's font-weight. Maps to --a-weight /
+      --a-weight-medium / --a-weight-semibold / --a-weight-bold.
+      Permissive: unknown values are no-ops (variant weight wins). Added
+      v0.6.18 (FB-10).
+    type: string
+    enum: ["regular", "medium", "semibold", "bold"]
+    default: ""
+    reflect: true
   textContent:
     description: Display text content. The main payload field for Text components extracted from HTML.
     type: string

package/components/toggle-scheme/class.js

@@ -272,11 +272,17 @@ export class UIToggleScheme extends UIElement {
   #writeTarget(scheme) {
     const t = this.#resolveTarget();
     t.style.setProperty('color-scheme', scheme);
+    // FEEDBACK-14: also write the [data-scheme] attribute. styles/themes.css
+    // selects on [data-scheme="dark"] etc., so consumer CSS patterned after
+    // themes.css needs the attribute — the inline color-scheme style alone
+    // satisfies AdiaUI's light-dark() tokens but not [data-scheme]-scoped CSS.
+    t.setAttribute('data-scheme', scheme);
   }
 
   #clearTargetOverride() {
     const t = this.#resolveTarget();
     t.style.removeProperty('color-scheme');
+    t.removeAttribute('data-scheme'); // FEEDBACK-14 — paired with #writeTarget
     if (this.persist) {
       try { localStorage.removeItem(`${this.storagePrefix}scheme`); } catch {}
     }

package/components/toggle-scheme/toggle-scheme.yaml

@@ -149,7 +149,13 @@ tokens:
   --toggle-scheme-icon-transition:
     description: Duration + easing for icon-color transition when scheme flips.
 a2ui:
-  rules: []
+  rules:
+    - >-
+      Place toggle-scheme-ui in the shell topbar's trailing action cluster
+      — slot="action" inside <admin-topbar slot="header"> of
+      <admin-content>. It is a persistent, app-wide preference control;
+      never put it in a sidebar footer / <admin-statusbar>, which hosts
+      user-account items only.
 anti_patterns: []
 examples:
   - name: header-action

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@adia-ai/web-components",
-  "version": "0.6.16",
+  "version": "0.6.18",
   "description": "AdiaUI web components \u2014 vanilla custom elements. A2UI runtime (renderer, registry, streams, wiring) lives in @adia-ai/a2ui-runtime.",
   "type": "module",
   "types": "./index.d.ts",