@profpowell/vb-design-system 0.1.0

package/src/web-components/semantic-palette/static.html

@@ -0,0 +1,42 @@
+<!DOCTYPE html>
+<html lang="en">
+<head>
+  <meta charset="utf-8">
+  <meta name="viewport" content="width=device-width, initial-scale=1">
+  <title>Semantic Palette (Static Fallback)</title>
+  <style>
+    *, *::before, *::after { box-sizing: border-box; }
+    body {
+      font-family: system-ui, sans-serif;
+      line-height: 1.5;
+      max-inline-size: 40rem;
+      margin-inline: auto;
+      padding: 2rem 1rem;
+    }
+  </style>
+</head>
+<body>
+
+  <!--
+    Upgrade relationship
+    ====================
+    This static HTML is the baseline that <semantic-palette> enhances.
+    Without JS the colors list is still readable as a definition list.
+  -->
+
+  <h1>Semantic Palette</h1>
+
+  <noscript>
+    <p>This component works best with JavaScript enabled.</p>
+  </noscript>
+
+  <semantic-palette colors="#6366f1,#ec4899,#22c55e">
+    <dl>
+      <dt>primary</dt><dd>#6366f1</dd>
+      <dt>secondary</dt><dd>#ec4899</dd>
+      <dt>accent</dt><dd>#22c55e</dd>
+    </dl>
+  </semantic-palette>
+
+</body>
+</html>

package/src/web-components/semantic-palette/styles.css

