holygrail5 1.0.19 → 1.0.21

package/src/build/theme-config-loader.js

@@ -0,0 +1,58 @@
+// Loader del JSON de configuración de tema
+// Cada tema vive en themes/<nombre>/ y puede tener un theme.json con:
+//   - meta              → nombre, descripción, versión, autor (para la demo)
+//   - tokenOverrides    → overrides de tokens HG5 por tema (color/spacing)
+//   - componentVars     → variables CSS de componentes (--btn-*, --input-*, etc.)
+//   - design            → tokens de diseño del tema (border-radius, transition…)
+//
+// El archivo es OPCIONAL. Si no existe, devolvemos null y el resto del build
+// sigue funcionando exactamente como antes — la única consecuencia es que la
+// demo no mostrará la cabecera de meta ni las tablas de variables del tema.
+
+const fs = require('fs');
+const path = require('path');
+
+/**
+ * Devuelve la ruta absoluta esperada del theme.json para un tema dado.
+ */
+function getThemeConfigPath(projectRoot, themeName) {
+  return path.join(projectRoot, 'themes', themeName, 'theme.json');
+}
+
+/**
+ * Carga themes/<themeName>/theme.json si existe. Si no existe o el JSON es
+ * inválido, devuelve null (con un warning si silent === false). Nunca lanza:
+ * el config de tema es opcional y no debe romper el build.
+ */
+function loadThemeConfig(projectRoot, themeName, silent = false) {
+  if (!themeName) return null;
+
+  const themeConfigPath = getThemeConfigPath(projectRoot, themeName);
+  if (!fs.existsSync(themeConfigPath)) return null;
+
+  try {
+    const raw = fs.readFileSync(themeConfigPath, 'utf8');
+    const parsed = JSON.parse(raw);
+
+    // Normalizamos para que el resto del código asuma que las claves existen
+    parsed.meta = parsed.meta || {};
+    parsed.tokenOverrides = parsed.tokenOverrides || {};
+    parsed.componentVars = parsed.componentVars || {};
+    parsed.design = parsed.design || {};
+
+    // Si el JSON no trae nombre, usamos el del directorio
+    if (!parsed.meta.name) parsed.meta.name = themeName;
+
+    if (!silent) {
+      console.log(`✅ theme.json cargado: themes/${themeName}/theme.json`);
+    }
+    return parsed;
+  } catch (error) {
+    if (!silent) {
+      console.warn(`⚠️  No se pudo cargar themes/${themeName}/theme.json:`, error.message);
+    }
+    return null;
+  }
+}
+
+module.exports = { loadThemeConfig, getThemeConfigPath };

package/src/build/theme-transformer.js

@@ -3,6 +3,9 @@
 
 const fs = require('fs');
 const path = require('path');
