@profpowell/vb-design-system 0.1.0

package/src/web-components/theme-import/dtcg-deserialize.js

@@ -0,0 +1,322 @@
+/**
+ * DTCG (Design Tokens Community Group) deserializer for VB.
+ *
+ * Pure function: takes a parsed DTCG object → returns
+ *   { tokens: Array<[name, value]>, ignored: string[], stats: {...} }
+ *
+ * Inverse of dtcg-serialize.js. Handles:
+ * - reverse prefix mapping (color/* → --color-*, etc.)
+ * - color rebuild from structured components (oklch / srgb)
+ * - dimension/duration/cubicBezier/shadow rebuild as CSS strings
+ * - light-dark variant folding back to light-dark()
+ * - $extensions["com.vanilla-breeze"] preference for round-trip-lossless
+ *   reconstruction (expression, lightDark literal, em/% units)
+ * - composite typography unpacking into VB scalars
+ * - {curly.brace} alias resolution (intra-document) → var(--…) output
+ * - group-level $type inheritance per spec
+ *
+ * Spec: https://www.designtokens.org/ (stable v1, 2025-10-28)
+ */
+
+const VB_NS = 'com.vanilla-breeze';
+
+/**
+ * @param {any} doc
+ * @returns {{ tokens: Array<[string, string]>, ignored: string[], stats: { applied: number, ignored: number } }}
+ */
+export function deserializeDTCG(doc) {
+  const tokens = [];
+  const ignored = [];
+  const tree = doc && typeof doc === 'object' ? doc : {};
+
+  // Walk the tree depth-first, propagating $type inheritance from groups.
+  walk(tree, [], undefined, tree, tokens, ignored);
+
+  return {
+    tokens,
+    ignored,
+    stats: { applied: tokens.length, ignored: ignored.length },
+  };
+}
+
+/* ---------- tree walk ---------- */
+
+function walk(node, path, inheritedType, root, tokens, ignored) {
+  if (!node || typeof node !== 'object') return;
+
+  // A token is an object that has $value OR is a variant container ($root/light/dark).
+  if ('$value' in node) {
+    handleToken(node, path, inheritedType ?? node.$type, root, tokens, ignored);
+    return;
+  }
+
+  // Variant container: presence of $root or both light+dark children that have $value.
+  if (isVariantContainer(node)) {
+    handleVariantToken(node, path, inheritedType ?? node.$type ?? 'color', root, tokens, ignored);
+    return;
+  }
+
+  // Otherwise it's a group — descend, inheriting $type if the group declares one.
+  const groupType = node.$type ?? inheritedType;
+  for (const [key, child] of Object.entries(node)) {
+    if (key.startsWith('$')) continue;
+    walk(child, [...path, key], groupType, root, tokens, ignored);
+  }
+}
+
+function isVariantContainer(node) {
+  // Variants are children with $value; the container itself has no $value.
+  const variants = ['$root', 'light', 'dark'];
+  return variants.some(k => node[k] && typeof node[k] === 'object' && '$value' in node[k]);
+}
+
+/* ---------- prefix reversal ---------- */
+
+/**
+ * Map a DTCG path back to the VB CSS custom-property name.
+ * Returns null if the path doesn't map to a known VB prefix.
+ *
+ * @param {string[]} path
+ * @returns {string | null}
+ */
+function pathToVar(path) {
+  const [head, second, ...rest] = path;
+  switch (head) {
+    case 'color': {
+      if (second === 'seeds') {
+        // color/seeds/{name} where name is the full token (hue-primary, lightness-primary, …)
+        return rest.length ? `--${rest.join('-')}` : null;
+      }
+      const tail = [second, ...rest].filter(Boolean).join('-');
+      return tail ? `--color-${tail}` : null;
+    }
+    case 'typography': {
+      const leaf = rest.join('-') || second;
+      const child = rest.length ? rest.join('-') : '';
+      switch (second) {
+        case 'family':        return child ? `--font-${child}` : null;
+        case 'size':          return child ? `--font-size-${child}` : null;
+        case 'weight':        return child ? `--font-weight-${child}` : null;
+        case 'lineHeight':    return child ? `--line-height-${child}` : null;
+        case 'letterSpacing': return child ? `--letter-spacing-${child}` : null;
+        default:              return null;
+      }
+      // (unreachable)
+      const _ = leaf;
+    }
+    case 'spacing':
+      return [second, ...rest].filter(Boolean).length ? `--size-${[second, ...rest].filter(Boolean).join('-')}` : null;
+    case 'border': {
+      const child = rest.join('-') || '';
+      if (second === 'radius') return child ? `--radius-${child}` : null;
+      if (second === 'width')  return child ? `--border-width-${child}` : null;
+      return null;
+    }
+    case 'motion': {
+      const child = rest.join('-') || '';
+      if (second === 'duration') return child ? `--duration-${child}` : null;
+      if (second === 'easing')   return child ? `--ease-${child}` : null;
+      return null;
+    }
+    case 'effect': {
+      const child = rest.join('-') || '';
+      if (second === 'shadow') return child ? `--shadow-${child}` : null;
+      return null;
+    }
+    default:
+      return null;
+  }
+}
+
+/* ---------- token handling ---------- */
+
+function handleToken(token, path, type, root, tokens, ignored) {
+  // Composite typography spans multiple VB scalars; check before pathToVar
+  // because the leaf name (e.g. "heading") doesn't have a single VB token.
+  if ((type === 'typography' || token.$type === 'typography')
+      && token.$value && typeof token.$value === 'object' && !Array.isArray(token.$value)
+      && path[0] === 'typography') {
+    unpackTypography(token, path, tokens);
+    return;
+  }
+
+  const cssVar = pathToVar(path);
+  if (!cssVar) {
+    ignored.push(path.join('.'));
+    return;
+  }
+
+  // Type inference from path when neither token nor group declared one.
+  // The DTCG spec forbids inferring from $value contents; path-based hints
+  // are part of group hierarchy and fine.
+  const effectiveType = type ?? inferTypeFromPath(path);
+
+  const ext = (token.$extensions && token.$extensions[VB_NS]) || {};
+
+  // Round-trip-lossless: prefer preserved CSS expression / literal.
+  if (ext.expression) { tokens.push([cssVar, ext.expression]); return; }
+  if (ext.lightDark)  { tokens.push([cssVar, ext.lightDark]);  return; }
+
+  const value = renderValue(token.$value, effectiveType, ext, root);
+  if (value == null) {
+    ignored.push(path.join('.'));
+    return;
+  }
+  tokens.push([cssVar, value]);
+}
+
+/**
+ * Infer a token type from its path (group-based, NOT $value-content-based).
+ * Mirrors the prefix table in pathToVar().
+ */
+function inferTypeFromPath(path) {
+  const [head, second] = path;
+  if (head === 'color')   return 'color';
+  if (head === 'spacing') return 'dimension';
+  if (head === 'border' && (second === 'radius' || second === 'width')) return 'dimension';
+  if (head === 'motion'   && second === 'duration') return 'duration';
+  if (head === 'motion'   && second === 'easing')   return 'cubicBezier';
+  if (head === 'effect'   && second === 'shadow')   return 'shadow';
+  if (head === 'typography') {
+    if (second === 'family')        return 'fontFamily';
+    if (second === 'size')          return 'dimension';
+    if (second === 'weight')        return 'fontWeight';
+    if (second === 'lineHeight')    return 'number';
+    if (second === 'letterSpacing') return 'dimension';
+  }
+  return undefined;
+}
+
+function handleVariantToken(node, path, type, root, tokens, ignored) {
+  const cssVar = pathToVar(path);
+  if (!cssVar) { ignored.push(path.join('.')); return; }
+  const ext = (node.$extensions && node.$extensions[VB_NS]) || {};
+  if (ext.lightDark) { tokens.push([cssVar, ext.lightDark]); return; }
+
+  const light = node.light?.$value ? renderValue(node.light.$value, type, {}, root) : null;
+  const dark  = node.dark?.$value  ? renderValue(node.dark.$value,  type, {}, root) : null;
+  const root_ = node.$root?.$value ? renderValue(node.$root.$value, type, {}, root) : null;
+
+  if (light && dark) {
+    tokens.push([cssVar, `light-dark(${light}, ${dark})`]);
+    return;
+  }
+  if (root_) { tokens.push([cssVar, root_]); return; }
+  if (light) { tokens.push([cssVar, light]); return; }
+  if (dark)  { tokens.push([cssVar, dark]);  return; }
+  ignored.push(path.join('.'));
+}
+
+/* ---------- value rendering ---------- */
+
+function renderValue(value, type, ext, root) {
+  // Alias: {group.token} → resolve and rebuild as var(--…) for cross-tool clarity.
+  if (typeof value === 'string' && /^\{[^}]+\}$/.test(value)) {
+    const targetPath = value.slice(1, -1).split('.');
+    const targetVar = pathToVar(targetPath);
+    if (targetVar) return `var(${targetVar})`;
+    // If unmappable target, fall back to literal.
+    return value;
+  }
+  switch (type) {
+    case 'color':       return renderColor(value, ext);
+    case 'fontFamily':  return renderFontFamily(value);
+    case 'fontWeight':  return String(value);
+    case 'number':      return renderNumber(value, ext);
+    case 'dimension':   return renderDimension(value, ext);
+    case 'duration':    return renderDuration(value);
+    case 'cubicBezier': return Array.isArray(value) ? `cubic-bezier(${value.join(', ')})` : null;
+    case 'shadow':      return renderShadow(value);
+    default:
+      // Best effort: stringify primitives.
+      if (typeof value === 'string' || typeof value === 'number') return String(value);
+      return null;
+  }
+}
+
+function renderColor(value, ext) {
+  if (!value || typeof value !== 'object') return null;
+  if (value.hex) return value.hex;
+  if (value.colorSpace === 'oklch') {
+    const [L, C, H] = value.components || [0, 0, 0];
+    const alpha = value.alpha != null ? ` / ${value.alpha}` : '';
+    return `oklch(${L} ${C} ${H}${alpha})`;
+  }
+  if (value.colorSpace === 'srgb') {
+    const [r, g, b] = value.components || [0, 0, 0];
+    const a = value.alpha;
+    if (a != null) {
+      return `rgba(${Math.round(r * 255)}, ${Math.round(g * 255)}, ${Math.round(b * 255)}, ${a})`;
+    }
+    return rgbToHex(r, g, b);
+  }
+  return null;
+}
+
+function rgbToHex(r, g, b) {
+  const h = (n) => Math.round(n * 255).toString(16).padStart(2, '0');
+  return `#${h(r)}${h(g)}${h(b)}`;
+}
+
+// CSS generic + system font keywords that should NOT be quoted.
+const BARE_FONT_KEYWORDS = new Set([
+  'serif', 'sans-serif', 'monospace', 'cursive', 'fantasy',
+  'system-ui', 'ui-serif', 'ui-sans-serif', 'ui-monospace', 'ui-rounded',
+  'math', 'emoji', 'fangsong',
+  '-apple-system', 'BlinkMacSystemFont',
+]);
+
+function renderFontFamily(value) {
+  if (typeof value === 'string') return value;
+  if (!Array.isArray(value)) return null;
+  return value.map((f) => {
+    if (BARE_FONT_KEYWORDS.has(f)) return f;
+    if (f.startsWith('"') || f.startsWith("'")) return f;
+    return `"${f}"`;
+  }).join(', ');
+}
+
+function renderNumber(value, ext) {
+  if (ext.unit === '%') return `${value}%`;
+  return String(value);
+}
+
+function renderDimension(value, ext) {
+  if (!value || typeof value !== 'object') return null;
+  // Honor VB extension unit hint (em, %) over the DTCG-stated unit.
+  const unit = ext.unit || value.unit || 'px';
+  return `${value.value}${unit}`;
+}
+
+function renderDuration(value) {
+  if (!value || typeof value !== 'object') return null;
+  return `${value.value}${value.unit || 'ms'}`;
+}
+
+function renderShadow(value) {
+  if (Array.isArray(value)) return value.map(renderShadowStop).filter(Boolean).join(', ');
+  return renderShadowStop(value);
+}
+
+function renderShadowStop(stop) {
+  if (!stop) return null;
+  const ox = renderDimension(stop.offsetX, {}) ?? '0px';
+  const oy = renderDimension(stop.offsetY, {}) ?? '0px';
+  const blur = renderDimension(stop.blur, {}) ?? '0px';
+  const spread = stop.spread ? ' ' + renderDimension(stop.spread, {}) : '';
+  const color = renderColor(stop.color, {}) ?? '#000';
+  return `${ox} ${oy} ${blur}${spread} ${color}`;
+}
+
+/* ---------- composite typography ---------- */
+
+function unpackTypography(token, path, tokens) {
+  const v = token.$value;
+  // Take the leaf segment as the token name (typography/heading → 'heading').
+  const leaf = path[path.length - 1];
+  if (v.fontFamily != null) tokens.push([`--font-${leaf}`,        renderFontFamily(v.fontFamily)]);
+  if (v.fontSize   != null) tokens.push([`--font-size-${leaf}`,   renderDimension(v.fontSize, {})]);
+  if (v.fontWeight != null) tokens.push([`--font-weight-${leaf}`, String(v.fontWeight)]);
+  if (v.lineHeight != null) tokens.push([`--line-height-${leaf}`, String(v.lineHeight)]);
+  if (v.letterSpacing != null) tokens.push([`--letter-spacing-${leaf}`, renderDimension(v.letterSpacing, {})]);
+}

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

