Design 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!

Conceptos básicos de arquitectura de software: ¿Qué es Clean Architecture?

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

En el desarrollo de software moderno, construir un “sistema resistente al cambio” es un desafío eterno. Cambios en los requisitos comerciales, el surgimiento de nuevos frameworks, renovaciones de la interfaz de usuario (UI), migraciones de bases de datos. Frente a todos estos cambios, se requiere una arquitectura que pueda adaptarse de manera flexible sin tener que reconstruir todo el sistema. Una de las respuestas a esto es la Arquitectura Limpia (Clean Architecture), propuesta por Robert C. Martin (comúnmente conocido como Uncle Bob).

En este artículo, profundizaremos en la esencia de Clean Architecture a través de su historia, propósito, detalles de sus 4 capas, la regla de dependencia y ejemplos de implementación específicos. Realizaremos una explicación técnica muy profunda y detallada.

1. Problemas con las arquitecturas tradicionales y la historia de Clean Architecture

Históricamente, la arquitectura de software ha experimentado varios cambios de paradigma. En los primeros sistemas, el código de la lógica de negocio, la UI y el acceso a datos estaban fuertemente acoplados (lo que se conoce como código espagueti). Posteriormente, con el propósito de la separación de preocupaciones (Separation of Concerns), se popularizó la arquitectura de 3 capas (capa de presentación, capa de lógica de negocio, capa de acceso a datos).

Sin embargo, la arquitectura tradicional de 3 capas tenía un gran problema. Este era que “el dominio (lógica de negocio) terminaba dependiendo de la base de datos o el framework”.

Por ejemplo, si la capa de lógica de negocio llama directamente a la capa de acceso a datos (como un ORM), un cambio en el esquema de la base de datos o un cambio en el ORM afectará a la lógica de negocio. Es decir, se producía la contradicción de que las “reglas de negocio”, que son las más importantes y no deberían cambiar, dependían de la “infraestructura”, donde es más probable que ocurran cambios técnicos.

Como soluciones a esto, se han ideado arquitecturas como las siguientes:

Arquitectura Hexagonal (Ports and Adapters) - Alistair Cockburn
Arquitectura Cebolla (Onion Architecture) - Jeffrey Palermo
DCI (Data, Context and Interaction) - James Coplien, Trygve Reenskaug
BCE (Boundary-Control-Entity) - Ivar Jacobson

Todas estas arquitecturas tienen el mismo propósito. Ese es la “separación de preocupaciones”. Dividir el software en capas, creando un estado donde cada una pueda ser probada de forma independiente y sea independiente de agentes externos (UI, base de datos, frameworks).

Robert C. Martin integró los conceptos de estas excelentes arquitecturas y las consolidó en una regla práctica única que llamó “Clean Architecture”.

2. Propósito y características de Clean Architecture

Un sistema que adopta Clean Architecture tiene las siguientes características:

Independencia de frameworks (Independent of Frameworks): La arquitectura no depende de la existencia de bibliotecas de software ricas en funciones. Esto permite utilizar los frameworks como “herramientas” y elimina la necesidad de forzar el sistema en las restricciones del framework.
Testable (Testable): Las reglas de negocio se pueden probar sin la UI, la base de datos, el servidor web u otros elementos externos.
Independencia de la UI (Independent of UI): La UI puede cambiar fácilmente sin alterar el resto del sistema. Por ejemplo, una UI web puede ser reemplazada por una UI de consola sin cambiar las reglas de negocio.
Independencia de la base de datos (Independent of Database): Puede cambiar Oracle o SQL Server por Mongo, BigTable, CouchDB, etc. Las reglas de negocio no están atadas a la base de datos.
Independencia de cualquier agente externo (Independent of any external agency): De hecho, las reglas de negocio no saben nada sobre el mundo exterior.

3. Las 4 capas de Clean Architecture (Layers)

Clean Architecture se representa generalmente con un diagrama de círculos concéntricos. Cuanto más cerca del centro, el software se convierte en políticas de nivel superior (reglas de negocio con un alto nivel de abstracción). Cuanto más hacia el exterior, se convierte en mecanismos (detalles específicos).

graph TD
subgraph "External Interfaces (Frameworks & Drivers)"
A["Web"]
B["UI"]
C["Base de datos"]
D["APIs externas"]
end
subgraph "Interface Adapters"
E["Controladores"]
F["Puertas de enlace"]
G["Presentadores"]
end
subgraph "Application Business Rules (Use Cases)"
H["Interactores de casos de uso"]
end
subgraph "Enterprise Business Rules (Entities)"
I["Entidades"]
end
A --> E
B --> E
C --> F
D --> F
E --> H
F --> H
G --> H
H --> I

