2nd/10_Wiki/Topic_Programming/Coding/Frontend_A11y_Modern.md

id, title, category, status, source_trust_level, verification_status, created_at, updated_at, tags, tech_stack, applied_in, aliases

id	title	category	status	source_trust_level	verification_status	created_at	updated_at	tags	tech_stack	applied_in	aliases
frontend-a11y-modern	Modern Accessibility — ARIA / focus / keyboard	Coding	draft	B	conceptual	2026-05-09	2026-05-09	frontend accessibility vibe-coding	language applicable_to TS / React Frontend		a11y accessibility ARIA focus management keyboard nav screen reader WCAG

Modern Accessibility (a11y)

사용자 의 ~15% 가 disability. WCAG 2.2, ARIA, focus, keyboard, screen reader.

📖 핵심 개념

• Native HTML 가 best (button, anchor, label, ...).
• ARIA 가 last resort.
• Keyboard 가 first-class.
• Screen reader test.

💻 코드 패턴

Semantic HTML

<!-- ❌ -->
<div onclick='submit()'>Submit</div>

<!-- ✅ -->
<button type='submit'>Submit</button>

→ 90% 의 a11y 가 native.

Heading hierarchy

<h1>Page title</h1>
  <h2>Section 1</h2>
    <h3>Subsection</h3>
  <h2>Section 2</h2>

→ Skip level 안 됨.

Label

<label for='email'>Email</label>
<input id='email' type='email' />

<!-- 또는 -->
<label>
  Email
  <input type='email' />
</label>

→ Screen reader 가 명확.

ARIA (last resort)

<div role='button' tabindex='0' onclick='...' onkeydown='...'>
  Custom button
</div>

→ Native 가 안 가능 시 만.

ARIA attributes

<button aria-label='Close' aria-pressed='false'>×</button>

<input aria-describedby='hint' />
<span id='hint'>At least 8 characters</span>

<div aria-live='polite'>Status update</div>
<div aria-live='assertive'>Error: ...</div>

Focus management

// Trap (modal)
function trapFocus(container: HTMLElement) {
  const focusable = container.querySelectorAll('a[href], button:not([disabled]), input, select, textarea, [tabindex]:not([tabindex="-1"])');
  const first = focusable[0] as HTMLElement;
  const last = focusable[focusable.length - 1] as HTMLElement;
  
  container.addEventListener('keydown', (e) => {
    if (e.key !== 'Tab') return;
    if (e.shiftKey && document.activeElement === first) {
      e.preventDefault();
      last.focus();
    } else if (!e.shiftKey && document.activeElement === last) {
      e.preventDefault();
      first.focus();
    }
  });
  
  first.focus();
}

→ Modal / dialog 안 만 tab.

Restore focus

function openModal() {
  const previousFocus = document.activeElement as HTMLElement;
  // ... show modal
  
  // On close
  previousFocus.focus();
}

Skip link

<a href='#main' class='skip-link'>Skip to content</a>

<style>
.skip-link {
  position: absolute;
  top: -40px;
  left: 0;
}
.skip-link:focus { top: 0; }
</style>

→ Screen reader / keyboard user 가 navigation skip.

Keyboard navigation

Tab: 다음 focusable.
Shift+Tab: 옛.
Enter / Space: button.
Escape: modal close.
Arrow: list / menu / radio.

function Menu({ items }: { items: string[] }) {
  const [activeIdx, setActiveIdx] = useState(0);
  
  const onKeyDown = (e: KeyboardEvent) => {
    if (e.key === 'ArrowDown') setActiveIdx(i => Math.min(items.length - 1, i + 1));
    if (e.key === 'ArrowUp') setActiveIdx(i => Math.max(0, i - 1));
    if (e.key === 'Enter') select(items[activeIdx]);
  };
  
  // ...
}

Focus visible

/* :focus 는 mouse 도 */
button:focus { outline: 2px solid blue; }

/* :focus-visible = keyboard 만 */
button:focus-visible { outline: 2px solid blue; }
button:focus:not(:focus-visible) { outline: none; }

Color contrast

WCAG AA: 4.5:1 (normal text).
WCAG AAA: 7:1.

→ Tools: WebAIM contrast checker.
Tailwind 도 contrast warning.

Reduced motion

@media (prefers-reduced-motion: reduce) {
  *, *::before, *::after {
    animation-duration: 0.01ms !important;
    animation-iteration-count: 1 !important;
    transition-duration: 0.01ms !important;
  }
}

