Communitygithub.com

wcag-audit

웹 UI의 WCAG 2.2 접근성(a11y) 오류를 감사하고 수정합니다. 정적 소스 스캔, 실제 브라우저 런타임 스캔, 적대적 검증, 최소 수정, 기계 판독 가능 보고서를 포함한 단계별 절차를 실행합니다.

wcag-audit란 무엇인가요?

이 스킬은 웹 사용자 인터페이스의 접근성(Accessibility)을 감사하고 수정하는 포괄적인 도구입니다. 개발자가 '접근성 감사', 'a11y 검사', 'WCAG 준수 확인', '스크린 리더 지원', '색상 대비 확인' 등을 요청할 때 사용됩니다. HTML, JSX, TSX, Vue, Svelte, Astro, MDX, Angular, CSS 등 다양한 프레임워크의 정적 소스를 스캔하고, axe-core와 키보드 검사를 통해 실제 브라우저에서 런타임 스캔을 수행합니다. 모든 발견 사항은 적대적 검증(Phase 3)을 거쳐 거짓 양성을 제거하며, 확인된 문제는 최소한의 변경으로 수정됩니다. 최종적으로 기계 판독 가능한 JSON 보고서와 사람이 읽을 수 있는 마크다운 보고서를 생성하며, 수동 검사가 필요한 항목을 명확히 표시합니다. 이 스킬은 Claude Code 같은 에이전트 환경에서 실행되며, Node.js CLI 도구를 활용하거나 오프라인 모드에서도 작동할 수 있습니다.

지원 대상~Claude Code~Codex CLI~Cursor
npx skills add https://github.com/mintwork/wcag-audit-skill/tree/HEAD/skills/wcag-audit

즐겨 사용하는 AI에게 물어보기

이 에이전트 스킬이 미리 로드된 새 채팅을 엽니다.

문서

WCAG 감사

사용자 인터페이스의 접근성 장벽을 감사하고 수정합니다. 장애 사용자는 시력이 있는 마우스 사용자처럼 레이블 누락을 우회할 수 없습니다. 확인된 각 발견 사항을 실제 사람을 막는 실제 버그로 취급하십시오.

목표: 검증된 발견 사항 목록 - 각각 WCAG 2.2 성공 기준에 연결되고, 정확한 위치, 증거 및 최소 수정 사항이 포함되며, 수정 사항이 적용되고 재검증됩니다.

원칙

  1. 검증되지 않으면 출시하지 않습니다. 모든 발견 사항은 3단계를 통과해야 합니다. 사용자가 무시하는 긴 목록보다 진짜 문제의 짧은 목록이 낫습니다.
  2. 기본 HTML 우선. 최고의 ARIA는 ARIA가 없는 것입니다. <div onClick>을 role, tabindex, 키 핸들러를 덧붙여 수정하지 말고 <button>으로 만드십시오.
  3. 최소한의, 동작을 보존하는 수정. 실패한 마크업만 변경하고 주변 코드를 다시 스타일링하거나 리팩터링하거나 포맷하지 마십시오. 발견 사항이 시각적인 경우(대비, 포커스 링, 대상 크기)가 아니라면 시각적 디자인을 변경하지 마십시오.
  4. 내용을 절대 만들어내지 마십시오. 대체 텍스트, 레이블 및 링크 텍스트는 UI가 실제로 의미하는 바를 반영해야 합니다. 이미지가 무엇을 전달하는지 알 수 없으면 발견 사항을 needs_validation으로 표시하고 물어보십시오. alt="이미지"라고 쓰지 마십시오.
  5. 자동화는 바닥이지 천장이 아닙니다. 도구는 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 발견 사항을 심각도가 높은 순서대로 수정 패턴 참조를 사용하여 수정하십시오. 각 수정에 대해:

  1. 프레임워크의 관용구(React의 htmlFor, Vue의 :aria-label 등)를 사용하여 기준을 충족하는 가장 작은 변경을 하십시오.
  2. 한두 문장으로 설명하십시오: 무엇이 잘못되었는지, 누구에게 영향을 미쳤는지, 무엇이 변경되었는지.
  3. 사용자가 이미 진행하라고 말하지 않은 경우, 보이는 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 코드를 수정하지 마십시오. 소스 컴포넌트를 수정하십시오.

파일

관련 스킬