3.1. Entidades (Entities)

Las entidades encapsulan las reglas de negocio a nivel empresarial (Enterprise Business Rules). Una entidad puede ser un objeto con métodos, o puede ser un conjunto de estructuras de datos y funciones. Son las reglas más generales y de alto nivel que se pueden reutilizar en múltiples aplicaciones diferentes dentro de la empresa. Incluso si solo se está creando una única aplicación, las entidades son los objetos de negocio de esa aplicación. Incluso si hay cambios externos (como cambios en la navegación de la página o cambios en la seguridad), las entidades nunca se verán afectadas.

3.2. Casos de uso (Use Cases)

La capa de casos de uso contiene reglas de negocio específicas de la aplicación (Application Business Rules). Aquí se encapsulan e implementan todos los casos de uso del sistema. Los casos de uso coordinan el flujo de datos hacia y desde las entidades, e instruyen a las entidades a usar sus reglas de negocio para lograr los objetivos del caso de uso. Los cambios en esta capa no deben afectar a las entidades. Además, los cambios externos como la base de datos, la UI o los frameworks no afectan a esta capa. Los casos de uso están completamente aislados de estas preocupaciones.

3.3. Adaptadores de interfaz (Interface Adapters)

La capa de adaptadores de interfaz es un conjunto de adaptadores que convierten los datos del formato más conveniente para los casos de uso y las entidades, al formato más conveniente para algún agente externo como la base de datos o la web. Por ejemplo, los elementos de la arquitectura MVC (Modelo-Vista-Controlador) de una GUI en el mundo web pertenecen aquí. Los controladores toman la entrada del usuario, la pasan al caso de uso, y los presentadores toman la salida del caso de uso y la formatean para la vista (UI). También es el rol de esta capa convertir los datos a un formato que la base de datos (como SQL) pueda entender. Ningún código dentro de esta capa debe saber nada sobre la base de datos.

3.4. Frameworks y controladores (Frameworks & Drivers)

La capa más externa está compuesta por herramientas como bases de datos, frameworks web, etc. Aquí, por lo general, no se escribe mucho código más que el “código pegamento (glue code)” para comunicarse con el círculo interior. Esta capa contiene todos los detalles. La web es un detalle. La base de datos es un detalle. Mantenemos estas cosas en el exterior donde pueden hacer poco daño.

4. La regla de dependencia (The Dependency Rule)

Existe una regla muy importante y que absolutamente no se debe romper para que Clean Architecture funcione. Esa es “La regla de dependencia (The Dependency Rule)”.

Las dependencias del código fuente solo deben apuntar hacia adentro, hacia las políticas de nivel superior.

El código que pertenece a un círculo interior no debe saber nada sobre el código que pertenece a un círculo exterior. Ningún nombre declarado en un círculo exterior (funciones, clases, variables, etc.) debe ser mencionado por el código de un círculo interior. De manera similar, los formatos de datos utilizados en un círculo exterior no deben ser utilizados en un círculo interior. Especialmente si ese formato es generado por un framework en un círculo exterior.

graph LR
A["Frameworks & Drivers"] -->| Dependencia | B["Interface Adapters"]
B -->| Dependencia | C["Use Cases"]
C -->| Dependencia | D["Entities"]
style A fill:#f9f9f9,stroke:#333,stroke-width:2px
style B fill:#e6f7ff,stroke:#333,stroke-width:2px
style C fill:#fff0f6,stroke:#333,stroke-width:2px
style D fill:#f6ffed,stroke:#333,stroke-width:2px

Expresado matemáticamente, si definimos el índice de la capa como $L_i$, con $i=0$ siendo las entidades (capa más interna) e $i=3$ siendo los frameworks (capa más externa), si existe una dependencia de una capa $L_m$ a $L_n$, siempre debe cumplirse la siguiente desigualdad:

$$ m > n $$

Es decir, el vector de dependencia $\vec{D}$ siempre apunta hacia el centro.

5. Cruzando fronteras: El principio de inversión de dependencias (DIP)

Al intentar adherirse a la regla de dependencia, uno se enfrenta rápidamente a un gran problema. “¿Qué hacemos cuando el caso de uso necesita obtener datos de la base de datos?”

Si la capa de casos de uso (interior) llama directamente a la capa de adaptadores de interfaz (la implementación del Repository en el exterior), la dependencia apuntará hacia el exterior, lo cual es una violación a la regla de dependencia.

