, ,

, , native и т.д. Браузер бесплатно даёт focus, keyboard activation (Enter/Space/Arrow), screen reader role announcements, form integration, IME support, контекстное меню. Путь B — div+ARIA:

с ручной реализацией всех этих behaviors. Он выглядит привлекательно, потому что: (а) дизайнеры просят "чтобы выглядело иначе" и кажется, что

, native /

, <details><summary> для disclosure). ARIA добавляем только когда: (а) нет HTML-аналога (combobox, tablist, tree, treegrid, dialog, alertdialog), (б) augmenting существующий semantic — aria-expanded на <button>, aria-current="page" на <a>, aria-describedby для error message, aria-label когда visible text не подходит. Для composite widgets обязательно следуем W3C ARIA Authoring Practices Guide (APG) полностью — все states, properties, keyboard interactions, focus management. Не используем ARIA-only когда semantic exists: NEVER role="button" на <div>, NEVER role="link" на <span>, NEVER role="navigation" на <div> когда есть <nav>. Anti-pattern detection: axe-core в CI с правилами "interactive-supports-focus", "aria-required-children", "aria-allowed-attr" — ломаем PR при нарушениях. Команда читает первое правило ARIA вслух перед каждым design review: "No ARIA is better than bad ARIA." Для React/Next выбираем headless libraries которые правильно реализуют APG (react-aria от Adobe, Radix UI primitives, Headless UI) вместо ручной разработки composite widgets — там 100+ keyboard edge cases которые мы сами не закроем. Для дизайнеров: <button> стилизуется полностью, дайте reset CSS и пользуйтесь — никогда не одобряем PR с div+onClick для кликабельного UI.',
      date: '2026-05-14',
    },
    {
      id: 'ADR-002',
      title: 'Automated audit (axe/Pa11y/Lighthouse) vs manual + real users — где граница',
      status: 'accepted',
      context: 'У команды есть желание поставить axe-core в CI, написать "100/100 Lighthouse a11y" в README и считать что accessibility закрыт. Реальность от Deque (создатели axe): автоматические тулы ловят 30-40% WCAG violations на типичной странице. Что они умеют — color contrast (если цвета в CSS, не в SVG/canvas), missing alt, missing label, missing lang, ARIA misuse (role-required-children, invalid attr), heading skip levels, duplicate ID, tabindex>0. Что они НЕ умеют — proverить что alt text осмысленный (alt="image" проходит), что keyboard reachable element actually does what user expects, что focus management при route change в SPA корректное, что live region announces в нужный момент с нужным wording, что custom dropdown/datepicker реально usable голосом+screen reader, что error message связан с input (могут проверить aria-describedby существует, но не что текст полезен), что цветовая семантика не единственный signal, что motion respect prefers-reduced-motion на complex animation, что touch targets >= 24x24px (WCAG 2.2), что reading order соответствует visual order. Manual testing с настоящим NVDA/VoiceOver ловит ещё 30-40% — обычно UX issues: announcement порядок странный, focus прыгает, modal не trap focus правильно, reading flow ломается на mobile. Но даже manual testing техническим инженером пропускает реальные user struggles. Real disabled users (через accessibility consultancy типа Fable, Knowbility, Applause) ловят оставшиеся 20-30% — где naming не соответствует mental model, где flow требует слишком много actions, где fatigue после 50 Tab presses, где "доступно но мучительно". Цена растёт: axe в CI — 0$, manual NVDA testing — час QA на feature, real user testing — $500-2000/session. ROI обратно пропорционален стадии: автоматика на этапе разработки дешевле всего, real user testing — дороже но ловит то что иначе летит в production и даёт PR/lawsuit risk. Dominos v. Robles (2019, Supreme Court отказался слушать) — пицца-сеть проиграла blind user из-за inaccessible site/app, обязали переделать + заплатить. Target settled в 2008 за $6M по аналогичному иску. Beyoncé.com sued в 2019. С 2025 EAA в EU — обязательно для e-commerce/banking/transport.',
      decision: 'Three-tier подход. Tier 1 (CI/PR gate, 0$) — axe-core в jest/playwright, lighthouse-ci с порогом 95+, eslint-plugin-jsx-a11y в lint, Storybook a11y addon на каждый компонент. Любой violation ломает PR. Это ловит ~35% и предотвращает регрессию. Tier 2 (per-feature, 1-2 часа QA, до релиза) — manual checklist: Tab through всю страницу, screen reader walkthrough (NVDA на Windows VM или VoiceOver на Mac) основных user journeys, zoom 200% test, keyboard-only flow, prefers-reduced-motion, color contrast в edge cases (overlays, hover states, focus rings), touch targets на mobile breakpoint. Документируем в PR template. Это ловит ещё ~35%. Tier 3 (quarterly + перед major launch, $$$) — accessibility consultancy с real disabled users, минимум 5 participants (sighted-keyboard, screen reader, low vision, cognitive, motor). Findings в backlog с severity, исправляем blockers до релиза. Бюджет $5-10K на quarter. Дополнительно — accessibility statement на сайте с контактом для feedback (требует EAA), VPAT/ACR документ для enterprise sales (US gov + corp clients требуют). Не считаем "Lighthouse 100" за победу — Lighthouse чекает ~10 правил из 50+ axe rules и ничего не знает про UX. Не делаем "a11y sprint раз в год" — debt накапливается экспоненциально, дешевле shift-left в каждый PR.',
      date: '2026-05-14',
    },
  ],
});

