Tailwind CSS on kenji.blog

Personalización de temas en Hugo: Cómo introducir Tailwind CSS

Sun, 13 Sep 2026 03:00:00 +0900

Introducción: La poderosa sinergia entre el generador de sitios estáticos Hugo y Tailwind CSS

En el desarrollo frontend moderno, equilibrar el rendimiento y la experiencia del desarrollador (DX: Developer Experience) es una de las prioridades más importantes en cualquier proyecto. Combinar Hugo, que cuenta con una de las velocidades de compilación más rápidas del mundo entre los generadores de sitios estáticos (SSG), con Tailwind CSS, que introdujo el paradigma innovador de utility-first (utilidad primero), se puede considerar una de las soluciones definitivas a este desafío.

Hugo está escrito en el lenguaje Go y posee un rendimiento asombroso que completa la compilación en apenas unos segundos, o incluso milisegundos, incluso para sitios con miles de páginas. Por otro lado, Tailwind CSS elimina el cambio de contexto entre archivos CSS y HTML, acelerando la iteración del diseño al permitir escribir innumerables clases de utilidad predefinidas (como flex, text-center, mt-4, etc.) directamente en el HTML.

En este artículo, explicaremos de manera exhaustiva y detallada, desde los fundamentos de la arquitectura hasta la perspectiva de la optimización matemática del rendimiento, el proceso de introducir Tailwind CSS a un tema de Hugo y, además, la construcción de una canalización de activos (Hugo Pipes) avanzada usando PostCSS.

1. La evolución hacia el CSS utility-first y la orientación a componentes

Antes de sumergirnos en los pasos de instalación de Tailwind CSS, es sumamente útil comprender profundamente el contexto y la historia de la evolución de la filosofía de diseño CSS detrás de por qué deberíamos usar Tailwind CSS.

Limitaciones de los diseños CSS tradicionales (BEM y OOCSS)

En el desarrollo web tradicional, asignar nombres de clases semánticas se consideraba una buena práctica. Por ejemplo, al crear un componente de tarjeta, se separaba el HTML y el CSS de la siguiente manera:

1
2
3
4
5
6
7


<div class="card">
 <img class="card__image" src="image.jpg" alt="miniatura">
 <div class="card__content">
 <h2 class="card__title">Título</h2>
 <p class="card__description">La descripción va aquí.</p>
 </div>
</div>

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12


.card {
 border-radius: 8px;
 box-shadow: 0 4px 6px rgba(0,0,0,0.1);
 background-color: #ffffff;
 overflow: hidden;
}
.card__title {
 font-size: 1.5rem;
 font-weight: bold;
 color: #333333;
}
/* A partir de aquí continúan estilos detallados */

Este tipo de diseño basado en BEM (Block Element Modifier) funciona mientras la escala del proyecto es pequeña, pero tiende a causar los siguientes problemas:

Agotamiento y fatiga por nombramiento: Cada vez que se crea un componente similar, hay que pensar en un nuevo nombre de clase (por ejemplo: card-news, card-featured, etc.).
Exceso (bloat) de CSS: El número de líneas de CSS sigue aumentando cada vez que se agrega una nueva funcionalidad, y el CSS, una vez escrito, rara vez se elimina por temor a “no saber dónde se está utilizando”, acumulando así código muerto.
Cambios de contexto: Al gestionar la estructura HTML y los estilos CSS en archivos separados, la cantidad de veces que se alterna entre pestañas en el editor aumenta exponencialmente.

Cambio de paradigma con Tailwind CSS

Tailwind CSS resuelve estos problemas mediante un enfoque de “combinación de clases de utilidad”. El componente de tarjeta mencionado anteriormente se vería así usando Tailwind CSS:

1
2
3
4
5
6
7


<div class="rounded-lg shadow-md bg-white overflow-hidden">
 <img class="w-full h-48 object-cover" src="image.jpg" alt="miniatura">
 <div class="p-6">
 <h2 class="text-2xl font-bold text-gray-800">Título</h2>
 <p class="mt-2 text-gray-600">La descripción va aquí.</p>
 </div>
</div>

Dado que el nombre de la clase en sí representa el valor de estilo específico (p-6 es padding: 1.5rem;, etc.), puedes predecir el resultado final de renderizado simplemente mirando el HTML. Además, gracias al compilador JIT (Just-In-Time) de Tailwind, solo las clases realmente utilizadas se extraen al archivo CSS de producción, por lo que el tamaño del archivo CSS se reduce al extremo.

2. Arquitectura de Hugo Pipes y PostCSS

Para integrar Tailwind CSS en Hugo, es necesario comprender la canalización de procesamiento de activos llamada Hugo Pipes. Hugo Pipes es una característica poderosa que completa todo el procesamiento relacionado con los activos, como la compilación de Sass/SCSS, el empaquetado y la minificación de JavaScript, y la ejecución de PostCSS que usaremos en esta ocasión, enteramente dentro de Hugo.

PostCSS es una herramienta para transformar CSS mediante el uso de complementos de JavaScript. Tailwind CSS en sí también funciona, de hecho, como un complemento de PostCSS.

Mecanismo de transformación de AST (Árbol de Sintaxis Abstracta) por PostCSS

