1. Principios de Diseño

Illanes Manual v3 es un sistema de diseño minimalista, funcional y coherente para toda la infraestructura illanes00.cl. Se basa en los siguientes principios fundamentales:

✨ Tipografía Fuerte
IBM Plex Sans a peso 800-900 para headings. La tipografía es el elemento visual dominante, no decoraciones.
🚫 Sin Efectos
No gradientes, no shadows, no animaciones innecesarias. Mantenemos la simplicidad visual.
📏 Bordes Sólidos
1px borders con colores --line y --line-strong. Sin border-radius (--radius: 0).
🎨 Colores Semánticos
Verde (OK), Azul (Info), Ámbar (Warning), Rojo (Error). Los colores comunican estado, no decoración.
🔲 Alto Contraste
Dark text on light backgrounds. Cumplimos WCAG AA en accesibilidad.
📐 Spacing Consistente
Grid system usando --space-* variables. Ritmo vertical predecible.
🌙 Dark Mode Opcional
Soporte completo para modo oscuro respetando preferencias del sistema.
📱 Mobile First
Responsive por defecto, optimizado para todos los dispositivos.

2. Instalación

Desde CDN (Recomendado)

Incluye las fuentes Google Fonts y el CSS desde el CDN:

<link rel="preconnect" href="https://fonts.googleapis.com"> <link rel="preconnect" href="https://fonts.gstatic.com" crossorigin> <link href="https://fonts.googleapis.com/css2?family=IBM+Plex+Sans:wght@400;600;700;800;900&family=JetBrains+Mono:wght@400;600&display=swap" rel="stylesheet">  <link rel="stylesheet" href="https://static.illanes00.cl/illanes/v3/illanes-manual.min.css"> <script src="https://static.illanes00.cl/illanes/v3/illanes-manual.js" defer></script>

Local

Si prefieres usar copias locales:

<link rel="stylesheet" href="/illanes/v3/illanes-manual.css">
<script src="/illanes/v3/illanes-manual.js" defer></script>

Dark Mode Toggle

Para habilitar el toggle de dark mode, agrega un botón con id themeToggle:

<button id="themeToggle" class="btn">modo: auto</button>

3. Paleta de Colores

Colores Base

Variable	Hex	Uso
`--bg`	`#f6f7f8`	Background principal
`--paper`	`#ffffff`	Superficies (cards, modales)
`--ink`	`#0f1113`	Texto principal
`--muted`	`#4b5563`	Texto secundario
`--line`	`#d5dbe3`	Bordes sutiles
`--line-strong`	`#a9b3c2`	Bordes fuertes

Colores Semánticos

Variable	Hex	Uso
`--c-green`	`#0b7e59`	Success / OK
`--c-blue`	`#3763e0`	Primary / Info
`--c-amber`	`#d97706`	Warning
`--c-red`	`#c0352b`	Error / Danger

VPS Colors

Swatch	Variable	VPS
	`--c-vps-dev`	VPS-Dev
	`--c-vps-control`	VPS-Control
	`--c-vps-deploy`	VPS-Deploy

4. Tipografía

Fuentes

Usamos dos familias tipográficas:

IBM Plex Sans (--font-sans) - UI y contenido
JetBrains Mono (--font-mono) - Código

Escala Tipográfica

Heading 1 - clamp(1.75rem, 3.2vw, 2.25rem)

Heading 2 - 1.5rem (24px)

Heading 3 - 1.25rem (20px)

Paragraph text - 1rem (16px) con line-height 1.62 para legibilidad óptima.

Large text - 1.125rem (18px)

Small text - 0.8125rem (13px)

Código inline: const x = 42;

Texto muted - color secundario para información menos importante

Uso

<h1>Título Principal</h1>
<h2>Subtítulo</h2>
<p>Texto normal</p>
<p class="large">Texto grande</p>
<p class="small">Texto pequeño</p>
<p class="muted">Texto secundario</p>
<code>código</code>

5. Sistema de Espaciado

Todas las distancias usan el spacing grid. Nunca uses valores arbitrarios.