@@ -0,0 +1,20 @@
+/**
+ * semantic-palette: interaction polish only.
+ * All layout is inline in logic.js; this file covers focus states and
+ * no-JS fallback hiding.
+ */
+
+semantic-palette[data-upgraded] > dl,
+semantic-palette[data-upgraded] > ul,
+semantic-palette[data-upgraded] > ol {
+  display: none;
+}
+
+semantic-palette .sp-export button:hover {
+  background: var(--color-surface-hover, var(--color-surface-raised, #f5f5f5));
+}
+
+semantic-palette .sp-export button:focus-visible {
+  outline: var(--focus-ring-width, 2px) solid var(--focus-ring-color, currentColor);
+  outline-offset: 2px;
+}

package/src/web-components/spacing-specimen/api.json

@@ -0,0 +1,63 @@
+{
+  "$schema": "../../../schemas/api.schema.json",
+  "element": "spacing-specimen",
+  "type": "web-component",
+  "description": "Design token spacing scale display",
+  "htmlvalidate": {
+    "flow": true,
+    "permittedContent": [
+      "@flow"
+    ]
+  },
+  "attributes": [
+    {
+      "name": "tokens",
+      "kind": "host-api",
+      "purpose": "config",
+      "type": "string",
+      "description": "Comma-separated token names to display"
+    },
+    {
+      "name": "prefix",
+      "kind": "host-api",
+      "purpose": "config",
+      "type": "string",
+      "description": "CSS variable prefix (default: \"--size-\")"
+    },
+    {
+      "name": "show-values",
+      "kind": "host-api",
+      "purpose": "config",
+      "type": "boolean",
+      "description": "Show computed px values (default: true)"
+    },
+    {
+      "name": "label",
+      "kind": "host-api",
+      "purpose": "config",
+      "type": "string",
+      "description": "Optional heading label"
+    },
+    {
+      "name": "editable",
+      "kind": "host-api",
+      "purpose": "config",
+      "type": "boolean",
+      "description": "Turn value cells into inputs that write the token on the target scope."
+    },
+    {
+      "name": "target",
+      "kind": "host-api",
+      "purpose": "config",
+      "type": "string",
+      "description": "CSS selector for the element to receive token overrides (default: \":root\"). Only used when editable."
+    }
+  ],
+  "events": [
+    {
+      "name": "spacing-specimen:change"
+    }
+  ],
+  "childAttributes": [],
+  "structure": []
+}

package/src/web-components/spacing-specimen/logic.js

@@ -0,0 +1,132 @@
+/**
+ * spacing-specimen: Design token spacing scale display
+ *
+ * Reads VB spacing tokens from computed styles and renders a visual
+ * scale with labeled bars and computed values. Auto-detects the current
+ * theme's spacing system.
+ *
+ * Uses CSS variables directly for bar widths (no JS measurement needed
+ * for rendering). Reads computed px values after paint for labels.
+ * All layout styles are inline so the component works without external CSS.
+ *
+ * @attr {string} tokens - Comma-separated token names to display
+ *   (default: "3xs,2xs,xs,s,m,l,xl,2xl,3xl")
+ * @attr {string} prefix - CSS variable prefix (default: "--size-")
+ * @attr {boolean} show-values - Show computed px values (default: true)
+ * @attr {string} label - Optional heading label
+ * @attr {boolean} editable - Turn value cells into inputs that write the token on target scope
+ * @attr {string} target - CSS selector for the element to receive token overrides (default: ":root")
+ *
+ * @fires spacing-specimen:change - When a token is edited. detail: { name, value, token, target }
+ *
+ * @example
+ * <spacing-specimen></spacing-specimen>
+ * <spacing-specimen tokens="xs,s,m,l,xl" label="Core Scale"></spacing-specimen>
+ * <spacing-specimen editable target=":root"></spacing-specimen>
+ */
+import { registerComponent } from '../../lib/bundle-registry.js';
+import { VBElement } from '../../lib/vb-element.js';
+
+class SpacingSpecimen extends VBElement {
+  static observedAttributes = ['tokens', 'prefix', 'show-values', 'label', 'editable', 'target'];
+
+  setup() {
+    this.#render();
+    this.#wireEditing();
+  }
+
+  attributeChangedCallback() {
+    if (this.isConnected) {
+      this.#render();
+      this.#wireEditing();
+    }
+  }
+
+  #render() {
+    const tokensAttr = this.getAttribute('tokens') || '3xs,2xs,xs,s,m,l,xl,2xl,3xl';
+    const prefix = this.getAttribute('prefix') || '--size-';
+    const showValues = this.getAttribute('show-values') !== 'false';
+    const label = this.getAttribute('label') || '';
+    const editable = this.hasAttribute('editable');
+
+    const tokens = tokensAttr.split(',').map(t => t.trim());
+
+    let html = '';
+
+    if (label) {
+      html += `<div style="font-size:0.75rem;font-weight:700;text-transform:uppercase;letter-spacing:0.08em;color:var(--color-text-muted,#666);margin-block-end:0.75rem;font-family:var(--font-sans,system-ui)">${label}</div>`;
+    }
+
+    html += `<div role="list" aria-label="${label || 'Spacing scale'}" style="display:flex;flex-direction:column;gap:0.25rem">`;
+
+    for (const name of tokens) {
+      const varName = `${prefix}${name}`;
+      const valueControl = editable
+        ? `<input type="text" class="scale-edit" data-token="${name}" aria-label="${name} value" style="font-family:var(--font-mono,monospace);font-size:0.75rem;padding:0.125rem 0.375rem;border:1px solid var(--color-border,#ccc);border-radius:var(--radius-s,0.25rem);background:var(--color-surface,#fff);color:var(--color-text,#222);inline-size:6rem;text-align:end">`
+        : (showValues ? `<span class="scale-value" style="font-family:var(--font-mono,monospace);font-size:0.75rem;color:var(--color-text-muted,#666);font-variant-numeric:tabular-nums;min-inline-size:3.5rem;text-align:end"></span>` : '');
+
+      html += `<div role="listitem" style="display:grid;grid-template-columns:3rem 1fr auto;align-items:center;gap:0.75rem;min-block-size:1.75rem">
+        <span style="font-family:var(--font-mono,monospace);font-size:0.875rem;color:var(--color-text-muted,#666);text-align:end">${name}</span>
+        <div class="scale-bar" style="display:block;block-size:var(--size-m,1rem);min-inline-size:2px;inline-size:var(${varName});background:var(--color-interactive,oklch(55% 0.2 260));border-radius:var(--radius-s,0.25rem)" aria-hidden="true"></div>
+        ${valueControl}
+      </div>`;
+    }
+
+    html += '</div>';
+    this.innerHTML = html;
+
+    // Read computed px values / fill edit inputs after paint
+    requestAnimationFrame(() => {
+      if (editable) {
+        const cs = getComputedStyle(this);
+        this.querySelectorAll('.scale-edit').forEach((node) => {
+          const input = /** @type {HTMLInputElement} */ (node);
+          const name = input.getAttribute('data-token');
+          const raw = cs.getPropertyValue(`${prefix}${name}`).trim();
+          input.value = raw || '';
+        });
+      } else if (showValues) {
+        this.querySelectorAll('.scale-bar').forEach((bar) => {
+          const px = bar.getBoundingClientRect().width;
+          const valueEl = bar.nextElementSibling;
+          if (valueEl) valueEl.textContent = `${Math.round(px * 100) / 100}px`;
+        });
+      }
+    });
+  }
+
+  #wireEditing() {
+    if (!this.hasAttribute('editable')) return;
+    const prefix = this.getAttribute('prefix') || '--size-';
+    this.querySelectorAll('.scale-edit').forEach((input) => {
+      this.listen(input, 'change', () => this.#applyTokenEdit(input, prefix));
+      this.listen(input, 'keydown', (e) => {
+        if (/** @type {KeyboardEvent} */ (e).key === 'Enter') this.#applyTokenEdit(input, prefix);
+      });
+    });
+  }
+
+  #applyTokenEdit(input, prefix) {
+    const name = input.getAttribute('data-token');
+    const value = input.value.trim();
+    if (!name || !value) return;
+    const target = /** @type {HTMLElement | null} */ (this.#resolveTarget());
+    const token = `${prefix}${name}`;
+    if (target) target.style.setProperty(token, value);
+    this.dispatchEvent(new CustomEvent('spacing-specimen:change', {
+      bubbles: true,
+      detail: { name, value, token, target: this.getAttribute('target') || ':root' },
+    }));
+  }
+
+  #resolveTarget() {
+    const sel = this.getAttribute('target') || ':root';
+    try {
+      return sel === ':root' ? document.documentElement : document.querySelector(sel);
+    } catch {
+      return document.documentElement;
+    }
+  }
+}
+
+registerComponent('spacing-specimen', SpacingSpecimen);

