Guía de uso

Todo lo que necesita para analizar la accesibilidad HTML con Speakable — desde la instalación hasta la integración CI/CD.

Instalación

Instale como dependencia de proyecto para uso programático y pipelines CI, o globalmente para acceso CLI en cualquier lugar.

Terminal

# Install as a project dependency
npm install @reticular/speakable

# Or install globally for CLI access
npm install -g @reticular/speakable

Comandos CLI

El binario speakable acepta rutas de archivos HTML como argumentos. Todas las opciones son flags — sin subcomandos.

Terminal

# Basic analysis (JSON output, NVDA by default)
speakable page.html

# Choose output format: json, text, audit, or both
speakable page.html -f text
speakable page.html -f json
speakable page.html -f audit
speakable page.html -f both

# Choose screen reader: nvda, jaws, voiceover, or all
speakable page.html -s nvda
speakable page.html -s jaws
speakable page.html -s voiceover
speakable page.html -s all

# Filter to specific elements with a CSS selector
speakable page.html --selector "button"

# Compare two HTML files (semantic diff)
speakable new.html --diff old.html

# Batch process multiple files
speakable --batch file1.html file2.html file3.html

# Write output to a file
speakable page.html -o output.json

# Read from stdin
cat page.html | speakable -

# Validate round-trip serialization
speakable page.html --validate

Formatos de salida

Speakable admite cuatro formatos de salida, cada uno adecuado para diferentes flujos de trabajo.

Format	Flag	Description
JSON	-f json	Canonical accessibility model as deterministic JSON. Best for CI/CD, snapshot testing, and programmatic comparison.
Text	-f text	Screen reader announcement text. Shows what each reader would say, line by line. Human-readable.
Audit	-f audit	Structured report with landmark structure, heading hierarchy, interactive elements, detected issues (error/warning/info), and summary statistics.
Both	-f both	JSON model and screen reader text combined in a single output.

Funciones Pro

Procesamiento por lotes

Analice múltiples archivos en una sola ejecución. El modo por lotes continúa procesando incluso si archivos individuales fallan, y reporta un resumen al final.

speakable --batch file1.html file2.html file3.html

Diff semántico

Compare HTML antes/después para detectar regresiones de accesibilidad. El diff identifica nodos añadidos, eliminados y modificados con detalle a nivel de propiedad (nombre, rol, estado, foco).

speakable new.html --diff old.html

Integración CI/CD

Use códigos de salida y salida JSON para verificaciones automatizadas de pipeline. Exit 0 = éxito, exit 1 = error de usuario, exit 2 = problemas de contenido o cambios en diff, exit 3 = error del sistema.

npx @reticular/speakable page.html -f audit

Analizador web

El analizador web en /tool le permite pegar HTML directamente y ver resultados al instante — sin necesidad de instalación.

Pegue su HTML en el área de texto
Seleccione un lector de pantalla (NVDA, JAWS, VoiceOver o Todos)
Opcionalmente ingrese un selector CSS para enfocarse en elementos específicos
Haga clic en Analizar para ver la salida predicha

Active el modo diff para comparar dos fragmentos HTML lado a lado. Speakable le mostrará exactamente qué nodos del árbol de accesibilidad fueron añadidos, eliminados o modificados entre las dos versiones.

Después de analizar, haga clic en el icono 🔊 en la barra de herramientas de salida para escuchar los resultados en voz alta, o cambie al modo línea por línea para navegar la salida un anuncio a la vez usando atajos de teclado.

Anunciador de voz

El analizador web y la extensión del navegador incluyen un anunciador de voz integrado que lee la salida del análisis en voz alta usando la API nativa SpeechSynthesis del navegador.

Reproducir todo

Lee toda la salida secuencialmente con pausas entre líneas y pausas más largas entre secciones de lectores de pantalla.

Navegación línea por línea

Imita cómo los usuarios de lectores de pantalla realmente navegan: un elemento a la vez.

Key	Action
↓ / j	Move to next line and speak it
↑ / k	Move to previous line and speak it
Enter / Space	Play all from current line
Escape	Stop speech and exit line-by-line mode

Controles de voz y velocidad

El menú desplegable de voz incluye un selector de voz y un control deslizante de velocidad que va de 0.5x a 2.0x.

Mejores prácticas

Ejecute en CI para detección de regresiones

Agregue Speakable a su pipeline de compilación para que cada PR sea verificado por cambios de accesibilidad.

Use selectores para análisis a nivel de componente

Enfóquese en componentes específicos con --selector en lugar de analizar páginas completas.

Verifique los tres lectores

Use -s all para ver diferencias entre plataformas. NVDA, JAWS y VoiceOver tienen patrones de anuncio únicos.

Guarde líneas base JSON para pruebas de snapshot

Almacene la salida JSON como líneas base, luego use --diff para detectar cambios entre versiones.

Comience con informes de auditoría

Use -f audit para una visión general rápida de la salud de accesibilidad antes de profundizar en la salida de lectores específicos.