Variable	Valor	Píxeles	Uso Común
`--space-1`	0.25rem	4px	Espaciado mínimo
`--space-2`	0.5rem	8px	Padding pequeño
`--space-3`	0.75rem	12px	Gaps, separadores
`--space-4`	1rem	16px	Padding estándar
`--space-5`	1.25rem	20px	Cards, sections
`--space-6`	1.5rem	24px	Margin entre elementos
`--space-8`	2rem	32px	Secciones grandes
`--space-10`	2.5rem	40px	Headers
`--space-12`	3rem	48px	Page margins
`--space-16`	4rem	64px	Grandes separaciones

Utilidades de Spacing

<div class="mt-4">margin-top: var(--space-4)</div>
<div class="mb-6">margin-bottom: var(--space-6)</div>
<div class="p-5">padding: var(--space-5)</div>
<div class="px-4">padding-left/right: var(--space-4)</div>
<div class="py-6">padding-top/bottom: var(--space-6)</div>

6. Layout y Containers

Containers

Tres variantes de contenedores centrados:

Clase	Max-width	Uso
`.container-narrow`	760px	Artículos, documentación
`.container`	1160px	Layout estándar (default)
`.container-wide`	1400px	Dashboards amplios

<div class="container">
  <!-- Contenido aquí -->
</div>

Topbar

Header estándar para todos los sitios:

<header class="topbar">
  <div class="brand-title">illanes00.cl</div>
  <div class="brand-sep">
    <span class="sw" style="background:var(--c-charcoal)"></span>
    <span class="sw" style="background:var(--c-grey)"></span>
  </div>
  <div class="brand-sub">Infraestructura y Servicios</div>
</header>

7. Componentes

Status Indicators

Dots (Puntos de Estado)

Para indicar estado de servicios systemd:

Servicio activo (ok)
Servicio con error (err)
Servicio con warning (warn)

<span class="dot ok"></span> active
<span class="dot err"></span> inactive
<span class="dot warn"></span> degraded

Pills (Badges de Estado)

Para códigos HTTP o estados de texto:

200 down 429 info

<span class="pill pill--ok">200</span>
<span class="pill pill--err">down</span>
<span class="pill pill--warn">429</span>
<span class="pill pill--info">info</span>

VPS Badges

Identificación de VPS con colores específicos:

VPS-Dev VPS-Control VPS-Deploy

<span class="badge badge-vps-dev">VPS-Dev</span>
<span class="badge badge-vps-control">VPS-Control</span>
<span class="badge badge-vps-deploy">VPS-Deploy</span>

Alerts (Mensajes)

Para comunicar mensajes importantes al usuario:

✓ Operación completada exitosamente. El servicio está funcionando correctamente.

✗ Error al conectar con el servidor. Por favor, intenta nuevamente.

⚠ Advertencia: El disco está al 85% de capacidad. Considera liberar espacio.

ℹ Información: Hay una nueva versión disponible para actualización.

<div class="alert alert-success">
  ✓ Operación completada exitosamente
</div>

<div class="alert alert-error">
  ✗ Error al procesar
</div>

<div class="alert alert-warn">
  ⚠ Advertencia importante
</div>

<div class="alert alert-info">
  ℹ Información relevante
</div>

Cards (Tarjetas)

Contenedores para agrupar información relacionada:

Card con Header

Contenido de la card aquí. Las cards son contenedores para agrupar información relacionada.

Enlace de ejemplo

Card Simple

Card sin header separado. Simplemente una card con contenido directo.

Texto secundario con clase .muted

<div class="card">
  <div class="card-header">
    <h3>Título</h3>
  </div>
  <p>Contenido aquí</p>
</div>

<!-- Card simple -->
<div class="card">
  <h3>Título</h3>
  <p>Contenido</p>
</div>

Buttons (Botones)

Botones para acciones del usuario:

Link Button

Tamaños

<button class="btn">Default</button>
<button class="btn btn-primary">Primary</button>
<button class="btn btn-success">Success</button>
<button class="btn btn-danger">Danger</button>

<!-- Tamaños -->
<button class="btn btn-sm">Small</button>
<button class="btn btn-lg">Large</button>

<!-- Link como botón -->
<a href="#" class="btn">Link</a>

Forms (Formularios)

Elementos de formulario completos con estados:

Nombre

Email Nunca compartiremos tu email.