@@ -0,0 +1,263 @@
+/**
+ * theme-import: Apply a DTCG tokens.json file to a preview scope.
+ *
+ * Sibling of <theme-export>. Three input modes — paste, file, URL — feed a
+ * pure deserializer that reverses VB's prefix mapping and rebuilds CSS
+ * values. Tokens land on the host's preview scope (default #preview),
+ * never on :root, so import experiments don't leak into the live site.
+ *
+ * Round-trip lossless for VB-authored DTCG: $extensions["com.vanilla-breeze"]
+ * preserves relative-color expressions, light-dark() literals, and em/% units.
+ *
+ * @attr {string} target - CSS selector for the scope to apply tokens to (default: "#preview").
+ * @attr {string} placeholder - Textarea placeholder. Default 'Paste DTCG tokens.json here…'.
+ *
+ * @fires theme-import:applied - When tokens are applied.
+ *   detail: { tokens, applied, ignored, source: 'paste'|'file'|'url' }
+ * @fires theme-import:error   - When parsing or fetch fails.
+ *   detail: { error, phase }
+ *
+ * @example
+ *   <theme-import target="#preview"></theme-import>
+ */
+
+import { registerComponent } from '../../lib/bundle-registry.js';
+import { VBElement } from '../../lib/vb-element.js';
+import { deserializeDTCG } from './dtcg-deserialize.js';
+
+class ThemeImport extends VBElement {
+  static observedAttributes = ['target', 'placeholder'];
+
+  setup() {
+    this.#render();
+    this.#wire();
+  }
+
+  attributeChangedCallback() {
+    if (this.isConnected && this.hasAttribute('data-upgraded')) {
+      this.#render();
+      this.#wire();
+    }
+  }
+
+  #targetEl() {
+    const sel = this.getAttribute('target') || '#preview';
+    try {
+      return /** @type {HTMLElement|null} */ (document.querySelector(sel));
+    } catch {
+      return null;
+    }
+  }
+
+  #render() {
+    const placeholder = this.getAttribute('placeholder') || 'Paste DTCG tokens.json here…';
+    const btn = `padding:0.375rem 0.75rem;border:1px solid var(--color-border,#ccc);border-radius:var(--radius-s,0.25rem);background:var(--color-surface,#fff);color:var(--color-text,#222);cursor:pointer;font:inherit;font-size:var(--font-size-xs,0.75rem)`;
+    const inp = `padding:0.375rem 0.5rem;border:1px solid var(--color-border,#ccc);border-radius:var(--radius-s,0.25rem);background:var(--color-surface,#fff);color:var(--color-text,#222);font:inherit;font-size:var(--font-size-xs,0.75rem)`;
+    const ta = `inline-size:100%;block-size:10rem;padding:var(--size-s,0.75rem);border:1px solid var(--color-border,#ccc);border-radius:var(--radius-s,0.25rem);background:var(--color-surface-sunken,#f8f8f8);color:var(--color-text,#222);font-family:var(--font-mono,monospace);font-size:var(--font-size-xs,0.75rem);white-space:pre;overflow:auto;tab-size:2;resize:vertical;box-sizing:border-box`;
+    const row = `display:flex;flex-wrap:wrap;gap:var(--size-2xs,0.375rem);align-items:center;margin-block-end:var(--size-s,0.5rem)`;
+    const muted = `font-size:var(--font-size-xs,0.75rem);color:var(--color-text-muted,#666)`;
+
+    this.innerHTML = `
+      <div class="ti-modes" role="tablist" aria-label="Import source" style="${row}">
+        <button type="button" class="ti-mode" data-mode="paste" style="${btn}" role="tab" aria-selected="true">Paste</button>
+        <button type="button" class="ti-mode" data-mode="file"  style="${btn}" role="tab" aria-selected="false">File</button>
+        <button type="button" class="ti-mode" data-mode="url"   style="${btn}" role="tab" aria-selected="false">URL</button>
+        <span style="${muted};margin-inline-start:auto" class="ti-target"></span>
+      </div>
+
+      <div class="ti-pane ti-pane-paste" role="tabpanel">
+        <textarea class="ti-paste" aria-label="DTCG JSON" placeholder="${placeholder}" style="${ta}"></textarea>
+        <div style="${row};margin-block-start:var(--size-2xs,0.375rem)">
+          <button type="button" class="ti-apply-paste" style="${btn}">Apply</button>
+        </div>
+      </div>
+
+      <div class="ti-pane ti-pane-file" role="tabpanel" hidden>
+        <label style="display:flex;flex-direction:column;gap:var(--size-2xs,0.375rem);${muted}">
+          <span>DTCG file (.tokens.json or .json)</span>
+          <input class="ti-file" type="file" accept=".json,.tokens,.tokens.json,application/json,application/design-tokens+json" style="${inp}">
+        </label>
+      </div>
+
+      <div class="ti-pane ti-pane-url" role="tabpanel" hidden>
+        <label style="display:flex;flex-direction:column;gap:var(--size-2xs,0.375rem);${muted}">
+          <span>DTCG URL (CORS-permitted host)</span>
+          <input class="ti-url" type="url" placeholder="https://example.com/theme.tokens.json" style="${inp}">
+        </label>
+        <div style="${row};margin-block-start:var(--size-2xs,0.375rem)">
+          <button type="button" class="ti-apply-url" style="${btn}">Fetch &amp; apply</button>
+        </div>
+      </div>
+
+      <output class="ti-result" style="display:block;margin-block-start:var(--size-s,0.5rem);${muted}"></output>
+
+      <details class="ti-ignored" style="margin-block-start:var(--size-2xs,0.375rem)" hidden>
+        <summary style="${muted};cursor:pointer">Ignored tokens</summary>
+        <ul class="ti-ignored-list" style="margin:var(--size-2xs,0.375rem) 0 0;padding-inline-start:1.25rem;${muted}"></ul>
+      </details>
+
+      <div style="${row};margin-block-start:var(--size-s,0.5rem)">
+        <button type="button" class="ti-reset" style="${btn}">Reset preview scope</button>
+      </div>
+    `;
+
+    this.#refreshTargetLabel();
+  }
+
+  #refreshTargetLabel() {
+    const span = this.querySelector('.ti-target');
+    if (!span) return;
+    const sel = this.getAttribute('target') || '#preview';
+    const found = this.#targetEl();
+    span.textContent = found ? `Target: ${sel}` : `Target ${sel} not found`;
+  }
+
+  #wire() {
+    for (const tab of this.querySelectorAll('.ti-mode')) {
+      this.listen(tab, 'click', () => this.#switchMode(/** @type {HTMLElement} */ (tab).dataset.mode || 'paste'));
+    }
+    const apply = this.querySelector('.ti-apply-paste');
+    if (apply) this.listen(apply, 'click', () => this.#applyFromPaste());
+    const file = /** @type {HTMLInputElement|null} */ (this.querySelector('.ti-file'));
+    if (file) this.listen(file, 'change', () => this.#applyFromFile(file));
+    const applyUrl = this.querySelector('.ti-apply-url');
+    if (applyUrl) this.listen(applyUrl, 'click', () => this.#applyFromURL());
+    const reset = this.querySelector('.ti-reset');
+    if (reset) this.listen(reset, 'click', () => this.#reset());
+  }
+
+  #switchMode(mode) {
+    for (const tab of this.querySelectorAll('.ti-mode')) {
+      const t = /** @type {HTMLElement} */ (tab);
+      const active = t.dataset.mode === mode;
+      t.setAttribute('aria-selected', String(active));
+    }
+    for (const pane of this.querySelectorAll('.ti-pane')) {
+      const p = /** @type {HTMLElement} */ (pane);
+      p.hidden = !p.classList.contains(`ti-pane-${mode}`);
+    }
+  }
+
+  #applyFromPaste() {
+    const ta = /** @type {HTMLTextAreaElement|null} */ (this.querySelector('.ti-paste'));
+    if (!ta) return;
+    this.#applyJSON(ta.value, 'paste');
+  }
+
+  /** @param {HTMLInputElement} input */
+  async #applyFromFile(input) {
+    const file = input.files?.[0];
+    if (!file) return;
+    try {
+      const text = await file.text();
+      this.#applyJSON(text, 'file');
+    } catch (err) {
+      this.#fail(err, 'file');
+    }
+  }
+
+  async #applyFromURL() {
+    const input = /** @type {HTMLInputElement|null} */ (this.querySelector('.ti-url'));
+    const url = input?.value?.trim();
+    if (!url) return;
+    try {
+      const res = await fetch(url, { mode: 'cors' });
+      if (!res.ok) throw new Error(`Fetch failed: ${res.status} ${res.statusText}`);
+      const text = await res.text();
+      this.#applyJSON(text, 'url');
+    } catch (err) {
+      this.#fail(err, 'url');
+    }
+  }
+
+  /**
+   * @param {string} text
+   * @param {'paste'|'file'|'url'} source
+   */
+  #applyJSON(text, source) {
+    let doc;
+    try {
+      doc = JSON.parse(text);
+    } catch (err) {
+      this.#fail(err, 'parse');
+      return;
+    }
+    const result = deserializeDTCG(doc);
+    const target = this.#targetEl();
+    if (!target) {
+      this.#fail(new Error(`Target ${this.getAttribute('target') || '#preview'} not found`), 'apply');
+      return;
+    }
+    for (const [name, value] of result.tokens) {
+      target.style.setProperty(name, value);
+    }
+    this.#showResult(result, source);
+    this.dispatchEvent(new CustomEvent('theme-import:applied', {
+      bubbles: true,
+      detail: {
+        tokens: result.tokens,
+        applied: result.stats.applied,
+        ignored: result.ignored,
+        source,
+      },
+    }));
+  }
+
+  #reset() {
+    const target = this.#targetEl();
+    if (!target) return;
+    // Strip any inline custom properties — anything starting with --.
+    const style = target.style;
+    const remove = [];
+    for (let i = 0; i < style.length; i++) {
+      const name = style.item(i);
+      if (name.startsWith('--')) remove.push(name);
+    }
+    for (const name of remove) style.removeProperty(name);
+
+    const out = this.querySelector('.ti-result');
+    if (out) out.textContent = `Cleared ${remove.length} custom properties from ${this.getAttribute('target') || '#preview'}.`;
+    const ig = this.querySelector('.ti-ignored');
+    if (ig) /** @type {HTMLDetailsElement} */ (ig).hidden = true;
+  }
+
+  #showResult(result, source) {
+    const out = this.querySelector('.ti-result');
+    if (out) {
+      out.textContent = `Applied ${result.stats.applied} token${result.stats.applied === 1 ? '' : 's'} from ${source}${result.stats.ignored ? ` · ${result.stats.ignored} ignored` : ''}.`;
+    }
+    const ig = this.querySelector('.ti-ignored');
+    const list = this.querySelector('.ti-ignored-list');
+    if (ig && list) {
+      const det = /** @type {HTMLDetailsElement} */ (ig);
+      if (result.ignored.length === 0) {
+        det.hidden = true;
+        list.innerHTML = '';
+      } else {
+        det.hidden = false;
+        list.innerHTML = result.ignored
+          .map((p) => `<li>${escapeHTML(p)}</li>`)
+          .join('');
+      }
+    }
+  }
+
+  #fail(err, phase) {
+    const out = this.querySelector('.ti-result');
+    if (out) out.textContent = `Error (${phase}): ${err && err.message ? err.message : String(err)}`;
+    this.dispatchEvent(new CustomEvent('theme-import:error', {
+      bubbles: true,
+      detail: { error: err, phase },
+    }));
+  }
+}
+
+function escapeHTML(s) {
+  return String(s).replace(/[&<>"']/g, (ch) => /** @type {Record<string,string>} */ ({
+    '&': '&amp;', '<': '&lt;', '>': '&gt;', '"': '&quot;', "'": '&#39;',
+  })[ch]);
+}
+
+registerComponent('theme-import', ThemeImport);
+
+export { ThemeImport };

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

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

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