stack
  .addProcess({ id: 'semantic', label: 'Semantic HTML (button, nav, main, label)', icon: 'code', state: 'running' })
  .addProcess({ id: 'aria', label: 'ARIA augmentation (roles, states, live)', icon: 'layers', state: 'running' })
  .addProcess({ id: 'keyboard', label: 'Keyboard handlers (Tab, Enter, Esc, focus trap)', icon: 'terminal', state: 'running' })
  .addProcess({ id: 'css', label: 'CSS (focus-visible, contrast, prefers-reduced-motion)', icon: 'monitor', state: 'running' })
  .addProcess({ id: 'media', label: 'Media (alt text, captions, transcripts)', icon: 'mail', state: 'running' })
  .autoResize();

// === Assistive tech — what users actually run ===
const at = topology.createGroup('at', {
  label: 'Assistive technology layer',
  x: 60,
  y: 480,
});

at
  .addProcess({ id: 'nvda', label: 'NVDA (Windows, free)', icon: 'cpu', state: 'running' })
  .addProcess({ id: 'voiceover', label: 'VoiceOver (macOS/iOS, built-in)', icon: 'cpu', state: 'running' })
  .addProcess({ id: 'jaws', label: 'JAWS (Windows, enterprise $$$)', icon: 'cpu', state: 'running' })
  .addProcess({ id: 'browser-zoom', label: 'Browser zoom 200% / OS magnifier', icon: 'search', state: 'running' })
  .autoResize();

// === Audit tooling pipeline ===
const audit = topology.createGroup('audit', {
  label: 'Audit pipeline (catch issues before users do)',
  x: 700,
  y: 480,
});

audit
  .addProcess({ id: 'axe', label: 'axe-core (Jest/Playwright)', icon: 'shield', state: 'running' })
  .addProcess({ id: 'pa11y', label: 'Pa11y (CLI, CI integration)', icon: 'shield', state: 'running' })
  .addProcess({ id: 'lighthouse', label: 'Lighthouse a11y (Chrome/CI)', icon: 'chart', state: 'running' })
  .addProcess({ id: 'manual', label: 'Manual NVDA/VoiceOver test', icon: 'user', state: 'running' })
  .addProcess({ id: 'real-users', label: 'Real disabled users (Fable, Applause)', icon: 'user', state: 'running' })
  .autoResize();

// === Compliance / legal layer ===
const compliance = topology.createGroup('compliance', {
  label: 'Compliance (WCAG 2.2 AA + legal)',
  x: 380,
  y: 880,
});

