Рекомендации по устранению

Библиотека Axe-core предназначена для автоматизированного выявления проблем доступности веб-страниц. Она предоставляет детальные отчёты о нарушениях стандартов WCAG и позволяет интегрировать проверку доступности прямо в процессы разработки.

Для использования библиотеки необходимо установить пакет через npm:

npm install axe-core

Или подключить его через CDN в браузере:

<script src="https://cdnjs.cloudflare.com/ajax/libs/axe-core/4.8.3/axe.min.js"></script>

После подключения можно инициировать проверку на странице:

import axe from 'axe-core';

axe.run(document, {}, (err, results) => {
  if (err) throw err;
  console.log(results.violations);
});

results.violations содержит массив объектов с подробной информацией о нарушениях доступности: идентификатор правила, описание проблемы, рекомендации по исправлению и элементы DOM, на которых обнаружено нарушение.

Структура отчёта о нарушениях

Каждое нарушение представлено объектом с ключевыми полями:

  • id — уникальный идентификатор правила, например "color-contrast".
  • impact — уровень критичности ("critical", "serious", "moderate", "minor").
  • description — краткое объяснение проблемы.
  • help — рекомендации для исправления.
  • nodes — массив элементов DOM, на которых выявлено нарушение.
  • tags — массив категорий стандарта WCAG, к которым относится проблема.

Пример объекта нарушения:

{
  "id": "color-contrast",
  "impact": "serious",
  "description": "Текст недостаточно контрастен с фоном.",
  "help": "Использовать цвета с более высоким контрастом.",
  "nodes": [
    {
      "html": "<p style=\"color:#ccc;\">Текст</p>",
      "target": ["p"]
    }
  ],
  "tags": ["wcag2aa", "wcag143"]
}

Основные категории проблем и рекомендации по устранению

Контраст текста

Описание: Недостаточный контраст между текстом и фоном затрудняет чтение пользователям с нарушениями зрения. Рекомендации:

  • Использовать контраст не менее 4.5:1 для обычного текста и 3:1 для крупного текста.
  • Проверять комбинации цветов с инструментами вроде Contrast Checker.

Пример исправления:

<p style="color:#000; background-color:#fff;">Текст</p>

Альтернативные описания для изображений

Описание: Отсутствие атрибута alt делает изображение недоступным для скринридеров. Рекомендации:

  • Для декоративных изображений использовать alt="".
  • Для информативных изображений предоставлять краткое и точное описание.
<img src="chart.png" alt="Диаграмма продаж за 2025 год">

Использование заголовков

Описание: Неправильная структура заголовков нарушает иерархию документа и усложняет навигацию. Рекомендации:

  • Заголовки должны следовать последовательной иерархии (<h1> → <h2> → <h3> и т.д.).
  • Избегать пропуска уровней, например <h1> сразу к <h3>.
<h1>Главная тема</h1>
<h2>Подтема 1</h2>
<h3>Детали под темы 1</h3>

Управление фокусом

Описание: Элементы управления должны быть доступными с клавиатуры и иметь визуальный индикатор фокуса. Рекомендации:

  • Использовать tabindex для управляемых элементов.
  • Обеспечивать видимость фокуса с помощью CSS:
button:focus {
  outline: 3px solid #005fcc;
}

Использование ARIA-атрибутов

Описание: ARIA-атрибуты помогают скринридерам корректно интерпретировать элементы интерфейса. Рекомендации:

  • aria-label — для кнопок без текста.
  • role="alert" — для сообщений об ошибках.
  • Избегать избыточного использования ARIA, если стандартные HTML-элементы подходят.
<button aria-label="Закрыть окно">×</button>

Интеграция Axe-core в тестирование

Автоматические тесты с Jest

import { configureAxe, toHaveNoViolations } from 'jest-axe';
expect.extend(toHaveNoViolations);

test('страница должна быть доступной', async () => {
  const axe = configureAxe();
  const results = await axe(document.body);
  expect(results).toHaveNoViolations();
});

Cypress

import 'cypress-axe';

describe('Проверка доступности', () => {
  it('страница без нарушений', () => {
    cy.visit('/');
    cy.injectAxe();
    cy.checkA11y();
  });
});

Локализация и настройка правил

Axe-core позволяет отключать определённые правила или задавать кастомные конфигурации:

axe.run(document, {
  rules: {
    'color-contrast': { enabled: false },
    'image-alt': { enabled: true }
  }
});

Можно создавать собственные правила для специфических требований проекта, задавая селекторы, условия и сообщения для пользователей.

Логирование и визуализация нарушений

Для упрощения исправления можно выводить отчёт в консоль с форматированием:

axe.run(document).then(results => {
  results.violations.forEach(violation => {
    console.group(`${violation.id} (${violation.impact})`);
    console.log(violation.description);
    violation.nodes.forEach(node => console.log(node.html));
    console.groupEnd();
  });
});

Также возможна интеграция с CI/CD для автоматической проверки доступности при каждом билде.

Практические рекомендации по устранению

  1. Начинать с критичных нарушений (impact: critical).
  2. Исправлять ошибки контраста и альтернативного текста в первую очередь, так как они напрямую влияют на базовую доступность.
  3. Поддерживать правильную иерархию заголовков для всех новых страниц.
  4. Тестировать клавиатурную навигацию после добавления интерактивных элементов.
  5. Регулярно обновлять библиотеку Axe-core для использования последних правил WCAG.
Оглавление