A11yGuard - Accessibility Linter for VS Code

v0.3.1 · MIT License

A11yGuard detects and fixes web accessibility issues (WCAG/ADA) in real-time, directly in your VS Code editor. 51 rules, auto-fixes, accessibility score, disability simulator, screen reader preview, CI/CD integration, and more.

Features

🔍 Real-Time Detection

Analyzes HTML, JSX, TSX, Vue, and Svelte files as you type. Issues appear as squiggly underlines in your editor, color-coded by severity:

Issues also appear in the Problems panel and the dedicated A11yGuard Issues sidebar in the Explorer.

🔧 Automatic Quick Fixes

Place your cursor on an underlined issue and press Ctrl+. (Cmd+. on Mac):

• Context-aware fixes generated from your actual code
• Multiple fix options per issue (e.g., add alt="" vs alt="description")
• Preferred fix marked for one-click resolution
• Links to official WCAG documentation

Supported fixes: image-alt, button-name, link-name, label, html-has-lang, meta-viewport, tabindex, document-title, and more.

📊 Score A-F por archivo (#6)

A real-time accessibility score appears in the status bar for the active file:

✅ A11y: A+ (100/100)     ⚠️ A11y: C (72/100)     ❌ A11y: F (15/100)

• Score from 0 to 100 based on issue penalties (critical=25, serious=15, moderate=8, minor=3)
• Grade from A+ to F
• Background color changes: green (≥90), orange (≥70), red (<70)
• Click to reveal the Issues panel

📈 Dashboard de proyecto (#7)

Open the command palette and run A11yGuard: Show Dashboard to see:

• Score promedio del workspace con calificación visual (anillo SVG)
• Total de problemas y distribución por severidad (barra de colores)
• Top 10 reglas más violadas con barras proporcionales
• Archivos más problemáticos con count de issues, críticos, y score
• Click en cualquier archivo para abrirlo

🎨 Heatmap de severidad (#8)

Los archivos en el Explorer muestran badges con el número de issues:

• Badge rojo → tiene issues críticos
• Badge naranja → issues serios
• Badge amarillo → issues moderados
• Badge gris → solo issues menores

Tooltip muestra: A11y: 5 problemas (crítico) - Score: 42

📖 CodeLens WCAG (#12)

Sobre cada línea con issues se muestra información inline:

A11y: 2 críticos, 1 serio | WCAG 1.1.1, 4.1.2    📖 Ver docs WCAG 1.1.1

• Conteo por severidad
• Criterios WCAG aplicables
• Link directo a la documentación W3C
• Click para navegar al issue

Desactivar con a11yguard.codeLens.enabled: false.

💡 18 Snippets accesibles (#11)

Escribe a11y- en cualquier archivo soportado para ver los snippets:

🪄 Fix All (#13)

Aplica todos los auto-fixes de un archivo o de todo el workspace con un solo comando:

• A11yGuard: Fix All Issues in File — corrige el archivo activo
• A11yGuard: Fix All Issues in Workspace — corrige todo (pide confirmación)
• Aplica el fix de mayor prioridad para cada issue
• Ordena de abajo hacia arriba para no invalidar offsets
• También disponible en el menú contextual (click derecho)

🙈 Ignorar reglas con comentario (#14)

Silencia falsos positivos con comentarios inline:

<!-- a11y-ignore: image-alt -- Imagen decorativa manejada por CSS -->
<img src="https://github.com/a11yguard/a11yguard/raw/HEAD/bg-pattern.png">

{/* a11y-ignore: button-name -- El icono tiene aria-label en el SVG */}
<button><Icon /></button>

• A11yGuard: Ignore This Rule — agrega el comentario automáticamente (pide razón opcional)
• A11yGuard: Ignore Entire File — agrega <!-- a11y-ignore-file --> al inicio
• Soporta ignorar múltiples reglas: a11y-ignore: image-alt, link-name
• También en menú contextual (click derecho)

👁 Simulador de discapacidades (#16)

Comando: A11yGuard: Disability Simulator

Abre un panel lateral que renderiza tu HTML con filtros de simulación:

🔊 Lector de pantalla virtual (#17)

Comando: A11yGuard: Virtual Screen Reader

Muestra en tabla el reading order que seguiría un screen reader (NVDA, JAWS, VoiceOver):

• 🏛 Landmarks: header, nav, main, footer, aside
• 📑 Headings: h1-h6 con nivel
• 🔗 Links: texto o aria-label
• 🔘 Buttons: nombre accesible
• 📝 Forms: tipo de input + etiqueta
• 🖼 Images: alt text
• 📢 Live regions: role="alert", aria-live
• 👁 Hidden: elementos con aria-hidden="true" (tachados)

Click en cualquier fila para navegar a esa línea en el editor. Estadísticas de conteo por tipo de elemento.

📄 Exportar reportes (#18)

Comando: A11yGuard: Export Report

Genera reportes de accesibilidad en 4 formatos:

Cada reporte incluye: score promedio, distribución por severidad, detalle de cada issue con archivo, línea, regla, WCAG y nivel.

🔎 Auditoría completa (#19)

Comando: A11yGuard: Full Audit Mode

Escaneo profundo de todo el workspace:

1. Analiza todos los archivos HTML/JSX/TSX/Vue/Svelte
2. Calcula score por archivo y promedio global
3. Muestra resumen con conteo por severidad
4. Ofrece abrir el Dashboard o Exportar reporte
5. Barra de progreso con cancelación

Ideal para ejecutar antes de un release o una auditoría de cumplimiento.

🔮 Quick Fix Preview (#10)

Comando: A11yGuard: Preview Fix (Before/After)

Antes de aplicar un fix, visualiza el diff:

1. Muestra los fixes disponibles para el issue bajo el cursor
2. Abre un diff side-by-side con el antes/después
3. Pregunta si quieres aplicar el cambio
4. También en menú contextual (click derecho)

🎯 Onboarding interactivo (#9)

La primera vez que instalas A11yGuard, se abre un tutorial de 4 pasos:

1. ¿Qué hace? — Features principales
2. Cómo funciona — Ejemplos de código con errores vs correcto
3. Features avanzadas — Simulador, screen reader, snippets, auditoría
4. ¡Pruébalo! — Crea un archivo de ejemplo con errores reales

Puedes re-abrirlo con: A11yGuard: Show Welcome Tutorial

🖥 CLI para CI/CD (#15)

Integra A11yGuard en tus pipelines de GitHub Actions, GitLab CI, etc:

# Instalar globalmente
npm install -g @a11yguard/cli

# O ejecutar directamente con npx
npx @a11yguard/cli check src/

# Escanear directorio
a11yguard check src/

# Fallar si hay issues críticos
a11yguard check src/ --fail-on critical

# Score mínimo (exit code 1 si es menor)
a11yguard check . --min-score 80

# Formato para JUnit (integración CI)
a11yguard check src/ --format junit > report.xml

# JSON para procesamiento
a11yguard check . --format json

# Excluir reglas
a11yguard check . --exclude color-contrast,heading-order

# Nivel WCAG
a11yguard check . --wcag-level AAA

GitHub Actions ejemplo:

- name: Accessibility Check
  run: |
    npx @a11yguard/cli check src/ --fail-on serious --format junit > a11y-report.xml

- name: Upload Report
  uses: actions/upload-artifact@v4
  with:
    name: a11y-report
    path: a11y-report.xml

📊 Telemetría anónima

A11yGuard incluye telemetría 100% opt-in y anónima:

• Se recopila: contadores de análisis, reglas más comunes, features usadas, versión de VS Code, plataforma
• NO se recopila: código fuente, rutas de archivos, nombres, IP, datos personales
• Se pide consentimiento explícito la primera vez
• Respeta la configuración global de VS Code (telemetry.telemetryLevel)
• Desactivar: a11yguard.telemetry.enabled: false
• Ver tus datos: A11yGuard: View Telemetry Data

Installation

From VS Code Marketplace

1. Open VS Code
2. Go to Extensions (Ctrl+Shift+X / Cmd+Shift+X)
3. Search for "A11yGuard"
4. Click Install

From Command Line

code --install-extension A11YGuardTeam.a11yguard

Commands

Open the Command Palette (Ctrl+Shift+P / Cmd+Shift+P):

Configuration

Open Settings (Ctrl+, / Cmd+,) and search for "A11yGuard":

{
  // Enable/disable A11yGuard
  "a11yguard.enable": true,

  // WCAG level: "A", "AA" (default), "AAA"
  "a11yguard.wcagLevel": "AA",

  // Minimum severity: "critical", "serious", "moderate", "minor" (default)
  "a11yguard.minSeverity": "minor",

  // Analyze on file save
  "a11yguard.analyzeOnSave": true,

  // Real-time analysis as you type
  "a11yguard.analyzeOnType": true,

  // Debounce time in ms (100-5000)
  "a11yguard.debounceTime": 500,

  // Rules to exclude from analysis
  "a11yguard.excludeRules": [],

  // Rules to include (empty = all)
  "a11yguard.includeRules": [],

  // Show WCAG CodeLens above issues
  "a11yguard.codeLens.enabled": true,

  // Anonymous usage telemetry (opt-in)
  "a11yguard.telemetry.enabled": false
}

Supported Rules (51)

Perceivable (WCAG 1.x)

Operable (WCAG 2.x)

Understandable (WCAG 3.x)

Robust (WCAG 4.x)

Supported Languages

Context Menu

Right-click in a supported file to access:

• A11yGuard: Ignore This Rule — Silenciar la regla bajo el cursor
• A11yGuard: Preview Fix — Ver diff antes/después
• A11yGuard: Fix All Issues in File — Corregir todo el archivo

Troubleshooting

Extension not working?

1. Check the file type is supported (HTML, JSX, TSX, Vue, Svelte)
2. Verify a11yguard.enable is true in Settings
3. Reload window: Ctrl+Shift+P → "Developer: Reload Window"

Too many false positives?

1. Use a11yguard.excludeRules to disable specific rules
2. Increase a11yguard.minSeverity to "serious" or "critical"
3. Use inline <!-- a11y-ignore: rule-id --> for specific cases

Performance issues?

1. Increase a11yguard.debounceTime (e.g., 1000ms)
2. Disable a11yguard.analyzeOnType and analyze manually
3. Disable CodeLens: a11yguard.codeLens.enabled: false

Contributing

Contributions welcome! See our Contributing Guide.

License

MIT — See LICENSE for details.

A11yGuard — See what others can't. Protect your code's accessibility.