refactor(topics): 멀티 에이전트용 지식 재편 — _Common(공통 기본기) + Domain_* 구조
에이전트 8종(대화형/프로그래머 C·S/디자이너/설계자/기획자/QA/PD/PM)에게 [공통 기본 능력 + 롤별 Specialty] 2층으로 지식을 주입하기 위한 재분류. 문서 내용·포맷은 무수정, 폴더 이동만 (6,372개 문서 수 보존 확인). - Topic_Programming → Domain_Programming (내부 구조 보존) - Topic_Graphic → Domain_Design - Topic_Business → Domain_Product - Topic_General → Domain_General - _Common 신설: Math(구 Topic_Math_Specialty), Reasoning(구 General/From_Thinking & Reasoning), Reasoning_Creativity(구 General/From_창의성), Communication(Poetic_Blog_Writing + From_writing) - 타 도메인의 From_* 폴더는 유지 (출처 표기일 뿐, 이미 도메인에 맞게 분류된 문서) - 빈 폴더 정리 (memory/procedures) - 에이전트→폴더 매핑은 workspace의 .astra/agent-knowledge-map.json (9개 에이전트) Co-Authored-By: Claude Fable 5 <noreply@anthropic.com>
This commit is contained in:
Antigravity Agent
@@ -0,0 +1,159 @@
|
||||
---
|
||||
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]]
|
||||
Reference in New Issue
Block a user