@@ -0,0 +1,24 @@
+{
+  "$schema": "../../../schemas/api.schema.json",
+  "element": "token-specimen",
+  "type": "web-component",
+  "description": "Unified design token scale display. Renders shadows, radii, borders, colors, or sizes based on the type attribute.",
+  "htmlvalidate": {
+    "flow": true,
+    "permittedContent": ["@flow"]
+  },
+  "attributes": [
+    { "name": "type",        "kind": "host-api", "purpose": "config", "type": "enum", "values": ["shadow", "radius", "border", "color", "size", "icon"], "description": "Token type to display" },
+    { "name": "tokens",      "kind": "host-api", "purpose": "config", "type": "string",  "description": "Comma-separated token names (for icon type: comma-separated icon names). Defaults vary by type" },
+    { "name": "prefix",      "kind": "host-api", "purpose": "config", "type": "string",  "description": "CSS variable prefix (auto-set from type if omitted; ignored for icon type)" },
+    { "name": "show-values", "kind": "host-api", "purpose": "config", "type": "boolean", "default": "true", "description": "Show computed token values (for icon type: show icon name labels)" },
+    { "name": "label",       "kind": "host-api", "purpose": "config", "type": "string",  "description": "Optional heading label" },
+    { "name": "size",        "kind": "host-api", "purpose": "config", "type": "string",  "description": "Icon size (icon type only): xs, sm, md, lg, xl, 2xl" },
+    { "name": "icon-set",    "kind": "host-api", "purpose": "config", "type": "string",  "description": "Icon set (icon type only): lucide, phosphor, tabler, etc. Defaults to icon-wc's default" },
+    { "name": "editable",    "kind": "host-api", "purpose": "config", "type": "boolean", "description": "Turn value cells into inputs that write the token on the target scope. Ignored for icon type." },
+    { "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": "token-specimen:change" }
+  ]
+}