package/src/web-components/spacing-specimen/static.html

@@ -0,0 +1,71 @@
+<!DOCTYPE html>
+<html lang="en">
+<head>
+  <meta charset="utf-8">
+  <meta name="viewport" content="width=device-width, initial-scale=1">
+  <title>Spacing Specimen (Static Fallback)</title>
+  <style>
+    /*
+     * Static fallback for <spacing-specimen>.
+     *
+     * Upgrade relationship:
+     * When JavaScript loads and the <spacing-specimen> custom element is
+     * defined, it reads the VB spacing tokens from computed styles and
+     * renders a visual scale with labeled bars and computed pixel values.
+     *
+     * Without JS, this static page presents a simple list of spacing
+     * token names and their CSS custom property references, providing
+     * equivalent information through plain semantic HTML.
+     */
+
+    *, *::before, *::after { box-sizing: border-box; }
+
+    body {
+      font-family: system-ui, sans-serif;
+      line-height: 1.6;
+      margin: 0;
+      padding: 2rem;
+      color: #1a1a1a;
+      background: #f8f8f8;
+    }
+
+    h1 { margin-block-end: 1rem; }
+
+    dl {
+      display: grid;
+      grid-template-columns: 4rem 1fr;
+      gap: 0.5rem 1rem;
+      max-width: 30rem;
+    }
+
+    dt {
+      font-family: ui-monospace, monospace;
+      font-size: 0.875rem;
+      text-align: end;
+    }
+
+    dd {
+      margin: 0;
+      font-family: ui-monospace, monospace;
+      font-size: 0.875rem;
+      color: #666;
+    }
+  </style>
+</head>
+<body>
+  <h1>Spacing Scale</h1>
+  <p>These tokens define the spacing system. With JavaScript enabled, this becomes a visual bar chart.</p>
+
+  <dl>
+    <dt>3xs</dt><dd>var(--size-3xs)</dd>
+    <dt>2xs</dt><dd>var(--size-2xs)</dd>
+    <dt>xs</dt><dd>var(--size-xs)</dd>
+    <dt>s</dt><dd>var(--size-s)</dd>
+    <dt>m</dt><dd>var(--size-m)</dd>
+    <dt>l</dt><dd>var(--size-l)</dd>
+    <dt>xl</dt><dd>var(--size-xl)</dd>
+    <dt>2xl</dt><dd>var(--size-2xl)</dd>
+    <dt>3xl</dt><dd>var(--size-3xl)</dd>
+  </dl>
+</body>
+</html>

package/src/web-components/spacing-specimen/styles.css

