Screen readers

Screen readers — это специализированные программы, которые преобразуют визуальный интерфейс веб-страницы в аудио или брайлевский вывод, предоставляя доступ к информации людям с нарушениями зрения. При работе с библиотекой MDX необходимо учитывать, как контент, написанный с использованием JSX в Markdown, будет интерпретироваться этими технологиями. Основной принцип — сохранять семантическую структуру документа и предоставлять альтернативные способы восприятия информации.

Семантическая разметка и MDX

MDX позволяет вставлять компоненты React внутрь Markdown. Для корректного взаимодействия со screen readers важно, чтобы компоненты сохраняли или имитировали семантику HTML. Ключевые моменты:

  • Заголовки (h1–h6) Screen readers используют их для построения структуры документа. В MDX заголовки создаются обычными Markdown-синтаксисом:

    ## Основные принципы

    В случае использования кастомных компонентов заголовков нужно передавать атрибут role="heading" и уровень aria-level:

    <CustomHeading role="heading" aria-level={2}>Основные принципы</CustomHeading>

  • Списки (ul, ol) и элементы списка (li) Семантика списков должна сохраняться. В MDX списки стандартно поддерживаются Markdown-нотацией:

    - Пункт 1
- Пункт 2

    Если создаются компоненты-обёртки, важно добавлять role="list" для контейнера и role="listitem" для элементов.

  • Таблицы (table) Таблицы требуют явного указания заголовков колонок с помощью <th> и правильного связывания данных через scope="col" или scope="row":

    <table>
  <thead>
    <tr>
      <th scope="col">Имя</th>
      <th scope="col">Возраст</th>
    </tr>
  </thead>
  <tbody>
    <tr>
      <td>Алексей</td>
      <td>30</td>
    </tr>
  </tbody>
</table>

Атрибуты ARIA

Использование ARIA (Accessible Rich Internet Applications) необходимо для кастомных компонентов, создаваемых через MDX. Основные рекомендации:

  • aria-label — короткое текстовое описание элемента, если текст не отображается визуально.

    <IconButton aria-label="Закрыть окно" />

  • aria-labelledby — связывает элемент с другим элементом, который содержит описание.

    <div id="desc">Описание кнопки</div>
<button aria-labelledby="desc">Кнопка</button>

  • role — явно указывает роль элемента для screen reader. Часто используется для интерактивных кастомных компонентов.

  • aria-hidden — скрывает элементы от скринридеров. Полезно для декоративных иконок:

    <DecorativeIcon aria-hidden="true" />

Навигация и фокус

MDX-компоненты должны корректно поддерживать навигацию клавиатурой:

  • Использование tabIndex для управления порядком фокуса.

  • Все интерактивные элементы (кнопки, ссылки, поля ввода) должны быть доступны через Tab.

  • Всплывающие элементы (модальные окна, всплывающие подсказки) должны управлять фокусом при открытии и закрытии. Примеры с React-компонентами в MDX:

    import { useEffect, useRef } from 'react';

function Modal({ isOpen, onClose, children }) {
  const modalRef = useRef(null);

  useEffect(() => {
    if (isOpen) {
      modalRef.current.focus();
    }
  }, [isOpen]);

  return isOpen ? (
    <div role="dialog" aria-modal="true" ref={modalRef} tabIndex={-1}>
      <button onCl ick={onClose}>Закрыть</button>
      {children}
    </div>
  ) : null;
}

Тестирование доступности

Проверка MDX-контента на доступность для screen readers включает:

  1. Автоматизированные инструменты: axe, Lighthouse, WAVE.
  2. Реальные screen readers: NVDA (Windows), VoiceOver (macOS/iOS), TalkBack (Android).
  3. Тесты на клавиатурную навигацию: все интерактивные элементы должны быть доступны без мыши.

Важно учитывать, что визуально корректно отображающийся компонент не всегда доступен для screen readers. Любое отклонение от семантической разметки или отсутствие ARIA-атрибутов может сделать контент недоступным.

Динамический контент и live regions

Для обновляемого динамического контента необходимо использовать aria-live, чтобы screen readers уведомляли пользователя об изменениях:

<div aria-live="polite">
  {notificationMessage}
</div>
  • aria-live="polite" — уведомления не прерывают текущий поток речи.
  • aria-live="assertive" — уведомления воспроизводятся немедленно, прерывая текущий контент.

Это особенно важно для компонентов уведомлений, статусных сообщений или обновлений данных в MDX-документации.

Итоговые рекомендации

  • Использовать стандартные HTML-теги Markdown там, где возможно.
  • Кастомные компоненты должны сохранять семантику через ARIA.
  • Поддерживать правильный порядок фокуса и клавиатурную навигацию.
  • Проверять доступность на реальных screen readers и автоматических инструментах.
  • Обновления контента должны уведомлять пользователя с помощью aria-live.

Эти принципы обеспечивают корректное взаимодействие MDX-контента с технологией screen readers, делая документацию и приложения доступными для всех пользователей.

Оглавление