Lo que resuelve este problema es la “D” de los principios SOLID (Dependency Inversion Principle: Principio de inversión de dependencias).

Definición del Principio de inversión de dependencias (DIP)

Los módulos de alto nivel no deben depender de los módulos de bajo nivel. Ambos deben depender de abstracciones.
Las abstracciones no deben depender de los detalles. Los detalles deben depender de las abstracciones.

Para lograr esto, se define una interfaz (abstracción) en la capa de casos de uso, y la capa exterior (adaptadores de interfaz) implementa esa interfaz. La capa de casos de uso solo depende de la interfaz que definió ella misma, y no de la implementación específica externa.

classDiagram
class UseCaseInteractor {
- UserRepository repository
+ execute()
}
class UserRepository {
<<Interface>>
+ findById(id)
+ save(user)
}
class UserRepositoryImpl {
+ findById(id)
+ save(user)
}
UseCaseInteractor --> UserRepository : "Depends on (Depende de)"
UserRepositoryImpl ..|> UserRepository : "Implements (Implementa)"
note for UseCaseInteractor "Capa interior (Caso de uso)"
note for UserRepository "Capa interior (Caso de uso)"
note for UserRepositoryImpl "Capa exterior (Adaptadores de interfaz)"

En el diagrama anterior, el flujo de control en tiempo de ejecución (Control Flow) es UseCaseInteractor $\rightarrow$ UserRepositoryImpl. Sin embargo, la dependencia del código fuente (Source Code Dependency) es UserRepositoryImpl $\rightarrow$ UserRepository (hacia adentro). Al utilizar polimorfismo, pudimos dirigir la dependencia del código fuente en la dirección opuesta al flujo de control. Esta es la razón por la que se llama “inversión” de dependencias.

6. Ejemplo de implementación específica en TypeScript

Aquí mostraremos un ejemplo de implementación simple de Clean Architecture (función de registro de usuario) utilizando TypeScript.

6.1. Entidades (Entities)

Son las reglas de negocio más centrales.

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


// src/domain/entities/User.ts
export class User {
 constructor(
 public readonly id: string,
 public readonly name: string,
 public readonly email: string,
 public readonly createdAt: Date
 ) {}

 // Reglas de negocio específicas de la entidad (ej: verificación de longitud del nombre, etc.)
 public isValid(): boolean {
 return this.name.length >= 3 && this.email.includes('@');
 }
}

6.2. Casos de uso (Use Cases)

En la capa de casos de uso, definimos las estructuras de datos de entrada y salida (DTO) y la interfaz del repositorio para invertir las dependencias.

 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
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59


// src/application/repositories/UserRepository.ts
import { User } from '../../domain/entities/User';

// Interfaz definida por la capa de casos de uso
export interface UserRepository {
 findByEmail(email: string): Promise<User | null>;
 save(user: User): Promise<void>;
}

// src/application/usecases/RegisterUser/RegisterUserDTO.ts
export interface RegisterUserInputDTO {
 name: string;
 email: string;
}

export interface RegisterUserOutputDTO {
 id: string;
 name: string;
 email: string;
 createdAt: Date;
}

// src/application/usecases/RegisterUser/RegisterUserUseCase.ts
import { User } from '../../domain/entities/User';
import { UserRepository } from '../../repositories/UserRepository';
import { RegisterUserInputDTO, RegisterUserOutputDTO } from './RegisterUserDTO';

export class RegisterUserUseCase {
 // Depende de la abstracción (interfaz). No depende de la concreción.
 constructor(private readonly userRepository: UserRepository) {}

 public async execute(input: RegisterUserInputDTO): Promise<RegisterUserOutputDTO> {
 const existingUser = await this.userRepository.findByEmail(input.email);
 if (existingUser) {
 throw new Error('User already exists');
 }

 const newUser = new User(
 crypto.randomUUID(),
 input.name,
 input.email,
 new Date()
 );

 if (!newUser.isValid()) {
 throw new Error('Invalid user data');
 }

 // Llama al proceso de guardado en la BD externa, pero la dependencia apunta hacia adentro (interfaz)
 await this.userRepository.save(newUser);

 return {
 id: newUser.id,
 name: newUser.name,
 email: newUser.email,
 createdAt: newUser.createdAt
 };
 }
}

6.3. Adaptadores de interfaz (Interface Adapters)

Creamos el proceso de acceso concreto a la base de datos (Implementación del Repository) y el Controller que procesa la solicitud HTTP.

 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