compliance
  .addProcess({ id: 'wcag', label: 'WCAG 2.2 AA (POUR principles)', icon: 'cloud', state: 'running' })
  .addProcess({ id: 'ada', label: 'ADA (US) — Dominos v. Robles 2019', icon: 'alert', state: 'running' })
  .addProcess({ id: 'eaa', label: 'EAA (EU 2025) — e-commerce mandatory', icon: 'alert', state: 'running' })
  .autoResize();

// === Edges: information flow from UI to user ===
topology.connect('semantic', 'aria', { type: 'tcp', label: 'augment' });
topology.connect('semantic', 'keyboard', { type: 'tcp', label: 'native handlers' });
topology.connect('semantic', 'css', { type: 'tcp', label: 'style hooks' });
topology.connect('semantic', 'media', { type: 'tcp', label: 'embed' });

topology.connect('aria', 'nvda', { type: 'tcp', label: 'announce' });
topology.connect('aria', 'voiceover', { type: 'tcp', label: 'announce' });
topology.connect('aria', 'jaws', { type: 'tcp', label: 'announce' });
topology.connect('css', 'browser-zoom', { type: 'tcp', label: 'reflow' });

topology.connect('sighted', 'css', { type: 'tcp', label: 'visual UI' });
topology.connect('sr-user', 'nvda', { type: 'tcp', label: 'listen' });
topology.connect('sr-user', 'voiceover', { type: 'tcp', label: 'listen' });
topology.connect('kbd-user', 'keyboard', { type: 'tcp', label: 'Tab/Enter' });
topology.connect('low-vision', 'browser-zoom', { type: 'tcp', label: 'magnify' });
topology.connect('cognitive', 'css', { type: 'tcp', label: 'reduced motion' });

topology.connect('axe', 'semantic', { type: 'tcp', label: 'scan DOM' });
topology.connect('pa11y', 'semantic', { type: 'tcp', label: 'scan DOM' });
topology.connect('lighthouse', 'semantic', { type: 'tcp', label: 'scan DOM' });
topology.connect('manual', 'nvda', { type: 'tcp', label: 'test' });
topology.connect('real-users', 'manual', { type: 'tcp', label: 'feedback' });

topology.connect('axe', 'wcag', { type: 'tcp', label: 'enforce' });
topology.connect('manual', 'wcag', { type: 'tcp', label: 'verify' });
topology.connect('wcag', 'ada', { type: 'tcp', label: 'compliance' });
topology.connect('wcag', 'eaa', { type: 'tcp', label: 'compliance' });

await topology.apply();

const flow = new FlowBuilder();

// === SCENARIO 1: <button> vs <div onClick> — the foundational mistake ===
flow
  .scenario('button-vs-div', '[1] <button> vs <div onClick>', 'Почему semantic HTML побеждает div+onClick для всех ability profiles')
  .from('sighted')
  .showMessage('[CASE] Designer хочет custom-styled clickable. Dev пишет <div className="btn" onClick={save}>Save</div>. Looks identical для sighted user.')
  .to('css')
  .from('css')
  .to('semantic')
  .showMessage('[OK для mouse user] Click срабатывает, save выполняется. Ship it!')
  .from('kbd-user')
  .to('keyboard')
  .showError('[FAIL] Tab не доходит до <div> — нет tabindex. Keyboard user blocked, не может submit form.')
  .from('keyboard')
  .to('semantic')
  .showMessage('[FIX attempt] Добавляем tabindex="0". Tab теперь работает.')
  .from('kbd-user')
  .to('keyboard')
  .showError('[FAIL #2] User жмёт Enter — ничего. Жмёт Space — page scrolls. <div> не активируется keyboard.')
  .from('keyboard')
  .to('semantic')
  .showMessage('[FIX #2] onKeyDown handler: if (e.key === "Enter" || e.key === " ") { e.preventDefault(); save(); }. 8 lines per button.')
  .from('sr-user')
  .to('nvda')
  .showError('[FAIL #3] NVDA reads "Save" — без role. User не знает что это interactive. Skips.')
  .from('nvda')
  .to('aria')
  .showMessage('[FIX #3] role="button" + aria-pressed (если toggle). Ещё больше attributes.')
  .from('axe')
  .to('semantic')
  .showError('[axe] Violation: "interactive-supports-focus" + "no keyboard handler" detected. Score drops.')
  .from('semantic')
  .showMessage('[REVELATION] Native <button>Save</button> делает ВСЕ это бесплатно: focus, Enter+Space, role=button, form submit, focus-visible. Используй native!')
  .from('sighted')
  .to('css')
  .showMessage('[STYLING] <button> полностью стилизуется: `button { all: unset; cursor: pointer; ... }`. Никакого визуального отличия от div.');

