`~`

---
name: fe-a11y-audit
description: 프론트엔드 접근성 감사를 WCAG 2.1 기준으로 수행하고, 위반 항목과 구체적인 수정안을 제시한다.
argument-hint: "[대상 디렉터리 또는 파일 경로] (선택: 준수 레벨 A/AA/AAA)"
user-invocable: true
disable-model-invocation: true
allowed-tools: Read, Grep, Glob
---

당신은 신중한 시니어 엔지니어다. $ARGUMENTS 를 대상으로 아래 작업을 수행하라.

## 목적

프론트엔드 코드베이스를 WCAG 2.1 기준에 따라 정적 감사하고, 접근성 문제를 식별한다.  
각 문제의 심각도, 영향을 받는 사용자 그룹, 구체적인 수정 코드 예시를 제시한다.  
자동 테스트로 탐지 가능한 항목과 수동 확인이 필요한 항목을 명확히 구분한다.

## 입력

- 대상 디렉터리 또는 파일 경로 (필수)
- 선택: 준수 레벨 (A / AA / AAA, 기본값: AA)
- 선택: 사용 프레임워크 (React / Vue / Angular / 정적 HTML 등)
- 선택: 중점 점검 영역 (폼 / 내비게이션 / 미디어 / 색상 대비 등)
- 정보가 부족하면 사용자에게 질문한다

## 절차

1. **코드베이스 파악**
   - Glob으로 대상 파일 식별 (`*.html`, `*.jsx`, `*.tsx`, `*.vue`, `*.svelte` 등)
   - Read로 컴포넌트 구조 확인
   - Grep으로 기존 접근성 대응 여부 검색 (`aria-`, `role=`, `alt=`, `tabIndex`)
   - 사용 중인 UI 라이브러리 또는 컴포넌트 라이브러리 확인

2. **지각 가능성(Perceivable) 점검**
   - 이미지 대체 텍스트: `<img>`에 `alt` 속성이 있는지, 장식용 이미지는 `alt=""`인지 확인
   - 미디어 대체 수단: `<video>` / `<audio>`에 자막 또는 대본 제공 여부
   - 콘텐츠 구조: 제목 계층(`<h1>`~`<h6>`)이 올바른 순서인지 확인
   - 색상에만 의존한 정보 전달 여부 (예: 에러를 색으로만 표시)
   - Grep으로 `color:` / `background-color:` 검색 후 대비 비율 확인 필요 영역 식별

3. **조작 가능성(Operable) 점검**
   - 키보드 접근성: `onClick`만 있고 `onKeyDown` / `onKeyPress`가 없는 요소 탐지
   - 포커스 관리: `tabIndex` 사용 방식, 포커스 트랩 존재 여부 확인
   - 내비게이션: 스킵 링크, 랜드마크(`<nav>`, `<main>`, `<aside>`) 존재 여부
   - 시간 제한: `setTimeout`, `setInterval`, `animation` 사용 시 중지 수단 제공 여부

4. **이해 가능성(Understandable) 점검**
   - 언어 설정: `<html lang="...">` 존재 여부
   - 폼 레이블: `<input>`에 연결된 `<label>` 또는 `aria-label` 존재 여부
   - 에러 메시지: 유효성 검사 메시지가 구체적이며 필드와 연결되어 있는지
   - UI 일관성: 내비게이션 및 주요 UI 요소의 일관성 유지 여부

5. **견고성(Robust) 점검**
   - 시맨틱 HTML 사용 여부: `<div>` / `<span>` 대신 적절한 HTML 요소 제안
   - ARIA 사용 적절성: role / property / state가 명세에 맞게 사용되었는지
   - 커스텀 컴포넌트: 커스텀 위젯에 적절한 ARIA 패턴이 적용되었는지

## 출력 형식

```markdown
## 접근성 감사 보고서

- **대상**: [디렉터리 / 파일]
- **준수 레벨**: WCAG 2.1 [A / AA / AAA]
- **프레임워크**: [감지된 프레임워크]
- **검사 파일 수**: [N개]

## 감사 결과 요약

| 심각도 | 건수 | 자동 탐지 가능 | 수동 확인 필요 |
|--------|------|---------------|----------------|
| Critical (사용 불가 수준) | [N] | [N] | [N] |
| Major (심각한 불편) | [N] | [N] | [N] |
| Minor (개선 필요) | [N] | [N] | [N] |

## 위반 항목 목록

### Critical

| # | WCAG 기준 | 문제 | 파일:라인 | 영향 사용자 | 수정안 |
|---|-----------|------|------------|--------------|--------|
| 1 | [1.1.1] | [문제 설명] | [file:line] | [스크린리더 사용자 등] | [수정 코드] |

### Major

| # | WCAG 기준 | 문제 | 파일:라인 | 영향 사용자 | 수정안 |
|---|-----------|------|------------|--------------|--------|
| 1 | [기준 번호] | [문제 설명] | [file:line] | [영향 사용자] | [수정 코드] |

### Minor

| # | WCAG 기준 | 문제 | 파일:라인 | 영향 사용자 | 수정안 |
|---|-----------|------|------------|--------------|--------|
| 1 | [기준 번호] | [문제 설명] | [file:line] | [영향 사용자] | [수정 코드] |

## 수동 확인 필요 항목

| # | 점검 항목 | 대상 | 확인 방법 |
|---|-----------|------|------------|
| 1 | [확인 내용] | [파일] | [확인 절차] |

## 개선 우선순위 맵

| 우선순위 | 대응 내용 | 예상 공수 | 영향도 |
|----------|-----------|-----------|--------|
| 높음 | [Critical 수정] | [S/M/L] | [높음] |
| 중간 | [Major 수정] | [S/M/L] | [중간] |
| 낮음 | [Minor 수정] | [S/M/L] | [낮음] |
```

## 보안 및 유의사항

- 코드는 수정하지 않는다. 감사와 개선 제안만 수행한다.
- 정적 분석으로 확인 가능한 범위만 보고하고, 실행 시 동작 추정은 “수동 확인 필요”로 명시한다.
- 색상 대비 비율은 CSS 값으로 계산 가능한 경우에만 보고한다. 동적 변경 요소는 수동 점검을 권장한다.
- 수정안은 해당 프레임워크의 관례에 맞게 제시한다.
- 네이티브 HTML 요소로 해결 가능한 경우 ARIA 남용을 피한다.

## 종료 조건

위 출력 형식에 맞춘 접근성 감사 보고서를 작성하면 종료한다.
심각도별 위반 목록, 수동 확인 항목, 개선 우선순위 맵이 포함되어야 한다.
코드 수정은 사용자의 추가 지시를 기다린다.