접근성 감사 도구
웹 애플리케이션의 접근성(WCAG 2.1 Level AA) 준수 여부를 감사하고 개선점을 제안합니다.
사용 시기
- UI 컴포넌트를 빌드하거나 검토할 때
- 사용자가 접근성 개선을 요청할 때
- 접근성 감사 준비 중일 때
- 사용자가 "접근성", "a11y", "WCAG", "스크린 리더", "키보드 탐색"을 언급할 때
지침
1. 시맨틱 HTML 체크
적절한 HTML 요소 사용:
<!-- 나쁨 -->
<div onclick="submit()">제출</div>
<!-- 좋음 -->
<button onclick="submit()">제출</button>
시맨틱 구조:
<header>,<nav>,<main>,<footer><article>,<section>,<aside><h1>~<h6>올바른 계층 구조로- 액션에는
<button>, 탐색에는<a>
2. ARIA 속성
ARIA 사용 시기:
- 사용자 정의 위젯 (탭, 아코디언, 모달)
- 동적 콘텐츠 업데이트
- 복잡한 상호작용
- 시맨틱 HTML만으로 부족할 때
일반적인 ARIA 속성:
<!-- 랜드마크 역할 -->
<nav role="navigation" aria-label="메인">
<!-- 위젯 역할 -->
<div role="button" tabindex="0" aria-pressed="false">
<!-- 라이브 리전 -->
<div role="alert" aria-live="assertive">오류가 발생했습니다</div>
<!-- 레이블 및 설명 -->
<button aria-label="대화상자 닫기">×</button>
<input aria-describedby="비밀번호-도움말" />
ARIA의 첫 번째 규칙: 시맨틱 HTML로 해결된다면 ARIA를 사용하지 마세요
3. 키보드 탐색
모든 대화형 요소는 키보드로 접근 가능해야 합니다:
// 사용자 정의 요소에 키보드 지원 추가
<div
role="button"
tabindex="0"
onClick={handleClick}
onKeyDown={(e) => {
if (e.key === 'Enter' || e.key === ' ') {
handleClick();
}
}}
>
클릭하세요
</div>
탭 순서:
- 사용자 정의 대화형 요소에는
tabindex="0"사용 tabindex > 0은 피하세요 (혼란스러운 탭 순서 유발)- 프로그래매틱 포커스 전용으로
tabindex="-1"사용
포커스 관리:
- 시각적 포커스 표시기
- 모달 내 포커스 트래핑
- 대화상자 닫을 때 포커스 반환
- 주요 콘텐츠로 건너뛰기 링크
4. 대체 텍스트 및 이미지
정보 제공 이미지:
<img src="chart.png" alt="3분기 매출 25% 증가" />
장식용 이미지:
<img src="decoration.png" alt="" />
<!-- 또는 -->
<img src="decoration.png" role="presentation" />
복잡한 이미지:
<figure>
<img src="complex-chart.png" alt="분기별 매출 차트" />
<figcaption>
차트 데이터에 대한 상세 설명...
</figcaption>
</figure>
5. 색상 및 대비
대비 비율 (WCAG AA):
- 일반 텍스트: 최소 4.5:1
- 큰 텍스트(18pt 이상): 최소 3:1
- UI 컴포넌트: 최소 3:1
색상에만 의존하지 마세요:
<!-- 나쁨: 색상만 사용 -->
<span style="color: red;">오류</span>
<!-- 좋음: 아이콘 + 색상 -->
<span style="color: red;">
<svg aria-hidden="true"><!-- 오류 아이콘 --></svg>
<span class="sr-only">오류: </span>
잘못된 입력
</span>
6. 폼 및 레이블
모든 입력에는 레이블이 필요합니다:
<!-- 명시적 레이블 -->
<label for="email">이메일</label>
<input id="email" type="email" />
<!-- 암시적 레이블 -->
<label>
이메일
<input type="email" />
</label>
<!-- 아이콘 버튼의 aria-label -->
<button aria-label="검색">
<svg><!-- 검색 아이콘 --></svg>
</button>
오류 메시지:
<input
id="password"
aria-invalid="true"
aria-describedby="password-error"
/>
<div id="password-error" role="alert">
비밀번호는 최소 8자 이상이어야 합니다
</div>
7. 제목 및 문서 구조
올바른 제목 계층 구조:
<h1>페이지 제목</h1>
<h2>섹션 1</h2>
<h3>하위 섹션 1.1</h3>
<h3>하위 섹션 1.2</h3>
<h2>섹션 2</h2>
레벨을 건너뛰지 마세요: h1 → h2 → h3 (h1 → h3 안 됨)
8. 동적 콘텐츠
스크린 리더에 업데이트 알림:
<!-- 예의: 사용자 일시 중지까지 대기 -->
<div role="status" aria-live="polite">
5개의 새 메시지
</div>
<!-- 적극적: 즉시 중단 -->
<div role="alert" aria-live="assertive">
세션이 1분 후에 만료됩니다
</div>
로딩 상태:
<button aria-busy="true" aria-label="로딩 중...">
<span aria-hidden="true">로딩</span>
</button>
9. 스크린 리더 테스트
스크린 리더 전용 텍스트:
.sr-only {
position: absolute;
width: 1px;
height: 1px;
padding: 0;
margin: -1px;
overflow: hidden;
clip: rect(0, 0, 0, 0);
white-space: nowrap;
border-width: 0;
}
장식 요소 숨기기:
<svg aria-hidden="true"><!-- 아이콘 --></svg>
10. 일반적인 문제 확인 사항
누락:
- 이미지의 대체 텍스트
- 폼 입력의 레이블
- 올바른 제목 계층 구조
- 키보드 포커스 표시기
- 아이콘 버튼의 ARIA 레이블
부적절:
- 낮은 대비 텍스트
- 비시맨틱 마크업 (버튼에 div 사용)
- 모달 내 포커스 관리 누락
- 키보드 트랩
- 자동 재생 미디어
테스트:
- 키보드 전용 탐색
- 스크린 리더 (NVDA, JAWS, VoiceOver)
- 색맹 시뮬레이션
- 200% 확대
- 자동화 도구 (axe, Lighthouse)
11. 자동화된 테스트
도구:
# Lighthouse
npx lighthouse https://example.com --only-categories=accessibility
# axe-core
npm install --save-dev @axe-core/cli
npx axe https://example.com
# pa11y
npm install --save-dev pa11y
npx pa11y https://example.com
테스트 코드:
import { axe } from 'jest-axe';
test('접근성 위반이 없어야 함', async () => {
const { container } = render(<MyComponent />);
const results = await axe(container);
expect(results).toHaveNoViolations();
});
12. WCAG 2.1 Level AA 체크리스트
인지 가능:
- 비텍스트 콘텐츠에 대한 텍스트 대체
- 오디오/비디오 자막
- 적응 가능한 콘텐츠 (시맨틱 마크업)
- 충분한 색상 대비
운용 가능:
- 키보드 접근 가능
- 키보드 트랩 없음
- 적절한 시간 제한 (조정 가능)
- 발작 유발 깜빡임 없음
- 탐색 건너뛰기 링크
- 설명적인 페이지 제목
- 포커스 순서가 논리적임
- 링크 목적을 문맥에서 명확히 알 수 있음
이해 가능:
- 페이지 언어 지정 (
<html lang="en">) - 예측 가능한 탐색
- 입력 도움말 (레이블, 지침, 오류 메시지)
견고:
- 유효한 HTML
- 사용자 정의 위젯의 이름, 역할, 값
- 보조 기술과의 호환성
모범 사례
- 처음부터 접근성 고려하여 구축
- 실제 보조 기술로 테스트
- 시맨틱 HTML 우선, ARIA는 그다음
- 논리적인 문서 구조 유지
- 콘텐츠에 여러 접근 방식 제공
- 키보드 탐색 철저히 테스트
- 확대/축소 비활성화 금지
- 랜드마크 및 제목 사용
지원 파일
reference/wcag-checklist.md: 전체 WCAG 2.1 AA 체크리스트reference/aria-patterns.md: 일반적인 ARIA 위젯 패턴