+const { generateTypographyHTML } = require('./typo-table-generator');
+const { generateThemeBlockHTML } = require('./theme-vars-table-generator');
+const { applyThemeTypographyOverrides } = require('../generators/utils');
 
 // Estilos del sidebar + Lenis (solo para dutti-demo.html en dist)
 const SIDEBAR_STYLES = `
@@ -24,31 +27,84 @@ const SIDEBAR_STYLES = `
     }
 `;
 
-// HTML del header y sidebar
-const HEADER_AND_SIDEBAR_HTML = `
+// Fallback de temas conocidos para la navegación de cada demo, usado
+// cuando el llamador NO inyecta una lista dinámica (p. ej. tests o
+// ejecuciones standalone del ThemeTransformer sin pasar por
+// BuildOrchestrator). En modo build normal, esta lista se sustituye por
+// los temas realmente activos en `config.themes[]`, de forma que
+// nunca se genere un enlace `../themes/<x>-demo.html` a un fichero
+// que no existe en `dist/themes/`.
+// El orden aquí determina el orden en el que aparecen los enlaces.
+// `name` es el slug del tema (coincide con la carpeta themes/<name>/ y
+// con el fichero generado themes/<name>-demo.html). `label` es el
+// texto visible en la nav principal.
+const THEMES_IN_NAV = [
+  { name: 'dutti', label: 'Tema Dutti' },
+  { name: 'limited', label: 'Tema Limited' }
+];
+
+// Capitaliza un slug para usarlo como nombre legible en el sidebar
+// (p. ej. 'dutti' → 'Dutti', 'limited' → 'Limited').
+function capitalize(s) {
+  if (!s) return '';
+  return s.charAt(0).toUpperCase() + s.slice(1);
+}
+
+/**
+ * Construye el HTML del header + sidebar para una demo concreta.
+ * El enlace del tema actual se marca con la clase `active` para que
+ * el usuario vea en qué tema está. Los enlaces a otros temas apuntan
+ * al fichero `../themes/<slug>-demo.html` correspondiente.
+ *
+ * @param {string} currentTheme - slug del tema activo (p. ej. 'dutti')
+ * @param {Array<{name:string,label:string}>} [themesForNav] - Lista de
+ *   temas a mostrar en la nav. Si se omite o viene vacía, se usa el
+ *   fallback `THEMES_IN_NAV`. Inyectar esta lista desde el build evita
+ *   que la demo enlace a temas que no se han generado en `dist/themes/`.
+ * @returns {string} HTML listo para inyectar tras `<body>`.
+ */
+function buildHeaderAndSidebar(currentTheme, themesForNav = null) {
+  const list = Array.isArray(themesForNav) && themesForNav.length > 0
+    ? themesForNav
+    : THEMES_IN_NAV;
+
+  const themeLinks = list.map(t => {
+    const cls = t.name === currentTheme ? ' class="active"' : '';
+    return `        <a href="../themes/${t.name}-demo.html"${cls}>${t.label}</a>`;
+  }).join('\n');
+
+  const displayName = capitalize(currentTheme);
+
+  return `
   <div class="guide-header">
     <a href="../index.html" class="guide-logo" style="text-decoration:none;">HolyGrail5</a>
     <div style="display: flex; align-items: center; gap: 1rem;">
       <nav class="guide-nav">
         <a href="../index.html">Guía</a>
-        <a href="../themes/dutti-demo.html" class="active">Tema Dutti</a>
+        <a href="../componentes.html">Componentes</a>
+${themeLinks}
         <a href="../skills.html">Skills</a>
       </nav>
       <button class="guide-header-button" onclick="toggleSidebar()">☰</button>
     </div>
   </div>
-  
+
   <div class="guide-sidebar-overlay" onclick="toggleSidebar()"></div>
-  
+
   <aside class="guide-sidebar">
     <div class="guide-sidebar-header">
       <div>HolyGrail5</div>
-      <p class="guide-sidebar-subtitle">Demo Tema Dutti</p>
+      <p class="guide-sidebar-subtitle">Demo Tema ${displayName}</p>
     </div>
 
     <nav class="guide-sidebar-nav">
+      <p class="guide-sidebar-title">Tema</p>
+
+      <a href="#theme-vars" class="guide-menu-item">Variables del tema</a>
+
       <p class="guide-sidebar-title">Componentes</p>
-      
+
+      <a href="#typography" class="guide-menu-item">Tipografía</a>
       <a href="#buttons" class="guide-menu-item">Botones</a>
       <a href="#inputs" class="guide-menu-item">Inputs</a>
       <a href="#checkboxes" class="guide-menu-item">Checkboxes</a>
@@ -57,7 +113,7 @@ const HEADER_AND_SIDEBAR_HTML = `
       <a href="#forms" class="guide-menu-item">Formularios</a>
     </nav>
   </aside>
-  
+
   <script>
     function toggleSidebar() {
       const sidebar = document.querySelector('.guide-sidebar');
@@ -65,19 +121,20 @@ const HEADER_AND_SIDEBAR_HTML = `
       sidebar.classList.toggle('open');
       overlay.classList.toggle('active');
     }
-    
+
     function closeSidebar() {
       const sidebar = document.querySelector('.guide-sidebar');
       const overlay = document.querySelector('.guide-sidebar-overlay');
       sidebar.classList.remove('open');
       overlay.classList.remove('active');
     }
-    
+
     // Hacer funciones globales
     window.toggleSidebar = toggleSidebar;
     window.closeSidebar = closeSidebar;
   </script>
 `;
+}
 
 // Script de Lenis para el head
 const LENIS_HEAD_SCRIPT = `
@@ -153,9 +210,14 @@ class ThemeTransformer {
    * @param {string} destPath - Ruta donde guardar el HTML transformado
    * @param {string} themeName - Nombre del tema (para personalización)
    * @param {boolean} silent - Si true, no muestra mensajes
+   * @param {Object} [config] - Config cargado de config.json (para inyectar tablas dinámicas como tipografía)
+   * @param {Object} [themeData] - theme.json parseado (para inyectar meta + tablas de variables del tema)
+   * @param {Array<{name:string,label:string}>} [themesForNav] - Lista de
+   *   temas activos a exponer en la nav del demo. Si se omite, se usa
+   *   el fallback estático de theme-transformer (dutti + limited).
    * @returns {boolean} - true si se transformó exitosamente
    */
-  transform(sourcePath, destPath, themeName = 'dutti', silent = false) {
+  transform(sourcePath, destPath, themeName = 'dutti', silent = false, config = null, themeData = null, themesForNav = null) {
     const fullSourcePath = path.isAbsolute(sourcePath)
       ? sourcePath
       : path.join(this.projectRoot, sourcePath);
@@ -174,7 +236,32 @@ class ThemeTransformer {
     try {
       // Leer el contenido
       let content = fs.readFileSync(fullSourcePath, 'utf8');
-      
+
+      // Inyectar bloques dinámicos derivados del config (p. ej. tabla de tipografía).
+      // Si el HTML fuente no contiene el placeholder, se ignora silenciosamente.
+      //
+      // Para cada tema aplicamos los overrides de tipografía declarados
+      // en `theme.json → typography.fontFamilyMap`. Así la tabla
+      // muestra la fuente real del tema (Suisse Works en Limited, por
+      // ejemplo) en vez de la fuente base de config.json.
+      if (config) {
+        const typoConfig = applyThemeTypographyOverrides(config, themeData);
+        const typoSection = generateTypographyHTML(typoConfig);
+        content = content.replace(/<!--\s*HG_TYPO_TABLE\s*-->/g, typoSection);
+      } else {
+        // Sin config, eliminamos el placeholder para no mostrarlo en crudo
+        content = content.replace(/<!--\s*HG_TYPO_TABLE\s*-->/g, '');
+      }
+
+      // Inyectar bloque del tema (meta + tablas de variables) si hay theme.json.
+      // Si no lo hay, quitamos el placeholder para no dejar comentarios huérfanos.
+      if (themeData) {
+        const themeBlock = generateThemeBlockHTML(themeData, config);
+        content = content.replace(/<!--\s*HG_THEME_BLOCK\s*-->/g, themeBlock);
+      } else {
+        content = content.replace(/<!--\s*HG_THEME_BLOCK\s*-->/g, '');
+      }
+
       // Ajustar rutas CSS
       content = content.replace(/href="\.\.\/\.\.\/dist\/output\.css"/g, 'href="../output.css"');
       content = content.replace(/href="\.\.\/output\.css"/g, 'href="../output.css"');
@@ -197,11 +284,17 @@ class ThemeTransformer {
       // Añadir inicialización de Lenis antes de </body>
       content = content.replace('</body>', `${LENIS_INIT_SCRIPT}\n</body>`);
       
-      // Añadir header y sidebar después del <body>
-      content = content.replace(/(<body[^>]*>)/i, '$1\n' + HEADER_AND_SIDEBAR_HTML);
-      
+      // Añadir header y sidebar después del <body>.
+      // La nav principal se construye dinámicamente a partir del tema
+      // activo, marcando su enlace con `active` y dejando los otros
+      // temas accesibles como enlaces normales. Si el build ha pasado
+      // la lista de temas activos, se respeta; si no, se cae al
+      // fallback estático THEMES_IN_NAV (compatibilidad).
+      const headerAndSidebarHTML = buildHeaderAndSidebar(themeName, themesForNav);
+      content = content.replace(/(<body[^>]*>)/i, '$1\n' + headerAndSidebarHTML);
+
       // Eliminar el título h1 del contenido si existe (ya está en el header)
-      content = content.replace(/<h1 class="demo-title">Sistema de Theming Dutti<\/h1>\s*/g, '');
+      content = content.replace(/<h1 class="demo-title">Sistema de Theming [^<]+<\/h1>\s*/g, '');
       
       // Envolver el contenido de demo-container con guide-container
       content = content.replace(

package/src/build/theme-vars-table-generator.js

@@ -0,0 +1,349 @@
+// Generador de la cabecera de meta y de las tablas de variables del tema.
+// Lee el theme.json (cargado por theme-config-loader) y produce HTML para
+// inyectar en la demo del tema. Si no hay theme.json o el bloque está vacío,
+// devuelve string vacío para mantener la demo limpia.
+
+function escapeHtml(str) {
+  if (str === undefined || str === null) return '';
+  return String(str)
+    .replace(/&/g, '&')
+    .replace(/</g, '&lt;')
+    .replace(/>/g, '&gt;')
+    .replace(/"/g, '&quot;');
+}
+
+/**
+ * Estilos comunes para las tablas del tema. Se inyectan una sola vez.
+ */
+const SHARED_STYLES = `
+        <style>
+          .hg-theme-meta {
+            margin-bottom: 32px;
+            padding: 20px 24px;
+            border-left: 4px solid var(--hg-color-primary, #000);
+            background: var(--hg-color-bg-light, #f0f0f0);
+          }
+          .hg-theme-meta h3 { margin: 0 0 4px; font-size: 22px; font-family: arial, sans-serif; }
+          .hg-theme-meta .hg-theme-meta-line {
+            font-size: 12px; color: var(--hg-color-dark-grey, #737373);
+            text-transform: uppercase; letter-spacing: 0.06em;
+          }
+          .hg-theme-meta p { margin: 12px 0 0; font-size: 14px; line-height: 1.6; }
+          .hg-vars-group { margin: 0; }
+          .hg-vars-group h4 {
+            margin: 0 0 8px; font-family: arial, sans-serif; font-size: 14px;
+            text-transform: uppercase; letter-spacing: 0.06em;
+            color: var(--hg-color-dark-grey, #737373);
+          }
+          /* 3 columnas verticales manuales (grid), balanceadas por item count */
+          .hg-vars-columns {
+            display: grid;
+            grid-template-columns: repeat(3, minmax(0, 1fr));
+            gap: 32px;
+            font-family: arial, sans-serif;
+            font-size: 11px;
+            align-items: start;
+          }
+          @media (max-width: 960px) {
+            .hg-vars-columns { grid-template-columns: repeat(2, minmax(0, 1fr)); }
+          }
+          @media (max-width: 600px) {
+            .hg-vars-columns { grid-template-columns: 1fr; }
+          }
+          .hg-vars-col {
+            display: flex;
+            flex-direction: column;
+            gap: 24px;
+            min-width: 0;
+          }
+          /* Lista de variables dentro del grupo: nombre izquierda, valor derecha */
+          .hg-vars-list {
+            display: flex;
+            flex-direction: column;
+          }
+          .hg-vars-item {
+            display: flex;
+            align-items: center;
+            justify-content: space-between;
+            gap: 8px;
+            padding: 5px 0;
+            border-bottom: 1px solid var(--hg-color-middle-grey, #a9a9a9);
+            min-width: 0;
+          }
+          .hg-vars-item .hg-vars-name,
+          .hg-vars-item .hg-vars-value {
+            display: flex;
+            align-items: center;
+            min-width: 0;
+          }
+          .hg-vars-item .hg-vars-name { flex: 1 1 auto; }
+          .hg-vars-item .hg-vars-value { flex: 0 0 auto; justify-content: flex-end; text-align: right; }
+          .hg-vars-item code {
+            background: var(--hg-color-bg-light, #f0f0f0);
+            padding: 2px 5px;
+            border-radius: 3px;
+            font-size: 10.5px;
+            line-height: 1.35;
+            word-break: break-all;
+            white-space: normal;
+          }
+          .hg-vars-item .hg-vars-name code { color: #000; font-weight: 600; }
+          .hg-vars-item .hg-vars-value code { color: #333; }
+          .hg-vars-item.is-overridden .hg-vars-name code { color: var(--hg-color-feel-dark, #c94c07); }
+          .hg-vars-item .hg-vars-badge {
+            display: inline-block;
+            margin-left: 6px;
+            padding: 1px 5px;
+            font-size: 9px;
+            font-weight: 600;
+            letter-spacing: 0.04em;
+            text-transform: uppercase;
+            background: var(--hg-color-feel, #fb9962);
+            color: #fff;
+            border-radius: 2px;
+          }
+          .hg-vars-swatch {
+            display: inline-block; width: 12px; height: 12px;
+            border-radius: 3px; vertical-align: middle;
+            margin-left: 6px;
+            border: 1px solid var(--hg-color-middle-grey, #a9a9a9);
+            flex-shrink: 0;
+            order: 2;
+          }
+          /* Sección de colores semánticos: swatch al final de la fila, 18x18 */
+          .hg-vars-group-semantic .hg-vars-swatch {
+            width: 18px; height: 18px;
+            margin-right: 0;
+            margin-left: 8px;
+            order: 2;
+          }
+          .hg-vars-group-semantic .hg-vars-item { padding: 7px 0; }
+          .hg-vars-group-semantic .hg-vars-value { gap: 0; }
+          .hg-vars-empty { color: var(--hg-color-middle-grey, #a9a9a9); font-style: italic; padding: 12px; }
+        </style>`;
+
+/**
+ * Cabecera con la meta del tema (nombre, descripción, versión, autor).
+ */
+function generateThemeMetaHTML(themeData) {
+  if (!themeData || !themeData.meta) return '';
+  const m = themeData.meta;
+  if (!m.displayName && !m.name && !m.description) return '';
+
+  const displayName = m.displayName || m.name || 'Tema';
+  const lineParts = [];
+  if (m.name) lineParts.push(escapeHtml(m.name));
+  if (m.version) lineParts.push(`v${escapeHtml(m.version)}`);
+  if (m.author) lineParts.push(escapeHtml(m.author));
+  const line = lineParts.join(' · ');
+
+  return `      <div class="hg-theme-meta">
+        <div class="hg-theme-meta-line">${line || 'Tema'}</div>
+        <h3>${escapeHtml(displayName)}</h3>
+        ${m.description ? `<p>${escapeHtml(m.description)}</p>` : ''}
+      </div>`;
+}
+
+/**
+ * Resuelve un valor que puede ser un literal de color (#…, rgb…, hsl…)
+ * o una referencia a una variable CSS `var(--hg-color-xxx)`. Devuelve el
+ * color final aplicable o null si no se puede resolver.
+ */
+function resolveColor(value, config, themeData, depth = 0) {
+  if (!value || depth > 5) return null;
+  if (/^(#|rgb|hsl)/i.test(value)) return value;
+  const m = String(value).match(/var\(\s*--hg-color-([\w-]+)\s*\)/);
+  if (!m) return null;
+  const key = m[1];
+  const overrides = (themeData && themeData.tokenOverrides && themeData.tokenOverrides.color) || {};
+  const baseColors = (config && config.colors) || {};
+  const resolved = Object.prototype.hasOwnProperty.call(overrides, key)
+    ? overrides[key]
+    : baseColors[key];
+  if (!resolved) return null;
+  return resolveColor(resolved, config, themeData, depth + 1);
+}
+
+function renderRow(name, value, prefix, opts = {}) {
+  const fullVar = prefix ? `--${prefix}-${name}` : `--${name}`;
+  // Swatch: si el valor es un color literal o un var(--hg-color-*) resoluble, lo mostramos
+  const resolvedColor = resolveColor(value, opts.config, opts.themeData);
+  const swatch = resolvedColor
+    ? `<span class="hg-vars-swatch" style="background:${escapeHtml(resolvedColor)}" title="${escapeHtml(resolvedColor)}"></span>`
+    : '';
+  const cls = opts.overridden ? ' is-overridden' : '';
+  const badge = opts.overridden ? '<span class="hg-vars-badge" title="Sobrescrito por el tema">tema</span>' : '';
+  // En la sección de colores semánticos el swatch va AL FINAL de la fila (después del valor).
+  // En el resto (componentes…) sigue yendo delante del valor.
+  const swatchAtEnd = !!opts.swatchAtEnd;
+  const valueHTML = swatchAtEnd
+    ? `<code>${escapeHtml(value)}</code>${swatch}`
+    : `${swatch}<code>${escapeHtml(value)}</code>`;
+  return `              <div class="hg-vars-item${cls}">
+                <div class="hg-vars-name"><code>${escapeHtml(fullVar)}</code>${badge}</div>
+                <div class="hg-vars-value">${valueHTML}</div>
+              </div>`;
+}
+
+/**
+ * Construye un grupo (título + lista de variables) y devuelve
+ * { html, count } para que la distribución en columnas pueda balancear.
+ */
+function buildGroup(title, entries, prefix, overriddenKeys = new Set(), ctx = {}, extraClass = '', rowOpts = {}) {
+  if (!entries || entries.length === 0) return null;
+  const rows = entries.map(([name, value]) => {
+    return renderRow(name, value, prefix, {
+      overridden: overriddenKeys.has(name),
+      config: ctx.config,
+      themeData: ctx.themeData,
+      swatchAtEnd: !!rowOpts.swatchAtEnd
+    });
+  }).join('\n');
+  const cls = extraClass ? ` ${extraClass}` : '';
+  const html = `        <div class="hg-vars-group${cls}">
+          <h4>${escapeHtml(title)} <span style="color:var(--hg-color-middle-grey, #a9a9a9);font-weight:400;">(${entries.length})</span></h4>
+          <div class="hg-vars-list">
+${rows}
+          </div>
+        </div>`;
+  return { html, count: entries.length + 1 /* +1 por el header */ };
+}
+
+/**
+ * Distribuye los grupos en N columnas balanceando el total de items (+header).
+ * Algoritmo greedy: cada grupo va a la columna con menor altura acumulada.
+ * Preserva el orden original dentro de cada columna.
+ * Los grupos con `pinLast: true` se anclan al final de la última columna,
+ * independientemente del balance.
+ */
+function distributeIntoColumns(groups, numCols = 3) {
+  const cols = Array.from({ length: numCols }, () => ({ items: [], count: 0 }));
+  const pinned = [];
+  groups.forEach(g => {
+    if (g.pinLast) {
+      pinned.push(g);
+      return;
+    }
+    // Encontrar columna con menor count (en caso de empate, la primera)
+    let target = cols[0];
+    for (let i = 1; i < cols.length; i++) {
+      if (cols[i].count < target.count) target = cols[i];
+    }
+    target.items.push(g.html);
+    target.count += g.count;
+  });
+  // Los grupos "pinLast" van siempre al final de la última columna
+  if (pinned.length) {
+    const last = cols[cols.length - 1];
+    pinned.forEach(g => {
+      last.items.push(g.html);
+      last.count += g.count;
+    });
+  }
+  return cols.map(c => `      <div class="hg-vars-col">\n${c.items.join('\n')}\n      </div>`).join('\n');
+}
+
+/**
+ * Sección con todas las variables del tema, agrupadas:
+ *   - Colores semánticos (del base, con overrides del tema si hay)
+ *   - Spacing overrides → si hay
+ *   - Component vars (btn, input, label…)
+ *   - Design tokens (border-radius, transition…)
+ */
+function generateThemeVarsHTML(themeData, config = null) {
+  if (!themeData) return '';
+
+  const groups = [];
+
+  const tokenOverrides = themeData.tokenOverrides || {};
+  const colorOverrides = tokenOverrides.color || {};
+  const tokenSpacing = tokenOverrides.spacing || {};
+
+  // 1) Colores semánticos — base + overrides del tema (si los hay)
+  // Se excluyen neutrales/utilitarios (blanco, negro, greys, backgrounds).
+  const NON_SEMANTIC_COLORS = new Set([
+    'white', 'black',
+    'dark-grey', 'middle-grey', 'light-grey', 'grey-ultra',
+    'bg-light', 'bg-cream'
+  ]);
+  const baseColors = (config && config.colors) || {};
+  const allColorKeys = new Set([
+    ...Object.keys(baseColors),
+    ...Object.keys(colorOverrides)
+  ]);
+  // Filtrar neutrales
+  const semanticKeys = Array.from(allColorKeys).filter(k => !NON_SEMANTIC_COLORS.has(k));
+  const ctx = { config, themeData };
+
+  // 1) Colores semánticos (al principio). Swatch al final de la fila, 18x18.
+  if (semanticKeys.length > 0) {
+    const overriddenKeys = new Set(Object.keys(colorOverrides));
+    const entries = semanticKeys.map(name => {
+      const value = overriddenKeys.has(name) ? colorOverrides[name] : baseColors[name];
+      return [name, value];
+    });
+    const g = buildGroup('Colores semánticos', entries, 'hg-color', overriddenKeys, ctx, 'hg-vars-group-semantic', { swatchAtEnd: true });
+    if (g) groups.push(g);
+  }
+
+  // 2) Spacing overrides (si hay)
+  if (Object.keys(tokenSpacing).length) {
+    const g = buildGroup('Spacing overrides', Object.entries(tokenSpacing), 'hg-spacing', new Set(), ctx, '', { swatchAtEnd: true });
+    if (g) groups.push(g);
+  }
+
+  // 3) Component vars (btn, input, label…)
+  const componentVars = themeData.componentVars || {};
+  Object.entries(componentVars).forEach(([component, vars]) => {
+    const g = buildGroup(`Componente: ${component}`, Object.entries(vars), component, new Set(), ctx, '', { swatchAtEnd: true });
+    if (g) groups.push(g);
+  });
+
+  // 4) Design tokens (sin prefijo)
+  const design = themeData.design || {};
+  if (Object.keys(design).length) {
+    const g = buildGroup('Design tokens', Object.entries(design), '', new Set(), ctx, '', { swatchAtEnd: true });
+    if (g) groups.push(g);
+  }
+
+  if (groups.length === 0) {
+    return `      <section class="demo-section" id="theme-vars">
+        <h2 class="demo-title">Variables del tema</h2>
+        <p class="hg-vars-empty">El theme.json no define variables. Añade <code>componentVars</code>, <code>tokenOverrides</code> o <code>design</code> para verlos aquí.</p>
+      </section>`;
+  }
+
+  const columnsHTML = distributeIntoColumns(groups, 3);
+
+  return `      <section class="demo-section" id="theme-vars">
+        <h2 class="demo-title">Variables del tema</h2>
+        <p class="mb-24">
+          Definidas en <code>themes/${escapeHtml(themeData.meta?.name || 'dutti')}/theme.json</code>. La fuente del CSS sigue siendo
+          <code>themes/${escapeHtml(themeData.meta?.name || 'dutti')}/_variables.css</code>; este JSON sirve como manifiesto del tema y para que
+          la demo muestre tablas siempre coherentes con sus tokens.
+        </p>
+        <div class="hg-vars-columns">
+${columnsHTML}
+        </div>
+      </section>`;
+}
+
+/**
+ * Bloque combinado: meta + sección variables. Devuelve string vacío si no hay datos.
+ * Incluye los estilos compartidos en la primera invocación.
+ */
+function generateThemeBlockHTML(themeData, config = null) {
+  if (!themeData) return '';
+  const meta = generateThemeMetaHTML(themeData);
+  const vars = generateThemeVarsHTML(themeData, config);
+  if (!meta && !vars) return '';
+  return `${SHARED_STYLES}
+${meta}
+${vars}`;
+}
+
+module.exports = {
+  generateThemeMetaHTML,
+  generateThemeVarsHTML,
+  generateThemeBlockHTML
+};