@profpowell/vb-design-system 0.1.0

package/src/web-components/palette-generator/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>Palette Generator (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 <palette-generator> enhances.
+
+    When JavaScript loads and the <palette-generator> 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>Palette Generator</h1>
+
+  <noscript>
+    <p>This component works best with JavaScript enabled.</p>
+  </noscript>
+
+  <!-- TODO: Add meaningful static fallback markup for <palette-generator> -->
+
+</body>
+</html>

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

@@ -0,0 +1,36 @@
+/**
+ * palette-generator styles
+ * Seed picker label/spacing and export toolbar hover states.
+ */
+
+palette-generator {
+  display: block;
+}
+
+palette-generator .pg-seed-label {
+  display: block;
+  font-size: var(--font-size-sm, 0.875rem);
+  font-weight: 600;
+  color: var(--color-text-muted, #666);
+  margin-block-end: var(--size-2xs, 0.25rem);
+}
+
+palette-generator > color-picker,
+palette-generator > input[type="color"] {
+  margin-block-end: var(--size-s, 0.75rem);
+  padding-block-end: var(--size-s, 0.75rem);
+  border-block-end: 1px solid var(--color-border-subtle, #e5e5e5);
+}
+
+palette-generator .pg-export {
+  margin-block-start: var(--size-s, 0.75rem);
+}
+
+palette-generator .pg-export button:hover {
+  background: var(--surface-hover, #f5f5f5);
+}
+
+palette-generator .pg-export button:focus-visible {
+  outline: var(--focus-ring-width, 2px) solid var(--focus-ring-color, currentColor);
+  outline-offset: 2px;
+}

package/src/web-components/semantic-palette/_color-math.js

@@ -0,0 +1,149 @@
+/**
+ * Color math helpers for semantic-palette.
+ * - hexToOklch / oklchToHex: round-trip sRGB hex ↔ OKLCh. Reference: Björn Ottosson's OKLab paper.
+ * - resolveToHex: normalize any CSS color string to #rrggbb via a DOM probe.
+ * - relativeLuminance + contrastRatio: WCAG 2.1 contrast for text-vs-background.
+ * - pickContrastingHex: black-or-white pick by perceived luminance.
+ */
+import { hexToRgb, rgbToHex } from '../color-picker/_color-utils.js';
+
+const srgbToLinear = (c) =>
+  c <= 0.04045 ? c / 12.92 : Math.pow((c + 0.055) / 1.055, 2.4);
+
+const linearToSrgb = (c) =>
+  c <= 0.0031308 ? 12.92 * c : 1.055 * Math.pow(c, 1 / 2.4) - 0.055;
+
+const clamp01 = (v) => (v < 0 ? 0 : v > 1 ? 1 : v);
+
+/**
+ * Convert a #rrggbb hex string into OKLCh.
+ * @param {string} hex
+ * @returns {{ l: number, c: number, h: number }} l is 0–1, c ≈ 0–0.4, h in degrees 0–360
+ */
+export function hexToOklch(hex) {
+  const { r, g, b } = hexToRgb(hex);
+  const lr = srgbToLinear(r / 255);
+  const lg = srgbToLinear(g / 255);
+  const lb = srgbToLinear(b / 255);
+
+  const lcone = 0.4122214708 * lr + 0.5363325363 * lg + 0.0514459929 * lb;
+  const mcone = 0.2119034982 * lr + 0.6806995451 * lg + 0.1073969566 * lb;
+  const scone = 0.0883024619 * lr + 0.2817188376 * lg + 0.6299787005 * lb;
+
+  const lp = Math.cbrt(lcone);
+  const mp = Math.cbrt(mcone);
+  const sp = Math.cbrt(scone);
+
+  const L = 0.2104542553 * lp + 0.7936177850 * mp - 0.0040720468 * sp;
+  const A = 1.9779984951 * lp - 2.4285922050 * mp + 0.4505937099 * sp;
+  const B = 0.0259040371 * lp + 0.7827717662 * mp - 0.8086757660 * sp;
+
+  const c = Math.sqrt(A * A + B * B);
+  let h = (Math.atan2(B, A) * 180) / Math.PI;
+  if (h < 0) h += 360;
+
+  return { l: L, c, h };
+}
+
+/**
+ * Convert OKLCh (l: 0–1, c: 0–~0.4, h: 0–360°) into a #rrggbb hex string.
+ * Gamut-clamps out-of-sRGB values to [0,1] before encoding.
+ */
+export function oklchToHex(l, c, h) {
+  const hr = (h * Math.PI) / 180;
+  const A = c * Math.cos(hr);
+  const B = c * Math.sin(hr);
+
+  const lp = l + 0.3963377774 * A + 0.2158037573 * B;
+  const mp = l - 0.1055613458 * A - 0.0638541728 * B;
+  const sp = l - 0.0894841775 * A - 1.2914855480 * B;
+
+  const lcone = lp * lp * lp;
+  const mcone = mp * mp * mp;
+  const scone = sp * sp * sp;
+
+  const lr =  4.0767416621 * lcone - 3.3077115913 * mcone + 0.2309699292 * scone;
+  const lg = -1.2684380046 * lcone + 2.6097574011 * mcone - 0.3413193965 * scone;
+  const lb = -0.0041960863 * lcone - 0.7034186147 * mcone + 1.7076147010 * scone;
+
+  const r = clamp01(linearToSrgb(lr));
+  const g = clamp01(linearToSrgb(lg));
+  const b = clamp01(linearToSrgb(lb));
+
+  return rgbToHex(Math.round(r * 255), Math.round(g * 255), Math.round(b * 255));
+}
+
+/**
+ * Resolve any CSS color string (hex, oklch, rgb, named) to a #rrggbb hex.
+ * Uses a DOM probe element to let the browser do color-space math.
+ * Returns null when the probe is unavailable or the string is invalid.
+ *
+ * @param {string} input
+ * @param {HTMLElement} [probeEl] optional reusable probe (span attached off-screen)
+ */
+export function resolveToHex(input, probeEl) {
+  if (!input) return null;
+  const s = String(input).trim();
+  if (/^#[0-9a-f]{6}$/i.test(s)) return s.toLowerCase();
+  if (/^#[0-9a-f]{3}$/i.test(s)) {
+    return ('#' + s.slice(1).split('').map((c) => c + c).join('')).toLowerCase();
+  }
+  if (typeof document === 'undefined') return null;
+
+  const probe = probeEl || document.createElement('span');
+  if (!probeEl) {
+    probe.style.display = 'none';
+    document.body.appendChild(probe);
+  }
+  probe.style.color = '';
+  probe.style.color = s;
+  const computed = getComputedStyle(probe).color;
+  if (!probeEl) probe.remove();
+
+  const m = computed.match(/rgba?\(\s*([0-9.]+)[\s,]+([0-9.]+)[\s,]+([0-9.]+)/);
+  if (!m) return null;
+  return rgbToHex(Math.round(+m[1]), Math.round(+m[2]), Math.round(+m[3]));
+}
+
+/**
+ * Format OKLCh values into a CSS oklch() string.
+ * @param {{l:number,c:number,h:number}} v
+ */
+export function formatOklch({ l, c, h }) {
+  return `oklch(${(l * 100).toFixed(1)}% ${c.toFixed(3)} ${h.toFixed(1)})`;
+}
+
+/** Relative luminance per WCAG 2.1 */
+export function relativeLuminance(hex) {
+  const { r, g, b } = hexToRgb(hex);
+  const channel = (v) => {
+    const s = v / 255;
+    return s <= 0.03928 ? s / 12.92 : Math.pow((s + 0.055) / 1.055, 2.4);
+  };
+  return 0.2126 * channel(r) + 0.7152 * channel(g) + 0.0722 * channel(b);
+}
+
+/** WCAG contrast ratio between two hex colors (1–21). */
+export function contrastRatio(hex1, hex2) {
+  const l1 = relativeLuminance(hex1);
+  const l2 = relativeLuminance(hex2);
+  const lighter = Math.max(l1, l2);
+  const darker = Math.min(l1, l2);
+  return (lighter + 0.05) / (darker + 0.05);
+}
+
+/**
+ * WCAG level for a ratio at normal text size.
+ * @param {number} ratio
+ * @returns {'AAA'|'AA'|'Fail'}
+ */
+export function wcagLevel(ratio) {
+  if (ratio >= 7) return 'AAA';
+  if (ratio >= 4.5) return 'AA';
+  return 'Fail';
+}
+
+/** Pick black or white for contrast against a given hex background. */
+export function pickContrastingHex(hex) {
+  return relativeLuminance(hex) > 0.4 ? '#000000' : '#ffffff';
+}

package/src/web-components/semantic-palette/api.json

@@ -0,0 +1,41 @@
+{
+  "$schema": "../../../schemas/api.schema.json",
+  "element": "semantic-palette",
+  "type": "web-component",
+  "description": "Preview a palette in use as VB semantic roles. Reads colors from a descendant <color-palette> or <palette-generator> and renders one preview card per role with per-pairing WCAG chips. Editing happens upstream in the palette; this component is a preview + theme CSS exporter.",
+  "attributes": [
+    {
+      "name": "colors",
+      "kind": "host-api",
+      "purpose": "config",
+      "type": "string",
+      "description": "Comma-separated hex palette (fallback when no <color-palette> or <palette-generator> child)."
+    },
+    {
+      "name": "roles",
+      "kind": "host-api",
+      "purpose": "config",
+      "type": "string",
+      "description": "Comma-separated roles in assignment order. Valid: primary, secondary, accent, success, warning, error, info. Default: \"primary,secondary,accent\"."
+    },
+    {
+      "name": "show-export",
+      "kind": "host-api",
+      "purpose": "config",
+      "type": "boolean",
+      "description": "Show Copy Theme CSS / Copy JSON toolbar."
+    },
+    {
+      "name": "label",
+      "kind": "host-api",
+      "purpose": "config",
+      "type": "string",
+      "description": "Optional heading label above the previews."
+    }
+  ],
+  "events": [
+    { "name": "semantic-palette:change" }
+  ],
+  "childAttributes": [],
+  "structure": []
+}

package/src/web-components/semantic-palette/logic.js

@@ -0,0 +1,400 @@
+/**
+ * semantic-palette: Preview a palette in use as VB semantic roles.
+ *
+ * Reads colors from a descendant <color-palette> or <palette-generator>
+ * (or its own `colors` attribute) and renders one preview card per role —
+ * button/link/badge for brand roles, alert/badge/inline for status roles —
+ * each with a per-pairing WCAG chip. Editing happens upstream in the palette;
+ * this component is a live preview that also exports a theme CSS block.
+ *
+ * @attr {string} colors - Comma-separated hex palette (fallback when no child source).
+ * @attr {string} roles - Comma-separated roles in assignment order. Default: "primary,secondary,accent".
+ *                        Valid: primary, secondary, accent, success, warning, error, info.
+ * @attr {boolean} show-export - Show Copy Theme CSS / Copy JSON toolbar.
+ * @attr {string} label - Optional heading label above the previews.
+ *
+ * @fires semantic-palette:change - On initial render and every palette update.
+ *   detail: { mapping: Record<role,hex>, tokens: string, source }
+ */
+import { registerComponent } from '../../lib/bundle-registry.js';
+import { VBElement } from '../../lib/vb-element.js';
+import { copyText } from '../../utils/copy-init.js';
+import {
+  hexToOklch,
+  oklchToHex,
+  formatOklch,
+  contrastRatio,
+  wcagLevel,
+  pickContrastingHex,
+  resolveToHex,
+} from './_color-math.js';
+import { generatePalette } from '../palette-generator/_palette-utils.js';
+
+const BRAND_ROLES = ['primary', 'secondary', 'accent'];
+const STATUS_ROLES = ['success', 'warning', 'error', 'info'];
+const ALL_ROLES = [...BRAND_ROLES, ...STATUS_ROLES];
+
+const ROLE_LABELS = {
+  primary: 'Primary', secondary: 'Secondary', accent: 'Accent',
+  success: 'Success', warning: 'Warning', error: 'Error', info: 'Info',
+};
+
+const LEVEL_COLORS = {
+  aaa:  { bg: 'oklch(92% 0.08 145)', fg: 'oklch(30% 0.12 145)' },
+  aa:   { bg: 'oklch(94% 0.08 90)',  fg: 'oklch(35% 0.12 70)' },
+  fail: { bg: 'oklch(92% 0.08 25)',  fg: 'oklch(35% 0.15 25)' },
+};
+
+const MONO = 'var(--font-mono, monospace)';
+const MUTED = 'var(--color-text-muted, #666)';
+const BORDER = 'var(--color-border, #ddd)';
+const SURFACE = 'var(--color-surface, #fff)';
+const TEXT = 'var(--color-text, #222)';
+const RADIUS_S = 'var(--radius-s, 0.25rem)';
+const RADIUS_M = 'var(--radius-m, 0.5rem)';
+
+class SemanticPalette extends VBElement {
+  static observedAttributes = ['colors', 'roles', 'show-export', 'label'];
+
+  /** @type {string[]} */ #colors = [];
+  /** @type {string[]} */ #roles = [];
+  /** @type {HTMLElement|null} */ #source = null;
+  /** @type {HTMLElement|null} */ #previews = null;
+  /** @type {HTMLElement|null} */ #probe = null;
+
+  setup() {
+    this.#probe = document.createElement('span');
+    this.#probe.style.cssText = 'position:absolute;visibility:hidden;pointer-events:none';
+    this.append(this.#probe);
+
+    this.#source = this.querySelector('color-palette, palette-generator');
+    this.#resolveRoles();
+    this.#readColors();
+    this.#renderShell();
+    this.#renderPreviews('init');
+    this.#wireSource();
+    this.#wireExport();
+    this.#emitChange('init');
+  }
+
+  attributeChangedCallback(name) {
+    if (!this.isConnected || !this.hasAttribute('data-upgraded')) return;
+    if (name === 'roles') this.#resolveRoles();
+    if (name === 'colors') this.#readColors();
+    // Shell (label/export toolbar) can safely re-render; it doesn't contain any picker
+    this.#renderShell();
+    this.#renderPreviews('attribute');
+    this.#wireExport();
+    this.#emitChange('attribute');
+  }
+
+  teardown() {
+    this.#probe?.remove();
+    this.#probe = null;
+  }
+
+  // ── Source + state ─────────────────────────────────────────────────
+
+  #readColors() {
+    // 1. color-palette child
+    const cp = this.querySelector('color-palette');
+    if (cp) {
+      if (typeof /** @type {any} */ (cp).colors !== 'undefined' && /** @type {any} */ (cp).colors.length) {
+        this.#colors = /** @type {any} */ (cp).colors.slice();
+        return;
+      }
+      const raw = cp.getAttribute('colors') || '';
+      const parsed = raw.split(',').map((s) => s.trim()).filter(Boolean);
+      if (parsed.length) { this.#colors = parsed; return; }
+    }
+    // 2. palette-generator child (derive from seed + harmony)
+    const pg = this.querySelector('palette-generator');
+    if (pg) {
+      const seed = pg.getAttribute('seed')
+        || /** @type {HTMLInputElement | null} */ (pg.querySelector('input[type="color"]'))?.value
+        || '';
+      const harmony = pg.getAttribute('harmony') || 'complementary';
+      if (seed) {
+        try {
+          const { colors } = generatePalette(seed, harmony);
+          this.#colors = colors.slice();
+          return;
+        } catch { /* fall through */ }
+      }
+    }
+    // 3. colors attribute
+    const raw = this.getAttribute('colors') || '';
+    this.#colors = raw.split(',').map((s) => s.trim()).filter(Boolean);
+  }
+
+  #resolveRoles() {
+    const raw = this.getAttribute('roles') || BRAND_ROLES.join(',');
+    const roles = raw
+      .split(',')
+      .map((s) => s.trim().toLowerCase())
+      .filter((r) => ALL_ROLES.includes(r));
+    this.#roles = roles.length ? roles : [...BRAND_ROLES];
+  }
+
+  #mapping() {
+    const map = {};
+    for (let i = 0; i < this.#roles.length; i++) {
+      map[this.#roles[i]] = this.#colors[i] || this.#colors[this.#colors.length - 1] || '#888888';
+    }
+    return map;
+  }
+
+  // ── Render ─────────────────────────────────────────────────────────
+
+  #renderShell() {
+    const existing = this.querySelector(':scope > .sp-shell');
+    if (existing) existing.remove();
+
+    const label = this.getAttribute('label');
+    const showExport = this.hasAttribute('show-export');
+
+    const shell = document.createElement('div');
+    shell.className = 'sp-shell';
+    shell.style.cssText = 'display:flex;flex-direction:column;gap:var(--size-m,1rem);margin-block-start:var(--size-s,0.75rem)';
+
+    if (label) {
+      const p = document.createElement('p');
+      p.style.cssText = 'font-weight:600;margin:0';
+      p.textContent = label;
+      shell.append(p);
+    }
+
+    const previews = document.createElement('section');
+    previews.className = 'sp-previews';
+    previews.setAttribute('aria-label', 'Role previews');
+    previews.style.cssText = `display:grid;grid-template-columns:repeat(auto-fill,minmax(min(22rem,100%),1fr));gap:var(--size-m,1rem)`;
+    shell.append(previews);
+    this.#previews = previews;
+
+    if (showExport) {
+      shell.insertAdjacentHTML('beforeend', this.#renderExport());
+    }
+
+    this.append(shell);
+  }
+
+  #renderPreviews(_source) {
+    if (!this.#previews) return;
+    const map = this.#mapping();
+    this.#previews.innerHTML = this.#roles.map((role) => this.#renderCard(role, map[role])).join('');
+  }
+
+  #renderCard(role, hex) {
+    const roleLabel = ROLE_LABELS[role] || role;
+    const isStatus = STATUS_ROLES.includes(role);
+    const samples = isStatus ? this.#renderStatusSamples(role, hex) : this.#renderBrandSamples(role, hex);
+    const cardStyle = `display:flex;flex-direction:column;gap:var(--size-s,0.75rem);padding:var(--size-m,1rem);border:1px solid ${BORDER};border-radius:${RADIUS_M};background:${SURFACE};min-inline-size:0`;
+
+    return `<article class="sp-card" data-role="${role}" aria-label="${roleLabel} role preview" style="${cardStyle}">
+      <header style="display:flex;align-items:center;justify-content:space-between;gap:var(--size-s,0.75rem)">
+        <div>
+          <code style="font-family:${MONO};font-size:var(--font-size-sm,0.875rem);font-weight:600">${role}</code>
+          <span style="display:block;font-size:var(--font-size-xs,0.75rem);color:${MUTED}">${roleLabel}</span>
+        </div>
+        <div style="display:flex;align-items:center;gap:0.5rem">
+          <span class="sp-swatch" style="display:inline-block;inline-size:1.75rem;block-size:1.75rem;border-radius:${RADIUS_S};border:1px solid oklch(0% 0 0 / 0.15);background:${hex}"></span>
+          <code style="font-family:${MONO};font-size:var(--font-size-xs,0.75rem);color:${MUTED}">${hex}</code>
+        </div>
+      </header>
+      <div class="sp-samples" style="display:flex;flex-wrap:wrap;gap:var(--size-s,0.75rem);align-items:flex-start">${samples}</div>
+    </article>`;
+  }
+
+  #renderBrandSamples(role, hex) {
+    const textOnRole = this.#resolveTextOnRole(role, hex);
+    const surface = this.#resolveSurface();
+    const subtleBg = this.#resolveSubtle(role, hex);
+    const subtleFg = this.#darken(hex);
+
+    return [
+      this.#sample({
+        render: `<button type="button" tabindex="-1" style="all:unset;display:inline-block;padding:0.375rem 0.875rem;border-radius:${RADIUS_S};background:${hex};color:${textOnRole};font-family:inherit;font-size:var(--font-size-sm,0.875rem);font-weight:600;cursor:default">Button</button>`,
+        fg: textOnRole, bg: hex, caption: 'On role',
+      }),
+      this.#sample({
+        render: `<span style="color:${hex};background:${surface};padding:0.25rem 0.5rem;border-radius:${RADIUS_S};font-size:var(--font-size-sm,0.875rem);font-weight:500;text-decoration:underline">Linked text</span>`,
+        fg: hex, bg: surface || '#ffffff', caption: 'On surface',
+      }),
+      this.#sample({
+        render: `<span style="display:inline-block;padding:0.125rem 0.5rem;border-radius:999px;background:${subtleBg};color:${subtleFg};font-size:var(--font-size-xs,0.75rem);font-weight:600;letter-spacing:0.04em;text-transform:uppercase">Badge</span>`,
+        fg: subtleFg, bg: subtleBg, caption: 'Subtle',
+      }),
+    ].join('');
+  }
+
+  #renderStatusSamples(role, hex) {
+    const surface = this.#resolveSurface();
+    const subtleBg = this.#resolveStatusSubtle(role, hex);
+    const statusText = this.#resolveStatusText(role, hex);
+    const onRole = pickContrastingHex(hex);
+
+    return [
+      this.#sample({
+        render: `<div style="display:flex;align-items:center;gap:0.5rem;padding:0.5rem 0.75rem;border-radius:${RADIUS_S};background:${subtleBg};color:${statusText};border:1px solid ${hex};font-size:var(--font-size-sm,0.875rem);max-inline-size:100%">
+          <span style="display:inline-block;inline-size:0.5rem;block-size:0.5rem;border-radius:50%;background:${hex};flex-shrink:0"></span>
+          <span><strong>${ROLE_LABELS[role] || role}</strong> — message text</span>
+        </div>`,
+        fg: statusText, bg: subtleBg, caption: 'Alert',
+      }),
+      this.#sample({
+        render: `<span style="display:inline-block;padding:0.125rem 0.5rem;border-radius:999px;background:${hex};color:${onRole};font-size:var(--font-size-xs,0.75rem);font-weight:700;letter-spacing:0.04em;text-transform:uppercase">${role}</span>`,
+        fg: onRole, bg: hex, caption: 'Badge',
+      }),
+      this.#sample({
+        render: `<span style="color:${hex};background:${surface};padding:0.25rem 0.5rem;border-radius:${RADIUS_S};font-size:var(--font-size-sm,0.875rem);font-weight:600">Inline status</span>`,
+        fg: hex, bg: surface || '#ffffff', caption: 'On surface',
+      }),
+    ].join('');
+  }
+
+  #sample({ render, fg, bg, caption }) {
+    const fgHex = resolveToHex(fg, this.#probe || undefined) || '#000000';
+    const bgHex = resolveToHex(bg, this.#probe || undefined) || '#ffffff';
+    const ratio = contrastRatio(fgHex, bgHex);
+    const level = wcagLevel(ratio).toLowerCase();
+    const lc = LEVEL_COLORS[level];
+    const chipStyle = `display:inline-flex;align-items:center;gap:0.25rem;padding:0.125rem 0.375rem;border-radius:${RADIUS_S};font-family:${MONO};font-size:var(--font-size-xs,0.75rem);background:${lc.bg};color:${lc.fg}`;
+    return `<div style="display:flex;flex-direction:column;gap:0.25rem;align-items:flex-start;min-inline-size:0;max-inline-size:100%">
+      <div style="max-inline-size:100%">${render}</div>
+      <div style="display:flex;align-items:center;gap:0.375rem;font-size:var(--font-size-xs,0.75rem);color:${MUTED}">
+        <span style="${chipStyle}" title="${caption}: ${ratio.toFixed(2)}:1">${ratio.toFixed(2)} <small>${level.toUpperCase()}</small></span>
+        <span>${caption}</span>
+      </div>
+    </div>`;
+  }
+
+  #renderExport() {
+    const toolbar = `display:flex;gap:var(--size-2xs,0.375rem);padding-block-start:var(--size-xs,0.5rem);border-block-start:1px solid ${BORDER}`;
+    const btn = `padding:0.375rem 0.875rem;border:1px solid ${BORDER};border-radius:${RADIUS_S};background:${SURFACE};color:${TEXT};cursor:pointer;font:inherit;font-size:var(--font-size-sm,0.875rem)`;
+    return `<div class="sp-export" role="toolbar" aria-label="Export semantic palette" style="${toolbar}">
+      <button type="button" class="sp-copy-css" style="${btn}">Copy Theme CSS</button>
+      <button type="button" class="sp-copy-json" style="${btn}">Copy JSON</button>
+    </div>`;
+  }
+
+  // ── Wiring ─────────────────────────────────────────────────────────
+
+  #wireSource() {
+    // color-palette edit events
+    const cp = this.querySelector('color-palette');
+    if (cp) {
+      this.listen(cp, 'color-palette:change', () => {
+        this.#readColors();
+        this.#renderPreviews('palette');
+        this.#emitChange('palette');
+      });
+    }
+    // palette-generator (legacy path — still supported)
+    const pg = this.querySelector('palette-generator');
+    if (pg) {
+      this.listen(pg, 'palette-generator:generate', () => {
+        this.#readColors();
+        this.#renderPreviews('palette');
+        this.#emitChange('palette');
+      });
+    }
+  }
+
+  #wireExport() {
+    const cssBtn = this.querySelector('.sp-copy-css');
+    const jsonBtn = this.querySelector('.sp-copy-json');
+    if (cssBtn) {
+      this.listen(cssBtn, 'click', () => {
+        copyText(this.#buildCSS(), {
+          button: /** @type {HTMLElement} */ (cssBtn),
+          announceMessage: 'Theme CSS copied',
+        });
+      });
+    }
+    if (jsonBtn) {
+      this.listen(jsonBtn, 'click', () => {
+        copyText(JSON.stringify(this.#mapping(), null, 2), {
+          button: /** @type {HTMLElement} */ (jsonBtn),
+          announceMessage: 'JSON copied',
+        });
+      });
+    }
+  }
+
+  // ── Token resolution ───────────────────────────────────────────────
+
+  #cs() { return getComputedStyle(this); }
+
+  #resolveSurface() {
+    return this.#cs().getPropertyValue('--color-surface').trim() || '#ffffff';
+  }
+
+  #resolveTextOnRole(role, fallbackHex) {
+    const explicit = this.#cs().getPropertyValue(`--color-text-on-${role}`).trim();
+    return explicit || pickContrastingHex(fallbackHex);
+  }
+
+  #resolveSubtle(role, fallbackHex) {
+    const explicit = this.#cs().getPropertyValue(`--color-${role}-subtle`).trim();
+    if (explicit) return explicit;
+    const { h } = hexToOklch(fallbackHex);
+    return oklchToHex(0.95, 0.03, h);
+  }
+
+  #resolveStatusSubtle(role, fallbackHex) {
+    const explicit = this.#cs().getPropertyValue(`--color-${role}-subtle`).trim();
+    if (explicit) return explicit;
+    const { h } = hexToOklch(fallbackHex);
+    return oklchToHex(0.94, 0.05, h);
+  }
+
+  #resolveStatusText(role, fallbackHex) {
+    const explicit = this.#cs().getPropertyValue(`--color-${role}-text`).trim();
+    if (explicit) return explicit;
+    const { h } = hexToOklch(fallbackHex);
+    return oklchToHex(0.3, 0.14, h);
+  }
+
+  #darken(hex) {
+    const { l, c, h } = hexToOklch(hex);
+    return oklchToHex(Math.max(0.2, l - 0.25), c, h);
+  }
+
+  // ── Export + emit ──────────────────────────────────────────────────
+
+  #buildCSS() {
+    const map = this.#mapping();
+    const brand = [];
+    const status = [];
+    for (const role of this.#roles) {
+      const hex = map[role];
+      if (!hex) continue;
+      const { l, c, h } = hexToOklch(hex);
+      if (BRAND_ROLES.includes(role)) {
+        brand.push(
+          `  --hue-${role}: ${h.toFixed(1)};`,
+          `  --lightness-${role}: ${(l * 100).toFixed(1)}%;`,
+          `  --chroma-${role}: ${c.toFixed(3)};`,
+        );
+      } else {
+        status.push(`  --color-${role}: ${formatOklch({ l, c, h })};`);
+      }
+    }
+    const parts = [];
+    if (brand.length) parts.push('  /* Brand seeds */', ...brand);
+    if (status.length) {
+      if (brand.length) parts.push('');
+      parts.push('  /* Status colors */', ...status);
+    }
+    return `:root {\n${parts.join('\n')}\n}\n`;
+  }
+
+  #emitChange(source) {
+    this.dispatchEvent(new CustomEvent('semantic-palette:change', {
+      bubbles: true,
+      detail: { mapping: this.#mapping(), tokens: this.#buildCSS(), source },
+    }));
+  }
+}
+
+registerComponent('semantic-palette', SemanticPalette);