Comprender cómo PostCSS procesa el CSS es de gran ayuda para la resolución de problemas. El siguiente diagrama de Mermaid muestra la canalización desde que PostCSS lee el archivo CSS, lo transforma a través de los complementos y genera el CSS final.

flowchart TD
A["CSS sin procesar (styles.css)"] -->|Parser| B["AST (Árbol de Sintaxis Abstracta)"]
B --> C["Complemento 1: Tailwind CSS"]
C --> D["Complemento 2: Autoprefixer"]
D --> E["Complemento N: cssnano"]
E -->|Stringifier| F["CSS Compilado y Optimizado"]

Analizador (Parser): Analiza la cadena CSS en bruto (cruda) de entrada y la convierte en una estructura de datos manejable mediante programación, el AST (Árbol de Sintaxis Abstracta).
Complementos (Plugins):
- Tailwind CSS: Escanea los archivos de plantilla (HTML o Markdown) y añade las clases de utilidad utilizadas como nodos en el AST. También expande la directiva @tailwind.
- Autoprefixer: Consulta la base de datos de Can I Use y, si es necesario, añade prefijos de proveedor (-webkit-, -moz-, etc.) a las propiedades del AST.
Generador de cadenas (Stringifier): Convierte el AST, una vez finalizada la transformación, nuevamente en una cadena CSS interpretable por el navegador para su salida.

3. Configuración del entorno y requisitos previos

Ahora, pasemos a los pasos de instalación reales. Primero, comprobaremos si está instalado el software necesario.

Requisitos indispensables

Hugo Extended Version: No es el Hugo normal, sino la versión Extended (Extendida) que incluye funciones de procesamiento de Sass/SCSS y compatibilidad nativa con PostCSS. Ejecuta el siguiente comando en la terminal y asegúrate de que la cadena extended esté incluida en la información de la versión.
1 2 3

hugo version # Ejemplo de salida esperada: # hugo v0.121.2-4146... windows/amd64 BuildDate=... VendorInfo=gohugoio +extended
Node.js y npm: Los paquetes de dependencia como Tailwind CSS y PostCSS se ejecutan sobre Node.js. Asegúrate de tener instalado Node.js (se recomienda la versión LTS).
1 2

node -v npm -v

Instalación de paquetes npm

Inicializa npm en el directorio raíz del proyecto (el nivel donde se encuentra el archivo de configuración de Hugo, hugo.toml) e instala los paquetes necesarios.

1
2
3
4
5


# Generación de package.json
npm init -y

# Instalación de Tailwind CSS, PostCSS y Autoprefixer como dependencias de desarrollo
npm install -D tailwindcss postcss postcss-cli autoprefixer

[!IMPORTANT] Si no está instalado postcss-cli, puede que se produzca un error al invocar PostCSS desde dentro de Hugo. Dado que Hugo Pipes utiliza internamente postcss-cli, asegúrate de instalarlo sin falta.

4. Construcción de los archivos de configuración (PostCSS y Tailwind CSS)

Una vez completada la instalación de los paquetes, crearemos dos archivos de configuración importantes que controlan el comportamiento del proyecto. Colócalos en el directorio raíz del proyecto.

Creación de tailwind.config.js

Al ejecutar el siguiente comando en la terminal, se generará el archivo de configuración predeterminado.

1

npx tailwindcss init

Abre el archivo tailwind.config.js generado en tu editor y configura la propiedad content. Esta parte es sumamente importante. Tailwind analizará los archivos de las rutas especificadas aquí y extraerá las clases utilizadas. Especifica las rutas de los archivos de diseño (layouts) y los archivos de contenido de forma precisa según la estructura de directorios del proyecto Hugo.

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28


/** @type {import('tailwindcss').Config} */
module.exports = {
 // Especifica el destino del análisis de acuerdo a la estructura de directorios de Hugo
 content: [
 "./content/**/*.md",
 "./content/**/*.html",
 "./layouts/**/*.html",
 "./assets/**/*.js",
 // Si estás utilizando un tema, también debes incluir el directorio del tema
 // "./themes/my-theme/layouts/**/*.html",
 ],
 theme: {
 extend: {
 // Extiende aquí colores personalizados, fuentes, etc.
 colors: {
 'brand-primary': '#3490dc',
 'brand-secondary': '#ffed4a',
 },
 fontFamily: {
 'sans': ['Helvetica Neue', 'Arial', 'Hiragino Kaku Gothic ProN', 'Meiryo', 'sans-serif'],
 }
 },
 },
 plugins: [
 // Añade complementos oficiales si es necesario (ej: complemento Typography)
 // require('@tailwindcss/typography'),
 ],
}

Creación de postcss.config.js

A continuación, crea un archivo postcss.config.js en la raíz del proyecto para definir qué complementos ejecutará PostCSS y en qué orden.

1
2
3
4
5
6


module.exports = {
 plugins: {
 tailwindcss: {},
 autoprefixer: {},
 }
}

Con esta configuración, cuando Hugo invoque a PostCSS, primero se ejecutará el procesamiento de Tailwind CSS y, luego, Autoprefixer aplicará los prefijos del proveedor.

5. Construcción de la canalización de activos CSS en Hugo