31
32
33
34
35
36
37
38
39
40
41
42


// src/adapters/repositories/PostgresUserRepository.ts
import { UserRepository } from '../../application/repositories/UserRepository';
import { User } from '../../domain/entities/User';
// Se asume un cliente de base de datos que es la capa externa (Driver)
import { DatabaseClient } from '../../infrastructure/database/DatabaseClient';

export class PostgresUserRepository implements UserRepository {
 constructor(private readonly dbClient: DatabaseClient) {}

 public async findByEmail(email: string): Promise<User | null> {
 const record = await this.dbClient.query('SELECT * FROM users WHERE email = $1', [email]);
 if (!record) return null;
 return new User(record.id, record.name, record.email, record.created_at);
 }

 public async save(user: User): Promise<void> {
 await this.dbClient.query(
 'INSERT INTO users (id, name, email, created_at) VALUES ($1, $2, $3, $4)',
 [user.id, user.name, user.email, user.createdAt]
 );
 }
}

// src/adapters/controllers/UserController.ts
import { RegisterUserUseCase } from '../../application/usecases/RegisterUser/RegisterUserUseCase';

export class UserController {
 constructor(private readonly registerUserUseCase: RegisterUserUseCase) {}

 public async register(req: any, res: any): Promise<void> {
 try {
 const input = {
 name: req.body.name,
 email: req.body.email
 };
 const output = await this.registerUserUseCase.execute(input);
 res.status(201).json(output);
 } catch (error: any) {
 res.status(400).json({ message: error.message });
 }
 }
}

6.4. Componente principal (Inyección de dependencias: DI)

Al iniciar la aplicación, se construyen (enlazan) todas las dependencias. A esto se le llama Composition Root.

 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


// src/infrastructure/web/server.ts
import express from 'express';
import { DatabaseClient } from '../database/DatabaseClient';
import { PostgresUserRepository } from '../../adapters/repositories/PostgresUserRepository';
import { RegisterUserUseCase } from '../../application/usecases/RegisterUser/RegisterUserUseCase';
import { UserController } from '../../adapters/controllers/UserController';

const app = express();
app.use(express.json());

// 1. Inicialización de los drivers
const dbClient = new DatabaseClient(/* Información de conexión */);

// 2. Inicialización de los adaptadores (instanciar clases concretas)
const userRepository = new PostgresUserRepository(dbClient);

// 3. Inicialización de los casos de uso (inyectar concreción en la interfaz = DI)
const registerUserUseCase = new RegisterUserUseCase(userRepository);

// 4. Inicialización de los controladores
const userController = new UserController(registerUserUseCase);

// Enrutamiento
app.post('/users', (req, res) => userController.register(req, res));

app.listen(3000, () => {
 console.log('Server is running on port 3000');
});

De esta manera, el “script de inicio” más externo asume los detalles sucios (instanciación de clases concretas) y pasa solo interfaces limpias a las capas internas, de modo que la lógica de negocio queda completamente aislada del mundo exterior.

7. Consideraciones matemáticas sobre el acoplamiento y la cohesión

En la ingeniería de software, el acoplamiento (Coupling) y la cohesión (Cohesion) son métricas para evaluar la calidad de una arquitectura.

El acoplamiento $C$ representa la fuerza de la dependencia entre módulos. Si el módulo $A$ depende del módulo $B$, siendo $N_{dep}$ el número total de dependencias del sistema y $N_{mod}$ el número de módulos, una métrica que indica la complejidad se puede expresar de la siguiente manera:

$$ Complexity \propto \frac{N_{dep}}{N_{mod}} $$

En Clean Architecture, al aplicar DIP, las flechas de dependencia física se dirigen hacia la abstracción. La frecuencia de cambio (Inestabilidad: $I$) de la abstracción (interfaz) está diseñada para ser muy baja.

La inestabilidad $I$ se calcula mediante la siguiente fórmula (definición de Robert C. Martin):

$C_e$ (Efferent Coupling): Acoplamiento eferente (el número de clases de las que dependemos)
$C_a$ (Afferent Coupling): Acoplamiento aferente (el número de clases que dependen de nosotros)

$$ I = \frac{C_e}{C_e + C_a} $$

Si $I = 0$, el componente es completamente estable (no depende de nadie y otros dependen de él).
Si $I = 1$, el componente es completamente inestable (nadie depende de él y depende de otros).

