Набор от инструменти · За разработчици

Уеб достъпност за разработчици — създадена за инженери, предпочитащи да отстраняват първопричината, а не да добавят overlay

Инженерно ориентираният раздел на сайта. Семантични HTML шаблони, ARIA роли, реално работещи в production, тестове, съобразени с екранните четци, рецепти за интеграция в CI и актуалното състояние на работата с клавиатура за всеки фреймуърк.

Подготвен като начална точка: шаблоните, инструментите, тестовите конфигурации и специфичните за фреймуърка ръководства, от които инженерите реално се нуждаят, за да доставят достъпни функционалности без overlay театър. Свързан с безплатния WCAG 2.2 скенер за еднократен триаж и с ръководството за избор на инструмент за мониторинг за непрекъснато наблюдение.

Четирите инженерни практики, които наистина имат значение

Категорични. Не изчерпателни. Шаблоните, които при спазване елиминират повечето регресии в достъпността преди code review.

Семантичен HTML на първо място, ARIA на второ

Когато нативният HTML може да свърши работата, използвайте го. <button> има вградена работа с клавиатура, фокус, роля и активиране с Enter/Space; <label> свързва контрола с описанието му; <dialog> идва с поведение за задържане на фокуса и деактивиране на останалата страница, което иначе би трябвало да се имплементира ръчно; <details> е disclosure widget без никакъв JavaScript. ARIA е вратата за излизане — полезна, когато няма нативен елемент за задачата, вредна, когато се добавя върху такъв, който вече работи. Справка: критериите за успех на WCAG 2.2 и ръководството за авторски практики на W3C ARIA.

Поддръжката на клавиатура не е отметка в списък

Всеки интерактивен елемент трябва да работи само с клавиатура. Tab и Shift+Tab за придвижване; Enter или Space за активиране; Esc за затваряне на преходна повърхност (модал, popover, меню). Фокусът трябва да е видим — никога outline: none; без замяна. Фокусът трябва да се премества логично — когато се отвори модал, фокусът влиза в него; когато модалът се затвори, фокусът се връща към елемента, отворил го. Тествайте с клавиатура преди да тествате с мишка; мишката скрива грешки, които клавиатурата веднага разкрива.

Достъпни наименования и описания

Не sprinkles от aria-label. Достъпното наименование идва по подразбиране от текстовото съдържание на елемента; aria-labelledby реферира текста на друг възел; aria-label замества всичко с твърдо кодиран низ (и трябва да е последна мярка, тъй като заобикаля превода и склонен е да се разминава с видимия етикет). Достъпното описание е отделно — aria-describedby реферира възела с помощен текст или съобщение за грешка. Проверявайте в дървото за достъпност на DevTools какво реално получава екранният четец — предположенията и реалността често не съвпадат.

Тествайте в реалната си CI среда, не само локално

Локалната проверка с axe е тест за здрав разум. Зелената CI е портал срещу регресии. Свържете eslint-plugin-jsx-a11y към всеки PR; добавете твърдения с axe-core в unit и e2e тестовете; изпълнявайте AT-driver потоци на представителни страници, за да включите реален екранен четец. Прегледът на инструментите за тестване с екранен четец обхваща какво си струва да се автоматизира и какво все още изисква ръчен преглед.

Инструментариумът — 13 подбрани инструмента и библиотеки

