Saltar al contenido principal

Documentation Index

Fetch the complete documentation index at: https://mintlify-mintlify-agent-cursor-1777414560.mintlify.app/llms.txt

Use this file to discover all available pages before exploring further.

Cuando creas documentación accesible, priorizas un diseño de contenido que haga tu documentación usable por la mayor cantidad posible de personas, independientemente de cómo accedan o interactúen con ella. La documentación accesible mejora la experiencia de uso para todos. Tu contenido es más claro, está mejor estructurado y es más fácil de navegar, ya sea que las personas accedan a él con un lector de pantalla, navegación por teclado, un dispositivo móvil o conexiones de red lentas. Esta guía cubre las prácticas recomendadas para crear documentación accesible. La accesibilidad es un proceso continuo. Las tecnologías y los estándares evolucionan, y siempre hay oportunidades de mejorar. Empieza por los cambios de alto impacto e integra la accesibilidad en tu flujo de trabajo.

​
¿Qué es la accesibilidad?

La accesibilidad (a veces abreviada como a11y por el número de letras entre la primera y la última de “accessibility”) consiste en diseñar y crear intencionalmente sitios web y herramientas que puedan utilizar el mayor número posible de personas. Las personas con discapacidades temporales o permanentes deben tener el mismo nivel de acceso a las tecnologías digitales. Y diseñar con la accesibilidad en mente beneficia a todos, incluidas las personas que acceden a tu sitio web desde dispositivos móviles o redes lentas. La documentación accesible sigue los estándares de accesibilidad web, principalmente las Pautas de Accesibilidad para el Contenido Web (WCAG). Estas pautas ayudan a garantizar que tu contenido sea perceptible, operable, comprensible y sólido.

​
Comienza con la accesibilidad

Hacer que tu documentación sea accesible es un proceso. No tienes que solucionarlo todo de una vez ni puedes hacerlo solo una vez. Si recién empiezas a implementar prácticas de accesibilidad en tu documentación, considera un enfoque por fases: comienza con cambios de alto impacto y avanza a partir de allí.

​
Primeros pasos

Estas son tres acciones que puedes realizar ahora mismo para mejorar la accesibilidad de tu documentación:
  1. Ejecuta mint a11y para identificar problemas de accesibilidad en tu contenido.
  2. Añade texto alternativo a todas las imágenes.
  3. Revisa la jerarquía de encabezados para asegurarte de que haya un H1 por página y que los encabezados sigan un orden secuencial.

​
Planifica tu trabajo de accesibilidad

El mejor flujo de trabajo es el que mejor se adapta a tu equipo. Aquí tienes una forma de abordar el trabajo de accesibilidad: Fase 1: Imágenes y estructura
  • Revisa todas las imágenes para asegurarte de que tengan texto alternativo descriptivo.
  • Revisa el texto de los enlaces y reemplaza frases genéricas como “haz clic aquí”.
  • Corrige problemas en la jerarquía de encabezados en toda tu documentación.
Fase 2: Navegación y medios
  • Prueba la navegación con el teclado en tu documentación.
  • Prueba la compatibilidad con lectores de pantalla.
  • Agrega subtítulos y transcripciones a los videos incrustados.
  • Revisa el contraste de color.
Fase 3: Incorpóralo a tu flujo de trabajo
  • Ejecuta mint a11y antes de publicar contenido nuevo.
  • Incluye comprobaciones de accesibilidad en tu proceso de revisión de contenido.
  • Prueba la navegación con el teclado al agregar funciones interactivas.
  • Verifica que los nuevos enlaces externos y los contenidos incrustados incluyan títulos y descripciones adecuados.
Empezar poco a poco e integrar la accesibilidad en tu flujo de trabajo habitual la hace sostenible. Cada mejora ayuda a que más personas accedan a tu documentación con éxito.

​
Estructura tu contenido

El contenido bien estructurado es más fácil de navegar y comprender, especialmente para las personas que usan lectores de pantalla y dependen de los encabezados para desplazarse por las páginas, así como para quienes navegan con el teclado.

​
Usa una jerarquía adecuada de encabezados

Cada página debe tener un solo encabezado H1, definido por la propiedad title: en el frontmatter de la página. Usa los demás encabezados en orden, sin saltarte niveles. Por ejemplo, no pases de H2 a H4. 
<!-- Bueno -->
# Título de página (H1)

## Sección principal (H2)

### Subsección (H3)

### Otra subsección (H3)

## Otra sección principal (H2)

