Revisar el contraste WCAG con Claude Code (en claro y en oscuro)

Para revisar el contraste WCAG con Claude Code, no le pidas que «mire si se lee bien»: dale una skill que calcule la razón de contraste de cada par de tokens con la fórmula de WCAG, en el tema claro y en el oscuro, y que te proponga el ajuste mínimo cuando un par no llega. El modelo es bueno leyendo tu CSS y explicando el informe; la cuenta la tiene que hacer un script, porque un 4,4:1 y un 4,6:1 no se distinguen a ojo y uno de los dos no cumple.

Aquí va qué mide WCAG 2.2, cómo armar esa revisión y los cuatro errores que encontramos el 19 y el 20 de octubre de 2026 en nuestro propio revisor de contraste. Son errores que cualquier script parecido puede tener, y por eso conviene probarlos en el tuyo.

Qué exige WCAG 2.2 (nivel AA)

Qué	Mínimo	Criterio
Texto normal	4,5:1	1.4.3 Contraste (mínimo)
Texto grande: 24 px, o 18,66 px en negrita	3:1	1.4.3
Bordes de campos, íconos, indicador de foco	3:1	1.4.11 Contraste no textual

La razón va de 1:1 (mismo color) a 21:1 (negro sobre blanco) y sale de la luminancia relativa de los dos colores: (L1 + 0,05) / (L2 + 0,05), con el más claro arriba. Los textos deshabilitados y los logos están exentos.

Por qué medir los tokens y no las pantallas

Si tu sitio usa variables como --color-texto y --color-fondo, el contraste se decide ahí. Un par que falla en los tokens falla en cada pantalla que lo usa, y se arregla cambiando una línea. Revisar pantalla por pantalla encuentra el mismo problema veinte veces.

Lo que los tokens no cubren se revisa aparte, con una captura: texto sobre una foto o un degradado, colores escritos a mano fuera de los tokens y texto con opacidad.

Cómo armarlo en Claude Code

1. Una skill con un script. La skill le dice a Claude cuándo usarla («cuando cambie la paleta o antes de aprobar un tema») y el script hace la cuenta. Así la respuesta no depende de cómo amaneció el modelo.
2. Pares por nombre. El script arma los pares solo: los tokens de texto (texto, foreground, on-, foco…) sobre los de fondo (fondo, background, surface, card…). Si tus nombres no siguen ese patrón, le das una lista de pares explícita en un JSON.
3. Los dos temas. El tema oscuro se mide con sus propios valores, no con los del claro.
4. Una propuesta, no solo un «no». Cuando un par falla, sugiere el color más cercano con el mismo tono que sí cumple, y un solo valor por token que pase contra todos sus fondos: un token, un cambio.
5. Tú decides los colores de marca. La skill propone opciones (oscurecer el token, usarlo solo en texto grande o crear un token nuevo para texto chico) y no cambia nada sin tu OK.

Con la skill instalada, el pedido es una frase:

Revisa el contraste de src/styles/tokens.css en claro y en oscuro.
Solo informe y propuesta, no cambies archivos.

Y el informe se ve así:

== tema claro (por defecto): 2 colores leídos ==
  OK  18.88:1 (mín. 4.5) --color-texto #111111 sobre --color-fondo #ffffff