Всеки запис съответства на фаза от жизнения цикъл — lint, unit тест, e2e, runtime, мониторинг или ръчен преглед — за да свържете правилния инструмент с правилния портал.

  • Runtime

    axe-core

    Машината за тестване на достъпност, която задвижва по-голямата част от инструментите по-долу. Интегрирайте я в unit тестове, e2e пакети или я свържете с DOM среда по време на разработка за проверки по време на изпълнение.

    github.com/dequelabs/axe-core ↗

  • E2E

    axe DevTools

    Разширение за браузър с интеграции за Playwright, Cypress, Jest и Selenium. Стандартният потребителски интерфейс за разработчици върху axe-core.

    www.deque.com/axe/devtools/ ↗

  • Lint

    eslint-plugin-jsx-a11y

    Правила за статичен анализ (lint) за React JSX. Улавя очевидните пропуски (липсващ alt, невалидни роли, onClick на div) преди code review.

    github.com/jsx-eslint/eslint-plugin-jsx-a11y ↗

  • Runtime

    vue-axe

    Инструмент за проверка на достъпността по време на изпълнение за Vue — показва нарушенията от axe-core в конзолата на браузъра по време на разработка.

    github.com/vue-a11y/vue-axe-next ↗

  • Unit test

    @testing-library/jest-dom

    Матчъри за unit тестове, ориентирани към достъпността. Насърчава намирането на елементи по начина, по който би го направил екранен четец (по роля + достъпно наименование), а не по клас.

    github.com/testing-library/jest-dom ↗

  • E2E

    Playwright + @axe-core/playwright

    Браузърна автоматизация от край до край с първокласна интеграция на axe-core. Изпълнява проверки за достъпност в реални браузъри в CI.

    github.com/dequelabs/axe-core-npm/tree/develop/packages/playwright ↗

  • Unit test

    Storybook a11y addon

    Сканиране с axe-core на ниво компонент в дизайн системата. Улавя нарушенията преди да са попаднали в продуктовия код.

    storybook.js.org/addons/@storybook/addon-a11y ↗

  • Мониторинг

    Pa11y

    CLI скенер, обвиващ axe-core и HTML CodeSniffer. Подходящ примитив за CI портал, който проваля билда при регресии.

    pa11y.org/ ↗

  • Мониторинг

    Lighthouse CI

    Разработен от Google, включва одит на достъпността (axe-core под капака) плюс оценки за производителност и добри практики. Полезен за проследяване на тенденции.

    github.com/GoogleChrome/lighthouse-ci ↗

  • Ръчно

    WebAIM WAVE

    Визуален скенер, който нанася проблемите върху живата страница. Подходящ за дизайнери и автори на съдържание, които не искат да четат JSON доклади.

    wave.webaim.org/ ↗

  • Unit test

    Wallaby + axe-core integration

    Цикъл за обратна връзка в IDE — изпълнява axe-core твърдения до курсора на теста. Ускорява итерацията на разработчика при свързване на нов компонент.

    wallabyjs.com/ ↗

  • E2E

    AT-driver (Playwright + assistive technology)

    Стандарт, инкубиран от W3C, за управление на реални екранни четци от автоматизирани тестове. Границата на автоматизираното тестване за достъпност — най-накрая излизаме отвъд статичните проверки в стил axe.

    github.com/w3c/at-driver ↗

  • Ръчно

    NVDA + JAWS + VoiceOver

    Реалните екранни четци, използвани от потребителите. Никаква автоматизация не замества ръчния преглед с екранен четец за 30–40% от WCAG проблемите, които автоматизацията не може да улови.

    www.nvaccess.org/ ↗

Специфични ръководства по фреймуърк

Проблемите с достъпността, които се проявяват по различен начин в различните екосистеми — и по-задълбоченото им разглеждане за всяка от тях.

React

Ключове в списъци (неправилно наредени списъци объркват екранните четци при пренареждане на елементи). Управление на фокуса при смяна на маршрута (без него фокусът остава върху връзката, задействала навигацията, и новата страница е невидима за потребителите на помощни технологии). Portals и задържане на фокуса — модал, рендериран в document.body, все пак трябва да задържа фокуса вътре в себе си. Несъответствията при хидратация, променящи DOM структурата между SSR и client, могат безшумно да счупят ARIA връзките. Нашият задълбочен преглед на aria-live региони в съвременни фреймуърки обхваща шаблона за обявяване на live региони, който React reconciliation е склонен да нарушава.

Vue / Svelte / Solid

Подобни шаблони; промените в реактивното състояние не задействат актуализации на live региони по подразбиране. Моделът на реактивност на всеки фреймуърк има различна дефиниция на „DOM се е променил“ и екранните четци виждат — или не виждат — резултиращата актуализация на възела по фино различни начини. v-if срещу v-show на Vue, реактивните декларации на Svelte и фино зърнестата реактивност на Solid произвеждат различни актуализации на дървото за достъпност за привидно еднакъв код.

