WCAG 감사
사용자 인터페이스의 접근성 장벽을 감사하고 수정합니다. 장애 사용자는 시력이 있는 마우스 사용자처럼 레이블 누락을 우회할 수 없습니다. 확인된 각 발견 사항을 실제 사람을 막는 실제 버그로 취급하십시오.
목표: 검증된 발견 사항 목록 - 각각 WCAG 2.2 성공 기준에 연결되고, 정확한 위치, 증거 및 최소 수정 사항이 포함되며, 수정 사항이 적용되고 재검증됩니다.
원칙
- 검증되지 않으면 출시하지 않습니다. 모든 발견 사항은 3단계를 통과해야 합니다. 사용자가 무시하는 긴 목록보다 진짜 문제의 짧은 목록이 낫습니다.
- 기본 HTML 우선. 최고의 ARIA는 ARIA가 없는 것입니다.
<div onClick>을role,tabindex, 키 핸들러를 덧붙여 수정하지 말고<button>으로 만드십시오. - 최소한의, 동작을 보존하는 수정. 실패한 마크업만 변경하고 주변 코드를 다시 스타일링하거나 리팩터링하거나 포맷하지 마십시오. 발견 사항이 시각적인 경우(대비, 포커스 링, 대상 크기)가 아니라면 시각적 디자인을 변경하지 마십시오.
- 내용을 절대 만들어내지 마십시오. 대체 텍스트, 레이블 및 링크 텍스트는 UI가 실제로 의미하는 바를 반영해야 합니다. 이미지가 무엇을 전달하는지 알 수 없으면 발견 사항을
needs_validation으로 표시하고 물어보십시오.alt="이미지"라고 쓰지 마십시오. - 자동화는 바닥이지 천장이 아닙니다. 도구는 WCAG 실패의 대략 1/3에서 절반 정도를 잡아냅니다. 테스트되지 않은 항목(수동 체크리스트 참조)을 보고하십시오.
설정
사용자 요청에서 범위를 결정하십시오: 전체 저장소, 디렉터리, 특정 컴포넌트 또는 URL. 그런 다음 도구를 확인하십시오:
npx --yes @mintwork/wcag-audit-skill --version # CLI 사용 가능?
CLI를 사용할 수 없는 경우(오프라인, Node 없음) 수동 모드로 계속 진행하십시오: 소스 코드를 직접 읽어 규칙 목록을 적용하고, 사용자 환경에 다른 브라우저 도구가 없으면 2단계를 건너뛰십시오.
모든 아티팩트를 저장소 루트의 .wcag-audit/에 작성하십시오(생성하고 .gitignore에 추가할 것을 제안하며, 프로젝트가 CI 기준선을 커밋하는 경우 .wcag-audit/baseline.json은 유지하십시오). 사용자가 요청하지 않는 한 다른 곳에 쓰지 마십시오.
워크플로우
단계를 순서대로 실행하십시오. 사용자에게 현재 단계를 알리십시오. 작은 범위(하나의 컴포넌트)의 경우 단계가 간단할 수 있지만 3단계를 건너뛰지 마십시오.
1단계 — 정적 스캔(소스)
npx @mintwork/wcag-audit-skill scan <path> --json -o .wcag-audit/static.json --fail-on none
프로젝트가 기준선을 커밋하더라도 --baseline 없이 감사하십시오: 기준선은 CI가 알려진 발견 사항을 무시하도록 할 뿐이며 여전히 검토가 필요합니다.
그런 다음 도구가 할 수 없는 검토를 수행하십시오: 기본 요소를 래핑하는 사용자 정의 컴포넌트, 조건부 렌더링, 디자인 시스템 프롭(<Icon label=…>), CSS-in-JS에서 제거되거나 다른 스타일시트로 대체된 포커스 스타일(CLI는 .css / .scss / .less 및 Tailwind 클래스를 한 번에 하나의 파일씩 확인합니다), 색상 전용 상태, 스프레드 프롭 또는 동적 값으로 인해 스캐너가 건너뛴 모든 것. 이를 "source": "static" 및 "confidence": "medium"과 함께 후보 발견 사항으로 추가하십시오.
2단계 — 런타임 스캔(실제 브라우저)
URL을 사용할 수 있거나 앱을 시작할 수 있는 경우에만 수행하십시오. 개발 명령어(package.json 스크립트, README)를 찾아 백그라운드에서 시작하고, 응답할 때까지 기다린 후 다음을 실행하십시오:
npx @mintwork/wcag-audit-skill scan http://localhost:3000 --source src --json -o .wcag-audit/runtime.json --fail-on none
# 추가 페이지/상태:
npx @mintwork/wcag-audit-skill scan http://localhost:3000/login http://localhost:3000/cart --json -o .wcag-audit/runtime-2.json --fail-on none
중요한 페이지(홈, 주요 흐름, 양식, 열린 모달)를 스캔하십시오 — 다루어야 할 상태, SPA 대기 및 인증에 대해서는 런타임 스캔 참조를 참조하십시오. 상태(모달 열기, 빈 양식 제출, 다크 모드, 320px)를 구성 파일에 넣고 scan --config .wcag-audit/config.json을 실행하십시오. 로그인된 페이지의 경우 사용자로부터 --storage-state <file>을 사용하고, 절대 자격 증명을 사용하지 마십시오. 프로젝트에 Storybook이 있으면 scan --storybook storybook-static(또는 실행 중인 Storybook URL)도 실행하여 모든 컴포넌트 상태를 다루십시오. 각 런타임 발견 사항의 sourceHint는 검색 결과입니다. 거기서 수정하기 전에 확인하십시오. 런타임 발견 사항은 정적 분석이 잡을 수 없는 것(계산된 대비, 실제 접근 가능한 이름, 포커스 순서, 키보드 트랩, 보이지 않는 포커스)을 잡아냅니다.
3단계 — 검증(거짓 양성 제거)
모든 후보에 대해 검증 참조를 따르십시오. 반증을 시도하십시오: 보고된 줄에서 소스를 열고, 프롭/슬롯/스프레드를 값이 설정된 위치로 추적하고, 상위 요소가 레이블을 제공하는지 확인하고, 런타임 발견 사항에 대해 렌더링된 DOM을 확인하십시오. 다음 중 하나의 평결을 할당하십시오:
confirmed— 추적했으며 기준을 충족하지 못합니다. 어떻게 알았는지 기록하십시오.needs_validation— 그럴듯하지만 확인할 수 없습니다(예: 대체 텍스트 품질, 볼 수 없는 콘텐츠, 도달할 수 없는 페이지). 수정 사항이 적용되지 않습니다.rejected— 반증되었습니다. 이유를 기록하십시오(이는 사용자에게 어떤 규칙을 조정해야 하는지 알려줍니다).
중복을 병합하십시오: 정적 및 런타임에서 보고된 동일한 근본 원인은 두 위치가 모두 포함된 하나의 발견 사항입니다.
4단계 — 수정
confirmed 발견 사항을 심각도가 높은 순서대로 수정 패턴 참조를 사용하여 수정하십시오. 각 수정에 대해:
- 프레임워크의 관용구(React의
htmlFor, Vue의:aria-label등)를 사용하여 기준을 충족하는 가장 작은 변경을 하십시오. - 한두 문장으로 설명하십시오: 무엇이 잘못되었는지, 누구에게 영향을 미쳤는지, 무엇이 변경되었는지.
- 사용자가 이미 진행하라고 말하지 않은 경우, 보이는 UI나 사본(대비 색상, 새로운 보이는 레이블, 링크 텍스트)을 변경하는 수정 전에 물어보십시오.
기계적 발견 사항(html-lang 수리, meta-viewport-zoom, aria-attr-valid 오타)은 CLI로 수정할 수 있습니다: scan <path> --dry-run을 실행하고 사용자에게 diff를 보여준 다음 scan <path> --fix를 실행하십시오. 누락된 lang은 페이지의 언어를 알고 나서만 --lang <code>와 함께 추가하십시오.
그런 다음 기계적으로 재검증하십시오:
npx @mintwork/wcag-audit-skill verify .wcag-audit/static.json
npx @mintwork/wcag-audit-skill verify .wcag-audit/runtime.json # dev 서버가 아직 실행 중이어야 함
verify는 아직 해결되지 않은 항목이 있거나 수정 사항이 새로운 발견 사항을 도입한 경우 0이 아닌 값으로 종료됩니다. 확인된 발견 사항이 해결되거나 코드로 수정할 수 없는 이유(예: 사용자의 캡션 콘텐츠 필요)를 설명할 때까지 반복하십시오. 프로젝트 자체 테스트/린트를 실행하십시오.
5단계 — 보고서
.wcag-audit/findings.json을 보고서 스키마를 준수하여 작성하고 검증하십시오:
node <skill-dir>/scripts/validate-findings.mjs .wcag-audit/findings.json
그런 다음 .wcag-audit/REPORT.md를 작성하고 보고 참조에 따라 사용자에게 짧은 요약을 제공하십시오: 심각도 및 평결별 개수, 수정된 사항, 사용자 입력이 필요한 사항, 테스트되지 않은 사항.
심각도
| 심각도 | 의미 | 예시 |
|---|---|---|
| 치명적 | 일부 사용자에게 작업을 완전히 차단 | 레이블이 없는 양식 필드, 유일한 제출 방법인 <div onClick>, 키보드 트랩, 확대/축소 비활성화 |
| 심각 | 주요 어려움 또는 정보 누락 | 낮은 대비 본문 텍스트, 누락된 페이지 언어, 이름이 없는 링크 |
| 중간 | 마찰, 혼란스러운 구조 | 건너뛴 제목 수준, 중복되거나 맥락에서 모호한 링크 텍스트 |
| 경미 | 다듬기, 모범 사례 | 모호한 대체 텍스트, 자동 포커스 |
심각도는 규칙의 기본값이 아니라 이 UI에서의 사용자 영향을 반영합니다: 바닥글의 레이블이 없는 검색 상자는 로그인 페이지의 레이블이 없는 비밀번호 필드보다 덜 심각합니다.
안티 패턴(하지 말 것)
- 보이는 텍스트를 복제하거나 모순되는
aria-label을 추가하지 마십시오(WCAG 2.5.3 위반). <button>이 작동하는데role="button"+tabindex="0"을 추가하지 마십시오.- 제목 순서 발견 사항을 시각적 크기를 변경하여 "수정"하지 마십시오. 수준을 변경하고 CSS는 유지하십시오.
- 정보를 제공하는 이미지에
alt=""를 설정하여 스캐너를 침묵시키지 마십시오. - 주석 옆에 서면 이유 없이 발견 사항을 억제하지 마십시오(
wcag-audit-ignore). - WCAG "준수"를 주장하지 마십시오 — 자동화 + 에이전트 검토는 실패를 보여줄 수 있지만 적합성은 아닙니다.
- 생성된 코드, 벤더 코드 또는
node_modules코드를 수정하지 마십시오. 소스 컴포넌트를 수정하십시오.
파일
- references/RULES.md — 모든 정적 및 런타임 규칙, WCAG에 매핑됨
- references/STATIC-SCAN.md — 프레임워크별 1단계 수동 검토
- references/RUNTIME-SCAN.md — 2단계 페이지, 상태, SPA, 인증
- references/VERIFICATION.md — 규칙별 3단계 반증 절차
- references/FIX-PATTERNS.md — 4단계 이전/이후 수정
- references/REPORTING.md — 5단계 보고서 형식
- references/MANUAL-CHECKLIST.md — 자동화가 확인할 수 없는 사항
- assets/report-schema.json — findings.json 스키마
scripts/validate-findings.mjs— findings.json용 제로 의존성 검증기