→ Vestibular disorder.

Reduced motion (JS)

const prefersReduced = window.matchMedia('(prefers-reduced-motion: reduce)').matches;

Screen reader test

macOS: VoiceOver (Cmd + F5).
Windows: NVDA (free) / JAWS.
iOS: VoiceOver.
Android: TalkBack.

→ Manual test 가 진짜.

Auto test (axe-core)

import { axe } from 'jest-axe';

test('accessible', async () => {
  const { container } = render(<MyComponent />);
  expect(await axe(container)).toHaveNoViolations();
});

→ Automated audit.

Lighthouse / Pa11y

lighthouse https://example.com --only-categories=accessibility
pa11y https://example.com

→ CI gate.

React (a11y)

// React 의 accessible component
<button aria-label='Close' onClick={close}>
  <X />
</button>

// Form
<form>
  <label htmlFor='email'>Email</label>
  <input id='email' type='email' aria-required='true' />
  {error && <p id='email-error' role='alert'>{error}</p>}
</form>

Radix / shadcn (a11y baked in)

import * as Dialog from '@radix-ui/react-dialog';

<Dialog.Root>
  <Dialog.Trigger>Open</Dialog.Trigger>
  <Dialog.Content>...</Dialog.Content>
</Dialog.Root>

→ Focus trap, Escape, ARIA 자동.

→ Frontend_shadcn_Radix_Patterns.

Image alt

<img src='hero.jpg' alt='Person typing on laptop' />

<!-- Decorative -->
<img src='divider.svg' alt='' role='presentation' />

Form error

<label for='email'>Email</label>
<input id='email' aria-invalid='true' aria-describedby='email-err' />
<span id='email-err' role='alert'>Required</span>

Live region

<div role='status' aria-live='polite'>
  Item added to cart
</div>

<div role='alert' aria-live='assertive'>
  Network error
</div>

→ Dynamic update 가 announce.

Mobile a11y

iOS:
- VoiceOver, accessibilityLabel.
- Dynamic Type (font size).

Android:
- TalkBack, contentDescription.
- Talkback gesture.

React Native:
- accessibilityLabel.
- accessibilityHint.
- accessibilityRole.

Modern HTML 5 elements

<header>, <nav>, <main>, <article>, <section>, <aside>, <footer>
<dialog>, <details>, <summary>

→ Semantic + a11y free.

Popover (modern)

<button popovertarget='my-popover'>Open</button>
<div id='my-popover' popover='auto'>Content</div>

→ Native + a11y 자동.

High contrast

@media (prefers-contrast: more) {
  /* high contrast styles */
}

@media (forced-colors: active) {
  /* Windows high contrast */
}

Cognitive a11y

- Clear language.
- Consistent navigation.
- Error prevention.
- Help text.
- Reasonable defaults.

→ Beyond visual / motor.

Legal

ADA (US) — lawsuit risk.
EAA (EU 2025) — required.
WCAG 2.1 AA = baseline.
Section 508 (US gov) — required.

→ 큰 브랜드 = legal team 검증.

CI gate

- run: npx pa11y http://localhost:3000
- run: npx axe http://localhost:3000
- run: npx lighthouse-ci

함정

- onClick 가 div: keyboard X.
- ARIA 가 native 대신 사용: 잘못 가능.
- Focus 가 잃음: keyboard user lost.
- Color 만 information: blind 가 X.
- Auto-play: vestibular.
- Time limit: cognitive disability.

🤔 의사결정 기준

작업	추천
Component	Native HTML > ARIA
Modal	Radix / shadcn
Form	Native label + aria-describedby
Animation	prefers-reduced-motion
Color	Contrast checker
Test	axe + manual screen reader
CI	pa11y / Lighthouse

❌ 안티패턴

• div + onClick: keyboard X.
• No label: screen reader X.
• Color 만 info: blind 가 X.
• No focus indicator: keyboard X.
• Modal 가 focus trap X: lost.
• Auto-play: vestibular.
• No alt: image 의 의미 X.

🤖 LLM 활용 힌트

• Native HTML 가 best.
• Radix / shadcn 가 a11y baked in.
• axe + manual screen reader test.
• prefers-reduced-motion 항상.

🔗 관련 문서

• Frontend_A11y_Testing
• Frontend_shadcn_Radix_Patterns
• React_Accessibility_Patterns