Framework CSS generator con Node.js - Genera CSS optimizado con variables CSS desde un archivo JSON de configuración
npm install holygrail5
Generador de CSS + guía HTML pensado para design systems ligeros: declaras tu config.json, HolyGrail5 crea variables compartidas, helpers responsive, tipografías y documentación navegable en dist/ sin depender de SASS ni toolchains complejos.
---
config.jsonBuildOrchestrator (src/build/build-orchestrator.js)AssetManager (src/build/asset-manager.js)ThemeTransformer (src/build/theme-transformer.js)---
``bashInstalación global
npm install -g holygrail5
> Requiere Node.js >= 12 (probado hasta v20).---
2. Flujo rápido
bash
1) Genera CSS + guía
npx holygrail52) Sirve dist/ en local
npm run serve
http://localhost:3000/index.html
3) Trabaja en caliente
npm run watch # regenera al guardar config.json
npm run dev # watch + servidor4) Genera CSS y tema Dutti
npm run build # genera CSS, HTML, assets y temas automáticamente
`---
3. Scripts disponibles
| Script | Descripción |
| ------ | ----------- |
|
| Genera CSS, HTML, assets y transforma temas automáticamente usando BuildOrchestrator. |
| npm run watch | Observa config.json, CSS y temas, regenerando automáticamente al detectar cambios. |
| npm run serve | Abre el navegador y sirve dist/ en el puerto 3000. |
| npm run dev | Alias práctico: watch + serve (desarrollo en caliente). |
| npm run test | Ejecuta todos los tests (20 tests unitarios). |
| npm run vars:report | Informe completo de variables CSS. |
| npm run vars:remove-unused | Limpia variables históricas no usadas. |---
4. ¿Qué se genera?
-
dist/output.css → Reset, variables compartidas, helpers de spacing, helpers de layout, grid opcional, aspect ratios y tipografías mobile/desktop.
- dist/index.html → Guía interactiva con navegación sticky, buscador y diffs visuales.
- dist/guide-styles.css → Estilos de la guía de documentación.
- dist/assets/ → Imágenes y recursos estáticos.
- dist/themes/dutti.css + dist/themes/dutti-demo.html → Cuando theme.enabled es true.---
5. Estructura del proyecto
`
holygrail5/
├── config.json # Configuración principal
├── generate-css.js # Entry point del build
├── package.json # Dependencias y scripts
│
├── src/
│ ├── assets/ # Assets estáticos (imágenes)
│ │ ├── intro.jpg
│ │ ├── introm.jpg
│ │ └── margen.webp
│ │
│ ├── build/ # Sistema de build modular
│ │ ├── asset-manager.js # Gestión de assets
│ │ ├── build-orchestrator.js # Orquestador principal
│ │ └── theme-transformer.js # Transformación de temas
│ │
│ ├── generators/ # Generadores de CSS
│ │ ├── grid-generator.js
│ │ ├── helpers-generator.js
│ │ ├── reset-generator.js
│ │ ├── spacing-generator.js
│ │ ├── typo-generator.js
│ │ ├── utils.js
│ │ └── variables-generator.js
│ │
│ ├── docs-generator/ # Generación de documentación
│ │ ├── guide-styles.css
│ │ ├── html-generator.js
│ │ ├── variables-cli.js
│ │ └── variables-tracker.js
│ │
│ ├── config-loader.js # Carga y validación de config
│ ├── css-generator.js # Generador CSS principal
│ ├── dev-server.js # Servidor de desarrollo
│ └── watch-config.js # Sistema de watch
│
├── themes/
│ └── dutti/ # Tema de ejemplo
│ ├── _variables.css
│ ├── _buttons.css
│ ├── _inputs.css
│ ├── demo.html
│ └── theme.css
│
├── tests/ # Tests unitarios
│ ├── asset-manager.test.js
│ ├── build-orchestrator.test.js
│ ├── theme-transformer.test.js
│ ├── config-loader.test.js
│ ├── css-generator.test.js
│ ├── helpers.test.js
│ ├── html-generator.test.js
│ └── run-all.js
│
├── docs/ # Documentación complementaria
│ ├── ANALISIS-ARQUITECTURA.md
│ ├── CHANGELOG-MEJORAS.md
│ ├── GUIA-USO-OTRO-PROYECTO.md
│ └── SUPERPROMPT.md
│
└── dist/ # Archivos generados (gitignored)
├── output.css
├── index.html
├── guide-styles.css
├── assets/ # Assets copiados
└── themes/ # Temas generados
---
6. Configurar
$3
jsonc
{
"prefix": "hg",
"baseFontSize": 16,
"breakpoints": { "mobile": "1px", "desktop": "992px" },
"fontFamilyMap": {
"primary": "arial, sans-serif",
"secondary": "\"ms-serif\", serif"
},
"colors": { "white": "#fff", "black": "#000" },
"spacingMap": { "0": "0", "16": "16px", "100-percent": "100%" },
"spacingImportant": ["0"],
"helpers": {
"display": { "property": "display", "class": "d", "responsive": true, "values": ["flex", "block", "none"] }
},
"grid": { "enabled": true, "gutter": "8px", "breakpoints": { "md": { "minWidth": "992px", "columns": 12 } } },
"aspectRatios": [
{ "class": "aspect-16-9", "width": 16, "height": 9, "description": "Ratio 16:9 (widescreen)" },
{ "class": "aspect-1-1", "width": 1, "height": 1, "description": "Ratio 1:1 (cuadrado)" }
],
"typo": {
"h2": {
"fontFamily": "arial, sans-serif",
"fontWeight": "900",
"mobile": { "fontSize": "18px", "lineHeight": "1.2" },
"desktop": { "fontSize": "24px", "lineHeight": "1.2" }
}
}
}
`$3
| Campo | Tipo | Descripción |
| ----- | ---- | ----------- |
|
| string | Prefijo usado en todas las variables (--hg-color-*). |
| baseFontSize | number | Conversión automática px → rem (default 16). |
| breakpoints.mobile / .desktop | string | Valores usados en media queries (992px, etc.). |
| fontFamilyMap | object | Alias legibles para las fuentes declaradas en tipografías. |
| colors | object | Paleta exportada como --hg-color-*. |
| spacingMap | object | Escala lógica de spacing (px o %). |
| spacingImportant | string[] | Keys de spacing con !important. |
| helpers | object | Helpers de layout. Permite arrays simples o mapas clave → valor. |
| grid | object | Define breakpoints, columnas y gutter por tamaño. |
| aspectRatios | array | Opcional: Define ratios de aspecto como .hg-aspect-16-9 con fallback automático. |
| typo | object | Clases de tipografía (obligatorio al menos un breakpoint). |
| theme | object | { name, enabled } para combinar temas desde themes/. |
| assets | object | Opcional: { css: [...], images: [...] } para configurar qué archivos copiar a dist/. |$3
Puedes configurar qué archivos CSS e imágenes se copian a
dist/ agregando una sección assets en tu config.json:`json
{
"assets": {
"css": [
{
"source": "src/docs-generator/guide-styles.css",
"dest": "dist/guide-styles.css"
}
],
"images": [
{
"source": "src/assets/intro.jpg",
"dest": "dist/assets/intro.jpg"
},
{
"source": "src/assets/margen.webp",
"dest": "dist/assets/margen.webp"
}
]
}
}
`Ventajas:
- ✅ Configuración sin modificar código
- ✅ Fácil agregar nuevos assets
- ✅ Flexible para diferentes proyectos
Si no se especifica
, el sistema usa una configuración por defecto.$3
-
src/generators/helpers-generator.js crea clases del tipo .hg-d-flex, .md\:hg-justify-center, .hg-gap-16, etc.
- Puedes mezclar helpers basados en values y helpers que reutilizan spacingMap con useSpacing: true (gap, row-gap, column-gap...).
- El grid (grid.enabled=true) genera utilidades .row, .col-md-6, offsets, contenedores fluidos y variantes por breakpoint.$3
-
src/generators/ratio-generator.js crea clases de aspect ratio como .hg-aspect, .hg-aspect-16-9, .hg-aspect-1-1, etc.
- La clase .hg-aspect sin sufijo usa el ratio 2:3 por defecto.
- Usa la propiedad CSS aspect-ratio nativa con fallback automático para navegadores antiguos (padding-top).
- Incluye .hg-aspect-image para imágenes/videos con object-fit: cover.
- Incluye .hg-aspect-content para posicionar contenido personalizado absolutamente dentro del ratio.
- Cada ratio se define con class, width, height y description.
- Útil para mantener proporciones consistentes en imágenes, videos y contenedores.
- Incluye ratios comunes (1:1, 4:3, 16:9) y especializados (separadores 3:1, 7:1, 12:1, 24:1).$3
- El generador (
src/generators/typo-generator.js) deduplica valores y crea variables compartidas (--hg-typo-font-size-24).
- Cada clase admite propiedades base (fontFamily, fontWeight, letterSpacing, textTransform) y propiedades por breakpoint (fontSize, lineHeight).
- Los valores px se convierten automáticamente a rem respetando baseFontSize.---
7. CLI y argumentos
generate-css.js puede ejecutarse como binario (holygrail5) o mediante node generate-css.js.Argumentos soportados:
`bash
npx holygrail5 \
--config=./config.personal.json \
--output=./dist/custom.css \
--html=./dist/guia.html
`
- Todos los parámetros son opcionales. Si omites alguno, se usan las rutas por defecto ( y dist/*).
- El script ajusta automáticamente el href="output.css" del HTML si CSS y HTML viven en carpetas distintas.---
8. Guía HTML interactiva
El módulo
src/docs-generator/html-generator.js produce dist/index.html con:
- ✅ Resumen visual de colores, tipografías y spacing
- ✅ Detección de cambios: los valores modificados respecto a .data/.previous-values.json se resaltan
- ✅ Buscador instantáneo y navegación lateral fija
- ✅ Información de metadata (versión del paquete y último commit disponible)
- ✅ Diseño responsive con smooth scroll (Lenis)---
9. Gestión de variables históricas
El binario
src/docs-generator/variables-cli.js + el módulo variables-tracker guardan un historial en .data/.historical-variables.json para que ninguna variable desaparezca sin que lo decidas.Comandos útiles:
`bash
npm run vars:report # Estadísticas y listado completo
npm run vars:remove-unused # Limpia todas las variables no utilizadas
node src/docs-generator/variables-cli.js list --css=./dist/output.css
node src/docs-generator/variables-cli.js remove -- --hg-typo-font-size-18
`
> Después de borrar variables históricas conviene volver a ejecutar para regenerar el CSS sin referencias huérfanas.---
10. Tema Dutti y demos
- El directorio
themes/dutti/ contiene CSS modular (_variables, _buttons, etc.) y un demo.html de referencia.
- El ThemeTransformer combina el tema en dist/themes/dutti.css, transforma el HTML agregando sidebar, header y scripts de Lenis automáticamente.
- Para crear tu propio tema copia la carpeta themes/dutti, ajusta los ficheros y actualiza config.json → theme.name.$3
1.
npm run watch detecta cambios en themes/dutti/ automáticamente
2. Los cambios en demo.html o archivos CSS se procesan al guardar
3. El resultado se genera en dist/themes/dutti-demo.html
4. El servidor de desarrollo () sirve los cambios en tiempo real---
11. Arquitectura del sistema
HolyGrail5 usa una arquitectura modular y centralizada construida en diciembre 2024:
$3
####
BuildOrchestrator (src/build/build-orchestrator.js)
- Coordina todo el proceso de build de forma centralizada
- Genera CSS, HTML, copia assets y transforma temas
- Soporta modo watch con cache busting automático
- ~175 líneas, 100% testeado####
AssetManager (src/build/asset-manager.js)
- Gestiona la copia de CSS e imágenes a dist/
- Configuración centralizada desde o fallback
- API simple: copyCSS(), copyImages(), copyAssets()
- Soporte para agregar assets dinámicamente
- ~153 líneas, 10 tests####
(src/build/theme-transformer.js)
- Transforma HTML de temas agregando sidebar, header y scripts
- Inyecta Lenis para scroll suave y navegación
- Manejo dinámico de múltiples temas
- ~234 líneas, 5 tests$3
- ✅ Sin duplicación de código (~150 líneas eliminadas)
- ✅ Consistencia entre build y watch
- ✅ Testeable (20 tests unitarios, 100% pasando)
- ✅ Mantenible (responsabilidades claramente separadas)
- ✅ Extensible (fácil agregar nuevas funcionalidades)
$3
`
generate-css.js
↓
BuildOrchestrator
├── config-loader.js → Carga config.json
├── css-generator.js → Genera CSS
├── html-generator.js → Genera HTML
├── AssetManager → Copia assets
└── ThemeTransformer → Transforma temas
---
12. Tests y calidad
$3
bash
npm test # Ejecuta todos los tests
`Tests disponibles:
- ✅
- Validación de configuración
- ✅ css-generator.test.js - Generación de CSS
- ✅ helpers.test.js - Utilidades compartidas
- ✅ html-generator.test.js - Generación de HTML
- ✅ asset-manager.test.js - Gestión de assets (10 tests)
- ✅ theme-transformer.test.js - Transformación de temas (5 tests)
- ✅ build-orchestrator.test.js - Orquestador de build (5 tests)Resultados:
`
📊 Resumen Total de Tests de Build:
✅ Pasados: 20
❌ Fallidos: 0
📈 Total: 20
Los tests:
- Imprimen resultados en consola sin necesidad de frameworks pesados
- Funciones puras fáciles de testear en aislamiento
- Cobertura completa del sistema de build
- Se ejecutan en menos de 1 segundo
---
13. Documentos complementarios
| Archivo | Contenido |
| ------- | --------- |
|
| Prompt detallado para asistentes/IA que necesiten generar HTML usando HolyGrail5. |
| docs/GUIA-USO-OTRO-PROYECTO.md | Pasos para integrar HolyGrail5 en proyectos existentes. |
| docs/ANALISIS-ARQUITECTURA.md | Análisis completo de la arquitectura y problemas resueltos. |
| docs/CHANGELOG-MEJORAS.md | Registro detallado de la refactorización de diciembre 2024. |$3
Puedes publicar
dist/index.html como documentación estática en:
- GitHub Pages
- Netlify (configurado en netlify.toml)
- Vercel
- Cualquier hosting estático`bash
npm run build
Publica el contenido de dist/ en tu hosting
`---
14. Recursos y soporte
- Repositorio: github.com/holygrailcss/holygrail5
- npm: holygrail5
- Issues y PRs: Bienvenidos. Sigue el flujo clásico: fork → rama → PR
- Documentación: Ver
para guías detalladas$3
1. Fork el proyecto
2. Crea tu rama de feature (
git checkout -b feature/AmazingFeature)
3. Commit tus cambios (git commit -m 'feat: agregar AmazingFeature')
4. Push a la rama (git push origin feature/AmazingFeature)
5. Abre un Pull Request---
15. Licencia
MIT © HolyGrail CSS
Usa, adapta y comparte libremente mientras conserves la atribución.
---
Changelog
$3
🎉 Refactorización arquitectural completa
- ✅ Nueva arquitectura modular con
BuildOrchestrator, AssetManager y ThemeTransformer
- ✅ Eliminadas ~150 líneas de código duplicado
- ✅ Assets organizados en y dist/assets/
- ✅ Configuración de assets desde
- ✅ 20 tests unitarios agregados (100% pasando)
- ✅ Sistema de watch mejorado
- ✅ Documentación actualizadaVer