LQIP — Low Quality Image Placeholder — es la técnica que llena ese hueco: durante la espera muestro una versión diminuta y borrosa de la imagen, y cuando la real termina de descargar, sustituyo una por la otra con un cross-fade. Es lo que hace Medium desde hace años, y antes lo hizo Pinterest.

La técnica en sí está documentada en mil sitios. Lo que cuento aquí es cómo la implementé en Idenautas, que corre sobre Lume: el script Deno que genera los placeholders en build, cómo los incrusto en el HTML, y cómo encajo todo en _config.ts sin meter JavaScript de cliente más allá del onload del propio <img>.

La idea #

Tres decisiones que conviene fijar antes de escribir nada:

1. El placeholder se genera en build, no en runtime. El servidor (o el CDN, en mi caso Bunny) no tiene que hacer nada en cada visita. La consecuencia es que el placeholder viaja inline en el HTML como data:image/jpeg;base64,... y aparece sin una sola petición HTTP adicional.
2. El placeholder es una versión de 16 píxeles de ancho de la propia imagen, en JPG. A esa resolución el peso ronda los 300-500 bytes. Codificado en base64 son unos ~600 bytes por imagen — irrelevante en el HTML.
3. El cross-fade lo hace el navegador. El <img> lleva un onload que añade la clase .loaded a su contenedor, y el CSS hace el resto con opacity y transition. Cero JavaScript propio, cero IntersectionObserver, cero librerías.

El truco está en que las tres decisiones son interdependientes. Si genero el placeholder en runtime, no puedo incrustarlo. Si no es minúsculo, no puedo permitirme incrustarlo en cada <img>. Si no lo incrusto, necesito una segunda petición HTTP solo para el placeholder, y eso elimina la mitad de la ventaja.

El script: scripts/lqip.ts #

El script tiene tres responsabilidades: encontrar las imágenes que se usan en el sitio, descargar su versión de 16 píxeles del CDN, y guardar el resultado en un JSON cacheable.

Descubrir las imágenes referenciadas #

No quiero mantener una lista de imágenes a mano. El script camina src/ con @std/fs/walk y busca dos patrones en los archivos .md, .vto, .njk y .ts:

• Llamadas a los shortcodes {{ img("ruta") }} y {{ cardPicture("ruta") }}.
• La clave heroImage: en el frontmatter.

