accessibility-wcag

name	accessibility-wcag
description	Enforce WCAG 2.2 accessibility standards. Use when creating UI components, reviewing frontend code, or when accessibility issues are detected. Covers semantic HTML, ARIA, keyboard navigation, and color contrast.
allowed-tools	Read, Glob, Grep, Edit, Write, Bash
license	MIT
metadata	{"author":"antigravity-team","version":"1.0"}

Accessibility (WCAG 2.2)

웹 접근성 표준 WCAG 2.2를 준수하도록 강제하는 스킬입니다.

2025 Context

WCAG 2.2는 2023년 10월 ISO 표준(ISO/IEC 40500)으로 채택되었습니다. 유럽 접근성법(EAA)은 2025년 6월부터 시행됩니다.

Core Principles (POUR)

원칙	설명	예시
Perceivable	인지 가능	대체 텍스트, 자막, 색상 대비
Operable	조작 가능	키보드 접근, 충분한 시간
Understandable	이해 가능	명확한 언어, 예측 가능한 동작
Robust	견고함	보조 기술 호환성

Rules

1. Semantic HTML (필수)

// ❌ BAD: div 남용
<div onClick={handleClick}>버튼</div>
<div class="header">제목</div>

// ✅ GOOD: 시맨틱 태그 사용
<button onClick={handleClick}>버튼</button>
<h1>제목</h1>

2. 이미지 대체 텍스트 (필수)

// ❌ BAD: alt 누락 또는 의미 없음
<img src="logo.png" />
<img src="chart.png" alt="이미지" />

// ✅ GOOD: 의미 있는 alt
<img src="logo.png" alt="회사명 로고" />
<img src="chart.png" alt="2024년 매출 증가 추이 그래프" />

// ✅ 장식용 이미지는 빈 alt
<img src="decoration.png" alt="" role="presentation" />

3. 키보드 접근성 (필수)

// ❌ BAD: 키보드 접근 불가
<div onClick={handleClick} style={{ cursor: 'pointer' }}>
  클릭
</div>

// ✅ GOOD: 키보드 접근 가능
<button onClick={handleClick}>클릭</button>

// 또는 커스텀 요소 사용 시
<div
  role="button"
  tabIndex={0}
  onClick={handleClick}
  onKeyDown={(e) => e.key === 'Enter' && handleClick()}
>
  클릭
</div>

4. 포커스 관리

// ❌ BAD: 포커스 스타일 제거
button:focus {
  outline: none;
}

// ✅ GOOD: 명확한 포커스 표시
button:focus {
  outline: 2px solid #005fcc;
  outline-offset: 2px;
}

button:focus-visible {
  outline: 2px solid #005fcc;
}

5. 색상 대비 (WCAG AA 기준)

텍스트 크기	최소 대비율
일반 텍스트	4.5:1
큰 텍스트 (18pt+, 14pt bold+)	3:1
UI 컴포넌트/그래픽	3:1

/* ❌ BAD: 낮은 대비 */
.text {
  color: #999;  /* 회색 on 흰색 = 2.85:1 */
  background: #fff;
}

/* ✅ GOOD: 충분한 대비 */
.text {
  color: #595959;  /* 4.54:1 */
  background: #fff;
}

6. 폼 레이블 (필수)

// ❌ BAD: 레이블 없음
<input type="email" placeholder="이메일" />

// ✅ GOOD: 명시적 레이블
<label htmlFor="email">이메일</label>
<input id="email" type="email" />

// 또는 aria-label 사용
<input type="email" aria-label="이메일 주소" placeholder="이메일" />

7. ARIA 역할 및 속성

// 모달 다이얼로그
<div
  role="dialog"
  aria-modal="true"
  aria-labelledby="modal-title"
>
  <h2 id="modal-title">확인</h2>
  ...
</div>

// 알림 메시지
<div role="alert" aria-live="polite">
  저장되었습니다.
</div>

// 로딩 상태
<button aria-busy={isLoading} disabled={isLoading}>
  {isLoading ? '처리 중...' : '제출'}
</button>

8. 건너뛰기 링크

// 페이지 상단에 추가
<a href="#main-content" className="skip-link">
  본문으로 건너뛰기
</a>

// CSS
.skip-link {
  position: absolute;
  top: -40px;
  left: 0;
  z-index: 100;
}

.skip-link:focus {
  top: 0;
}

WCAG 2.2 신규 기준

2.4.11 Focus Not Obscured (AA)

// ❌ BAD: 고정 헤더가 포커스 요소를 가림
.header { position: fixed; top: 0; }

// ✅ GOOD: scroll-margin으로 여유 공간 확보
:target {
  scroll-margin-top: 80px;
}

*:focus {
  scroll-margin-top: 80px;
}

2.5.7 Dragging Movements (AA)

// ❌ BAD: 드래그만 지원
<DraggableList onDrag={handleReorder} />

// ✅ GOOD: 드래그 + 버튼 대안 제공
<DraggableList onDrag={handleReorder}>
  <button onClick={moveUp}>위로 이동</button>
  <button onClick={moveDown}>아래로 이동</button>
</DraggableList>

2.5.8 Target Size (AA)

/* 최소 터치 타겟: 24x24px (AA), 44x44px 권장 */
button, a, input[type="checkbox"] {
  min-width: 44px;
  min-height: 44px;
}

테스트 도구

자동화 도구

# axe-core (React)
npm install @axe-core/react

# eslint-plugin-jsx-a11y
npm install eslint-plugin-jsx-a11y --save-dev

# Lighthouse CI
npm install -g @lhci/cli
lhci autorun

eslint 설정

{
  "extends": ["plugin:jsx-a11y/recommended"],
  "rules": {
    "jsx-a11y/alt-text": "error",
    "jsx-a11y/anchor-is-valid": "error",
    "jsx-a11y/click-events-have-key-events": "error",
    "jsx-a11y/no-static-element-interactions": "error"
  }
}

수동 테스트 체크리스트

• 키보드만으로 모든 기능 사용 가능
• Tab 순서가 논리적
• 포커스 표시가 명확함
• 스크린 리더로 내용 이해 가능
• 200% 확대해도 콘텐츠 손실 없음
• 색상만으로 정보 전달하지 않음

Workflow

1. 컴포넌트 작성 시

체크포인트:
1. 시맨틱 HTML 사용했는가?
2. 키보드 접근 가능한가?
3. 적절한 ARIA 속성이 있는가?
4. 포커스 스타일이 있는가?

2. 코드 리뷰 시

접근성 체크:
1. img에 alt 있는가?
2. form에 label 있는가?
3. 색상 대비 충분한가?
4. 터치 타겟 크기 충분한가?

Checklist

• 시맨틱 HTML 태그 사용
• 모든 이미지에 의미 있는 alt
• 폼 요소에 label 연결
• 키보드만으로 조작 가능
• 포커스 표시 명확
• 색상 대비 4.5:1 이상
• 터치 타겟 44x44px 이상
• 건너뛰기 링크 제공
• axe/Lighthouse 테스트 통과

References

• WCAG 2.2
• WAI-ARIA 1.2
• eslint-plugin-jsx-a11y