// === SCENARIO 2: Skip link saves screen reader user from re-listening to nav ===
flow
  .scenario('skip-link', '[2] Skip link для keyboard / SR users', 'Первая ссылка на странице — bypass для повторяющейся navigation')
  .from('sr-user')
  .to('nvda')
  .showMessage('[CONTEXT] Сайт: header с logo, mega-menu (40 links), search, user dropdown, потом main content. Каждая страница.')
  .from('nvda')
  .to('semantic')
  .showError('[PAIN] На каждой page reload screen reader читает 40 nav links подряд. Чтобы дойти до main content — 60+ Tab presses или прослушивание 30 секунд header.')
  .from('semantic')
  .showMessage('[FIX] Первый focusable element: <a href="#main" class="skip-link">Skip to main content</a>. Visually hidden until focused.')
  .from('kbd-user')
  .to('keyboard')
  .showMessage('[KBD] User жмёт Tab один раз — skip link появляется (focus-visible). Enter — focus прыгает на <main>.')
  .from('semantic')
  .to('css')
  .showMessage('[CSS] .skip-link { position: absolute; top: -40px; } .skip-link:focus { top: 0; } — invisible до focus, visible когда нужно.')
  .from('sr-user')
  .to('nvda')
  .showMessage('[OK] NVDA: "Skip to main content, link". Enter -> "Main, landmark". 2 actions вместо 60.')
  .from('semantic')
  .to('aria')
  .showMessage('[BONUS] Тоже работает: landmarks navigation (NVDA: D key для main/nav/footer). Требует <main>, <nav>, <footer> — semantic HTML again.')
  .from('axe')
  .to('semantic')
  .showMessage('[AUDIT] axe не проверяет skip link существует (UX rule, не WCAG SC). Но WCAG 2.4.1 Bypass Blocks требует механизм — skip link самый common.')
  .from('low-vision')
  .to('browser-zoom')
  .showMessage('[BONUS 2] Zoom 200% user тоже выигрывает — sticky header съедает 50% viewport, skip link даёт быстрый путь.');

// === SCENARIO 3: ARIA live region для dynamic SPA updates ===
flow
  .scenario('live-region', '[3] aria-live для dynamic updates', 'SPA меняет DOM без page reload — screen reader не знает, нужен live region')
  .from('sighted')
  .to('css')
  .showMessage('[CASE] User adds item to cart. UI: toast notification "Added to cart" появляется bottom-right на 3 сек.')
  .from('css')
  .showMessage('[OK для sighted] Visual feedback мгновенный. User знает что click сработал.')
  .from('sr-user')
  .to('nvda')
  .showError('[FAIL] DOM меняется в углу. Screen reader focus всё ещё на "Add" button. NVDA молчит. User не знает что произошло — нажмёт ещё раз? 3 раза?')
  .from('semantic')
  .to('aria')
  .showMessage('[FIX] Toast div: <div role="status" aria-live="polite" aria-atomic="true">Item added to cart</div>. polite — не прерывает текущую речь.')
  .from('aria')
  .to('nvda')
  .showMessage('[OK] NVDA: после current speech ends -> "Item added to cart". User знает: success, можно двигаться дальше.')
  .from('aria')
  .to('voiceover')
  .showMessage('[CROSS-AT] VoiceOver работает идентично. JAWS — есть quirk с initial render, fix: render контейнер сразу, обновляй textContent.')
  .from('css')
  .showError('[CASE 2: critical] Session expired modal. polite не подойдёт — user может потерять unsaved data.')
  .from('semantic')
  .to('aria')
  .showMessage('[FIX 2] role="alert" или aria-live="assertive". Прерывает текущую речь немедленно.')
  .from('aria')
  .to('nvda')
  .showMessage('[OK 2] NVDA немедленно: "Session expired, please log in". User успевает сохранить.')
  .from('axe')
  .to('aria')
  .showError('[ANTI-PATTERN] Множественные live regions с assertive = звуковой ад. Use polite by default. assertive только для emergencies (errors, timeouts, security).')
  .from('aria')
  .showMessage('[NUANCE] aria-live добавляется ДО first announcement, не после. Иначе screen reader не подпишется на изменения. React: render container always, toggle textContent.');

