Auditoría de Accesibilidad (a11y-audit)
Nombre: a11y-audit Nivel: ESTÁNDAR Categoría: Ingeniería - Calidad Frontend Dependencias: Python 3.8+ (Solo Biblioteca Estándar) Autor: Alireza Rezvani Versión: 2.1.2 Última Actualización: 2026-03-18 Licencia: MIT
Nombre
a11y-audit: Habilidad de Auditoría y Corrección de Accesibilidad WCAG 2.2
Descripción
La habilidad a11y-audit proporciona un pipeline completo de auditoría de accesibilidad para aplicaciones web modernas. Implementa un flujo de trabajo de tres fases —Escanear, Corregir, Verificar— que identifica violaciones de WCAG 2.2 Nivel A y AA, genera código de corrección exacto por framework y produce informes de cumplimiento listos para las partes interesadas.
Esta habilidad va más allá de la detección. Para cada violación que encuentra, proporciona la corrección de código precisa (antes/después) adaptada a tu framework (React, Next.js, Vue, Angular, Svelte o HTML plano). Entiende que un atributo alt faltante en un <img> en JSX de React requiere un patrón de corrección diferente al mismo problema en un SFC de Vue o una plantilla de Angular.
Qué hace esta habilidad:
- Escanea tu código base en busca de todas las violaciones de WCAG 2.2 Nivel A y AA, categorizadas por severidad (Crítica, Mayor, Menor)
- Corrige cada violación con patrones de código específicos del framework (antes/después)
- Verifica que las correcciones resuelvan las violaciones originales y no introduzcan regresiones
- Informa los hallazgos en un formato estructurado adecuado para desarrolladores, gerentes de producto y partes interesadas en cumplimiento
- Se integra en pipelines CI/CD para prevenir regresiones de accesibilidad
Diferenciadores clave:
- Patrones de corrección conscientes del framework (no consejos HTML genéricos)
- Análisis de contraste de color con sugerencias de alternativas accesibles
- Cobertura de WCAG 2.2 incluyendo los criterios de éxito más nuevos (Apariencia de Enfoque, Movimientos de Arrastre, Tamaño de Objetivo)
- Integración en pipeline CI/CD con GitHub Actions, GitLab CI y Azure DevOps
- Soporte de comando slash via
/a11y-audit
Características
Capacidades principales
| Característica | Descripción |
|---|---|
| Escaneo Completo WCAG 2.2 | Verifica todos los criterios de éxito Nivel A y AA en tu código base |
| Detección de Framework | Detecta automáticamente React, Next.js, Vue, Angular, Svelte o HTML plano |
| Clasificación de Severidad | Categoriza cada violación como Crítica, Mayor o Menor |
| Generación de Código de Corrección | Produce diferencias de código antes/después para cada problema |
| Verificador de Contraste de Color | Valida pares de primer/segundo plano contra ratios AA y AAA |
| Alternativas Accesibles | Sugiere colores de reemplazo que cumplen con los requisitos de contraste |
| Informes de Cumplimiento | Genera informes para partes interesadas con resúmenes de aprobado/reprobado |
| Integración CI/CD | Configuraciones de pipeline para GitHub Actions, GitLab CI, Azure DevOps |
| Auditoría de Navegación por Teclado | Detecta problemas de gestión de enfoque y orden de tabulación faltantes |
| Validación ARIA | Verifica atributos ARIA incorrectos, redundantes o faltantes |
| Detección de Regiones Vivas | Identifica contenido dinámico que carece de anuncios aria-live |
| Accesibilidad de Formularios | Valida asociaciones de etiquetas, mensajes de error y tipos de entrada |
Matriz de Cobertura WCAG 2.2
| Principio | Criterios Nivel A | Criterios Nivel AA |
|---|---|---|
| Perceptible | 1.1.1 Contenido No Textual, 1.2.1-1.2.3 Medios Basados en el Tiempo, 1.3.1-1.3.3 Adaptable, 1.4.1-1.4.2 Distinguible | 1.3.4-1.3.5 Adaptable, 1.4.3-1.4.5 Contraste e Imágenes de Texto, 1.4.10-1.4.12 Reflujo y Contenido |
| Operable | 2.1.1-2.1.2 Teclado, 2.2.1-2.2.2 Tiempo Suficiente, 2.3.1 Convulsiones, 2.4.1-2.4.4 Navegable, 2.5.1-2.5.4 Entrada | 2.4.5-2.4.7 Navegable, 2.4.11 Apariencia de Enfoque (NUEVO 2.2), 2.5.7 Arrastre (NUEVO 2.2), 2.5.8 Tamaño de Objetivo (NUEVO 2.2) |
| Comprensible | 3.1.1 Idioma de la Página, 3.2.1-3.2.2 Predecible, 3.3.1-3.3.2 Asistencia para la Entrada | 3.1.2 Idioma de las Partes, 3.2.3-3.2.4 Predecible, 3.3.3-3.3.4 Manejo de Errores, 3.3.7 Entrada Redundante (NUEVO 2.2), 3.3.8 Autenticación Accesible (NUEVO 2.2) |
| Robusto | 4.1.2 Nombre, Rol, Valor | 4.1.3 Mensajes de Estado |
Definiciones de Severidad
| Severidad | Definición | Ejemplo | SLA |
|---|---|---|---|
| Crítica | Bloquea el acceso para grupos enteros de usuarios | Texto alternativo faltante en imágenes informativas, sin acceso por teclado a la navegación principal | Corregir antes del lanzamiento |
| Mayor | Barrera significativa que degrada la experiencia | Contraste de color insuficiente en el texto del cuerpo, etiquetas de formulario faltantes | Corregir dentro del sprint actual |
| Menor | Problema de usabilidad que causa fricción | Roles ARIA redundantes, jerarquía de encabezados subóptima | Corregir dentro de los próximos 2 sprints |
Uso
Inicio Rápido
Activa la habilidad y ejecuta una auditoría en tu proyecto:
# Escanear proyecto completo
python scripts/a11y_scanner.py /ruta/al/proyecto
# Escanear con salida JSON para herramientas
python scripts/a11y_scanner.py /ruta/al/proyecto --json
# Verificar contraste de color para valores específicos
python scripts/constrast_checker.py --fg "#777777" --bg "#ffffff"
# Verificar contraste en un archivo CSS/Tailwind
python scripts/constrast_checker.py --file /ruta/a/styles.css
Comando Slash
Usa el comando slash /a11y-audit para una sesión de auditoría interactiva:
/a11y-audit # Auditar proyecto actual
/a11y-audit --scope src/ # Auditar directorio específico
/a11y-audit --fix # Auditar y aplicar correcciones automáticamente
/a11y-audit --report # Generar informe para partes interesadas
/a11y-audit --ci # Salida de resultados compatible con CI
Flujo de Trabajo en Tres Fases
Fase 1: Escaneo
El escáner recorre tu árbol de código fuente, detecta el framework en uso y aplica el conjunto de reglas apropiado.
python scripts/a11y_scanner.py /ruta/al/proyecto --format table
Salida de ejemplo:
INFORME DE AUDITORÍA A11Y - /ruta/al/proyecto
Framework Detectado: React (Next.js)
Archivos Escaneados: 127
━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
CRÍTICAS (3 problemas)
[1.1.1] src/components/Hero.tsx:14
Falta texto alternativo en elemento <img>
[2.1.1] src/components/Modal.tsx:8
Enfoque no está atrapado dentro del diálogo modal
[1.4.3] src/styles/globals.css:42
Relación de contraste 2.8:1 en .subtitle (requiere 4.5:1)
MAYORES (7 problemas)
[2.4.11] src/components/Button.tsx:22
Indicador de enfoque no visible (se requiere contorno de 2px)
[1.3.1] src/components/Form.tsx:31
Entrada sin <label> asociado
...
MENORES (4 problemas)
[1.3.1] src/components/Nav.tsx:5
<nav> tiene role="navigation" redundante
...
━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
RESUMEN: 14 violaciones (3 Críticas, 7 Mayores, 4 Menores)
WCAG 2.2 Nivel A: 8 problemas
WCAG 2.2 Nivel AA: 6 problemas
Fase 2: Corrección
Para cada violación, aplica la corrección específica del framework. La habilidad proporciona código exacto antes/después para cada tipo de problema.
Consulta la sección Patrones de Corrección por Framework a continuación para ver el catálogo completo de correcciones.
Fase 3: Verificación
Vuelve a ejecutar el escáner para confirmar que todas las correcciones se han aplicado y no se han introducido regresiones:
# Reescanear después de correcciones
python scripts/a11y_scanner.py /ruta/al/proyecto --format table
# Comparar con la línea base
python scripts/a11y_scanner.py /ruta/al/proyecto --baseline audit-baseline.json
Salida de verificación:
RESULTADOS DE VERIFICACIÓN
━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
Escaneo Anterior: 14 violaciones (3 Críticas, 7 Mayores, 4 Menores)
Escaneo Actual: 2 violaciones (0 Críticas, 1 Mayor, 1 Menor)
Resueltas: 12 violaciones
Nuevos Problemas: 0 regresiones
ESTADO: MEJORADO (reducción del 85.7%)
Ejemplos
Ejemplo 1: Auditoría de Componente React
Dado un componente React con múltiples problemas de accesibilidad:
// ANTES: src/components/ProductCard.tsx
function ProductCard({ product }) {
return (
<div onClick={() => navigate(`/product/${product.id}`)}>
<img src={product.image} />
<div style={{ color: '#aaa', fontSize: '12px' }}>
{product.name}
</div>
<span style={{ color: '#999' }}>${product.price}</span>
</div>
);
}
Violaciones detectadas:
| # | WCAG | Severidad | Problema |
|---|---|---|---|
| 1 | 1.1.1 | Crítica | Atributo alt faltante en <img> |
| 2 | 2.1.1 | Crítica | <div onClick> no accesible por teclado |
| 3 | 1.4.3 | Mayor | Color #aaa sobre blanco falla contraste (2.32:1, necesita 4.5:1) |
| 4 | 1.4.3 | Mayor | Color #999 sobre blanco falla contraste (2.85:1, necesita 4.5:1) |
| 5 | 4.1.2 | Mayor | Elemento interactivo sin rol ni nombre accesible |
// DESPUÉS: src/components/ProductCard.tsx
function ProductCard({ product }) {
return (
<a
href={`/product/${product.id}`}
className="product-card"
aria-label={`Ver ${product.name} - $${product.price}`}
>
<img src={product.image} alt={product.imageAlt || product.name} />
<div style={{ color: '#595959', fontSize: '12px' }}>
{product.name}
</div>
<span style={{ color: '#767676' }}>${product.price}</span>
</a>
);
}
Qué cambió:
<div onClick>reemplazado con<a href>para soporte nativo de teclado y lectores de pantalla- Atributo
altañadido a<img>con un valor significativo alternativo aria-labelproporciona contexto completo para la tecnología de asistencia- Color
#aaareemplazado con#595959(relación de contraste 7.01:1 — pasa AA y AAA) - Color
#999reemplazado con#767676(relación de contraste 4.54:1 — pasa AA)
Ejemplo 2: Auditoría de SFC Vue (Formulario)
<!-- ANTES: src/components/LoginForm.vue -->
<template>
<form @submit="handleLogin">
<input type="text" placeholder="Correo electrónico" v-model="email" />
<input type="password" placeholder="Contraseña" v-model="password" />
<div v-if="error" style="color: red">{{ error }}</div>
<div @click="handleLogin">Iniciar sesión</div>
</form>
</template>
Violaciones detectadas:
| # | WCAG | Severidad | Problema |
|---|---|---|---|
| 1 | 1.3.1 | Crítica | Entradas sin elementos <label> asociados |
| 2 | 3.3.2 | Mayor | Texto de marcador de posición usado como única etiqueta (desaparece al escribir) |
| 3 | 2.1.1 | Crítica | <div @click> no accesible por teclado |
| 4 | 4.1.3 | Mayor | Mensaje de error no anunciado a lectores de pantalla |
| 5 | 3.3.1 | Mayor | Error no asociado programáticamente con la entrada |
<!-- DESPUÉS: src/components/LoginForm.vue -->
<template>
<form @submit.prevent="handleLogin" aria-label="Inicia sesión en tu cuenta">
<div class="field">
<label for="login-email">Correo electrónico</label>
<input
id="login-email"
type="email"
v-model="email"
autocomplete="email"
required
:aria-describedby="emailError ? 'email-error' : undefined"
:aria-invalid="!!emailError"
/>
<span v-if="emailError" id="email-error" role="alert">
{{ emailError }}
</span>
</div>
<div class="field">
<label for="login-password">Contraseña</label>
<input
id="login-password"
type="password"
v-model="password"
autocomplete="current-password"
required
:aria-describedby="passwordError ? 'password-error' : undefined"
:aria-invalid="!!passwordError"
/>
<span v-if="passwordError" id="password-error" role="alert">
{{ passwordError }}
</span>
</div>
<div v-if="error" role="alert" aria-live="assertive" class="form-error">
{{ error }}
</div>
<button type="submit">Iniciar sesión</button>
</form>
</template>
Ejemplo 3: Auditoría de Plantilla Angular
<!-- ANTES: src/app/dashboard/dashboard.component.html -->
<div class="tabs">
<div *ngFor="let tab of tabs"
(click)="selectTab(tab)"
[class.active]="tab.active">
{{ tab.label }}
</div>
</div>
<div class="tab-content">
<div *ngIf="selectedTab">{{ selectedTab.content }}</div>
</div>
Violaciones detectadas:
| # | WCAG | Severidad | Problema |
|---|---|---|---|
| 1 | 4.1.2 | Crítica | Widget de pestañas sin roles ARIA (tablist, tab, tabpanel) |
| 2 | 2.1.1 | Crítica | Pestañas no navegables por teclado (teclas de flecha, Inicio, Fin) |
| 3 | 2.4.11 | Mayor | Sin indicador de enfoque visible en la pestaña activa |
<!-- DESPUÉS: src/app/dashboard/dashboard.component.html -->
<div class="tabs" role="tablist" aria-label="Secciones del panel">
<button
*ngFor="let tab of tabs; let i = index"
role="tab"
[id]="'tab-' + tab.id"
[attr.aria-selected]="tab.active"
[attr.aria-controls]="'panel-' + tab.id"
[attr.tabindex]="tab.active ? 0 : -1"
(click)="selectTab(tab)"
(keydown)="handleTabKeydown($event, i)"
class="tab-button"
[class.active]="tab.active">
{{ tab.label }}
</button>
</div>
<div
*ngIf="selectedTab"
role="tabpanel"
[id]="'panel-' + selectedTab.id"
[attr.aria-labelledby]="'tab-' + selectedTab.id"
tabindex="0"
class="tab-content">
{{ selectedTab.content }}
</div>
TypeScript de soporte para la navegación por teclado:
// dashboard.component.ts
handleTabKeydown(event: KeyboardEvent, index: number): void {
const tabCount = this.tabs.length;
let newIndex = index;
switch (event.key) {
case 'ArrowRight':
newIndex = (index + 1) % tabCount;
break;
case 'ArrowLeft':
newIndex = (index - 1 + tabCount) % tabCount;
break;
case 'Home':
newIndex = 0;
break;
case 'End':
newIndex = tabCount - 1;
break;
default:
return;
}
event.preventDefault();
this.selectTab(this.tabs[newIndex]);
// Mover el enfoque al botón de la nueva pestaña
const tabElement = document.getElementById(`tab-${this.tabs[newIndex].id}`);
tabElement?.focus();
}
Ejemplo 4: Auditoría de Página en Next.js
// ANTES: src/app/page.tsx
export default function Home() {
return (
<main>
<div className="text-4xl font-bold">Bienvenido a Acme</div>
<div className="mt-4">
Construye mejores productos con nuestra plataforma.
</div>
<div className="mt-8 bg-blue-600 text-white px-6 py-3 rounded cursor-pointer"
onClick={() => router.push('/signup')}>
Comenzar
</div>
</main>
);
}
Violaciones detectadas:
| # | WCAG | Severidad | Problema |
|---|---|---|---|
| 1 | 1.1.1 | Crítica | Encabezado sin semántica adecuada (no es un <h1>) |
| 2 | 2.1.1 | Crítica | Botón de llamada a la acción no accesible por teclado |
| 3 | 1.4.3 | Mayor | Texto del cuerpo sin tamaño de fuente mínimo o línea de base de contraste |
// DESPUÉS: src/app/page.tsx
export default function Home() {
return (
<main>
<h1 className="text-4xl font-bold">Bienvenido a Acme</h1>
<p className="mt-4 text-gray-700">
Construye mejores productos con nuestra plataforma.
</p>
<Link
href="/signup"
className="inline-block mt-8 bg-blue-600 text-white px-6 py-3 rounded focus:outline-2 focus:outline-offset-2 focus:outline-blue-800"
>
Comenzar
</Link>
</main>
);
}
Qué cambió:
<div>sin semántica reemplazado con<h1>y<p>apropiados<div onClick>reemplazado con el componente<Link>de Next.js para navegación accesible- Indicador de enfoque añadido (
focus:outline-2 focus:outline-offset-2 focus:outline-blue-800) - Texto del cuerpo ahora usa una escala de grises accesible
Patrones de Corrección por Framework
React / Next.js
| Problema | Patrón Incorrecto | Corrección |
|---|---|---|
Falta alt | <img src={src} /> | <img src={src} alt={altText} /> |
| Click sin teclado | <div onClick={fn}> | <button onClick={fn}> o <a href={url}> |
| Contraste bajo | style={{ color: '#aaa' }} | style={{ color: '#595959' }} (verificar ratio 4.5:1) |
| Etiqueta de formulario faltante | <input placeholder="Email" /> | <label htmlFor="id">Email</label><input id="id" /> |
| Sin indicador de enfoque | Sin estilos :focus | className="focus:outline-2 focus:outline-blue-500" (Tailwind) |
| ARIA redundante | <nav role="navigation"> | <nav> |
| Tabla sin | <table><tr>...</tr></table> | <table><caption>Descripción</caption>... |
Vue
| Problema | Patrón Incorrecto | Corrección |
|---|---|---|
Falta alt | <img :src="src" /> | <img :src="src" :alt="altText" /> |
| Etiqueta de formulario faltante | <input v-model="email" placeholder="Email" /> | <label for="email">Email</label><input id="email" v-model="email" /> |
| Click sin teclado | <div @click="fn"> | <button @click="fn"> o <router-link to="..."> |
| Mensaje de error no anunciado | <div v-if="error" style="color: red"> | <div v-if="error" role="alert" aria-live="assertive"> |
| Falta relación aria-describedby | <input :aria-invalid="!!error" /> | <input :aria-describedby="errorId" :aria-invalid="!!error" /> |
Angular
| Problema | Patrón Incorrecto | Corrección |
|---|---|---|
| Falta rol ARIA en pestañas | <div (click)="selectTab(tab)"> | <button role="tab" (click)="selectTab(tab)" [attr.aria-selected]="..."> |
| Panel de pestañas sin aria-labelledby | <div *ngIf="tab">{{tab.content}}</div> | <div role="tabpanel" [attr.aria-labelledby]="'tab-' + tab.id"> |
| Navegación por teclado faltante | Solo (click) en pestañas | Añadir (keydown)="handleKeydown($event, i)" con lógica de flechas/Inicio/Fin |
| Sin indicador de enfoque | Sin estilos CSS :focus-visible | button:focus-visible { outline: 2px solid blue; } |
Svelte
| Problema | Patrón Incorrecto | Corrección |
|---|---|---|
Falta alt | <img src={src}> | <img src={src} alt={altText}> |
| Click sin teclado | <div on:click={handler}> | <button on:click={handler}> |
| Etiqueta de formulario faltante | <input bind:value={email} placeholder="Email" /> | <label for="email">Email</label><input id="email" bind:value={email} /> |
| Región viva faltante | {#if error}<div>{error}</div>{/if} | {#if error}<div role="alert" aria-live="assertive">{error}</div>{/if} |
HTML Plano
| Problema | Patrón Incorrecto | Corrección |
|---|---|---|
Falta alt | <img src="photo.jpg"> | <img src="photo.jpg" alt="Descripción de la foto"> |
| Click sin teclado | <div onclick="submit()">Enviar</div> | <button type="submit">Enviar</button> |
| Etiqueta de formulario faltante | <input type="text" placeholder="Nombre"> | <label for="name">Nombre</label><input id="name" type="text"> |
| Sin idioma en la página | <html> | <html lang="es"> |
| Encabezados saltados | <h1>Título</h1><h3>Subtítulo</h3> | <h1>Título</h1><h2>Subtítulo</h2> |
| Sin doctype | <html> | <!DOCTYPE html><html lang="es"> |
Integración CI/CD
GitHub Actions
name: Auditoría de Accesibilidad
on: [push, pull_request]
jobs:
a11y:
runs-on: ubuntu-latest
steps:
- uses: actions/checkout@v4
- name: Ejecutar escaneo de accesibilidad
run: |
python scripts/a11y_scanner.py . --json --output a11y-report.json
- name: Fallar si hay problemas críticos
run: |
python scripts/check_severity.py a11y-report.json --fail-on critical
GitLab CI
stages:
- accessibility
a11y-audit:
stage: accessibility
image: python:3.11-slim
script:
- pip install -r requirements.txt # Solo si hay dependencias externas
- python scripts/a11y_scanner.py . --json --output a11y-report.json
- python scripts/check_severity.py a11y-report.json --fail-on critical
artifacts:
paths:
- a11y-report.json
Azure DevOps
- job: Accesibilidad
pool:
vmImage: 'ubuntu-latest'
steps:
- script: |
python scripts/a11y_scanner.py . --json --output $(Build.ArtifactStagingDirectory)/a11y-report.json
displayName: 'Escaneo de Accesibilidad'
- script: |
python scripts/check_severity.py $(Build.ArtifactStagingDirectory)/a11y-report.json --fail-on critical
displayName: 'Verificar Severidad'
Preguntas Frecuentes
P: ¿Puedo usar esta habilidad con un proyecto que no esté en mi sistema de archivos local? R: Sí. La habilidad puede escanear directorios remotos o repositorios clonados. Para una integración CI/CD, consulta las configuraciones de pipeline anteriores.
P: ¿Qué frameworks están soportados? R: React, Next.js, Vue, Angular, Svelte y HTML plano. El escáner detecta automáticamente el framework que estás usando.
P: ¿Cómo verifico el contraste de color con esta habilidad?
R: Usa el script contrast_checker.py con valores de primer y segundo plano (foreground/background) o pasa un archivo CSS/Tailwind para un análisis por lotes.
P: ¿Esta habilidad incluye los nuevos criterios de WCAG 2.2? R: Sí. Cubre Apariencia de Enfoque (2.4.11), Movimientos de Arrastre (2.5.7), Tamaño de Objetivo (2.5.8), Entrada Redundante (3.3.7) y Autenticación Accesible (3.3.8).
P: ¿Puedo aplicar correcciones automáticamente?
R: El modo --fix aplicará correcciones conocidas automáticamente. Siempre recomendamos revisar los cambios antes de confirmarlos.
P: ¿Qué pasa si mi framework no está en la lista? R: El escáner recurre a HTML plano y aplica reglas genéricas. Los patrones de corrección seguirán siendo relevantes, pero las diferencias de código pueden no ser tan específicas del framework.
Licencia
MIT
Soporte
Para problemas, solicitudes de características o contribuciones, consulta el repositorio del proyecto o crea un problema.