La “capa de entidades” de Clean Architecture es $C_e = 0$ (no depende del exterior), por lo tanto, $I = 0$. Es decir, es la capa más estable. A la inversa, la “capa UI” o la “capa DB” tienen $C_a \approx 0$ y $C_e > 0$, por lo que $I \approx 1$, lo que las convierte en capas fácilmente modificables (capas inestables).

Un principio importante de arquitectura, el SDP (Stable Dependencies Principle: Principio de dependencias estables), establece que “las dependencias deben apuntar en la dirección de la estabilidad (componentes con $I$ menor)”. Los círculos concéntricos de Clean Architecture son exactamente una visualización de este SDP, diseñados de modo que las dependencias apunten desde el exterior ($I=1$) hacia el interior ($I=0$).

8. Estrategia de pruebas y Clean Architecture

Una de las mayores ventajas de Clean Architecture es la facilidad de prueba. Dado que las capas están separadas, se pueden escribir pruebas para cada capa de forma independiente.

8.1. Pruebas de entidades (Unit Test)

Dado que es pura lógica sin ninguna dependencia externa, no se necesita ni DB ni mocks. Es la prueba más rápida y segura de ejecutar.

8.2. Pruebas de casos de uso (Unit Test con Mocks)

Dado que todas las dependencias externas como los repositorios se definen como interfaces, solo es necesario inyectar (DI) mocks de prueba o implementaciones en memoria (Fakes) al momento de realizar la prueba. No es necesario levantar una base de datos real. Esto permite probar rápidamente las ramificaciones complejas y el manejo de excepciones de la lógica de negocio.

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


// Ejemplo de prueba de caso de uso (asumiendo Jest)
test('Lanza un error si se intenta registrar con un correo electrónico existente', async () => {
 // Creación de repositorio Fake
 const mockRepo: UserRepository = {
 findByEmail: async (email) => new User('1', 'Test', email, new Date()), // Devuelve un usuario existente
 save: async (user) => {}
 };

 const useCase = new RegisterUserUseCase(mockRepo);

 // Ejecución del caso de uso y aserción de error
 await expect(useCase.execute({ name: 'Bob', email: 'test@example.com' }))
 .rejects
 .toThrow('User already exists');
});

8.3. Pruebas de adaptadores (Integration Test)

La clase de implementación del repositorio se conectará realmente a la base de datos para probar que el SQL es correcto. La prueba del controlador verifica la parte que recibe la solicitud HTTP y devuelve el JSON. Aquí no se realiza una validación detallada de la lógica de negocio, sino que solo se confirma que la “conversión” y la “comunicación” son correctas.

9. Desventajas de Clean Architecture y cuándo adoptarla

Aunque parece ser la panacea, Clean Architecture no es una bala de plata. Existen las siguientes desventajas (trade-offs):

Aumento del costo de aprendizaje inicial y costo de desarrollo: El número de archivos e interfaces (abstracciones) aumenta significativamente. Hay mucho “código repetitivo (boilerplate)” como la reasignación de DTO.
Excesiva para proyectos pequeños (Overkill): Para prototipos creados en unos pocos días o herramientas de un solo uso en las que casi no ocurren cambios, adoptar esta arquitectura suele ser un costo innecesario. Tampoco es adecuada para API simples que solo realizan operaciones CRUD.

Cuándo adoptarla:

Productos que se espera mantener y operar durante un largo período de tiempo (varios años o más).
Sistemas con reglas de negocio complejas y cambios frecuentes de especificaciones.
Cuando se desea promover la división del trabajo (frontend, backend, infraestructura, etc.) en un equipo de desarrollo grande.
Cuando se desea modelar un dominio de negocio complejo combinándolo con el Diseño Dirigido por el Dominio (DDD: Domain-Driven Design).

10. Resumen

Clean Architecture es una filosofía de diseño para proteger el “núcleo” del sistema, es decir, las “reglas de negocio”, de los “detalles” como la UI, la base de datos o los frameworks.

En su núcleo se encuentran la regla de dependencia y el principio de inversión de dependencias (DIP). Al aplicar estos correctamente, el software se vuelve flexible a los cambios, fácil de probar y capaz de mantener su valor durante un largo período de tiempo.

Lo importante no es imitar ciegamente la estructura de directorios de Clean Architecture, sino entender la esencia de “por qué se divide de esa manera” y “hacia dónde apuntan las flechas de dependencia”, y aplicarla adecuadamente según la escala y complejidad del propio proyecto.

Referencia: “Clean Architecture: A Craftsman’s Guide to Software Structure and Design” por Robert C. Martin

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.