<!-- Malo -->
# Título de página (H1)

## Sección principal (H2)

#### Subsección (H4)

### Otra subsección (H3)
Los encabezados del mismo nivel deben tener nombres únicos. 
<!-- Bueno -->
## Consejos de accesibilidad (H2)

### Escribir texto alternativo efectivo (H3)

### Usar contraste de color adecuado (H3)

<!-- Malo -->
## Consejos de accesibilidad (H2)

### Sugerencia (H3)

### Sugerencia (H3)

​
Escribe texto de enlace descriptivo

El texto del enlace debe ser significativo y estar relacionado con el destino. Evita frases vagas como “haz clic aquí” o “leer más”. 
<!-- Bueno -->
Aprende cómo [configurar tu navegación](/organize/navigation).

<!-- Relación poco clara entre el texto del enlace y el destino -->
[Más información](/organize/navigation).

​
Mantén el contenido fácil de recorrer

  • Divide los párrafos largos.
  • Usa listas para pasos y opciones.
  • Destaca la información con avisos.

​
Usa una estructura de tabla adecuada

Usa las tablas con moderación y solo para datos tabulares cuyo significado provenga de los encabezados de columnas y filas. Cuando uses tablas, incluye encabezados para que los lectores de pantalla puedan asociar los datos con la columna correcta: 
| Función | Estado | Última actualización |
| ------- | ------ | -------------------- |
| Búsqueda  | Activa | 2024-03-15   |
| Analytics | Activa | 2024-03-10 |
| Exportaciones | Beta | 2024-03-20 |
El ejemplo deficiente carece de encabezados, lo que hace imposible que los lectores de pantalla anuncien qué representa cada columna.

​
Escribe texto alternativo descriptivo

El texto alternativo hace que las imágenes sean accesibles para las personas que usan lectores de pantalla y aparece cuando las imágenes no se cargan. Las imágenes en tu documentación deben incluir texto alternativo que describa la imagen y deje claro por qué está incluida. Incluso con texto alternativo, no debes depender únicamente de las imágenes para transmitir información. Asegúrate de que tu contenido describa lo que comunica la imagen.
Obtén más información sobre cómo trabajar con imágenes en la guía de medios.

​
Escribe texto alternativo eficaz

  • Sé específico: Describe lo que muestra la imagen, no solo que es una imagen.
  • Sé conciso: Limítate a una o dos frases.
  • Evita redundancias: No empieces con “Imagen de” porque los lectores de pantalla ya saben que el texto alternativo está asociado a una imagen. Sin embargo, incluye descripciones como “Captura de pantalla de” o “Diagrama de” si ese contexto es importante para la imagen.
<!-- Bueno -->
![Captura de pantalla del dashboard que muestra tres proyectos activos y dos invitaciones pendientes](/images/dashboard.png)

<!-- No es útil -->
![Captura de pantalla del dashboard](/images/dashboard.png)

​
Añade texto alternativo a las imágenes

Para las imágenes en Markdown, incluye el texto alternativo entre corchetes: 
![Descripción de la imagen](/path/to/image.png)
Para las imágenes en HTML, usa el atributo alt: 
<img
  src="/images/screenshot.png"
  alt="Panel de configuración con opciones de accesibilidad activadas. Las opciones están destacadas con un rectángulo naranja."
/>

​
Añade títulos al contenido incrustado

Los iframes y las inserciones de video requieren títulos descriptivos: 
<iframe
  src="https://www.youtube.com/embed/example"
  title="Tutorial: Configuración de tu primer sitio de documentación"
></iframe>

​
Diseña para mejorar la legibilidad

Las decisiones de diseño visual afectan cuán accesible es tu documentación para personas con baja visión, daltonismo u otras discapacidades visuales.

​
Asegúrate de un contraste de color suficiente

Si personalizas los colores del tema, verifica que las relaciones de contraste cumplan los requisitos de las WCAG:
  • Texto de párrafo: relación de contraste mínima de 4.5:1
  • Texto grande: relación de contraste mínima de 3:1
  • Elementos interactivos: relación de contraste mínima de 3:1