Contraseña La contraseña debe tener al menos 8 caracteres

Biografía

País

Acepto los términos y condiciones

Notificaciones: Todas Solo importantes Ninguna

<form>
  <div class="form-group">
    <label for="name">Nombre</label>
    <input type="text" id="name" placeholder="...">
  </div>

  <div class="form-group error">
    <label for="email">Email</label>
    <input type="email" id="email">
    <span class="form-error">Email inválido</span>
  </div>

  <button type="submit" class="btn btn-primary">Enviar</button>
</form>

Tables (Tablas)

Tablas con rayas zebra automáticas y headers sticky:

Servicio	VPS	Puerto	Estado
illanes00-admin	VPS-Control	8102	active
illanes00-api	VPS-Dev	8103	inactive
prometheus	VPS-Control	9090	active

Tabla Compacta

Para tablas con muchos datos, usa .table-compact:

Col 1	Col 2	Col 3
Data 1	Data 2	Data 3
Data 4	Data 5	Data 6

<div class="table-wrap">
  <table>
    <thead>
      <tr>
        <th>Header 1</th>
        <th>Header 2</th>
      </tr>
    </thead>
    <tbody>
      <tr>
        <td>Data</td>
        <td>Data</td>
      </tr>
    </tbody>
  </table>
</div>

<!-- Tabla compacta -->
<table class="table-compact">...</table>

Tabs (Navegación)

Sistema de navegación por pestañas:

<div class="nav">
  <button class="tab active">Dashboard</button>
  <button class="tab">Servicios</button>
  <button class="tab">Configuración</button>
</div>

El tab activo usa la clase .active con fondo oscuro.

8. Sistema de Grids

Sistema de grids responsivo con variantes de 2, 3 y 4 columnas:

Grid 2 Columnas

Columna 1

Columna 2

Grid 3 Columnas

Col 1

Col 2

Col 3

Grid 4 Columnas

<div class="grid-2">
  <div>...</div>
  <div>...</div>
</div>

<div class="grid-3">...</div>
<div class="grid-4">...</div>

Responsive: Los grids colapsan a 1 columna en móvil (<768px)

9. Utilidades

Spacing Utilities

Clase	Propiedad	Ejemplo
`.mt-{n}`	margin-top	`.mt-4` = margin-top: var(--space-4)
`.mb-{n}`	margin-bottom	`.mb-6` = margin-bottom: var(--space-6)
`.p-{n}`	padding	`.p-5` = padding: var(--space-5)
`.px-{n}`	padding-left/right	`.px-4`
`.py-{n}`	padding-top/bottom	`.py-6`

Display Utilities

.block - display: block
.inline-block - display: inline-block
.flex - display: flex
.flex-col - flex-direction: column
.items-center - align-items: center
.justify-between - justify-content: space-between

Text Utilities

.text-left - text-align: left
.text-center - text-align: center
.text-right - text-align: right
.fw-400, .fw-600, .fw-700 - font-weight

Width Utilities

.w-full - width: 100%
.w-half - width: 50%

10. Dark Mode

Illanes Manual v3 incluye soporte completo para dark mode. Los usuarios pueden elegir entre:

Auto - Sigue la preferencia del sistema (prefers-color-scheme)
Light - Modo claro forzado
Dark - Modo oscuro forzado

Activación

Incluye el script JavaScript y agrega un botón con id themeToggle:

<script src="/illanes/v3/illanes-manual.js" defer></script>
<button id="themeToggle" class="btn">modo: auto</button>

Colores Dark Mode

Variable	Light	Dark
`--bg`	#f6f7f8	#0f1113
`--paper`	#ffffff	#1a1d21
`--ink`	#0f1113	#e5e7eb
`--muted`	#4b5563	#9ca3af
`--line`	#d5dbe3	#2d3139
`--line-strong`	#a9b3c2	#4b5563

Custom Styles para Dark Mode

Usa el selector html[data-theme="dark"] para estilos personalizados:

.mi-componente {
  background: var(--paper);
  color: var(--ink);
}

html[data-theme="dark"] .mi-componente {
  border-color: var(--line-strong);
}

ℹ Nota: Todos los componentes de v3 son compatibles con dark mode. No necesitas agregar estilos adicionales.

11. Responsive

El sistema es responsive por defecto. Breakpoints:

Breakpoint	Tamaño	Descripción
Mobile	< 480px	Smartphones
Tablet	481px - 768px	Tablets
Desktop	> 768px	Laptops y desktops

Cambios Automáticos

En móvil (<768px):

Font size ligeramente más pequeño (15px base)
Padding reducido en containers
Tabs más compactos
Tables con scroll horizontal
Grids colapsan a 1 columna
Botones full-width en formularios

Media Query Custom

@media (max-width: 768px) {
  .mi-elemento {
    /* Estilos móvil */
  }
}

12. Normas y Reglas

✅ DO - Siempre hacer

Usar variables CSS en lugar de valores hardcoded
Respetar spacing grid: Solo usar --space-* values
Colores semánticos: Verde para OK, Rojo para errores, Azul para info, Ámbar para warnings
Alto contraste: Texto oscuro siempre sobre fondos claros (o viceversa en dark mode)
Bordes de 1px: Nunca usar 2px o más gruesos
Tipografía IBM Plex Sans: Para UI y contenido
Line-height 1.62: Para texto largo, mejor legibilidad
Mobile first: Diseñar para móvil primero, escalar hacia arriba

❌ DON'T - Nunca hacer

No usar gradientes en backgrounds
No usar box-shadows (excepto el definido como none)
No inventar colores fuera de la palette
No usar margin/padding arbitrarios (siempre variables)
No usar border-radius (excepto el definido como 0)
No usar animations/transitions innecesarias (keep it simple)
No mezclar unidades: Siempre rem, nunca px en CSS
No usar !important: Indica mala especificidad

🎯 Best Practices

Semántica HTML: Usa elementos correctos (<button> para botones, no <div>)
Accesibilidad: Labels en forms, alt en imágenes, aria-labels cuando necesario
Clases descriptivas: .card-header mejor que .ch
Consistencia: Si usas .btn en un lugar, úsalo en todos
Performance: Usa .min.css en producción

13. Templates

Hemos creado templates HTML completos listos para usar. Descárgalos desde:

Dashboard

Panel administrativo con tabs, tablas, métricas

Ver Template

Service Status

Tabla de monitoreo de servicios

Ver Template

Documentation

Página de documentación con TOC

Ver Template

14. Guía de Integración

Migración desde v2

Illanes Manual v3 es totalmente compatible con v2. No hay breaking changes.

Pasos:

Reemplaza el link CSS de v2 por v3:
 <link rel="stylesheet" href="/static/illanes/v2/illanes-manual.min.css">  <link rel="stylesheet" href="/illanes/v3/illanes-manual.min.css">
Actualiza el script JavaScript (opcional):
<script src="/illanes/v3/illanes-manual.js" defer></script>
Prueba tu sitio - todo debería funcionar idéntico
Opcionalmente, usa los nuevos componentes (alerts, cards, buttons, forms)

Nueva Aplicación

Para una nueva aplicación desde cero:

Copia un template desde /illanes/v3/templates/
Personaliza el contenido
Usa componentes del sistema según necesites
Sigue las normas de diseño

CDN vs Local

Opción	Pros	Contras
CDN	• Sin mantenimiento • Actualizaciones automáticas • Cacheable	• Requiere conexión • Menos control
Local	• Funciona offline • Control total • Personalización	• Mantenimiento manual • Sin updates automáticos

ℹ Recomendación: Usa CDN para proyectos en producción. Usa local para desarrollo o sitios con requerimientos especiales.

Integración con Frameworks

Vanilla HTML

<!DOCTYPE html>
<html lang="es">
<head>
  <link href="..." rel="stylesheet">
</head>
<body>
  <div class="container">
    <!-- Tu contenido -->
  </div>
</body>
</html>

Flask (Python)

<!-- templates/base.html -->
<link rel="stylesheet" href="{{ url_for('static', filename='illanes/v3/illanes-manual.min.css') }}">

FastAPI + Jinja2

<!-- templates/layout.html -->
<link rel="stylesheet" href="/illanes/v3/illanes-manual.min.css">

Django

{% load static %}
<link rel="stylesheet" href="{% static 'illanes/v3/illanes-manual.min.css' %}">