Una vez completada la configuración, por fin incorporaremos Tailwind CSS en el lado del tema de Hugo.

5-1. Creación del archivo CSS como punto de entrada

Crea el archivo CSS que servirá como punto de entrada en el directorio assets/css/ (si no existe, créalo). Aquí lo llamaremos main.css.

Ruta del archivo: assets/css/main.css

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16


/* Carga de los estilos base de Tailwind (reseteo CSS, etc.) */
@tailwind base;

/* Carga de las clases de componentes */
@tailwind components;

/* Carga de las clases de utilidad */
@tailwind utilities;

/* Si necesitas CSS personalizado propio, puedes agregarlo aquí,
 pero se recomienda hacerlo mediante extend en tailwind.config.js siempre que sea posible */
@layer components {
 .btn-primary {
 @apply bg-blue-500 hover:bg-blue-700 text-white font-bold py-2 px-4 rounded transition-colors duration-300;
 }
}

5-2. Edición del archivo de diseño (head.html)

A continuación, describiremos la canalización para cargar el archivo CSS anterior desde la plantilla de Hugo y procesarlo con PostCSS. Generalmente, se edita la plantilla parcial que define el interior de la etiqueta <head> (por ejemplo, layouts/partials/head.html).

Ruta del archivo: layouts/partials/head.html

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25


<head>
 <meta charset="utf-8">
 <meta name="viewport" content="width=device-width, initial-scale=1">
 <title>{{ .Title }} | {{ .Site.Title }}</title>

 <!-- Obtener assets/css/main.css -->
 {{ $css := resources.Get "css/main.css" }}

 <!-- Definición de opciones para PostCSS -->
 {{ $options := dict "inlineImports" true }}
 {{ $css = $css | resources.PostCSS $options }}

 <!-- Canalización de optimización de activos para el entorno de producción (Production) -->
 {{ if hugo.IsProduction }}
 <!-- 1. Minify (Compresión) -->
 {{ $css = $css | minify }}
 <!-- 2. Fingerprint (Adición de hash para invalidar la caché) -->
 {{ $css = $css | fingerprint "sha512" }}
 <!-- 3. Salida de la etiqueta incluyendo SRI (Subresource Integrity) -->
 <link rel="stylesheet" href="{{ $css.RelPermalink }}" integrity="{{ $css.Data.Integrity }}" crossorigin="anonymous">
 {{ else }}
 <!-- En el entorno de desarrollo (Development), salida directa sin comprimir (prioriza la velocidad de compilación) -->
 <link rel="stylesheet" href="{{ $css.RelPermalink }}">
 {{ end }}
</head>

Explicación de la canalización y diagrama de Mermaid

Ilustraremos mediante un diagrama de Mermaid cómo el código de la plantilla Go anterior procesa el archivo CSS a través de una serie de procesos de canalización.

flowchart TD
A["assets/css/main.css"] -->|resources.Get| B["Espacio de Memoria de Hugo"]
B -->|resources.PostCSS| C["Proceso JIT de PostCSS + Tailwind"]
C --> D{"hugo.IsProduction ?"}
D -- "Sí (Entorno de Producción)" --> E["minify (Eliminación de espacios en blanco y saltos de línea)"]
E --> F["fingerprint (Cálculo de hash)"]
F --> G["public/css/main.[hash].css (con SRI)"]
D -- "No (Entorno de Desarrollo)" --> H["public/css/main.css"]

resources.Get: Busca el archivo especificado dentro del directorio assets y lo carga como un objeto de recurso en memoria.
resources.PostCSS: Hace referencia a postcss.config.js en la raíz del proyecto y aplica el procesamiento de Tailwind CSS y Autoprefixer al código fuente CSS. En el entorno de desarrollo (hugo server), el modo JIT se activa, generando rápidamente solo las clases necesarias cuando el archivo cambia.
minify: Durante la compilación en el entorno de producción (como con hugo --environment production), elimina espacios en blanco y comentarios innecesarios, minimizando el tamaño del archivo.
fingerprint: Calcula un hash SHA basado en el contenido del archivo y lo añade al nombre del archivo (por ejemplo, main.ab12cd...css). Esto permite la “invalidación de caché” (cache busting), que asegura que se lea de manera confiable un nuevo archivo cuando el CSS se actualiza, al mismo tiempo que aprovecha la poderosa caché del navegador.
integrity: Imprime el atributo SRI utilizando el valor hash calculado por Fingerprint para prevenir la manipulación desde CDNs, etc.

6. Análisis matemático del rendimiento en la optimización de CSS

Una de las mayores ventajas de introducir Tailwind CSS es la reducción drástica del tamaño del archivo CSS entregado. Utilizando un modelo matemático, analicemos cuantitativamente cómo afecta esto al rendimiento web (especialmente a First Contentful Paint: FCP).

Modelo de reducción del tamaño del archivo CSS

En los frameworks CSS tradicionales (como Bootstrap), todo el volumen se carga incluyendo estilos no utilizados, por lo que el tamaño del archivo $S_{original}$ tiende a ser grande (alrededor de 150KB a 200KB). Si denotamos como $S_{purged}$ el tamaño después de aplicar la purga de clases innecesarias por el compilador JIT de Tailwind CSS, usando la tasa de reducción $R_{purge}$, se puede expresar de la siguiente manera:

$$ S_{purged} = S_{original} \times (1 - R_{purge}) $$

En un proyecto típico, $R_{purge}$ alcanza cerca de $0.9$ (reducción del 90%) y $S_{purged}$ se mantiene en apenas unos 10KB a 20KB.

Además, en el momento de la entrega, se realiza una compresión mediante Brotli o Gzip en el lado del servidor. Si establecemos la tasa de compresión como $R_{compress}$ (generalmente alrededor de 0.7 a 0.8), el tamaño del payload final que fluye por la red, $S_{final}$, se calcula con la siguiente fórmula:

$$ S_{final} = S_{purged} \times (1 - R_{compress}) $$

Ruta de renderizado crítica y latencia de red

El tiempo hasta que el navegador dibuja el primer contenido en la pantalla (FCP) se puede aproximar como la suma del tiempo de descarga de HTML, el tiempo de descarga de CSS y el tiempo de renderizado.

$$ T_{FCP} \approx RTT + \frac{S_{HTML}}{BW} + RTT + \frac{S_{final}}{BW} + T_{render} $$

Aquí,

$RTT$ : Round Trip Time (tiempo de retardo de ida y vuelta de comunicación con el servidor)
$BW$ : Ancho de banda de la red (Bandwidth)

En entornos como redes móviles donde $BW$ es estrecho y $RTT$ es grande (latencia alta), el enfoque de Tailwind CSS de reducir $S_{final}$ a unidades de kilobytes hace que el término $\frac{S_{final}}{BW}$ se acerque al límite de cero, y se convierte en la fuerza motriz para obtener puntuaciones asombrosas (en herramientas como Google PageSpeed Insights).

7. Inicio del servidor de desarrollo y verificación de la recarga en caliente

Una vez completada toda la configuración, iniciaremos el servidor de desarrollo de Hugo y verificaremos que Tailwind CSS funciona correctamente.

1

hugo server -D

Accede a http://localhost:1313/ en el navegador y verifica que se muestre el sitio. Abre un archivo de contenido Markdown o una plantilla de Hugo (archivos bajo layouts/) e intenta agregar una clase.

1
2
3
4
5


<!-- Ejemplo de aplicación de clases de Tailwind para pruebas -->
<div class="bg-gradient-to-r from-blue-500 to-purple-600 text-white p-8 rounded-xl shadow-2xl text-center transform transition duration-500 hover:scale-105">
 <h1 class="text-4xl font-extrabold tracking-tight">¡Tailwind CSS + Hugo es Increíble!</h1>
 <p class="mt-4 text-lg font-medium">Verifica que la recarga en caliente se refleje instantáneamente.</p>
</div>

En el mismo momento en que guardas el archivo, el potente observador de archivos de Hugo (file watcher) se coordina con el compilador JIT de Tailwind, el CSS se reconstruye en unidades de milisegundos y deberías poder saborear la emoción de ver cómo el navegador se recarga automáticamente (hot reload).

Solución de problemas: Si los estilos no se reflejan

Si los cambios no se reflejan, verifica los siguientes puntos:

Configuración de la ruta content en tailwind.config.js Si la ruta del archivo a escanear es incorrecta, Tailwind no podrá detectar las clases utilizadas dentro de ese archivo y no las emitirá al CSS. Especialmente si usas un tema, verifica que la ruta al directorio del tema no haya sido omitida.
Error de PostCSS Si se muestra un error como Error: failed to transform resource: PostCSS not found en el registro del servidor de Hugo en la terminal, es posible que npm install no se haya ejecutado correctamente o que falte postcss-cli.
Borrar la caché de Hugo Rara vez, un CSS antiguo puede permanecer como causa de la caché de Hugo. Intenta detener el servidor e iniciarlo con hugo server --ignoreCache, o elimina el directorio temporal del sistema operativo (como /tmp/hugo_cache/).

8. Compilación para el entorno de producción y una mayor sofisticación

Al desplegar tu sitio en un servidor de producción (Netlify, Vercel, GitHub Pages, Cloudflare Pages, etc.), necesitas configurar variables de entorno para ejecutar la canalización de optimización de producción.

1
2


# Ejemplo de comando de compilación para producción
NODE_ENV=production hugo --minify --environment production

Al agregar la bandera --environment production, se ejecuta el bloque {{ if hugo.IsProduction }} dentro de head.html, y se realiza la minificación y la adición del Fingerprint al CSS.

Estilizar Markdown usando el complemento Typography

En un blog o un sitio de documentación como Hugo, no puedes agregar clases directamente a los elementos HTML puros (<h1>, <p>, <ul>, etc.) generados a partir de Markdown. Lo que resulta extremadamente útil en tales casos es el Complemento Typography (Typography plugin) oficial de Tailwind.

Instalación del complemento

1

npm install -D @tailwindcss/typography

Añadir a tailwind.config.js

1
2
3
4
5
6


module.exports = {
 // ...
 plugins: [
 require('@tailwindcss/typography'),
 ],
}

