El stack de agentes del ingeniero de diseño
Un agente de programación con IA puede pasar todas las pruebas que tengas y aun así poner un subtítulo en 19px, hardcodear #cccccc y desplazar el layout en un teléfono. Las pruebas verifican la lógica. Ninguna configuración de agente que yo haya usado verifica el oficio hasta que alguien agrega las verificaciones. Este artículo construye esa capa: seis verificaciones que obligan al trabajo de un agente a respetar una escala tipográfica, un sistema de color, un layout estable, un presupuesto de Lighthouse, las reglas WCAG y screenshots aprobados. Las verificaciones de tokens se ejecutan en tres lugares, y el primero es un hook que le avisa al agente de una violación mientras todavía está trabajando. Las demás verificaciones se ejecutan como comandos, en tu máquina o en CI. Ejecuté las configuraciones y los scripts de abajo contra los ejemplos de este artículo antes de publicarlos, y una sección cerca del final dice qué probé y qué no. Dos secciones después de las verificaciones, La capa de gusto y Qué se gana con el stack, tratan lo que ninguna de las verificaciones puede juzgar: si el resultado es bueno. El FAQ y tres secciones de referencia vienen después de ellas.
Actualización, 16 de noviembre de 2026: Reconstruí este artículo. La versión de abril describía el stack como infraestructura que yo ejecuto, cosa que no hago, y sus fragmentos de código no se habían ejecutado. Varias de sus cifras sobre este sitio estaban equivocadas. Qué cambió respecto a la versión de abril enumera cada corrección.
TL;DR
- La calidad de diseño se divide en partes que una máquina puede verificar (uso de tokens, estabilidad del layout, presupuestos de rendimiento, reglas WCAG, cambios visuales no intencionales) y una que no puede (el gusto).
- Una configuración de Stylelint, solo con reglas integradas, informa del valor crudo corriente: un tamaño de fuente, un peso, un valor de espaciado o un color que no es un token. Un script de 150 líneas informa de los problemas en las declaraciones que un cambio introduce. Ambos son un lint para errores de buena fe, no una frontera de seguridad. El script se ejecuta en tres lugares: un hook
PostToolUsede Claude Code, un hook pre-commit de git y CI. - Tres specs de Playwright cubren el layout en tres anchos, un escaneo de axe con etiquetas de WCAG 2.2 y líneas base de screenshots. Lighthouse CI sostiene los puntajes de categoría y el Cumulative Layout Shift.
- No ejecuto este stack en este sitio. Según el conteo del 16 de noviembre de 2026, su CSS contiene 691 tamaños de fuente crudos junto a 548 usos de tokens y 2850 declaraciones de color crudas, y su color de texto terciario mide 3,66:1 sobre negro, por debajo del 4,5:1 que WCAG AA pide para el texto de cuerpo. Esa deriva es el argumento a favor del stack.
- Pasar las seis verificaciones dice que ninguna verificación configurada encontró una violación en los archivos, las páginas y los anchos que cubre. No dice que el trabajo sea bueno.
Qué necesitan los ingenieros de diseño de los agentes
Un ingeniero puro pregunta si el código funciona. Un ingeniero de diseño hace seis preguntas más.
Consistencia visual. El espaciado sale de la escala de espaciado, así que las separaciones entre elementos se repiten. Un agente que agrega una tarjeta con margin-top: 13px en lugar de var(--spacing-md) ha agregado ruido que ninguna prueba unitaria ve.
Disciplina tipográfica. Cada font-size es un paso de la escala tipográfica, y cada font-weight es uno de los pesos que el sistema define. Un agente que establece un subtítulo en font-size: 19px ha inventado un paso, y la jerarquía se vuelve un poco menos legible.
Cumplimiento del sistema de color. Cada color es un token. Un agente que escribe color: #cccccc ha tomado una decisión de contraste que nadie revisó. En el tema oscuro de este sitio, ese gris mide 13,08:1 contra la página negra. En el tema claro, el mismo literal queda sobre un blanco roto a 1,53:1, muy por debajo del 4,5:1 que WCAG pide para el texto de cuerpo, porque un valor hardcodeado no cambia cuando cambia el tema.1
Conciencia de rendimiento. Un cambio visual tiene un costo de rendimiento. Los Core Web Vitals de Google le ponen números: Largest Contentful Paint dentro de 2,5 segundos, Cumulative Layout Shift de 0,1 o menos e Interaction to Next Paint de 200 milisegundos o menos, cada uno en el percentil 75 de las cargas de página reales.2 Una ejecución de laboratorio no puede ver a los usuarios reales, pero puede detectar una regresión antes que ellos.
Accesibilidad. Estructura semántica, orden de encabezados, etiquetas, contraste, foco. Un escáner encuentra la parte medible. El resto requiere un teclado, un lector de pantalla y una persona.
Gusto. Lo más difícil de codificar: coherencia entre elementos, moderación en la decoración, espacio en blanco que es intencional y no un sobrante. El gusto distingue un layout que sigue cada regla y se siente incorrecto de uno que sigue cada regla y se siente correcto.
El gusto es un sistema técnico con cuatro partes: restricciones, criterios de evaluación, reconocimiento de patrones y coherencia. Las primeras cinco preguntas caen bajo las dos primeras partes. Una regla de tokens es una restricción y un presupuesto es un criterio de evaluación, y una máquina puede verificar ambos. La sexta pregunta pertenece al reconocimiento de patrones y a la coherencia, que siguen en manos de una persona.
Seis componentes del stack del ingeniero de diseño
Ninguna de las piezas es nueva. Stylelint hace linting de CSS, Lighthouse CI hace aserciones sobre los informes de Lighthouse, axe-core escanea una página renderizada en busca de fallas de WCAG y Playwright compara screenshots. Lo que suele faltarle a la configuración de un agente es el ensamblaje: las verificaciones configuradas para un sistema de diseño concreto y colocadas donde el agente recibe el resultado mientras todavía está trabajando.
| Componente | Pregunta que responde | Herramienta |
|---|---|---|
| 1. Tokens de tipografía y espaciado | ¿Cada tamaño, peso y separación es un paso de una escala? | Stylelint |
| 2. Tokens de color | ¿Cada color es un token? | Stylelint |
| 3. Verificaciones de layout | ¿La página cabe y se queda quieta en los anchos que indicas? | Playwright |
| 4. Presupuesto de Lighthouse | ¿La página cumple los presupuestos que fijaste para el rendimiento y los aspectos básicos auditados? | Lighthouse CI |
| 5. Escaneo de accesibilidad | ¿La página renderizada rompe alguna regla de WCAG que una herramienta pueda detectar? | axe-core en Playwright |
| 6. Regresión visual | ¿Cambió algo que no debía cambiar? | Playwright |
1. Tokens de tipografía y espaciado
La regla de Robert Bringhurst para los tamaños de letra: “Usa la vieja escala conocida, o usa escalas nuevas de tu propia invención, pero limítate, al principio, a un conjunto modesto de intervalos distintos y relacionados”.3 En CSS, la escala es un conjunto de custom properties, y la verificación consiste en que un tamaño se escriba como una de ellas. Stylelint puede hacer esa verificación con reglas que trae incluidas.4 Este es el .stylelintrc.json completo. Cuatro de sus patrones empiezan con el mismo lookbehind largo, que solo exige que la coincidencia no esté dentro de una cadena entre comillas; la parte que hay que leer en cada uno es su final. Los nombres de los tokens son los de este sitio, así que sustitúyelos por los tuyos:
{
"rules": {
"declaration-property-value-allowed-list": {
"/^font-size$/i": ["/^var\\(--font-size-(xs|sm|base|lg|xl|[2-7]xl|display)\\)$/", "inherit"],
"/^font-weight$/i": ["/^var\\(--font-weight-(normal|medium|semibold|bold|black)\\)$/", "inherit"],
"/^(margin|padding|gap|row-gap|column-gap)/i": ["/^((var\\(--spacing-(xs|sm|md|lg|xl|[2-4]xl)\\)|0|auto)(\\s+|$))+$/"]
},
"declaration-property-value-disallowed-list": {
"/^(?!--)/": [
"/(?<=^([^\"']|\"(\\\\[\\s\\S]|[^\"\\\\])*\"|'(\\\\[\\s\\S]|[^'\\\\])*')*)(?<!url\\([^)\"']*)#[0-9a-f]{3,8}\\b/i",
"/(?<=^([^\"']|\"(\\\\[\\s\\S]|[^\"\\\\])*\"|'(\\\\[\\s\\S]|[^'\\\\])*')*)\\b(rgba?|hsla?|hwb|lab|lch|oklab|oklch|color|color-mix)\\(/i",
"/(?<=^([^\"']|\"(\\\\[\\s\\S]|[^\"\\\\])*\"|'(\\\\[\\s\\S]|[^'\\\\])*')*)\\\\/",
"/(?<=^([^\"']|\"(\\\\[\\s\\S]|[^\"\\\\])*\"|'(\\\\[\\s\\S]|[^'\\\\])*')*)\\/\\*/"
]
},
"color-named": ["never", { "ignoreProperties": ["/^--/"] }],
"property-disallowed-list": ["/^font$/i", "/\\\\/"]
}
}
Toma los tres errores de la sección anterior, más un peso que el sistema no define:
.card { margin-top: 13px; }
.card-title { font-size: 19px; font-weight: 650; }
.card-meta { color: #cccccc; }
Stylelint informa de cada uno:
$ npx stylelint examples/card.css
examples/card.css
1:21 ✖ Disallowed value "13px" for property "margin-top" declaration-property-value-allowed-list
2:26 ✖ Disallowed value "19px" for property "font-size" declaration-property-value-allowed-list
2:45 ✖ Disallowed value "650" for property "font-weight" declaration-property-value-allowed-list
3:21 ✖ Disallowed value "#cccccc" for property "color" declaration-property-value-disallowed-list
✖ 4 problems (4 errors, 0 warnings)
Antes de los detalles, para qué sirve esta configuración. Atrapa el error corriente, un tamaño crudo, un color crudo o un peso sin token, en el momento en que un agente o una persona lo comete. Es un lint, no una frontera de seguridad. CSS tiene muchas formas de escribir una misma cosa, y un CSS escrito para esquivar estos patrones puede esquivarlos. Sí informa de las evasiones que conozco: nombres de propiedad en mayúsculas, escapes como f\6f nt-size, una cadena que continúa en la línea siguiente, una comilla escondida en un comentario dentro de un valor, casi siempre rechazando la construcción sin más. Tres cosas que no cubre se enumeran bajo las reglas de color, y Cómo probé esto dice cómo se encontraron esas evasiones.
Seis decisiones en estas reglas son deliberadas:
- Los nombres de propiedad coinciden sin importar mayúsculas o minúsculas. Cada clave es una expresión regular con el flag
i, porque los nombres de propiedad de CSS no distinguen entre mayúsculas y minúsculas yFONT-SIZE: 19pxes la misma declaración quefont-size: 19px. - Los pasos se enumeran por nombre.
var(--font-size-md)falla porque la escala no tiene un pasomd, yvar(--font-size-lg, 19px)falla porque un fallback crudo es un segundo tamaño que nadie revisó. - El shorthand
fontestá prohibido.font: 600 19px/1.2 system-uiestablece un tamaño y un peso en una propiedad que la primera regla nunca lee. - Los escapes con barra invertida se rechazan. CSS permite que
f\6f nt-sizeequivalga afont-sizeyr\67 b(argb(. Estas reglas comparan el texto tal como está escrito y no decodifican los escapes, así que la configuración informa de una barra invertida en un nombre de propiedad, y de una en el valor de una propiedad que no es una custom property cuando está fuera de una cadena entre comillas. - Un comentario dejado dentro de un valor se rechaza. El parser de Stylelint descarta un comentario que tiene espacio alrededor, como en
0 /* note */ auto, pero en mis pruebas conservó uno que toca a sus vecinos, como enurl(a)/*x*/#fff. Una comilla dentro de un comentario conservado desbarataría el manejo de cadenas descrito bajo las reglas de color, así que la configuración informa de/*fuera de una cadena entre comillas en esos valores. - El espaciado acepta tokens,
0oauto. La clave cubremargin,paddingygapcon sus propiedades longhand, incluidasrow-gapycolumn-gap. Los desplazamientos comotopeinsetquedan a tu criterio: agrégalos si tu layout los establece a partir de la escala. Un valor que tiene que romper la regla, como un margen negativo construido concalc(), lleva un comentariostylelint-disable-next-linecon una razón. La excepción queda entonces en el diff, donde un revisor la ve.
2. Tokens de color
Las reglas de color están en el mismo archivo. declaration-property-value-disallowed-list tiene como clave /^(?!--)/, que coincide con toda propiedad que no sea una custom property, y sus patrones buscan un valor hexadecimal, un nombre de función de color, una barra invertida o un marcador de comentario en el valor. color-named informa de red, con las custom properties exentas mediante su opción ignoreProperties. Juntas apuntan a una sola cosa: un color crudo va en el valor de una custom property y en ningún otro lugar.
Stylelint parsea el archivo, así que sabe a qué propiedad pertenece cada valor. Un token definido en medio de un bloque :root de varias líneas pasa, y border: 1px solid rgba(255, 255, 255, 0.6) falla aunque el color sea la tercera palabra del valor. Aun así, el valor mismo se compara como texto, no se parsea. Por eso cada patrón empieza con un lookbehind que exige que toda comilla anterior a la coincidencia esté cerrada, incluida una cadena que un salto de línea escapado continúa en la línea siguiente, lo que evita que content: "#123" y url("sprite(1).svg#fade") se lean como colores. El patrón hexadecimal tiene un segundo lookbehind para un url(sprite.svg#fade) sin comillas. Esto es coincidencia de patrones con parches, no un parser de valores de CSS, y se sostiene en los casos que probé.
Tres límites. La regla no impide que un agente defina una custom property nueva y la use. Eso llega al diff como un token nuevo, que es justo lo que una persona debe revisar. color-named no informa de transparent, currentColor ni de palabras clave de color del sistema como CanvasText, así que esas pasan. Y un token no es una garantía de contraste. Mi token de texto terciario es blanco al 40% de opacidad. Sobre la página negra se compone a 3,66:1, lo que supera el 3:1 de WCAG para texto grande y no alcanza el 4,5:1 para texto de tamaño de cuerpo.15 El contraste le corresponde al escaneo de accesibilidad del componente 5.
3. Verificaciones de layout
Dos fallas se esconden en anchos que nadie miró: contenido más ancho que el viewport y contenido que se mueve después de pintarse. Los componentes 3, 5 y 6 son specs de Playwright y comparten un playwright.config.js que inicia el sitio y establece la URL base. El sitio de prueba son dos pequeñas páginas estáticas, / y /blog/:
import { defineConfig } from '@playwright/test';
export default defineConfig({
testDir: 'tests',
use: { baseURL: 'http://127.0.0.1:4173' },
webServer: {
// Any command that serves the site on this port.
command: 'python3 -m http.server 4173 --directory site',
url: 'http://127.0.0.1:4173',
reuseExistingServer: !process.env.CI,
},
});
La spec de layout carga la página en tres anchos y hace aserciones sobre ambas fallas:
import { test, expect } from '@playwright/test';
for (const width of [375, 768, 1440]) {
test(`layout holds at ${width}px`, async ({ page }) => {
await page.setViewportSize({ width, height: 900 });
await page.addInitScript(() => {
window.layoutShift = 0;
new PerformanceObserver((list) => {
for (const entry of list.getEntries())
if (!entry.hadRecentInput) window.layoutShift += entry.value;
}).observe({ type: 'layout-shift', buffered: true });
});
await page.goto('/');
await page.waitForTimeout(1000);
const { measured, overflow, shift } = await page.evaluate(() => ({
measured: PerformanceObserver.supportedEntryTypes.includes('layout-shift'),
overflow: document.documentElement.scrollWidth - document.documentElement.clientWidth,
shift: window.layoutShift,
}));
expect(measured, 'browser reports layout-shift entries').toBe(true);
expect(overflow, 'pixels of horizontal overflow').toBe(0);
expect(shift, 'layout shift during load').toBeLessThanOrEqual(0.1);
});
}
El número de desplazamiento es la suma de las entradas layout-shift que el frame principal de la página informa desde la navegación hasta un segundo después del evento load. El CLS es la mayor ráfaga de desplazamientos, no el total, así que, para las entradas que esa ventana observa, la suma es al menos tan grande como su CLS, y mantenerla en 0,1 es al menos igual de estricto.6 No es una medición de CLS. El CLS abarca toda la vida de la página y cuenta los desplazamientos dentro de iframes; la spec no ve ni un desplazamiento que ocurre más tarde, como uno posterior a una interacción, ni uno dentro de un iframe. La primera aserción hace que la prueba falle en un navegador que no informa entradas layout-shift, así que la spec no puede pasar sin medir. La ejecuté en el Chromium de Playwright, donde mide, y en el WebKit de Playwright, donde esa aserción falló.
Contra la página de inicio limpia pasaron los tres anchos. Contra una copia que inyecta un banner de 240px de alto 300 milisegundos después de la carga y contiene un bloque con un ancho fijo de 600px, fallaron los tres: la prueba de 375px con 249 píxeles de desbordamiento horizontal, la de 768px, donde el bloque cabe, con un desplazamiento de 0,227, y la de 1440px con un desplazamiento de 0,107.
4. Presupuesto de Lighthouse
Lighthouse CI ejecuta Lighthouse varias veces contra una página servida y hace fallar el build cuando una aserción no se cumple. Este es el lighthouserc.json:
{
"ci": {
"collect": {
"startServerCommand": "python3 -u -m http.server 4173 --directory site",
"startServerReadyPattern": "Serving HTTP",
"url": ["http://127.0.0.1:4173/", "http://127.0.0.1:4173/blog/"],
"numberOfRuns": 3
},
"assert": {
"assertions": {
"categories:performance": ["error", { "minScore": 0.9, "aggregationMethod": "median" }],
"categories:accessibility": ["error", { "minScore": 1, "aggregationMethod": "pessimistic" }],
"categories:best-practices": ["error", { "minScore": 1, "aggregationMethod": "pessimistic" }],
"categories:seo": ["error", { "minScore": 1, "aggregationMethod": "pessimistic" }],
"cumulative-layout-shift": ["error", { "maxNumericValue": 0.1, "aggregationMethod": "pessimistic" }]
}
}
}
}
Qué hacen las claves, según la documentación de configuración de Lighthouse CI:7
categories:<id>hace una aserción sobre un puntaje de categoría de 0 a 1. Unperformancea secas no es una clave de categoría. Lighthouse CI lo lee como un ID de auditoría, no encuentra tal auditoría y hace fallar la ejecución sea cual sea el puntaje.cumulative-layout-shiftes un ID de auditoría, y la aserción se hace sobre su valor numérico. El límite de 0,1 es la línea de Google para un buen puntaje.6 Bájalo si la página ya se mantiene por debajo de un número menor.numberOfRunsrecoge tres informes por cada URL, porque los puntajes se mueven entre ejecuciones.aggregationMethoddefine cómo se agrega el valor de la aserción entre las tres ejecuciones antes de compararlo con el umbral. El valor por defecto esoptimistic, el valor con más probabilidades de pasar, así que lo establezco a mano:medianpara el rendimiento, el puntaje ruidoso, ypessimistic, el valor con menos probabilidades de pasar, para el resto.startServerCommandes lo que sea que sirva tu sitio, ystartServerReadyPatternes el texto que imprime una vez que está escuchando.
Fija cada mínimo en un número que la página sostenga hoy. Un presupuesto que la página ya incumple hace fallar todos los builds y no dice nada sobre el cambio que tiene delante. Estos son presupuestos absolutos, no una comparación con el build anterior: un puntaje de rendimiento que cae de 100 a 95 sigue pasando un mínimo de 0,9.
npx lhci autorun terminó con código 0 en el sitio de prueba limpio. En la copia con el banner tardío terminó con código 1, con el CLS en 0,232 frente al límite de 0,1 y el rendimiento en 0,89 frente a 0,9. En una copia con texto de bajo contraste terminó con código 1, con la accesibilidad en 0,9. Por defecto, Lighthouse carga la página en un solo ancho de teléfono emulado, 412px en los informes que recogí, y por eso la spec de layout del componente 3 verifica cada ancho por separado.
5. Escaneo de accesibilidad
axe-core se ejecuta dentro de un navegador real contra la página renderizada, así que trabaja a partir de los estilos computados y no solo del marcado. @axe-core/playwright lo mete en una prueba de Playwright:
import { test, expect } from '@playwright/test';
import AxeBuilder from '@axe-core/playwright';
for (const path of ['/', '/blog/']) {
test(`axe finds no WCAG A or AA violations on ${path}`, async ({ page }) => {
await page.goto(path);
const results = await new AxeBuilder({ page })
.withTags(['wcag2a', 'wcag2aa', 'wcag21a', 'wcag21aa', 'wcag22aa'])
.analyze();
expect(results.violations).toEqual([]);
});
}
Cada etiqueta cubre una versión de WCAG en un nivel, así que wcag22aa por sí sola ejecutaría únicamente lo que WCAG 2.2 agregó en AA. La lista nombra cada versión y nivel que el escaneo debe incluir.8 La etiqueta de 2.2 tiene que estar ahí: el W3C “aconseja usar WCAG 2.2 para maximizar la aplicabilidad futura de los esfuerzos de accesibilidad”.1 La aserción es toEqual([]), sin margen para violaciones conocidas. axe también devuelve un array incomplete, que su documentación llama elementos de revisión: nodos sobre los que no pudo decidir en un sentido ni en otro. Esta spec no lo lee, así que un resultado aprobado significa que axe no encontró ninguna falla de la que estuviera seguro, no que nada necesite revisión.8
Contra una copia del sitio de prueba cuyo texto de tarjeta era blanco al 40% de opacidad sobre #111111, el escaneo hizo fallar la página de inicio en la regla color-contrast de axe: 3,81:1 medido, 4,5:1 esperado. La segunda página, que ese cambio no tocó, pasó, y las dos páginas del sitio limpio pasaron.
Lo que un escaneo no puede encontrar sigue siendo manual. La documentación de Playwright lo dice directamente: “muchos problemas de accesibilidad solo pueden descubrirse mediante pruebas manuales”.9 El foco después de un swap de HTMX, el orden de teclado a través de contenido dinámico y lo que un lector de pantalla anuncia ante un cambio de estado necesitan interacción programada o una persona.
6. Regresión visual
Las cinco verificaciones anteriores prueban una propiedad cada una. Una comparación de screenshots es la amplia: falla cuando una página capturada difiere, en más de la tolerancia que fijes, de la última versión que una persona aprobó. toHaveScreenshot de Playwright lo hace en pocas líneas:
import { test, expect } from '@playwright/test';
for (const width of [375, 768, 1440]) {
test(`home page matches its baseline at ${width}px`, async ({ page }) => {
await page.setViewportSize({ width, height: 900 });
await page.goto('/');
await expect(page).toHaveScreenshot(`home-${width}.png`, {
fullPage: true,
maxDiffPixelRatio: 0.001,
});
});
}
La primera ejecución no tiene nada contra qué comparar. Escribe las imágenes de línea base y falla con un mensaje que empieza por “A snapshot doesn’t exist.” Las ejecuciones posteriores comparan, y maxDiffPixelRatio deja que un píxel de cada mil difiera antes de que una prueba falle. Que un píxel cuente como distinto es un ajuste aparte, threshold, que dejé en su valor por defecto de 0,2.10 Para simular un efecto secundario, agregué 3px de padding a la tarjeta, un cambio lo bastante pequeño como para pasar inadvertido en una revisión. Los tres anchos fallaron. A 375px, la página había pasado de 1002px a 1010px de alto, y 7064 píxeles diferían.
Tres cosas que conviene saber antes de confiar en ella. Las líneas base pertenecen a una plataforma: las mías se escribieron como home-375-darwin.png, y Playwright advierte que el renderizado varía según el sistema operativo, el hardware y el modo headless, así que las líneas base tienen que salir del entorno que las va a comparar.10 Un screenshot cubre solo lo que captura: aquí, una página en tres anchos, en reposo, sin nada con hover, con foco ni abierto. Y un diff dice que algo cambió, no si el cambio es una mejora. Una persona mira el diff y luego corrige la página o acepta el nuevo aspecto con npx playwright test --update-snapshots.
Servicios alojados como Percy y Chromatic combinan el mismo tipo de comparación con una pantalla de revisión. BackstopJS, que la versión anterior de este artículo nombraba junto a ellos, ahora abre su README con “BackstopJS necesita un nuevo mantenedor/propietario”.11
Dónde se ejecutan las verificaciones
Una verificación que se ejecuta después de que el agente terminó produce un informe para que yo lo lea. Una verificación que se ejecuta mientras el agente trabaja le da la oportunidad de corregir la línea. Las reglas de tokens se ejecutan en tres lugares desde un solo script, tools/token-lint.mjs.
Mi codebase no está limpio, y muchos no lo están. Una verificación que responde a cada edición con cientos de problemas viejos es inutilizable, así que el script informa de lo que el cambio introduce.
Hace linting del archivo completo e informa de los problemas en las declaraciones que el cambio introduce, junto con cualquier problema que quede fuera de toda declaración, como un error de sintaxis. Como hook compara el archivo en disco con el último commit; en el commit (--cached), la copia en staging con el último commit; en CI (un rango A...B), el commit en B con la merge base de A y B. La regla a la que apunto es corta: si la versión anterior contiene la misma declaración, carácter por carácter, bajo los mismos encabezados, no es nueva; de lo contrario, lo es. Ante la duda, el script prefiere volver a informar de un problema viejo antes que dejar pasar uno nuevo. Qué cuenta como nuevo tiene la regla completa; este es el script:
#!/usr/bin/env node
// Reports Stylelint problems only in the CSS declarations a change introduces.
// Claude Code PostToolUse hook: node tools/token-lint.mjs (tool call JSON on stdin)
// git pre-commit hook: node tools/token-lint.mjs --cached
// CI: node tools/token-lint.mjs origin/main...HEAD
import { execFileSync } from 'node:child_process';
import { readFileSync } from 'node:fs';
import { basename, dirname } from 'node:path';
import postcss from 'postcss';
import stylelint from 'stylelint';
// File names are passed to git as literal paths, never as patterns.
const git = (...args) =>
execFileSync('git', args, {
encoding: 'utf8',
env: { ...process.env, GIT_LITERAL_PATHSPECS: '1' },
maxBuffer: 64 * 1024 * 1024,
stdio: ['ignore', 'pipe', 'ignore'],
});
// Runs git for the two calls that locate the repository; outside one, says so and stops.
// Only git's closing newline is removed, because a path may begin or end with a space.
const repo = (...args) => {
try {
return git('rev-parse', ...args).replace(/\n$/, '');
} catch {
console.error('token-lint: not inside a git repository, so nothing was checked.');
process.exit(1);
}
};
const [range = 'HEAD'] = process.argv.slice(2);
const hook = process.argv.length === 2;
let files;
if (hook) {
const file = JSON.parse(readFileSync(0, 'utf8')).tool_input?.file_path ?? '';
if (!file.endsWith('.css')) process.exit(0);
process.chdir(dirname(file));
files = [repo('--show-prefix') + basename(file)];
}
process.chdir(repo('--show-toplevel'));
if (!hook) {
files = git('diff', '--name-only', '-z', '--diff-filter=ACMR', range).split('\0');
files = files.filter((file) => file.endsWith('.css'));
}
// The two versions each mode compares. An empty revision is the index; null is the file on disk.
// hook, or one revision: that revision (HEAD for the hook) -> disk
// --cached: HEAD -> index
// A...B (or A..B): the merge base of A and B (or A) -> B
const dots = /\.\.\.?/;
function versions() {
if (range === '--cached') return ['HEAD', ''];
if (!dots.test(range)) return [range, null];
const [a, b] = range.split(dots).map((revision) => revision || 'HEAD');
return [range.includes('...') ? git('merge-base', a, b).trim() : a, b];
}
const [before, after] = versions();
const show = (revision, file) => git('show', `${revision}:${file}`);
// CSS turns CRLF, a lone CR and a form feed into LF before it reads anything, so both versions
// get the same treatment. Nothing else in the text is changed before it is compared.
const lf = (code) => code.replace(/\r\n?|\f/g, '\n');
// Every declaration in a stylesheet, keyed by source text alone: the characters of the
// declaration itself, and before them the header of each rule and at-rule around it, from the
// header's first character through its opening brace. Where the text cannot be pinned down
// exactly, the key is a symbol, which equals nothing, so the declaration counts as new.
function declarations(code) {
const root = postcss.parse(code);
const { css } = root.source.input; // the text PostCSS read: the same, less a byte-order mark
const lineStart = [0];
for (let i = css.indexOf('\n'); i !== -1; i = css.indexOf('\n', i + 1)) lineStart.push(i + 1);
const index = ({ line, column }) => lineStart[line - 1] + column - 1;
// PostCSS does not record where a header's brace is. Its length comes from the pieces PostCSS
// parsed, and the text is used only if the file holds exactly those characters there.
const header = ({ type, name, params, selector, raws, source }) => {
const pieces =
type === 'atrule'
? ['@', name, raws.afterName, raws.params?.raw ?? params, raws.between, '{']
: [raws.selector?.raw ?? selector, raws.between, '{'];
const from = index(source.start);
const text = css.slice(from, from + pieces.join('').length);
return text === pieces.join('') ? text : Symbol('header not found');
};
// A declaration ends at its semicolon. Without one, PostCSS drops trailing white space from
// the end it reports, escaped white space included, so the text runs on to the closing brace
// of the rule around it (or to the end of the file, outside any rule).
const declaration = ({ parent, source: { start, end } }) => {
if (css[index(end)] === ';') return css.slice(index(start), index(end) + 1);
if (parent.type === 'root') return css.slice(index(start));
const brace = index(parent.source.end);
return css[brace] === '}' ? css.slice(index(start), brace) : Symbol('closing brace not found');
};
const found = [];
root.walkDecls((decl) => {
const { start, end } = decl.source;
const parts = [declaration(decl)];
for (let node = decl.parent; node.type !== 'root'; node = node.parent)
parts.unshift(header(node));
const key = parts.some((part) => typeof part === 'symbol') ? Symbol() : JSON.stringify(parts);
found.push({ key, start, end });
});
return found;
}
// A version that is missing or does not parse has no declarations.
const declarationsOrNone = (read) => {
try {
return declarations(read());
} catch {
return [];
}
};
const notAfter = (a, b) => a.line < b.line || (a.line === b.line && a.column <= b.column);
const problems = [];
for (const file of files) {
const code = lf(after === null ? readFileSync(file, 'utf8') : show(after, file));
// Count each declaration of the earlier version; one in the new version is new when no
// earlier declaration with the same key is left to pair it with.
const earlier = new Map();
for (const { key } of declarationsOrNone(() => lf(show(before, file))))
earlier.set(key, (earlier.get(key) ?? 0) + 1);
const current = declarationsOrNone(() => code);
const introduced = new Set(
current.filter(({ key }) => {
const left = earlier.get(key) ?? 0;
earlier.set(key, left - 1);
return left < 1;
}),
);
const { results } = await stylelint.lint({ code, codeFilename: file });
for (const w of results[0].warnings) {
const decl = current.find(({ start, end }) => notAfter(start, w) && notAfter(w, end));
// A problem outside every declaration, such as a syntax error, is always reported.
if (!decl || introduced.has(decl)) problems.push(`${file}:${w.line}:${w.column} ${w.text}`);
}
}
if (problems.length) {
console.error(
`Design tokens: ${problems.length} problem(s) in declarations this change introduces. ` +
`Use a token defined in :root instead of a raw value.\n${problems.join('\n')}`,
);
process.exit(2);
}
El script necesita PostCSS junto a Stylelint (npm install --save-dev stylelint postcss).
Mientras el agente edita
Esto va en .claude/settings.json:
{
"hooks": {
"PostToolUse": [
{
"matcher": "Edit|Write",
"hooks": [
{
"type": "command",
"command": "node",
"args": ["${CLAUDE_PROJECT_DIR}/tools/token-lint.mjs"]
}
]
}
]
}
}
Claude Code ejecuta un hook PostToolUse después de que una llamada a herramienta tiene éxito y pasa la llamada como JSON por stdin. Para Edit y Write, la ruta está en tool_input.file_path. Un comando de shell no tiene ese campo, así que el script termina en silencio para él, igual que para cualquier archivo que no sea una hoja de estilos.12 Como la escritura ya ocurrió, el script lee el archivo terminado desde el disco, y así es como un token definido a mitad de bloque se juzga en contexto. El código de salida 2 no deshace la escritura. Le muestra al modelo el stderr del script: el archivo, la línea y el valor que no es un token.
Probé el hook de dos maneras. Primero le pasé por pipe el JSON que la referencia de hooks documenta para cada herramienta:
| Entrada | Resultado |
|---|---|
Edit que agrega font-size: 19px |
exit 2, nombra la línea |
Edit que agrega font-size: 1.25rem o .5rem |
exit 2 |
Edit que agrega font-weight: 800 |
exit 2 |
Edit que agrega FONT-SIZE: 19px en mayúsculas |
exit 2 |
Edit que cambia solo la segunda línea de un margin de dos líneas a 13px |
exit 2 |
Edit que elimina solo las marcas de comentario alrededor de un font-size: 19px viejo |
exit 2 |
Edit que solo cambia la indentación de una regla vieja y de sus declaraciones |
exit 0 |
Edit que mueve la llave de apertura de una regla vieja a su propia línea |
exit 2 |
Edit que reparte en dos líneas el valor de un margin: 13px … viejo |
exit 2 |
Edit que agrega color: #cccccc |
exit 2 |
Write que crea una hoja de estilos con un tamaño crudo y un color crudo |
exit 2, dos problemas |
Edit que usa solo tokens |
exit 0 |
Edit que agrega un token dentro de un :root {} de varias líneas |
exit 0 |
Edit limpio en un archivo con un font-size: 15px viejo |
exit 0 |
Bash ejecutando git commit -m "fix #123 header" |
exit 0 |
Edit a un archivo Markdown que menciona font-size: 19px |
exit 0 |
Luego lo ejecuté en una sesión real: Claude Code 2.1.325, headless, en un proyecto de prueba con esta configuración. Le pedí que agregara .badge { font-size: 19px; } al final de una hoja de estilos con un solo Edit. La edición se aplicó, el hook se ejecutó y la sesión recibió esto:
PostToolUse:Edit hook blocking error from command: "node ${CLAUDE_PROJECT_DIR}/tools/token-lint.mjs": [node ${CLAUDE_PROJECT_DIR}/tools/token-lint.mjs]: Design tokens: 1 problem(s) in declarations this change introduces. Use a token defined in :root instead of a raw value.
static/css/site.css:12:21 Disallowed value "19px" for property "font-size" (declaration-property-value-allowed-list)
Ese es un caso en vivo, no la tabla completa. Muestra que la configuración carga y que el mensaje llega al agente; el valor crudo se queda en el archivo hasta que el agente o una persona lo corrija.
Un hueco: el hook no ve el CSS que el agente reescribe mediante un comando de shell. La referencia dice que un hook PostToolUse que coincide con Edit|Write no se ejecuta cuando un comando de Bash reescribe el mismo archivo.12 Los dos lugares siguientes cubren eso.
En el commit
#!/bin/sh
exec node tools/token-lint.mjs --cached
Guardado como .git/hooks/pre-commit y hecho ejecutable, esto hace linting de la versión en el área de staging de cada hoja de estilos que está en ella. En un repositorio de prueba detuvo un commit que llevaba font-size: 19px en staging, dejó pasar un commit que usaba tokens y juzgó el contenido en staging cuando la copia de trabajo difería de él. La documentación de Git dice que el hook “se puede omitir con la opción --no-verify”,13 así que es una comodidad para el caso honesto y no el gate.
En CI
#!/bin/sh
# Stops at the first check that fails and exits with that check's status.
set -e
node tools/token-lint.mjs origin/main...HEAD
npx playwright test
npx lhci autorun
Guardado como tools/design-checks.sh, este es el gate. Dado un rango como origin/main...HEAD, el script de tokens enumera las hojas de estilos que difieren y hace linting de cada una tal como está en el commit donde termina el rango. set -e detiene el script en la primera verificación que falla y hace que termine con el código de salida de esa verificación. Sin él, un script de shell termina con el código de salida de su último comando, así que una verificación de tokens fallida seguida de una ejecución de Lighthouse que pasa terminaría con código 0. Probé el script con sustitutos de los tres comandos, haciendo fallar el primero, el segundo y el tercero por turno. Es un script, no un archivo de workflow: ejecuté cada comando real en local y no he ejecutado nada de esto dentro de un servicio de CI. El hook de commit y el script de CI verifican el cambio sin importar quién lo escribió, una persona o cualquier agente. Esa parte del stack no depende de Claude Code.
Qué tiene este sitio hoy
No ejecuto este stack en blakecrosley.com. Mis artículos de ingeniería de diseño describen la escala tipográfica, los tokens de color y el trabajo con Lighthouse. El repositorio define los tokens y no contiene ninguna de las verificaciones: ni configuración de Stylelint, ni configuración de Lighthouse CI, ni spec de axe, ni líneas base de screenshots. Así es como se ve eso, contado a partir de static/css el 16 de noviembre de 2026.5
Los tokens existen. Construí primero los tokens y nunca los componentes. :root en styles.css define 12 tamaños de fuente de 0.75rem a 5rem, cinco pesos (400, 500, 600, 700, 900), ocho pasos de espaciado y 13 colores, cada uno con su override para el tema claro. Mi artículo anterior sobre tipografía dice 13 pasos y cuatro pesos; la hoja de estilos tiene 12 y cinco.
El uso es parcial. Conteo en 75 hojas de estilos:
| Declaraciones | Total | Usan un token | Crudas | Nota |
|---|---|---|---|---|
font-size |
1241 | 548 | 691 | 312 de las 548 agregan un fallback crudo después del nombre del token, como en var(--font-size-sm, 0.875rem). Las dos restantes son un inherit y una referencia a un paso que no existe, descrita más abajo. |
font-weight |
512 | 104 | 408 | 299 de los valores crudos son valores que un token ya contiene (600, 700, 500, 400, bold o normal). 109 son pesos que ningún token contiene (650, 800 o 550). |
| Color crudo, fuera de las definiciones de tokens | 2850 | no contado | 2850 | 2844 contienen un valor hexadecimal o una función de color, y seis el nombre white. |
La mayor parte está fuera de la hoja de estilos principal, en archivos escritos para artículos interactivos individuales: el propio styles.css representa 77 de los tamaños crudos y 230 de los colores crudos.
La configuración encuentra cosas. Ejecutada sobre una copia de esas hojas de estilos, la configuración del componente 1 devolvió 6034 problemas, y por eso el script informa de lo que un cambio introduce y no del archivo completo. Uno de ellos es un paso que no existe: infrastructure-stack.css pide var(--font-size-md, 1rem), y la escala no tiene md.
Un nivel no alcanza AA. El texto blanco sobre la página negra mide 21:1 a opacidad completa, 8,6:1 al 65% y 3,66:1 al 40%. Los dos primeros superan el 7:1 de AAA. El tercero no alcanza el 4,5:1 de AA en tamaños de cuerpo.1 Mi artículo anterior sobre este sistema de color da 13,7:1 para el nivel del 65% y 8,4:1 para el nivel del 40%; esas cifras son incorrectas, y estas son las calculadas.
Los puntajes se movieron. Ejecuté Lighthouse 13.6.0 contra la página de inicio en producción el 16 de noviembre de 2026, tres ejecuciones para móvil y tres para escritorio. Las seis informaron rendimiento 100, buenas prácticas 100, SEO 100, CLS 0,000 y accesibilidad 93. Dos días antes, las mismas seis ejecuciones dieron un rendimiento de entre 95 y 100, con los demás números iguales.14 Dos auditorías le costaron puntos a la accesibilidad. Una es el nivel del 40% en texto de 12px: dos líneas del footer, que Lighthouse informa como 3,65:1 sobre negro, y en escritorio además diez etiquetas del listado de guías, a 3,44:1 sobre #0a0a0a. La otra son los enlaces del footer, que no pasan la auditoría de tamaño del objetivo de WCAG 2.2 en sus dos condiciones: miden 23.8px de alto frente a un mínimo de 24px, y no tienen suficiente espacio libre alrededor para compensarlo.
En enero de 2026 medí 100 en las cuatro categorías en este sitio, con el CLS en 0,033. Haya cambiado la página o la auditoría, nada en el repositorio estaba vigilando el número. Una ejecución de diagnóstico del 16 de noviembre coincide con Lighthouse. Usó las etiquetas de axe del componente 5 y la medición de layout del componente 3, pero registró lo que encontró en lugar de hacer aserciones sobre ello. En la página de inicio en producción, axe informó color-contrast, target-size y un label-content-name-mismatch, y la medición de layout no encontró desbordamiento ni desplazamiento a 375, 768 ni 1440px.
Ese es el argumento a favor del stack, y lo aporta el sitio de la misma persona que lo recomienda. Los tokens sin una verificación son una convención, y estos conteos son el aspecto que tiene una convención cuando nada la impone.
La capa de gusto
Los seis componentes detectan violaciones. Ninguno detecta el output que sigue cada regla y aun así se siente incorrecto.
Imagina una tarjeta con tamaños de fuente de token, colores de token, sin desplazamiento de layout, una ejecución limpia de Lighthouse, sin violaciones de axe y sin diff de screenshots. Su título se amontona contra la imagen, su longitud de línea fuerza la lectura y su estado hover salta donde debería suavizarse. Cada verificación pasa. La tarjeta es correcta. La tarjeta no es buena.
El gusto opera por encima de la capa de reglas. Los seis componentes manejan restricciones y criterios de evaluación. El reconocimiento de patrones y la coherencia necesitan a una persona que vuelva a recorrer el trabajo, un segundo pase y un tercero, preguntando cada vez no si las reglas se cumplen sino si el resultado merece enviarse. La verificación de orgullo termina con “¿Dejé el codebase mejor de como lo encontré?” El criterio de Steve termina con “¿Firmaría esto con mi nombre sin titubear?” Ninguna de las dos preguntas tiene un linter.
Qué se gana con el stack
Sin verificaciones, la deriva puede acumularse en incrementos demasiado pequeños para verse en un solo diff: un tamaño de fuente aquí, un valor hexadecimal allá, un enlace del footer al que le falta una fracción de píxel. Los conteos de mi propio CSS son el aspecto que tiene el agregado.
Con las verificaciones, el agente todavía puede cometer el error. Lo que cambia es cuándo alguien se entera: en el mismo turno para un token, en el commit para lo que el hook dejó pasar, en CI para el layout, el rendimiento, la accesibilidad y el cambio visual. Es una promesa más estrecha que “no puede derivar”, que es lo que afirmaba la versión anterior de este artículo. Las verificaciones cubren las propiedades que nombran, en las declaraciones que un cambio introduce, en las páginas y los anchos que las specs enumeran. Una página que nadie enumeró queda sin verificar.
Lo que se gana con eso es atención. Un revisor que ya no anda a la caza de 19px y #cccccc puede dedicar la revisión a la capa de gusto, las preguntas que las verificaciones no pueden responder.
FAQ
¿Necesito los seis componentes para empezar?
No. Empieza con la configuración de Stylelint y el script, porque las violaciones de tokens son las más baratas de verificar y la configuración es un solo archivo. Agrega Lighthouse CI y la spec de axe después; cada uno necesita solo una página servida. La spec de layout necesita un navegador que informe desplazamientos de layout, y la spec de screenshots necesita líneas base hechas en el entorno que las va a comparar, así que van al final.
¿Funciona el stack con herramientas de build?
Para un sitio cuyos estilos están escritos como archivos de CSS plano, las verificaciones no dependen de cómo se construye: Stylelint lee los archivos fuente, y Playwright y Lighthouse leen lo que sea que sirva el servidor. Con un paso de build, haz linting del código fuente y apunta las verificaciones de navegador al output compilado. El script selecciona solo archivos .css. Sass, CSS-in-JS, los estilos inline y las clases de utilidad en plantillas necesitan otra forma de seleccionar y parsear el código fuente, o una verificación contra el CSS generado. Solo lo he ejecutado contra CSS plano sin paso de build, donde el archivo que el agente escribe es el archivo que se envía.
¿Solo funciona con Claude Code?
El hook que actúa durante la edición es de Claude Code. El hook pre-commit y los comandos de CI se ejecutan sobre el cambio en sí y no les importa qué agente, o qué persona, lo escribió.
¿Pueden los agentes aprender gusto sin el stack?
Yo no contaría con ello. Un prompt puede enumerar los tokens, y un agente al que se le da la escala puede usarla. Pero un prompt es una petición y una verificación que falla es un hecho. El stack no enseña gusto. Elimina las violaciones de reglas para que la atención de una persona se dirija al gusto.
¿Cómo manejan las pruebas de regresión visual los cambios intencionales?
Un cambio intencional que mueve más píxeles de los que la tolerancia permite hace fallar la comparación como cualquier otro. Una persona revisa el diff y ejecuta npx playwright test --update-snapshots para aceptarlo como la nueva línea base. El valor está en la parte no intencional: un agente cambia el color de un botón a propósito y mueve la tarjeta tres píxeles por accidente, y el screenshot muestra ambas cosas.
Qué cuenta como nuevo
Este es el detalle detrás de la regla corta que acompaña al script, para quien necesite predecir de qué va a informar.
Para decidir qué declaraciones introduce un cambio, el script parsea dos versiones del archivo con PostCSS, el parser sobre el que está construido Stylelint. Una declaración de la versión más nueva es nueva salvo que la versión más vieja contenga una contraparte. Dos declaraciones son contrapartes cuando dos fragmentos del texto fuente son idénticos, carácter por carácter. Uno es la declaración misma, desde el primer carácter de su propiedad (o de un hack de prefijo como el * de *color) hasta su punto y coma inclusive. Una última declaración sin punto y coma llega hasta la llave de cierre de su regla, porque el punto final que el propio parser le asigna deja fuera caracteres finales que pueden importar. El otro es el encabezado de cada regla y at-rule que la rodea, desde el primer carácter del encabezado hasta su llave de apertura inclusive. El texto se compara tal como está en el archivo. El único cambio que se hace a ambas versiones antes de comparar es el que CSS hace antes de leer una hoja de estilos: CRLF, un CR suelto y un salto de página se convierten cada uno en LF. Las contrapartes se emparejan una a una, así que una segunda declaración idéntica es nueva.
El script compara el texto fuente, y no los campos que devuelve un parser, porque los campos parseados pueden perder caracteres que importan: un espacio de no separación que un trim eliminó, un tabulador escapado que el parser guardó fuera del valor. Los problemas se asocian a las declaraciones por línea y luego por columna, lo que también se sostiene en una línea de más de un millón de caracteres. Comparar el texto fuente cuesta más informes repetidos, y donde el script no puede fijar el texto con exactitud trata la declaración como nueva.
Lo que no cuenta como cambio es el texto fuera de esos dos fragmentos:
- la indentación antes de una declaración o de una regla
- las líneas en blanco
- los comentarios entre declaraciones
- el orden de las declaraciones dentro de una regla
- una marca de orden de bytes al inicio del archivo
- otras reglas agregadas o eliminadas a su alrededor
Lo que sí cuenta es un carácter cambiado dentro de ellos. En mis pruebas, cada uno de estos casos informa de la declaración como nueva, problema viejo incluido, y un cambio en un encabezado lo hace para cada declaración bajo ese encabezado:
- un espacio agregado antes de dos puntos, de un punto y coma o de una llave de apertura
- una llave movida a su propia línea
- una lista de selectores unida en una sola línea
- un valor repartido en dos líneas
- un comentario dentro de un selector o de una declaración
- un espacio de no separación
!important- un cambio de mayúsculas o minúsculas
- un punto y coma agregado a una última declaración que no tenía
- un espacio o un comentario agregado antes de la llave de cierre después de una declaración así
Esa es la decisión que tomé. Dos grafías que difieren en un carácter pueden significar cosas distintas en CSS, dentro de una cadena, de un valor de atributo o de un escape.
De la regla se siguen tres cosas más:
- Una declaración movida bajo un encabezado distinto es nueva, y también lo es cada declaración bajo un selector que cambió de nombre.
- Una declaración que una eliminación pone en vigor, como una que estaba dentro de un comentario, es nueva aunque ninguno de sus propios caracteres haya cambiado.
- Un archivo sin versión anterior bajo su nombre, uno nuevo o renombrado, es nuevo en su totalidad, igual que un archivo cuya versión anterior estaba vacía o no se pudo parsear.
Lo que la comparación no puede ver es el orden, ni el contexto fuera del texto comparado. Conoce los encabezados que rodean a una declaración, no en qué regla está la declaración ni dónde cae en la cascada. Así que no detecta:
- un traslado entre dos reglas con encabezados idénticos
- un reordenamiento de declaraciones o de reglas
- un cambio en otra parte que deja ganar a una declaración vieja, como eliminar la declaración que la sobrescribía
- una at-rule de sentencia, porque solo mira las declaraciones: un
@importo un@layeragregado, o un@namespacecuyo enlace cambia, lo que altera con qué coincide un selector comon|amientras cada carácter de la regla sigue igual
Dos comportamientos más son deliberados. El script necesita un repositorio de git: fuera de uno lo dice en una línea y termina con código 1 sin verificar nada. Los nombres de archivo llegan de git separados por bytes NUL y vuelven a él como rutas literales, así que las rutas que probé funcionaron: espacios y un acento en un nombre, y un nombre de directorio que empieza o termina con un espacio.
Cómo probé esto
Todo se ejecutó el 16 de noviembre de 2026, en macOS con Node 22.22.0: Stylelint 17.16.0, PostCSS 8.5.33, @playwright/test 1.65.1, @axe-core/playwright 4.14.0 con axe-core 4.14.0 y @lhci/cli 0.16.1 con Lighthouse 13.6.0. Stylelint 18.0.0 era la versión más reciente ese día. Su package.json declara Node ^22.22.2 || ^24.15.0 || >=26.0.0, así que npm advirtió de un engine no soportado cuando lo instalé en Node 22.22.0. Se ejecutó de todos modos, y la configuración dio el mismo output en mis archivos de ejemplo que en 17.16.0. No he ejecutado 18.0.0 en una versión de Node que soporte.
Las specs y la configuración de Lighthouse CI se ejecutaron contra un sitio de prueba de dos páginas estáticas, una vez limpio y otra en copias rotas de una manera cada una. El harness del script de tokens hace 238 comprobaciones en 237 ejecuciones del script en carpetas de prueba: a través del hook, en staging, sobre un rango de commits y fuera de un repositorio. Probado en los tres modos: declaraciones de varias líneas, declaraciones que una eliminación pone en vigor, cambios fuera de toda declaración y encabezado, cambios de un solo carácter dentro de ellos (un espacio de no separación, un espacio de ancho cero, una llave movida, un espacio escapado frente a un tabulador escapado), declaraciones sin punto y coma, comentarios dejados dentro de valores, una línea de más de un millón de caracteres, declaraciones movidas, los cuatro casos no detectados descritos arriba, una versión anterior vacía o que no se puede parsear, cadenas que continúan en la línea siguiente y nombres de archivo con espacios y un acento.
Un segundo modelo, Codex de OpenAI, revisó la configuración y el script cinco veces, leyendo el código y ejecutando sus propias sondas, y corregí lo que encontró cada pasada antes de la siguiente. Cada pasada confirmó las correcciones anteriores y luego encontró algo más raro. A lo largo de las cinco pasadas, los hallazgos pasaron de errores que cualquiera comete (una violación en una línea sin cambios, una declaración destapada por una eliminación) a CSS que nadie escribe por accidente (espacio en blanco que no es espacio en blanco, un carácter escapado al final mismo de una declaración). Esa es la evidencia para llamar a estos dos archivos un lint y no una frontera. El script de verificaciones se ejecutó con sustitutos de sus tres comandos. El hook también se ejecutó una vez dentro de una sesión en vivo de Claude Code 2.1.325, con el caso de 19px, con el script tal como aparece aquí. No probado: el resto de los casos del hook en una sesión en vivo; el script de verificaciones dentro de un servicio de CI; y nada de esto contra un pipeline de build.
Qué cambió respecto a la versión de abril
La versión de abril describía el stack como infraestructura que yo ejecuto. Decía “La infraestructura ejecuta Lighthouse en Chrome headless contra el despliegue de staging” y “El gate se ejecuta en CI usando lighthouse-ci”, y tenía una sección titulada “Cómo se mapea el stack a mi infraestructura”. No lo ejecuto: el repositorio de este sitio no contiene ninguna de estas verificaciones. Sus fragmentos de código no se habían ejecutado. Ambos hooks buscaban en .tool_input.command, un campo que solo llevan los comandos de shell, así que ninguno veía una edición de CSS, y la configuración de Lighthouse CI nombraba sus categorías con claves que Lighthouse CI no conoce. También describía mal este sitio: “tres pesos: 700, 400 y 300” (hay cinco tokens de peso, y 300 no es uno de ellos), “exactamente diez tokens” (la paleta tiene 13 tokens de color), una “escala de 13 pasos” (la escala tiene 12 pasos) y “cada nivel cumple AAA” (el nivel de texto terciario no lo hace). Una frase que puso entre comillas bajo el nombre de Jony Ive no está en el perfil que citaba, y no pude encontrar el artículo de Nathan Curtis que citaba, así que ambos desaparecieron. Los fragmentos de código de esta versión se ejecutaron antes de publicarse, la sección de pruebas de arriba dice qué no se ejercitó y las cifras sobre este sitio salen de tres lugares, todos del 16 de noviembre de 2026: conteos tomados de su CSS, ratios de contraste calculados a partir de sus tokens y cifras de Lighthouse medidas en el sitio en producción.
Tres cosas del código cambiaron después de que la reconstrucción se publicó por primera vez. El script decidía qué había tocado un cambio contando las líneas agregadas, así que dejaba pasar una violación que Stylelint ubicaba en una línea sin cambios de una declaración modificada, y no podía ver una declaración que una eliminación ponía en vigor. Ahora compara el texto fuente de cada declaración, y de los encabezados que la rodean, antes y después del cambio. Los nombres de propiedad en mayúsculas o con escapes pasaban la configuración. Y los tres comandos de CI, publicados sin set -e, podían terminar con código 0 después de una verificación fallida.
Fuentes
-
W3C, Web Content Accessibility Guidelines (WCAG) 2.2. El criterio de conformidad 1.4.3 Contraste (mínimo) pide “una relación de contraste de al menos 4,5:1” para el texto y “al menos 3:1” para el texto de gran tamaño; 1.4.6 Contraste (mejorado) pide 7:1. El mismo documento dice que “el W3C aconseja usar WCAG 2.2 para maximizar la aplicabilidad futura de los esfuerzos de accesibilidad”. ↩↩↩↩
-
Philip Walton, “Web Vitals”, web.dev. “El LCP debe ocurrir dentro de los 2,5 segundos desde que la página empieza a cargarse”, “las páginas deben tener un INP de 200 milisegundos o menos” y “un buen umbral para medir es el percentil 75 de las cargas de página”. ↩
-
Robert Bringhurst, The Elements of Typographic Style, sección 3.1.1, “Don’t compose without a scale”, citado en Richard Rutter, The Elements of Typographic Style Applied to the Web. ↩
-
Stylelint,
declaration-property-value-allowed-list: “Usa esta regla para imponer un subconjunto de valores para una propiedad como convención”. El pluginstylelint-declaration-strict-valuees una alternativa dedicada para el mismo trabajo. Usé las reglas integradas y no probé el plugin. ↩ -
Conteo del autor sobre las 75 hojas de estilos escritas que hay en
static/cssen el commit253f49adedel 16 de noviembre de 2026, excluyendo los archivos generadosstyles.min.cssycritical.css, con los comentarios eliminados. Las relaciones de contraste usan la fórmula de luminancia relativa de WCAG sobre cada color compuesto sobre#000000. ↩↩ -
Milica Mihajlija y Philip Walton, “Cumulative Layout Shift (CLS)”, web.dev. “Para ofrecer una buena experiencia de usuario, los sitios deben esforzarse por tener un puntaje de CLS de 0,1 o menos”, y “el CLS es una medida de la mayor ráfaga de puntajes de desplazamiento de layout para cada desplazamiento de layout inesperado que ocurre durante todo el ciclo de vida de una página”. Sobre los iframes: “La API no informa entradas
layout-shiftpara los desplazamientos que ocurren dentro de iframes, pero la métrica sí, ya que forman parte de la experiencia de usuario de la página”. ↩↩ -
Lighthouse CI, “Configuration”. Las aserciones de categoría “tienen como clave
categories:<categoryId>”, las opciones por defecto son{"aggregationMethod": "optimistic", "minScore": 1}, yoptimisticsignifica “Usar el valor con más probabilidades de pasar de entre todas las ejecuciones”. ↩ -
Deque, documentación de la API de axe-core, la tabla de etiquetas:
wcag2a,wcag2aa,wcag21a,wcag21aaywcag22aanombran cada una una versión y un nivel de WCAG. ↩↩ -
Playwright, “Accessibility testing”. ↩
-
Playwright, “Visual comparisons”. “Para obtener screenshots consistentes, ejecuta las pruebas en el mismo entorno donde se generaron los screenshots de línea base”. La opción
maxDiffPixelRatiose describe bajotoHaveScreenshoten la referencia de la API de PageAssertions: “Una proporción aceptable de píxeles que son diferentes respecto a la cantidad total de píxeles, entre0y1”. ↩↩ -
BackstopJS, README, consultado el 16 de noviembre de 2026. ↩
-
Anthropic, referencia de hooks de Claude Code. Las entradas de
EdityWritellevanfile_path; paraPostToolUse, el código de salida 2 “Muestra stderr a Claude; la herramienta ya se ejecutó”; y “Claude Code no ejecuta un hookPostToolUseque coincide conEdit|Writecuando un comando deBasho un proceso externo a Claude Code reescribe el mismo archivo”. ↩↩ -
Git, documentación de githooks, bajo
pre-commit. ↩ -
Medición del autor. Lighthouse 13.6.0 ejecutado desde la línea de comandos contra
https://blakecrosley.com/el 16 de noviembre de 2026, con la configuración móvil por defecto y el preset de escritorio, tres ejecuciones cada uno. El 14 de noviembre, las mismas seis ejecuciones dieron un rendimiento de 95, 100 y 99 en móvil y de 99, 100 y 100 en escritorio, con una accesibilidad de 93. El 3,65:1 de Lighthouse y mi 3,66:1 son el mismo ratio, 3,657: yo lo redondeo, y axe, que Lighthouse ejecuta para esta auditoría, lo corta a dos decimales. ↩