// === SCENARIO 4: Audit pipeline — what catches what ===
flow
  .scenario('audit-pipeline', '[4] Audit: automated -> manual -> real users', 'Three-tier стратегия: где каждый тул эффективен и где провал')
  .from('axe')
  .to('semantic')
  .showMessage('[TIER 1: CI] PR opens. axe-core scans. Catches: missing alt (5), insufficient contrast (3.2:1, need 4.5:1), heading skip h1->h3, missing label на input.')
  .from('axe')
  .showMessage('[FIXED] Dev fixes 4 violations. axe re-runs -> 0 violations. PR merges.')
  .from('lighthouse')
  .to('semantic')
  .showMessage('[CI #2] Lighthouse a11y: 100/100. Team celebrates. README: "WCAG AA compliant".')
  .from('manual')
  .to('nvda')
  .showError('[TIER 2: NVDA] QA opens NVDA. Custom dropdown: arrow keys не работают. axe не поймал — keyboard interaction patterns не проверяются автоматом.')
  .from('manual')
  .showError('[NVDA #2] Modal opens — focus не переходит на heading. Esc не закрывает. Tab убегает на background page.')
  .from('manual')
  .to('keyboard')
  .showMessage('[FIX] Implement focus trap (react-focus-lock), focus first heading on open, Esc closes + restore focus to opener.')
  .from('manual')
  .to('voiceover')
  .showError('[CROSS-AT] VoiceOver на Mac: read order карточки странный — price читается ДО title. Visual order: title первый. CSS order/flex с reverse сломал DOM order.')
  .from('manual')
  .to('semantic')
  .showMessage('[FIX] DOM order = reading order. CSS только для visual rearrange (flex `order:` ОК для visual, плохо для AT).')
  .from('real-users')
  .to('manual')
  .showError('[TIER 3: real users] 5 disabled testers, 1 hour each. Findings axe и QA пропустили: cart flow требует 23 Tab presses, fatigue real. Form errors — текст полезный, но связь с input через aria-describedby не announced на JAWS 2024 (bug). User не знает где ошибка.')
  .from('real-users')
  .to('manual')
  .showMessage('[FINDING #2] Color picker: contrast OK, keyboard OK, но cognitive load — 5 controls без grouping. Fix: <fieldset><legend>Choose color</legend>.')
  .from('manual')
  .to('wcag')
  .showMessage('[OUTCOME] axe ловит ~35%, manual + ~35%, real users + ~30%. Все три tier нужны. Бюджет: $0 + 2hr/feature + $5K/quarter.')
  .from('wcag')
  .to('ada')
  .showMessage('[LEGAL] Dominos v. Robles (2019): blind user не мог заказать pizza. SCOTUS отказался слушать appeal -> ADA covers websites/apps. Settlement + переделка.')
  .from('wcag')
  .to('eaa')
  .showError('[EAA 2025] EU Accessibility Act: e-commerce, banking, transport, e-books — обязательно WCAG 2.1 AA. Penalty до 4% revenue. Не просто "nice to have".');

return flow;
</article></body></html>