Aplicación en la plantilla Simplemente asigna la clase prose (y, opcionalmente, las variantes de color o tamaño a tu gusto) al elemento contenedor que produce el texto del artículo para aplicar estilos predeterminados hermosos.
1 2 3

<article class="prose prose-lg prose-blue mx-auto mt-10"> {{ .Content }} </article>

Con esto, se elimina por completo la necesidad de escribir manualmente selectores CSS complejos (como .article-content h2 { ... }), y la modularidad de los componentes se conserva perfectamente.

9. Conclusión: Finalización de un ecosistema frontend de alta mantenibilidad

¡Buen trabajo! Con esto, has completado una canalización de activos de desarrollo web perfecta equipada con el motor de generación de sitios estáticos ultrarrápido de Hugo, las características de estilo modernas de Tailwind CSS y la extensibilidad de PostCSS.

La ventaja sobresaliente de esta arquitectura es que “la configuración requiere hacerse solo una vez al principio”. Una vez que hayas construido la canalización, los desarrolladores pueden construir interfaces de usuario complejas a una velocidad asombrosa con solo describir clases de utilidad intuitivas en plantillas HTML o Markdown, sin tener que abrir ningún archivo CSS.

Además, dado que el tamaño del CSS de salida siempre se minimiza, esto conduce directamente a una mejora en la puntuación de los Core Web Vitals, y también funciona de manera muy favorable desde la perspectiva del SEO.

La combinación de Hugo y Tailwind CSS seguirá siendo una de las “mejores opciones” en cada proyecto, desde blogs tecnológicos personales hasta sitios corporativos a gran escala. ¡Por favor, asegúrate de utilizar esta poderosa cadena de herramientas para disfrutar de una cómoda vida de desarrollo web!

Puntos clave del diseño CSS para la compatibilidad con el modo oscuro en blogs

Sat, 12 Sep 2026 12:00:00 +0900

En el desarrollo web moderno, el soporte para el modo oscuro (Dark Mode) ha pasado de ser una simple “función agradable de tener” (Nice to have) a un “requisito indispensable” (Must have) para mejorar la experiencia del usuario (UX). Especialmente en medios que asumen lecturas prolongadas de texto, como blogs o sitios de documentación, tiene el efecto de reducir la fatiga visual del usuario y el consumo de batería del dispositivo, por lo que la importancia de la compatibilidad con el modo oscuro es extremadamente alta.

En este artículo, profundizaremos desde la perspectiva de un ingeniero frontend en los desafíos técnicos inevitables y los puntos clave para un diseño CSS de alta mantenibilidad al implementar el modo oscuro en un blog. Cubriremos todo sobre la implementación del modo oscuro: el uso de CSS Custom Properties (variables CSS), controles avanzados de JavaScript e integración con SSR para prevenir FOUC (Flash of Unstyled Content), diseño de colores (RGB, HSL y el más reciente OKLCH) para garantizar la accesibilidad (WCAG 2.1 AAA), y ejemplos prácticos de código utilizando Tailwind CSS.

1. Fundamentos del diseño de temas mediante CSS Custom Properties (Variables CSS)

Al implementar el modo oscuro, el enfoque más estándar y poderoso en la actualidad es el uso de CSS Custom Properties (variables CSS). Mientras que las variables ($color) de los preprocesadores CSS como Sass se resuelven estáticamente durante la compilación, las variables CSS se resuelven y sobrescriben dinámicamente en el tiempo de ejecución del navegador. Esto hace posible cambiar el tono de color de toda la página al instante simplemente cambiando de clase desde JavaScript.

1.1 Definición de la paleta de colores básica

Primero, utilizamos la pseudoclase :root para definir la paleta de colores del modo claro (predeterminado). Luego, el patrón de diseño principal consiste en sobrescribir estas variables cuando se aplica un atributo como [data-theme='dark'] (o la clase .dark).

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30


/* Definición de variables del modo claro (predeterminado) */
:root {
 --color-bg-primary: #ffffff;
 --color-bg-secondary: #f3f4f6;
 --color-text-primary: #111827;
 --color-text-secondary: #4b5563;
 --color-accent: #3b82f6;
 --color-border: #e5e7eb;
}

/* Sobrescritura de variables en modo oscuro */
[data-theme='dark'] {
 --color-bg-primary: #111827;
 --color-bg-secondary: #1f2937;
 --color-text-primary: #f9fafb;
 --color-text-secondary: #9ca3af;
 --color-accent: #60a5fa;
 --color-border: #374151;
}

/* Aplicación real */
body {
 background-color: var(--color-bg-primary);
 color: var(--color-text-primary);
 transition: background-color 0.3s ease, color 0.3s ease;
}

a {
 color: var(--color-accent);
}

De esta manera, separando por completo la especificación de diseño y tipografía de la especificación de colores (tema), la mantenibilidad del CSS mejora drásticamente.

1.2 Uso de @media (prefers-color-scheme: dark)

Si el modo oscuro está configurado a nivel de sistema operativo (OS), es deseable desde el punto de vista de UX aplicar automáticamente el tema oscuro desde la primera visita al sitio web. Esto se logra mediante la media query @media (prefers-color-scheme: dark).

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11


