> ## Documentation Index
> Fetch the complete documentation index at: https://adminroletesting-justin-client-exports.mintlify.site/llms.txt
> Use this file to discover all available pages before exploring further.

# Cómo crear documentación accesible

> Crea documentación accesible siguiendo las pautas WCAG con HTML semántico, navegación por teclado, texto alternativo y prácticas de contenido inclusivo.

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.

<div id="what-is-accessibility">
  ## ¿Qué es la accesibilidad?
</div>

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)](https://www.w3.org/WAI/WCAG22/quickref/). Estas pautas ayudan a garantizar que tu contenido sea perceptible, operable, comprensible y sólido.

<div id="get-started-with-accessibility">
  ## Comienza con la accesibilidad
</div>

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í.

<div id="first-steps">
  ### Primeros pasos
</div>

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.

<div id="plan-your-accessibility-work">
  ### Planifica tu trabajo de accesibilidad
</div>

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.

<div id="structure-your-content">
  ## Estructura tu contenido
</div>

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.

<div id="use-proper-heading-hierarchy">
  ### Usa una jerarquía adecuada de encabezados
</div>

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.

```mdx theme={null}
<!-- 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.

```mdx theme={null}
<!-- 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)
```

<div id="write-descriptive-link-text">
  ### Escribe texto de enlace descriptivo
</div>

El texto del enlace debe ser significativo y estar relacionado con el destino. Evita frases vagas como "haz clic aquí" o "leer más".

```mdx theme={null}
<!-- 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).
```

<div id="keep-content-scannable">
  ### Mantén el contenido fácil de recorrer
</div>

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

<div id="use-proper-table-structure">
  ### Usa una estructura de tabla adecuada
</div>

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:

<CodeGroup>
  ```mdx Estructura de tabla adecuada theme={null}
  | Función | Estado | Última actualización |
  | ------- | ------ | -------------------- |
  | Búsqueda  | Activa | 2024-03-15   |
  | Analytics | Activa | 2024-03-10 |
  | Exportaciones | Beta | 2024-03-20 |
  ```

  ```mdx Estructura de tabla deficiente theme={null}
  | Búsqueda | Activa | 2024-03-15 |
  | Analytics | Activa | 2024-03-10 |
  | Exportaciones | Beta | 2024-03-20 |
  ```
</CodeGroup>

El ejemplo deficiente carece de encabezados, lo que hace imposible que los lectores de pantalla anuncien qué representa cada columna.

<div id="write-descriptive-alt-text">
  ## Escribe texto alternativo descriptivo
</div>

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.

<Tip>
  Obtén más información sobre cómo trabajar con imágenes en la [guía de medios](/es/guides/media).
</Tip>

<div id="write-effective-alt-text">
  ### Escribe texto alternativo eficaz
</div>

* **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.

```mdx theme={null}
<!-- 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)
```

<div id="add-alt-text-to-images">
  ### Añade texto alternativo a las imágenes
</div>

Para las imágenes en Markdown, incluye el texto alternativo entre corchetes:

```mdx theme={null}
![Descripción de la imagen](/path/to/image.png)
```

Para las imágenes en HTML, usa el atributo `alt`:

```html theme={null}
<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."
/>
```

<div id="add-titles-to-embedded-content">
  ### Añade títulos al contenido incrustado
</div>

Los iframes y las inserciones de video requieren títulos descriptivos:

```html theme={null}
<iframe
  src="https://www.youtube.com/embed/example"
  title="Tutorial: Configuración de tu primer sitio de documentación"
></iframe>
```

<div id="design-for-readability">
  ## Diseña para mejorar la legibilidad
</div>

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.

<div id="ensure-sufficient-color-contrast">
  ### Asegúrate de un contraste de color suficiente
</div>

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.

<CodeGroup>
  ```json Ejemplo de buen contraste theme={null}
  {
    "colors": {
      "primary": "#0066CC",
      "background": {
        "light": "#FFFFFF",
        "dark": "#1A1A1A"
      }
    }
  }
  ```

  ```json Ejemplo de contraste deficiente theme={null}
  {
    "colors": {
      "primary": "#FFCC00",
      "background": {
        "light": "#FFFFFF",
        "dark": "#333333"
      }
    }
  }
  ```
</CodeGroup>

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.

<div id="dont-rely-on-color-alone">
  ### No dependas solo del color
</div>

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".

<div id="use-clear-concise-language">
  ### Usa un lenguaje claro y conciso
</div>

* 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.

<Tip>
  Consulta la [guía de estilo y tono](/es/guides/style-and-tone) para conocer más prácticas recomendadas de redacción.
</Tip>

<div id="make-code-examples-accessible">
  ## Haz que los ejemplos de código sean accesibles
</div>

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.

<div id="specify-the-programming-language">
  ### Especifica el lenguaje de programación
</div>

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:

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

<div id="provide-context-around-code">
  ### Proporciona contexto del código
</div>

Proporciona contexto claro para los bloques de código:

````mdx theme={null}
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.
````

<div id="video-and-multimedia-accessibility">
  ## Accesibilidad de vídeo y multimedia
</div>

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.

<div id="add-captions-to-videos">
  ### Agrega subtítulos a los videos
</div>

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.

<div id="provide-transcripts">
  ### Proporciona transcripciones
</div>

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:

```mdx theme={null}
<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.