@@ -0,0 +1,58 @@
+/* --- Progressive enhancement: no-JS fallback --- */
+spacing-specimen:not(:defined) {
+  display: block;
+}
+
+spacing-specimen {
+  display: block;
+}
+
+spacing-specimen .specimen-label {
+  display: block;
+  font-size: var(--font-size-xs, 0.75rem);
+  font-weight: 700;
+  text-transform: uppercase;
+  letter-spacing: 0.08em;
+  color: var(--color-text-muted, #666);
+  margin-block-end: var(--size-s, 0.75rem);
+  font-family: var(--font-sans, system-ui);
+}
+
+spacing-specimen .specimen-scale {
+  display: flex;
+  flex-direction: column;
+  gap: var(--size-2xs, 0.25rem);
+}
+
+spacing-specimen .scale-step {
+  display: grid;
+  grid-template-columns: 3rem 1fr auto;
+  align-items: center;
+  gap: var(--size-s, 0.75rem);
+  min-block-size: 1.75rem;
+}
+
+spacing-specimen .scale-name {
+  font-family: var(--font-mono, monospace);
+  font-size: var(--font-size-sm, 0.875rem);
+  color: var(--color-text-muted, #666);
+  text-align: end;
+}
+
+spacing-specimen .scale-bar {
+  display: block;
+  block-size: var(--size-m, 1rem);
+  min-inline-size: 2px;
+  background: var(--color-interactive, oklch(55% 0.2 260));
+  border-radius: var(--radius-s, 0.25rem);
+  transition: inline-size 0.3s ease;
+}
+
+spacing-specimen .scale-value {
+  font-family: var(--font-mono, monospace);
+  font-size: var(--font-size-xs, 0.75rem);
+  color: var(--color-text-muted, #666);
+  font-variant-numeric: tabular-nums;
+  min-inline-size: 3.5rem;
+  text-align: end;
+}

package/src/web-components/theme-catalog/api.json

@@ -0,0 +1,14 @@
+{
+  "$schema": "../../../schemas/api.schema.json",
+  "element": "theme-catalog",
+  "type": "web-component",
+  "description": "Browse and apply curated public design-system token sets (Material, IBM Carbon, Salesforce Lightning, GOV.UK, Atlassian, Tailwind, Bootstrap, Catppuccin Mocha). Renders a tile grid; clicking a tile fetches the entry's DTCG file and applies its tokens to a target preview scope via the same deserializer <theme-import> uses.",
+  "attributes": [
+    { "name": "target",       "kind": "host-api", "purpose": "config", "type": "string", "default": "#preview", "description": "CSS selector for the scope to apply tokens to. Tokens land as inline custom properties." },
+    { "name": "catalog-base", "kind": "host-api", "purpose": "config", "type": "string", "description": "Base URL for catalog files (manifest.json + entry .tokens.json). Defaults to /cdn/themes/catalog; override for hosted contexts." }
+  ],
+  "events": [
+    { "name": "theme-catalog:applied", "description": "Fired after an entry is applied. detail: { id, applied, ignored, tokens, source }" },
+    { "name": "theme-catalog:error",   "description": "Fired when fetch / parse / apply fails. detail: { id, error, phase }" }
+  ]
+}

package/src/web-components/theme-catalog/logic.js

@@ -0,0 +1,228 @@
+/**
+ * theme-catalog: Browse and apply curated public design-system token sets.
+ *
+ * Renders a tile grid of vendored DTCG entries (Material, IBM Carbon,
+ * Salesforce Lightning, GOV.UK, Atlassian, Tailwind, Bootstrap,
+ * Catppuccin Mocha). Clicking a tile fetches the entry's .tokens.json,
+ * deserializes it via the Phase 3 deserializer, and writes the resulting
+ * custom properties to a target scope (default #preview).
+ *
+ * Companion to <theme-import>. theme-import handles ad-hoc paste/file/URL
+ * imports; theme-catalog is the curated quick-start surface.
+ *
+ * @attr {string} target  - CSS selector for the scope to apply tokens to (default: "#preview").
+ * @attr {string} catalog-base - Base URL for the catalog files. Default auto-detects from the
+ *                               component path; override for hosted contexts.
+ *
+ * @fires theme-catalog:applied - When an entry is applied. detail: { id, applied, ignored, tokens, source }
+ * @fires theme-catalog:error   - On fetch / parse / apply failure. detail: { id, error, phase }
+ *
+ * @example
+ *   <theme-catalog target="#preview"></theme-catalog>
+ */
+
+import { registerComponent } from '../../lib/bundle-registry.js';
+import { VBElement } from '../../lib/vb-element.js';
+import { deserializeDTCG } from '../theme-import/dtcg-deserialize.js';
+
+class ThemeCatalog extends VBElement {
+  static observedAttributes = ['target', 'catalog-base'];
+
+  /** @type {any[] | null} */
+  #entries = null;
+  #lastAppliedId = '';
+
+  setup() {
+    this.#renderShell();
+    this.#loadAndRender();
+  }
+
+  attributeChangedCallback() {
+    if (this.isConnected && this.hasAttribute('data-upgraded')) {
+      this.#renderShell();
+      this.#loadAndRender();
+    }
+  }
+
+  #targetEl() {
+    const sel = this.getAttribute('target') || '#preview';
+    try {
+      return /** @type {HTMLElement|null} */ (document.querySelector(sel));
+    } catch {
+      return null;
+    }
+  }
+
+  /**
+   * Resolve the catalog base URL. The component is bundled into the VB
+   * core so it ships from the same origin as `dist/cdn/components/theme-catalog.js`.
+   * Catalog files live in src/web-components/theme-import/catalog/ — the
+   * publish pipeline copies them under dist/cdn/themes/catalog/ (Phase 4
+   * build step). Auto-detect from a known sibling import or accept an
+   * explicit `catalog-base` attribute override.
+   */
+  #base() {
+    const explicit = this.getAttribute('catalog-base');
+    if (explicit) return explicit.replace(/\/$/, '');
+    if (typeof window !== 'undefined' && /** @type {any} */ (window).__VB_CATALOG_BASE) {
+      return String(/** @type {any} */ (window).__VB_CATALOG_BASE).replace(/\/$/, '');
+    }
+    return '/cdn/themes/catalog';
+  }
+
+  #renderShell() {
+    const card  = `border:1px solid var(--color-border,#ddd);border-radius:var(--radius-m,0.5rem);background:var(--color-surface,#fff);padding:var(--size-m,1rem);display:flex;flex-direction:column;gap:var(--size-2xs,0.375rem);min-block-size:0`;
+    const grid  = `display:grid;grid-template-columns:repeat(auto-fill,minmax(14rem,1fr));gap:var(--size-s,0.75rem)`;
+    const muted = `font-size:var(--font-size-xs,0.75rem);color:var(--color-text-muted,#666)`;
+    const title = `margin:0;font-size:var(--font-size-md,1rem);font-weight:600;color:var(--color-text,#222)`;
+    const btn   = `align-self:flex-start;padding:0.375rem 0.75rem;border:1px solid var(--color-border,#ccc);border-radius:var(--radius-s,0.25rem);background:var(--color-primary,#0066cc);color:var(--color-text-on-primary,#fff);cursor:pointer;font:inherit;font-size:var(--font-size-xs,0.75rem)`;
+    const tag   = `display:inline-block;padding:0.125rem 0.375rem;border-radius:0.25rem;background:var(--color-surface-raised,#f3f3f3);${muted};margin-inline-end:0.25rem`;
+
+    this.innerHTML = `
+      <div class="tc-head" style="display:flex;align-items:baseline;gap:var(--size-s,0.75rem);margin-block-end:var(--size-s,0.75rem);flex-wrap:wrap">
+        <strong style="font-size:var(--font-size-sm,0.875rem)">Start from a known system</strong>
+        <span class="tc-target" style="${muted}"></span>
+      </div>
+      <div class="tc-grid" style="${grid}" role="list"></div>
+      <output class="tc-result" style="display:block;margin-block-start:var(--size-s,0.75rem);${muted}"></output>
+      <p class="tc-attribution" style="margin-block-start:var(--size-2xs,0.375rem);${muted}" hidden></p>
+      <details class="tc-ignored" style="margin-block-start:var(--size-2xs,0.375rem)" hidden>
+        <summary style="${muted};cursor:pointer">Ignored tokens</summary>
+        <ul class="tc-ignored-list" style="margin:var(--size-2xs,0.375rem) 0 0;padding-inline-start:1.25rem;${muted}"></ul>
+      </details>
+      <style>
+        :host ._card { ${card} }
+        :host ._title { ${title} }
+        :host ._btn { ${btn} }
+        :host ._tag { ${tag} }
+      </style>
+    `;
+
+    this.#refreshTargetLabel();
+  }
+
+  #refreshTargetLabel() {
+    const span = this.querySelector('.tc-target');
+    if (!span) return;
+    const sel = this.getAttribute('target') || '#preview';
+    const found = this.#targetEl();
+    span.textContent = found ? `Target: ${sel}` : `Target ${sel} not found`;
+  }
+
+  async #loadAndRender() {
+    const grid = this.querySelector('.tc-grid');
+    if (!grid) return;
+    try {
+      const res = await fetch(`${this.#base()}/manifest.json`);
+      if (!res.ok) throw new Error(`Catalog manifest fetch failed: ${res.status}`);
+      const manifest = await res.json();
+      this.#entries = manifest.entries || [];
+      this.#renderTiles();
+    } catch (err) {
+      grid.innerHTML = '';
+      const out = this.querySelector('.tc-result');
+      if (out) out.textContent = `Couldn't load catalog manifest: ${err && err.message ? err.message : String(err)}`;
+    }
+  }
+
+  #renderTiles() {
+    const grid = this.querySelector('.tc-grid');
+    if (!grid || !this.#entries) return;
+    const card = `border:1px solid var(--color-border,#ddd);border-radius:var(--radius-m,0.5rem);background:var(--color-surface,#fff);padding:var(--size-m,1rem);display:flex;flex-direction:column;gap:var(--size-2xs,0.375rem)`;
+    const title = `margin:0;font-size:var(--font-size-md,1rem);font-weight:600;color:var(--color-text,#222)`;
+    const btn   = `align-self:flex-start;margin-block-start:auto;padding:0.375rem 0.75rem;border:1px solid var(--color-border,#ccc);border-radius:var(--radius-s,0.25rem);background:var(--color-primary,#0066cc);color:var(--color-text-on-primary,#fff);cursor:pointer;font:inherit;font-size:var(--font-size-xs,0.75rem)`;
+    const muted = `font-size:var(--font-size-xs,0.75rem);color:var(--color-text-muted,#666)`;
+    const tag   = `display:inline-block;padding:0.125rem 0.375rem;border-radius:0.25rem;background:var(--color-surface-raised,#f3f3f3);${muted};margin-inline-end:0.25rem`;
+
+    grid.innerHTML = '';
+    for (const entry of this.#entries) {
+      const tile = document.createElement('article');
+      tile.setAttribute('role', 'listitem');
+      tile.setAttribute('data-id', entry.id);
+      tile.style.cssText = card;
+      tile.innerHTML = `
+        <h3 style="${title}">${escapeHTML(entry.name)}</h3>
+        <p style="${muted};margin:0">${escapeHTML(entry.summary || '')}</p>
+        <p style="${muted};margin:0">License: ${escapeHTML(entry.license)}</p>
+        <p style="margin:0">${(entry.tags || []).map((t) => `<span style="${tag}">${escapeHTML(t)}</span>`).join('')}</p>
+        <button type="button" class="tc-apply" style="${btn}" data-id="${escapeAttr(entry.id)}" aria-label="Apply ${escapeAttr(entry.name)} tokens">
+          Apply
+        </button>
+      `;
+      const btnEl = /** @type {HTMLButtonElement|null} */ (tile.querySelector('button.tc-apply'));
+      if (btnEl) this.listen(btnEl, 'click', () => this.#applyEntry(entry));
+      grid.appendChild(tile);
+    }
+  }
+
+  /**
+   * @param {{ id: string, name: string, file: string, attribution: string, source: string, license: string }} entry
+   */
+  async #applyEntry(entry) {
+    const target = this.#targetEl();
+    if (!target) {
+      this.#fail(entry.id, new Error(`Target ${this.getAttribute('target') || '#preview'} not found`), 'apply');
+      return;
+    }
+    try {
+      const res = await fetch(`${this.#base()}/${entry.file}`);
+      if (!res.ok) throw new Error(`Fetch failed: ${res.status}`);
+      const doc = await res.json();
+      const result = deserializeDTCG(doc);
+      for (const [name, value] of result.tokens) {
+        target.style.setProperty(name, value);
+      }
+      this.#showResult(entry, result);
+      this.#lastAppliedId = entry.id;
+      this.dispatchEvent(new CustomEvent('theme-catalog:applied', {
+        bubbles: true,
+        detail: { id: entry.id, applied: result.stats.applied, ignored: result.ignored, tokens: result.tokens, source: 'catalog' },
+      }));
+    } catch (err) {
+      this.#fail(entry.id, err, 'fetch-or-apply');
+    }
+  }
+
+  #showResult(entry, result) {
+    const out = this.querySelector('.tc-result');
+    if (out) {
+      out.textContent = `Applied ${result.stats.applied} token${result.stats.applied === 1 ? '' : 's'} from ${entry.name}${result.stats.ignored ? ` · ${result.stats.ignored} ignored` : ''}.`;
+    }
+    const att = /** @type {HTMLElement|null} */ (this.querySelector('.tc-attribution'));
+    if (att) {
+      att.hidden = false;
+      att.textContent = entry.attribution;
+    }
+    const ig = /** @type {HTMLDetailsElement|null} */ (this.querySelector('.tc-ignored'));
+    const list = this.querySelector('.tc-ignored-list');
+    if (ig && list) {
+      if (result.ignored.length === 0) {
+        ig.hidden = true;
+        list.innerHTML = '';
+      } else {
+        ig.hidden = false;
+        list.innerHTML = result.ignored.map((p) => `<li>${escapeHTML(p)}</li>`).join('');
+      }
+    }
+  }
+
+  #fail(id, err, phase) {
+    const out = this.querySelector('.tc-result');
+    if (out) out.textContent = `Error (${phase}): ${err && err.message ? err.message : String(err)}`;
+    this.dispatchEvent(new CustomEvent('theme-catalog:error', {
+      bubbles: true,
+      detail: { id, error: err, phase },
+    }));
+  }
+}
+
+function escapeHTML(s) {
+  return String(s).replace(/[&<>"']/g, (ch) => /** @type {Record<string,string>} */ ({
+    '&': '&amp;', '<': '&lt;', '>': '&gt;', '"': '&quot;', "'": '&#39;',
+  })[ch]);
+}
+function escapeAttr(s) { return escapeHTML(s); }
+
+registerComponent('theme-catalog', ThemeCatalog);
+
+export { ThemeCatalog };