/* Fallback para cuando el modo oscuro está configurado en el SO */
@media (prefers-color-scheme: dark) {
 :root:not([data-theme='light']) {
 --color-bg-primary: #111827;
 --color-bg-secondary: #1f2937;
 --color-text-primary: #f9fafb;
 --color-text-secondary: #9ca3af;
 --color-accent: #60a5fa;
 --color-border: #374151;
 }
}

Con esta notación, a menos que el usuario haya seleccionado explícitamente el modo claro (data-theme='light'), se sobrescriben las variables respetando la configuración del modo oscuro del SO.

2. Comprensión del espacio de color y accesibilidad (WCAG 2.1 AAA)

En el diseño de color para el modo oscuro, no basta simplemente con “poner el fondo negro y el texto blanco”. Si el contraste es demasiado fuerte, causará halos y dificultará la lectura; si el contraste es demasiado bajo, la visibilidad se verá comprometida. Las Web Content Accessibility Guidelines (WCAG) definen estrictamente las relaciones de contraste para asegurar la visibilidad.

2.1 Fórmula para calcular el ratio de contraste de WCAG

El ratio de contraste (Contrast Ratio) $CR$ en WCAG se define de la siguiente manera, utilizando la luminancia relativa (Relative Luminance) del color de fondo y el color de primer plano.

$$CR = \frac{L_{lighter} + 0.05}{L_{darker} + 0.05}$$

Aquí, $L_{lighter}$ es la luminancia relativa del color más claro y $L_{darker}$ es la luminancia relativa del color más oscuro (los valores van de 0.0 a 1.0). Para alcanzar el nivel AAA de WCAG 2.1, se requiere un ratio de contraste de 7:1 o superior para el texto normal y de 4.5:1 o superior para texto grande.

La luminancia relativa $L$ se calcula a partir de los valores RGB del espacio de color sRGB usando la siguiente fórmula compleja.

$$L = 0.2126 \times R + 0.7152 \times G + 0.0722 \times B$$

Cada componente ($R, G, B$) utiliza el valor normalizado obtenido al dividir el valor original de 8 bits ($R_{sRGB}$) entre 255, y aplica la siguiente transformación para deshacer la corrección gamma:

$$ R, G, B = \begin{cases} \frac{C_{sRGB}}{12.92} & \text{if } C_{sRGB} \le 0.03928 \\ \left( \frac{C_{sRGB} + 0.055}{1.055} \right)^{2.4} & \text{otherwise} \end{cases} $$

Realizar este cálculo manualmente es difícil, pero al usar herramientas de diseño de color, es posible seleccionar automáticamente colores que cumplan con un ratio de contraste de 7:1 ($CR \ge 7.0$).

2.2 HSL vs RGB vs OKLCH

Al crear una paleta de colores, el RGB y el HSL solían ser los más populares. Sin embargo, tienen un gran defecto desde el punto de vista de la “uniformidad perceptual”.

RGB: Son los tres colores primarios mecánicos de la luz, y es difícil para los humanos hacer ajustes intuitivos como “hacerlo más brillante” o “hacerlo más oscuro”.
HSL: Utiliza Tono (Hue), Saturación (Saturation) y Luminosidad (Lightness), pero la “Luminosidad (L)” de HSL no coincide con el brillo percibido por el ojo humano. Por ejemplo, en HSL, un amarillo puro y un azul puro al 50% de luminosidad son numéricamente igual de brillantes, pero al ojo humano, el amarillo parece abrumadoramente más brillante.
OKLCH: Es el espacio de color más nuevo introducido en CSS Color Module Level 4. Está compuesto por Lightness (Luminosidad perceptual), Chroma (Croma/Saturación) y Hue (Tono), y coincide perfectamente con las características visuales humanas (uniformidad perceptual).

Al utilizar OKLCH, incluso si cambias el tono (Hue), puedes mantener la misma luminosidad perceptual (Lightness), lo que hace que la generación de una paleta de colores para el modo oscuro sea extremadamente predecible y segura.

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14


/* Ejemplo de definición de variables CSS usando OKLCH */
:root {
 /* En el modo claro, luminosidad base alta, saturación contenida */
 --bg-base: oklch(0.98 0.01 250);
 --text-base: oklch(0.25 0.02 250);
 --primary-brand: oklch(0.65 0.15 250);
}

[data-theme="dark"] {
 /* En el modo oscuro, solo invirtiendo la luminosidad es fácil mantener el contraste perceptual */
 --bg-base: oklch(0.20 0.02 250);
 --text-base: oklch(0.95 0.01 250);
 --primary-brand: oklch(0.75 0.15 250); /* Un poco más claro para el modo oscuro para asegurar visibilidad */
}

Al adoptar OKLCH de esta manera, se puede construir lógicamente y de forma sencilla un mecanismo que garantice un ratio de contraste consistente (nivel WCAG AAA) entre múltiples temas.

3. Prevención de FOUC (Flash of Unstyled Content) e Hidratación SSR

El problema que más molesta a los desarrolladores en la implementación del modo oscuro es el parpadeo de la pantalla conocido como FOUC (Flash of Unstyled Content).

3.1 La trampa de cambiar de tema con JS en el lado del cliente

