@profpowell/vb-design-system 0.1.0

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

@@ -0,0 +1,256 @@
+/**
+ * token-specimen: Unified design token scale display
+ *
+ * One component for multiple token types — shadows, radii, borders,
+ * colors, and sizes. The `type` attribute controls rendering while
+ * sharing the same core API (tokens, prefix, show-values, label).
+ *
+ * Reads CSS custom properties and renders a visual specimen with
+ * computed values after paint. All layout is inline so the component
+ * works without external CSS.
+ *
+ * @attr {string} type - Token type: "shadow", "radius", "border", "color", "size", "icon"
+ * @attr {string} tokens - Comma-separated token names (defaults vary by type)
+ * @attr {string} prefix - CSS variable prefix (auto-set from type if omitted)
+ * @attr {boolean} show-values - Show computed values (default: true)
+ * @attr {string} label - Optional heading label
+ * @attr {string} size - Icon size (icon type only): xs, sm, md, lg, xl, 2xl
+ * @attr {string} icon-set - Icon set (icon type only, default: "lucide")
+ * @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 token-specimen:change - When a token is edited. detail: { name, value, token, target }
+ *
+ * @example
+ * <token-specimen type="shadow"></token-specimen>
+ * <token-specimen type="radius" tokens="s,m,l,xl,full"></token-specimen>
+ * <token-specimen type="icon" tokens="chevron-right,check,x,search"></token-specimen>
+ * <token-specimen type="color" editable></token-specimen>
+ */
+import { registerComponent } from '../../lib/bundle-registry.js';
+import { VBElement } from '../../lib/vb-element.js';
+
+const TYPE_DEFAULTS = {
+  shadow: {
+    prefix: '--shadow-',
+    tokens: 'xs,s,m,l,xl,2xl',
+  },
+  radius: {
+    prefix: '--radius-',
+    tokens: 'xs,s,m,l,xl,2xl,full',
+  },
+  border: {
+    prefix: '--border-width-',
+    tokens: 'thin,medium,thick',
+  },
+  color: {
+    prefix: '--color-',
+    tokens: 'primary,secondary,accent,success,warning,error,info',
+  },
+  size: {
+    prefix: '--size-',
+    tokens: '3xs,2xs,xs,s,m,l,xl,2xl,3xl',
+  },
+  icon: {
+    prefix: '',
+    tokens: 'home,search,settings,user,bell,heart,star,check,x,chevron-right,menu,trash',
+  },
+};
+
+const RENDERERS = {
+  shadow: renderShadow,
+  radius: renderRadius,
+  border: renderBorder,
+  color: renderColor,
+  size: renderSize,
+  icon: renderIcon,
+};
+
+class TokenSpecimen extends VBElement {
+  static observedAttributes = ['type', 'tokens', 'prefix', 'show-values', 'label', 'size', 'icon-set', 'editable', 'target'];
+
+  setup() { this.#render(); }
+
+  attributeChangedCallback() {
+    if (this.isConnected) this.#render();
+  }
+
+  #render() {
+    const type = this.getAttribute('type') || 'shadow';
+    const defaults = TYPE_DEFAULTS[type] || TYPE_DEFAULTS.shadow;
+    const prefix = this.getAttribute('prefix') || defaults.prefix;
+    const tokensAttr = this.getAttribute('tokens') || defaults.tokens;
+    const showValues = this.getAttribute('show-values') !== 'false';
+    const label = this.getAttribute('label') || '';
+    const tokens = tokensAttr.split(',').map(t => t.trim());
+
+    const renderer = RENDERERS[type] || RENDERERS.shadow;
+    let html = '';
+
+    if (label) {
+      html += `<p 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}</p>`;
+    }
+
+    html += renderer(tokens, prefix, showValues, this);
+    this.innerHTML = html;
+
+    const editable = this.hasAttribute('editable') && type !== 'icon';
+
+    if (showValues && type !== 'icon') {
+      requestAnimationFrame(() => {
+        this.#readComputedValues(type, prefix, tokens);
+        if (editable) this.#injectEditors(type, prefix);
+      });
+    } else if (editable) {
+      requestAnimationFrame(() => this.#injectEditors(type, prefix));
+    }
+  }
+
+  #injectEditors(type, prefix) {
+    const cs = getComputedStyle(this);
+    this.querySelectorAll('[data-token-value]').forEach((node) => {
+      const el = /** @type {HTMLElement} */ (node);
+      const name = el.dataset.tokenValue;
+      const raw = cs.getPropertyValue(`${prefix}${name}`).trim();
+      const input = document.createElement('input');
+      input.type = type === 'color' && /^#[0-9a-f]{3,8}$/i.test(raw) ? 'color' : 'text';
+      input.value = raw || '';
+      input.className = 'ts-edit';
+      input.setAttribute('data-token', name || '');
+      input.setAttribute('aria-label', `${name} value`);
+      input.style.cssText = `font-family:var(--font-mono,monospace);font-size:0.625rem;padding:0.125rem 0.25rem;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:${type === 'color' ? '3rem' : '100%'};${type === 'color' ? 'block-size:1.5rem;padding:0;' : 'max-inline-size:8rem;'}`;
+      el.replaceWith(input);
+      this.listen(input, 'change', () => this.#applyEdit(input, prefix));
+      this.listen(input, 'keydown', (e) => { if (/** @type {KeyboardEvent} */ (e).key === 'Enter') this.#applyEdit(input, prefix); });
+    });
+  }
+
+  #applyEdit(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('token-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;
+    }
+  }
+
+  #readComputedValues(type, prefix, tokens) {
+    const cs = getComputedStyle(this);
+    this.querySelectorAll('[data-token-value]').forEach(node => {
+      const el = /** @type {HTMLElement} */ (node);
+      const name = el.dataset.tokenValue;
+      const raw = cs.getPropertyValue(`${prefix}${name}`).trim();
+      if (type === 'radius' || type === 'size') {
+        // Show px for length values
+        const sample = this.querySelector(`[data-token-sample="${name}"]`);
+        if (sample) {
+          const prop = type === 'radius' ? 'borderRadius' : 'width';
+          const rect = type === 'size' ? sample.getBoundingClientRect().width : null;
+          el.textContent = rect != null
+            ? `${Math.round(rect * 100) / 100}px`
+            : raw || '—';
+        }
+      } else {
+        el.textContent = raw || '—';
+      }
+    });
+  }
+}
+
+// ── Type renderers ────────────────────────────────────────────
+
+function renderShadow(tokens, prefix, showValues) {
+  let html = `<div role="list" style="display:flex;flex-wrap:wrap;gap:1rem;align-items:end">`;
+  for (const name of tokens) {
+    html += `<div role="listitem" style="text-align:center">
+      <div style="width:7rem;height:5rem;background:var(--color-surface,#fff);border-radius:var(--radius-m,0.5rem);box-shadow:var(${prefix}${name})" aria-hidden="true"></div>
+      <p style="font-family:var(--font-mono,monospace);font-size:0.75rem;color:var(--color-text-muted,#666);margin-block-start:0.5rem">${name}</p>
+      ${showValues ? `<p data-token-value="${name}" style="font-family:var(--font-mono,monospace);font-size:0.625rem;color:var(--color-text-muted,#999);max-width:7rem;overflow:hidden;text-overflow:ellipsis;white-space:nowrap"></p>` : ''}
+    </div>`;
+  }
+  html += '</div>';
+  return html;
+}
+
+function renderRadius(tokens, prefix, showValues) {
+  let html = `<div role="list" style="display:flex;flex-wrap:wrap;gap:1rem;align-items:end">`;
+  for (const name of tokens) {
+    html += `<div role="listitem" style="text-align:center">
+      <div data-token-sample="${name}" style="width:4.5rem;height:4.5rem;background:var(--color-primary,oklch(55% 0.2 260));border-radius:var(${prefix}${name});display:flex;align-items:center;justify-content:center;color:#fff;font-size:0.75rem;font-family:var(--font-mono,monospace)" aria-hidden="true">${name}</div>
+      ${showValues ? `<p data-token-value="${name}" style="font-family:var(--font-mono,monospace);font-size:0.625rem;color:var(--color-text-muted,#999);margin-block-start:0.25rem"></p>` : ''}
+    </div>`;
+  }
+  html += '</div>';
+  return html;
+}
+
+function renderBorder(tokens, prefix, showValues) {
+  let html = `<div role="list" style="display:flex;flex-direction:column;gap:0.75rem">`;
+  for (const name of tokens) {
+    html += `<div role="listitem" style="display:grid;grid-template-columns:4rem 1fr auto;align-items:center;gap:0.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 style="border-block-start:var(${prefix}${name}) solid var(--color-text,#333);min-inline-size:4rem" aria-hidden="true"></div>
+      ${showValues ? `<span data-token-value="${name}" style="font-family:var(--font-mono,monospace);font-size:0.75rem;color:var(--color-text-muted,#666);font-variant-numeric:tabular-nums"></span>` : ''}
+    </div>`;
+  }
+  html += '</div>';
+  return html;
+}
+
+function renderColor(tokens, prefix, showValues) {
+  let html = `<div role="list" style="display:flex;flex-wrap:wrap;gap:0.75rem">`;
+  for (const name of tokens) {
+    html += `<div role="listitem" style="text-align:center">
+      <div style="width:4rem;height:3rem;background:var(${prefix}${name});border-radius:var(--radius-s,0.25rem);border:1px solid var(--color-border,#ddd)" aria-hidden="true"></div>
+      <p style="font-family:var(--font-mono,monospace);font-size:0.625rem;color:var(--color-text-muted,#666);margin-block-start:0.25rem">${name}</p>
+      ${showValues ? `<p data-token-value="${name}" style="font-family:var(--font-mono,monospace);font-size:0.5625rem;color:var(--color-text-muted,#999);max-width:4rem;overflow:hidden;text-overflow:ellipsis;white-space:nowrap"></p>` : ''}
+    </div>`;
+  }
+  html += '</div>';
+  return html;
+}
+
+function renderSize(tokens, prefix, showValues) {
+  let html = `<div role="list" style="display:flex;flex-direction:column;gap:0.25rem">`;
+  for (const name of tokens) {
+    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 data-token-sample="${name}" style="display:block;block-size:var(--size-m,1rem);min-inline-size:2px;inline-size:var(${prefix}${name});background:var(--color-interactive,oklch(55% 0.2 260));border-radius:var(--radius-s,0.25rem)" aria-hidden="true"></div>
+      ${showValues ? `<span data-token-value="${name}" 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>` : ''}
+    </div>`;
+  }
+  html += '</div>';
+  return html;
+}
+
+function renderIcon(tokens, _prefix, showValues, host) {
+  const size = host?.getAttribute('size') || 'md';
+  const iconSet = host?.getAttribute('icon-set') || '';
+  const setAttr = iconSet ? ` set="${iconSet}"` : '';
+  let html = `<div role="list" style="display:flex;flex-wrap:wrap;gap:1rem">`;
+  for (const name of tokens) {
+    html += `<div role="listitem" style="display:flex;flex-direction:column;align-items:center;gap:0.375rem;min-inline-size:4.5rem">
+      <span style="display:inline-flex;align-items:center;justify-content:center;padding:var(--size-s,0.75rem);background:var(--color-surface-raised,#f5f5f5);border-radius:var(--radius-s,0.25rem);border:1px solid var(--color-border,#ddd);color:var(--color-text,#222)">
+        <icon-wc name="${name}" size="${size}"${setAttr}></icon-wc>
+      </span>
+      ${showValues ? `<code style="font-family:var(--font-mono,monospace);font-size:0.625rem;color:var(--color-text-muted,#666);max-inline-size:5rem;overflow:hidden;text-overflow:ellipsis;white-space:nowrap">${name}</code>` : ''}
+    </div>`;
+  }
+  html += '</div>';
+  return html;
+}
+
+registerComponent('token-specimen', TokenSpecimen);

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

@@ -0,0 +1,47 @@
+<!DOCTYPE html>
+<html lang="en">
+<head>
+  <meta charset="utf-8">
+  <meta name="viewport" content="width=device-width, initial-scale=1">
+  <title>Token Specimen (Static Fallback)</title>
+  <style>
+    /*
+      Minimal baseline styling for the no-JS fallback.
+      A production page would load the project stylesheet instead;
+      these rules exist only so the file is self-contained.
+    */
+    *, *::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 <token-specimen> enhances.
+
+    When JavaScript loads and the <token-specimen> custom element is
+    defined, the markup is progressively enhanced with additional
+    interactivity, ARIA attributes, and keyboard navigation.
+
+    Without JS the core content remains accessible and functional.
+  -->
+
+  <h1>Token Specimen</h1>
+
+  <noscript>
+    <p>This component works best with JavaScript enabled.</p>
+  </noscript>
+
+  <!-- TODO: Add meaningful static fallback markup for <token-specimen> -->
+
+</body>
+</html>

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

@@ -0,0 +1,10 @@
+/* token-specimen: unified token scale display */
+
+token-specimen:not(:defined) {
+  display: block;
+  min-height: 2rem;
+}
+
+token-specimen {
+  display: block;
+}

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

@@ -0,0 +1,91 @@
+{
+  "$schema": "../../../schemas/api.schema.json",
+  "element": "type-specimen",
+  "type": "web-component",
+  "description": "Typography specimen display",
+  "htmlvalidate": {
+    "flow": true,
+    "permittedContent": [
+      "@flow"
+    ]
+  },
+  "attributes": [
+    {
+      "name": "font-family",
+      "kind": "host-api",
+      "purpose": "config",
+      "type": "string",
+      "description": "CSS font-family value"
+    },
+    {
+      "name": "label",
+      "kind": "host-api",
+      "purpose": "config",
+      "type": "string",
+      "description": "Display name for the font (optional, falls back to font-family)"
+    },
+    {
+      "name": "sample",
+      "kind": "host-api",
+      "purpose": "config",
+      "type": "string",
+      "description": "Custom sample text (default: \"The quick brown fox...\")"
+    },
+    {
+      "name": "show-scale",
+      "kind": "host-api",
+      "purpose": "config",
+      "type": "boolean",
+      "description": "Show VB type scale (xs–5xl)"
+    },
+    {
+      "name": "show-weights",
+      "kind": "host-api",
+      "purpose": "config",
+      "type": "boolean",
+      "description": "Show weight scale (100–900)"
+    },
+    {
+      "name": "show-characters",
+      "kind": "host-api",
+      "purpose": "config",
+      "type": "boolean",
+      "description": "Show character grid"
+    },
+    {
+      "name": "weights",
+      "kind": "host-api",
+      "purpose": "config",
+      "type": "string",
+      "description": "Comma-separated available weights (default: \"400,700\")"
+    },
+    {
+      "name": "editable",
+      "kind": "host-api",
+      "purpose": "config",
+      "type": "boolean",
+      "description": "Turn the font-family label into a live input + quick-picks that write a CSS custom property."
+    },
+    {
+      "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."
+    },
+    {
+      "name": "token",
+      "kind": "host-api",
+      "purpose": "config",
+      "type": "string",
+      "description": "Token name to write when editing (default: \"font-family-base\"). Only used when editable."
+    }
+  ],
+  "events": [
+    {
+      "name": "type-specimen:change"
+    }
+  ],
+  "childAttributes": [],
+  "structure": []
+}

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

@@ -0,0 +1,156 @@
+/**
+ * type-specimen: Typography specimen display
+ *
+ * Renders a font specimen with sample text, character grid, weight scale,
+ * and optional type scale display using VB's 9-step system.
+ *
+ * @attr {string} font-family - CSS font-family value
+ * @attr {string} label - Display name for the font (optional, falls back to font-family)
+ * @attr {string} sample - Custom sample text (default: "The quick brown fox...")
+ * @attr {boolean} show-scale - Show VB type scale (xs–5xl)
+ * @attr {boolean} show-weights - Show weight scale (100–900)
+ * @attr {boolean} show-characters - Show character grid
+ * @attr {string} weights - Comma-separated available weights (default: "400,700")
+ * @attr {boolean} editable - Turn the font-family label into a live input that writes a CSS custom property
+ * @attr {string} target - CSS selector for the element to receive token overrides (default: ":root")
+ * @attr {string} token - Token name to write when editing (default: "font-family-base")
+ *
+ * @fires type-specimen:change - When edited. detail: { fontFamily, token, target }
+ *
+ * @example
+ * <type-specimen font-family="Georgia" label="Georgia" show-characters show-weights></type-specimen>
+ * <type-specimen font-family="'Inter', sans-serif" editable show-scale></type-specimen>
+ */
+import { registerComponent } from '../../lib/bundle-registry.js';
+import { VBElement } from '../../lib/vb-element.js';
+
+const QUICK_FONTS = ['system-ui', 'Georgia', 'Inter, sans-serif', '"JetBrains Mono", monospace', 'Verdana', 'Cambria', 'ui-serif'];
+
+class TypeSpecimen extends VBElement {
+  static observedAttributes = ['font-family', 'label', 'sample', 'show-scale', 'show-weights', 'show-characters', 'weights', 'editable', 'target', 'token'];
+
+  setup() {
+    this.#render();
+    this.#wireEditing();
+  }
+
+  attributeChangedCallback() {
+    if (this.isConnected) {
+      this.#render();
+      this.#wireEditing();
+    }
+  }
+
+  #render() {
+    const fontFamily = this.getAttribute('font-family') || 'system-ui';
+    const label = this.getAttribute('label') || fontFamily.replace(/['"]/g, '').split(',')[0];
+    const sample = this.getAttribute('sample') || 'The quick brown fox jumps over the lazy dog';
+    const showScale = this.hasAttribute('show-scale');
+    const showWeights = this.hasAttribute('show-weights');
+    const showChars = this.hasAttribute('show-characters');
+    const weightsAttr = this.getAttribute('weights') || '300,400,500,600,700';
+    const weights = weightsAttr.split(',').map(w => w.trim());
+
+    let html = '';
+
+    const editable = this.hasAttribute('editable');
+
+    // Header with font name and large sample
+    const labelHTML = editable
+      ? `<input type="text" class="specimen-font-input" value="${fontFamily.replace(/"/g, '&quot;')}" aria-label="Font family" style="font:inherit;padding:0.25rem 0.5rem;border:1px solid var(--color-border,#ccc);border-radius:var(--radius-s,0.25rem);min-inline-size:18rem;max-inline-size:100%;font-family:${fontFamily};font-size:var(--font-size-sm,0.875rem)">
+          <span class="specimen-quick" style="display:inline-flex;flex-wrap:wrap;gap:0.25rem;margin-inline-start:0.5rem">
+            ${QUICK_FONTS.map((f) => `<button type="button" class="specimen-quick-btn" data-font="${f.replace(/"/g, '&quot;')}" style="font:inherit;font-size:var(--font-size-xs,0.75rem);padding:0.125rem 0.5rem;border:1px solid var(--color-border,#ccc);border-radius:999px;background:var(--color-surface,#fff);color:var(--color-text,#222);cursor:pointer">${f.split(',')[0].replace(/["']/g, '')}</button>`).join('')}
+          </span>`
+      : `<span class="specimen-label">${label}</span>`;
+
+    html += `<div class="specimen-header" style="font-family:${fontFamily}">
+      ${labelHTML}
+      <p class="specimen-sample" contenteditable="plaintext-only" spellcheck="false">${sample}</p>
+    </div>`;
+
+    // Character grid
+    if (showChars) {
+      html += `<div class="specimen-chars" style="font-family:${fontFamily}">
+        <div class="char-row"><span class="char-label">Upper</span>${'ABCDEFGHIJKLMNOPQRSTUVWXYZ'.split('').map(c => `<span>${c}</span>`).join('')}</div>
+        <div class="char-row"><span class="char-label">Lower</span>${'abcdefghijklmnopqrstuvwxyz'.split('').map(c => `<span>${c}</span>`).join('')}</div>
+        <div class="char-row"><span class="char-label">Digits</span>${'0123456789'.split('').map(c => `<span>${c}</span>`).join('')}</div>
+        <div class="char-row"><span class="char-label">Punct</span>${'!@#$%^&*()_+-=[]{}|;:,.<>?'.split('').map(c => `<span>${c === '<' ? '&lt;' : c === '>' ? '&gt;' : c === '&' ? '&amp;' : c}</span>`).join('')}</div>
+      </div>`;
+    }
+
+    // Weight scale
+    if (showWeights) {
+      html += `<div class="specimen-weights">`;
+      for (const w of weights) {
+        html += `<div class="weight-sample" style="font-family:${fontFamily};font-weight:${w}">
+          <span class="weight-label">${w}</span>
+          <span class="weight-text">Aa</span>
+        </div>`;
+      }
+      html += `</div>`;
+    }
+
+    // VB type scale
+    if (showScale) {
+      const scale = [
+        { name: 'xs', rem: 0.75 },
+        { name: 'sm', rem: 0.875 },
+        { name: 'md', rem: 1 },
+        { name: 'lg', rem: 1.125 },
+        { name: 'xl', rem: 1.25 },
+        { name: '2xl', rem: 1.5 },
+        { name: '3xl', rem: 1.875 },
+        { name: '4xl', rem: 2.25 },
+        { name: '5xl', rem: 3 },
+      ];
+      html += `<div class="specimen-scale">`;
+      for (const step of scale) {
+        html += `<div class="scale-step" style="font-family:${fontFamily};font-size:${step.rem}rem">
+          <span class="scale-label">${step.name}</span>
+          <span class="scale-text">${sample.substring(0, 30)}</span>
+        </div>`;
+      }
+      html += `</div>`;
+    }
+
+    this.innerHTML = html;
+  }
+
+  #wireEditing() {
+    if (!this.hasAttribute('editable')) return;
+    const input = /** @type {HTMLInputElement | null} */ (this.querySelector('.specimen-font-input'));
+    if (input) {
+      this.listen(input, 'input', () => this.#applyFontFamily(input.value));
+    }
+    this.querySelectorAll('.specimen-quick-btn').forEach((btn) => {
+      this.listen(btn, 'click', () => {
+        const font = btn.getAttribute('data-font') || '';
+        if (input) input.value = font;
+        this.#applyFontFamily(font);
+      });
+    });
+  }
+
+  #applyFontFamily(value) {
+    const target = /** @type {HTMLElement | null} */ (this.#resolveTarget());
+    const token = this.getAttribute('token') || 'font-family-base';
+    if (target) target.style.setProperty(`--${token}`, value);
+    // Update the attribute so the specimen re-renders with the new font
+    this.setAttribute('font-family', value);
+    this.dispatchEvent(new CustomEvent('type-specimen:change', {
+      bubbles: true,
+      detail: { fontFamily: 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('type-specimen', TypeSpecimen);

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

@@ -0,0 +1,84 @@
+<!DOCTYPE html>
+<html lang="en">
+<head>
+  <meta charset="utf-8">
+  <meta name="viewport" content="width=device-width, initial-scale=1">
+  <title>Type Specimen — Static Fallback</title>
+</head>
+<body>
+  <!--
+    Static fallback for <type-specimen>.
+
+    Upgrade relationship:
+    - Without JS: The font specimen is shown as static paragraphs at
+      different sizes, a character grid, and weight samples — all using
+      standard HTML and inline font-family styles. The content is readable
+      and demonstrates the typeface without any JavaScript.
+    - With JS: <type-specimen> reads `font-family`, `label`, `sample`,
+      `show-scale`, `show-weights`, and `show-characters` attributes to
+      dynamically render a specimen header with an editable sample text
+      (contenteditable), a character grid (upper, lower, digits, punctuation),
+      a weight scale (100-900), and the VB 9-step type scale (xs-5xl).
+
+    The static form preserves the core purpose — showing how a typeface
+    looks at different sizes and weights.
+  -->
+
+  <main>
+    <h1>Type Specimen</h1>
+
+    <section>
+      <h2 style="font-family: Georgia, serif">Georgia</h2>
+
+      <p style="font-family: Georgia, serif; font-size: 2.25rem">
+        The quick brown fox jumps over the lazy dog
+      </p>
+
+      <h3>Character Set</h3>
+      <p style="font-family: Georgia, serif; letter-spacing: 0.1em">
+        ABCDEFGHIJKLMNOPQRSTUVWXYZ<br>
+        abcdefghijklmnopqrstuvwxyz<br>
+        0123456789<br>
+        !@#$%^&amp;*()_+-=[]{}|;:,.&lt;&gt;?
+      </p>
+
+      <h3>Weights</h3>
+      <p style="font-family: Georgia, serif; font-weight: 400">
+        <strong>400</strong> — The quick brown fox jumps over the lazy dog
+      </p>
+      <p style="font-family: Georgia, serif; font-weight: 700">
+        <strong>700</strong> — The quick brown fox jumps over the lazy dog
+      </p>
+
+      <h3>Type Scale</h3>
+      <p style="font-family: Georgia, serif; font-size: 0.75rem">
+        <small>xs (0.75rem)</small> — The quick brown fox jumps over
+      </p>
+      <p style="font-family: Georgia, serif; font-size: 0.875rem">
+        <small>sm (0.875rem)</small> — The quick brown fox jumps over
+      </p>
+      <p style="font-family: Georgia, serif; font-size: 1rem">
+        <small>md (1rem)</small> — The quick brown fox jumps over
+      </p>
+      <p style="font-family: Georgia, serif; font-size: 1.125rem">
+        <small>lg (1.125rem)</small> — The quick brown fox jumps over
+      </p>
+      <p style="font-family: Georgia, serif; font-size: 1.25rem">
+        <small>xl (1.25rem)</small> — The quick brown fox jumps over
+      </p>
+      <p style="font-family: Georgia, serif; font-size: 1.5rem">
+        <small>2xl (1.5rem)</small> — The quick brown fox jumps over
+      </p>
+      <p style="font-family: Georgia, serif; font-size: 1.875rem">
+        <small>3xl (1.875rem)</small> — The quick brown fox jumps over
+      </p>
+      <p style="font-family: Georgia, serif; font-size: 2.25rem">
+        <small>4xl (2.25rem)</small> — The quick brown fox jumps
+      </p>
+      <p style="font-family: Georgia, serif; font-size: 3rem">
+        <small>5xl (3rem)</small> — The quick brown fox
+      </p>
+    </section>
+  </main>
+</body>
+</html>