Guía del Design System
Variables, clases, convenciones, estructura del proyecto y cómo extender el sistema sin romper nada.
Variables CSS
Todas las variables viven en /_astro/main.min.css (el ?v= de la URL real es un hash de contenido, se recalcula solo con bump_cache_version.py). Nunca uses valores hardcoded — si ese archivo no carga, styles.css tiene un fallback idéntico en :root.
--bg#060810--bg-2#0a0e1a--surface#0d1121--surface-2#111827--cardrgba(…)--text#f1f5f9--text-2#e2e8f0--text-3#cbd5e1--text-4#94a3b8--text-5#64748b--indigo#6366f1--indigo-l#818cf8--indigo-d#4f46e5--purple#a855f7--purple-l#c084fc--green#22c55e--borderrgba(…45%)--border-lrgba(…70%)--border-hiindigo 50%/_astro/main.min.css y al fallback de styles.css.
Paleta de colores
CostaCraft UI usa una paleta oscura (dark-first) construida sobre azul índigo + violeta como acentos, con verde solo para estados de éxito. Todos los valores ya están como variables.
Tipografía
El sistema usa dos familias tipográficas. Nunca uses font-family hardcoded.
--font-displayUsado en headings (h1–h3), nombres de componentes, números grandes y cualquier texto que necesite personalidad fuerte. Weights: 700, 800, 900.
--font-bodyPárrafos, labels, descripciones, UI pequeño. Weights: 400, 500, 600. Tamaños: 0.75rem → 1rem.
Bloques pre, code inline, .docs-code, .kb-cmd. No disponible como variable — se usa directamente con font-family: monospace stack.
Escala tipográfica
Espaciado & Radios de borde
Los radios de borde están todos en variables. El espaciado no tiene variables propias — seguí las convenciones por contexto.
--r-sm
6px
--r-md
10px
--r-lg
14px
--r-xl
18px
--r-2xl
24px
--r-full
9999px
Convenciones de espaciado
| Contexto | Padding | Gap |
|---|---|---|
| Panel header principal | 36px 44px 28px | — |
| Panel body | 28px 44px 60px | — |
| Subnav | 12px 44px | 4px entre tabs |
| Card de componente | 12–14px interior | 16px entre cards |
| KB card | 20px | 14px entre cards |
| Sidebar nav item | 8px 10px | 2px entre items |
| Responsive ≤1023px | 24px 20px | reducido |
Sombras
--shadow-md
0 4px 24px rgba(0,0,0,.35) — hover de cards, modales pequeños
--shadow-lg
0 12px 48px rgba(0,0,0,.5) — drawers, panels flotantes
Iconografía
Todo el sitio usa SVG inline, nunca una librería de íconos ni una fuente de íconos (Font Awesome, etc.) ni archivos .svg externos. Cada ícono es un <svg> pegado directo en el HTML, con un patrón de atributos casi siempre idéntico:
Los cuatro atributos fill="none" stroke="currentColor" stroke-width="2.5" viewBox="0 0 24 24" son fijos en casi todo el sitio — stroke="currentColor" es lo que permite que el ícono herede el color del texto/link que lo rodea sin tocar nada del SVG. Lo único que cambia por contexto es el tamaño (width/height) y, en menor medida, el grosor del trazo.
Tamaños por contexto
| Tamaño | Dónde se usa | stroke-width |
|---|---|---|
| 10px | Chevrons de breadcrumb, flechas "volver" | 2.5 |
| 12px | Íconos dentro de botones chicos (Copiar, Editar) | 2.2 – 2.5 |
| 14px | Íconos de título de sección (.docs-section-title-icon), la mayoría de los íconos del sitio | 2 – 2.5 |
| 16px | Bullets de Do/Don't (.docs-best-practice) | 2.5 |
<path> del ícono que haga falta y se pega con el mismo wrapper de arriba.
No agregar una librería de íconos (Font Awesome, Lucide como paquete, etc.) — cada ícono nuevo se agrega como SVG inline, siguiendo el mismo patrón de esta sección.
Animaciones & transiciones
Las duraciones de transición no están en variables (a diferencia de colores y radios) — se repiten por convención directamente en cada regla. Estos son los valores reales que ya usa el sitio, agrupados por qué tan "grande" es el cambio visual:
| Duración | Uso típico |
|---|---|
| 0.15s – 0.16s | Cambios chicos: color de texto/borde en hover, opacity de un ícono |
| 0.18s – 0.22s | Cambios medianos: transform (levantar una card), box-shadow al hacer hover |
| 0.4s – 0.5s | Cambios grandes: aparecer/desaparecer un overlay, glow que se prende con opacity |
Para transiciones de transform (las que más se "sienten" si el easing es lineal), el sitio usa una curva propia en vez de ease:
Glow que sigue el mouse
Varias cajas del sitio (el hero de ia-negocio, la caja de preview de component-view.html) tienen un glow radial que se mueve con el cursor. No es una clase reusable todavía — es la misma técnica repetida a mano en cada lugar que la necesita:
- Un listener de
mousemoveen el contenedor actualiza dos custom properties,--mx/--my, con la posición del cursor relativa a la caja. - Un pseudo-elemento
::afterconbackground: radial-gradient(260px circle at var(--mx,50%) var(--my,0%), ...)lee esas variables — el navegador repinta el gradiente en cada frame sin JS adicional. opacity:0por defecto yopacity:1en:hover, con su propia transición — así el glow aparece/desaparece suave en vez de "saltar".
@media (prefers-reduced-motion: reduce) ya está implementado en styles.css — apaga las animaciones puramente decorativas (orbes del hero, loaders, dots de estado). Si agregás una animación nueva que sea decorativa (no comunica estado ni feedback de una acción), sumala a esa misma regla.
Componentes — clases semánticas
Los componentes se activan con clases semánticas definidas en /_astro/main.min.css. No copies estilos inline — usá las clases.
Clases utilitarias de /ui/
Estas clases son exclusivas de /ui/styles.css y no están disponibles en el resto del sitio:
| Clase | Qué hace | Contexto |
|---|---|---|
.ui-layout | Grid 248px sidebar + 1fr main | Wrapper raíz |
.ui-sidebar | Sidebar sticky con scroll propio | Sidebar |
.ui-nav-item | Link de nav con estado activo y hover | Sidebar |
.ui-section | Sección oculta — .active la muestra | Main |
.ui-panel-header | Header de panel con grid de fondo | Cada sección |
.ui-subnav | Tabs de subcategoría con scroll horizontal | Galaxy / KB |
.comp-grid | Grid de componentes tipo UIverse | Galaxy |
.comp-card | Card de componente con preview + código | Galaxy |
.kb-grid / .kb-card | Grid de artículos de KB | KB sections |
.docs-section | Sección de documentación con separadores | Guía |
.docs-callout | Bloque de aviso (+ .warn, .success) | Guía |
.docs-code | Bloque de código con mono + highlight | Guía |
.docs-best-practice | Do/Don't visual (+ .do, .dont) | Guía |
Buenas prácticas
Siempre variables CSS — nunca colores, tamaños o fuentes hardcodeados en ningún archivo nuevo.
No Bootstrap, no Tailwind — el design system es autocontenido. Agregar frameworks externos rompe la consistencia visual.
Mobile-first — estilos base para móvil, @media (min-width: 640px) y @media (min-width: 1024px) para desktop. Nunca max-width primero.
Respetar el orden de carga de scripts — data → renderers → nav.js. Si movés nav.js arriba, la navegación se rompe.
No editar galaxy/_bundles/ a mano — son archivos generados. Siempre editá en galaxy/<Categoría>/ y corré el build.
content-visibility: auto en grids grandes — ya está en .comp-card. Si creás nuevas grillas de renderizado masivo, aplicá el mismo patrón para mantener el rendimiento.
No mezclar estilos de /ui/styles.css en el sitio principal — la carpeta /ui/ es completamente autocontenida. Sus clases no deben usarse fuera de ella.
Correr bump_cache_version.py --apply después de tocar cualquier .css/.js — ver Cache-busting. Sin esto, el navegador de un visitante puede seguir sirviendo la versión vieja desde caché.
No usar Node.js para verificar cambios — este proyecto se valida con Python o directamente en el navegador. build-galaxy-bundles.js es la única pieza que requiere Node, y solo corre en local, nunca como parte de la verificación de un cambio.
Estructura del proyecto
Así está organizado el repositorio. Todo lo relacionado a /ui/ vive de forma autocontenida — no toca nada de /_astro/ salvo leer las variables.
galaxy/_bundles/ es generada por build-galaxy-bundles.js. Si la editás a mano, el próximo build la sobreescribe. Editá siempre el .html fuente.
Cache-busting (?v=)
Todo .css y .js se referencia en el HTML con un ?v=<hash> al final — por ejemplo styles.css?v=5bf61a60. Ese hash no se escribe a mano: es sha256(contenido del archivo)[:8], calculado por un script.
?v= en el HTML todavía apunta al hash viejo.python bump_cache_version.py escanea TODOS los .html del proyecto buscando referencias a ese asset (por ruta absoluta o relativa).--apply reemplaza el hash viejo por el nuevo en cada referencia. Sin --apply solo informa qué CAMBIARÍA (dry-run).?v=) cambió, el navegador la trata como un recurso distinto y la vuelve a descargar — nunca sirve la copia vieja desde caché.--apply.
.css o .js que ya esté referenciado con ?v= en algún HTML. Editar solo HTML (como esta misma Guía) nunca lo necesita.
Breakpoints responsive
Como ya dice Buenas prácticas, el sitio es mobile-first: los estilos base son para pantallas chicas y los @media agregan/ajustan para pantallas más grandes. Estos son los breakpoints reales que ya existen (no hay más que estos tres a nivel de /ui/styles.css):
| Breakpoint | Qué cambia | Dónde |
|---|---|---|
max-width: 639px | Layout mobile: sidebar se convierte en tabs horizontales arriba, se ocultan elementos secundarios (brand, footer) | styles.css |
max-width: 1023px | Padding reducido de panels (36px 44px → 24px 20px), grillas pasan a menos columnas | styles.css |
max-width: 900px | El layout de dos columnas (preview + código) colapsa a una sola columna apilada | component-view.html — propio de esa página, no está en styles.css |
max-width, no min-width — la convención de este proyecto es escribir el estilo base pensando en mobile y usar max-width para las excepciones de pantalla chica cuando el layout de escritorio ya está resuelto con grid/flex fluido. Si necesitás agregar un breakpoint nuevo, seguí el mismo criterio en vez de mezclar min-width y max-width en el mismo archivo.
Galaxy: cómo funciona el sistema
Galaxy es la sección de Complementos y Plantillas. Por el volumen de archivos (miles de snippets), el navegador nunca lee la carpeta fuente directamente.
galaxy/<Categoría>/nombre.html como un snippet HTML/CSS autocontenido.node build-galaxy-bundles.js en local. Lee los _index.json de cada categoría y empaqueta todos los .html en un _bundles/Categoría.json._bundles/manifest.json tiene el conteo por categoría — de ahí salen los números del sidebar (ej. "Botones 1231").Agregar un componente nuevo a Galaxy
Auto-escalado del preview
Cada componente puede traer cualquier tamaño natural — un modal gigante o un ícono chiquito — pero la caja de preview siempre mide lo mismo. Por eso cada preview se auto-escala para entrar sin recortarse:
measureNaturalExtent()mide el tamaño real del componente: no solo su wrapper, sino la unión del bounding rect de todos sus descendientes (varios componentes se dibujan con hijos enposition:absolute, así que el wrapper solo no alcanza).scaleToFit()aplica untransform: scale()que achica el componente si no entra — nunca lo agranda si ya entra de sobra.- Para componentes con el tag Tailwind, se vuelve a medir 150ms después: el CDN de Tailwind aplica sus clases de forma asíncrona (su propio
MutationObserver), así que medir una sola vez de inmediato puede dar un tamaño incorrecto.
galaxy-renderer.js (como measureAndScale()/fitPreviews(), para la grilla) y en component-view.html (copia local más chica, para la vista de un solo componente) — esa página no carga el renderer completo porque asume una estructura de sidebar/subnav que ahí no existe.
Editor de código en vivo
En la vista de un solo componente (component-view.html, el botón "Ver completo" de cualquier card) hay un botón "Editar" junto a "Copiar": convierte el HTML y el CSS en <textarea> editables, y cada tecleo (con un debounce de 200ms) vuelve a renderizar el preview con el código actual.
Nada se guarda — es 100% en memoria del navegador. Recargar la página siempre vuelve al código original del componente. Es un sandbox visual, no un editor con persistencia.
Por qué el CSS editado necesita escoparse
Si el CSS que escribe un visitante se inyectara tal cual en un <style>, un selector como body { background: red } afectaría toda la página, no solo su caja de preview. Por eso, antes de inyectarlo, se le aplica el mismo mecanismo de escopado que ya usa el build de Galaxy:
La caja de preview (.comp-preview-inner) tiene ese mismo atributo data-comp-scope="gscope-<id>", así que el selector escopado solo puede matchear elementos dentro de esa caja — nunca el <body> real ni el resto de la página, sin importar qué escriba el visitante.
scopeCSS() en component-view.html es un puerto directo a JavaScript de scope_css() en fix_scoped_css.py (mismo regex, mismo criterio para no tocar selectores dentro de comentarios o de bloques @keyframes). Si en algún momento se agrega otro preview editable en /ui/, reusá esta misma función en vez de reinventarla.
Cómo se arma un artículo de KB
Los artículos de las 5 secciones de Knowledge Base (Minecraft, Hosting Web, Panel Pterodactyl, Email&SMTP, Desarrollo) no son Markdown ni HTML — son texto plano con un formato propio que kb-renderer.js convierte a HTML en el navegador. Cada artículo vive como un objeto dentro de un array (ej. window.KB_MINECRAFT en data/kb-minecraft.js):
Dentro de content, un parser de texto plano (no un parser de Markdown) busca patrones exactos línea por línea. Estas son las reglas, en el orden en que las busca:
1. Banner superior (decorativo, se ignora)
Todo lo que esté entre la primera y la segunda línea de 12+ caracteres ━ se descarta por completo al renderizar — es solo para que quien lea el archivo fuente vea de un vistazo de qué trata el artículo.
2. Secciones (se vuelven <h2>)
Un "sándwich" de 3 líneas: separador liviano (12+ caracteres ═), el título, y otro separador liviano. Cada uno de estos se vuelve un <h2> con un id calculado a partir del título:
sections del objeto (mismo title, y anchor calculado con esta función exacta — no es un slugify estándar):
[a-z0-9], así que se "comen" en el guion — "INFORMACIÓN DEL SERVIDOR" da "informaci-n-del-servidor", no "informacion-del-servidor". Si el anchor no coincide exactamente con lo que produce esa función, el link del TOC lateral no salta a ningún lado.
3. Callouts
Cualquier línea que empiece con NOTA:, IMPORTANTE:, ADVERTENCIA:, WARNING:, CRÍTICO: o ATENCIÓN: (sin importar mayúsculas/minúsculas) se convierte en un cuadro de aviso destacado.
4. Bloques de código
Cualquier línea que empiece con 2+ espacios o un tab se trata como código — queda en monoespaciada con su propio botón "Copiar". Así se muestran todos los comandos/config de ejemplo en los artículos existentes.
5. Párrafos
Cualquier otra línea (no vacía, no separador, no callout, no indentada) es texto normal — líneas consecutivas se unen en un mismo párrafo. Una línea en blanco corta el párrafo.
Nameservers de CostaCraft
Cuando conectes un dominio a los servicios de CostaCraft, usá estos nameservers:
Glosario de términos
Términos propios de este proyecto que aparecen en varias secciones de la Guía sin repetir la definición cada vez:
| Término | Qué significa |
|---|---|
| Galaxy | El sistema de Complementos + Plantillas dentro de /ui/ — miles de snippets copy-paste organizados por categoría. No confundir con el resto de /ui/ (Guía, KB), que no pasa por el pipeline de bundles. |
| Bundle | Un .json en galaxy/_bundles/ con todos los componentes de UNA categoría ya empaquetados — lo que el navegador realmente descarga, nunca los .html fuente. |
| Manifest | galaxy/_bundles/manifest.json — conteo de componentes por categoría, de ahí salen los números del sidebar. |
| scopedCss / gscope | La versión del CSS de un componente con cada selector prefijado por [data-comp-scope="gscope-<id>"], para que solo aplique dentro de su propia caja de preview. Ver Editor de código en vivo. |
| Auto-escalado | La lógica de scaleToFit()/measureNaturalExtent() que achica (nunca agranda) un componente para que entre en su caja de preview. Ver Galaxy: cómo funciona. |
| KB | Knowledge Base — las 5 secciones de artículos largos (Minecraft, Hosting Web, Panel Pterodactyl, Email&SMTP, Desarrollo). Formato propio, no Markdown. Ver Cómo se arma un artículo de KB. |
| Cache-busting | Cambiar el ?v=<hash> de un asset para forzar al navegador a descargar la versión nueva en vez de servir una copia vieja desde caché. Ver Cache-busting. |
| Dry-run | Modo de bump_cache_version.py que solo informa qué cambiaría, sin escribir nada — el modo por defecto, ya que este proyecto no tiene git para deshacer un error. |
| ui-section | Cada una de las áreas principales de /ui/ (Guía, Componentes, Plantillas, Fondos de Video, cada KB) — solo una tiene la clase .active (visible) a la vez, controlado por nav.js. |
| Renderer | El script de js/ que arma el HTML de una sección a partir de sus datos (galaxy-renderer.js, kb-renderer.js, templates-renderer.js, video-bg-renderer.js). Cada sección tiene el suyo, ninguno depende de otro. |
Preguntas frecuentes
node build-galaxy-bundles.js después de agregar el archivo? El browser no lee los .html fuente — solo los .json de _bundles/. También asegurate de que el nombre del archivo esté en el array "files" de _index.json de la categoría./_astro/main.min.css, /ui/styles.css, los renderers). Sí podés incluirlos dentro del HTML de un componente Galaxy si ese componente específicamente lo necesita para su preview — pero ese CSS queda aislado dentro del .comp-preview y no afecta al sistema.galaxy/_bundles/manifest.json. Este archivo se genera automáticamente cada vez que corrés el build y contiene el conteo de componentes por categoría. El renderer lo lee al inicializar y actualiza los badges del sidebar.nav.js es el controlador central: escucha clics en el sidebar, activa la sección correcta, dispara la inicialización lazy de cada renderer, y expone window.UI_NAV con métodos como .go(), .galaxyTab() y .kbDoc(). Debe ir último porque necesita que todos los renderers (window.GALAXY_RENDERER, window.KB_RENDERER, etc.) ya estén definidos cuando se inicializa.window.UI_NAV:
- Agregá el link en el sidebar:
<a class="ui-nav-item" data-section="mi-seccion"> - Creá el elemento en main:
<section id="section-mi-seccion" class="ui-section"> - Registrá el ID en el array
SECTIONSdenav.js - Creá el renderer en
js/mi-renderer.jse incluidlo antes de nav.js
python bump_cache_version.py --apply desde la raíz del proyecto — recalcula el hash de contenido de cada asset y actualiza el ?v= en todos los HTML que lo referencian, así el navegador lo trata como una URL nueva y lo vuelve a descargar. Ver Cache-busting.data-comp-scope="gscope-<id>" único, y su CSS se reescribe para que cada selector empiece con [data-comp-scope="..."] — así .btn se vuelve [data-comp-scope="gscope-X"] .btn, que solo matchea dentro de esa caja. Lo genera el build para el CSS de cada componente, y el mismo mecanismo (scopeCSS()) se usa en vivo para el editor de código. Ver también Estructura del proyecto → fix_scoped_css.py.Galaxy Componentes
+2800 snippets de HTML/CSS listos para copiar. Botones, cards, inputs, loaders y mucho mas.
Galaxy Plantillas
Paginas web completas listas para deployar. Minecraft, Hosting, Portfolios, Dashboards.
Estas de acá son plantillas de página para desarrollo (Galaxy). Las 24 plantillas de negocio reales — con precios y editor con IA — viven en el catálogo público.
Fondos de Video
Videos de fondo en loop, listos para usar como pantalla completa en cualquier sitio o plantilla — los mismos que usa el generador de sitios.
Minecraft Técnico
Referencia completa: comandos, optimización, plugins, crashes. Válido para Vanilla, Spigot, Paper, Purpur.
Hosting Web Avanzado
DNS, SSL, Nginx, Apache, VPS desde cero, panel de control completo y resolucion de problemas extremos.
Panel Pterodactyl
Gestiona tu servidor Minecraft desde el panel de CostaCraft: consola, archivos, backups, schedules, SFTP y diagnóstico de errores.
Email & SMTP
Configuración de correo, SPF/DKIM/DMARC, deliverability, WP Mail SMTP y diagnóstico de emails que van a spam.
Desarrollo Avanzado
Git, CI/CD con GitHub Actions, Docker local, Node.js y PHP en hosting, APIs REST y webhooks.