En SPAs (o sitios estáticos vía SSG) como React o Vue, es común guardar las preferencias del usuario en localStorage y leerlas con JavaScript para cambiar el tema. Sin embargo, si este proceso se realiza dentro de algo como useEffect de React, ocurren los siguientes problemas:

El navegador renderiza el HTML/CSS del modo claro.
Se carga y se ejecuta el bundle de JS.
Se lee la configuración dark de localStorage.
Se aplica la clase dark al HTML y la pantalla se oscurece de repente (parpadeo).

3.2 La solución perfecta para FOUC: Uso de Cookies y SSR

La mejor práctica para prevenir completamente el FOUC y evitar errores de hidratación es guardar la configuración del tema del usuario en document.cookie y devolver el HTML con la clase adecuada ya aplicada durante la fase de Renderizado del Lado del Servidor (SSR).

El siguiente diagrama de secuencia muestra el flujo ideal para inicializar el tema utilizando una Cookie.

sequenceDiagram
participant User as "Usuario"
participant Browser as "Navegador SO"
participant Server as "Servidor SSR"
participant DOM as "DOM del Cliente"
User->>Browser: "Solicitar página"
Browser->>Server: "Petición GET con Cookie (theme=dark)"
Server-->>Browser: "Devolver HTML con <html data-theme='dark'>"
Browser->>DOM: "Renderizar HTML Inicial (Sin FOUC)"
DOM->>DOM: "Ejecutar Script de Hidratación"
alt "Cookie ausente (Primera Visita)"
DOM->>Browser: "Comprobar prefers-color-scheme del SO"
Browser-->>DOM: "Resultado de matchMedia (ej. dark)"
DOM->>DOM: "Establecer data-theme='dark' vía script en línea bloqueante"
end

3.3 Línea de defensa mediante script en línea (Para sitios estáticos que no pueden usar Cookies)

Para los blogs donde solo se utiliza SSG (Generación de Sitios Estáticos) y el SSR es imposible (exportaciones estáticas de Hugo, Gatsby o Astro), es indispensable colocar un código JavaScript en línea dentro de la etiqueta <head> que bloquee la ejecución y aplique la clase justo antes de que el DOM se renderice.

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11


<!-- Colocar al final dentro de <head> -->
<script>
 (function() {
 try {
 var localTheme = localStorage.getItem('theme');
 var osTheme = window.matchMedia('(prefers-color-scheme: dark)').matches ? 'dark' : 'light';
 var theme = localTheme || osTheme;
 document.documentElement.setAttribute('data-theme', theme);
 } catch (e) {}
 })();
</script>

Dado que este pequeño script bloquea el renderizado del navegador y se ejecuta de inmediato, el atributo data-theme ya estará establecido en el momento en que se dibuje la pantalla, lo que permite prevenir completamente el parpadeo de la pantalla (FOUC).

4. Enfoques de implementación con Tailwind CSS y SCSS/CSS puro

Al incorporar el modo oscuro en un proyecto real, es necesario comprender el enfoque según cada herramienta.

4.1 Modo oscuro en Tailwind CSS

Tailwind CSS proporciona la variante dark: por defecto, lo que facilita enormemente la implementación del modo oscuro. Se configura la propiedad darkMode en el archivo de configuración (tailwind.config.js).

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14


// tailwind.config.js
module.exports = {
 // 'media' (depende de la config del SO) o 'class' (se puede cambiar manualmente)
 darkMode: 'class',
 theme: {
 extend: {
 colors: {
 /* Expandir la paleta de colores de Tailwind usando variables CSS */
 primary: 'rgb(var(--color-primary) / <alpha-value>)',
 background: 'rgb(var(--color-background) / <alpha-value>)',
 }
 }
 }
}

En el lado del HTML, simplemente se añaden clases como en el siguiente ejemplo:

1
2
3
4


<div class="bg-white dark:bg-gray-900 text-gray-900 dark:text-gray-100">
 <h1 class="text-2xl font-bold">Hello World</h1>
 <p class="mt-2">Tailwind makes dark mode incredibly easy.</p>
</div>

Sin embargo, escribir dark:bg-xxx en todos los elementos puede causar que los componentes se vuelvan excesivamente grandes. En blogs o aplicaciones a gran escala, se recomienda un diseño híbrido (diseño de color semántico) donde la base sean las variables CSS y Tailwind referencie esas variables CSS.

A continuación se muestra un diagrama de clases que ilustra la herencia de variables CSS y sus capas de aplicación.

classDiagram
class GlobalCSSVariables {
"--color-brand-500"
"--color-gray-900"
}
class SemanticVariables {
"--bg-primary"
"--text-base"
"--accent"
}
class TailwindConfig {
"theme.colors.background"
"theme.colors.primary"
}
class UIComponents {
"class='bg-background text-primary'"
}
GlobalCSSVariables <|-- SemanticVariables : ":root & .dark"
SemanticVariables <|-- TailwindConfig : "tailwind.config.js"
TailwindConfig <.. UIComponents : "Aplica clases de utilidad"

4.2 Implementación con SCSS/CSS puro (Uso de Mixin)

En proyectos que no utilizan Tailwind y escriben SCSS propio, se puede aprovechar @mixin para encapsular los estilos del modo oscuro.

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25