== modo oscuro: 2 colores leídos ==
  NO  1.00:1 (mín. 4.5) --color-texto #111111 sobre --color-fondo #111111
       sugerencia para --color-texto: oklch(59.3% 0.000 89.9) (#7e7e7e) → 4.64:1

Cuatro errores que un revisor de contraste no debe cometer

Nuestro script de contraste es parte de un kit que vendemos, y también lo enviamos a varios catálogos públicos de skills en GitHub. El 19 de octubre de 2026 encontramos que en algunos archivos medía el modo oscuro contra el fondo claro, y el 20 una revisión automática del código en uno de esos catálogos señaló estos cuatro. Están corregidos en el repositorio gratis, en el catálogo agentic-awesome-skills, que incorporó la skill el 20 de octubre, y en las propuestas abiertas a otros dos catálogos. La v1.0.0 del kit que se vende en Gumroad todavía trae la versión anterior del script; la v1.1, en preparación, lo corrige, y las actualizaciones les llegan por Gumroad a quienes ya compraron. Cada error trae una prueba que puedes copiar para revisar tu propio script.

1. Medir el modo oscuro contra el fondo claro

Si el script no reconoce el bloque oscuro, mezcla los valores de los dos temas. El caso que lo destapó: un bloque escrito como .dark:root { … } en vez de .dark { … }. El script buscaba .dark seguido de una llave y no lo encontró, así que los colores oscuros pisaron a los claros y el informe mostró un solo tema con colores mezclados.

Prueba: un tema claro que pasa y un oscuro que no.

:root      { --color-texto: #111; --color-fondo: #fff; }
.dark:root { --color-texto: #111; --color-fondo: #111; }

El informe tiene que mostrar dos temas: el claro en OK y el oscuro con 1:1. Prueba también :root.dark, [data-theme="dark"] y el @media (prefers-color-scheme: dark) con más de una regla adentro.

2. Dejar fuera el texto de las tarjetas

--color-card-foreground tiene una palabra de texto (foreground) y una de fondo (card). Un filtro que descarta todo lo que nombra un fondo lo saca de la revisión, y con él a --color-on-surface. En los temas de shadcn/ui ese es justo el texto de las tarjetas.

Prueba: --color-card: #fff y --color-card-foreground: #eee. Tiene que fallar con 1,16:1. Antes del arreglo, el informe decía «todos los pares cumplen».

3. Decir «todo cumple» sin haber medido nada

Este es el más peligroso, porque el informe se ve limpio. Pasaba en tres casos: un token mal escrito en la lista de pares, un CSS sin variables de color y un archivo donde ningún nombre calzaba con el patrón. En los tres, el script no medía ningún par y terminaba con «Todos los pares revisados cumplen WCAG 2.2 AA».

Prueba: corre el script sobre un archivo vacío. Tiene que decir que no midió nada y terminar con un código de error, no con éxito. Si lo usas en un hook o en tu integración continua, eso es lo que evita que un error de tipeo pase como aprobado.

4. Leer mal los colores modernos

CSS acepta más formas de escribir un color de las que un parser casero suele leer:

• hsl(0.5turn 100% 25%): el tono está en vueltas, no en grados. Es #008080, no un rojo.
• oklch(60% 20% 30): el croma en porcentaje, donde 100% equivale a 0,4. Aquí es 0,08, no 20.
• var(--color-Brand): el nombre de una variable distingue mayúsculas. Si el script lo pasa a minúsculas, no lo encuentra.

Y una más sobre la sugerencia: negro sobre negro necesita subir la luminosidad bastante más de la mitad del rango. Si el script busca solo hasta la mitad, no sugiere nada. Tiene que proponer un gris medio (#757575).

Lo que no reemplaza

El script mide los tokens. No ve una foto detrás de un titular, un opacity: 0.6 puesto a mano ni un color que alguien escribió directo en un componente. Para eso, pídele a Claude que busque colores fuera de los tokens (#, rgb(, text-[#) y revisa las secciones con imagen en una captura. Y el contraste es un criterio entre muchos: para una auditoría completa de accesibilidad necesitas también foco visible, tamaño de los objetivos táctiles y textos alternativos.

La skill, lista para usar

La skill contraste-colores del repositorio gratis ya tiene el script corregido. Es una de las 3 skills gratis de mi kit, en un repositorio público de GitHub. Se instala desde Claude Code con:

/plugin marketplace add Clagoss/claude-code-para-disenadores
/plugin install lagos-diseno-es@claude-code-para-disenadores

El kit completo, «Del Figma a producción con Claude Code», la conecta con el resto del flujo: los tokens pasan de Figma a Tailwind, un subagente revisa que se usen los tokens y otro audita la accesibilidad antes de publicar. Es de pago; aquí está todo lo que incluye. El kit no está afiliado a Anthropic.