<div id="consider-alternatives-to-video-only-content">
  ### Considera alternativas al contenido exclusivamente en video
</div>

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.

<div id="test-your-documentation">
  ## Prueba tu documentación
</div>

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

<div id="check-for-accessibility-issues-with-mint-a11y">
  ### Detecta problemas de accesibilidad con `mint a11y`
</div>

Usa el comando de la CLI `mint a11y` para analizar automáticamente tu documentación en busca de problemas de accesibilidad comunes:

```bash theme={null}
mint a11y
```

El comando verifica:

* Falta de texto alternativo en imágenes y videos.
* Contraste de color insuficiente.

<div id="interpret-the-output">
  #### Interpreta el resultado
</div>

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

```bash theme={null}
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
```

<div id="fix-common-issues">
  #### Soluciona problemas comunes
</div>

**Texto alternativo faltante**: Añade texto alternativo descriptivo a la imagen o video:

```mdx theme={null}
<!-- 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`:

```json theme={null}
{
  "colors": {
    "primary": "#0066CC",  // Cambiado de #FFCC00
    "light": "#3399FF",
    "dark": "#004C99"
  }
}
```

Ejecuta `mint a11y` nuevamente para verificar tus correcciones.

<div id="use-flags-for-targeted-checks">
  #### Usa flags para comprobaciones específicas
</div>

Usa flags para comprobar problemas de accesibilidad específicos:

```bash theme={null}
# 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
```

<div id="basic-keyboard-navigation-test">
  ### Prueba básica de navegación con teclado
</div>

Navega por tu documentación usando solo el teclado:

1. Pulsa <kbd>Tab</kbd> para avanzar por los elementos interactivos.
2. Pulsa <kbd>Shift</kbd> + <kbd>Tab</kbd> para retroceder.
3. Pulsa <kbd>Enter</kbd> para activar enlaces y botones.
4. Comprueba que todos los elementos interactivos sean accesibles y tengan indicadores de foco visibles.

<div id="go-deeper-with-accessibility-testing">
  ### Profundiza en las pruebas de accesibilidad
</div>

Para realizar pruebas más completas:

* **Lectores de pantalla**: Prueba con [NVDA (Windows)](https://www.nvaccess.org/) o [VoiceOver (Mac)](https://www.apple.com/accessibility/voiceover/).
* **Extensiones del navegador**: Instala [axe DevTools](https://www.deque.com/axe/browser-extensions/) o [WAVE](https://wave.webaim.org/extension/) para analizar páginas y detectar problemas.
* **Pautas WCAG**: Revisa las [Pautas de Accesibilidad para el Contenido Web](https://www.w3.org/WAI/WCAG22/quickref/) para conocer los estándares en detalle.

<div id="frequently-asked-questions">
  ## Preguntas frecuentes
</div>

<AccordionGroup>
  <Accordion title="¿Necesito que mi documentación cumpla con WCAG AA o AAA?">
    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.
  </Accordion>

  <Accordion title="¿Cómo pruebo mi documentación con un lector de pantalla?">
    En Mac, usa el VoiceOver integrado (pulsa <kbd>Cmd</kbd> + <kbd>F5</kbd> para activarlo). En Windows, descarga [NVDA](https://www.nvaccess.org/) (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.
  </Accordion>

  <Accordion title="¿Cuál es la diferencia entre el texto alternativo y los pies de imagen?">
    **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).
  </Accordion>

  <Accordion title="¿Puedo usar emojis en documentación accesible?">
    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.
  </Accordion>

  <Accordion title="¿Cómo gestiono la accesibilidad de los ejemplos de código?">
    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.
  </Accordion>

  <Accordion title="¿Qué pasa si no puedo solucionar todos los problemas de accesibilidad de inmediato?">
    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.
  </Accordion>
</AccordionGroup>

<div id="additional-resources">
  ## Recursos adicionales
</div>

Sigue aprendiendo sobre accesibilidad con estos recursos de confianza:

* **[WebAIM](https://webaim.org/)**: Artículos y tutoriales prácticos sobre accesibilidad web
* **[The A11y Project](https://www.a11yproject.com/)**: Recursos de accesibilidad de la comunidad y una lista de comprobación
* **[W3C Web Accessibility Initiative (WAI)](https://www.w3.org/WAI/)**: Normas oficiales de accesibilidad y guías