@adia-ai/web-components 0.0.27 → 0.0.29

package/components/feed/feed.js

@@ -0,0 +1,385 @@
+/**
+ * <feed-ui> + <feed-item-ui> — Shared top-layer feed channel.
+ *
+ * Per docs/specs/feed-channel.md (SPEC-FEED-CHANNEL-001).
+ *
+ * Phase 1 (skeleton) ships here:
+ *   - Per-position singletons (`<feed-ui position="bottom-right">`)
+ *     resolving OD-FEED-1; mounted lazily into document.body via
+ *     Popover API for top-layer placement.
+ *   - Auto-fade `<feed-item-ui>` policy. Sticky-dismissible and
+ *     action-required policies are stubs that respect the contract
+ *     (no auto-dismiss when `duration` is null/0; close button
+ *     surfaces when `dismissible` is set) but the action-required
+ *     focus-trap is deferred.
+ *   - Static API:  AdiaFeed.post() / .get() / .clear() / .purge()
+ *     — `purge()` directly addresses the audit's L-B4 container-leak
+ *     finding by giving consumers a tear-down hook.
+ *   - Global event channel:  window.dispatchEvent(new CustomEvent(
+ *       'feed', { detail: { text, position, ... } })) — same shape as
+ *     AdiaFeed.post() so any code can post without importing the
+ *     module directly. Idempotent listener install (HMR-safe).
+ *
+ * Toast migration (spec § 2.5) is deferred — toast-ui keeps its own
+ * container + API for now; the migration happens once the feed-ui
+ * surface has soaked.
+ */
+
+import { AdiaElement, html } from '../../core/element.js';
+
+/* ── Container — one per position, mounted into document.body ── */
+
+class AdiaFeedContainer extends AdiaElement {
+  static properties = {
+    position: { type: String, default: 'bottom-right', reflect: true },
+    max:      { type: Number, default: 5,              reflect: true },
+  };
+  static template = () => html``;
+
+  connected() {
+    if (!this.hasAttribute('role')) this.setAttribute('role', 'region');
+    if (!this.hasAttribute('aria-label')) this.setAttribute('aria-label', 'Feed');
+  }
+}
+
+customElements.define('feed-ui', AdiaFeedContainer);
+
+/* ── Item — one per posted message ── */
+
+class AdiaFeedItem extends AdiaElement {
+  #timer = null;
+  #removing = false;
+  #closeTimer = null;
+  #openRaf = null;
+
+  static properties = {
+    text:        { type: String,  default: '',           reflect: true },
+    heading:     { type: String,  default: '',           reflect: true },
+    icon:        { type: String,  default: '',           reflect: true },
+    variant:     { type: String,  default: 'default',    reflect: true },
+    duration:    { type: Number,  default: 4000,         reflect: true },
+    dismissible: { type: Boolean, default: false,        reflect: true },
+    // Phase 2: action-required policy. When set, the item carries an
+    // action button that the user MUST click (or dismiss) before the
+    // item goes away. Spec §2.3 — action-required role=alertdialog,
+    // focus is trapped until choice is made.
+    action:      { type: String,  default: '',           reflect: true },
+  };
+
+  static parts = {
+    body: '<div slot="body"></div>',
+  };
+  static template = () => html``;
+
+  #onPress = (e) => {
+    if (e.target.closest('[data-feed-close]')) { this.dismiss(); return; }
+    // Phase 2: action button — fires the action callback (if registered
+    // via FeedHandle.update with onAction) then dismisses. The handle's
+    // .update({onAction: fn}) populates this.#onAction below.
+    if (e.target.closest('[data-feed-action]')) {
+      try { this.#onAction?.(); } catch (err) { console.warn('[feed-item] action handler threw:', err); }
+      this.dismiss();
+    }
+  };
+
+  // Phase 2 focus-trap state — only used when the policy is action-required.
+  #onAction = null;
+  #focusTrapPrev = null;
+  #onTrapKeydown = null;
+
+  connected() {
+    this.addEventListener('press', this.#onPress);
+  }
+
+  #getDuration() {
+    const raw = getComputedStyle(this).getPropertyValue('--feed-item-duration').trim();
+    return parseFloat(raw) || 200;
+  }
+
+  render() {
+    const body = this.ensure('body');
+    body.textContent = '';
+    if (this.heading) {
+      const h = document.createElement('strong');
+      h.textContent = this.heading;
+      h.style.display = 'block';
+      body.appendChild(h);
+    }
+    if (this.text) {
+      const t = document.createElement('span');
+      t.textContent = this.text;
+      body.appendChild(t);
+    }
+
+    /* Inferred policy roles per spec §2.4. Auto-fade gets `status`;
+       sticky danger/warning gets `alert`; action-required (sticky +
+       has [action]) gets `alertdialog` and a focus trap. */
+    const isSticky = !this.duration || this.duration <= 0;
+    const isLoud   = this.variant === 'danger' || this.variant === 'warning';
+    const isActionRequired = isSticky && !!this.action;
+    let role = 'status';
+    if (isActionRequired) role = 'alertdialog';
+    else if (isSticky && isLoud) role = 'alert';
+    this.setAttribute('role', role);
+    this.setAttribute('aria-live', role === 'alert' || role === 'alertdialog' ? 'assertive' : 'polite');
+    if (isActionRequired) this.setAttribute('aria-modal', 'false'); // not page-blocking; focus-trap only
+
+    /* Render dismiss button for sticky items (spec §2.2 — default true
+       for sticky, false for auto-fade). Action-required items still
+       allow Escape to dismiss for safety; the action button is not the
+       only escape. */
+    const wantsClose = this.dismissible || isSticky;
+    let close = this.querySelector(':scope > [data-feed-close]');
+    if (wantsClose && !close) {
+      close = document.createElement('button-ui');
+      close.setAttribute('data-feed-close', '');
+      close.setAttribute('icon', 'x');
+      close.setAttribute('variant', 'ghost');
+      close.setAttribute('size', 'sm');
+      close.setAttribute('aria-label', 'Dismiss');
+      this.appendChild(close);
+    } else if (!wantsClose && close) {
+      close.remove();
+    }
+
+    /* Phase 2 — render the action button when [action] is set. Sits
+       between the body and the close button. */
+    let actionBtn = this.querySelector(':scope > [data-feed-action]');
+    if (this.action) {
+      if (!actionBtn) {
+        actionBtn = document.createElement('button-ui');
+        actionBtn.setAttribute('data-feed-action', '');
+        actionBtn.setAttribute('variant', 'ghost');
+        actionBtn.setAttribute('size', 'sm');
+        if (close && close.parentElement === this) this.insertBefore(actionBtn, close);
+        else                                       this.appendChild(actionBtn);
+      }
+      actionBtn.setAttribute('text', this.action);
+    } else if (actionBtn) {
+      actionBtn.remove();
+    }
+
+    /* Focus-trap activation for action-required. */
+    if (isActionRequired) this.#installFocusTrap();
+    else                  this.#uninstallFocusTrap();
+
+    if (!this.hasAttribute('data-open') && !this.#removing) {
+      this.#openRaf = requestAnimationFrame(() => {
+        this.#openRaf = null;
+        this.setAttribute('data-open', '');
+      });
+    }
+    this.#scheduleAutoDismiss();
+  }
+
+  #scheduleAutoDismiss() {
+    if (this.#timer) clearTimeout(this.#timer);
+    if (this.duration && this.duration > 0) {
+      this.#timer = setTimeout(() => this.dismiss(), this.duration);
+    }
+  }
+
+  dismiss() {
+    if (this.#removing) return;
+    this.#removing = true;
+    if (this.#timer) { clearTimeout(this.#timer); this.#timer = null; }
+    this.removeAttribute('data-open');
+    this.setAttribute('data-closing', '');
+    this.#closeTimer = setTimeout(() => {
+      this.#closeTimer = null;
+      const container = this.parentElement;
+      this.dispatchEvent(new Event('close', { bubbles: true }));
+      this.remove();
+      if (container?.matches?.('feed-ui')) AdiaFeed.releaseContainerIfEmpty(container);
+    }, this.#getDuration());
+  }
+
+  update(patch) {
+    if (!patch || typeof patch !== 'object') return;
+    for (const k of Object.keys(patch)) {
+      if (k in AdiaFeedItem.properties) this[k] = patch[k];
+    }
+    // Phase 2: handle is set via the FeedHandle's update(); not a
+    // reflected attribute, so it lives outside the property loop.
+    if (typeof patch.onAction === 'function') this.#onAction = patch.onAction;
+    this.#scheduleAutoDismiss();
+  }
+
+  // Phase 2 focus-trap. Installs on action-required items; saves the
+  // previously-focused element so we can return focus on dismiss; cycles
+  // Tab/Shift-Tab between focusable descendants; Escape dismisses.
+  #installFocusTrap() {
+    if (this.#onTrapKeydown) return; // already installed
+    this.#focusTrapPrev = document.activeElement;
+    const focusables = () => [...this.querySelectorAll('button, button-ui, [tabindex]:not([tabindex="-1"]), input, [data-feed-action], [data-feed-close]')]
+      .filter((el) => !el.hasAttribute('disabled') && el.offsetParent !== null);
+    this.#onTrapKeydown = (e) => {
+      if (e.key === 'Escape') { e.stopPropagation(); this.dismiss(); return; }
+      if (e.key !== 'Tab') return;
+      const els = focusables();
+      if (!els.length) return;
+      const first = els[0];
+      const last  = els[els.length - 1];
+      const active = document.activeElement;
+      if (e.shiftKey && active === first) { e.preventDefault(); last.focus(); }
+      else if (!e.shiftKey && active === last) { e.preventDefault(); first.focus(); }
+    };
+    this.addEventListener('keydown', this.#onTrapKeydown, true);
+    // Move focus into the item — prefer the action button.
+    queueMicrotask(() => {
+      const els = focusables();
+      const action = this.querySelector('[data-feed-action]');
+      (action || els[0])?.focus?.();
+    });
+  }
+
+  #uninstallFocusTrap() {
+    if (!this.#onTrapKeydown) return;
+    this.removeEventListener('keydown', this.#onTrapKeydown, true);
+    this.#onTrapKeydown = null;
+    // Restore focus to whatever had it before the trap engaged.
+    try { this.#focusTrapPrev?.focus?.(); } catch { /* element may have been removed */ }
+    this.#focusTrapPrev = null;
+  }
+
+  disconnected() {
+    this.removeEventListener('press', this.#onPress);
+    if (this.#timer) { clearTimeout(this.#timer); this.#timer = null; }
+    if (this.#closeTimer) { clearTimeout(this.#closeTimer); this.#closeTimer = null; }
+    if (this.#openRaf != null) { cancelAnimationFrame(this.#openRaf); this.#openRaf = null; }
+    this.#uninstallFocusTrap();
+  }
+}
+
+customElements.define('feed-item-ui', AdiaFeedItem);
+
+/* ── Static API — AdiaFeed ── */
+
+class AdiaFeed {
+  static #containers = new Map();
+
+  /**
+   * Get (or lazily create) the per-position lane. Each lane is a
+   * manual Popover-API container — `[popover="manual"]` puts it in
+   * the browser's top-layer with no z-index wars and the native
+   * popover stack lets multiple lanes coexist (e.g. one feed in
+   * top-right + another in bottom-center) without collision.
+   */
+  static get(position = 'bottom-right') {
+    let el = AdiaFeed.#containers.get(position);
+    if (el && el.isConnected) return el;
+    el = document.createElement('feed-ui');
+    el.setAttribute('position', position);
+    if ('popover' in HTMLElement.prototype) el.setAttribute('popover', 'manual');
+    document.body.appendChild(el);
+    try { el.showPopover?.(); } catch { /* graceful fallback */ }
+    AdiaFeed.#containers.set(position, el);
+    return el;
+  }
+
+  /**
+   * Post a feed item. Returns a `FeedHandle` (`{id, dismiss, update}`).
+   *
+   * @param {Object} opts
+   * @param {string} [opts.text]
+   * @param {string} [opts.heading]
+   * @param {string} [opts.icon]
+   * @param {string} [opts.variant='default']  default | info | success | warning | danger
+   * @param {number|null} [opts.duration=4000]  ms; null/0 = sticky (requires close click)
+   * @param {string} [opts.position='bottom-right']
+   * @param {boolean} [opts.dismissible]  override default (true for sticky, false for auto)
+   * @param {string} [opts.id]
+   * @param {string} [opts.action]  Phase 2 — action button label. When set,
+   *                                duration is forced to null (sticky); the
+   *                                item gets role=alertdialog + focus trap.
+   * @param {function} [opts.onAction]  Phase 2 — callback invoked when the
+   *                                action button is pressed. Item dismisses
+   *                                after the callback returns.
+   */
+  static post(opts = {}) {
+    const {
+      text = '',
+      heading = '',
+      icon = '',
+      variant = 'default',
+      duration = 4000,
+      position = 'bottom-right',
+      dismissible,
+      id,
+      action = '',
+      onAction,
+    } = opts;
+    const v = variant === 'error' ? 'danger' : variant;  // documented alias
+    const container = AdiaFeed.get(position);
+    // Phase 2 max-queue: items above [max] queue with [data-queued] and
+    // become visible as visible items dismiss.
+    const max = parseInt(container.getAttribute('max') || '5', 10);
+    const visibleCount = [...container.children].filter((c) =>
+      c.tagName === 'FEED-ITEM-UI' && !c.hasAttribute('data-queued')
+    ).length;
+    const item = document.createElement('feed-item-ui');
+    if (id) item.setAttribute('data-id', id);
+    item.text = text;
+    item.heading = heading;
+    item.icon = icon;
+    item.variant = v;
+    // Action-required forces sticky.
+    item.duration = action ? 0 : duration;
+    if (dismissible != null) item.dismissible = !!dismissible;
+    if (action) item.action = action;
+    if (visibleCount >= max) item.setAttribute('data-queued', '');
+    container.appendChild(item);
+    if (typeof onAction === 'function') item.update({ onAction });
+    return {
+      id: id ?? null,
+      dismiss: () => item.dismiss(),
+      update:  (patch) => item.update(patch),
+    };
+  }
+
+  /** Clear all items in a single lane. */
+  static clear(position = 'bottom-right') {
+    const el = AdiaFeed.#containers.get(position);
+    if (!el) return;
+    for (const item of [...el.children]) {
+      if (item.tagName === 'FEED-ITEM-UI') item.dismiss?.();
+    }
+  }
+
+  /** Tear down ALL containers. Test cleanup; addresses audit L-B4. */
+  static purge() {
+    for (const el of AdiaFeed.#containers.values()) {
+      try { el.hidePopover?.(); } catch { /* noop */ }
+      el.remove();
+    }
+    AdiaFeed.#containers.clear();
+  }
+
+  /** Internal: drop a lane when its last item exits. Also rotates the
+   *  Phase 2 max-queue: when a visible item leaves, promote the oldest
+   *  queued sibling so the visible-count returns to [max]. */
+  static releaseContainerIfEmpty(container) {
+    if (!container) return;
+    // Promote the oldest queued sibling (if any) before deciding whether
+    // to release. The queue is FIFO; queued items live at the tail.
+    const queued = container.querySelector('feed-item-ui[data-queued]');
+    if (queued) queued.removeAttribute('data-queued');
+    if (container.children.length > 0) return;
+    try { container.hidePopover?.(); } catch { /* noop */ }
+    container.remove();
+    for (const [pos, el] of AdiaFeed.#containers) {
+      if (el === container) AdiaFeed.#containers.delete(pos);
+    }
+  }
+}
+
+/* Global 'feed' CustomEvent listener — same shape as AdiaFeed.post().
+   Idempotent (HMR-safe via window flag). */
+if (typeof window !== 'undefined' && !window.__adiaFeedListenerInstalled) {
+  window.__adiaFeedListenerInstalled = true;
+  window.addEventListener('feed', (e) => {
+    if (e?.detail && typeof e.detail === 'object') AdiaFeed.post(e.detail);
+  });
+}
+
+export { AdiaFeedContainer, AdiaFeedItem, AdiaFeed };

package/components/feed/feed.yaml

@@ -0,0 +1,33 @@
+# Generated alongside feed.js — kept in sync by hand for now (feed
+# is a Phase-1 skeleton; once it stabilizes, run the regen pipeline).
+$schema: ../../../../scripts/schemas/component.yaml.schema.json
+name: AdiaFeedContainer
+tag: feed-ui
+component: Feed
+category: container
+version: 1
+description: >-
+  Shared top-layer feed channel. Per docs/specs/feed-channel.md
+  (SPEC-FEED-CHANNEL-001). Per-position singletons mounted lazily into
+  document.body via Popover API; consumers post via the static API
+  (`AdiaFeed.post()`) or the global 'feed' CustomEvent.
+props:
+  position:
+    description: Lane the feed renders into
+    type: string
+    default: bottom-right
+    enum:
+      - top-left
+      - top-center
+      - top-right
+      - bottom-left
+      - bottom-center
+      - bottom-right
+      - inline
+  max:
+    description: Cap on simultaneously visible items per lane
+    type: number
+    default: 5
+events: {}
+slots: {}
+states: {}

package/components/index.js

@@ -30,6 +30,7 @@ export { AdiaChat } from './chat/chat.js';
 export { AdiaDrawer } from './drawer/drawer.js';
 export { AdiaModal } from './modal/modal.js';
 export { AdiaToast } from './toast/toast.js';
+export { AdiaFeedContainer, AdiaFeedItem, AdiaFeed } from './feed/feed.js';
 export { AdiaTabs } from './tabs/tabs.js';
 export { AdiaTab } from './tabs/tab.js';
 export { AdiaTooltip } from './tooltip/tooltip.js';
@@ -51,6 +52,7 @@ export { AdiaSkeleton } from './skeleton/skeleton.js';
 export { AdiaAlert } from './alert/alert.js';
 export { AdiaKbd } from './kbd/kbd.js';
 export { AdiaTag } from './tag/tag.js';
+export { AdiaSwatch } from './swatch/swatch.js';
 export { AdiaCol }   from './col/col.js';
 export { AdiaField } from './field/field.js';
 export { AdiaRow }   from './row/row.js';

package/components/swatch/swatch.a2ui.json

@@ -0,0 +1,116 @@
+{
+  "$schema": "https://json-schema.org/draft/2020-12/schema",
+  "$id": "https://adiaui.dev/a2ui/v0_9/components/Swatch.json",
+  "title": "Swatch",
+  "description": "Color/style swatch primitive — a small inline tile representing a single\nvisual sample. Renders as block, dot, square, line, or dashed depending on\nshape; pairs with an optional label slot or attribute. Composed by chart-\nlegend-ui's per-row swatch and consumed directly by the token-colors /\nspacing demo pages.\n",
+  "type": "object",
+  "allOf": [
+    {
+      "$ref": "common_types.json#/$defs/ComponentCommon"
+    },
+    {
+      "$ref": "common_types.json#/$defs/CatalogComponentCommon"
+    }
+  ],
+  "properties": {
+    "color": {
+      "description": "Swatch color. Accepts any CSS color value or var() reference. Sets the internal --swatch-color custom property; consumers can also set --swatch-color via inline style.",
+      "type": "string",
+      "default": ""
+    },
+    "component": {
+      "const": "Swatch"
+    },
+    "label": {
+      "description": "Optional label rendered next to (or below, for shape=\"block\") the swatch. Use the default slot for richer content.",
+      "type": "string",
+      "default": ""
+    },
+    "shape": {
+      "description": "Visual shape — block (filled tile), dot (small circle), square (small filled square), line (solid hairline), dashed (dashed hairline).",
+      "type": "string",
+      "enum": [
+        "block",
+        "dot",
+        "square",
+        "line",
+        "dashed"
+      ],
+      "default": "square"
+    },
+    "size": {
+      "description": "Size preset — sm / md / lg. Drives the swatch's intrinsic dimensions; lg is reserved for the token-scale demo (40 px tall).",
+      "type": "string",
+      "enum": [
+        "sm",
+        "md",
+        "lg"
+      ],
+      "default": "md"
+    }
+  },
+  "required": [
+    "component"
+  ],
+  "unevaluatedProperties": false,
+  "x-adiaui": {
+    "anti_patterns": [],
+    "category": "display",
+    "events": {},
+    "examples": [
+      {
+        "description": "A single dot swatch with text label, e.g. as a chart-legend row.",
+        "a2ui": "[\n  {\n    \"id\": \"root\",\n    \"component\": \"Swatch\",\n    \"shape\": \"dot\",\n    \"color\": \"var(--a-data-0)\",\n    \"label\": \"Revenue\"\n  }\n]",
+        "name": "basic-swatch"
+      },
+      {
+        "description": "Block swatch for a token-scale step.",
+        "a2ui": "[\n  {\n    \"id\": \"root\",\n    \"component\": \"Swatch\",\n    \"shape\": \"block\",\n    \"size\": \"lg\",\n    \"color\": \"var(--a-neutral-50)\",\n    \"label\": \"50\"\n  }\n]",
+        "name": "token-block"
+      }
+    ],
+    "keywords": [
+      "swatch",
+      "color",
+      "chip",
+      "sample",
+      "palette",
+      "legend",
+      "step",
+      "token"
+    ],
+    "name": "AdiaSwatch",
+    "related": [
+      "chart-legend-ui",
+      "tag-ui"
+    ],
+    "slots": {
+      "default": {
+        "description": "Optional rich label content. When present, replaces the [label] attribute's text."
+      }
+    },
+    "states": [
+      {
+        "description": "Default, ready for display.",
+        "name": "idle"
+      }
+    ],
+    "synonyms": {
+      "color-chip": [
+        "swatch",
+        "chip"
+      ],
+      "color-sample": [
+        "swatch"
+      ]
+    },
+    "tag": "swatch-ui",
+    "tokens": {
+      "--swatch-color": {
+        "description": "Resolved color of the swatch fill / line. Wins over the [color] attr if set inline."
+      }
+    },
+    "traits": [],
+    "version": 1
+  }
+}

package/components/swatch/swatch.css

@@ -0,0 +1,141 @@
+@scope (swatch-ui) {
+  :where(:scope) {
+    /* ── Layout ── */
+    --swatch-gap:               var(--a-space-2);
+
+    /* ── Sizes ──
+       The "tile" is the coloured shape; the label is plain text rendered
+       beside (or below, for shape="block") the tile. Tile dimensions are
+       size-driven; line shapes use a fixed thickness regardless of size. */
+    --swatch-tile-sm:           var(--a-space-2);          /* 8px ~ */
+    --swatch-tile-md:           var(--a-space-2-5);        /* 10px ~ */
+    --swatch-tile-lg:           40px;                       /* token-scale block */
+    --swatch-line-thickness:    2px;
+    --swatch-line-length:       calc(var(--swatch-tile-md) * 1.75);
+
+    /* ── Colors ──
+       Default colour falls back through the data palette so a bare
+       <swatch-ui> still renders something visible; consumers usually set
+       --swatch-color via [color] attr or inline style. */
+    --swatch-color:             var(--a-data-0);
+    --swatch-label-fg:          var(--a-fg-subtle);
+
+    /* ── Shape ── */
+    --swatch-radius-block:      var(--a-radius-sm);
+    --swatch-radius-square:     var(--a-radius-sm);
+
+    /* ── Block-shape extras (token-scale) ── */
+    --swatch-block-shadow:      inset 0 0 0 1px color-mix(in oklab, currentColor 8%, transparent);
+
+    /* ── Typography ── */
+    --swatch-label-size:        var(--a-ui-size);
+    --swatch-label-step-size:   10px;
+    --swatch-label-step-mt:     4px;
+  }
+
+  :scope {
+    /* Default: inline-flex row — tile + label side-by-side, vertically
+       centered. shape="block" overrides to flex-column (label sits below
+       the tile, mimicking the token-scale step layout). */
+    box-sizing: border-box;
+    display: inline-flex;
+    align-items: center;
+    gap: var(--swatch-gap);
+    min-width: 0;
+    color: var(--swatch-label-fg);
+    font-size: var(--swatch-label-size);
+    line-height: 1.2;
+    vertical-align: baseline;
+  }
+
+  /* The colored tile — sized by [size] + [shape] combinations below. */
+  :scope > [data-tile] {
+    box-sizing: border-box;
+    display: block;
+    flex-shrink: 0;
+    background: var(--swatch-color);
+    line-height: 0;
+  }
+
+  :scope > [data-label] {
+    min-width: 0;
+    overflow: hidden;
+    text-overflow: ellipsis;
+    white-space: nowrap;
+  }
+
+  :scope > [data-label][hidden] { display: none; }
+
+  /* ═══════ Shape: dot ═══════ */
+  :scope[shape="dot"] > [data-tile] {
+    width: var(--_size, var(--swatch-tile-md));
+    height: var(--_size, var(--swatch-tile-md));
+    border-radius: 50%;
+  }
+
+  /* ═══════ Shape: square ═══════ */
+  :scope[shape="square"] > [data-tile] {
+    width: var(--_size, var(--swatch-tile-md));
+    height: var(--_size, var(--swatch-tile-md));
+    border-radius: var(--swatch-radius-square);
+  }
+
+  /* ═══════ Shape: line (solid hairline) ═══════ */
+  :scope[shape="line"] > [data-tile] {
+    width: var(--swatch-line-length);
+    height: var(--swatch-line-thickness);
+    border-radius: var(--swatch-line-thickness);
+  }
+
+  /* ═══════ Shape: dashed (dashed hairline) ═══════ */
+  :scope[shape="dashed"] > [data-tile] {
+    width: var(--swatch-line-length);
+    height: var(--swatch-line-thickness);
+    background: transparent;
+    border-top: var(--swatch-line-thickness) dashed var(--swatch-color);
+  }
+
+  /* ═══════ Shape: block (token-scale tile) ═══════
+     Filled rectangle whose height grows with [size]; label sits BELOW
+     the tile (flex-column) so we can use it as a token-step swatch
+     without any extra wrapper. */
+  :scope[shape="block"] {
+    flex-direction: column;
+    align-items: stretch;
+    gap: 0;
+  }
+
+  :scope[shape="block"] > [data-tile] {
+    width: 100%;
+    height: var(--_block-h, var(--swatch-tile-lg));
+    border-radius: var(--swatch-radius-block);
+    box-shadow: var(--swatch-block-shadow);
+  }
+
+  :scope[shape="block"] > [data-label] {
+    text-align: center;
+    font-family: var(--a-font-family-code);
+    font-size: var(--swatch-label-step-size);
+    font-variant-numeric: tabular-nums;
+    color: var(--a-fg-muted);
+    margin-block-start: var(--swatch-label-step-mt);
+    white-space: nowrap;
+  }
+
+  /* ═══════ Sizes ═══════
+     Override the dot/square diameter (`--_size`) and the block-shape
+     height (`--_block-h`) for each size preset. Line/dashed widths use
+     --swatch-line-length so they stay consistent at all sizes. */
+  :scope[size="sm"] {
+    --_size: var(--swatch-tile-sm);
+    --_block-h: calc(var(--swatch-tile-lg) * 0.6);
+  }
+  :scope[size="md"] {
+    --_size: var(--swatch-tile-md);
+    --_block-h: calc(var(--swatch-tile-lg) * 0.75);
+  }
+  :scope[size="lg"] {
+    --_size: calc(var(--swatch-tile-md) * 1.4);
+    --_block-h: var(--swatch-tile-lg);
+  }
+}