Si alguna vez has configurado una auditoría de accesibilidad (a11y) en un repositorio frontend, seguro empezaste con el conjunto estándar: el linter eslint-plugin-jsx-a11y, el plugin axe-core y el informe de Lighthouse en CI/CD. Parecería que con el escudo verde todo está listo para el lanzamiento. Pero basta con que un usuario ciego con lector de pantalla o una persona que navega solo con el teclado abra la página para que empiecen los problemas.
El foco cae en capas invisibles, cerrar una ventana modal devuelve el cursor al inicio del documento y las pestañas se cambian con el tabulador en lugar de las flechas. ¿Por qué las herramientas automáticas pasan por alto errores tan básicos?
Analicemos esta mecánica y veamos cómo el equipo británico TetraLogical abordó la automatización de más del 95% de los requisitos del estándar WCAG 2.2 combinando escenarios BDD y el navegador headless Playwright.
El punto ciego de los linters estáticos: por qué el 60% de los bugs no se detectan en CI
El problema de los escáneres DOM y linters tradicionales radica en sus limitaciones arquitectónicas. Herramientas como axe-core o Pa11y analizan una captura estática del marcado en un momento dado. Encuentran muy bien defectos básicos:
- Falta del atributo
alten la etiqueta<img>; - Relación de contraste insuficiente del texto respecto al fondo;
- Ruptura de la jerarquía de encabezados de
h1ah6; - Pérdida de la etiqueta de texto en un botón o campo de entrada.
Sin embargo, estos errores estáticos representan apenas un tercio del total de barreras de accesibilidad. El resto de los problemas surgen exclusivamente de forma dinámica, durante la interacción con la interfaz.
Un analizador estático no puede comprobar si el foco queda atrapado dentro de una ventana emergente abierta (keyboard focus trap) hasta que la ventana se abre con un clic. No sabe adónde regresará el foco tras pulsar la tecla Escape: si al botón de apertura o a la raíz de la página. Tampoco comprobará si el lector de pantalla anuncia la actualización dinámica del carrito mediante aria-live.
Hasta hace poco, la única salida seguía siendo las lentas pruebas manuales con lectores de pantalla (NVDA, JAWS, VoiceOver). Pero integrar a un tester humano en cada pull request de un sistema de diseño es inviable. Esa brecha es precisamente la que cierra la biblioteca abierta accessible-components-library de TetraLogical.
Arquitectura de la biblioteca TetraLogical: cinco áreas de WCAG 2.2 y 8 componentes base
Los ingenieros de TetraLogical identificaron 8 componentes fundamentales de interfaz sobre los que se construye cualquier sistema de diseño:
- Accordion: paneles desplegables con encabezados y roles de botón;
- Breadcrumbs: ruta de navegación con semántica
navyaria-current="page"; - Dialog / Modal: ventanas modales aisladas con retención del foco;
- Disclosure: botón único para ocultar y mostrar un bloque;
- Pagination: navegación accesible por páginas de listados;
- Tabs: cambio de contenido según el patrón oficial de ARIA tabs;
- Text Input: formularios con vinculación de etiquetas y mensajes de error;
- Textarea: campos de texto con contador dinámico de caracteres.
Todos los criterios del estándar WCAG 2.2 se descomponen en cinco áreas aplicadas:
- Adaptability: adaptabilidad al hacer zoom de texto hasta un 200% sin pérdida de funcionalidad y reflujo sin desplazamiento horizontal a un ancho de 320px (WCAG 1.4.10).
- Keyboard: acceso a todos los elementos sin ratón (WCAG 2.1.1), ausencia de trampas de foco (WCAG 2.1.2) e indicador de foco visible y con buen contraste (WCAG 2.4.7).
- Assistive Technology: semántica estricta de roles y estados (
aria-expanded,aria-selected,aria-controls) y notificación de cambios mediante regiones activas. - Colour and Contrast: contraste mínimo de texto de 4.5:1 para tamaño normal y 3:1 para texto grande.
- Input Assistance: resaltado de errores mediante
aria-invalid="true"y su vinculación con textos de ayuda mediantearia-describedby.
De escenarios BDD en Gherkin a pasos de Playwright: cómo funciona el test runner
En lugar de escribir pruebas aisladas, los desarrolladores de TetraLogical redactaron los requisitos en lenguaje Gherkin. Esto permite que diseñadores, responsables de accesibilidad e ingenieros trabajen con una terminología común y clara.
Los escenarios se guardan en archivos .feature. La etiqueta @automatic marca las comprobaciones que ejecuta por completo el runner de pruebas, mientras que la etiqueta @manual separa los criterios que requieren una evaluación humana subjetiva.
Aquí tienes un fragmento de la especificación para comprobar el aislamiento del foco en una ventana modal del repositorio de GitHub de TetraLogical:
@dialog @keyboard @2.1.2 @a @automatic
Feature: Dialog — Keyboard Trap and Focus Management
Background:
Given I load the sample "components/dialog/examples/modal.html"
Scenario: Tab key cycles focus within the active dialog
When I click the button "Open Dialog"
Then the element "#modal-dialog" should be visible
And the focus should be on the element "#dialog-first-input"
When I press "Tab" until reaching the last focusable element
And I press "Tab"
Then the focus should be on the element "#dialog-close-button"
@dialog @keyboard @escape @automatic
Scenario: Escape key dismisses the dialog and returns focus to trigger
When I click the button "Open Dialog"
And I press "Escape"
Then the element "#modal-dialog" should not be visible
And the focus should be on the element "#open-dialog-trigger"
La capa de definiciones (step definitions) traduce las frases de Gherkin directamente a comandos asíncronos de la API de Playwright:
import { Given, When, Then } from '@cucumber/cucumber';
import { expect } from '@playwright/test';
import { AccessibilityWorld } from '../support/world';
Given('I load the sample {string}', async function (this: AccessibilityWorld, url: string) {
await this.page.goto(url);
await this.page.waitForLoadState('networkidle');
});
When('I press {string}', async function (this: AccessibilityWorld, key: string) {
await this.page.keyboard.press(key);
});
Then('the focus should be on the element {string}', async function (this: AccessibilityWorld, selector: string) {
const targetElement = this.page.locator(selector);
await expect(targetElement).toBeFocused();
});
Si ya has estudiado cómo funciona la biblioteca de componentes de TetraLogical, sabrás que el navegador se encarga de parte de la gestión básica del foco. Pero los escenarios de TetraLogical garantizan que, ante cualquier composición de botones personalizados y campos anidados, el foco no se pierda en el árbol del documento bajo ninguna circunstancia.
Integración en el pipeline de CI/CD: ejecución automática de pruebas
Para integrar el conjunto de pruebas en el proyecto se necesita el entorno Node.js y la instalación de los runners:
npm install --save-dev @playwright/test @cucumber/cucumber ts-node typescript
npx playwright install --with-deps chromium
En el archivo de configuración cucumber.js se define la ejecución exclusiva de las pruebas automáticas:
module.exports = {
default: {
paths: ['features/**/*.feature'],
require: ['features/step_definitions/**/*.ts', 'features/support/**/*.ts'],
requireModule: ['ts-node/register'],
format: ['summary', 'html:reports/accessibility-report.html'],
tags: '@automatic and not @manual',
parallel: 2
}
};
La clase auxiliar AccessibilityWorld crea el contexto de navegador de Playwright:
import { setWorldConstructor, World, IWorldOptions, Before, After } from '@cucumber/cucumber';
import { Browser, BrowserContext, Page, chromium } from 'playwright';
export class AccessibilityWorld extends World {
browser!: Browser;
context!: BrowserContext;
page!: Page;
constructor(options: IWorldOptions) {
super(options);
}
}
setWorldConstructor(AccessibilityWorld);
Before(async function (this: AccessibilityWorld) {
this.browser = await chromium.launch({ headless: true });
this.context = await this.browser.newContext({ viewport: { width: 1280, height: 720 } });
this.page = await this.context.newPage();
});
After(async function (this: AccessibilityWorld) {
await this.page.close();
await this.context.close();
await this.browser.close();
});
La ejecución en el pipeline de CI se realiza con el comando npx cucumber-js. Si un desarrollador olvida devolver el foco al cerrar un modal o rompe el ciclo de la tecla Tab, la compilación en el pull request se detendrá de inmediato indicando el criterio WCAG infringido. Esto ahorra decenas de horas de revisión manual y protege la interfaz frente a regresiones ocultas.