Нативна мобилна разработка (iOS + Android)

Напълно различна повърхност на API. iOS излага UIAccessibility (и .accessibilityLabel() / .accessibilityHint() на SwiftUI) за VoiceOver; Android излага AccessibilityNodeInfo за TalkBack. ARIA в уеб стил не се транслира. Материалът за нативните мобилни API за достъпност съпоставя уеб концепциите с техните нативни еквиваленти, за да спре инженерите, обучени в уеб среда, да отгатват.

Библиотеки с компоненти

Headless библиотеките (Radix UI, Headless UI, React Aria) поемат трудните части — управление на фокуса, работа с клавиатура, свързване на ARIA — и оставят визуалния дизайн изцяло на вас. Пълнофункционалните библиотеки (Material UI, Chakra, Ant) идват с мнения за визуалната страна, но качеството им по отношение на достъпността варира значително, и „достъпен по подразбиране“ рядко означава „тестван срещу реални екранни четци“. Нашият преглед на достъпни библиотеки с компоненти оценява основните варианти спрямо реално тестване с помощни технологии.

Контролен списък при PR преглед за достъпност

Отпечатайте го, поставете го в PR шаблона или го автоматизирайте в бот. Минимумът, на който всеки рецензент трябва да обърне внимание.

  • Интерактивните елементи работят само с клавиатура (Tab + Enter + Space + Esc).
  • Индикаторът за фокус е видим на всеки интерактивен елемент.
  • Полетата на формуляра имат асоцииран <label>.
  • Съобщенията за грешка са асоциирани с полетата си (aria-describedby или съседен текст).
  • Промените в динамичното съдържание се обявяват чрез aria-live при необходимост.
  • Модалните диалози задържат фокуса и го връщат към отварящия елемент при затваряне.
  • Изображенията имат смислен алтернативен текст; декоративните изображения носят alt="".
  • Списъците използват <ul> / <ol> / <dl> — не <div> салата.
  • Йерархията на заглавията е логична (без пропуснати нива).
  • Lint + axe тестовете преминават в CI преди сливане.

Чести инженерни антишаблони

Шаблоните, преминаващи code review и счупващи се в production. Улавяйте ги по-рано.

  • „Overlay widget“ — JavaScript на трета страна, претендиращ, че добавя достъпност към съществуващ сайт. Не го прави, чести нарушава слоя на помощните технологии и сам по себе си е генерирал вълна от съдебни искове. Контекст: overlay доставчиците.
  • role="button" върху <div> — добавя обявяването на ролята без поведението при работа с клавиатура (Enter, Space) или участие в таб реда. Използвайте <button>.
  • aria-hidden="true" върху фокусируеми елементи — създава капан за фокуса, при който потребителите с клавиатура могат да попаднат на елемент, за който екранният четец е инструктиран да игнорира. Или премахнете елемента от таб реда с tabindex="-1", или премахнете aria-hidden.
  • Персонализирано падащо меню без управление с клавиатура — combobox на база <div>, отварящ се при клик, но игнориращ клавишите със стрелки, Home/End, въвеждане на знак и Esc. Прегледът на достъпни библиотеки с компоненти обхваща библиотеките, които се справят с това правилно от кутията.
  • Toast известия, които не се обявяват — преходна повърхност, рендерирана без role="status" (polite) или role="alert" (assertive). Зрящите потребители я виждат; потребителите на екранни четци — не.
  • Генериран DOM, счупващ дървото за достъпност — тежки обвивки около input (персонализиран select, изграден от дванадесет вложени <div>) често скриват реалния контрол от помощните технологии. Тествайте какво вижда помощната технология, а не само какво вижда потребителят.

Набор от инструменти + pipeline за мониторинг

Повечето екипи искат три неща в последователност: еднократно сканиране при триаж, когато нещо изглежда счупено; инженерна справка, когато искат да разберат основните шаблони; и непрекъснат слой за мониторинг, след като достъпността е влязла в production пътната карта. Нашият безплатен WCAG 2.2 скенер покрива първото — поставете публичен URL, получете доклад, задвижван от axe, в нов таб. Инженерното съдържание на редакционния отдел покрива второто — включително анализи на дълга по достъпността като технически дълг и на инциденти с достъпността като SRE постмортем за екипи, управляващи достъпността в мащаб.

