Реалізація клавіатурної навігації для сайту (WCAG)

На проєкті з інтернет-магазином на React 18 і Next.js 14 користувачі масово скаржилися, що не можуть додати товар у кошик — клавіатурний фокус зникав після вибору розміру. Модальні вікна блокували вихід. Такі баги не лише погіршують UX, а й створюють ризики судових позовів. Клавіатурна навігація — сувора вимога WCAG 2.1 (Success Criterion 2.1.1). Ми, наша команда, допомагаємо впровадити її під ключ: аудит, виправлення, тестування та документація. Оцінимо проєкт за один робочий день, терміни реалізації — від 5 днів. Понад 5 років досвіду у веб-доступності, десятки успішних проєктів. Наш підхід скорочує кількість скарг користувачів на 80% порівняно з сайтами без адаптованої навігації. За даними WebAIM, сайти з реалізованою клавіатурною навігацією мають на 30% вищу задоволеність користувачів.

Чому клавіатурна навігація критична для доступності?

Без неї сайт недоступний користувачам screen reader'ів, людям з тремором або тимчасовими обмеженнями (зламана миша). Google і Яндекс враховують доступність у ранжуванні. Реалізація за WCAG — внесок в UX та SEO одночасно.

Які інструменти допомагають тестувати клавіатурну навігацію?

Для автоматизації використовуємо Cypress з плагіном cypress-axe, а також ручну перевірку. Нижче — таблиця критеріїв WCAG, які перевіряємо.

Типові проблеми та їх рішення

Найчастіше клієнти приходять з такими проблемами: користувачі не можуть заповнити форми, бо фокус зникає після вводу; модальні вікна захоплюють фокус, але не віддають його назад; кастомні дропдауни не відкриваються з клавіатури. Вирішення кожної проблеми потребує детального аудиту та подальшого рефакторингу.

Як ми реалізуємо: один кейс розгорнуто

Нещодавно наш клієнт, інтернет-магазин на React 18 з Next.js 14, зіткнувся з проблемами в модальному вікні кошика. Реалізували фокус-пастку з циклічним перемиканням та поверненням на кнопку після закриття. Заодно додали aria-modal="true" та обробку Escape.

function Modal({ isOpen, onClose, children }) {
  const modalRef = useRef(null);
  useEffect(() => {
    if (!isOpen) return;
    const focusableSelectors = [
      'a[href]',
      'button:not([disabled])',
      'input:not([disabled])',
      'textarea',
      'select',
      '[tabindex]:not([tabindex="-1"])'
    ].join(', ');
    const focusable = modalRef.current?.querySelectorAll(focusableSelectors);
    const first = focusable?.[0];
    const last = focusable?.[focusable.length - 1];
    first?.focus();
    const handleTab = (e) => {
      if (e.key !== 'Tab') return;
      if (e.shiftKey) {
        if (document.activeElement === first) {
          e.preventDefault();
          last?.focus();
        }
      } else {
        if (document.activeElement === last) {
          e.preventDefault();
          first?.focus();
        }
      }
    };
    const handleEsc = (e) => {
      if (e.key === 'Escape') onClose();
    };
    document.addEventListener('keydown', handleTab);
    document.addEventListener('keydown', handleEsc);
    return () => {
      document.removeEventListener('keydown', handleTab);
      document.removeEventListener('keydown', handleEsc);
    };
  }, [isOpen]);
  if (!isOpen) return null;
  return (
    <div role="dialog" aria-modal="true" ref={modalRef}>
      {children}
    </div>
  );
}

Такий підхід гарантує, що користувач не застряне в модалці.

Кастомні компоненти: дропдаун

function DropdownMenu({ trigger, items }) {
  const [open, setOpen] = useState(false);
  const [activeIndex, setActiveIndex] = useState(-1);
  const itemRefs = useRef([]);

  const handleKeyDown = (e) => {
    switch (e.key) {
      case 'ArrowDown':
        e.preventDefault();
        setActiveIndex(i => Math.min(i + 1, items.length - 1));
        break;
      case 'ArrowUp':
        e.preventDefault();
        setActiveIndex(i => Math.max(i - 1, 0));
        break;
      case 'Escape':
        setOpen(false);
        triggerRef.current?.focus();
        break;
      case 'Home':
        setActiveIndex(0);
        break;
      case 'End':
        setActiveIndex(items.length - 1);
        break;
    }
  };

  useEffect(() => {
    if (activeIndex >= 0) {
      itemRefs.current[activeIndex]?.focus();
    }
  }, [activeIndex]);

  return (
    <div>
      <button
        aria-haspopup="listbox"
        aria-expanded={open}
        onClick={() => setOpen(!open)}
      >
        {trigger}
      </button>
      {open && (
        <ul role="listbox" onKeyDown={handleKeyDown}>
          {items.map((item, i) => (
            <li
              key={item.id}
              role="option"
              tabIndex={-1}
              ref={el => itemRefs.current[i] = el}
            >
              {item.label}
            </li>
          ))}
        </ul>
      )}
    </div>
  );
}

Ми використовуємо aria-haspopup на MDN та role="listbox", щоб screen reader коректно оголошував меню.

Базові клавіші навігації

Чек-лист типових помилок

Процес роботи

1. Аналітика — аудит поточної реалізації, складання звіту.
2. Проектування — визначення патернів для кожного компонента.
3. Реалізація — правки стилів, JS, ARIA.
4. Тестування — unit-тести, інтеграційні тести, ручна перевірка.
5. Деплой — здача документації та підтримка.

Що входить у роботу

У результаті ви отримуєте:

• Аудит з детальним звітом за критеріями WCAG 2.1.
• Виправлені компоненти з правильним tabindex та ARIA.
• Документація за реалізованими keyboard pattern.
• Інтеграційні тести на Cypress.
• Інструкція для розробників щодо підтримки доступності.

Терміни реалізації

• Аудит клавіатурної навігації: 1 день.
• Виправлення нативних елементів та стилів фокусу: 1–2 дні.
• Кастомні компоненти (дропдауни, модалки, слайдери): 3–5 днів.
• Тестування та доопрацювання: 1–2 дні.

Вартість розраховується індивідуально, але в середньому аудит обходиться в суму, порівнянну з одним днем роботи розробника. Замовте аудит клавіатурної навігації — отримайте консультацію. Зв'яжіться з нами, щоб обговорити деталі вашого проєкту.