[G1-Sync] Manual knowledge update

2026-05-09 21:08:02 +09:00
parent f0befc887a
commit 93ec7e9056
363 changed files with 68333 additions and 64 deletions
@@ -0,0 +1,161 @@
+---
+id: frontend-a11y-testing
+title: A11y Testing — axe / 키보드 / 스크린리더
+category: Coding
+status: draft
+source_trust_level: B
+verification_status: conceptual
+created_at: 2026-05-09
+updated_at: 2026-05-09
+tags: [frontend, a11y, accessibility, testing, vibe-coding]
+tech_stack: { language: "TS / React", applicable_to: ["Web"] }
+applied_in: []
+aliases: [a11y, accessibility, axe, WCAG, ARIA, screen reader]
+---
+
+# A11y Testing
+
+> 자동화는 30% — 나머지 70% 는 키보드 + 스크린리더 + 색대비. **`axe-core` (개발) + `@axe-core/playwright` (E2E)** 가 기본. ARIA 보다 native HTML 우선.
+
+## 📖 핵심 개념
+- WCAG 2.1 AA: 일반 기준.
+- ARIA: HTML 으로 표현 안 되는 의미 추가. 그러나 native > ARIA.
+- Semantic HTML: button, nav, main, header, footer.
+- Focus management: 모달 열림 → 모달 안 / 닫힘 → 트리거.
+
+## 💻 코드 패턴
+
+### axe-core dev — 자동 검사
+```tsx
+// react app, dev only
+if (process.env.NODE_ENV !== 'production') {
+  import('@axe-core/react').then(({ default: axe }) => {
+    axe(React, ReactDOM, 1000);
+  });
+}
+```
+
+### Playwright E2E
+```ts
+import { expect, test } from '@playwright/test';
+import AxeBuilder from '@axe-core/playwright';
+
+test('home page is accessible', async ({ page }) => {
+  await page.goto('/');
+  const results = await new AxeBuilder({ page }).analyze();
+  expect(results.violations).toEqual([]);
+});
+```
+
+### Storybook + a11y addon
+```ts
+// .storybook/main.ts
+addons: ['@storybook/addon-a11y'],
+```
+
+스토리에 자동 panel — violations 보여줌.
+
+### React Testing Library + jest-axe
+```tsx
+import { axe } from 'jest-axe';
+import { render } from '@testing-library/react';
+
+test('Button has no a11y violations', async () => {
+  const { container } = render(<Button>Save</Button>);
+  expect(await axe(container)).toHaveNoViolations();
+});
+```
+
+### 키보드 — 모든 interactive 가능?
+```ts
+test('navigates with keyboard', async ({ page }) => {
+  await page.goto('/');
+  await page.keyboard.press('Tab');
+  await expect(page.locator(':focus')).toHaveText('Skip to main content');
+  await page.keyboard.press('Enter');
+  await expect(page.locator('main')).toBeFocused();
+});
+```
+
+### Native HTML 우선
+```html
+<!-- ❌ button 처럼 만들지 마 -->
+<div onclick="..." role="button">Save</div>
+
+<!-- ✅ -->
+<button>Save</button>
+```
+
+### Form — label 연결
+```html
+<label for="email">Email</label>
+<input id="email" type="email" required aria-describedby="email-error">
+<p id="email-error" role="alert">잘못된 이메일</p>
+```
+
+### 모달 focus trap
+```tsx
+import { FocusTrap } from 'focus-trap-react';
+
+{open && (
+  <FocusTrap focusTrapOptions={{ initialFocus: '#confirm', returnFocusOnDeactivate: true }}>
+    <div role="dialog" aria-modal="true" aria-labelledby="t">
+      <h2 id="t">정말 삭제?</h2>
+      <button id="confirm">삭제</button>
+      <button onClick={() => setOpen(false)}>취소</button>
+    </div>
+  </FocusTrap>
+)}
+```
+
+또는 Radix UI / Headless UI — focus trap 자동.
+
+### Live region
+```tsx
+<div role="status" aria-live="polite" className="sr-only">
+  {savedAt && `Saved at ${savedAt}`}
+</div>
+```
+
+### Skip link
+```html
+<a href="#main" className="sr-only focus:not-sr-only">Skip to main content</a>
+<main id="main">...</main>
+```
+
+### 색대비
+```css
+/* WCAG AA: text 4.5:1, large text 3:1 */
+.text-on-bg { color: #1a1a1a; background: #fff; } /* 16:1 */
+```
+
+도구: Chrome DevTools color picker, contrast-ratio.com.
+
+## 🤔 의사결정 기준
+| 검사 | 도구 |
+|---|---|
+| 자동 (CI) | axe-playwright / axe-react |
+| 컴포넌트 단위 | jest-axe + RTL |
+| Storybook | addon-a11y |
+| 키보드만 | manual test |
+| 스크린리더 | macOS VoiceOver / NVDA / JAWS |
+| 색대비 | DevTools / Stark |
+
+## ❌ 안티패턴
+- **`<div onClick>` 모든 것을**: 키보드/스크린리더 없음.
+- **Tabindex 양수**: tab 순서 깨짐. `0` 또는 `-1` 만.
+- **`outline: none` 만**: focus-visible 대체.
+- **모달 `<div>` body 끝에 — focus 안 trap**: focus trap 라이브러리.
+- **Image alt 없음**: alt 빈 문자열도 의도. 의미 있는 글로.
+- **placeholder 만 — label 없음**: 스크린리더 사람 못 들음.
+- **Color only 의미 (빨강 = 에러)**: 아이콘 / 텍스트 같이.
+
+## 🤖 LLM 활용 힌트
+- Native HTML > ARIA.
+- axe + jest-axe + Playwright 3종.
+- Radix UI / Headless UI 가 a11y 잘 처리.
+
+## 🔗 관련 문서
+- [[Frontend_i18n_Patterns]]
+- [[Component_Library_Selection]]
+- [[Form_UX_Patterns]]