За непрекъснатия слой, ръководството за избор на инструмент за мониторинг е най-категоричният материал в сайта. Оценява axe Monitor, Siteimprove, Level Access и Qualibooth — последният от които интегрира мониторинга с предаване към ръчен одит, липсващото звено в повечето стекове само с автоматизация — по широчина на покритие, процент на фалшиви положителни резултати и колко чисто данните се вграждат в инженерните работни процеси. Целта на мониторинга е да се гарантира, че корекциите, доставени днес, няма да регресират следващия спринт.

Често задавани инженерни въпроси

Въпросите, появяващи се на всеки стартов разговор за достъпност. Огледалени в структурираните данни FAQPage.

По-добро ли е aria-label от видимите текстови етикети?
Не. Видимият текст почти винаги е по-добър — той е полезен за зрящи потребители, зрящи потребители с когнитивни увреждания, потребители на гласово управление (казват това, което виждат) и инструменти за превод. Прибягвайте до aria-label само когато няма видим текст за асоцииране (бутони само с икона) или когато видимият текст наистина не е желаното достъпно наименование.
Трябва ли да използвам ARIA роли за всичко?
Не. Първото правило на ARIA е "do not use ARIA". Нативните HTML елементи идват с правилната роля, правилното поведение при работа с клавиатура и правилната семантика в дървото за достъпност. Използвайте ARIA само когато (и единствено когато) няма нативен елемент, подходящ за целта — например таб списък, дърво или персонализиран диалог, при който не можете да използвате <dialog>.
Как да тествам достъпността в CI?
Три слоя, наредени по цена. (1) Lint: eslint-plugin-jsx-a11y при всеки PR. (2) Unit тестове: @testing-library/jest-dom плюс jest-axe (или @axe-core/react) за всеки компонент. (3) End-to-end: @axe-core/playwright на представителни потребителски пътища. Добавете портал Pa11y или Lighthouse CI в staging среда, за да хванете дрейфа, пропуснат от по-ниските слоеве.
axe-core и Lighthouse едно и също ли са?
Lighthouse използва axe-core под капака за своя одит на достъпността, но изпълнява подбрано подмножество от правилата и ги представя в рамките на по-широк доклад за производителност / SEO / добри практики. axe-core е самият двигател — когато искате пълния набор от правила или искате да го разширите, използвате axe-core директно. За повечето екипи: използвайте Lighthouse за проследяване на тенденции, axe-core за реалния портал.
Каква е минималната конфигурация за тестване на достъпност в React проект?
Добавете eslint-plugin-jsx-a11y към съществуващата конфигурация на ESLint (предоставя се по подразбиране с create-react-app и Next.js). Добавете @testing-library/jest-dom и jest-axe към настройката за unit тестове и извиквайте expect(await axe(container)).toHaveNoViolations() в поне един тест за всеки компонент. Това е минимумът — улавя около 40% от реалните WCAG проблеми срещу няколко часа настройка.
Необходимо ли е тестване с реални екранни четци?
Да, за всяка функционалност на продукта, която потребител на помощна технология реално ще използва. Автоматизираните инструменти улавят структурните грешки (липсващи етикети, контраст, несъответствия в ролите), но не и функционалните (фокус, прескачащ към долния колонтитул, live региони, които не обявяват, „достъпен“ модал, задържащ фокуса в грешното поддърво). Планирайте поне един ръчен преглед на всяко основно издание с NVDA на Windows и VoiceOver на macOS / iOS.

Следващи стъпки

Направете бърза проверка с безплатния WCAG 2.2 скенер, ако извършвате триаж на конкретна страница. Прочетете прегледа на инструментите за тестване с екранен четец преди да свържете AT-driver в CI. И ако достъпността преминава от „еднократен одит“ към „постоянна production грижа“, ръководството за избор на инструмент за мониторинг е най-конкретният материал в сайта за избор на доставчик.