const SHORTCODE_RE =
  /(?:\{%[-\s]*|\{\{[-\s]*(?:await\s+)?)(?:img|cardPicture)\s*\(?\s*["']([^"']+)["']/g;
const HERO_RE = /^heroImage:\s*(.+)$/m;

async function findImagePaths(): Promise<string[]> {
  const paths = new Set<string>();
  for await (
    const entry of walk(SRC_DIR, {
      exts: [".md", ".vto", ".njk", ".ts"],
      skip: [/node_modules/, /_data\/lqip\.json$/],
    })
  ) {
    if (!entry.isFile) continue;
    const content = await Deno.readTextFile(entry.path);
    let m: RegExpExecArray | null;
    SHORTCODE_RE.lastIndex = 0;
    while ((m = SHORTCODE_RE.exec(content)) !== null) paths.add(m[1]);
    const hero = content.match(HERO_RE);
    if (hero) paths.add(hero[1].trim().replace(/^["']|["']$/g, ""));
  }
  return [...paths];
}

El regex de los shortcodes acepta tanto la sintaxis Nunjucks heredada ({% img "..." %}) como la nueva de Vento ({{ img("...") }}). Migrar de una a otra es trabajo que hago a fuego lento, así que el script tiene que entender ambas durante el periodo de transición.

Es una solución imperfecta — un parser real entendería el código sin riesgo de falsos positivos —, pero a la práctica el regex acierta en el 100% de los casos del sitio. Si una imagen se referencia desde un layout o un sitio menos estándar, basta con añadir su patrón al regex.

Descargar los placeholders del CDN #

Las imágenes de Idenautas viven en Bunny Storage y el build no las regenera: las versiones a 480px, 800px, 1200px, 1920px y 16px (esta última, mi placeholder) ya están subidas con sufijo en el nombre. La ruta de cada placeholder es predecible:

function imgBase(imgPath: string): string {
  const i = imgPath.lastIndexOf(".");
  return i >= 0 ? imgPath.slice(0, i) : imgPath;
}

// imgBase("portada.jpg") + "-16.jpg" → "portada-16.jpg"

Para cada imagen, descargo ${CDN}${base}-16.jpg y la convierto a data URI:

async function fetchBase64(url: string): Promise<string> {
  const res = await fetch(url);
  if (!res.ok) throw new Error(`HTTP ${res.status}`);
  const type = res.headers.get("content-type") ?? "image/jpeg";
  const bytes = new Uint8Array(await res.arrayBuffer());
  return `data:${type};base64,${encodeBase64(bytes)}`;
}

encodeBase64 viene de jsr:@std/encoding/base64. Es una primitiva de la librería estándar de Deno; no añado dependencias.

El cache: src/_data/lqip.json #

El detalle que marca la diferencia entre un script aceptable y uno usable a diario es el cache. Sin cache, cada npm run publicar haría tantas peticiones HTTP como imágenes hay en el sitio. Con cache, solo se descargan las nuevas:

let existing: Record<string, string> = {};
try {
  existing = JSON.parse(await Deno.readTextFile(OUTPUT));
} catch {
  // primera ejecución, no hay cache
}

const lqip: Record<string, string> = {};
let downloaded = 0;
for (const img of images) {
  if (existing[img]) {
    lqip[img] = existing[img];
    continue;
  }
  const url = `${CDN}${imgBase(img)}-16.jpg`;
  try {
    lqip[img] = await fetchBase64(url);
    downloaded++;
  } catch (err) {
    console.error(`  [lqip] ✗ ${img}: ${(err as Error).message}`);
  }
}

El JSON resultante es un mapa ruta-original → data URI. El script lo guarda en src/_data/lqip.json solo si el contenido ha cambiado — escribir el archivo en cada build invalidaría el watcher de Lume sin necesidad y dispararía recargas en desarrollo:

const prevJson = JSON.stringify(existing, null, 2);
const nextJson = JSON.stringify(lqip, null, 2);
if (prevJson !== nextJson) {
  await Deno.writeTextFile(OUTPUT, nextJson);
}

Otra ventaja del JSON cacheado: las imágenes que ya no se referencian desde ningún lado se eliminan del mapa automáticamente, porque el script reconstruye el objeto desde cero a partir del escaneo. No necesita una lógica de garbage collection aparte.

Integración con Lume #

El script expone una función generateLQIP() para poder llamarse desde _config.ts. La conexión es mínima:

import { generateLQIP } from "./scripts/lqip.ts";

let lqipData: Record<string, string> = {};
try {
  lqipData = JSON.parse(await Deno.readTextFile("./src/_data/lqip.json"));
} catch {
  // primer build, todavía no hay cache
}

site.addEventListener("beforeBuild", async () => {
  lqipData = await generateLQIP({ quiet: false });
});

Dos detalles aquí:

• Carga del cache al arrancar. El JSON.parse inicial existe para que los servidores de desarrollo en frío arranquen con el mapa ya rellenado, sin esperar a la primera regeneración.
• beforeBuild y no beforeUpdate. En desarrollo, mientras edito un post, no quiero que cada cambio dispare una conexión al CDN. La regeneración solo ocurre en builds completos.

Con lqipData en memoria, los shortcodes que generan el HTML pueden consultarlo:

site.data("img", function (imgPath: string, alt: string, ...) {
  const lqip = lqipData[imgPath] || imgUrl(imgPath, 16, "jpg");
  return `<div class="lqip-wrap" style="background-image:url('${lqip}')">
    <picture>...</picture>
  </div>`;
});

El fallback || imgUrl(imgPath, 16, "jpg") cubre el caso en el que añado una imagen al post pero todavía no he regenerado el cache. En vez de quedarme sin placeholder, sirvo la URL del placeholder directamente desde el CDN — funciona, solo es marginalmente menos eficiente porque el navegador hace una petición HTTP extra mientras llega la imagen real.

El HTML resultante #

Para cada imagen, el shortcode produce este HTML:

<div class="lqip-wrap"
     style="background-image:url('data:image/jpeg;base64,/9j/4AAQ...')">
  <picture>
    <source type="image/avif" srcset="foto-480.avif 480w, ..." sizes="...">
    <source type="image/webp" srcset="foto-480.webp 480w, ..." sizes="...">
    <img src="foto-1200.jpg" srcset="foto-480.jpg 480w, ..."
         sizes="..." alt="..." loading="lazy"
         width="1200" height="800"
         onload="this.parentNode.classList.add('loaded')">
  </picture>
</div>

Tres piezas:

• El wrapper lleva el placeholder como background-image. Aparece instantáneo: ya viaja en el HTML.
• El <picture> sirve la imagen definitiva con srcset para densidades y formatos modernos. Eso es ortogonal al LQIP — es la técnica de imágenes responsive, aplicada a la imagen real.
• El onload añade .loaded al wrapper cuando el <img> termina de descargar, lo que dispara el cross-fade.

El CSS: cross-fade sin JavaScript #

.lqip-wrap {
  position: relative;
  background-size: cover;
  background-position: center;
  background-repeat: no-repeat;
  overflow: hidden;
  width: 100%;
  height: 100%;
}

.lqip-wrap > img {
  display: block;
  width: 100%;
  height: 100%;
  object-fit: cover;
  opacity: 0;
  transition: opacity 0.4s ease;
}

.lqip-wrap.loaded > img {
  opacity: 1;
}

El placeholder es el fondo del wrapper. El <img> empieza con opacity: 0, ocupando el mismo espacio. Cuando dispara su onload, el wrapper recibe .loaded, el <img> pasa a opacity: 1, y la transición de 0.4s hace el cross-fade.

object-fit: cover se asegura de que la imagen real cubra el wrapper sin deformarse, lo que importa porque el width y height del <img> definen la proporción pero el contenedor real lo controla CSS.

Por qué 16 píxeles y por qué JPG #

Probé valores entre 8 y 32 píxeles. Por debajo de 16 el placeholder se nota pixelado en la transición; por encima, el peso crece más rápido que la mejora visual. El JPG a 16px y calidad por defecto pesa unos 350 bytes — aceptable.

Sobre el formato: aquí JPG gana a WebP y AVIF. A 16 píxeles las cabeceras de WebP/AVIF representan un porcentaje ridículamente alto del archivo, y la ganancia de compresión sobre JPG es marginal. Además, los placeholders viajan en el HTML, donde el ahorro de bytes brutos sí cuenta — y JPG genera buffers pequeños y predecibles. He medido los tres formatos: a 16px, JPG es el más ligero en mi caso.

Por qué no BlurHash, Plaiceholder o transform_images #

Existen alternativas conocidas:

• BlurHash codifica el placeholder como un string ASCII de unos 30 caracteres y lo reconstruye con JavaScript en el cliente. El string es más compacto que una data URI base64, sí — pero requiere ~3 KB de JavaScript en cada página y un canvas para reconstruir el placeholder. Para una web sin frameworks no compensa.
• Plaiceholder es una librería de Node.js que genera LQIPs (entre otros formatos: blurhash, color dominante, SVG). En Idenautas no me hace falta el paso de generar la imagen pequeña — Bunny ya tiene la versión de 16px subida —, y prefiero un script de 100 líneas que entiendo entero a una dependencia más.
• El plugin oficial transform_images procesa imágenes con Sharp dentro del propio build de Lume. No genera placeholders como tales, pero sí puede producir la variante de 16 px y leerla luego para incrustarla en base64 — todo en una sola pasada de Lume, sin un script aparte como el mío. Si dejas que Lume gestione también tus variantes responsive con transform_images o el plugin picture, esa ruta es más coherente. En Idenautas las variantes están subidas a Bunny Storage por un pipeline anterior a Lume, así que el script de LQIP solo se ocupa del placeholder; si arrancase el proyecto desde cero hoy, probablemente movería todo el flujo de imágenes a transform_images y haría el LQIP ahí mismo.

Si fuera un proyecto donde las imágenes solo viven a tamaño completo y necesito regenerarlas, transform_images (o sharp directamente) sería la opción razonable. Mi pipeline ya produce las variantes responsive con un script aparte, así que añadir -16.jpg a esa lista era trivial.

Lo que cuesta y lo que aporta #

El coste, en bytes incrustados, es de unos 600 bytes por imagen en el HTML. En una página con cinco imágenes son 3 KB extra antes de cualquier compresión gzip — y gzip los reduce todavía más, porque las cabeceras JPG son repetitivas entre placeholders. Es un coste muy bajo para evitar huecos vacíos en la primera pintada.

Lo que aporta es perceptual: la página se siente más rápida sin serlo necesariamente. Las imágenes ya están en su sitio cuando entras, solo enfocan. El usuario rara vez identifica conscientemente la técnica, pero nota la diferencia cuando la quitas.

Es una de esas inversiones de unas pocas horas que se quedan trabajando en silencio durante años. Y en Lume, con un script Deno y un evento beforeBuild, encaja sin necesidad de plugins ni configuración adicional.

Pero hay trampas. No errores evidentes que te bloquean con un mensaje rojo — sino comportamientos sutiles que hacen que las páginas se generen vacías, que los posts pierdan sus categorías, o que el CSS deje de llegar donde tiene que llegar. Todo compila, todo parece funcionar, pero el resultado no es el que esperas.

Estos son los tres problemas reales que encontré migrando paigar.es de Eleventy a Lume.

1. Los includes dentro de bucles no reciben variables #

En Eleventy con Nunjucks, esto funciona perfectamente:

{% for post in collections.bitacora %}
  {% include "partials/postcard.njk" %}
{% endfor %}

El partial postcard.njk accede a la variable post del bucle padre sin problemas. Es el comportamiento esperado de Nunjucks: los includes heredan el scope del template que los llama.

En Lume, el mismo patrón genera HTML vacío. Sin errores, sin warnings — simplemente no renderiza nada dentro del bucle. La página se construye, el div contenedor aparece, pero los postcards no están.

Lo desconcertante es que search.pages() sí devuelve resultados. Puedes verificarlo con un debug inline:

{% for post in search.pages("bitacora", "date=desc") %}
  <p>{{ post.title }}</p>  {# Esto SÍ funciona #}
  {% include "partials/postcard.njk" %}  {# Esto NO #}
{% endfor %}

El título se muestra, pero el include produce una cadena vacía. El partial no puede ver post.

Por qué pasa esto #

Óscar Otero, el creador de Lume, me explicó la causa técnica. Nunjucks es por defecto un motor síncrono, pero Lume es asíncrono por naturaleza, así que utiliza Nunjucks en modo asíncrono. En ese modo, algunas etiquetas no funcionan cuando contienen código asíncrono (como un include) y hay que usar otras: asyncEach en vez de for, e ifAsync en vez de if. Esta es precisamente una de las razones por las que Óscar decidió crear Vento.

La solución en Nunjucks: macros #

La alternativa que funciona en Lume con Nunjucks son los macros. En lugar de un partial que depende del scope del padre, defines una función que recibe los datos como argumentos:

{# partials/postcard.njk #}
{% macro renderPostcard(post, postHeading) %}
<article class="postcard">
  <h3>{{ post.title }}</h3>
  ...
</article>
{% endmacro %}

Y en el template que lo usa:

{% from "partials/postcard.njk" import renderPostcard %}

{% for post in search.pages("bitacora", "date=desc") %}
  {{ renderPostcard(post, "h2") }}
{% endfor %}

La solución definitiva: Vento #

Al migrar de Nunjucks a Vento (el motor nativo de Lume), el problema desaparece porque Vento permite pasar datos explícitamente al include:

{{ for post of search.pages("bitacora", "date=desc") }}
  {{ include "partials/postcard.vto" { post, postHeading: "h2" } }}
{{ /for }}

Esa sintaxis { post, postHeading: "h2" } es un objeto de datos que el include recibe. No hay ambigüedad sobre qué variables están disponibles. Es más explícito y más fiable que depender de la herencia de scope.

2. La cascada de datos no fusiona arrays #

En Eleventy, puedes definir valores por defecto para todos los archivos de un directorio con un fichero posts.11tydata.js:

// bitacora/posts/posts.11tydata.js
module.exports = {
  tags: ["bitacora"],
  layout: "layouts/post.njk",
};

Si un post tiene sus propios tags en el frontmatter (tags: [css, técnicas]), Eleventy los fusiona con los del directorio. El post acaba con ["bitacora", "css", "técnicas"]. Esto es fundamental para que collections.bitacora incluya todos los posts de la sección.

En Lume, el equivalente es un archivo _data.yml:

# bitacora/_data.yml
tags:
  - bitacora
layout: layouts/post.vto

Pero Lume reemplaza los arrays en lugar de fusionarlos. Un post con tags: [css, técnicas] pierde el tag bitacora del directorio. El resultado: search.pages("bitacora") devuelve cero resultados.

El primer intento: mergedKeys #

Lume tiene una opción mergedKeys que permite fusionar arrays:

mergedKeys:
  tags: array
tags:
  - bitacora
layout: layouts/post.vto

Funciona — pero con un efecto secundario. El _data.yml aplica a todos los archivos del directorio, incluyendo index.vto. El índice de la sección acaba con el tag bitacora, apareciendo en los resultados de búsqueda como si fuera un post más. El feed RSS incluye la página de índice. Las postcards muestran la sección como si fuera un artículo.

La primera solución: un preprocessor #

Mi primera solución fue un preprocessor en _config.ts que solo inyecta el tag de sección en archivos Markdown, ignorando las plantillas .vto:

site.preprocess([".md"], (pages) => {
  for (const page of pages) {
    const path = page.src.path;
    if (path.startsWith("/bitacora/")) {
      page.data.tags = [...(page.data.tags || []), "bitacora"];
    } else if (path.startsWith("/reflexiones/")) {
      page.data.tags = [...(page.data.tags || []), "reflexiones"];
    }
  }
});

El filtro [".md"] es la clave. Solo procesa archivos Markdown, así que los index.vto de cada sección no reciben el tag. Es más explícito que la cascada de datos y no tiene efectos colaterales. Funcionaba bien, pero seguía usando tags para algo que no es realmente una etiqueta.

La solución definitiva: separar sección de tags #

Óscar Otero, el creador de Lume, me comentó que tags debería tener mergedKeys activado por defecto, y que el comportamiento que encontré podría ser un bug de Lume o un error en mi implementación — era mi primera vez con Lume, así que no descarto haberme dejado algo por el camino. Pero lo más interesante fue su propuesta: en vez de usar tags para agrupar por sección, usar una variable propia como type.

La idea es sencilla. En el _data.yml de cada sección defines el tipo:

# bitacora/_data.yml
layout: layouts/post.vto
type: bitacora

Y en el index.vto de la sección lo anulas para que el índice no aparezca en las búsquedas:

---
type:
---

Las búsquedas pasan de search.pages("bitacora") a search.pages("type=bitacora"). Los tags quedan libres para lo que realmente son — etiquetas de contenido como css, técnicas o eleventy — sin mezclarse con la agrupación por sección.

Este enfoque es más limpio que el preprocessor: no necesita código en _config.ts, la intención queda clara en los datos, y tags deja de hacer doble función. Es el que uso actualmente.

3. El bundling de CSS y JS no existe #

Eleventy tiene un plugin de bundling que permite incluir CSS y JavaScript inline directamente desde las plantillas:

{# base.njk — recoge CSS de todos los templates #}
{% css %}{% include "public/css/reset.css" %}{% endcss %}
{% css %}{% include "public/css/tokens.css" %}{% endcss %}
{% css %}{% include "public/css/components.css" %}{% endcss %}

<style>
  {% getBundle "css" %}
</style>

El mecanismo es potente: cada plantilla puede añadir su propio CSS con {% css %}...{% endcss %}, y todo se concatena en un solo <style> en el <head>. Los posts añaden estilos de navegación, la home añade estilos del hero, la 404 añade estilos del terminal — y el usuario solo descarga el CSS que la página necesita.

Lume no tiene nada parecido. No hay {% css %}, no hay {% getBundle %}, no hay concatenación de CSS desde plantillas.

La solución: postcss + inline + pageCss #

La migración requiere tres pasos:

Primero, extraer todos los bloques {% css %}...{% endcss %} de las plantillas a archivos CSS individuales: page-hero.css, page-post.css, page-404.css, page-sobre.css, etc. Cada archivo contiene exactamente el CSS que antes vivía dentro de su plantilla.

Segundo, crear un main.css que importe solo el CSS base — el que todas las páginas necesitan:

/* main.css */
@import "./public/css/reset.css";
@import "./public/css/tokens.css";
@import "./public/css/theme.css";
@import "./public/fonts/fonts.css";
@import "./public/css/layout.css";
@import "./public/css/components.css";
@import "./public/css/code.css";

El plugin postcss resuelve los @import y concatena todo. El plugin inline sustituye el <link> por un <style> con el contenido incrustado:

<link rel="stylesheet" href="/css_main.css" inline>

Tercero, cada plantilla declara en su frontmatter qué CSS extra necesita con un array pageCss:

---
layout: layouts/base.vto
title: "Paigar — Juanjo Marcos"
pageCss:
  - /css/page-hero.css
---

El layout base recorre ese array y añade cada archivo como un <link inline>:

{{ for css of pageCss }}
<link rel="stylesheet" href="{{ css }}" inline>
{{ /for }}

El resultado es que la homepage solo carga el CSS del hero, un post solo carga el CSS de posts, y la 404 solo carga el suyo. Exactamente el mismo comportamiento que el getBundle de Eleventy — cada página recibe solo el CSS que necesita, todo inline, cero peticiones HTTP.

Para JavaScript, la misma idea. El atributo inline funciona también con <script>:

<script src="/js/theme-toggle.js" inline></script>
<script src="/js/externallinks.js" inline></script>
<script src="/js/reveal.js" inline></script>
<script src="/js/nav-mobile.js" inline></script>

Lume lee cada archivo y lo incrusta directamente en el HTML. Cero peticiones externas para JS.

¿Mereció la pena? #

Sí. Los tres problemas se resolvieron en el mismo día, y el resultado es un proyecto más limpio:

• Deno en lugar de Node — sin node_modules de 200 MB, sin package.json, sin package-lock.json
• Vento en lugar de Nunjucks — sintaxis más clara, datos explícitos en includes, expresiones JavaScript reales
• TypeScript nativo — la configuración, los generadores y el script de publicación son .ts, con tipado sin transpilación
• Build en ~2 segundos — 159 archivos generados, incluyendo conversión SVG→PNG de las imágenes Open Graph

El código fuente pasó de depender de 10 paquetes npm a cero dependencias de Node.js. Todo corre sobre Deno y las importaciones son URLs directas o paquetes de JSR. Para un sitio que predica la simplicidad, es coherente.

Crear esas imágenes a mano para cada post es tedioso. Y conectar un servicio externo para algo tan simple es sobredimensionar el problema. La solución está en el propio build: generar las imágenes durante la compilación, sin servicios externos.

La idea original la encontré en el artículo de Bernard Nijenhuis para Eleventy, y la he adaptado a Lume con las herramientas que Deno ofrece.

La estrategia #

El truco es usar SVG como plantilla intermedia. SVG es código, así que puedes generarlo programáticamente. Después, una librería WASM convierte ese SVG a PNG durante el build.

El flujo completo:

1. Un generador TypeScript (og-images.page.ts) produce un archivo SVG por cada post
2. El SVG contiene el título del post, la sección y el branding del sitio
3. Después del build, un evento afterBuild en _config.ts convierte todos los SVG a PNG con resvg
4. Las meta tags og:image apuntan a las imágenes PNG generadas

Todo ocurre en el build. No hay servicios externos, no hay APIs, no hay imágenes que mantener a mano.

El generador: og-images.page.ts #

En Lume, los archivos .page.ts son generadores: exportan una función que puede producir múltiples páginas. Cada yield genera un archivo. Es el equivalente a la paginación de otros SSG, pero con TypeScript puro.

El generador empieza recopilando todos los posts de ambas secciones con search.pages():

export default function* ({ search }: Lume.Data) {
	const posts = [...search.pages("bitacora"), ...search.pages("reflexiones")];

	for (const post of posts) {
		const title = post.title as string;
		const tags = (post.tags || []) as string[];
		// ...
	}
}

Para cada post hay que resolver tres cosas: partir el título en líneas, determinar la sección, y extraer el slug para el nombre de archivo.

Partir el título en líneas #

SVG no sabe partir texto automáticamente. Si el título tiene 80 caracteres, se sale del canvas. La solución es dividir el texto en líneas de máximo 36 caracteres, cortando siempre por espacios:

const parts = title.split(" ");
const titleLines: string[] = parts.reduce((prev: string[], current: string) => {
	if (!prev.length) return [current];
	const lastLine = prev[prev.length - 1];
	if (lastLine.length + 1 + current.length > 36) {
		return [...prev, current];
	}
	prev[prev.length - 1] = lastLine + " " + current;
	return prev;
}, []);

El 36 depende del tamaño de fuente y del ancho del canvas. Con font-size="48" y un canvas de 1200px, 36 caracteres encajan bien.

Posición vertical del título #

La posición Y del título se ajusta según el número de líneas, para que quede centrado visualmente en la imagen:

const lineCount = titleLines.length;
let titleY: number;
if (lineCount === 1) titleY = 310;
else if (lineCount === 2) titleY = 280;
else if (lineCount === 3) titleY = 240;
else titleY = 200;

Sección y slug #

La sección se determina a partir de los tags del post. El slug se extrae de la URL — es el último segmento:

const seccion = tags.includes("bitacora") ? "BITACORA" : "REFLEXIONES";

const urlParts = (post.url as string).split("/").filter(Boolean);
const slug = urlParts[urlParts.length - 1];

El SVG #

Con todos los datos preparados, se construye el SVG como un template literal. Las líneas del título se generan como <tspan> con la coordenada Y incrementada en 62px por línea. El texto se escapa con una función auxiliar escapeXml para evitar que caracteres como & o < rompan el XML:

const tspans = titleLines
	.map(
		(line: string, i: number) =>
			`    <tspan x="80" y="${titleY + i * 62}">${escapeXml(line)}</tspan>`,
	)
	.join("\n");

El diseño es intencionalmente sencillo: fondo oscuro (#111118), una barra naranja lateral (#f86624) como marca visual, el nombre de la sección en naranja, el título en claro, y el branding del sitio abajo. Todo con <rect>, <text>, <line> y <circle>.

Finalmente, el generador produce el archivo:

yield {
  url: `/og-images/${slug}.svg`,
  content: svg,
};

Por qué PNG y no JPEG o WebP #

La elección del formato no es casual. Estas imágenes son texto sobre fondos planos, sin fotografías ni degradados complejos. PNG comprime ese tipo de contenido muy bien y mantiene los bordes del texto nítidos. JPEG introduciría artefactos de compresión visibles en las letras y líneas rectas — necesitarías calidad alta para disimularlos, y el archivo acabaría pesando lo mismo o más.

WebP sería ideal por tamaño, pero los crawlers de redes sociales (Facebook, LinkedIn, WhatsApp) históricamente han tenido problemas con WebP en og:image. Facebook recomienda oficialmente PNG o JPEG.

En la práctica, las imágenes generadas pesan entre 22 y 38 KB. No merece la pena buscar más optimización.

La conversión: SVG a PNG con resvg-wasm #

Los SVG no sirven directamente como imágenes Open Graph — los crawlers de redes sociales esperan formatos rasterizados. Aquí es donde la migración a Lume trajo un reto interesante.

En Eleventy, la conversión era trivial: @11ty/eleventy-img usa Sharp, que es una librería nativa de Node.js con bindings precompilados. En Deno, Sharp no funciona directamente. Y la mayoría de paquetes npm de conversión SVG→PNG están o deprecados, o usan binarios nativos incompatibles con Deno, o tienen APIs inestables.

La solución fue resvg-wasm, una versión compilada a WebAssembly del renderizador SVG de Mozilla. Funciona en cualquier plataforma sin binarios nativos.

La conversión se ejecuta en un evento afterBuild de Lume, cuando los SVG ya están generados en _site/og-images/:

import { render as renderSvgToPng } from "https://deno.land/x/resvg_wasm@0.2.0/mod.ts";

site.addEventListener("afterBuild", async () => {
	const ogDir = site.dest() + "/og-images";

	try {
		const entries = [...Deno.readDirSync(ogDir)];
		const svgFiles = entries.filter((e) => e.name.endsWith(".svg"));

		if (svgFiles.length === 0) return;

		let converted = 0;
		for (const entry of svgFiles) {
			const svgPath = `${ogDir}/${entry.name}`;
			const pngPath = svgPath.replace(".svg", ".png");
			const svgContent = await Deno.readTextFile(svgPath);

			const pngBuffer = await renderSvgToPng(svgContent);
			await Deno.writeFile(pngPath, pngBuffer);
			await Deno.remove(svgPath);
			converted++;
		}

		console.log(`[og-images] ${converted} SVG convertidos a PNG`);
	} catch (err) {
		if (!(err instanceof Deno.errors.NotFound)) {
			console.error("[og-images] Error:", err);
		}
	}
});

La API es mínima — una sola función render() que recibe SVG como string y devuelve PNG como Uint8Array. Por cada SVG, genera el PNG y elimina el original.

Las meta tags #

Solo queda apuntar las meta tags a las imágenes generadas. En el layout base:

{{ if tags && (tags.includes("bitacora") || tags.includes("reflexiones")) }}
<meta
	property="og:image"
	content="{{ metadata.url }}/og-images/{{ page.src.slug }}.png" />
{{ else }}
<meta property="og:image" content="{{ metadata.url }}/og-images/default.png" />
{{ /if }}
<meta property="og:image:width" content="1200" />
<meta property="og:image:height" content="630" />
<meta name="twitter:card" content="summary_large_image" />

Los posts obtienen su imagen específica. El resto de páginas usan una imagen genérica con el nombre y la descripción del sitio. El valor summary_large_image en twitter:card hace que la imagen se muestre en grande al compartir en X.

Sobre las fuentes #

Un detalle importante: el renderizador SVG usa las fuentes del sistema donde se ejecuta el build. Si usas una tipografía personalizada que no está instalada en la máquina, el resultado será diferente. En mi caso uso Arial como fuente para las imágenes OG, que está disponible en prácticamente cualquier sistema.

El archivo completo #

Para referencia, este es el og-images.page.ts completo tal como funciona en producción:

export default function* ({ search }: Lume.Data) {
	const posts = [...search.pages("bitacora"), ...search.pages("reflexiones")];

	for (const post of posts) {
		const title = post.title as string;
		const tags = (post.tags || []) as string[];

		// Partir el título en líneas de máximo 36 caracteres
		const parts = title.split(" ");
		const titleLines: string[] = parts.reduce(
			(prev: string[], current: string) => {
				if (!prev.length) return [current];
				const lastLine = prev[prev.length - 1];
				if (lastLine.length + 1 + current.length > 36) {
					return [...prev, current];
				}
				prev[prev.length - 1] = lastLine + " " + current;
				return prev;
			},
			[],
		);

		const lineCount = titleLines.length;
		let titleY: number;
		if (lineCount === 1) titleY = 310;
		else if (lineCount === 2) titleY = 280;
		else if (lineCount === 3) titleY = 240;
		else titleY = 200;

		const seccion = tags.includes("bitacora") ? "BITACORA" : "REFLEXIONES";

		// Extraer el slug de la URL del post
		const urlParts = (post.url as string).split("/").filter(Boolean);
		const slug = urlParts[urlParts.length - 1];

		const tspans = titleLines
			.map(
				(line: string, i: number) =>
					`    <tspan x="80" y="${titleY + i * 62}">${escapeXml(line)}</tspan>`,
			)
			.join("\n");

		const svg = `<?xml version="1.0" encoding="UTF-8" standalone="no"?>
<svg width="1200" height="630" viewBox="0 0 1200 630" xmlns="http://www.w3.org/2000/svg">

  <!-- Fondo -->
  <rect width="1200" height="630" fill="#111118"/>

  <!-- Barra naranja lateral -->
  <rect x="0" y="0" width="8" height="630" fill="#f86624"/>

  <!-- Seccion -->
  <text x="80" y="${titleY - 60}" font-family="Arial, Helvetica, sans-serif" font-size="22" fill="#f86624" letter-spacing="3">${seccion}</text>

  <!-- Titulo -->
  <text font-family="Arial, Helvetica, sans-serif" font-size="48" font-weight="bold" fill="#dcdcd4">
${tspans}
  </text>

  <!-- Linea separadora -->
  <line x1="80" y1="530" x2="1120" y2="530" stroke="#2a2a3a" stroke-width="1"/>

  <!-- Branding -->
  <text x="80" y="575" font-family="Arial, Helvetica, sans-serif" font-size="24" fill="#8e8e86">paigar.es</text>

  <!-- Punto naranja -->
  <circle cx="1120" cy="568" r="6" fill="#f86624"/>

</svg>`;

		yield {
			url: `/og-images/${slug}.svg`,
			content: svg,
		};
	}
}

function escapeXml(str: string): string {
	return str
		.replace(/&/g, "&amp;")
		.replace(/</g, "&lt;")
		.replace(/>/g, "&gt;")
		.replace(/"/g, "&quot;")
		.replace(/'/g, "&apos;");
}

La alternativa oficial: el plugin og_images #

Lume tiene un plugin oficial de imágenes Open Graph que resuelve el mismo problema. Usa Satori (de Vercel) para convertir componentes JSX en SVG, y Sharp para rasterizar a PNG. Los layouts se definen como funciones JSX con estilos inline, y se asignan desde el frontmatter con openGraphLayout.

Es una opción válida si prefieres un enfoque más integrado con el ecosistema de Lume. En mi caso elegí la implementación manual por varias razones:

• Control total del SVG — puedo usar cualquier elemento SVG (<line>, <circle>, <tspan>) sin las limitaciones de Satori, que solo soporta un subconjunto de CSS basado en flexbox.
• Sin Sharp — Sharp es una librería nativa de Node.js que no funciona directamente en Deno. Con resvg-wasm no hay binarios nativos ni dependencias de plataforma.
• Menos dependencias — el generador es un único archivo TypeScript de 89 líneas, sin configuración JSX ni paquetes adicionales.

El plugin oficial es más cómodo si no necesitas un diseño muy específico o si ya usas JSX en tu proyecto. Pero para un sitio que busca minimizar dependencias, la solución manual encaja mejor.

El resultado #

Con esta solución, cada vez que hago build se generan automáticamente las imágenes de vista previa para todos los posts. Sin intervención manual, sin servicios externos, sin imágenes que versionar en el repositorio. Solo código que genera código que genera imágenes.

La técnica original es para Eleventy con Sharp. Mi adaptación a Lume usa generadores .page.ts para la creación de SVGs y resvg-wasm para la conversión a PNG, eliminando la dependencia de Node.js.

Esta versión 3.x de paigar.es nació con Eleventy y funcionaba bien. No había una razón urgente para cambiar. Pero las razones de fondo — independencia del proyecto, afinidad con Deno, curiosidad técnica — pesaban lo suficiente como para justificar el experimento. Y siendo un sitio personal, me podía permitir romper cosas.

Qué se gana con Lume #

Deno en lugar de Node. Adiós a package.json, package-lock.json y la carpeta node_modules de 200 MB. Las dependencias se resuelven por URL o desde JSR. El proyecto entero se gestiona con deno.json y un solo _config.ts.

TypeScript nativo. La configuración, los generadores de páginas y el script de publicación son .ts. Sin transpilación, sin configuración extra, con tipado real.

Vento en lugar de Nunjucks. El motor de plantillas nativo de Lume es más limpio: usa {{ }} para todo — variables, condicionales, bucles — con expresiones JavaScript reales en lugar de un lenguaje propio. Y los includes pasan datos de forma explícita, lo que evita problemas de scope que tenía con Nunjucks.

Plugins integrados. Feed RSS, sitemap, minificación HTML, PostCSS, inlining de assets — todo con una línea en la configuración. En Eleventy necesitaba paquetes npm separados para cada cosa.

Lo que cambió #

De Nunjucks a Vento #

El cambio más visible. Donde antes escribía:

{% for post in collections.bitacora %} {% include "partials/postcard.njk" %} {%
endfor %}

Ahora escribo:

{{ for post of search.pages("bitacora", "date=desc") }} {{ include
"partials/postcard.vto" { post } }} {{ /for }}

search.pages() sustituye a las colecciones de Eleventy. Es más potente — puedes filtrar por tags, ordenar, paginar — y la sintaxis es JavaScript estándar.

De colecciones a search #

En Eleventy, las colecciones se alimentaban de los tags del frontmatter y de la cascada de datos (posts.11tydata.js). En Lume, uso un preprocessor que inyecta el tag de sección solo a los archivos Markdown:

site.preprocess([".md"], (pages) => {
	for (const page of pages) {
		if (page.src.path.startsWith("/bitacora/")) {
			page.data.tags = [...(page.data.tags || []), "bitacora"];
		}
	}
});

Más explícito, sin efectos colaterales, y sin depender de una cascada de datos que puede sorprenderte.

De bundling a postcss + inline #

Eleventy tiene un plugin de bundling que concatena CSS y JS desde las plantillas e inyecta todo inline. Lume no tiene equivalente directo, pero la combinación de los plugins postcss e inline consigue el mismo resultado:

<link rel="stylesheet" href="/css_main.css" inline />

PostCSS resuelve los @import y concatena. El plugin inline sustituye el <link> por un <style> con el contenido. Cada página puede declarar CSS adicional en su frontmatter con pageCss, así que solo carga lo que necesita — igual que antes.

De Sharp a resvg-wasm #

Las imágenes Open Graph se generaban con @11ty/eleventy-img (que usa Sharp internamente). Sharp no funciona en Deno, así que la conversión SVG→PNG ahora usa resvg-wasm, una versión WebAssembly del renderizador SVG de Mozilla. Funciona en cualquier plataforma sin binarios nativos.

De Node a Deno para publicar #

El script de publicación (publicar.mjs) era Node.js con dotenv. Ahora es publicar.ts con APIs nativas de Deno: Deno.env, Deno.readFile, Deno.Command. Cero dependencias npm.

Lo que no cambió #

Todo lo que importa se mantuvo intacto:

• El diseño — el mismo CSS, los mismos tokens, el mismo sistema de layout "límites"
• El contenido — los archivos Markdown no se tocaron (salvo el frontmatter de permalink a url)
• El tema claro/oscuro — misma implementación con data-theme y localStorage
• El rendimiento — CSS y JS inline, HTML minificado, cero frameworks en el cliente
• El despliegue — Git → Build → Bunny CDN → Purga de caché

El sitio se ve exactamente igual. Si no lees el footer donde ahora dice "Hecho con Lume", no sabrías que cambió nada.

El resultado #

El build genera 159 archivos en unos 2 segundos. Las 42 imágenes Open Graph se convierten de SVG a PNG solo cuando su contenido cambia — en builds sucesivos se sirven desde una caché local. El proyecto no tiene ninguna dependencia de Node.js. Todo corre sobre Deno.

Después de la migración aproveché para limpiar: eliminé filtros que Vento hacía innecesarios (de 12 a 5), moví la versión anterior del sitio a un subdominio propio para no arrastrar 17 MB en cada deploy, y reorganicé los assets para que solo los archivos realmente externos (cookieconsent) se copien al output — el CSS y JS funcional se incrusta inline directamente desde las plantillas.

Para un sitio que predica la simplicidad y el código limpio, la arquitectura ahora es coherente con el mensaje. Y si te interesan los detalles técnicos de la migración, los he documentado en un artículo aparte con los tres problemas que más tiempo me costaron resolver.

El problema #

En la mayoría de webs, el contenido tiene diferentes anchos. El texto principal suele estar a 65-70 caracteres para una lectura cómoda, pero a veces quieres que una imagen ocupe todo el viewport, que una cita sea más estrecha, o que una sección de tarjetas sea más ancha que el texto.

La solución habitual es anidar divs con max-width y margin: 0 auto:

<!-- El markup típico -->
<div class="wrapper">
  <div class="narrow-wrapper">
    <p>Texto estrecho...</p>
  </div>
</div>
<div class="full-width">
  <img src="hero.jpg" alt="">
</div>
<div class="wrapper">
  <p>Texto normal...</p>
</div>

Esto funciona, pero ensucia el HTML con contenedores que no aportan semántica. Y empeora cuando tienes cinco o seis anchos diferentes.

La solución: columnas nombradas #

La idea es definir un único grid con columnas nombradas que representan los diferentes anchos:

.limites {
  display: grid;
  grid-template-columns:
    [total-start] minmax(1rem, 1fr)
    [ancho-start] minmax(0, calc((var(--anchura-ancho) - var(--anchura-normal)) / 2))
    [normal-start] minmax(0, calc((var(--anchura-normal) - var(--anchura-estrecho)) / 2))
    [estrecho-start] min(var(--anchura-estrecho), 100% - 2rem)
    [estrecho-end] minmax(0, calc((var(--anchura-normal) - var(--anchura-estrecho)) / 2))
    [normal-end] minmax(0, calc((var(--anchura-ancho) - var(--anchura-normal)) / 2))
    [ancho-end] minmax(1rem, 1fr)
    [total-end];
}

Parece intimidante al principio, pero la lógica es sencilla: estás definiendo columnas simétricas que actúan como márgenes entre cada nivel de ancho. La columna central (estrecho) tiene el contenido más estrecho, y las columnas a los lados se expanden progresivamente hasta total, que ocupa todo el viewport.

Cómo se usa #

Cada hijo del grid elige su ancho con una simple clase:

.limites > * { grid-column: normal; }
.limites > .ancho { grid-column: ancho; }
.limites > .estrecho { grid-column: estrecho; }
.limites > .total { grid-column: total; }

Y en el HTML:

<main class="limites">
  <p>Este párrafo ocupa el ancho normal (65ch).</p>
  <section class="ancho">Esto es más ancho (55rem).</section>
  <blockquote class="estrecho">Esto es más estrecho.</blockquote>
  <img class="total" src="panoramica.jpg" alt="">
</main>

Sin wrappers, sin media queries para los anchos, sin max-width repetidos. El grid se encarga de todo.

Por qué funciona #

El truco está en las líneas nombradas de CSS Grid. Cuando defines [nombre-start] y [nombre-end], puedes usar grid-column: nombre como shorthand. El navegador entiende que nombre se refiere al rango entre nombre-start y nombre-end.

Los minmax() hacen que sea responsive por naturaleza. Cuando el viewport se estrecha, las columnas exteriores colapsan a su mínimo (1rem de padding lateral) y las columnas intermedias llegan a 0. El resultado: en móvil, normal, ancho y estrecho convergen al mismo ancho, que es el viewport menos 2rem de margen.

Las custom properties #

Los anchos están definidos como variables CSS en los tokens del sitio:

:root {
  --anchura-ancho: 55rem;
  --anchura-normal: 65ch;
  --anchura-estrecho: 50ch;
}

Esto permite ajustar los anchos en un solo lugar. Y como son custom properties, podrías cambiarlos por sección si alguna página necesita un layout diferente.

Un detalle importante: --anchura-normal usa ch (el ancho del carácter "0") en lugar de rem o px. Es deliberado — quiero que la anchura del texto dependa del tamaño de la fuente, no de un número arbitrario de píxeles. Si cambio la fuente o el tamaño, la anchura óptima de lectura se ajusta sola.

Lo que no encontrarás en un framework #

Este patrón no viene en Bootstrap, no está en Tailwind, no lo genera ningún plugin. Es el tipo de solución que aparece después de años trabajando con CSS, entendiendo las especificaciones y pensando en el problema real en vez de buscar la clase preconstruida.

No digo que los frameworks no tengan su lugar. Pero para un sistema de layout, cuatro líneas de CSS Grid y tres custom properties hacen más que cientos de clases de utilidad.

Lo que probablemente no conoces es por qué cada propiedad está ahí. Y no, no es casual. Cada línea resuelve un problema específico, y si quitas una, algo se rompe en algún lugar.

El patrón completo #

.visually-hidden:not(:focus):not(:active) {
  clip-path: inset(50%);
  height: 1px;
  overflow: hidden;
  position: absolute;
  white-space: nowrap;
  width: 1px;
}

Seis propiedades y dos pseudo-clases negadas. Vamos línea por línea.

Por qué no display: none #

Empecemos por lo que no se usa. display: none elimina el elemento del árbol de accesibilidad. Los lectores de pantalla no lo leen. visibility: hidden hace lo mismo. Ambos son invisibles para todos, no solo visualmente.

Lo que necesitamos es algo más sutil: un elemento que existe en el árbol de accesibilidad, que el lector de pantalla puede leer, pero que no ocupa espacio visual en la pantalla. Es como susurrar algo que solo ciertos oyentes pueden escuchar.

position: absolute #

Saca el elemento del flujo del documento. Hasta aquí, nada sorprendente.

Pero el detalle está en lo que no hace: no usa coordenadas negativas como left: -9999px. Esa fue la técnica clásica durante años, y tiene problemas reales:

• En páginas con dirección RTL (árabe, hebreo), el contenido desplazado a la izquierda puede generar barras de scroll horizontales.
• Algunos lectores de pantalla intentan desplazar la vista hasta donde está el contenido, provocando saltos de scroll desconcertantes.
• JAWS tiene una función llamada Visual Tracking que muestra un borde rojo alrededor del elemento que está leyendo. Con left: -9999px, ese borde se dibuja fuera de la pantalla y el indicador visual se pierde.

position: absolute sin coordenadas simplemente coloca el elemento donde estaría en el flujo, pero sin afectar a los demás. Sin saltos, sin scrollbars fantasma.

width: 1px y height: 1px #

¿Por qué no 0? Porque dimensiones cero pueden sacar el elemento del árbol de accesibilidad en algunos navegadores. En Safari, un elemento con ancho o alto cero no puede recibir foco — lo que rompe los skip links para usuarios de teclado.

Un píxel es el mínimo necesario para que el navegador considere que el elemento "existe" lo suficiente como para mantenerlo accesible. No lo verás, pero el navegador sabe que está ahí.

overflow: hidden #

Con un contenedor de 1×1 píxeles, el texto del interior se desbordaría y sería visible. overflow: hidden corta cualquier contenido que se escape de esa caja mínima. Combinado con las dimensiones, el resultado visual es nada. Cero píxeles visibles.

clip-path: inset(50%) #

Esta es la propiedad que hace el trabajo pesado de ocultar. inset(50%) recorta el elemento desde los cuatro lados hacia dentro un 50%, lo que resulta en un área de recorte de 0×0. Visualmente desaparece.

Lo importante es que clip-path solo afecta la representación visual. El contenido sigue existiendo en el árbol de accesibilidad. Es como poner una máscara sobre algo — no lo destruyes, solo lo tapas.

Quizá hayas visto versiones antiguas del patrón que usan la propiedad clip (sin el -path). Eso era necesario para Internet Explorer. clip está deprecated desde hace años, así que si no necesitas soportar IE, puedes quedarte solo con clip-path.

white-space: nowrap #

Esta es la propiedad que más me sorprendió cuando entendí su razón de ser.

Sin nowrap, el texto dentro de la caja de 1×1 píxeles se envuelve. Cada palabra acaba en su propia "línea" dentro de esa caja mínima. Y aquí vienen dos problemas reales:

NVDA interpreta los saltos como líneas separadas. Si tu texto es "Ir al contenido principal", sin nowrap NVDA puede leerlo como cinco anuncios separados: "Ir", "al", "contenido", "principal". Una experiencia confusa para el usuario.

JAWS Visual Tracking se descuadra. El borde rojo que JAWS dibuja alrededor del elemento leído se extiende verticalmente para acomodar todas esas "líneas" de una palabra, creando un rectángulo alto y estrecho que se superpone con otros elementos de la página.

white-space: nowrap fuerza todo el texto en una sola línea lógica. El desbordamiento ya lo gestiona overflow: hidden y clip-path.

:not(:focus):not(:active) #

El selector completo incluye dos negaciones que anulan todo el ocultamiento cuando el elemento recibe foco.

¿Por qué? Piensa en un skip link: "Ir al contenido principal". Ese enlace debe ser invisible por defecto, pero cuando un usuario de teclado presiona Tab y el enlace recibe foco, tiene que hacerse visible. Un usuario con visión que navega con teclado necesita ver dónde está el foco.

Si el skip link es invisible incluso con foco, el usuario presiona Tab, no ve nada, presiona Enter sin saber qué va a pasar, y la experiencia se rompe. Es peor que no tener skip link.

La adición de :not(:active) es un matiz para Safari. En Safari, al hacer clic en un elemento, este pierde momentáneamente el estado :focus durante el estado :active. Sin esta negación, el elemento parpadearía — visible durante el foco, invisible durante el click, visible de nuevo. El :not(:active) lo mantiene visible durante toda la interacción.

El caso estrella: "Ir al contenido principal" #

He mencionado los skip links varias veces, pero merece la pena detenerse en por qué existen.

Cuando un usuario de lector de pantalla o de teclado llega a una página, lo primero que encuentra es la navegación: logo, menú principal, enlaces secundarios, quizá un buscador. En un sitio con una cabecera compleja, pueden ser 20 o 30 tabulaciones antes de llegar al contenido real. En cada página. Imagina tener que cruzar el mismo pasillo de 30 puertas cada vez que entras en una habitación.

Un skip link es un atajo: el primer elemento focusable de la página, antes incluso de la navegación, que enlaza directamente al contenido principal:

<body>
  <a href="#contenido" class="visually-hidden">
    Ir al contenido principal
  </a>
  <header>...</header>
  <main id="contenido">
    ...
  </main>
</body>

Para un usuario con visión que usa ratón, este enlace no existe — está oculto con .visually-hidden. Pero para un usuario de teclado, aparece en la primera pulsación de Tab. Y para un usuario de lector de pantalla, es lo primero que escucha.

Darle estilo al foco #

Que el enlace se haga visible con :not(:focus) es solo la mitad del trabajo. Si al recibir foco simplemente "aparece" con los estilos por defecto del navegador, el resultado es un texto sin contexto flotando en algún rincón de la página. Necesita estilos propios que lo hagan reconocible:

.visually-hidden:focus {
  position: fixed;
  top: 1rem;
  left: 1rem;
  z-index: 9999;
  padding: 0.75rem 1.5rem;
  background: var(--color-fondo, #1a1a1a);
  color: var(--color-texto, #ffffff);
  font-size: 1rem;
  font-weight: 600;
  text-decoration: none;
  border-radius: 0.25rem;
  box-shadow: 0 2px 8px rgba(0, 0, 0, 0.3);
  outline: 2px solid currentColor;
  outline-offset: 2px;
  width: auto;
  height: auto;
  overflow: visible;
  clip-path: none;
  white-space: normal;
}

Hay varios detalles que importan:

• position: fixed con coordenadas explícitas — lo coloca en una posición predecible, siempre visible, independientemente del scroll.
• Contraste alto — fondo oscuro con texto claro (o al revés). El usuario necesita verlo inmediatamente.
• outline visible — refuerza que el elemento tiene foco. Nunca quites el outline sin dar una alternativa.
• Resetear las propiedades de ocultamiento — width: auto, height: auto, clip-path: none, overflow: visible y white-space: normal deshacen explícitamente cada propiedad del patrón .visually-hidden. Si no las reseteas, el elemento sigue recortado o limitado a 1×1 píxeles aunque tenga foco.

El skip link es probablemente la mejora de accesibilidad con mejor relación esfuerzo-impacto que puedes implementar. Unas pocas líneas de HTML y CSS, y la experiencia de navegación con teclado mejora drásticamente.

Un hack robusto sigue siendo un hack #

James Edwards, el autor del análisis original en Vispero, lo describe perfectamente: es "un hack robusto y probado". Y tiene razón. Cada una de estas propiedades existe para parchear un caso límite de un navegador o un lector de pantalla específico.

No hay una forma nativa de decirle al navegador "este contenido es solo para lectores de pantalla". Tenemos aria-label y aria-labelledby para algunos casos, pero para bloques de texto más largos o skip links, seguimos necesitando este truco CSS.

Lo ideal sería algo como un valor nativo — un hipotético content-visibility: assistive-only o similar — que declare la intención directamente en vez de simular el efecto con seis propiedades. Pero mientras ese día llega, .visually-hidden cumple su función.

Llévate esto #

Si mantienes un archivo de utilidades CSS, asegúrate de que tu .visually-hidden incluye las seis propiedades. No recortes. No "simplifiques". Cada línea está ahí por una razón, probada en campo durante años por la comunidad de accesibilidad.

Y la próxima vez que alguien te diga que la accesibilidad web es fácil, enséñale que necesitamos seis propiedades CSS y dos pseudo-clases negadas solo para ocultar un texto de forma inclusiva.

Los sistemas operativos modernos permiten activar una opción de "reducir movimiento" (macOS, iOS, Windows, Android). Y CSS tiene una media query que detecta esa preferencia: prefers-reduced-motion.

La implementación básica #

@media (prefers-reduced-motion: reduce) {
  *,
  *::before,
  *::after {
    animation-duration: 0.01ms !important;
    animation-iteration-count: 1 !important;
    transition-duration: 0.01ms !important;
    scroll-behavior: auto !important;
  }
}

Este bloque nuclear desactiva todas las animaciones y transiciones de un plumazo. Es efectivo pero tosco — también elimina transiciones sutiles que no causan problemas, como un cambio de color en hover.

Un enfoque más matizado #

En vez de matar todas las animaciones, prefiero desactivar selectivamente las que implican movimiento real (traslaciones, rotaciones, escalados) y mantener las que son puramente visuales (cambios de color, opacidad):

@media (prefers-reduced-motion: reduce) {
  .reveal {
    opacity: 1 !important;
    transform: none !important;
    transition: none !important;
  }

  .animado {
    animation: none !important;
  }
}

Así mantengo los cambios de color en hover (que son informativos, no decorativos) pero elimino los elementos que entran deslizándose, las rotaciones del scroll y las transiciones de posición.

La filosofía: motion como mejora progresiva #

Hay un enfoque alternativo que me gusta más. En vez de definir animaciones y luego desactivarlas, puedes hacer lo contrario: definir la versión estática por defecto y añadir animaciones solo cuando el usuario no ha pedido reducirlas:

/* Por defecto: sin animación */
.reveal {
  opacity: 1;
}

/* Solo animar si el usuario no ha pedido reducir movimiento */
@media (prefers-reduced-motion: no-preference) {
  .reveal {
    opacity: 0;
    transform: translateY(20px);
    transition: opacity 0.6s ease, transform 0.6s ease;
  }

  .reveal.visible {
    opacity: 1;
    transform: none;
  }
}

Este enfoque trata la animación como una mejora progresiva: la funcionalidad base es estática y funcional, y la animación se añade solo cuando es bienvenida. Es más robusto y más respetuoso.

JavaScript también #

Si tu JavaScript controla animaciones, también debería comprobar la preferencia:

const prefersReducedMotion = window.matchMedia(
  "(prefers-reduced-motion: reduce)"
).matches;

if (!prefersReducedMotion) {
  // Inicializar IntersectionObserver para reveals
  // Activar animaciones de scroll
  // etc.
}

Y si la preferencia puede cambiar durante la sesión (el usuario activa/desactiva la opción mientras navega):

const motionQuery = window.matchMedia("(prefers-reduced-motion: reduce)");

motionQuery.addEventListener("change", () => {
  if (motionQuery.matches) {
    desactivarAnimaciones();
  } else {
    activarAnimaciones();
  }
});

En este sitio #

Las animaciones de "reveal" (elementos que aparecen al hacer scroll) respetan prefers-reduced-motion. Si tienes la opción activada en tu sistema operativo, los elementos simplemente están ahí — sin deslizamiento, sin fundido. El contenido es el mismo; la decoración es la que cambia.

Es un esfuerzo mínimo para el desarrollador y una diferencia enorme para el usuario que lo necesita. No hay excusa para ignorarlo.

:has() cambia eso. Y no solo resuelve el caso del selector padre — es mucho más potente de lo que parece a primera vista.

Qué es :has() #

En su forma más simple, :has() selecciona un elemento que contiene algo:

/* Selecciona los artículos que tienen una imagen */
article:has(img) {
  grid-template-columns: 1fr 1fr;
}

/* Selecciona los artículos que NO tienen imagen */
article:not(:has(img)) {
  grid-template-columns: 1fr;
}

Eso es el selector padre. Un article que contiene un img recibe un layout diferente. Antes necesitabas una clase extra en el HTML o JavaScript para conseguir esto.

Pero :has() acepta cualquier selector como argumento, incluyendo pseudo-clases, combinadores y selectores compuestos. Ahí es donde se pone interesante.

Formularios reactivos sin JavaScript #

El caso de uso que más me convence es hacer que los formularios respondan a su propio estado sin una sola línea de JavaScript.

Mostrar ayuda cuando un campo tiene foco #

.campo:has(input:focus) .ayuda {
  display: block;
}

Cuando el input dentro de .campo tiene foco, el texto de ayuda se muestra. Sin eventos focus/blur en JS, sin toggle de clases.

Resaltar campos inválidos con contexto #

.campo:has(input:invalid:not(:placeholder-shown)) {
  --borde-campo: var(--color-error);
}

.campo:has(input:invalid:not(:placeholder-shown)) .mensaje-error {
  display: block;
}

El truco de :not(:placeholder-shown) evita que el campo se marque como inválido antes de que el usuario escriba algo. :has() permite que el contenedor reaccione, no solo el input.

Deshabilitar visualmente el botón de envío #

form:has(:invalid) button[type="submit"] {
  opacity: 0.5;
  pointer-events: none;
}

Si el formulario contiene algún campo inválido, el botón se atenúa. El formulario entero es consciente de su estado, sin necesidad de validación JavaScript para el feedback visual.

Navegación contextual #

Otro patrón útil: que la navegación sepa qué está pasando en la página.

/* Si la página tiene un hero, la nav es transparente */
body:has(.hero) .nav-principal {
  background: transparent;
  position: absolute;
}

/* Si un menú desplegable está abierto, oscurecer el fondo */
body:has(.dropdown[open]) .overlay {
  opacity: 1;
  pointer-events: auto;
}

Antes, el patrón habitual era añadir clases al body con JavaScript (body.has-hero, body.menu-open). Con :has(), el CSS lo resuelve solo.

Layouts que responden al contenido #

Esto es lo que más me interesa para este mismo sitio. En vez de crear variantes con clases CSS, el layout se adapta a lo que contiene.

Tarjetas con o sin imagen #

.tarjeta:has(img) {
  display: grid;
  grid-template-columns: 200px 1fr;
  gap: 1rem;
}

.tarjeta:not(:has(img)) {
  padding: 1.5rem;
}

Grids que reaccionan a la cantidad de hijos #

Combinando :has() con :nth-child() puedes crear grids que se reorganizan según cuántos elementos contienen:

/* Si el grid tiene más de 3 hijos, usar 3 columnas */
.grid:has(:nth-child(4)) {
  grid-template-columns: repeat(3, 1fr);
}

/* Si tiene 2 o menos, usar 2 columnas */
.grid:not(:has(:nth-child(3))) {
  grid-template-columns: repeat(2, 1fr);
}

Sin JavaScript contando elementos, sin clases condicionales generadas desde el servidor.

Seleccionar hermanos previos #

Un efecto secundario inesperado de :has() es que habilita la selección de hermanos anteriores, algo que nunca fue posible en CSS:

/* Resaltar todos los elementos de la lista anteriores al hover */
li:has(~ li:hover) {
  color: var(--color-acento);
}

Esto dice: "selecciona un li que tiene un hermano posterior (~) que está en hover". En otras palabras, selecciona los anteriores al elemento en hover. Perfecto para crear un sistema de valoración con estrellas, por ejemplo.

Soporte en navegadores #

:has() está soportado en todos los navegadores modernos desde finales de 2023:

• Chrome / Edge: desde la versión 105 (agosto 2022)
• Safari: desde la versión 15.4 (marzo 2022) — fue el primero en implementarlo
• Firefox: desde la versión 121 (diciembre 2023) — el último en llegar

A fecha de hoy, el soporte global supera el 96% de los usuarios según Can I Use. La única franja sin cobertura son versiones muy antiguas de navegadores que probablemente tampoco soporten otras características modernas que ya usamos con normalidad como gap en flexbox o aspect-ratio.

Progressive enhancement: úsalo sin miedo #

Hay una característica de :has() que lo convierte en candidato ideal para progressive enhancement: cuando un navegador no lo entiende, simplemente ignora la regla. No lanza errores, no rompe el resto del CSS. El selector no aplica y punto.

Esto significa que puedes usarlo como una mejora visual sobre un diseño base que funciona sin él:

/* Base: funciona en todos los navegadores */
.tarjeta {
  padding: 1.5rem;
}

/* Mejora: solo se aplica si el navegador entiende :has() */
.tarjeta:has(img) {
  display: grid;
  grid-template-columns: 200px 1fr;
  gap: 1rem;
  padding: 0;
}

El diseño base muestra una tarjeta funcional y legible. Si el navegador soporta :has(), obtiene un layout mejorado con la imagen al lado. Si no, la imagen simplemente aparece encima del texto, dentro del flujo normal. Nada se rompe.

La clave es diseñar el caso base primero — el CSS que funciona sin :has() — y luego añadir las mejoras. No construyas layouts que dependan de :has() para ser usables. Úsalo para mejorar la experiencia, no para sostenerla.

En la práctica, con más del 96% de soporte, el porcentaje de usuarios que no se beneficiarán de tus reglas con :has() es mínimo, y esos usuarios seguirán viendo un sitio perfectamente funcional.

Cuándo no usarlo #

:has() no reemplaza JavaScript para lógica compleja. Si necesitas validación asíncrona, peticiones al servidor o transformaciones de datos, sigue usando JS. Lo que elimina son los casos donde JavaScript solo servía para observar el DOM y aplicar clases CSS — exactamente el tipo de código que siempre pareció que no debería ser necesario.

Tampoco es ideal para animaciones complejas basadas en el estado. Para eso, las custom properties con un pequeño script siguen siendo más explícitas y depurables.

La regla que me aplico #

Antes de añadir un addEventListener que solo hace classList.toggle(), pienso si :has() lo resuelve. La mayoría de las veces, sí. Y el resultado es CSS que se lee como una frase: "si el formulario tiene un campo inválido, atenúa el botón". Sin intermediarios.

La solución que más se recomienda en la comunidad Eleventy es Decap CMS (antes Netlify CMS): un panel de administración que se conecta a un repositorio Git y genera ficheros Markdown. En teoría, el cliente edita en un formulario bonito, el CMS hace commit a Git, se dispara un build, y la web se actualiza. En la práctica, es más complicado.

Lo bueno #

Decap CMS resuelve el problema fundamental: el cliente no necesita saber qué es Git, ni Markdown, ni un terminal. Ve un formulario con campos, escribe, le da a "Publicar" y su contenido aparece en la web.

La configuración es un único fichero config.yml donde defines las colecciones (blog, páginas, etc.) y los campos de cada una. La integración con Eleventy es natural porque ambos trabajan con ficheros Markdown y frontmatter YAML.

collections:
  - name: "blog"
    label: "Blog"
    folder: "content/blog/posts"
    create: true
    fields:
      - { label: "Título", name: "title", widget: "string" }
      - { label: "Fecha", name: "date", widget: "datetime" }
      - { label: "Contenido", name: "body", widget: "markdown" }

Lo malo: los builds #

Aquí es donde empiezan los problemas. Cada vez que el cliente guarda un borrador, Decap CMS hace un commit. Cada commit dispara un build en Netlify, Cloudflare Pages o el servicio que uses. Un cliente que escribe un artículo y guarda tres borradores antes de publicar ha generado cuatro builds.

Si el sitio es pequeño y el build dura segundos, no pasa nada. Pero he visto proyectos donde un cliente entusiasta generaba 30-40 builds al día porque guardaba cada párrafo. Con los límites de minutos de build que tienen los planes gratuitos de la mayoría de plataformas, eso se convierte en un problema real.

Lo peor: el contenido roto #

Un CMS headless no valida el resultado visual. El cliente puede:

• Pegar texto desde Word con formato oculto que rompe el Markdown
• Subir imágenes de 5MB sin optimizar
• Dejar campos obligatorios vacíos (Decap los valida, pero no siempre bien)
• Crear estructuras de encabezados incorrectas (un H4 después de un H2)
• Romper el build si introduce caracteres especiales en el título que afectan al slug

He tenido clientes que borran contenido pensando que estaban editando, y como Decap hace commit directamente, el contenido desaparece de la web. Sí, está en el historial de Git, pero explicarle a un cliente qué es un git revert no es una conversación productiva.

La alternativa honesta #

Después de varios proyectos con esta arquitectura, he llegado a una conclusión incómoda: si el cliente necesita editar contenido frecuentemente, un generador estático probablemente no es la herramienta adecuada.

No digo que no funcione nunca. Para un cliente que actualiza su blog una vez al mes y tiene un perfil mínimamente técnico, Decap CMS con Eleventy es una buena solución. Pero para un cliente que publica a diario, tiene varios editores, necesita previsualización en tiempo real y quiere un flujo de borrador-revisión-publicación, un CMS tradicional como WordPress (sí, he dicho WordPress) sigue siendo más apropiado.

Cuándo sí funciona #

La combinación Eleventy + Decap CMS funciona bien cuando:

• El contenido se actualiza con poca frecuencia (semanal o menos)
• Hay un solo editor o un equipo muy pequeño
• El editor entiende la estructura básica del contenido (título, cuerpo, fecha)
• Hay un desarrollador disponible para solucionar problemas ocasionales
• Los builds son rápidos (menos de un minuto)

En esos casos, las ventajas del stack estático (rendimiento, seguridad, coste cero de hosting) superan las incomodidades del CMS.

Lo que hago ahora #

Para proyectos donde el cliente necesita autonomía total, uso WordPress con un tema a medida. Para proyectos donde el contenido es mayoritariamente estático o lo gestiono yo, uso Eleventy sin CMS. Y para el terreno intermedio, valoro caso a caso y soy honesto con el cliente sobre lo que implica cada opción.

La peor decisión es elegir la herramienta que a ti te gusta en vez de la que el cliente necesita.

La técnica se basa en un truco elegante: usar una animación CSS pausada, y controlar en qué fotograma se encuentra usando animation-delay con un valor negativo calculado a partir del scroll.

La idea central #

El único JavaScript necesario es actualizar una variable CSS con la posición de scroll:

window.addEventListener("scroll", () => {
  requestAnimationFrame(() => {
    document.body.style.setProperty(
      "--recorrido",
      window.pageYOffset
    );
  });
}, { passive: true });

Eso es todo el JavaScript. Una variable CSS (--recorrido) que contiene los píxeles recorridos. El resto es CSS puro.

La clase mágica #

El núcleo del sistema es una clase .animado que convierte cualquier animación CSS en una animación controlada por scroll:

.animado {
  animation: var(--nombreanimacion) 1s linear forwards;
  animation-play-state: paused;
  animation-delay: calc(
    ((var(--recorrido, 0) - var(--posinicio, 0)) / var(--altura, 1)) * -1s
  );
  animation-fill-mode: both;
}

Vamos a descomponer esta fórmula:

• --recorrido — la posición de scroll actual (viene del JS)
• --posinicio — el punto de scroll donde empieza la animación de este elemento
• --altura — la distancia en píxeles durante la que se desarrolla la animación
• El resultado se multiplica por -1s para convertirlo en un delay negativo

¿Por qué funciona? #

El truco está en cómo los navegadores interpretan animation-delay con valores negativos. Cuando una animación tiene un delay de -0.5s y dura 1s, el navegador la renderiza como si llevase medio segundo reproduciéndose. Pero como animation-play-state está en paused, no avanza: se queda congelada en ese punto exacto.

Al cambiar el valor de --recorrido con el scroll, el animation-delay se recalcula automáticamente (gracias a las custom properties), y el navegador renderiza el fotograma correspondiente. El efecto es una animación que avanza y retrocede siguiendo el scroll.

Configurar cada elemento #

Cada elemento animado necesita tres cosas:

1. La animación — un @keyframes que defina el movimiento
2. El punto de inicio — --posinicio establecido en el HTML o CSS
3. La duración — --altura que define cuántos píxeles de scroll dura

@keyframes rotar {
  from { transform: rotate(0deg); }
  to { transform: rotate(45deg); }
}

#cabecera .intro {
  --nombreanimacion: rotar;
}

Y en el HTML o con JavaScript, se establecen las variables de posición:

// Calcular las alturas de cada sección
document.body.style.setProperty(
  "--alturaCabecera",
  document.getElementById("cabecera").offsetHeight
);

Las ventajas #

Rendimiento: no hay cálculos de transformación en JavaScript. Todo lo hace el motor de renderizado CSS, que está optimizado para eso. El JS solo escribe una variable numérica en cada frame.

Composición: puedes combinar múltiples animaciones en el mismo elemento. Un elemento puede rotar, cambiar de opacidad y moverse, todo controlado por el mismo scroll.

Reversibilidad: como el cálculo es bidireccional, hacer scroll hacia arriba revierte la animación naturalmente. No necesitas código adicional.

Mantenibilidad: las animaciones se definen en CSS, donde pertenecen. Si quieres cambiar un movimiento, editas un @keyframes. El JavaScript no cambia nunca.

Las limitaciones #

No es perfecto. El cálculo asume un scroll vertical lineal, así que no funciona bien con scroll horizontal o con contenedores con scroll propio. Las variables de posición (--posinicio, --altura) hay que calcularlas una vez al cargar y actualizar en el resize, lo que añade algo de complejidad.

Y si el contenido es dinámico y cambia de altura después de cargar, las posiciones se descuadran. Para una web estática donde tú controlas el contenido, funciona a la perfección.

El futuro: CSS Scroll-Driven Animations #

La especificación CSS ahora incluye animation-timeline: scroll(), que hace lo mismo de forma nativa, sin JavaScript:

@keyframes revelar {
  from { opacity: 0; transform: translateY(20px); }
  to { opacity: 1; transform: translateY(0); }
}

.elemento {
  animation: revelar linear both;
  animation-timeline: scroll();
  animation-range: entry 0% entry 100%;
}

Todavía no tiene soporte universal, pero cuando lo tenga, el JavaScript desaparecerá por completo. Hasta entonces, la técnica del animation-delay negativo sigue siendo la más fiable y ligera.

La técnica clásica: el gradiente diagonal #

La idea original de Mike se basa en tres conceptos combinados:

1. Un gradiente diagonal aplicado al body con un corte duro al 50%
2. Un cálculo de tamaño que compensa la altura del viewport
3. Una máscara fija que oculta todo excepto una tira de 3 píxeles

La geometría #

Imagina un rectángulo con una línea diagonal:

+------------------+
|            /   B |   B = fondo (transparente)
|         /        |
|      /           |
|   /              |
| A                |   A = color de acento
+------------------+

Cuando el viewport se desplaza hacia abajo por este rectángulo, la intersección de la diagonal con el borde superior se mueve de izquierda a derecha. Si solo ves una franja fina en la parte de arriba, parece una barra de progreso.

El CSS del gradiente #

body {
  background-image: linear-gradient(
    to right top,
    #f86624 50%,
    transparent 50%
  );
  background-size: 100% calc(100% - 100vh + 4rem + 3px + 1px);
  background-repeat: no-repeat;
}

body::after {
  content: "";
  position: fixed;
  top: calc(4rem + 3px);
  bottom: 0;
  left: 0;
  right: 0;
  background: #fff;
  z-index: -1;
}

La parte más ingeniosa es el background-size:

Sin el - 100vh, el gradiente solo estaría a medio llenar al final de la página. La resta compensa que el viewport ocupa espacio.

El pseudo-elemento ::after con z-index: -1 actúa como máscara: queda entre el canvas del navegador (donde se pinta el fondo del body) y el contenido normal.

La limitación #

Esta técnica tiene un inconveniente importante. El gradiente se pinta en el canvas — la capa más baja del modelo de renderizado del navegador. Cualquier elemento con fondo propio (bloques de código, tarjetas, tablas) se pinta por encima. Cuando estos elementos cruzan la franja del indicador al hacer scroll, la tapan momentáneamente.

En páginas con mucho texto plano funciona bien. En páginas con muchos bloques de código, la barra desaparece durante tramos largos. Es geometría pura, y es brillante. Pero los contextos de apilamiento de CSS le ganan la batalla.

La versión moderna: scroll-driven animations #

Desde 2023, CSS tiene una API nativa para vincular animaciones al progreso de scroll: animation-timeline: scroll(). Esta alternativa resuelve el problema del z-index.

body::before {
  content: "";
  position: fixed;
  top: 4rem;
  left: 0;
  width: 100%;
  height: 3px;
  background: #f86624;
  z-index: 99;
  transform-origin: left;
  scale: 0 1;
  animation: scroll-indicator linear forwards;
  animation-timeline: scroll();
}

@keyframes scroll-indicator {
  to { scale: 1 1; }
}

El indicador es un pseudo-elemento fijo con z-index: 99, por encima de todo el contenido. La animación scale va de 0 a 1 en el eje X, y animation-timeline: scroll() la vincula al progreso del scroll.

El inconveniente: el soporte de navegadores todavía no es completo. Chrome y Edge lo soportan bien desde 2023, pero Firefox y Safari van con retraso. Para un sitio donde el soporte universal importa, puede no ser suficiente.

CSS vs JavaScript #

Un listener de scroll en JavaScript ejecuta código en cada frame, necesita requestAnimationFrame para no bloquear el hilo principal, y falla si el usuario deshabilita scripts. Las versiones CSS:

• No ejecutan código en cada frame
• El navegador optimiza la animación internamente
• Funcionan sin JavaScript
• Son menos de 15 líneas

Cada enfoque tiene sus compromisos. El gradiente diagonal es universal pero tiene el problema del z-index. Las scroll-driven animations lo resuelven pero dependen de soporte moderno. Y JavaScript, aunque menos elegante, funciona en todas partes sin limitaciones visuales.

A veces la solución más elegante no es la más práctica. Pero merece la pena conocerla.

La técnica del gradiente diagonal es de Mike Riethmuller. También la explica en detalle CSS-Tricks. La API de scroll-driven animations está documentada en MDN.

Lo que ya ganas #

Con Eleventy o cualquier generador estático, partes con ventaja:

• Sin servidor dinámico — el HTML está pregenerado, el servidor solo lo sirve
• CDN friendly — los ficheros estáticos se cachean y distribuyen globalmente
• Sin base de datos — cero latencia de queries
• Sin framework JS (si lo evitas) — menos código para parsear y ejecutar

Pero estas ventajas se pueden desperdiciar fácilmente.

CSS: inline vs archivo externo #

El plugin eleventy-plugin-bundle permite incluir el CSS inline en el HTML:

<style>
  {% getBundle "css" %}
</style>

Para sitios pequeños, esto es una ventaja: eliminas una petición HTTP. El navegador tiene todo lo que necesita en el primer HTML para renderizar la página. No hay FOUC (flash of unstyled content) porque el CSS está disponible antes del primer paint.

El punto de inflexión está alrededor de los 14KB. Ese es el tamaño del primer round-trip TCP (el primer fragmento que el servidor puede enviar). Si tu CSS cabe ahí junto con el HTML, inline es la opción correcta. Si no, un archivo externo con rel="preload" es mejor porque el navegador lo cachea.

El CSS completo de este sitio, incluyendo todos los componentes y ambos temas, está por debajo de ese límite.

Fuentes: la trampa silenciosa #

Las fuentes web son probablemente el mayor problema de rendimiento en sitios que por lo demás son ligeros. Cada fichero de fuente es una petición HTTP, y el navegador no renderiza el texto hasta que la fuente carga (por defecto).

Opciones, de más rápida a más lenta:

1. System font stack — cero peticiones, renderizado instantáneo
2. Fuente local con font-display: swap — el texto aparece inmediatamente con la fuente del sistema y cambia cuando carga la fuente web
3. Fuente de Google Fonts — añade latencia de DNS + petición al CDN de Google
4. Múltiples pesos de fuente — cada peso es un archivo adicional

@font-face {
  font-family: "MiFuente";
  src: url("/fonts/mifuente.woff2") format("woff2");
  font-display: swap;
  font-weight: 400;
}

El formato woff2 es obligatorio — es el más comprimido y tiene soporte universal. Si tu fuente solo viene en TTF u OTF, conviértela.

Y un consejo: limita los pesos. ¿Realmente necesitas thin, light, regular, medium, semibold, bold, extrabold y black? Probablemente con regular y bold cubras el 95% de los casos.

Imágenes: el elefante en la habitación #

En una web de contenido textual como esta, las imágenes no son un problema porque apenas las hay. Pero en proyectos con imágenes, son el factor dominante del rendimiento.

Lo mínimo que deberías hacer:

• Formatos modernos: WebP o AVIF en vez de JPEG/PNG
• Dimensiones correctas: no servir una imagen de 3000px para un espacio de 800px
• loading="lazy": carga diferida para imágenes fuera del viewport
• srcset y sizes: para que el navegador elija la resolución adecuada

<picture>
  <source srcset="imagen.avif" type="image/avif">
  <source srcset="imagen.webp" type="image/webp">
  <img src="imagen.jpg" alt="Descripción" loading="lazy"
       width="800" height="450">
</picture>

JavaScript: menos es más #

El JavaScript propio de este sitio — toggle de tema, menú hamburguesa, animaciones de entrada y gestión de enlaces externos — va inline en el HTML y pesa menos de lo que pesa una sola imagen de avatar en la mayoría de webs. El cookie consent, que es la dependencia más pesada, se carga de forma diferida: su CSS y JavaScript no bloquean el primer renderizado ni forman parte del bundle principal.

El truco no es minificar mejor ni usar tree-shaking más agresivo. El truco es no cargar lo que no necesitas en el momento crítico. Cada npm install que evitas es rendimiento ganado, y lo que no puedes evitar, lo difiere.

Medir, no adivinar #

Las herramientas están ahí:

• Lighthouse en las DevTools de Chrome — puntuación general
• WebPageTest — waterfall detallado y métricas reales
• El panel Network de las DevTools — para ver exactamente qué se carga y cuánto pesa

La métrica más importante para una web de contenido es Largest Contentful Paint (LCP): cuánto tarda en aparecer el contenido principal. Para este sitio, debería estar por debajo de 1 segundo en una conexión decente, porque lo primero que el navegador recibe es un HTML completo con CSS inline y texto. No hay JavaScript que bloquee el renderizado, no hay fuentes que retrasen el paint, no hay imágenes above-the-fold.

Eso no es magia. Es solo tomar decisiones conscientes sobre qué incluir y qué dejar fuera.

Un móvil con pantalla de 375px no necesita una imagen de 2000px de ancho. Un navegador que soporta WebP no debería recibir un JPEG. Pero si no le das opciones al navegador, descargará la única imagen que le ofreces, sea o no la adecuada.

El atributo srcset #

La forma más sencilla de ofrecer alternativas:

<img
  src="foto-800.jpg"
  srcset="foto-400.jpg 400w,
          foto-800.jpg 800w,
          foto-1200.jpg 1200w"
  sizes="(max-width: 600px) 100vw,
         (max-width: 900px) 50vw,
         33vw"
  alt="Descripción de la foto"
  loading="lazy"
  width="1200"
  height="800"
>

srcset le dice al navegador qué imágenes están disponibles y su ancho real en píxeles. sizes le dice cuánto espacio ocupará la imagen en el layout. Con esa información, el navegador elige la imagen más adecuada considerando el ancho del viewport y la densidad de píxeles de la pantalla.

El src original es el fallback para navegadores que no soportan srcset (prácticamente ninguno en 2025, pero por compatibilidad).

El elemento picture #

Cuando necesitas cambiar el formato de imagen (no solo el tamaño), <picture> es la herramienta:

<picture>
  <source srcset="foto.avif" type="image/avif">
  <source srcset="foto.webp" type="image/webp">
  <img src="foto.jpg" alt="Descripción" loading="lazy"
       width="800" height="450">
</picture>

El navegador recorre las <source> en orden y usa la primera que soporta. Si soporta AVIF (el más comprimido), lo usa. Si no, prueba WebP. Si no soporta ninguno, usa el JPEG del <img>.

También puedes combinar formatos con tamaños:

<picture>
  <source
    srcset="foto-400.avif 400w, foto-800.avif 800w"
    sizes="(max-width: 600px) 100vw, 50vw"
    type="image/avif">
  <source
    srcset="foto-400.webp 400w, foto-800.webp 800w"
    sizes="(max-width: 600px) 100vw, 50vw"
    type="image/webp">
  <img
    src="foto-800.jpg"
    srcset="foto-400.jpg 400w, foto-800.jpg 800w"
    sizes="(max-width: 600px) 100vw, 50vw"
    alt="Descripción"
    loading="lazy"
    width="800" height="450">
</picture>

Es verboso, sí. Pero puede reducir el peso de las imágenes en un 50-70%.

Lazy loading nativo #

<img src="foto.jpg" alt="..." loading="lazy">

Una línea. Le dice al navegador que no descargue la imagen hasta que esté cerca del viewport. No necesitas IntersectionObserver, no necesitas una librería. Es un atributo HTML.

Úsalo en todas las imágenes que no estén en el viewport inicial (above the fold). Para la imagen hero o el logo, usa loading="eager" (o simplemente no pongas el atributo, que es el valor por defecto).

Width y height: evitar el layout shift #

Siempre incluye width y height en tus imágenes:

<img src="foto.jpg" alt="..." width="800" height="450">

No es para definir el tamaño visual (eso lo hace CSS). Es para que el navegador pueda calcular el aspect ratio antes de descargar la imagen y reservar el espacio correcto en el layout. Sin estos atributos, el contenido "salta" cuando la imagen carga — eso es un layout shift, y es una de las métricas que más penaliza en Core Web Vitals.

Formatos: AVIF > WebP > JPEG #

• AVIF: la mejor compresión disponible. Archivos 50% más pequeños que JPEG a calidad equivalente. Soporte del 92%+ de navegadores.
• WebP: buen compromiso entre compresión y soporte. 25-35% más pequeño que JPEG. Soporte prácticamente universal.
• JPEG: el fallback universal. Sigue siendo necesario como último recurso.
• PNG: solo para imágenes que necesitan transparencia y no pueden ser WebP/AVIF.

En la práctica #

Para una web con pocas imágenes (como esta), la optimización manual es factible: generas las variantes una vez y las subes. Para una web con muchas imágenes, necesitas automatización — eleventy-img para Eleventy, sharp en Node, o un servicio de transformación como Cloudinary.

Lo importante es no servir imágenes sin optimizar. Una foto de 4000x3000 pixels directo de la cámara en un <img> sin srcset ni lazy loading es el error de rendimiento más común y más fácil de corregir en la web.

Lo que me gusta #

Herencia de layouts #

La característica estrella. Defines un layout base y los demás lo extienden:

{# base.njk #}
<!DOCTYPE html>
<html>
  <head>...</head>
  <body>
    {{ content | safe }}
  </body>
</html>

{# post.njk — extiende base #}
---
layout: layouts/base.njk
---
<article class="post">
  <h1>{{ title }}</h1>
  {{ content | safe }}
</article>

Es limpio, predecible y fácil de seguir. Cada layout sabe qué hereda y qué añade.

Includes y partials #

Los parciales de Nunjucks son la forma más natural de componentizar HTML sin JavaScript:

{% include 'partials/cabecera.njk' %}
{% include 'partials/pie.njk' %}

No hay props, no hay estado, no hay ciclo de vida. Es solo insertar HTML. Para una web estática, es todo lo que necesitas.

Filtros #

Los filtros son funciones que transforman datos en la plantilla. Eleventy permite definirlos en la configuración y usarlos en Nunjucks:

<time>{{ date | readableDate }}</time>
<p>{{ content | intro(100) }}</p>

Son compositivos — puedes encadenarlos — y mantienen la lógica de presentación separada de los datos. Es el patrón correcto.

Loops y condicionales #

La sintaxis para iterar y condicionar es directa:

{%- for post in collections.bitacora %}
  {% if post.data.destacado %}
    {% include 'partials/postcard.njk' %}
  {% endif %}
{%- endfor %}

Sin sorpresas, sin edge cases raros. Hace lo que parece que hace.

Lo que me frustra #

Errores crípticos #

Cuando algo falla en una plantilla Nunjucks, los mensajes de error son a menudo inútiles. Un paréntesis mal cerrado o una variable inexistente te dan un error genérico que apunta a la línea equivocada. Depurar una plantilla compleja a veces se convierte en un proceso de eliminación: vas comentando bloques hasta que encuentras el que falla.

No hay tipado #

Nunjucks no sabe qué propiedades tiene un objeto hasta el runtime. Si escribes {{ post.tittle }} (con doble T), no hay error — simplemente no renderiza nada. Te das cuenta cuando ves un hueco vacío en la web. TypeScript arruinó mi tolerancia a los errores en tiempo de ejecución.

Sintaxis verbosa para lógica compleja #

Cuando la lógica se complica, Nunjucks se vuelve difícil de leer:

{%- set postsOrdenados = collections.bitacora | ordenarPorFecha | head(3) %}
{%- for post in postsOrdenados %}
  {%- if post.data.tags | filterTagList | length > 0 %}
    ...
  {%- endif %}
{%- endfor %}

No es terrible, pero cuando tienes tres niveles de anidación con filtros encadenados, echas de menos poder escribir lógica en un lenguaje de verdad.

Whitespace control #

Los {%- y -%} para controlar los espacios en blanco son necesarios pero molestos. Si no los usas, tu HTML generado tiene líneas vacías y sangrado irregular. Si los usas en todas partes, la plantilla se vuelve ruidosa.

Lo que he considerado #

Liquid: más limitado que Nunjucks, pero con mejor manejo de errores. Jekyll lo usa y la comunidad es enorme.

WebC: la propuesta nativa de Eleventy para componentes web. Interesante, pero todavía joven y con una curva de aprendizaje diferente.

JSX/TSX con 11ty: técnicamente posible, pero va contra la filosofía de mantener las plantillas simples y sin build step.

De momento me quedo con Nunjucks. Sus defectos son menores comparados con sus ventajas, y la familiaridad acumulada después de varios proyectos tiene un valor que no se puede subestimar. El mejor motor de plantillas es el que ya conoces, siempre que no te limite activamente.

La estructura #

Todo el sistema se basa en tres piezas:

1. Custom properties para los colores del tema
2. Un atributo data-theme en el <html> para cambiar entre temas
3. Un script mínimo para persistir la preferencia

Los colores como variables #

En vez de usar colores directos en los componentes, todo pasa por custom properties:

:root {
  --color-texto: #1a1b2e;
  --color-texto-alt: #5a5b6e;
  --color-fondo: #fafaf8;
  --color-fondo-alt: #f0f0ec;
  --color-acento: #e05a1b;
  --color-borde: #d8d8d0;
}

[data-theme="dark"] {
  --color-texto: #dcdcd4;
  --color-texto-alt: #8e8e86;
  --color-fondo: #111118;
  --color-fondo-alt: #1a1a24;
  --color-acento: #f86624;
  --color-borde: #2a2a3a;
}

Lo importante: el acento siempre es naranja, pero se ajusta ligeramente entre temas. En tema claro uso un naranja más contenido (#e05a1b) para que no resulte agresivo sobre fondo blanco. En tema oscuro, un naranja más vivo (#f86624) que destaque sobre el fondo oscuro. Es el mismo tono, con diferente intensidad. Lo que cambia de forma más notable son los fondos, los textos y los bordes.

Los componentes no saben de temas #

Una vez definidas las variables, los componentes las usan sin saber si estamos en tema claro u oscuro:

.tarjeta {
  background: var(--color-fondo-alt);
  color: var(--color-texto);
  border: 1px solid var(--color-borde);
}

No hay .tarjeta--dark, no hay @media (prefers-color-scheme: dark) repetido en cada componente, no hay clases condicionales. El cambio de tema se resuelve en un solo lugar: la definición de las variables.

Evitar el flash (FOUC) #

El error más común al implementar temas es poner el JavaScript al final del body. El resultado: la página carga en el tema por defecto (claro) y medio segundo después salta al oscuro. Ese parpadeo es molesto y fácil de evitar.

La solución es un script inline en el <head>, antes del CSS:

<script>
  (function() {
    var theme = localStorage.getItem('theme');
    if (!theme) {
      theme = window.matchMedia('(prefers-color-scheme: dark)').matches
        ? 'dark' : 'light';
    }
    document.documentElement.setAttribute('data-theme', theme);
  })();
</script>

Este script se ejecuta síncronamente antes de que el navegador renderice nada. Lee la preferencia guardada en localStorage; si no hay ninguna, respeta la del sistema operativo. El atributo data-theme se aplica antes del primer paint, así que no hay flash.

El botón de toggle #

El botón es simple: cambia el atributo y guarda en localStorage.

document.querySelectorAll(".theme-toggle").forEach(btn => {
  btn.addEventListener("click", () => {
    const current = document.documentElement.getAttribute("data-theme");
    const next = current === "dark" ? "light" : "dark";
    document.documentElement.setAttribute("data-theme", next);
    localStorage.setItem("theme", next);
    // Actualizar icono
    document.querySelectorAll(".theme-toggle").forEach(b => {
      b.textContent = next === "dark" ? "☀" : "☾";
    });
  });
});

Detalles que importan #

Imágenes y contraste #

En tema oscuro, las imágenes con fondo blanco quedan como focos en una habitación a oscuras. Puedo reducir su brillo con CSS:

[data-theme="dark"] img {
  filter: brightness(0.9);
}

Sombras #

Las sombras que funcionan en tema claro son invisibles en tema oscuro. En vez de sombras negras, uso sombras basadas en el color de fondo con transparencia.

Transiciones #

Un transition en el body suaviza el cambio:

body {
  transition: background-color 0.3s ease, color 0.3s ease;
}

Pero ojo: esto puede causar transiciones no deseadas al cargar la página. Una opción es añadir la transición solo después del primer paint con JavaScript, o usar una clase temporal.

Lo que no hago #

No uso prefers-color-scheme como selector principal. Lo uso solo como fallback cuando no hay preferencia guardada. La razón: si el usuario ha elegido explícitamente un tema en mi web, esa decisión debe prevalecer sobre la del sistema operativo.

Tampoco intento hacer una transición automática entre temas según la hora del día. Si el usuario quiere claro a las 3 de la mañana, es su decisión. El toggle está ahí para eso.

Después de probar varias plataformas para mis proyectos con Eleventy, estas son mis conclusiones. No es una lista teórica — es un recorrido por las que he usado realmente y por qué he acabado donde he acabado.

Netlify #

Fue pionera en popularizar el hosting estático con builds automáticos. Conectas un repositorio Git, configuras el comando de build (npx eleventy), y cada push despliega automáticamente. Durante años fue la referencia del sector, y con razón.

Lo bueno: Configuración trivial, previews de PR, redirects con _redirects, formularios nativos, functions serverless. El plan gratuito es generoso (100GB de ancho de banda, 300 minutos de build).

Lo malo: Los builds pueden ser lentos (arrancar el entorno lleva más que el build en sí). El CDN no es tan rápido como el de Cloudflare. Y las funciones serverless añaden complejidad que contradice la filosofía del sitio estático. Con el tiempo, la plataforma ha ido creciendo en funcionalidades hasta convertirse en algo que ya no se siente tan simple.

Yo usé Netlify durante una buena temporada. Cumple, pero llegó un momento en que busqué alternativas que se ajustaran mejor a mi forma de trabajar.

Ideal para: proyectos con formularios, funciones serverless o equipos que necesitan previews de PR.

Cloudflare Pages #

Es más reciente que Netlify pero la infraestructura de CDN de Cloudflare es difícil de superar. Para quien ya está en el ecosistema Cloudflare (DNS, protección DDoS), la integración es natural.

Lo bueno: CDN global rapidísimo, builds razonablemente rápidos, plan gratuito sin límites prácticos de ancho de banda (ilimitado), integración con el ecosistema Cloudflare (DNS, protección DDoS, analytics server-side).

Lo malo: Menos funcionalidades "de conveniencia" que Netlify. No tiene formularios nativos ni redirects con fichero de texto (usa _headers y _redirects, pero con limitaciones). La documentación es menos madura.

La he probado para algunas pruebas puntuales, poco más. Funciona bien, pero no me ha dado motivos para adoptarla como opción principal.

Ideal para: proyectos donde el rendimiento de entrega es prioritario y ya estás en el ecosistema Cloudflare.

StaticHost.eu #

Una alternativa europea que merece atención. StaticHost es un servicio de hosting pensado específicamente para webs estáticas, con una filosofía que me atrae: simplicidad, transparencia y servidores en Europa.

Lo bueno: Filosofía alineada con la web estática (sin funciones serverless, sin complejidad innecesaria). Precios claros. Servidores europeos. Soporte cercano — cuando hay un problema, hablas con personas, no con un chatbot. El proyecto avanza con paso firme y cada actualización demuestra que hay un criterio detrás.

Lo malo: Al ser un servicio más joven, todavía tiene algunas limitaciones técnicas. Nada que impida alojar un sitio estático, pero las opciones de configuración avanzada no están al nivel de los grandes. Es un servicio en crecimiento, y eso implica que no todo está pulido aún.

Me gusta lo que están construyendo. Es el tipo de servicio que quieres que funcione, porque representa una alternativa real a los gigantes estadounidenses.

Ideal para: proyectos estáticos que valoren privacidad, servidores europeos y un servicio con filosofía clara.

Bunny CDN #

Y aquí es donde he acabado. Bunny CDN es, técnicamente, una CDN — no una plataforma de hosting estático al uso. Pero su servicio de Storage + Pull Zone funciona perfectamente como hosting para webs estáticas, y con una flexibilidad que las plataformas especializadas no ofrecen.

Lo bueno: Red global de servidores rápida y fiable. Puedo subir ficheros por FTP, usar su API, o automatizar el despliegue desde GitHub con Actions — cada proyecto puede usar el flujo que más le convenga. El panel de control es claro y sin artificios. Los precios son de pago por uso real, sin sorpresas. Y lo que más me convence: puedo agrupar todos mis proyectos en un mismo proveedor con un mismo flujo de trabajo.

Lo malo: No es "conectar repositorio y olvidarse" como Netlify o Cloudflare Pages. Hay que configurar el storage, la pull zone, los headers, el certificado SSL. No es difícil, pero es trabajo que en otras plataformas viene hecho. Tampoco tiene builds automáticos — tú haces el build y subes el resultado.

Para mí, esa "desventaja" es parte del atractivo. Quiero controlar el proceso de despliegue, no delegarlo en una caja negra.

Ideal para: desarrolladores que quieren flexibilidad real, múltiples vías de despliegue y una CDN de verdad detrás del hosting.

GitHub Pages #

La opción gratuita más simple. Sin build automático (necesitas GitHub Actions o hacer el build local), pero para proyectos personales es difícil de superar en simplicidad.

Lo bueno: Gratis, integrado con GitHub, sin configuración si usas Jekyll. Con un GitHub Action de unas pocas líneas puedes desplegar Eleventy sin problemas.

Lo malo: Sin CDN propio (aunque puedes poner Cloudflare delante), dominio personalizado con HTTPS requiere configuración manual, sin headers personalizables.

Ideal para: proyectos personales, documentación de repositorios, webs de organizaciones de GitHub.

Un servidor propio (VPS) #

Para quien quiere control total. Un VPS barato (5-10€/mes) con Nginx sirviendo ficheros estáticos es la opción más controlable.

Lo bueno: Control absoluto sobre headers, redirects, configuración del servidor, logs. Sin límites artificiales de ningún plan. Puedes alojar múltiples sitios.

Lo malo: Tú te encargas de todo: actualizaciones de seguridad, certificados SSL (Let's Encrypt lo automatiza, pero hay que configurarlo), backups, monitorización. Si el servidor cae, es tu problema.

Ideal para: desarrolladores que quieren control total y no les importa la administración de sistemas.

FTP a un hosting compartido #

Sí, sigue existiendo. Y para un sitio estático, funciona perfectamente. Generas el build local, subes por FTP, listo.

Lo bueno: Funciona con cualquier hosting. No necesitas Git, ni CI/CD, ni cuenta en ningún servicio. Si ya tienes hosting para otra cosa, no cuesta nada adicional.

Lo malo: Despliegue manual (o script que automatices tú). Sin previews, sin rollbacks fáciles, sin builds automáticos.

Ideal para: proyectos donde ya tienes un hosting contratado y no quieres añadir otra plataforma.

Mi recorrido y dónde he acabado #

Mi camino ha sido: Netlify → StaticHost → Bunny CDN. Cada salto tenía un motivo.

De Netlify me fui porque quería algo más simple y más alineado con mi forma de trabajar. StaticHost me atrajo por su filosofía — un servicio europeo, pensado para webs estáticas, sin artificios. Me gusta mucho lo que están haciendo y sigo su evolución con interés.

Pero al final me decanté por Bunny CDN por una razón práctica: flexibilidad. Puedo subir ficheros por FTP cuando estoy haciendo pruebas rápidas, usar su API para scripts de despliegue, o configurar GitHub Actions para proyectos donde quiero automatización completa. Cada proyecto elige su flujo. Y al final, por comodidad, estoy agrupando todos los proyectos en un mismo proveedor. Este sitio y Bilbonauta están en Bunny.

No es la solución para todo el mundo. Si lo que buscas es conectar un repositorio y olvidarte, Netlify o Cloudflare Pages siguen siendo opciones excelentes. Pero si prefieres entender y controlar cada paso del despliegue, Bunny merece que le eches un vistazo.

Lo importante no es qué plataforma elijas, sino entender que para un sitio estático, el hosting es un problema resuelto. No dejes que la decisión de dónde alojar te retrase. Pon los ficheros en cualquier servidor y ocúpate de lo que importa: el contenido.

Lo que realmente necesitas #

Pensemos en las interacciones típicas de un sitio web:

• Menú hamburguesa que se abre y cierra
• Toggle de tema claro/oscuro
• Elementos que aparecen al hacer scroll
• Enlaces externos que se abren en pestaña nueva
• Un banner de cookies

¿Cuánto JavaScript necesitas para eso? Veamos el menú hamburguesa completo:

document.addEventListener("DOMContentLoaded", () => {
  const btn = document.querySelector(".nav-hamburger");
  const panel = document.getElementById("nav-panel");
  const overlay = document.getElementById("nav-overlay");
  const close = document.querySelector(".nav-panel__close");

  function open() {
    panel.classList.add("is-open");
    overlay.classList.add("is-open");
    document.body.style.overflow = "hidden";
    btn.setAttribute("aria-expanded", "true");
  }

  function cerrar() {
    panel.classList.remove("is-open");
    overlay.classList.remove("is-open");
    document.body.style.overflow = "";
    btn.setAttribute("aria-expanded", "false");
  }

  btn.addEventListener("click", open);
  close.addEventListener("click", cerrar);
  overlay.addEventListener("click", cerrar);
  document.addEventListener("keydown", e => {
    if (e.key === "Escape") cerrar();
  });
});

Son 25 líneas. Funciona en todos los navegadores, no tiene dependencias, no necesita build step, y hace exactamente lo que tiene que hacer. ¿Merece la pena cargar React (40KB+ gzipped) más React DOM para esto?

Lo que ha cambiado #

La razón por la que jQuery era imprescindible en 2010 era que JavaScript y el DOM eran un campo de minas. addEventListener no existía en IE. Seleccionar elementos era verboso. Las diferencias entre navegadores eran enormes.

Hoy tenemos:

• document.querySelector y querySelectorAll — selectores CSS nativos
• classList — manipulación de clases sin regex
• addEventListener — universal y consistente
• fetch — peticiones HTTP sin XMLHttpRequest
• IntersectionObserver — detección de visibilidad sin cálculos de scroll
• Template literals, destructuring, arrow functions, async/await

El lenguaje que justificó la existencia de jQuery ha mejorado tanto que la librería ya no tiene razón de ser.

IntersectionObserver: el ejemplo perfecto #

Antes, para saber si un elemento era visible en pantalla necesitabas escuchar el evento scroll, calcular la posición del elemento con getBoundingClientRect(), y comparar con el viewport. Era costoso y propenso a errores.

Ahora:

const observer = new IntersectionObserver((entries) => {
  entries.forEach(entry => {
    if (entry.isIntersecting) {
      entry.target.classList.add("visible");
      observer.unobserve(entry.target);
    }
  });
}, { threshold: 0.1 });

document.querySelectorAll(".reveal").forEach(el => {
  observer.observe(el);
});

Esto es lo que uso en este sitio para las animaciones de entrada. No necesité instalar aos.js (24KB), ni scroll-reveal (22KB), ni mucho menos una librería de animación completa. Diez líneas de JavaScript vanilla y las transiciones se definen en CSS, donde pertenecen.

Cuándo sí necesitas un framework #

No soy un fundamentalista. Los frameworks tienen su lugar:

• Aplicaciones con estado complejo — un dashboard con datos en tiempo real, un editor visual, una herramienta de gestión. Aquí la reactividad de React o Vue aporta valor real.
• SPAs con mucha interactividad — donde la navegación client-side y la gestión de estado justifican la complejidad.
• Equipos grandes — donde la estructura que impone un framework ayuda a la coordinación.

Pero un blog, una web corporativa, un portfolio, una landing page... no son aplicaciones. Son documentos. Y los documentos se resuelven con HTML, CSS y una pizca de JavaScript.

El coste oculto #

Cada framework que añades tiene un coste que va más allá del tamaño del bundle:

• Dependencia de un ecosistema que puede cambiar de versión mayor cada año
• Build step obligatorio — ya no puedes abrir un HTML y trabajar
• Curva de aprendizaje para ti y para quien mantenga el proyecto después
• Actualizaciones de seguridad que tienes que seguir
• La tentación de "componentizar" todo, incluso lo que no lo necesita

JavaScript vanilla no tiene ninguno de estos costes. Funciona hoy y funcionará dentro de diez años. No se deprecia, no cambia de API, no necesita migración.

HTML semántico: la base de todo #

La forma más efectiva de hacer una web accesible es usar las etiquetas HTML correctas. No es un consejo sofisticado, pero es el que más se ignora:

<!-- Mal -->
<div class="boton" onclick="enviar()">Enviar</div>

<!-- Bien -->
<button type="submit">Enviar</button>

El <button> es focusable por teclado, activable con Enter y Space, anunciado como "botón" por los lectores de pantalla, y gestiona correctamente los estados :focus y :active. El <div> no hace nada de eso — tendrías que reimplementarlo todo con JavaScript y ARIA.

Lo mismo aplica para:

• <nav> en vez de <div class="nav">
• <main> en vez de <div class="contenido">
• <header> y <footer> en vez de divs genéricos
• <h1>-<h6> en orden jerárquico, sin saltar niveles
• <a> para navegación, <button> para acciones

Contraste de color #

Las WCAG piden un ratio de contraste mínimo de 4.5:1 para texto normal y 3:1 para texto grande (18px+ o 14px+ en negrita). Es una regla simple con herramientas simples para verificarla.

En las DevTools de Chrome y Firefox, al inspeccionar un color de texto, te muestra el ratio de contraste directamente. Si está por debajo del mínimo, cámbialo.

Los errores más comunes:

• Texto gris claro sobre fondo blanco (esos grises "elegantes" de #999 o #aaa que no pasan el mínimo)
• Texto sobre imágenes sin overlay oscuro
• Placeholders de formulario demasiado claros (los placeholders también necesitan contraste)

Textos alternativos en imágenes #

Toda imagen con contenido informativo necesita un alt descriptivo:

<!-- Decorativa: alt vacío -->
<img src="ornamento.svg" alt="">

<!-- Informativa: descripción del contenido -->
<img src="grafico-ventas.png" alt="Gráfico de ventas trimestrales mostrando un crecimiento del 15%">

Un alt vacío (alt="") le dice al lector de pantalla "ignora esta imagen". Omitir el atributo alt completamente hace que el lector de pantalla lea el nombre del fichero, que suele ser algo como "IMG_20240315_142356.jpg". Eso no ayuda a nadie.

Navegación por teclado #

Toda funcionalidad de la web debe ser accesible con teclado. Esto significa:

• Tab navega entre elementos interactivos
• Enter/Space activa botones y enlaces
• Escape cierra modales y menús
• El foco es visible en todo momento

El error más dañino es eliminar el outline del foco:

/* NUNCA hagas esto sin proporcionar una alternativa */
*:focus { outline: none; }

Si el outline por defecto te parece feo, reemplázalo con uno mejor, pero no lo elimines:

:focus-visible {
  outline: 2px solid var(--color-acento);
  outline-offset: 2px;
}

:focus-visible es mejor que :focus porque solo se activa con navegación por teclado, no con clics de ratón. Así mantienes la indicación visual para quien la necesita sin molestar a quien usa ratón.

Skip to content #

Un enlace oculto al principio del documento que permite a los usuarios de teclado saltar directamente al contenido principal, sin tener que tabular por toda la navegación:

<body>
  <a href="#contenido" class="skip-link">Saltar al contenido principal</a>
  <header>...</header>
  <main id="contenido">...</main>
</body>

.skip-link {
  position: absolute;
  left: -9999px;
}
.skip-link:focus {
  position: fixed;
  top: 0;
  left: 0;
  z-index: 999;
  /* estilos visibles */
}

Es una de las técnicas más simples de implementar y de las más apreciadas por usuarios de teclado y lectores de pantalla.

Formularios con labels #

Cada campo de formulario necesita un <label> asociado:

<label for="email">Tu email</label>
<input type="email" id="email" name="email">

No un placeholder como sustituto del label. No un div con texto al lado. Un <label> con for apuntando al id del input. Es la forma en que los lectores de pantalla saben qué pedir al usuario.

Tamaño de áreas táctiles #

En móvil, los elementos interactivos deben tener al menos 44x44 píxeles de área de toque. Un enlace de texto pequeño en una lista puede ser difícil de pulsar para personas con motricidad reducida — o para cualquiera en un autobús en movimiento.

.nav__link {
  padding: 0.75em 1em;
  min-height: 44px;
  display: flex;
  align-items: center;
}

No es difícil, es hábito #

Ninguna de estas prácticas es técnicamente compleja. No requieren librerías, plugins ni conocimientos especializados. Son decisiones de implementación que cualquier desarrollador puede tomar si es consciente de ellas.

La accesibilidad no es un feature que se añade al final del proyecto. Es una forma de escribir código desde el principio. Y como toda buena práctica, se convierte en automática con el tiempo.

/* El enfoque antiguo */
h1 { font-size: 1.5rem; }
@media (min-width: 768px) { h1 { font-size: 2rem; } }
@media (min-width: 1200px) { h1 { font-size: 2.5rem; } }

Funciona, pero tiene un problema: los saltos son bruscos. En 767px tienes un tamaño, en 768px otro. Y tienes que decidir cuántos breakpoints usar, qué valores poner en cada uno, y mantener toda esa cascada cuando cambias la escala.

La función clamp() #

clamp() acepta tres valores: un mínimo, un valor preferido (fluido), y un máximo.

h1 {
  font-size: clamp(1.5rem, 1.2rem + 1.5vw, 2.5rem);
}

Esto significa: el tamaño será 1.2rem + 1.5vw, pero nunca menor que 1.5rem ni mayor que 2.5rem. El texto crece suavemente con el viewport, sin saltos, sin breakpoints.

Cómo calcular los valores #

El valor fluido (1.2rem + 1.5vw) no es arbitrario. Se calcula a partir de los dos extremos que quieres:

• Viewport mínimo: 320px → tamaño mínimo: 1.5rem (24px)
• Viewport máximo: 1200px → tamaño máximo: 2.5rem (40px)

La fórmula es:

valor fluido = mínimo + (máximo - mínimo) * ((100vw - viewport_min) / (viewport_max - viewport_min))

Simplificado:

pendiente = (40 - 24) / (1200 - 320) = 16 / 880 ≈ 0.01818
intercepto = 24 - (0.01818 * 320) = 24 - 5.818 ≈ 18.18px ≈ 1.136rem

Redondeando: clamp(1.5rem, 1.14rem + 1.82vw, 2.5rem).

No hace falta hacer esto a mano — hay calculadoras online. Pero entender la lógica te permite ajustar los valores con criterio en vez de copiar y pegar sin saber por qué.

Mi escala tipográfica #

En este sitio uso un enfoque ligeramente diferente al de aplicar clamp() a cada nivel por separado. Defino una sola variable base fluida y construyo el resto de la escala con multiplicadores:

:root {
  --fs-base: clamp(1rem, 1.5vw, 1.15rem);
  --fs-2: calc(var(--fs-base) * 0.75);
  --fs-1: calc(var(--fs-base) * 0.85);
  --fs0: var(--fs-base);
  --fs1: calc(var(--fs-base) * 1.2);
  --fs2: calc(var(--fs-base) * 1.45);
  --fs3: calc(var(--fs-base) * 1.75);
  --fs4: calc(var(--fs-base) * 2.1);
  --fs5: calc(var(--fs-base) * 2.5);
  --fs6: calc(var(--fs-base) * 3.2);
}

La ventaja de este enfoque es que toda la escala se mueve junta. Si cambio el clamp() de la base, todos los tamaños se reajustan proporcionalmente. No tengo que recalcular siete valores diferentes.

Además, para móvil uso una media query que reduce los multiplicadores de los niveles grandes, porque en pantallas pequeñas el contraste entre tamaños tiene que ser más sutil:

@media screen and (max-width: 45rem) {
  :root {
    --fs1: calc(var(--fs-base) * 1.15);
    --fs2: calc(var(--fs-base) * 1.3);
    --fs3: calc(var(--fs-base) * 1.5);
    --fs4: calc(var(--fs-base) * 1.7);
    --fs5: calc(var(--fs-base) * 2);
    --fs6: calc(var(--fs-base) * 2.5);
  }
}

Sí, estoy usando una media query — justo lo que este artículo pretende evitar. Pero el clamp() de la base se encarga de la fluidez continua, y la media query solo ajusta las proporciones de la escala en viewports estrechos. Es un híbrido pragmático: la transición es suave gracias a la base fluida, y los ratios se ajustan cuando realmente hace falta.

Tipografía fluida más allá del font-size #

clamp() no solo sirve para tamaños de texto. Lo uso para:

Espaciado vertical entre secciones:

:root {
  --space-l: clamp(1.5rem, 1.2rem + 1.5vw, 2.5rem);
  --space-xl: clamp(2rem, 1.5rem + 2.5vw, 4rem);
}

Interlineado que se ajusta al tamaño:

body {
  line-height: clamp(1.5, 1.4 + 0.2vw, 1.7);
}

Márgenes laterales:

.contenido {
  padding-inline: clamp(1rem, 0.5rem + 2vw, 3rem);
}

El resultado es un diseño que fluye de forma natural entre cualquier tamaño de pantalla, sin los saltos artificiales de las media queries.

Accesibilidad #

Un detalle importante: al usar rem como base y unidad mínima/máxima, la tipografía fluida respeta la configuración de tamaño de texto del usuario. Si alguien ha aumentado el tamaño base en su navegador, todos los rem escalan con él. Si usases solo px o solo vw, romperías esa preferencia.

La combinación de rem (accesible, respeta preferencias) con vw (fluido, se adapta al viewport) es lo que hace que clamp() sea la herramienta correcta para tipografía responsive.

Pero CSS ha cambiado. Y la pregunta que me hago ahora no es "¿qué preprocesador uso?" sino "¿necesito un preprocesador?". La respuesta, para la mayoría de mis proyectos, es no.

Lo que Sass resolvía #

Las razones principales por las que usábamos Sass eran:

1. Variables — para no repetir valores de colores, tamaños, fuentes
2. Nesting — para evitar selectores largos
3. Mixins — para reutilizar bloques de declaraciones
4. Funciones — para cálculos y transformaciones de color
5. Partials e imports — para organizar el código en ficheros

Veamos qué ha pasado con cada una.

Variables: custom properties ganan #

// Sass
$color-acento: #f86624;
.boton { background: $color-acento; }

/* CSS */
:root { --color-acento: #f86624; }
.boton { background: var(--color-acento); }

Hasta aquí parecen equivalentes. Pero las custom properties hacen algo que Sass no puede: cambiar en tiempo de ejecución. Un cambio de tema, un hover, una media query — las custom properties se recalculan en el navegador. Las variables Sass se resuelven en el build y desaparecen del CSS final.

/* Esto es imposible con Sass */
[data-theme="dark"] {
  --color-fondo: #111118;
}

Con Sass tendrías que duplicar todos los selectores que usan ese color. Con custom properties, cambias la variable y todo se actualiza automáticamente.

Nesting: CSS lo tiene (casi) #

CSS Nesting ya está disponible en los navegadores modernos:

.tarjeta {
  padding: 1rem;

  & .titulo {
    font-weight: 700;
  }

  &:hover {
    border-color: var(--color-acento);
  }
}

La sintaxis es ligeramente diferente (necesitas el & en más casos), pero funciona. Para proyectos que no necesitan soportar navegadores antiguos, el nesting nativo es suficiente.

Dicho esto, yo uso poco el nesting — prefiero selectores planos por claridad. Pero si era tu razón principal para usar Sass, ya no lo es.

Mixins: no los echo de menos #

Los mixins más comunes eran para vendor prefixes y patrones repetitivos. Los vendor prefixes ya no son necesarios para la mayoría de propiedades. Y los patrones repetitivos se resuelven mejor con custom properties:

/* En vez de un mixin de Sass para botones... */
.boton {
  padding: var(--boton-padding, 0.5em 1em);
  border-radius: var(--boton-radius, 0.25em);
  background: var(--boton-bg, var(--color-acento));
  color: var(--boton-color, white);
}

/* Variantes cambiando las variables */
.boton--grande {
  --boton-padding: 0.75em 1.5em;
  --boton-radius: 0.5em;
}

Más flexible que un mixin porque las variantes se pueden definir en cualquier contexto — incluso desde el HTML con style.

Funciones: CSS tiene calc(), clamp() y color-mix() #

Sass ofrecía darken(), lighten(), mix(). CSS ahora tiene color-mix():

.overlay {
  background: color-mix(in srgb, var(--color-acento) 15%, transparent);
}

Para cálculos numéricos, calc() y clamp() cubren todo lo que necesitas:

.grid {
  gap: calc(var(--space-base) * 2);
  font-size: clamp(1rem, 0.95rem + 0.25vw, 1.125rem);
}

Organización: la única ventaja real de Sass #

El único punto donde Sass sigue aportando algo es la organización en parciales con @use y @forward. CSS tiene @import, pero carga cada fichero como una petición HTTP separada, lo que es malo para el rendimiento.

Mi solución es diferente: uso eleventy-plugin-bundle para concatenar los ficheros CSS en build. Cada fichero CSS se incluye en orden en el layout base, y el plugin los une en un único bloque inline. La organización es por ficheros, la salida es un único bloque — lo mejor de ambos mundos sin Sass.

El build step que desaparece #

Esta es la ventaja más subestimada de abandonar Sass: no necesitas compilar tu CSS. No hay sass --watch, no hay plugin de Webpack, no hay dependencia de node-sass o dart-sass que se rompe al actualizar Node.

Abres un fichero CSS, lo editas, el navegador lo interpreta. Así de simple. Así debería ser.