package/src/web-components/theme-catalog/static.html

@@ -0,0 +1,15 @@
+<!DOCTYPE html>
+<html lang="en">
+<head>
+  <meta charset="utf-8">
+  <title>Theme Catalog (Static Fallback)</title>
+</head>
+<body>
+  <h1>Theme Catalog</h1>
+  <noscript><p>This component works best with JavaScript enabled.</p></noscript>
+  <theme-catalog target="#preview"></theme-catalog>
+  <section id="preview">
+    <p>Preview scope.</p>
+  </section>
+</body>
+</html>

package/src/web-components/theme-export/api.json

@@ -0,0 +1,18 @@
+{
+  "$schema": "../../../schemas/api.schema.json",
+  "element": "theme-export",
+  "type": "web-component",
+  "description": "Collects VB custom property overrides from a scope and emits them as a theme.css block (or JSON). The assembly glue for the Theme Composer.",
+  "attributes": [
+    { "name": "scope",    "kind": "host-api", "purpose": "config", "type": "string",  "default": ":root",  "description": "CSS selector for the scope to read overrides from." },
+    { "name": "selector", "kind": "host-api", "purpose": "config", "type": "string",  "default": ":root",  "description": "Selector written in the emitted CSS output." },
+    { "name": "include",  "kind": "host-api", "purpose": "config", "type": "string",  "description": "Comma-separated prefixes to collect. Default covers all VB token categories." },
+    { "name": "format",   "kind": "host-api", "purpose": "config", "type": "enum", "values": ["css", "json", "dtcg"], "default": "css", "description": "Output format. 'dtcg' emits Design Tokens Community Group JSON (stable spec 2025.10)." },
+    { "name": "vb-version", "kind": "host-api", "purpose": "config", "type": "string", "description": "Optional VB version string included in DTCG $extensions metadata." },
+    { "name": "label",    "kind": "host-api", "purpose": "config", "type": "string",  "description": "Optional heading label." },
+    { "name": "live",     "kind": "host-api", "purpose": "config", "type": "boolean", "description": "Re-scan whenever an editable specimen fires a :change event." }
+  ],
+  "events": [
+    { "name": "theme-export:change" }
+  ]
+}