@nghitrum/dsforge 0.1.1

package/dist/html-6SIG34W5.js

@@ -0,0 +1,2417 @@
+// src/generators/showcase/types.ts
+function esc(s) {
+  return s.replace(/&/g, "&amp;").replace(/</g, "&lt;").replace(/>/g, "&gt;");
+}
+function isHex(v) {
+  return /^#[0-9a-fA-F]{3,8}$/.test(v);
+}
+function hexLuminance(hex) {
+  const c = hex.replace("#", "");
+  const full = c.length === 3 ? c.split("").map((x) => x + x).join("") : c;
+  const r = parseInt(full.slice(0, 2), 16) / 255;
+  const g = parseInt(full.slice(2, 4), 16) / 255;
+  const b = parseInt(full.slice(4, 6), 16) / 255;
+  const toLinear = (x) => x <= 0.03928 ? x / 12.92 : ((x + 0.055) / 1.055) ** 2.4;
+  return 0.2126 * toLinear(r) + 0.7152 * toLinear(g) + 0.0722 * toLinear(b);
+}
+function textOnColor(hex) {
+  return hexLuminance(hex) > 0.35 ? "#111827" : "#ffffff";
+}
+function componentTokens(config, tokens) {
+  return {
+    action: tokens["semantic.color-action"] ?? "#2563eb",
+    actionHover: tokens["semantic.color-action-hover"] ?? "#1d4ed8",
+    actionText: tokens["semantic.color-text-on-color"] ?? "#ffffff",
+    bg: tokens["semantic.color-bg-default"] ?? "#ffffff",
+    border: tokens["semantic.color-border-default"] ?? "#e2e8f0",
+    text: tokens["semantic.color-text-primary"] ?? "#0f172a",
+    textSecondary: tokens["semantic.color-text-secondary"] ?? "#64748b",
+    radiusMd: config.radius?.["md"] ?? 4,
+    radiusLg: config.radius?.["lg"] ?? 8,
+    ff: config.typography?.fontFamily ?? "system-ui, sans-serif"
+  };
+}
+
+// src/lib/license.ts
+import { readFileSync } from "fs";
+import { join } from "path";
+function readKeyFromDotEnv() {
+  try {
+    const content = readFileSync(join(process.cwd(), ".env"), "utf8");
+    for (const raw of content.split("\n")) {
+      const line = raw.trim();
+      if (!line || line.startsWith("#")) continue;
+      const eq = line.indexOf("=");
+      if (eq === -1) continue;
+      const key = line.slice(0, eq).trim();
+      if (key !== "DSFORGE_KEY") continue;
+      const val = line.slice(eq + 1).trim().replace(/^["']|["']$/g, "");
+      return val || void 0;
+    }
+  } catch {
+  }
+  return void 0;
+}
+function isProUnlocked() {
+  const key = process.env["DSFORGE_KEY"] ?? readKeyFromDotEnv();
+  return typeof key === "string" && key.length > 0;
+}
+
+// src/generators/showcase/foundations.ts
+function buildColorSection(config, tokens) {
+  const groups = [];
+  const globalEntries = Object.entries(config.tokens?.global ?? {}).filter(([, v]) => isHex(String(v))).map(([k, v]) => ({ name: k, value: String(v) }));
+  if (globalEntries.length)
+    groups.push({ title: "Global Palette", items: globalEntries });
+  const semanticEntries = Object.entries(tokens).filter(([k, v]) => k.startsWith("semantic.color") && isHex(v)).map(([k, v]) => ({ name: k.replace("semantic.", ""), value: v }));
+  if (semanticEntries.length)
+    groups.push({ title: "Semantic Colors", items: semanticEntries });
+  return groups.map(
+    ({ title, items }) => `
+    <div class="section-block">
+      <h3 class="group-title">${esc(title)}</h3>
+      <div class="swatch-grid">
+        ${items.map(
+      ({ name, value }) => `
+          <div class="swatch" style="background:${value};color:${textOnColor(value)}">
+            <span class="swatch-name">${esc(name)}</span>
+            <span class="swatch-value">${esc(value)}</span>
+          </div>
+        `
+    ).join("")}
+      </div>
+    </div>
+  `
+  ).join("");
+}
+function buildTypographySection(config) {
+  const roles = config.typography?.roles ?? {};
+  const ff = config.typography?.fontFamily ?? "system-ui, sans-serif";
+  return `
+    <div class="section-block">
+      <h3 class="group-title">Font Family</h3>
+      <div class="type-family">${esc(ff)}</div>
+    </div>
+    <div class="section-block">
+      <h3 class="group-title">Type Scale</h3>
+      <div class="type-scale">
+        ${Object.entries(roles).map(([role, def]) => {
+    const size = typeof def === "object" && def !== null ? def["size"] : 16;
+    const weight = typeof def === "object" && def !== null ? def["weight"] : 400;
+    const lh = typeof def === "object" && def !== null ? def["lineHeight"] : 1.5;
+    return `
+            <div class="type-row">
+              <div class="type-meta">
+                <span class="type-role">${esc(role)}</span>
+                <span class="type-spec">${size}px / ${weight} / lh ${lh}</span>
+              </div>
+              <div class="type-sample" style="font-size:${size}px;font-weight:${weight};line-height:${lh};font-family:${esc(ff)}">
+                The quick brown fox
+              </div>
+            </div>
+          `;
+  }).join("")}
+      </div>
+    </div>
+  `;
+}
+function buildSpacingSection(config) {
+  const scale = config.spacing?.scale ?? {};
+  const baseUnit = config.spacing?.baseUnit ?? 4;
+  const row = (key, val) => `
+    <div class="spacing-row">
+      <span class="spacing-key">${esc(key)}</span>
+      <div class="spacing-bar-wrap">
+        <div class="spacing-bar" style="width:${Math.min(Number(val) * 2, 320)}px"></div>
+      </div>
+      <span class="spacing-val">${val}px</span>
+    </div>`;
+  return `
+    <div class="section-block">
+      <h3 class="group-title">Base Unit: ${baseUnit}px</h3>
+      <div class="spacing-list">
+        ${Object.entries(scale).map(([k, v]) => row(k, v)).join("")}
+      </div>
+    </div>
+    <div class="section-block">
+      <h3 class="group-title">Semantic Spacing</h3>
+      <div class="spacing-list">
+        ${Object.entries(config.spacing?.semantic ?? {}).map(([k, v]) => row(k, v)).join("")}
+      </div>
+    </div>
+  `;
+}
+function buildRadiusSection(config) {
+  const radius = config.radius ?? {};
+  return `
+    <div class="section-block">
+      <h3 class="group-title">Border Radius</h3>
+      <div class="radius-grid">
+        ${Object.entries(radius).map(
+    ([key, val]) => `
+          <div class="radius-item">
+            <div class="radius-box" style="border-radius:${val}px"></div>
+            <span class="radius-key">${esc(key)}</span>
+            <span class="radius-val">${val}px</span>
+          </div>
+        `
+  ).join("")}
+      </div>
+    </div>
+  `;
+}
+function buildElevationSection(config) {
+  const elevation = config.elevation ?? {};
+  return `
+    <div class="section-block">
+      <h3 class="group-title">Elevation</h3>
+      <div class="elevation-grid">
+        ${Object.entries(elevation).map(
+    ([key, val]) => `
+          <div class="elevation-item">
+            <div class="elevation-box" style="box-shadow:${val === "none" ? "none" : val}"></div>
+            <span class="elevation-key">Level ${esc(key)}</span>
+            <span class="elevation-val">${esc(String(val))}</span>
+          </div>
+        `
+  ).join("")}
+      </div>
+    </div>
+  `;
+}
+function buildMotionSection(config) {
+  const duration = config.motion?.duration ?? {};
+  const easing = config.motion?.easing ?? {};
+  const dot = (transitionStyle, onclick) => `
+    <div class="motion-track" onclick="${onclick}">
+      <div class="motion-dot" style="transition:${transitionStyle}"></div>
+    </div>`;
+  return `
+    <div class="section-block">
+      <h3 class="group-title">Duration</h3>
+      <div class="motion-grid">
+        ${Object.entries(duration).map(
+    ([key, val]) => `
+          <div class="motion-item" onclick="this.querySelector('.motion-dot').style.transform='translateX(120px)';setTimeout(()=>this.querySelector('.motion-dot').style.transform='',${val}+50)">
+            ${dot(`transform ${val}ms linear`, "")}
+            <span class="motion-key">${esc(key)}</span>
+            <span class="motion-val">${val}ms</span>
+            <span class="motion-hint">click to preview</span>
+          </div>
+        `
+  ).join("")}
+      </div>
+    </div>
+    <div class="section-block">
+      <h3 class="group-title">Easing</h3>
+      <div class="motion-grid">
+        ${Object.entries(easing).map(
+    ([key, val]) => `
+          <div class="motion-item" onclick="this.querySelector('.motion-dot').style.transform='translateX(120px)';setTimeout(()=>this.querySelector('.motion-dot').style.transform='',500)">
+            ${dot(`transform 500ms ${val}`, "")}
+            <span class="motion-key">${esc(key)}</span>
+            <span class="motion-val">${esc(String(val))}</span>
+            <span class="motion-hint">click to preview</span>
+          </div>
+        `
+  ).join("")}
+      </div>
+    </div>
+  `;
+}
+
+// src/generators/showcase/page.ts
+var lockedPanel = (label) => `
+  <div class="locked-panel">
+    <div class="locked-icon">\u2298</div>
+    <div class="locked-title">${label} \u2014 dsforge Pro</div>
+    <p class="locked-desc">This tab is available with a dsforge Pro license.</p>
+    <p class="locked-hint">Set the <code>DSFORGE_KEY</code> environment variable to unlock.</p>
+  </div>`;
+function buildComponentPage(def, isPro) {
+  const tabId = (tab) => `${def.id}-tab-${tab}`;
+  const panelId = (tab) => `${def.id}-panel-${tab}`;
+  const overviewHtml = `<div class="comp-overview">${def.overviewHtml}</div>`;
+  const propsTable = `
+    <table class="props-table">
+      <thead>
+        <tr>
+          <th>Prop</th>
+          <th>Required</th>
+          <th>Type</th>
+          <th>Default</th>
+          <th>Description</th>
+        </tr>
+      </thead>
+      <tbody>
+        ${def.props.map(
+    (p) => `
+          <tr>
+            <td><code class="prop-name">${esc(p.name)}</code></td>
+            <td class="prop-required-cell">
+              ${p.required ? '<span class="prop-required">Yes</span>' : '<span class="prop-optional">\u2014</span>'}
+            </td>
+            <td><code class="prop-type">${esc(p.type)}</code></td>
+            <td><code class="prop-default">${esc(p.default)}</code></td>
+            <td class="prop-desc">${esc(p.description)}</td>
+          </tr>`
+  ).join("")}
+      </tbody>
+    </table>`;
+  const examplesHtml = def.examples.map(
+    (ex, i) => `
+    <div class="example-block">
+      <div class="example-header">
+        <div class="example-label">${esc(ex.label)}</div>
+        <div class="example-desc">${esc(ex.description)}</div>
+      </div>
+      <div class="example-preview">${ex.previewHtml}</div>
+      <div class="example-code-wrap">
+        <div class="example-code-bar">
+          <span>TSX</span>
+          <button class="copy-btn" onclick="copyCode('${def.id}-ex-${i}', this)">Copy</button>
+        </div>
+        <pre class="example-code" id="${def.id}-ex-${i}">${esc(ex.code)}</pre>
+      </div>
+    </div>`
+  ).join("");
+  const a11yHtml = `
+    <div class="a11y-list">
+      ${def.a11y.map(
+    (item) => `
+        <div class="a11y-item">
+          <div class="a11y-header">
+            <span class="a11y-criterion">${esc(item.criterion)}</span>
+            <span class="a11y-badge a11y-badge-${item.level.toLowerCase()}">WCAG ${item.level}</span>
+          </div>
+          <p class="a11y-desc">${esc(item.description)}</p>
+        </div>`
+  ).join("")}
+    </div>`;
+  const aiJson = JSON.stringify(def.aiMeta, null, 2);
+  const aiHtml = `
+    <div class="ai-meta-intro">
+      <p>This JSON contract is emitted to <code>dist-ds/metadata/${def.id}.json</code>.
+      AI coding assistants use it to understand when and how to use this component correctly.</p>
+    </div>
+    <div class="example-code-wrap" style="margin-top:16px">
+      <div class="example-code-bar">
+        <span>JSON</span>
+        <button class="copy-btn" onclick="copyCode('${def.id}-ai-meta', this)">Copy</button>
+      </div>
+      <pre class="example-code" id="${def.id}-ai-meta">${esc(aiJson)}</pre>
+    </div>
+    <div class="ai-guidance">
+      <div class="group-title" style="margin-top:24px">AI usage guidance</div>
+      <ul class="ai-guidance-list">
+        ${def.aiMeta.aiGuidance.map((g) => `<li>${esc(g)}</li>`).join("")}
+      </ul>
+    </div>`;
+  const tabs = [
+    { id: "overview", label: "Overview", content: overviewHtml, locked: false },
+    { id: "props", label: "Props", content: propsTable, locked: false },
+    { id: "examples", label: "Examples", content: examplesHtml, locked: false },
+    {
+      id: "accessibility",
+      label: "Accessibility",
+      content: isPro ? a11yHtml : lockedPanel("Accessibility"),
+      locked: !isPro
+    },
+    {
+      id: "ai-metadata",
+      label: "AI Metadata",
+      content: isPro ? aiHtml : lockedPanel("AI Metadata"),
+      locked: !isPro
+    }
+  ];
+  return `
+    <div class="comp-tabs" id="${def.id}-tabs">
+      <div class="comp-tab-bar" role="tablist">
+        ${tabs.map(
+    (t, i) => `
+          <button
+            class="comp-tab${i === 0 ? " active" : ""}${t.locked ? " locked" : ""}"
+            id="${tabId(t.id)}"
+            role="tab"
+            aria-selected="${i === 0}"
+            aria-controls="${panelId(t.id)}"
+            onclick="${t.locked ? "return false" : `switchTab('${def.id}', '${t.id}', this)`}"
+            ${t.locked ? 'title="Unlock with dsforge Pro"' : ""}
+          >${esc(t.label)}${t.locked ? " &#x1F512;" : ""}</button>`
+  ).join("")}
+      </div>
+      ${tabs.map(
+    (t, i) => `
+        <div
+          class="comp-tab-panel${i === 0 ? " active" : ""}"
+          id="${panelId(t.id)}"
+          role="tabpanel"
+          aria-labelledby="${tabId(t.id)}"
+        >${t.content}</div>`
+  ).join("")}
+    </div>`;
+}
+
+// src/generators/showcase/components/button.ts
+function buttonDef(config, tokens) {
+  const { radiusMd, ff } = componentTokens(config, tokens);
+  const r = `${radiusMd}px`;
+  const s = (extra = "") => `style="font-family:${esc(ff)};${extra}"`;
+  const C = {
+    action: "var(--color-action, #2563eb)",
+    actionText: "var(--color-text-on-color, #fff)",
+    text: "var(--color-text-primary, #0f172a)"
+  };
+  return {
+    id: "button",
+    label: "Button",
+    description: "Triggers an action or event. Use for form submissions, dialogs, and in-page actions.",
+    overviewHtml: `
+      <div class="comp-overview-section">
+        <div class="comp-overview-label">Variants</div>
+        <div class="comp-preview-row">
+          <button class="ds-btn" ${s(`background:${C.action};color:${C.actionText};border-radius:${r}`)}>Primary</button>
+          <button class="ds-btn" ${s(`background:transparent;color:${C.action};border:1.5px solid ${C.action};border-radius:${r}`)}>Secondary</button>
+          <button class="ds-btn" ${s(`background:#dc2626;color:#fff;border-radius:${r}`)}>Danger</button>
+          <button class="ds-btn" ${s(`background:transparent;color:${C.text};border-radius:${r}`)}>Ghost</button>
+          <button class="ds-btn" ${s(`background:${C.action};color:${C.actionText};border-radius:${r};opacity:0.4;cursor:not-allowed`)} disabled>Disabled</button>
+        </div>
+      </div>
+      <div class="comp-overview-section">
+        <div class="comp-overview-label">Sizes</div>
+        <div class="comp-preview-row" style="align-items:center">
+          <button class="ds-btn" ${s(`background:${C.action};color:${C.actionText};border-radius:${r};font-size:12px;padding:4px 12px`)}>Small</button>
+          <button class="ds-btn" ${s(`background:${C.action};color:${C.actionText};border-radius:${r};font-size:14px;padding:8px 16px`)}>Medium</button>
+          <button class="ds-btn" ${s(`background:${C.action};color:${C.actionText};border-radius:${r};font-size:16px;padding:12px 24px`)}>Large</button>
+        </div>
+      </div>`,
+    props: [
+      {
+        name: "variant",
+        type: '"primary" | "secondary" | "danger" | "ghost"',
+        default: '"primary"',
+        required: false,
+        description: "Visual style of the button."
+      },
+      {
+        name: "size",
+        type: '"sm" | "md" | "lg"',
+        default: '"md"',
+        required: false,
+        description: "Controls padding and font size."
+      },
+      {
+        name: "disabled",
+        type: "boolean",
+        default: "false",
+        required: false,
+        description: "Prevents interaction and applies reduced opacity."
+      },
+      {
+        name: "loading",
+        type: "boolean",
+        default: "false",
+        required: false,
+        description: "Shows a spinner and disables the button."
+      },
+      {
+        name: "onClick",
+        type: "() => void",
+        default: "\u2014",
+        required: false,
+        description: "Callback fired on click."
+      },
+      {
+        name: "type",
+        type: '"button" | "submit" | "reset"',
+        default: '"button"',
+        required: false,
+        description: "Native button type. Always set explicitly inside forms."
+      },
+      {
+        name: "children",
+        type: "React.ReactNode",
+        default: "\u2014",
+        required: true,
+        description: "Button label. Prefer plain text; icons should have aria-label."
+      },
+      {
+        name: "className",
+        type: "string",
+        default: "\u2014",
+        required: false,
+        description: "Additional CSS classes on the root element."
+      }
+    ],
+    examples: [
+      {
+        label: "Basic usage",
+        description: "The default primary button.",
+        code: `<Button onClick={() => console.log('clicked')}>
+  Save changes
+</Button>`,
+        previewHtml: `<button class="ds-btn" ${s(`background:${C.action};color:${C.actionText};border-radius:${r}`)}>Save changes</button>`
+      },
+      {
+        label: "Danger action",
+        description: "Use the danger variant for destructive or irreversible actions.",
+        code: `<Button variant="danger" onClick={handleDelete}>
+  Delete account
+</Button>`,
+        previewHtml: `<button class="ds-btn" ${s(`background:#dc2626;color:#fff;border-radius:${r}`)}>Delete account</button>`
+      },
+      {
+        label: "Loading state",
+        description: "Pass loading to show a spinner while an async action is in progress.",
+        code: `<Button loading onClick={handleSubmit}>
+  Saving\u2026
+</Button>`,
+        previewHtml: `<button class="ds-btn" ${s(`background:${C.action};color:${C.actionText};border-radius:${r};opacity:0.7;cursor:not-allowed`)} disabled>\u27F3 &nbsp;Saving\u2026</button>`
+      },
+      {
+        label: "Button group",
+        description: "Combine secondary and primary for confirm/cancel pairs.",
+        code: `<div style={{ display: 'flex', gap: 8 }}>
+  <Button variant="secondary" onClick={onCancel}>Cancel</Button>
+  <Button onClick={onConfirm}>Confirm</Button>
+</div>`,
+        previewHtml: `<div style="display:flex;gap:8px">
+          <button class="ds-btn" ${s(`background:transparent;color:${C.action};border:1.5px solid ${C.action};border-radius:${r}`)}>Cancel</button>
+          <button class="ds-btn" ${s(`background:${C.action};color:${C.actionText};border-radius:${r}`)}>Confirm</button>
+        </div>`
+      }
+    ],
+    a11y: [
+      {
+        criterion: "1.3.1 Info and Relationships",
+        level: "A",
+        description: "Button role is conveyed via the native <button> element \u2014 no extra role attribute needed."
+      },
+      {
+        criterion: "1.4.3 Contrast (Minimum)",
+        level: "AA",
+        description: "Primary and danger variants are validated against WCAG AA (4.5:1 for text, 3:1 for UI components)."
+      },
+      {
+        criterion: "2.1.1 Keyboard",
+        level: "A",
+        description: "Fully operable with keyboard. Enter and Space activate the button. Tab moves focus."
+      },
+      {
+        criterion: "2.4.7 Focus Visible",
+        level: "AA",
+        description: "A visible focus ring is applied on :focus-visible. Never suppressed with outline:none."
+      },
+      {
+        criterion: "4.1.2 Name, Role, Value",
+        level: "A",
+        description: "Icon-only buttons must receive an aria-label. Loading state sets aria-busy='true'."
+      }
+    ],
+    aiMeta: {
+      component: "Button",
+      role: "action-trigger",
+      hierarchyLevel: "primary",
+      interactionModel: "synchronous",
+      layoutImpact: "inline",
+      destructiveVariants: ["danger"],
+      accessibilityContract: {
+        keyboard: true,
+        focusRing: "required",
+        ariaLabel: "required-for-icon-only",
+        ariaBusy: "set-when-loading"
+      },
+      variants: ["primary", "secondary", "danger", "ghost"],
+      aiGuidance: [
+        "Use primary for the single most important action on a surface.",
+        "Never place two primary buttons side by side.",
+        "Use danger only for irreversible destructive actions \u2014 always pair with a confirmation dialog.",
+        "Ghost is suitable for tertiary actions inside dense UI (toolbars, table rows)."
+      ]
+    }
+  };
+}
+
+// src/generators/showcase/components/input.ts
+function inputDef(config, tokens) {
+  const { radiusMd, ff } = componentTokens(config, tokens);
+  const r = `${radiusMd}px`;
+  const C = {
+    text: "var(--color-text-primary, #0f172a)",
+    textSecondary: "var(--color-text-secondary, #64748b)",
+    bg: "var(--color-bg-default, #fff)",
+    border: "var(--color-border-default, #e2e8f0)"
+  };
+  const fieldHtml = (label, opts, borderColor = C.border, helperHtml = "") => `
+    <div class="ds-field" style="font-family:${esc(ff)};max-width:320px">
+      <label class="ds-label" style="color:${C.text}">${label}</label>
+      <input class="ds-input" style="border-color:${borderColor};border-radius:${r};color:${C.text};background:${C.bg}" ${opts} />
+      ${helperHtml}
+    </div>`;
+  return {
+    id: "input",
+    label: "Input",
+    description: "Single-line text field. Covers all standard input types with label, helper text, and validation states.",
+    overviewHtml: `
+      <div class="comp-overview-section">
+        <div class="comp-overview-label">States</div>
+        <div class="comp-preview-col">
+          ${fieldHtml("Default", 'placeholder="Placeholder text"')}
+          ${fieldHtml("With value", 'value="Some input value"')}
+          ${fieldHtml(
+      "Error",
+      'value="invalid@"',
+      "#dc2626",
+      `<span style="font-size:12px;color:#dc2626;margin-top:2px">Enter a valid email address</span>`
+    )}
+          ${fieldHtml("Disabled", 'disabled placeholder="Disabled" style="opacity:0.5"')}
+        </div>
+      </div>`,
+    props: [
+      {
+        name: "label",
+        type: "string",
+        default: "\u2014",
+        required: true,
+        description: "Visible label rendered above the field. Also used as the accessible name."
+      },
+      {
+        name: "value",
+        type: "string",
+        default: "\u2014",
+        required: false,
+        description: "Controlled value. Pair with onChange."
+      },
+      {
+        name: "onChange",
+        type: "(value: string) => void",
+        default: "\u2014",
+        required: false,
+        description: "Fires on every keystroke."
+      },
+      {
+        name: "placeholder",
+        type: "string",
+        default: "\u2014",
+        required: false,
+        description: "Hint text shown when value is empty. Not a substitute for label."
+      },
+      {
+        name: "type",
+        type: '"text" | "email" | "password" | "number" | "search" | "tel" | "url"',
+        default: '"text"',
+        required: false,
+        description: "HTML input type."
+      },
+      {
+        name: "error",
+        type: "string",
+        default: "\u2014",
+        required: false,
+        description: "Validation message shown below the field. Triggers error styling."
+      },
+      {
+        name: "disabled",
+        type: "boolean",
+        default: "false",
+        required: false,
+        description: "Makes the field non-interactive."
+      },
+      {
+        name: "required",
+        type: "boolean",
+        default: "false",
+        required: false,
+        description: "Marks the field as required and sets aria-required."
+      },
+      {
+        name: "helperText",
+        type: "string",
+        default: "\u2014",
+        required: false,
+        description: "Supplementary text below the field (shown when no error)."
+      }
+    ],
+    examples: [
+      {
+        label: "Controlled input",
+        description: "Typical controlled usage with value and onChange.",
+        code: `const [email, setEmail] = useState('');
+
+<Input
+  label="Email address"
+  type="email"
+  value={email}
+  onChange={setEmail}
+  placeholder="you@example.com"
+/>`,
+        previewHtml: fieldHtml(
+          "Email address",
+          'type="email" placeholder="you@example.com"'
+        )
+      },
+      {
+        label: "With validation error",
+        description: "Pass an error string to show inline validation feedback.",
+        code: `<Input
+  label="Username"
+  value="ab"
+  error="Username must be at least 3 characters."
+/>`,
+        previewHtml: fieldHtml(
+          "Username",
+          'value="ab"',
+          "#dc2626",
+          `<span style="font-size:12px;color:#dc2626;margin-top:2px">Username must be at least 3 characters.</span>`
+        )
+      },
+      {
+        label: "Password field",
+        description: "type='password' masks the value automatically.",
+        code: `<Input
+  label="Password"
+  type="password"
+  required
+  helperText="Must be at least 8 characters."
+/>`,
+        previewHtml: `
+          <div class="ds-field" style="font-family:${esc(ff)};max-width:320px">
+            <label class="ds-label" style="color:${C.text}">Password <span style="color:#dc2626">*</span></label>
+            <input class="ds-input" type="password" style="border-color:${C.border};border-radius:${r};color:${C.text};background:${C.bg}" placeholder="\u2022\u2022\u2022\u2022\u2022\u2022\u2022\u2022" />
+            <span style="font-size:12px;color:${C.textSecondary};margin-top:2px">Must be at least 8 characters.</span>
+          </div>`
+      }
+    ],
+    a11y: [
+      {
+        criterion: "1.3.1 Info and Relationships",
+        level: "A",
+        description: "Every input is programmatically associated with its label via htmlFor/id. Never use placeholder as a label."
+      },
+      {
+        criterion: "1.4.3 Contrast (Minimum)",
+        level: "AA",
+        description: "Text, placeholder, and border colour all meet WCAG AA at the configured token values."
+      },
+      {
+        criterion: "3.3.1 Error Identification",
+        level: "A",
+        description: "When an error is present, the field receives aria-invalid='true' and aria-describedby pointing to the error message."
+      },
+      {
+        criterion: "3.3.2 Labels or Instructions",
+        level: "A",
+        description: "The label prop is always rendered as a visible <label> element. helperText is associated via aria-describedby."
+      },
+      {
+        criterion: "4.1.2 Name, Role, Value",
+        level: "A",
+        description: "required maps to aria-required. disabled maps to the native disabled attribute, preventing all interaction."
+      }
+    ],
+    aiMeta: {
+      component: "Input",
+      role: "data-entry",
+      hierarchyLevel: "atomic",
+      interactionModel: "continuous",
+      layoutImpact: "block",
+      destructiveVariants: [],
+      accessibilityContract: {
+        labelRequired: true,
+        ariaInvalidOnError: true,
+        ariaDescribedByForHelper: true,
+        ariaRequired: "mirrors-required-prop"
+      },
+      variants: ["default", "error", "disabled"],
+      aiGuidance: [
+        "Always provide a label \u2014 never rely on placeholder alone.",
+        "Use error to surface validation results inline, not via alert/toast.",
+        "For password fields always use type='password' \u2014 never type='text'.",
+        "Group related inputs inside a <fieldset> with a <legend> for screen readers."
+      ]
+    }
+  };
+}
+
+// src/generators/showcase/components/card.ts
+function cardDef(config, tokens) {
+  const { radiusMd, radiusLg, ff } = componentTokens(config, tokens);
+  const rMd = `${radiusMd}px`;
+  const rLg = `${radiusLg}px`;
+  const C = {
+    action: "var(--color-action, #2563eb)",
+    actionText: "var(--color-text-on-color, #fff)",
+    text: "var(--color-text-primary, #0f172a)",
+    textSecondary: "var(--color-text-secondary, #64748b)",
+    bg: "var(--color-bg-default, #fff)",
+    border: "var(--color-border-default, #e2e8f0)"
+  };
+  const cardHtml = (title, body, extraStyle = "", footerHtml = "") => `
+    <div class="ds-card" style="border-color:${C.border};border-radius:${rLg};background:${C.bg};color:${C.text};${extraStyle}">
+      <div class="ds-card-header" style="border-bottom:1px solid ${C.border}"><strong>${title}</strong></div>
+      <div class="ds-card-body"><p style="color:${C.textSecondary};margin:0;font-size:14px;font-family:${esc(ff)}">${body}</p></div>
+      ${footerHtml ? `<div class="ds-card-footer" style="border-top:1px solid ${C.border}">${footerHtml}</div>` : ""}
+    </div>`;
+  const footerBtn = `<button class="ds-btn" style="background:${C.action};color:${C.actionText};border-radius:${rMd};font-size:13px;padding:6px 14px;font-family:${esc(ff)}">Action</button>`;
+  return {
+    id: "card",
+    label: "Card",
+    description: "A surface that groups related content. Supports header, body, and optional footer slots.",
+    overviewHtml: `
+      <div class="comp-overview-section">
+        <div class="comp-overview-label">Variants</div>
+        <div class="comp-preview-row" style="align-items:flex-start;flex-wrap:wrap">
+          ${cardHtml("Default", "Bordered surface, no shadow.", "", footerBtn)}
+          ${cardHtml("Elevated", "Shadow replaces border.", `border-color:transparent;box-shadow:0 4px 6px -1px rgb(0 0 0 / 0.10)`)}
+          ${cardHtml("Outlined", "Stronger border, no shadow.", `border:2px solid ${C.border}`)}
+        </div>
+      </div>`,
+    props: [
+      {
+        name: "variant",
+        type: '"default" | "elevated" | "outlined"',
+        default: '"default"',
+        required: false,
+        description: "Visual style. Elevated uses box-shadow; outlined uses a heavier border."
+      },
+      {
+        name: "padding",
+        type: '"none" | "sm" | "md" | "lg"',
+        default: '"md"',
+        required: false,
+        description: "Inner padding of the card body."
+      },
+      {
+        name: "header",
+        type: "React.ReactNode",
+        default: "\u2014",
+        required: false,
+        description: "Content rendered in the card header slot."
+      },
+      {
+        name: "footer",
+        type: "React.ReactNode",
+        default: "\u2014",
+        required: false,
+        description: "Content rendered in the card footer slot."
+      },
+      {
+        name: "children",
+        type: "React.ReactNode",
+        default: "\u2014",
+        required: true,
+        description: "Main body content."
+      },
+      {
+        name: "className",
+        type: "string",
+        default: "\u2014",
+        required: false,
+        description: "Additional CSS classes on the root element."
+      }
+    ],
+    examples: [
+      {
+        label: "Basic card",
+        description: "Default bordered card with header, body, and a footer action.",
+        code: `<Card
+  header={<strong>Card title</strong>}
+  footer={<Button size="sm">Action</Button>}
+>
+  Card body content goes here.
+</Card>`,
+        previewHtml: cardHtml(
+          "Card title",
+          "Card body content goes here.",
+          "",
+          footerBtn
+        )
+      },
+      {
+        label: "Elevated card",
+        description: "Use elevated for surfaces that float above the page background.",
+        code: `<Card variant="elevated" header={<strong>Elevated</strong>}>
+  Uses box-shadow instead of a border.
+</Card>`,
+        previewHtml: cardHtml(
+          "Elevated",
+          "Uses box-shadow instead of a border.",
+          "border-color:transparent;box-shadow:0 4px 6px -1px rgb(0 0 0 / 0.10)"
+        )
+      },
+      {
+        label: "No header or footer",
+        description: "Header and footer are optional. Omit both for a simple content container.",
+        code: `<Card>
+  A minimal card with no header or footer \u2014 just body content.
+</Card>`,
+        previewHtml: `
+          <div class="ds-card" style="border-color:${C.border};border-radius:${rLg};background:${C.bg};color:${C.text}">
+            <div class="ds-card-body">
+              <p style="color:${C.textSecondary};margin:0;font-size:14px;font-family:${esc(ff)}">A minimal card with no header or footer.</p>
+            </div>
+          </div>`
+      }
+    ],
+    a11y: [
+      {
+        criterion: "1.3.1 Info and Relationships",
+        level: "A",
+        description: "Card is a <div> container \u2014 it carries no implicit role. If the card is a meaningful landmark, add role='region' and an aria-label."
+      },
+      {
+        criterion: "1.4.3 Contrast (Minimum)",
+        level: "AA",
+        description: "Text and border colour tokens are validated against WCAG AA at generate time."
+      },
+      {
+        criterion: "2.4.6 Headings and Labels",
+        level: "AA",
+        description: "The header slot should contain a heading element (<h2>\u2013<h4>) rather than bold text to preserve document outline."
+      },
+      {
+        criterion: "2.1.1 Keyboard",
+        level: "A",
+        description: "The card itself is not focusable. Interactive children (buttons, links) are reachable and operable by keyboard."
+      }
+    ],
+    aiMeta: {
+      component: "Card",
+      role: "content-container",
+      hierarchyLevel: "composite",
+      interactionModel: "passive",
+      layoutImpact: "block",
+      destructiveVariants: [],
+      accessibilityContract: {
+        implicitRole: "none",
+        addRoleRegionForLandmarks: true,
+        headerSlotShouldUseHeading: true
+      },
+      variants: ["default", "elevated", "outlined"],
+      aiGuidance: [
+        "Do not nest interactive cards inside other interactive cards.",
+        "If the entire card is clickable, use a single <a> or <button> wrapping the content \u2014 not onClick on the div.",
+        "Use header slot for a concise title; keep it to one line where possible.",
+        "Elevated variant is best on coloured or image backgrounds where a border would be lost."
+      ]
+    }
+  };
+}
+
+// src/generators/showcase/components/badge.ts
+function badgeDef(config, tokens) {
+  const { ff } = componentTokens(config, tokens);
+  const badgeHtml = (label, bg, color) => `<span style="display:inline-flex;align-items:center;font-family:${esc(ff)};font-size:12px;font-weight:500;padding:2px 8px;border-radius:9999px;background:${bg};color:${color};white-space:nowrap">${label}</span>`;
+  const variants = [
+    { label: "Default", bg: "#f1f5f9", color: "#6b7280" },
+    { label: "Success", bg: "#dcfce7", color: "#16a34a" },
+    { label: "Warning", bg: "#fef9c3", color: "#ca8a04" },
+    { label: "Danger", bg: "#fee2e2", color: "#dc2626" },
+    { label: "Info", bg: "#dbeafe", color: "#2563eb" }
+  ];
+  return {
+    id: "badge",
+    label: "Badge",
+    description: "Compact label for status, categories, or counts. Display-only \u2014 not interactive.",
+    overviewHtml: `
+      <div class="comp-overview-section">
+        <div class="comp-overview-label">Variants</div>
+        <div class="comp-preview-row">
+          ${variants.map((v) => badgeHtml(v.label, v.bg, v.color)).join("\n          ")}
+        </div>
+      </div>
+      <div class="comp-overview-section">
+        <div class="comp-overview-label">Sizes</div>
+        <div class="comp-preview-row" style="align-items:center">
+          <span style="display:inline-flex;align-items:center;font-family:${esc(ff)};font-size:11px;font-weight:500;padding:1px 6px;border-radius:9999px;background:#dbeafe;color:#2563eb">Small</span>
+          <span style="display:inline-flex;align-items:center;font-family:${esc(ff)};font-size:12px;font-weight:500;padding:2px 8px;border-radius:9999px;background:#dbeafe;color:#2563eb">Medium</span>
+          <span style="display:inline-flex;align-items:center;font-family:${esc(ff)};font-size:14px;font-weight:500;padding:4px 12px;border-radius:9999px;background:#dbeafe;color:#2563eb">Large</span>
+          <span style="display:inline-flex;width:8px;height:8px;border-radius:50%;background:#16a34a" title="Dot mode"></span>
+        </div>
+      </div>`,
+    props: [
+      {
+        name: "variant",
+        type: '"default" | "success" | "warning" | "danger" | "info"',
+        default: '"default"',
+        required: false,
+        description: "Semantic color variant."
+      },
+      {
+        name: "size",
+        type: '"sm" | "md" | "lg"',
+        default: '"md"',
+        required: false,
+        description: "Controls font size and padding."
+      },
+      {
+        name: "dot",
+        type: "boolean",
+        default: "false",
+        required: false,
+        description: "Renders as a coloured dot with no text."
+      },
+      {
+        name: "children",
+        type: "React.ReactNode",
+        default: "\u2014",
+        required: false,
+        description: "Badge label text."
+      }
+    ],
+    examples: [
+      {
+        label: "Status badges",
+        description: "Use semantic variants to communicate status at a glance.",
+        code: `<Badge variant="success">Published</Badge>
+<Badge variant="warning">Draft</Badge>
+<Badge variant="danger">Archived</Badge>`,
+        previewHtml: `<div style="display:flex;gap:8px;flex-wrap:wrap">
+          ${badgeHtml("Published", "#dcfce7", "#16a34a")}
+          ${badgeHtml("Draft", "#fef9c3", "#ca8a04")}
+          ${badgeHtml("Archived", "#fee2e2", "#dc2626")}
+        </div>`
+      },
+      {
+        label: "Dot indicator",
+        description: "Use dot mode for presence or connection status indicators.",
+        code: `<span style={{ display: 'flex', alignItems: 'center', gap: 6 }}>
+  <Badge variant="success" dot />
+  Online
+</span>`,
+        previewHtml: `<div style="display:flex;align-items:center;gap:6px;font-family:${esc(ff)};font-size:14px;color:var(--color-text-primary,#0f172a)">
+          <span style="display:inline-flex;width:8px;height:8px;border-radius:50%;background:#16a34a"></span>
+          Online
+        </div>`
+      },
+      {
+        label: "With a count",
+        description: "Pair with a label for notification counts.",
+        code: `<Badge variant="danger">3</Badge>`,
+        previewHtml: `<div style="display:flex;gap:8px">
+          ${badgeHtml("3", "#fee2e2", "#dc2626")}
+          ${badgeHtml("12", "#dbeafe", "#2563eb")}
+        </div>`
+      }
+    ],
+    a11y: [
+      {
+        criterion: "1.3.1 Info and Relationships",
+        level: "A",
+        description: "Badge is a <span> with no implicit role. If it conveys status, add role='status' or wrap in a live region."
+      },
+      {
+        criterion: "1.4.3 Contrast (Minimum)",
+        level: "AA",
+        description: "All variant colour pairs are chosen to meet 4.5:1 contrast ratio for small text."
+      },
+      {
+        criterion: "1.4.11 Non-text Contrast",
+        level: "AA",
+        description: "Dot badges must have sufficient contrast with their background. Pair with a text label for screen readers."
+      }
+    ],
+    aiMeta: {
+      component: "Badge",
+      role: "status-indicator",
+      hierarchyLevel: "utility",
+      interactionModel: "none",
+      layoutImpact: "inline",
+      destructiveVariants: [],
+      accessibilityContract: {
+        implicitRole: "none",
+        dotRequiresTextAlternative: true
+      },
+      variants: ["default", "success", "warning", "danger", "info"],
+      aiGuidance: [
+        "Use badge to convey status, not to trigger actions \u2014 use Button for actions.",
+        "Dot badges are not perceivable by screen readers alone; always pair with adjacent text.",
+        "Keep badge labels short \u2014 1\u20132 words or a count.",
+        "Danger variant is appropriate for errors or destructive states, not general alerts."
+      ]
+    }
+  };
+}
+
+// src/generators/showcase/components/checkbox.ts
+function checkboxDef(config, tokens) {
+  const { ff } = componentTokens(config, tokens);
+  const C = {
+    action: "var(--color-action, #2563eb)",
+    text: "var(--color-text-primary, #0f172a)",
+    textSecondary: "var(--color-text-secondary, #64748b)",
+    border: "var(--color-border-default, #e2e8f0)",
+    bg: "var(--color-bg-default, #fff)"
+  };
+  const boxHtml = (checked, indeterminate = false) => {
+    const fill = checked || indeterminate ? "#2563eb" : C.bg;
+    const borderColor = checked || indeterminate ? "#2563eb" : C.border;
+    const mark = checked ? `<svg width="10" height="10" viewBox="0 0 10 10" fill="none" stroke="#fff" stroke-width="2" stroke-linecap="round" stroke-linejoin="round"><polyline points="1.5,5 4,7.5 8.5,2.5"/></svg>` : indeterminate ? `<svg width="10" height="10" viewBox="0 0 10 10" fill="none" stroke="#fff" stroke-width="2" stroke-linecap="round"><line x1="2" y1="5" x2="8" y2="5"/></svg>` : "";
+    return `<span style="display:inline-flex;align-items:center;justify-content:center;width:16px;height:16px;border-radius:2px;border:2px solid ${borderColor};background:${fill};flex-shrink:0">${mark}</span>`;
+  };
+  const checkboxHtml = (label, checked, opts = "", helper = "") => `<label style="display:inline-flex;align-items:flex-start;gap:8px;cursor:pointer;font-family:${esc(ff)};${opts}">
+      ${boxHtml(checked)}
+      <span style="font-size:14px;color:${C.text};line-height:1.4">${label}${helper ? `<br><span style="font-size:12px;color:${C.textSecondary}">${helper}</span>` : ""}</span>
+    </label>`;
+  return {
+    id: "checkbox",
+    label: "Checkbox",
+    description: "Binary toggle for boolean values. Supports indeterminate state for partial selections.",
+    overviewHtml: `
+      <div class="comp-overview-section">
+        <div class="comp-overview-label">States</div>
+        <div class="comp-preview-col">
+          ${checkboxHtml("Unchecked", false)}
+          ${checkboxHtml("Checked", true)}
+          <label style="display:inline-flex;align-items:flex-start;gap:8px;cursor:pointer;font-family:${esc(ff)}">
+            ${boxHtml(false, true)}
+            <span style="font-size:14px;color:${C.text}">Indeterminate</span>
+          </label>
+          ${checkboxHtml("Disabled", false, "opacity:0.4;cursor:not-allowed")}
+        </div>
+      </div>`,
+    props: [
+      {
+        name: "label",
+        type: "string",
+        default: "\u2014",
+        required: false,
+        description: "Visible label rendered next to the checkbox."
+      },
+      {
+        name: "checked",
+        type: "boolean",
+        default: "\u2014",
+        required: false,
+        description: "Controlled checked state. Pair with onChange."
+      },
+      {
+        name: "defaultChecked",
+        type: "boolean",
+        default: "false",
+        required: false,
+        description: "Initial checked state for uncontrolled usage."
+      },
+      {
+        name: "indeterminate",
+        type: "boolean",
+        default: "false",
+        required: false,
+        description: "Partial selection state. Visually distinct from checked/unchecked."
+      },
+      {
+        name: "disabled",
+        type: "boolean",
+        default: "false",
+        required: false,
+        description: "Prevents interaction and applies reduced opacity."
+      },
+      {
+        name: "size",
+        type: '"sm" | "md" | "lg"',
+        default: '"md"',
+        required: false,
+        description: "Controls checkbox and label size."
+      },
+      {
+        name: "helperText",
+        type: "string",
+        default: "\u2014",
+        required: false,
+        description: "Secondary text below the label."
+      },
+      {
+        name: "onChange",
+        type: "(e: React.ChangeEvent<HTMLInputElement>) => void",
+        default: "\u2014",
+        required: false,
+        description: "Fires when the checked state changes."
+      }
+    ],
+    examples: [
+      {
+        label: "Controlled checkbox",
+        description: "Manage checked state externally with useState.",
+        code: `const [agreed, setAgreed] = useState(false);
+
+<Checkbox
+  label="I accept the terms and conditions"
+  checked={agreed}
+  onChange={(e) => setAgreed(e.target.checked)}
+/>`,
+        previewHtml: checkboxHtml("I accept the terms and conditions", true)
+      },
+      {
+        label: "Indeterminate (parent selection)",
+        description: "Use indeterminate when some but not all children are selected.",
+        code: `<Checkbox
+  label="Select all (3 of 5)"
+  indeterminate
+/>`,
+        previewHtml: `<label style="display:inline-flex;align-items:center;gap:8px;cursor:pointer;font-family:${esc(ff)}">
+          ${boxHtml(false, true)}
+          <span style="font-size:14px;color:${C.text}">Select all (3 of 5)</span>
+        </label>`
+      },
+      {
+        label: "With helper text",
+        description: "helperText provides secondary context without replacing the label.",
+        code: `<Checkbox
+  label="Receive email notifications"
+  helperText="We'll send summaries once a week."
+  defaultChecked
+/>`,
+        previewHtml: checkboxHtml(
+          "Receive email notifications",
+          true,
+          "",
+          "We'll send summaries once a week."
+        )
+      }
+    ],
+    a11y: [
+      {
+        criterion: "1.3.1 Info and Relationships",
+        level: "A",
+        description: "A hidden native <input type=checkbox> is always present. The visible custom box is aria-hidden."
+      },
+      {
+        criterion: "2.1.1 Keyboard",
+        level: "A",
+        description: "Focusable and toggleable with Space. Tab moves focus to/from the checkbox."
+      },
+      {
+        criterion: "2.4.7 Focus Visible",
+        level: "AA",
+        description: "Focus ring renders on keyboard focus via :focus-visible detection."
+      },
+      {
+        criterion: "4.1.2 Name, Role, Value",
+        level: "A",
+        description: "Role is conveyed by the native input element. Indeterminate state is set via the indeterminate property on the DOM node."
+      }
+    ],
+    aiMeta: {
+      component: "Checkbox",
+      role: "data-entry",
+      hierarchyLevel: "primary",
+      interactionModel: "synchronous",
+      layoutImpact: "inline",
+      destructiveVariants: [],
+      accessibilityContract: {
+        keyboard: true,
+        focusRing: "required",
+        nativeInputPreserved: true,
+        indeterminateDomProperty: true
+      },
+      variants: ["default", "error", "disabled"],
+      aiGuidance: [
+        "Always provide a label prop or a wrapping <label> \u2014 never rely on adjacent text alone.",
+        "Use indeterminate for 'select all' patterns when partial selection exists.",
+        "Group related checkboxes in a <fieldset> with a <legend>.",
+        "For single boolean toggles, prefer Checkbox over a custom toggle switch."
+      ]
+    }
+  };
+}
+
+// src/generators/showcase/components/radio.ts
+function radioDef(config, tokens) {
+  const { ff } = componentTokens(config, tokens);
+  const C = {
+    action: "#2563eb",
+    text: "var(--color-text-primary, #0f172a)",
+    textSecondary: "var(--color-text-secondary, #64748b)",
+    border: "var(--color-border-default, #e2e8f0)",
+    bg: "var(--color-bg-default, #fff)"
+  };
+  const circleHtml = (selected) => {
+    const borderColor = selected ? C.action : C.border;
+    return `<span style="display:inline-flex;align-items:center;justify-content:center;width:16px;height:16px;border-radius:50%;border:2px solid ${borderColor};background:${C.bg};flex-shrink:0">
+      ${selected ? `<span style="width:8px;height:8px;border-radius:50%;background:${C.action}"></span>` : ""}
+    </span>`;
+  };
+  const radioHtml = (label, selected, opts = "") => `<label style="display:inline-flex;align-items:center;gap:8px;cursor:pointer;font-family:${esc(ff)};${opts}">
+      ${circleHtml(selected)}
+      <span style="font-size:14px;color:${C.text}">${label}</span>
+    </label>`;
+  return {
+    id: "radio",
+    label: "Radio",
+    description: "Single selection within a mutually exclusive group. Always pair Radio with RadioGroup.",
+    overviewHtml: `
+      <div class="comp-overview-section">
+        <div class="comp-overview-label">RadioGroup (vertical)</div>
+        <div class="comp-preview-col">
+          <fieldset style="border:none;padding:0;margin:0;font-family:${esc(ff)}">
+            <legend style="font-size:13px;font-weight:600;color:${C.text};margin-bottom:8px">Notification preference</legend>
+            <div class="comp-preview-col">
+              ${radioHtml("Email", true)}
+              ${radioHtml("SMS", false)}
+              ${radioHtml("Push notification", false)}
+            </div>
+          </fieldset>
+        </div>
+      </div>
+      <div class="comp-overview-section">
+        <div class="comp-overview-label">Horizontal layout</div>
+        <div class="comp-preview-row">
+          ${radioHtml("Monthly", true)}
+          ${radioHtml("Quarterly", false)}
+          ${radioHtml("Annually", false)}
+        </div>
+      </div>`,
+    props: [
+      {
+        name: "label",
+        type: "string",
+        default: "\u2014",
+        required: false,
+        description: "Visible label rendered next to the radio circle."
+      },
+      {
+        name: "value",
+        type: "string",
+        default: "\u2014",
+        required: false,
+        description: "The value submitted when this radio is selected. Required when used inside RadioGroup."
+      },
+      {
+        name: "size",
+        type: '"sm" | "md" | "lg"',
+        default: '"md"',
+        required: false,
+        description: "Controls radio and label size."
+      },
+      {
+        name: "disabled",
+        type: "boolean",
+        default: "false",
+        required: false,
+        description: "Prevents interaction and applies reduced opacity."
+      },
+      {
+        name: "legend",
+        type: "string",
+        default: "\u2014",
+        required: true,
+        description: "[RadioGroup] Accessible group label read by screen readers."
+      },
+      {
+        name: "orientation",
+        type: '"horizontal" | "vertical"',
+        default: '"vertical"',
+        required: false,
+        description: "[RadioGroup] Layout direction of the radio items."
+      },
+      {
+        name: "onChange",
+        type: "(value: string) => void",
+        default: "\u2014",
+        required: false,
+        description: "[RadioGroup] Fires when the selected value changes."
+      }
+    ],
+    examples: [
+      {
+        label: "Controlled RadioGroup",
+        description: "Wrap Radio buttons inside RadioGroup for proper grouping and keyboard navigation.",
+        code: `const [plan, setPlan] = useState("monthly");
+
+<RadioGroup
+  legend="Billing cycle"
+  value={plan}
+  onChange={setPlan}
+>
+  <Radio value="monthly" label="Monthly" />
+  <Radio value="annual" label="Annual (save 20%)" />
+</RadioGroup>`,
+        previewHtml: `<fieldset style="border:none;padding:0;margin:0;font-family:${esc(ff)}">
+          <legend style="font-size:13px;font-weight:600;color:${C.text};margin-bottom:8px">Billing cycle</legend>
+          <div style="display:flex;flex-direction:column;gap:8px">
+            ${radioHtml("Monthly", true)}
+            ${radioHtml("Annual (save 20%)", false)}
+          </div>
+        </fieldset>`
+      },
+      {
+        label: "Horizontal orientation",
+        description: "Use orientation='horizontal' for compact inline layouts.",
+        code: `<RadioGroup legend="Size" orientation="horizontal" defaultValue="md">
+  <Radio value="sm" label="S" />
+  <Radio value="md" label="M" />
+  <Radio value="lg" label="L" />
+</RadioGroup>`,
+        previewHtml: `<fieldset style="border:none;padding:0;margin:0;font-family:${esc(ff)}">
+          <legend style="font-size:13px;font-weight:600;color:${C.text};margin-bottom:8px">Size</legend>
+          <div style="display:flex;gap:16px">
+            ${radioHtml("S", false)}
+            ${radioHtml("M", true)}
+            ${radioHtml("L", false)}
+          </div>
+        </fieldset>`
+      }
+    ],
+    a11y: [
+      {
+        criterion: "1.3.1 Info and Relationships",
+        level: "A",
+        description: "RadioGroup renders a native <fieldset> with <legend>. Individual radios are native <input type=radio> elements \u2014 role and grouping are implicit."
+      },
+      {
+        criterion: "2.1.1 Keyboard",
+        level: "A",
+        description: "Arrow keys cycle through options within the group. Tab moves focus to/from the group."
+      },
+      {
+        criterion: "2.4.7 Focus Visible",
+        level: "AA",
+        description: "Focus ring renders on keyboard focus via :focus-visible detection."
+      },
+      {
+        criterion: "4.1.2 Name, Role, Value",
+        level: "A",
+        description: "Selected state is communicated via the native checked attribute. Name grouping is handled by RadioGroup context."
+      }
+    ],
+    aiMeta: {
+      component: "Radio",
+      role: "data-entry",
+      hierarchyLevel: "primary",
+      interactionModel: "synchronous",
+      layoutImpact: "inline",
+      destructiveVariants: [],
+      accessibilityContract: {
+        keyboard: true,
+        focusRing: "required",
+        mustUseRadioGroup: true,
+        nativeInputPreserved: true
+      },
+      variants: ["default", "disabled"],
+      aiGuidance: [
+        "Always wrap Radio inside RadioGroup \u2014 never render standalone Radio elements.",
+        "Use radio buttons when the user must pick exactly one option from a small set (2\u20137 items).",
+        "For longer lists, prefer Select instead.",
+        "The legend prop is required on RadioGroup and must describe the choice being made."
+      ]
+    }
+  };
+}
+
+// src/generators/showcase/components/select.ts
+function selectDef(config, tokens) {
+  const { radiusMd, ff } = componentTokens(config, tokens);
+  const r = `${radiusMd}px`;
+  const C = {
+    text: "var(--color-text-primary, #0f172a)",
+    textSecondary: "var(--color-text-secondary, #64748b)",
+    bg: "var(--color-bg-default, #fff)",
+    border: "var(--color-border-default, #e2e8f0)"
+  };
+  const chevron = `<svg width="14" height="14" viewBox="0 0 24 24" fill="none" stroke="${C.textSecondary}" stroke-width="2" stroke-linecap="round" stroke-linejoin="round"><polyline points="6 9 12 15 18 9"/></svg>`;
+  const selectHtml = (label, placeholder, options = [], borderColor = C.border, helperHtml = "", disabled = false) => `
+    <div class="ds-field" style="font-family:${esc(ff)};max-width:320px;${disabled ? "opacity:0.5" : ""}">
+      <label class="ds-label" style="color:${C.text}">${esc(label)}</label>
+      <div style="position:relative;display:flex;align-items:center;background:${C.bg};border:1px solid ${borderColor};border-radius:${r}">
+        <select style="flex:1;appearance:none;-webkit-appearance:none;background:${C.bg};border:none;outline:none;padding:8px 32px 8px 12px;font-size:14px;color:${C.text};cursor:${disabled ? "not-allowed" : "pointer"};width:100%" ${disabled ? "disabled" : ""}>
+          <option value="" disabled selected style="color:${C.textSecondary}">${esc(placeholder)}</option>
+          ${options.map((o) => `<option>${esc(o)}</option>`).join("")}
+        </select>
+        <span style="position:absolute;right:8px;display:flex;align-items:center;pointer-events:none">${chevron}</span>
+      </div>
+      ${helperHtml}
+    </div>`;
+  return {
+    id: "select",
+    label: "Select",
+    description: "Dropdown picker for selecting from a list of options. Wraps native <select> for full accessibility.",
+    overviewHtml: `
+      <div class="comp-overview-section">
+        <div class="comp-overview-label">States</div>
+        <div class="comp-preview-col">
+          ${selectHtml("Country", "Select a country\u2026", ["Norway", "Sweden", "Denmark"], C.border, `<span style="font-size:12px;color:${C.textSecondary};margin-top:2px">Select your country of residence.</span>`)}
+          ${selectHtml("Role", "Select a role\u2026", ["Admin", "Editor", "Viewer"], C.border, `<span style="font-size:12px;color:${C.textSecondary};margin-top:2px">Role determines what permissions this user has.</span>`)}
+          ${selectHtml("Priority", "Select a priority\u2026", ["Low", "Medium", "High"], "#dc2626", `<span style="font-size:12px;color:#dc2626;margin-top:2px">Please select a priority level.</span>`)}
+          ${selectHtml("Status", "Select a status\u2026", ["Active", "Inactive"], C.border, "", true)}
+        </div>
+      </div>`,
+    props: [
+      {
+        name: "label",
+        type: "string",
+        default: "\u2014",
+        required: false,
+        description: "Visible label rendered above the select."
+      },
+      {
+        name: "options",
+        type: "SelectOption[]",
+        default: "\u2014",
+        required: false,
+        description: "Structured option list. Alternatively, pass <option> children directly."
+      },
+      {
+        name: "placeholder",
+        type: "string",
+        default: "\u2014",
+        required: false,
+        description: "Disabled first option shown when no value is selected."
+      },
+      {
+        name: "errorMessage",
+        type: "string",
+        default: "\u2014",
+        required: false,
+        description: "Validation message. Also applies error border styling."
+      },
+      {
+        name: "helperText",
+        type: "string",
+        default: "\u2014",
+        required: false,
+        description: "Secondary text shown below the select (no error state)."
+      },
+      {
+        name: "size",
+        type: '"sm" | "md" | "lg"',
+        default: '"md"',
+        required: false,
+        description: "Controls padding and font size."
+      },
+      {
+        name: "fullWidth",
+        type: "boolean",
+        default: "false",
+        required: false,
+        description: "Expands the select to fill its container."
+      },
+      {
+        name: "disabled",
+        type: "boolean",
+        default: "false",
+        required: false,
+        description: "Prevents interaction and applies reduced opacity."
+      }
+    ],
+    examples: [
+      {
+        label: "Using options prop",
+        description: "Pass a structured array for programmatic option lists.",
+        code: `<Select
+  label="Framework"
+  placeholder="Choose a framework\u2026"
+  options={[
+    { value: "react", label: "React" },
+    { value: "vue", label: "Vue" },
+    { value: "svelte", label: "Svelte" },
+  ]}
+  onChange={(e) => console.log(e.target.value)}
+/>`,
+        previewHtml: `<div class="ds-field" style="font-family:${esc(ff)};max-width:320px">
+          <label class="ds-label" style="color:${C.text}">Framework</label>
+          <div style="position:relative;display:flex;align-items:center;background:${C.bg};border:1px solid ${C.border};border-radius:${r}">
+            <select style="flex:1;appearance:none;-webkit-appearance:none;background:${C.bg};border:none;outline:none;padding:8px 32px 8px 12px;font-size:14px;color:${C.text};cursor:pointer;width:100%">
+              <option value="" disabled selected style="color:${C.textSecondary}">Choose a framework\u2026</option>
+              <option>React</option>
+              <option>Vue</option>
+              <option>Svelte</option>
+            </select>
+            <span style="position:absolute;right:8px;display:flex;align-items:center;pointer-events:none">${chevron}</span>
+          </div>
+        </div>`
+      },
+      {
+        label: "With validation error",
+        description: "Pass errorMessage to show inline validation and apply error styling.",
+        code: `<Select
+  label="Department"
+  placeholder="Select department"
+  errorMessage="Please select a department."
+/>`,
+        previewHtml: selectHtml(
+          "Department",
+          "Select a department\u2026",
+          ["Engineering", "Design", "Product"],
+          "#dc2626",
+          `<span style="font-size:12px;color:#dc2626;margin-top:2px">Please select a department.</span>`
+        )
+      }
+    ],
+    a11y: [
+      {
+        criterion: "1.3.1 Info and Relationships",
+        level: "A",
+        description: "The native <select> is always rendered. The custom chevron icon is aria-hidden. Label is associated via htmlFor/id."
+      },
+      {
+        criterion: "2.1.1 Keyboard",
+        level: "A",
+        description: "Native <select> is fully keyboard accessible. Arrow keys navigate options; Enter or Space opens the dropdown."
+      },
+      {
+        criterion: "3.3.1 Error Identification",
+        level: "A",
+        description: "When errorMessage is present, the select receives aria-invalid='true' and aria-describedby pointing to the error."
+      },
+      {
+        criterion: "4.1.2 Name, Role, Value",
+        level: "A",
+        description: "Role and value state are communicated by the native select element \u2014 no ARIA additions needed."
+      }
+    ],
+    aiMeta: {
+      component: "Select",
+      role: "data-entry",
+      hierarchyLevel: "primary",
+      interactionModel: "synchronous",
+      layoutImpact: "block",
+      destructiveVariants: [],
+      accessibilityContract: {
+        keyboard: true,
+        nativeSelectPreserved: true,
+        ariaInvalidOnError: true
+      },
+      variants: ["default", "error", "disabled"],
+      aiGuidance: [
+        "Use Select for lists of 4+ options; use RadioGroup for 2\u20133 mutually exclusive choices.",
+        "Always provide a label \u2014 never rely on placeholder alone.",
+        "For multi-select, use native multiple attribute or a custom multi-select component.",
+        "options prop and children are mutually exclusive \u2014 use one approach consistently."
+      ]
+    }
+  };
+}
+
+// src/generators/showcase/components/toast.ts
+function toastDef(config, tokens) {
+  const { radiusMd, ff } = componentTokens(config, tokens);
+  const r = `${radiusMd}px`;
+  const vDefault = { name: "default", bg: "var(--color-bg-subtle, #f8fafc)", border: "var(--color-border-default, #e2e8f0)", icon: "var(--color-text-secondary, #6b7280)", label: "Default" };
+  const vSuccess = { name: "success", bg: "var(--color-success-subtle, #dcfce7)", border: "var(--color-success-border, #86efac)", icon: "var(--color-success, #16a34a)", label: "Success" };
+  const vWarning = { name: "warning", bg: "var(--color-warning-subtle, #fef9c3)", border: "var(--color-warning-border, #fde047)", icon: "var(--color-warning, #ca8a04)", label: "Warning" };
+  const vDanger = { name: "danger", bg: "var(--color-danger-subtle, #fee2e2)", border: "var(--color-danger-border, #fca5a5)", icon: "var(--color-danger, #dc2626)", label: "Error" };
+  const vInfo = { name: "info", bg: "var(--color-info-subtle, #dbeafe)", border: "var(--color-info-border, #93c5fd)", icon: "var(--color-info, #2563eb)", label: "Info" };
+  const variants = [vDefault, vSuccess, vWarning, vDanger, vInfo];
+  const icons = {
+    default: `<svg width="16" height="16" viewBox="0 0 24 24" fill="none" stroke="currentColor" stroke-width="2" stroke-linecap="round"><circle cx="12" cy="12" r="10"/><line x1="12" y1="16" x2="12" y2="12"/><line x1="12" y1="8" x2="12.01" y2="8"/></svg>`,
+    success: `<svg width="16" height="16" viewBox="0 0 24 24" fill="none" stroke="currentColor" stroke-width="2" stroke-linecap="round"><path d="M22 11.08V12a10 10 0 1 1-5.93-9.14"/><polyline points="22 4 12 14.01 9 11.01"/></svg>`,
+    warning: `<svg width="16" height="16" viewBox="0 0 24 24" fill="none" stroke="currentColor" stroke-width="2" stroke-linecap="round"><path d="M10.29 3.86L1.82 18a2 2 0 0 0 1.71 3h16.94a2 2 0 0 0 1.71-3L13.71 3.86a2 2 0 0 0-3.42 0z"/><line x1="12" y1="9" x2="12" y2="13"/><line x1="12" y1="17" x2="12.01" y2="17"/></svg>`,
+    danger: `<svg width="16" height="16" viewBox="0 0 24 24" fill="none" stroke="currentColor" stroke-width="2" stroke-linecap="round"><circle cx="12" cy="12" r="10"/><line x1="12" y1="8" x2="12" y2="12"/><line x1="12" y1="16" x2="12.01" y2="16"/></svg>`,
+    info: `<svg width="16" height="16" viewBox="0 0 24 24" fill="none" stroke="currentColor" stroke-width="2" stroke-linecap="round"><circle cx="12" cy="12" r="10"/><line x1="12" y1="16" x2="12" y2="12"/><line x1="12" y1="8" x2="12.01" y2="8"/></svg>`
+  };
+  const alertHtml = (v, title, body) => `<div role="alert" style="display:flex;gap:12px;padding:12px 16px;border-radius:${r};border:1px solid ${v.border};background:${v.bg};font-family:${esc(ff)};max-width:360px">
+      <span style="color:${v.icon};flex-shrink:0;margin-top:1px">${icons[v.name]}</span>
+      <div>
+        <p style="margin:0;font-size:13px;font-weight:600;color:${v.icon}">${title}</p>
+        <p style="margin:4px 0 0;font-size:13px;color:var(--color-text-secondary,#6b7280)">${body}</p>
+      </div>
+    </div>`;
+  return {
+    id: "toast",
+    label: "Toast / Alert",
+    description: "Feedback for user actions. Alert is inline and static; Toast is an overlay with auto-dismiss and a useToast() hook.",
+    overviewHtml: `
+      <div class="comp-overview-section">
+        <div class="comp-overview-label">Alert \u2014 inline variants</div>
+        <div class="comp-preview-col">
+          ${variants.map((v) => alertHtml(v, v.label, `This is a ${v.name} alert message.`)).join("\n          ")}
+        </div>
+      </div>`,
+    props: [
+      {
+        name: "variant",
+        type: '"default" | "success" | "warning" | "danger" | "info"',
+        default: '"default"',
+        required: false,
+        description: "Semantic color and icon variant."
+      },
+      {
+        name: "title",
+        type: "string",
+        default: "\u2014",
+        required: false,
+        description: "Bold heading rendered above the message body."
+      },
+      {
+        name: "dismissible",
+        type: "boolean",
+        default: "false",
+        required: false,
+        description: "[Alert] Shows a close button. Hides the alert on click."
+      },
+      {
+        name: "onDismiss",
+        type: "() => void",
+        default: "\u2014",
+        required: false,
+        description: "[Alert] Called after the alert is dismissed."
+      },
+      {
+        name: "message",
+        type: "string",
+        default: "\u2014",
+        required: true,
+        description: "[Toast] The notification message body."
+      },
+      {
+        name: "duration",
+        type: "number",
+        default: "5000",
+        required: false,
+        description: "[Toast] Auto-dismiss delay in ms. Set to 0 to disable."
+      }
+    ],
+    examples: [
+      {
+        label: "Inline Alert",
+        description: "Alert renders in-place within the page flow.",
+        code: `<Alert variant="success" title="Payment confirmed">
+  Your order #1234 has been placed successfully.
+</Alert>`,
+        previewHtml: alertHtml(
+          vSuccess,
+          "Payment confirmed",
+          "Your order #1234 has been placed successfully."
+        )
+      },
+      {
+        label: "Dismissible Alert",
+        description: "Add dismissible to show a close button.",
+        code: `<Alert
+  variant="warning"
+  title="Your trial expires in 3 days"
+  dismissible
+  onDismiss={() => setShowBanner(false)}
+>
+  Upgrade to continue using all features.
+</Alert>`,
+        previewHtml: `<div role="alert" style="display:flex;gap:12px;padding:12px 16px;border-radius:${r};border:1px solid ${vWarning.border};background:${vWarning.bg};font-family:${esc(ff)};max-width:360px">
+          <span style="color:${vWarning.icon};flex-shrink:0;margin-top:1px">${icons["warning"]}</span>
+          <div style="flex:1">
+            <p style="margin:0;font-size:13px;font-weight:600;color:${vWarning.icon}">Your trial expires in 3 days</p>
+            <p style="margin:4px 0 0;font-size:13px;color:var(--color-text-secondary,#6b7280)">Upgrade to continue using all features.</p>
+          </div>
+          <button style="background:transparent;border:none;cursor:pointer;color:var(--color-text-secondary,#6b7280);padding:2px;flex-shrink:0" aria-label="Dismiss">\u2715</button>
+        </div>`
+      },
+      {
+        label: "Toast via useToast()",
+        description: "Wrap your app in ToastProvider, then call toast.add() from anywhere.",
+        code: `// Wrap your app once
+<ToastProvider>
+  <App />
+</ToastProvider>
+
+// Inside any component
+const toast = useToast();
+
+toast.add({
+  variant: "success",
+  title: "Saved",
+  message: "Your changes have been saved.",
+  duration: 4000,
+});`,
+        previewHtml: `<div style="position:relative;background:var(--color-bg-subtle,#f8fafc);border:1px dashed var(--color-border-default,#e2e8f0);border-radius:${r};padding:20px;min-height:80px;font-family:${esc(ff)}">
+          <p style="font-size:12px;color:var(--color-text-secondary,#6b7280);margin:0 0 12px">Bottom-right overlay (fixed position)</p>
+          <div style="display:flex;gap:12px;padding:12px 16px;border-radius:${r};border:1px solid var(--color-success-border,#86efac);background:var(--color-success-subtle,#dcfce7);box-shadow:0 4px 12px rgba(0,0,0,0.12)">
+            <span style="color:var(--color-success,#16a34a)">${icons["success"]}</span>
+            <div>
+              <p style="margin:0;font-size:13px;font-weight:600;color:var(--color-text-primary,#0f172a)">Saved</p>
+              <p style="margin:4px 0 0;font-size:13px;color:var(--color-text-secondary,#6b7280)">Your changes have been saved.</p>
+            </div>
+            <button style="background:transparent;border:none;cursor:pointer;color:var(--color-text-secondary,#6b7280);padding:2px" aria-label="Dismiss">\u2715</button>
+          </div>
+        </div>`
+      }
+    ],
+    a11y: [
+      {
+        criterion: "4.1.3 Status Messages",
+        level: "AA",
+        description: "Alert uses role='alert' for immediate announcements. Toast container uses aria-live='polite' so screen readers announce without interrupting."
+      },
+      {
+        criterion: "2.2.1 Timing Adjustable",
+        level: "A",
+        description: "duration prop controls auto-dismiss timing. Set to 0 to disable. Users can also dismiss manually with the close button."
+      },
+      {
+        criterion: "2.1.1 Keyboard",
+        level: "A",
+        description: "The dismiss button is keyboard focusable and activatable. Toast overlay does not trap focus."
+      },
+      {
+        criterion: "1.4.3 Contrast (Minimum)",
+        level: "AA",
+        description: "All variant text/background pairs are selected to meet 4.5:1 contrast for body text."
+      }
+    ],
+    aiMeta: {
+      component: "Toast",
+      role: "feedback",
+      hierarchyLevel: "utility",
+      interactionModel: "asynchronous",
+      layoutImpact: "overlay",
+      destructiveVariants: [],
+      accessibilityContract: {
+        alertRoleForInline: true,
+        ariaLivePoliteForToasts: true,
+        dismissButtonRequired: "when-dismissible"
+      },
+      variants: ["default", "success", "warning", "danger", "info"],
+      aiGuidance: [
+        "Use Alert for inline, contextual feedback tied to a form or page section.",
+        "Use Toast (via useToast) for transient system-level feedback after async actions.",
+        "Never use Toast for error messages that the user must act on \u2014 use Alert instead.",
+        "Keep toast messages under 80 characters \u2014 they are ephemeral."
+      ]
+    }
+  };
+}
+
+// src/generators/showcase/components/spinner.ts
+function spinnerDef(config, tokens) {
+  const { ff } = componentTokens(config, tokens);
+  const C = {
+    action: "#2563eb",
+    textSecondary: "#6b7280",
+    bg: "var(--color-bg-default, #fff)"
+  };
+  const svgSpinner = (size, color, strokeWidth = 2) => {
+    const r = size / 2 - strokeWidth;
+    const c = 2 * Math.PI * r;
+    return `<svg width="${size}" height="${size}" viewBox="0 0 ${size} ${size}" fill="none" style="color:${color};animation:dsforge-spin 0.75s linear infinite;display:block">
+      <circle cx="${size / 2}" cy="${size / 2}" r="${r}" stroke="currentColor" stroke-width="${strokeWidth}" opacity="0.2"/>
+      <circle cx="${size / 2}" cy="${size / 2}" r="${r}" stroke="currentColor" stroke-width="${strokeWidth}" stroke-linecap="round"
+        stroke-dasharray="${c}" stroke-dashoffset="${c * 0.25}"
+        transform="rotate(-90 ${size / 2} ${size / 2})"/>
+    </svg>`;
+  };
+  return {
+    id: "spinner",
+    label: "Spinner",
+    description: "Loading indicator for async operations. Includes a visually hidden status label for screen readers.",
+    overviewHtml: `
+      <div class="comp-overview-section">
+        <div class="comp-overview-label">Sizes</div>
+        <div class="comp-preview-row" style="align-items:center">
+          ${svgSpinner(12, C.action, 2.5)}
+          ${svgSpinner(16, C.action, 2.5)}
+          ${svgSpinner(24, C.action, 2)}
+          ${svgSpinner(32, C.action, 2)}
+          ${svgSpinner(48, C.action, 1.5)}
+        </div>
+      </div>
+      <div class="comp-overview-section">
+        <div class="comp-overview-label">Variants</div>
+        <div class="comp-preview-row" style="align-items:center">
+          ${svgSpinner(24, C.textSecondary, 2)}
+          ${svgSpinner(24, C.action, 2)}
+          <span style="background:#1e293b;padding:8px;border-radius:6px;display:inline-flex">${svgSpinner(24, "#ffffff", 2)}</span>
+        </div>
+      </div>`,
+    props: [
+      {
+        name: "size",
+        type: '"xs" | "sm" | "md" | "lg" | "xl"',
+        default: '"md"',
+        required: false,
+        description: "Controls the diameter and stroke width."
+      },
+      {
+        name: "variant",
+        type: '"default" | "primary" | "inverted"',
+        default: '"default"',
+        required: false,
+        description: "Color variant. Use inverted on dark backgrounds."
+      },
+      {
+        name: "label",
+        type: "string",
+        default: '"Loading\u2026"',
+        required: false,
+        description: "Screen reader announcement. Rendered as visually hidden text inside role='status'."
+      }
+    ],
+    examples: [
+      {
+        label: "Inline loading state",
+        description: "Use inside buttons or next to labels during async operations.",
+        code: `<div style={{ display: 'flex', alignItems: 'center', gap: 8 }}>
+  <Spinner size="sm" label="Saving changes" />
+  <span>Saving\u2026</span>
+</div>`,
+        previewHtml: `<div style="display:flex;align-items:center;gap:8px;font-family:${esc(ff)};font-size:14px;color:var(--color-text-primary,#0f172a)">
+          ${svgSpinner(16, C.action, 2.5)}
+          <span>Saving\u2026</span>
+        </div>`
+      },
+      {
+        label: "Full-page loader",
+        description: "Center a large spinner during initial data fetching.",
+        code: `<div style={{ display: 'flex', justifyContent: 'center', padding: 48 }}>
+  <Spinner size="lg" label="Loading dashboard" />
+</div>`,
+        previewHtml: `<div style="display:flex;justify-content:center;padding:32px;background:var(--color-bg-subtle,#f8fafc);border-radius:6px;border:1px solid #e2e8f0">
+          ${svgSpinner(32, C.action, 2)}
+        </div>`
+      },
+      {
+        label: "On dark background",
+        description: "Use variant='inverted' when the spinner sits on a dark surface.",
+        code: `<div style={{ background: '#1e293b', padding: 16, borderRadius: 8 }}>
+  <Spinner variant="inverted" label="Loading" />
+</div>`,
+        previewHtml: `<div style="background:#1e293b;padding:16px;border-radius:6px;display:inline-flex">
+          ${svgSpinner(24, "#ffffff", 2)}
+        </div>`
+      }
+    ],
+    a11y: [
+      {
+        criterion: "4.1.3 Status Messages",
+        level: "AA",
+        description: "Spinner is wrapped in a <span role='status'>. The label prop is rendered as visually hidden text inside this element, ensuring screen readers announce the loading state."
+      },
+      {
+        criterion: "1.4.3 Contrast (Minimum)",
+        level: "AA",
+        description: "The spinner arc contrasts with its track. default and primary variants are validated against the configured background token."
+      },
+      {
+        criterion: "2.2.2 Pause, Stop, Hide",
+        level: "A",
+        description: "Spinner animations are driven by CSS. Users with prefers-reduced-motion can override these with a media query."
+      }
+    ],
+    aiMeta: {
+      component: "Spinner",
+      role: "loading-indicator",
+      hierarchyLevel: "utility",
+      interactionModel: "asynchronous",
+      layoutImpact: "inline",
+      destructiveVariants: [],
+      accessibilityContract: {
+        roleStatus: true,
+        visuallyHiddenLabel: "required",
+        reducedMotionSupported: true
+      },
+      variants: ["default", "primary", "inverted"],
+      aiGuidance: [
+        "Always provide a meaningful label describing what is loading, not just 'Loading\u2026'.",
+        "Use sm size inside buttons; md for inline states; lg/xl for full-page loaders.",
+        "Pair with aria-busy='true' on the container that is loading for extra screen reader context.",
+        "Use inverted variant on dark surfaces (dark backgrounds, colored buttons)."
+      ]
+    }
+  };
+}
+
+// src/generators/showcase/registry.ts
+var SHOWCASE_COMPONENTS = [
+  {
+    id: "button",
+    label: "Button",
+    pageDescription: "Triggers an action or event. Supports multiple variants, sizes, and loading state.",
+    def: buttonDef
+  },
+  {
+    id: "input",
+    label: "Input",
+    pageDescription: "Single-line text field with label, helper text, and validation states.",
+    def: inputDef
+  },
+  {
+    id: "card",
+    label: "Card",
+    pageDescription: "Surface that groups related content. Supports header, body, and footer slots.",
+    def: cardDef
+  },
+  {
+    id: "badge",
+    label: "Badge",
+    pageDescription: "Compact label for status, categories, or counts. Display-only \u2014 not interactive.",
+    def: badgeDef
+  },
+  {
+    id: "checkbox",
+    label: "Checkbox",
+    pageDescription: "Binary toggle for boolean values. Supports indeterminate state for partial selections.",
+    def: checkboxDef
+  },
+  {
+    id: "radio",
+    label: "Radio",
+    pageDescription: "Single selection within a mutually exclusive group. Always use inside RadioGroup.",
+    def: radioDef
+  },
+  {
+    id: "select",
+    label: "Select",
+    pageDescription: "Dropdown picker for selecting from a list of options. Wraps native <select> for full accessibility.",
+    def: selectDef
+  },
+  {
+    id: "toast",
+    label: "Toast / Alert",
+    pageDescription: "Feedback messages for user actions. Alert is inline; Toast is an overlay with auto-dismiss.",
+    def: toastDef
+  },
+  {
+    id: "spinner",
+    label: "Spinner",
+    pageDescription: "Loading indicator for async operations. Includes a visually hidden status label for screen readers.",
+    def: spinnerDef
+  }
+];
+
+// src/generators/showcase/html.ts
+function generateShowcase(config, resolution) {
+  const tokens = resolution.tokens;
+  const name = config.meta?.name ?? "Design System";
+  const version = config.meta?.version ?? "0.1.0";
+  const themes = Object.keys(config.themes ?? {});
+  const foundationItems = [
+    { id: "colors", label: "Colors" },
+    { id: "typography", label: "Typography" },
+    { id: "spacing", label: "Spacing" },
+    { id: "radius", label: "Border Radius" },
+    { id: "elevation", label: "Elevation" },
+    { id: "motion", label: "Motion" }
+  ];
+  const componentItems = SHOWCASE_COMPONENTS.map(({ id, label }) => ({ id, label }));
+  const allItems = [...foundationItems, ...componentItems];
+  const isPro = isProUnlocked();
+  const sections = {
+    colors: buildColorSection(config, tokens),
+    typography: buildTypographySection(config),
+    spacing: buildSpacingSection(config),
+    radius: buildRadiusSection(config),
+    elevation: buildElevationSection(config),
+    motion: buildMotionSection(config),
+    ...Object.fromEntries(
+      SHOWCASE_COMPONENTS.map((entry) => [
+        entry.id,
+        buildComponentPage(entry.def(config, tokens), isPro)
+      ])
+    )
+  };
+  const flatTokens = Object.fromEntries(
+    Object.entries(tokens).map(([k, v]) => [
+      k.replace(/^(global|semantic|component)\./, ""),
+      v
+    ])
+  );
+  const lightTheme = config.themes?.["light"] ?? {};
+  const darkTheme = config.themes?.["dark"] ?? {};
+  const themeCssLight = Object.entries({ ...flatTokens, ...lightTheme }).map(([k, v]) => `  --${k}: ${v};`).join("\n");
+  const themeCssDark = Object.entries({ ...flatTokens, ...darkTheme }).map(([k, v]) => `  --${k}: ${v};`).join("\n");
+  return `<!DOCTYPE html>
+<html lang="en" data-theme="light">
+<head>
+  <meta charset="UTF-8" />
+  <meta name="viewport" content="width=device-width, initial-scale=1.0" />
+  <title>${esc(name)} \u2014 Design System Docs</title>
+  <link rel="icon" type="image/svg+xml" href="../assets/favicon.svg" />
+  <style>
+    /* \u2500\u2500 Theme tokens \u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500 */
+    [data-theme="light"] {
+${themeCssLight}
+    }
+    [data-theme="dark"] {
+${themeCssDark}
+    }
+
+    /* \u2500\u2500 Reset + base \u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500 */
+    *, *::before, *::after { box-sizing: border-box; margin: 0; padding: 0; }
+    html { font-size: 16px; }
+    body {
+      font-family: -apple-system, BlinkMacSystemFont, "Segoe UI", sans-serif;
+      background: var(--color-bg-subtle, #f8fafc);
+      color: var(--color-text-primary, #0f172a);
+      display: flex; min-height: 100vh; line-height: 1.5;
+    }
+
+    /* \u2500\u2500 Sidebar \u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500 */
+    .sidebar {
+      width: 220px; min-width: 220px;
+      background: var(--color-bg-default, #fff);
+      border-right: 1px solid var(--color-border-default, #e2e8f0);
+      height: 100vh; position: sticky; top: 0;
+      display: flex; flex-direction: column; overflow-y: auto;
+    }
+    .sidebar-header { padding: 18px 16px 14px; border-bottom: 1px solid var(--color-border-default, #e2e8f0); }
+    .sidebar-title { font-size: 14px; font-weight: 700; color: var(--color-text-primary, #0f172a); letter-spacing: -0.01em; }
+    .sidebar-version { font-size: 11px; color: var(--color-text-secondary, #64748b); margin-top: 2px; }
+    .sidebar-section { padding: 12px 8px 4px; }
+    .sidebar-section-label {
+      font-size: 10px; font-weight: 600; text-transform: uppercase;
+      letter-spacing: 0.08em; color: var(--color-text-secondary, #64748b);
+      padding: 0 8px; margin-bottom: 4px;
+    }
+    .nav-item {
+      display: block; padding: 5px 8px; border-radius: 5px;
+      font-size: 13px; color: var(--color-text-secondary, #64748b);
+      cursor: pointer; text-decoration: none;
+      transition: background 120ms, color 120ms;
+    }
+    .nav-item:hover { background: var(--color-bg-subtle, #f8fafc); color: var(--color-text-primary, #0f172a); }
+    .nav-item.active { background: var(--color-bg-overlay, #f1f5f9); color: var(--color-action, #2563eb); font-weight: 500; }
+
+    /* \u2500\u2500 Main \u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500 */
+    .main { flex: 1; overflow-y: auto; }
+    .topbar {
+      position: sticky; top: 0; z-index: 10;
+      background: var(--color-bg-default, #fff);
+      border-bottom: 1px solid var(--color-border-default, #e2e8f0);
+      padding: 10px 32px;
+      display: flex; align-items: center; justify-content: space-between; gap: 16px;
+    }
+    .topbar-breadcrumb { font-size: 13px; color: var(--color-text-secondary, #64748b); }
+    .topbar-breadcrumb span { color: var(--color-text-primary, #0f172a); font-weight: 500; }
+    .topbar-actions { display: flex; gap: 8px; align-items: center; }
+    .theme-toggle {
+      display: flex; gap: 3px;
+      background: var(--color-bg-subtle, #f8fafc);
+      border: 1px solid var(--color-border-default, #e2e8f0);
+      border-radius: 7px; padding: 3px;
+    }
+    .theme-btn {
+      padding: 3px 10px; border-radius: 4px; border: none;
+      background: transparent; font-size: 12px; cursor: pointer;
+      color: var(--color-text-secondary, #64748b);
+      transition: background 120ms, color 120ms;
+    }
+    .theme-btn.active {
+      background: var(--color-bg-default, #fff);
+      color: var(--color-text-primary, #0f172a); font-weight: 500;
+      box-shadow: 0 1px 2px rgb(0 0 0 / 0.06);
+    }
+    .content { padding: 36px 40px 80px; max-width: 860px; }
+    .page { display: none; }
+    .page.active { display: block; }
+    .page-title {
+      font-size: 26px; font-weight: 700; letter-spacing: -0.02em;
+      color: var(--color-text-primary, #0f172a); margin-bottom: 4px;
+    }
+    .page-desc {
+      font-size: 14px; color: var(--color-text-secondary, #64748b);
+      margin-bottom: 28px; line-height: 1.65; max-width: 640px;
+    }
+    .section-block { margin-bottom: 36px; }
+    .group-title {
+      font-size: 11px; font-weight: 600; text-transform: uppercase;
+      letter-spacing: 0.07em; color: var(--color-text-secondary, #64748b);
+      margin-bottom: 14px; padding-bottom: 8px;
+      border-bottom: 1px solid var(--color-border-default, #e2e8f0);
+    }
+
+    /* \u2500\u2500 Foundations: colors \u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500 */
+    .swatch-grid { display: flex; flex-wrap: wrap; gap: 8px; }
+    .swatch {
+      width: 88px; height: 72px; border-radius: 8px; padding: 8px;
+      display: flex; flex-direction: column; justify-content: flex-end;
+      font-size: 10px; line-height: 1.3; border: 1px solid rgb(0 0 0 / 0.06);
+    }
+    .swatch-name { font-weight: 600; word-break: break-all; }
+    .swatch-value { opacity: 0.8; }
+
+    /* \u2500\u2500 Foundations: typography \u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500 */
+    .type-family {
+      font-size: 13px; color: var(--color-text-secondary, #64748b); font-family: monospace;
+      background: var(--color-bg-overlay, #f1f5f9);
+      display: inline-block; padding: 4px 10px; border-radius: 6px; margin-bottom: 24px;
+    }
+    .type-scale { display: flex; flex-direction: column; gap: 2px; }
+    .type-row { display: flex; align-items: center; gap: 24px; padding: 12px 0; border-bottom: 1px solid var(--color-border-default, #e2e8f0); }
+    .type-meta { width: 140px; min-width: 140px; }
+    .type-role { font-size: 12px; font-weight: 600; color: var(--color-action, #2563eb); display: block; }
+    .type-spec { font-size: 11px; color: var(--color-text-secondary, #64748b); font-family: monospace; }
+    .type-sample { flex: 1; color: var(--color-text-primary, #0f172a); }
+
+    /* \u2500\u2500 Foundations: spacing \u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500 */
+    .spacing-list { display: flex; flex-direction: column; gap: 10px; }
+    .spacing-row { display: flex; align-items: center; gap: 16px; }
+    .spacing-key { width: 160px; min-width: 160px; font-size: 12px; font-family: monospace; color: var(--color-text-secondary, #64748b); }
+    .spacing-bar-wrap { flex: 1; }
+    .spacing-bar { height: 8px; background: var(--color-action, #2563eb); border-radius: 4px; min-width: 4px; opacity: 0.7; }
+    .spacing-val { width: 48px; font-size: 12px; color: var(--color-text-secondary, #64748b); font-family: monospace; text-align: right; }
+
+    /* \u2500\u2500 Foundations: radius \u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500 */
+    .radius-grid { display: flex; flex-wrap: wrap; gap: 24px; }
+    .radius-item { display: flex; flex-direction: column; align-items: center; gap: 8px; }
+    .radius-box { width: 64px; height: 64px; background: var(--color-action, #2563eb); opacity: 0.15; border: 2px solid var(--color-action, #2563eb); }
+    .radius-key { font-size: 12px; font-weight: 600; color: var(--color-text-primary, #0f172a); }
+    .radius-val { font-size: 11px; color: var(--color-text-secondary, #64748b); font-family: monospace; }
+
+    /* \u2500\u2500 Foundations: elevation \u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500 */
+    .elevation-grid { display: flex; flex-wrap: wrap; gap: 24px; align-items: flex-start; }
+    .elevation-item { display: flex; flex-direction: column; align-items: center; gap: 12px; }
+    .elevation-box { width: 80px; height: 80px; background: var(--color-bg-default, #fff); border-radius: 10px; border: 1px solid var(--color-border-default, #e2e8f0); }
+    .elevation-key { font-size: 12px; font-weight: 600; color: var(--color-text-primary, #0f172a); }
+    .elevation-val { font-size: 10px; color: var(--color-text-secondary, #64748b); font-family: monospace; text-align: center; max-width: 120px; word-break: break-all; }
+
+    /* \u2500\u2500 Foundations: motion \u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500 */
+    .motion-grid { display: flex; flex-direction: column; gap: 12px; }
+    .motion-item {
+      display: flex; align-items: center; gap: 16px; cursor: pointer;
+      padding: 10px 12px; border-radius: 8px;
+      border: 1px solid var(--color-border-default, #e2e8f0);
+      background: var(--color-bg-default, #fff); transition: border-color 150ms;
+    }
+    .motion-item:hover { border-color: var(--color-action, #2563eb); }
+    .motion-track { width: 140px; height: 12px; background: var(--color-bg-overlay, #f1f5f9); border-radius: 6px; position: relative; overflow: hidden; }
+    .motion-dot { position: absolute; left: 4px; top: 2px; width: 8px; height: 8px; border-radius: 50%; background: var(--color-action, #2563eb); transform: translateX(0); }
+    .motion-key { width: 100px; font-size: 12px; font-weight: 600; color: var(--color-text-primary, #0f172a); }
+    .motion-val { flex: 1; font-size: 12px; font-family: monospace; color: var(--color-text-secondary, #64748b); }
+    .motion-hint { font-size: 11px; color: var(--color-text-secondary, #64748b); margin-left: auto; }
+
+    /* \u2500\u2500 Component tab bar \u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500 */
+    .comp-tab-bar {
+      display: flex;
+      border-bottom: 1px solid var(--color-border-default, #e2e8f0);
+      margin-bottom: 28px;
+    }
+    .comp-tab {
+      padding: 8px 16px;
+      background: none; border: none; border-bottom: 2px solid transparent;
+      font-size: 13px; font-weight: 500; cursor: pointer;
+      color: var(--color-text-secondary, #64748b);
+      margin-bottom: -1px; transition: color 120ms, border-color 120ms;
+    }
+    .comp-tab:hover { color: var(--color-text-primary, #0f172a); }
+    .comp-tab.active { color: var(--color-action, #2563eb); border-bottom-color: var(--color-action, #2563eb); }
+    .comp-tab-panel { display: none; }
+    .comp-tab-panel.active { display: block; }
+
+    /* \u2500\u2500 Component overview \u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500 */
+    .comp-overview-section { margin-bottom: 28px; }
+    .comp-overview-label {
+      font-size: 11px; font-weight: 600; text-transform: uppercase;
+      letter-spacing: 0.07em; color: var(--color-text-secondary, #64748b); margin-bottom: 12px;
+    }
+    .comp-preview-row {
+      display: flex; flex-wrap: wrap; gap: 12px; align-items: center;
+      padding: 24px; background: var(--color-bg-default, #fff);
+      border: 1px solid var(--color-border-default, #e2e8f0); border-radius: 10px;
+    }
+    .comp-preview-col {
+      display: flex; flex-direction: column; gap: 16px;
+      padding: 24px; max-width: 400px;
+      background: var(--color-bg-default, #fff);
+      border: 1px solid var(--color-border-default, #e2e8f0); border-radius: 10px;
+    }
+
+    /* \u2500\u2500 Props table \u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500 */
+    .props-table { width: 100%; border-collapse: collapse; font-size: 13px; }
+    .props-table th {
+      text-align: left; padding: 8px 12px;
+      font-size: 11px; font-weight: 600; text-transform: uppercase; letter-spacing: 0.06em;
+      color: var(--color-text-secondary, #64748b);
+      border-bottom: 2px solid var(--color-border-default, #e2e8f0);
+    }
+    .props-table td { padding: 10px 12px; border-bottom: 1px solid var(--color-border-default, #e2e8f0); vertical-align: top; line-height: 1.5; }
+    .props-table tr:last-child td { border-bottom: none; }
+    .prop-name    { font-family: monospace; font-size: 13px; color: var(--color-text-primary, #0f172a); font-weight: 600; }
+    .prop-type    { font-family: monospace; font-size: 12px; color: var(--color-action, #2563eb); }
+    .prop-default { font-family: monospace; font-size: 12px; color: var(--color-text-secondary, #64748b); }
+    .prop-desc    { font-size: 13px; color: var(--color-text-secondary, #64748b); }
+    .prop-required-cell { text-align: center; }
+    .prop-required {
+      display: inline-block; font-size: 10px; font-weight: 700;
+      text-transform: uppercase; letter-spacing: 0.04em;
+      color: #dc2626; background: #fef2f2;
+      border: 1px solid #fecaca; border-radius: 4px; padding: 2px 6px;
+    }
+    .prop-optional { color: var(--color-text-secondary, #64748b); font-size: 13px; }
+
+    /* \u2500\u2500 Examples \u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500 */
+    .example-block { border: 1px solid var(--color-border-default, #e2e8f0); border-radius: 10px; overflow: hidden; margin-bottom: 20px; }
+    .example-header { padding: 14px 16px; border-bottom: 1px solid var(--color-border-default, #e2e8f0); background: var(--color-bg-default, #fff); }
+    .example-label { font-size: 13px; font-weight: 600; color: var(--color-text-primary, #0f172a); }
+    .example-desc  { font-size: 12px; color: var(--color-text-secondary, #64748b); margin-top: 2px; }
+    .example-preview { padding: 28px 24px; background: var(--color-bg-subtle, #f8fafc); border-bottom: 1px solid var(--color-border-default, #e2e8f0); }
+    .example-code-wrap { position: relative; }
+    .example-code-bar {
+      display: flex; justify-content: space-between; align-items: center;
+      padding: 6px 14px;
+      background: var(--color-bg-overlay, #f1f5f9);
+      color: var(--color-text-secondary, #64748b);
+      font-size: 11px; font-weight: 600; letter-spacing: 0.05em;
+      border-bottom: 1px solid var(--color-border-default, #e2e8f0);
+    }
+    .copy-btn {
+      background: transparent; border: 1px solid var(--color-border-default, #e2e8f0);
+      color: var(--color-text-secondary, #64748b); font-size: 11px; padding: 3px 10px;
+      border-radius: 4px; cursor: pointer; transition: background 120ms, color 120ms;
+    }
+    .copy-btn:hover { background: var(--color-bg-subtle, #f8fafc); color: var(--color-text-primary, #0f172a); }
+    .copy-btn.copied { color: #16a34a; border-color: #16a34a; }
+    .example-code {
+      margin: 0; padding: 16px 18px;
+      background: var(--color-bg-default, #fff);
+      color: var(--color-text-primary, #0f172a);
+      border: 1px solid var(--color-border-default, #e2e8f0); border-top: none;
+      font-family: "SF Mono", "Fira Code", "Cascadia Code", monospace;
+      font-size: 12.5px; line-height: 1.65; overflow-x: auto; white-space: pre;
+    }
+
+    /* \u2500\u2500 Accessibility \u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500 */
+    .a11y-list { display: flex; flex-direction: column; gap: 1px; }
+    .a11y-item { padding: 16px; border: 1px solid var(--color-border-default, #e2e8f0); border-radius: 8px; margin-bottom: 10px; background: var(--color-bg-default, #fff); }
+    .a11y-header { display: flex; align-items: center; gap: 10px; margin-bottom: 6px; }
+    .a11y-criterion { font-size: 13px; font-weight: 600; color: var(--color-text-primary, #0f172a); }
+    .a11y-badge { font-size: 10px; font-weight: 700; padding: 2px 7px; border-radius: 99px; letter-spacing: 0.04em; }
+    .a11y-badge-a   { background: #f0fdf4; color: #15803d; border: 1px solid #bbf7d0; }
+    .a11y-badge-aa  { background: #eff6ff; color: #1d4ed8; border: 1px solid #bfdbfe; }
+    .a11y-badge-aaa { background: #faf5ff; color: #7e22ce; border: 1px solid #e9d5ff; }
+    .a11y-desc { font-size: 13px; color: var(--color-text-secondary, #64748b); line-height: 1.6; }
+
+    /* \u2500\u2500 AI Metadata \u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500 */
+    .ai-meta-intro { padding: 14px 16px; background: var(--color-bg-overlay, #f1f5f9); border: 1px solid var(--color-border-default, #e2e8f0); border-radius: 8px; margin-bottom: 4px; }
+    .ai-meta-intro p { font-size: 13px; color: var(--color-text-secondary, #64748b); line-height: 1.6; }
+    .ai-meta-intro code { font-family: monospace; font-size: 12px; color: var(--color-action, #2563eb); }
+    .ai-guidance-list { padding-left: 20px; display: flex; flex-direction: column; gap: 8px; margin-top: 10px; }
+    .ai-guidance-list li { font-size: 13px; color: var(--color-text-secondary, #64748b); line-height: 1.6; }
+
+    /* \u2500\u2500 Locked tabs \u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500 */
+    .comp-tab.locked { opacity: 0.45; cursor: default; }
+    .comp-tab.locked:hover { color: var(--color-text-secondary, #64748b); }
+    .locked-panel {
+      display: flex; flex-direction: column; align-items: center; justify-content: center;
+      padding: 64px 32px; text-align: center;
+      border: 1px dashed var(--color-border-default, #e2e8f0); border-radius: 10px;
+      background: var(--color-bg-subtle, #f8fafc);
+    }
+    .locked-icon { font-size: 28px; color: var(--color-text-secondary, #64748b); margin-bottom: 12px; }
+    .locked-title { font-size: 14px; font-weight: 600; color: var(--color-text-primary, #0f172a); margin-bottom: 8px; }
+    .locked-desc { font-size: 13px; color: var(--color-text-secondary, #64748b); max-width: 360px; line-height: 1.6; margin-bottom: 6px; }
+    .locked-hint { font-size: 12px; color: var(--color-text-secondary, #64748b); font-family: monospace; }
+    .locked-hint code { background: var(--color-bg-overlay, #f1f5f9); padding: 1px 6px; border-radius: 4px; border: 1px solid var(--color-border-default, #e2e8f0); }
+
+    /* \u2500\u2500 Component primitives \u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500 */
+    .ds-btn { border: none; cursor: pointer; font-size: 14px; font-weight: 500; padding: 8px 16px; transition: filter 120ms; }
+    .ds-btn:hover:not(:disabled) { filter: brightness(0.92); }
+    .ds-field { display: flex; flex-direction: column; gap: 4px; }
+    .ds-label { font-size: 13px; font-weight: 500; }
+    .ds-input { border: 1.5px solid; padding: 8px 12px; font-size: 14px; outline: none; transition: border-color 150ms, box-shadow 150ms; width: 100%; }
+    .ds-input:focus { box-shadow: 0 0 0 3px color-mix(in srgb, var(--color-action, #2563eb) 20%, transparent); border-color: var(--color-action, #2563eb) !important; }
+    .ds-card { border: 1px solid; overflow: hidden; width: 220px; }
+    .ds-card-header { padding: 12px 14px; font-size: 14px; font-weight: 600; }
+    .ds-card-body   { padding: 12px 14px; }
+    .ds-card-footer { padding: 10px 14px; display: flex; justify-content: flex-end; }
+
+    /* \u2500\u2500 Spinner animation \u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500 */
+    @keyframes dsforge-spin { to { transform: rotate(360deg); } }
+    @media (prefers-reduced-motion: reduce) { @keyframes dsforge-spin { to { transform: none; } } }
+  </style>
+</head>
+<body>
+
+  <aside class="sidebar">
+    <div class="sidebar-header">
+      <div class="sidebar-title">${esc(name)}</div>
+      <div class="sidebar-version">v${esc(version)}${themes.length ? " \xB7 " + themes.join(", ") : ""}</div>
+    </div>
+    <div class="sidebar-section">
+      <div class="sidebar-section-label">Foundations</div>
+      ${foundationItems.map(
+    (item) => `
+        <a class="nav-item${item.id === "colors" ? " active" : ""}" onclick="showPage('${item.id}', this)" href="#">${esc(item.label)}</a>
+      `
+  ).join("")}
+    </div>
+    <div class="sidebar-section">
+      <div class="sidebar-section-label">Components</div>
+      ${componentItems.map(
+    (item) => `
+        <a class="nav-item" onclick="showPage('${item.id}', this)" href="#">${esc(item.label)}</a>
+      `
+  ).join("")}
+    </div>
+  </aside>
+
+  <div class="main">
+    <div class="topbar">
+      <div class="topbar-breadcrumb">
+        ${esc(name)} / <span id="topbar-current">Colors</span>
+      </div>
+      <div class="topbar-actions">
+        ${themes.length >= 2 ? `
+          <div class="theme-toggle">
+            ${themes.map(
+    (t, i) => `
+              <button class="theme-btn${i === 0 ? " active" : ""}" onclick="setTheme('${t}', this)">${esc(t)}</button>
+            `
+  ).join("")}
+          </div>
+        ` : ""}
+      </div>
+    </div>
+
+    <div class="content">
+      ${allItems.map(
+    ({ id, label }) => `
+        <div class="page${id === "colors" ? " active" : ""}" id="page-${id}">
+          <h1 class="page-title">${esc(label)}</h1>
+          <p class="page-desc">${esc(pageDesc(id, name))}</p>
+          ${sections[id] ?? ""}
+        </div>
+      `
+  ).join("")}
+    </div>
+  </div>
+
+  <script>
+    function showPage(id, el) {
+      document.querySelectorAll('.page').forEach(p => p.classList.remove('active'));
+      document.querySelectorAll('.nav-item').forEach(n => n.classList.remove('active'));
+      document.getElementById('page-' + id).classList.add('active');
+      el.classList.add('active');
+      document.getElementById('topbar-current').textContent = el.textContent.trim();
+    }
+
+    function setTheme(name, btn) {
+      document.documentElement.setAttribute('data-theme', name);
+      document.querySelectorAll('.theme-btn').forEach(b => b.classList.remove('active'));
+      btn.classList.add('active');
+    }
+
+    function switchTab(compId, tabId, btn) {
+      const tabs   = document.querySelectorAll('#' + compId + '-tabs .comp-tab');
+      const panels = document.querySelectorAll('#' + compId + '-tabs .comp-tab-panel');
+      tabs.forEach(t => { t.classList.remove('active'); t.setAttribute('aria-selected', 'false'); });
+      panels.forEach(p => p.classList.remove('active'));
+      btn.classList.add('active');
+      btn.setAttribute('aria-selected', 'true');
+      document.getElementById(compId + '-panel-' + tabId).classList.add('active');
+    }
+
+    function copyCode(id, btn) {
+      const code = document.getElementById(id).textContent;
+      navigator.clipboard.writeText(code).then(() => {
+        btn.textContent = 'Copied!';
+        btn.classList.add('copied');
+        setTimeout(() => { btn.textContent = 'Copy'; btn.classList.remove('copied'); }, 2000);
+      });
+    }
+  </script>
+</body>
+</html>`;
+}
+function pageDesc(id, name) {
+  const foundations = {
+    colors: `The color tokens used across ${name}. Global palette tokens are the raw values; semantic tokens map intent to palette.`,
+    typography: `Type scale and font settings for ${name}. All sizes, weights, and line heights.`,
+    spacing: `Spacing scale based on the configured base unit. Used for padding, margin, and gap values.`,
+    radius: `Border radius tokens. Applied to buttons, inputs, cards, and other surfaces.`,
+    elevation: `Box shadow levels. Higher levels appear more elevated.`,
+    motion: `Duration and easing tokens. Click any row to preview the animation.`
+  };
+  if (id in foundations) return foundations[id] ?? "";
+  const entry = SHOWCASE_COMPONENTS.find((c) => c.id === id);
+  return entry?.pageDescription ?? "";
+}
+export {
+  generateShowcase
+};