Доступность в сложных компонентах: что ревьюить и как чинить

Кастомный компонент выбора выглядит идеально в макете, но пользователь с клавиатурой не может открыть список, а VoiceOver зачитывает его как пустой div. Это самая частая история с доступностью: базовые кнопки и ссылки обычно в порядке, а ломаются именно сложные интерактивные компоненты — комбобоксы, модальные окна, вкладки, таблицы с сортировкой. Ниже — что искать на ревью такого кода и как переписывать, а не какие красивые слова добавить в описание задачи.

Речь про фронтенд на любом фреймворке; примеры на голом HTML и JS, чтобы отделить суть от React или Vue. Ориентир — WAI-ARIA Authoring Practices Guide (APG), актуальная редакция. Это не спецификация ARIA, а набор проверенных паттернов взаимодействия, на который стоит смотреть при любом кастомном компоненте.

Почему div с onClick — это первое замечание

Разработчики любят вешать обработчик на div или span, потому что так проще стилизовать. Проблема не в стилях, а в том, что вместе с семантикой кнопки теряется всё поведение, которое браузер даёт бесплатно.

Нативный <button> получает фокус по Tab, срабатывает по Enter и Space, объявляется скринридером как «кнопка», участвует в отправке формы. У div нет ничего из этого. Чтобы вернуть поведение вручную, придётся дописать tabindex, role, обработку клавиш — и легко что-нибудь забыть.

Правило ревью, экономящее половину замечаний: если элемент кликается — это должен быть button или a. div с onClick без role и клавиатурной обработки — это баг, а не стилистика.

Формулировка замечания в PR, которая работает лучше «поправьте доступность»:

• «Здесь div с обработчиком клика. Замените на <button type="button"> — иначе элемент недоступен с клавиатуры и не объявляется скринридером. Стили кнопки сбрасываются через all: unset или appearance: none».

Что реально ломается в сложных компонентах

Разберём три компонента, которые проваливают доступность чаще всего, и что писать на ревью для каждого.

Кастомный dropdown вместо select

Дизайнеру не понравился нативный <select>, и появился кастомный список на div. Типичные дефекты: список не открывается с клавиатуры, стрелки не двигают выделение, состояние «открыт/закрыт» не передаётся скринридеру, при клике вне списка фокус теряется в никуда.

По APG такой компонент — это паттерн combobox или listbox. Минимальный рабочий набор атрибутов:

<!-- Кнопка, открывающая список -->
<button
  type="button"
  id="city-button"
  aria-haspopup="listbox"
  aria-expanded="false"
  aria-labelledby="city-label city-button">
  Выберите город
</button>

<!-- Сам список -->
<ul
  role="listbox"
  id="city-list"
  aria-labelledby="city-label"
  tabindex="-1">
  <li role="option" id="opt-msk" aria-selected="true">Москва</li>
  <li role="option" id="opt-spb" aria-selected="false">Санкт-Петербург</li>
</ul>

Что проверять на ревью:

• aria-expanded переключается в JS при открытии и закрытии — не остаётся статичным false;
• стрелки вверх/вниз двигают активную опцию, Enter выбирает, Escape закрывает и возвращает фокус на кнопку;
• активная опция помечается через aria-selected, а не только цветом;
• клик вне списка закрывает его и не роняет фокус на <body>.

Отдельный момент: управление фокусом внутри listbox часто делают через aria-activedescendant, а не переносом реального фокуса. Это отдельная развилка — здесь важно, что состояние опции должно быть в разметке, а не только в CSS-классе.

Модальное окно

Модалка — чемпион по утечке фокуса. Пользователь открыл окно, но Tab уводит его на элементы под окном, которые визуально скрыты оверлеем. Скринридер продолжает зачитывать фоновую страницу.

Что должно быть в коде модалки, и что писать в замечаниях, если этого нет:

1. role="dialog" и aria-modal="true" на контейнере окна. Без этого скринридер не понимает, что открылся диалог.
2. Фокус переносится внутрь при открытии — на первый интерактивный элемент или на сам контейнер с tabindex="-1".
3. Ловушка фокуса: Tab с последнего элемента возвращается на первый, а не уходит на фон.
4. Escape закрывает окно.
5. После закрытия фокус возвращается на элемент, который открыл модалку. Иначе пользователь клавиатуры оказывается в начале страницы.
6. aria-labelledby указывает на заголовок окна, чтобы диалог был объявлен по имени.

Если проект использует нативный <dialog> с методом showModal() (поддержка есть во всех актуальных браузерах с 2022 года), браузер сам делает ловушку фокуса, обработку Escape и aria-modal. Замечание на ревью может звучать так: «Здесь руками написанная ловушка фокуса на 60 строк — рассмотрите нативный <dialog>, он закрывает пункты 2–4 из коробки». Проверьте только возврат фокуса — его <dialog> делает не во всех сценариях.

Таблица с сортировкой и фильтрами

Обычная таблица данных доступна почти бесплатно, если использовать <table>, <th> и атрибут scope. Ломается она, когда добавляют интерактив.

Кнопка сортировки в заголовке должна сообщать текущее состояние через aria-sort на ячейке <th>:

<th scope="col" aria-sort="ascending">
  <button type="button">Цена</button>
</th>

Значения aria-sort: ascending, descending, none. При клике по кнопке значение обновляется в JS. Частая ошибка — рисуют стрелку через CSS, а aria-sort не трогают: зрячий видит направление сортировки, пользователь скринридера — нет.

Ещё одно замечание, которое стоит писать почти всегда: если строки таблицы подгружаются или фильтруются без перезагрузки, изменение количества результатов должно объявляться через регион aria-live="polite". Иначе после применения фильтра пользователь не понимает, что список обновился.

Сравнение подходов к клавиатурной навигации

Внутри составных виджетов фокусом управляют двумя способами. Выбор влияет на объём кода и на поведение со скринридером.

Чек-лист для ревью интерактивного компонента

Пройдитесь по компоненту до того, как читать логику. Большинство дефектов видно за минуту:

• каждый кликабельный элемент — button или a, а не div с обработчиком;
• по компоненту можно пройти Tab и вернуться Shift+Tab без застреваний;
• состояние (открыт, выбран, отсортирован) отражено в ARIA-атрибуте, а не только в CSS-классе;
• Escape закрывает то, что открывается; Enter и Space срабатывают там, где ожидаешь;
• у иконочных кнопок есть aria-label — иначе скринридер зачитает пустоту;
• динамические изменения без перезагрузки объявляются через aria-live;
• фокус виден: outline не убран глобальным *:focus { outline: none }.

Как проверять, а не угадывать

Ревью на глаз ловит не всё. Три инструмента, которые стоит гонять до мержа:

• Клавиатура. Отложите мышь и пройдите сценарий целиком. Если куда-то не попасть или фокус исчез — это дефект.
• Скринридер. VoiceOver на macOS (Cmd+F5) или NVDA на Windows (бесплатный). Послушайте, как объявляется компонент.
• Автопроверка. axe DevTools или Lighthouse в разделе Accessibility ловят отсутствие меток и нарушения контраста. Помните: автотесты покрывают порядка трети проблем — управление фокусом и логику клавиш они не проверяют.

Что делать дальше: заведите в проекте линтер eslint-plugin-jsx-a11y для React или аналог для вашего фреймворка — он отловит часть дефектов ещё до ревью. Для регресса добавьте прогон axe-core в CI на ключевых страницах. А самый честный тест — раз в спринт проходить основной сценарий продукта только с клавиатуры и включённым скринридером: это находит то, что не видит ни один линтер.