/* Definición del Mixin de SCSS */
@mixin dark-mode {
 /* Soporta tanto el atributo [data-theme='dark'] como la configuración del SO */
 [data-theme='dark'] & {
 @content;
 }
 @media (prefers-color-scheme: dark) {
 :root:not([data-theme='light']) & {
 @content;
 }
 }
}

/* Ejemplo de uso */
.card {
 background-color: #ffffff;
 color: #333333;
 border: 1px solid #eeeeee;

 @include dark-mode {
 background-color: #1a202c;
 color: #e2e8f0;
 border-color: #2d3748;
 }
}

Este método es intuitivo, pero el tamaño del archivo CSS compilado tiende a crecer considerablemente (las media queries se duplican para cada selector), por lo que la tendencia actual es migrar a un diseño centrado en las variables CSS (Custom Properties).

5. Optimización del modo oscuro para imágenes (Image) y SVG

Incluso si el diseño de color del texto y los fondos está completo, si las imágenes o los iconos (SVG) colocados como contenido permanecen en el modo claro, se verán deslumbrantes y desentonarán en el modo oscuro. La optimización para estos elementos también es indispensable.

5.1 Filtros CSS para reducir la luminosidad de las imágenes

Las imágenes de mapa de bits, como las fotografías, a veces pueden ser demasiado brillantes si se muestran tal cual en el modo oscuro. Al usar la propiedad filter de CSS para reducir ligeramente la luminosidad (brightness) y el contraste (contrast) de las imágenes, se pueden integrar de manera natural en la interfaz de usuario del tema oscuro.

 1
 2
 3
 4
 5
 6
 7
 8
 9
10


[data-theme='dark'] img:not([src*=".svg"]) {
 /* Reducir el brillo y aumentar un poco el contraste */
 filter: brightness(0.8) contrast(1.1);
 transition: filter 0.3s ease;
}

[data-theme='dark'] img:hover {
 /* Restaurar el brillo original al hacer hover (si el usuario quiere ver los detalles) */
 filter: brightness(1) contrast(1);
}

5.2 Alternancia de imágenes mediante la etiqueta `<picture>`

Para imágenes de logotipos o diagramas explicativos (como JPEGs con un fondo blanco fijo), el procesamiento de filtros por sí solo no es suficiente. En esos casos, la solución correcta es utilizar el elemento <picture> de HTML y media queries para cargar un archivo de imagen diferente diseñado para el modo oscuro.

1
2
3
4
5
6


<picture>
 <!-- Mostrar esto a los usuarios con la configuración del SO en modo oscuro -->
 <source srcset="/img/logo-dark.png" media="(prefers-color-scheme: dark)">
 <!-- Predeterminado (Modo claro) -->
 <img src="/img/logo-light.png" alt="Logotipo del sitio">
</picture>

No obstante, dado que este método no se sincroniza con cambios manuales a través de localStorage o similares (depende únicamente de la configuración del SO), si has implementado un cambio manual, necesitarás reescribir dinámicamente el src de las imágenes mediante JS, o alternar su visibilidad cambiando la propiedad display: none con clases CSS.

5.3 Compatibilidad con `currentColor` para iconos SVG

Para los SVGs en línea utilizados como iconos o similares, lo más inteligente es vincular el color de relleno al color del texto del elemento padre. Para ello, se especifica currentColor en los atributos fill o stroke del SVG.

1
2
3
4


<!-- El valor de la propiedad color en CSS (como var(--text-primary)) se aplicará automáticamente -->
<svg viewBox="0 0 24 24" fill="currentColor">
 <path d="M12 2L2 22h20L12 2z" />
</svg>

De esta manera, si cambias al modo oscuro y el color del texto del elemento padre se vuelve blanquecino, el icono SVG también cambiará automáticamente a tonos blancos.

6. Conclusión: Hacia un diseño de modo oscuro sostenible

Para implementar un modo oscuro de alta calidad en blogs o aplicaciones web, es esencial un diseño CSS que cubra los siguientes puntos clave:

Aprovechar CSS Custom Properties: Evitar codificar colores directamente y abstraerlos en nombres de variables semánticos (ej. --bg-primary).
Adoptar el espacio de color OKLCH: Diseñar lógicamente un ratio de contraste altamente accesible que cumpla con WCAG 2.1 AAA (7:1 o superior) en un espacio de color que sea perceptualmente uniforme.
Prevención estricta de FOUC: Eliminar completamente el parpadeo de la pantalla durante la carga inicial mediante la integración de SSR y Cookies, o a través de scripts en línea bloqueantes dentro de <head>.
Optimización de medios y recursos: Hacer uso de filter: brightness(), currentColor y la etiqueta <picture> para que los elementos distintos al texto también armonicen con el tema oscuro.

Estas cuidadosas consideraciones, que van mucho más allá de una simple “inversión de colores”, son las condiciones de un blog moderno que proporciona una experiencia de lectura excelente y sin fatiga visual, y que los usuarios apreciarán durante mucho tiempo. Si eres un desarrollador que va a introducir el modo oscuro, te animamos a que tomes como referencia los patrones de diseño presentados en este artículo.