Prueba tanto el modo claro como el oscuro. El comando mint a11y comprueba el contraste de color. 
{
  "colors": {
    "primary": "#0066CC",
    "background": {
      "light": "#FFFFFF",
      "dark": "#1A1A1A"
    }
  }
}
En el ejemplo deficiente, el amarillo (#FFCC00) sobre blanco tiene un contraste insuficiente. El fondo del modo oscuro (#333333) es demasiado claro para una legibilidad óptima.

​
No dependas solo del color

Si usas el color para transmitir información, incluye también una etiqueta de texto o un icono. Por ejemplo, no marques los errores únicamente con texto rojo. Incluye un icono de error o la palabra “Error”.

​
Usa un lenguaje claro y conciso

  • Escribe con un lenguaje sencillo.
  • Define los términos técnicos cuando aparezcan por primera vez.
  • Evita las oraciones demasiado largas.
  • Usa la voz activa.
Consulta la guía de estilo y tono para conocer más prácticas recomendadas de redacción.

​
Haz que los ejemplos de código sean accesibles

Los bloques de código son una parte fundamental de la documentación técnica, pero requieren consideraciones específicas de accesibilidad para garantizar que las personas que usan lectores de pantalla puedan comprenderlos. En general, sigue estas pautas:
  • Divide los ejemplos de código largos en fragmentos más pequeños y con sentido.
  • Comenta la lógica compleja dentro del código.
  • Considera proporcionar una descripción en texto para algoritmos complejos.
  • Al mostrar la estructura de archivos, usa bloques de código reales con etiquetas de lenguaje en lugar de arte ASCII.

​
Especifica el lenguaje de programación

Declara siempre el lenguaje para el resaltado de sintaxis. Esto ayuda a los lectores de pantalla a anunciar el contexto del código a los usuarios: 
```javascript
function getUserData(id) {
  return fetch(`/api/users/${id}`);
}
```

​
Proporciona contexto del código

Proporciona contexto claro para los bloques de código: 
La siguiente función obtiene datos de usuario desde la API:

```javascript
function getUserData(id) {
  return fetch(`/api/users/${id}`);
}
```

Esto devuelve una promesa que se resuelve en el objeto de usuario.

​
Accesibilidad de vídeo y multimedia

Los vídeos, las animaciones y otros contenidos multimedia necesitan alternativas textuales para que todas las personas puedan acceder a la información que contienen.

​
Agrega subtítulos a los videos

Los subtítulos hacen que el contenido de video sea accesible para personas sordas o con discapacidad auditiva. También ayudan a quienes están en entornos sensibles al sonido y a hablantes no nativos:
  • Usa subtítulos para todo el contenido hablado en los videos.
  • Incluye efectos de sonido relevantes en los subtítulos.
  • Asegúrate de que los subtítulos estén sincronizados con el audio.
  • Usa puntuación adecuada e identifica a los interlocutores cuando hablen varias personas.
La mayoría de las plataformas de alojamiento de videos admiten subtítulos. Sube archivos de subtítulos o usa subtítulos generados automáticamente como punto de partida y luego revísalos para verificar su precisión.

​
Proporciona transcripciones

Las transcripciones ofrecen una forma alternativa de acceder al contenido de video. Se pueden buscar, son más fáciles de consultar y accesibles para los lectores de pantalla: 
<iframe
  src="https://www.youtube.com/embed/example"
  title="Tutorial: Configuración de autenticación"
></iframe>

<Accordion title="Transcripción del video">
En este tutorial, veremos cómo configurar la autenticación...
</Accordion>
Coloca las transcripciones junto al video o proporciona un enlace claro para acceder a ellas.

​
Considera alternativas al contenido exclusivamente en video

Si la información crítica solo aparece en un video:
  • Proporciona la misma información en formato de texto.
  • Incluye capturas de pantalla clave con texto alternativo descriptivo.
  • Crea un tutorial escrito que cubra el mismo material.
Esto garantiza que los usuarios que no pueden acceder al contenido en video puedan igualmente completar su tarea.

​
Prueba tu documentación

Probar con regularidad te ayuda a detectar problemas de accesibilidad antes de que los usuarios se encuentren con ellos.

​
Detecta problemas de accesibilidad con mint a11y

Usa el comando de la CLI mint a11y para analizar automáticamente tu documentación en busca de problemas de accesibilidad comunes: 
mint a11y
El comando verifica:
  • Falta de texto alternativo en imágenes y videos.
  • Contraste de color insuficiente.

​
Interpreta el resultado

Cuando se complete el análisis, verás un informe como este: 
Accessibility Issues Found:

❌ Missing alt text (3 issues)
  - /guides/quickstart.mdx:45 - Image missing alt text
  - /api-reference/users.mdx:12 - Image missing alt text
  - /guides/setup.mdx:89 - Video missing title attribute

⚠️  Color contrast (2 issues)
  - Primary color (#FFCC00) on light background fails WCAG AA (2.1:1)
  - Link color (#FF6B6B) on dark background fails WCAG AA (3.2:1)

✅ 0 issues found in 15 other pages

​
Soluciona problemas comunes

Texto alternativo faltante: Añade texto alternativo descriptivo a la imagen o video: 
<!-- Antes -->
![](/images/dashboard.png)

<!-- Después -->
![Dashboard que muestra tres proyectos activos y dos invitaciones pendientes](/images/dashboard.png)
Fallos de contraste de color: Actualiza los colores del tema en docs.json: 
{
  "colors": {
    "primary": "#0066CC",  // Cambiado de #FFCC00
    "light": "#3399FF",
    "dark": "#004C99"
  }
}
Ejecuta mint a11y nuevamente para verificar tus correcciones.

​
Usa flags para comprobaciones específicas

Usa flags para comprobar problemas de accesibilidad específicos: 
# Verifica solo el texto alternativo faltante
mint a11y --skip-contrast

# Verifica solo problemas de contraste de color
mint a11y --skip-alt-text

# Falla el pipeline de CI/CD si se encuentran problemas
mint a11y --fail-on-error

​
Prueba básica de navegación con teclado

Navega por tu documentación usando solo el teclado:
  1. Pulsa Tab para avanzar por los elementos interactivos.
  2. Pulsa Shift + Tab para retroceder.
  3. Pulsa Enter para activar enlaces y botones.
  4. Comprueba que todos los elementos interactivos sean accesibles y tengan indicadores de foco visibles.

​
Profundiza en las pruebas de accesibilidad

Para realizar pruebas más completas:

​
Preguntas frecuentes

La mayoría de las organizaciones aspiran a cumplir con el Nivel AA de WCAG 2.1, que es el estándar para muchos requisitos legales y ofrece un buen equilibrio entre accesibilidad y viabilidad. El Nivel AAA es más estricto y puede no ser alcanzable para todos los tipos de contenido.Empieza con el Nivel AA como base. El comando mint a11y comprueba requisitos comunes del Nivel AA, como el contraste de color y el texto alternativo.
En Mac, usa el VoiceOver integrado (pulsa Cmd + F5 para activarlo). En Windows, descarga NVDA (gratuito y de código abierto). Navega por tu documentación usando solo el lector de pantalla y escucha si los encabezados se anuncian correctamente, si el texto de los enlaces es descriptivo, si las imágenes tienen texto alternativo y si el orden de lectura es lógico. No necesitas ser experto para detectar los problemas más importantes.
El texto alternativo lo leen los lectores de pantalla y aparece cuando las imágenes no se cargan. Describe lo que muestra la imagen y por qué es relevante. El texto alternativo es obligatorio para la accesibilidad.Los pies de imagen aparecen debajo de las imágenes para todos los usuarios. Aportan contexto adicional, atribución o explicación. Los pies de imagen son opcionales y complementan al texto alternativo.Usa ambos cuando una imagen necesite descripción (texto alternativo) y contexto adicional (pie de imagen).
Sí, pero con moderación. Los lectores de pantalla anuncian en voz alta los nombres de los emojis, por lo que varios emojis seguidos resultan disruptivos. Por ejemplo, 🎉 se convierte en “party popper” y 🚀 en “rocket”, de modo que 🎉 🚀 se convierte en “party popper rocket”. Evita usar emojis para transmitir información crítica. Si se eliminara el emoji, el significado debería seguir siendo claro. Cuando tengas dudas, usa texto.
Especifica el lenguaje en cada bloque de código para el resaltado de sintaxis. Proporciona contexto antes y después de los bloques de código para que las personas que usan lectores de pantalla entiendan qué hace el código, ya que los lectores de pantalla suelen omitir el código en sí. Divide los ejemplos largos en fragmentos más pequeños y usa nombres de variables descriptivos que tengan sentido al leerse en voz alta.
Prioriza por impacto. Soluciona primero el texto alternativo faltante, la navegación por teclado deficiente y el contraste de color insuficiente, ya que son los que afectan a más usuarios. Luego siguen la jerarquía deficiente de encabezados y el texto de enlace impreciso. Documenta los problemas conocidos junto con un plan para abordarlos. El progreso es mejor que la perfección.

​
Recursos adicionales

Sigue aprendiendo sobre accesibilidad con estos recursos de confianza: