A11y Check

---

왜 A11y Check인가

대부분의 자동 검사 도구는 위반 목록을 영어로 나열하는 데 그칩니다. A11y Check는 진단에서 멈추지 않고 개선 작업으로 이어지는 산출물을 만듭니다.

• 🇰🇷 KWCAG 2.2 한국어 규칙 카탈로그 — packages/core/src/catalog에 111개 규칙을 WCAG 2.2 성공기준과 KWCAG 2.2 검사항목(33개)에 이중 매핑하고, 규칙마다 한국어 개선 가이드를 담았습니다. 이 카탈로그 자체가 접근성 실무자·개발자에게 독립적으로 유용한 자산입니다.
• 🔧 진단 → 수정 연결 — 위반마다 한국어 개선 방법 + AI 코딩 도구(Cursor·Copilot 등)에 그대로 투입 가능한 **수정 요청 문서(Markdown·JSON)**를 자동 생성합니다.
• 🧭 WCAG-EM 2.0 방법론 준수 — 대표 페이지 표본 선정 → 자동 점검 → 점검자 판정 → 통합 준수율까지 구조화된 평가 절차를 따르고, EARL 리포트로 내보낼 수 있습니다.
• 🙅 정직한 자동화 — 자동 검사가 확정할 수 없는 항목은 감추지 않고 수동 검사 방법과 함께 안내합니다. "100% 자동 통과"를 주장하지 않습니다.
• 🧩 크롬 확장 — 사이드 패널에서 현재 페이지를 실시간 점검하고, 위반을 페이지 위에 직접 표시합니다.

자동 검사 도구는 접근성 문제의 일부만 찾을 수 있습니다. 이 프로젝트는 그 한계를 명시하고, 사람이 확인해야 하는 항목을 검사 방법과 함께 제공하는 것을 원칙으로 합니다.

무엇을 하나

	기능
점검	axe-core + 자체 규칙(리플로우·텍스트 간격·초점·키보드·미디어 등) + 사이트 수준 검사(제목 유일성·일관된 내비·여러 방법)
매핑	모든 위반을 WCAG 2.2 성공기준 · KWCAG 2.2 검사항목에 동시 대응
보고서	자동/수동/통합 준수율, KWCAG 33항목 매트릭스, 인증 준비 요약, 전후 비교, PDF·CSV·EARL 내보내기
개선	규칙별 한국어 가이드 + AI 수정 요청 문서(MD/JSON)
확장	크롬 MV3 사이드 패널 — 실시간 점검·구조 시각화·장애 시뮬레이션·명도대비 스포이드·전문가 판정
맛보기	로그인 없이 URL 1개를 즉석 검사(1페이지) — 랜딩에서 바로 체험, 봇 방지·횟수 제한
운영	도메인 소유확인, 정기 자동 점검, 회귀 알림, 임베드 배지, 공개 점검 목록, 친구 초대 등급
CI	GitHub Action으로 PR·배포 전 자동 검사 게이트 — 사용법
MCP	Claude Code·Cursor 등 AI 코딩 도구가 검사·한국어 가이드를 직접 호출 — 사용법

CI에서 바로 쓰기

PR마다 지정 페이지를 검사하고, 심각 이상 위반이 있으면 잡을 실패시킵니다. 결과는 잡 요약에 Markdown 표로 남습니다.

- uses: IsaacEryn/a11ychk@v1
  with:
    urls: |
      https://example.com/
      https://example.com/login
    fail-on: serious

입력·출력과 버전 고정 방법은 docs/github-action.md에 있습니다.

AI 코딩 도구에서 바로 쓰기 (플러그인 · MCP)

Claude Code에서는 플러그인 하나로 감사 스킬 2종과 검사 엔진(MCP 서버)이 함께 설치됩니다. 개발 중인 localhost 페이지를 그 자리에서 검사하고, 위반마다 한국어 개선 가이드를 받아 수정하고, 재검사까지 한 대화에서 돕니다.

/plugin marketplace add IsaacEryn/a11ychk
/plugin install a11ychk@a11ychk

• /a11ychk:a11y-audit — 검사 → 수정 → 재검사 루프 (배포 전 점검)
• /a11ychk:kwcag-audit — KWCAG 2.2 33개 검사항목 관점 점검

MCP 서버만 쓰려면 (Cursor 등 다른 클라이언트 포함):

claude mcp add a11ychk -- npx -y @a11ychk/mcp

{
  "mcpServers": {
    "a11ychk": { "command": "npx", "args": ["-y", "@a11ychk/mcp"] }
  }
}

도구 구성과 설치 안내는 docs/mcp.md에 있습니다.

구조 (npm workspaces 모노레포)

packages/core     @a11ychk/core — 검사 엔진 (오픈소스의 심장)
  src/crawler/      대표 페이지 수집 (sitemap → 내부 링크, robots.txt 존중)
  src/scanner/      axe-core 실행·결과 정규화 (Playwright Page 주입형) + 2-패스 안정성 필터
  src/catalog/      111개 규칙 → WCAG 2.2 · KWCAG 2.2 이중 매핑 + 한국어 개선 가이드
  src/manual/       수동 검사 항목 정의 (KWCAG 33개 중 자동 판정 불가 항목)
  src/report/       보고서 집계 (준수율, KWCAG 매트릭스, 사이트 수준 검사)
  src/security/     SSRF 가드 (사설 IP·DNS 리바인딩·redirect 차단), robots.txt 파서
packages/mcp      @a11ychk/mcp — AI 코딩 도구용 MCP 서버 (npm)
apps/web          Next.js 16 서비스 앱 (a11ychk.com)
apps/extension    크롬 확장 (MV3 Side Panel)
action            GitHub Action 러너 (워크스페이스 밖 독립 패키지 — 소비자 CI가 직접 설치)
supabase          DB 마이그레이션 + RLS 정책
docs              아키텍처 · 로드맵 · 운영 설정

시작하기

npm install
cp apps/web/.env.example apps/web/.env.local   # Supabase 키 등 입력
npx playwright install chromium                 # 로컬 스캔용 브라우저
npm run dev                                     # http://localhost:3000

크롬 확장은 **크롬 웹스토어**에서 바로 설치할 수 있습니다. 소스에서 빌드하려면 npm run build -w @a11ychk/extension → apps/extension/dist를 chrome://extensions에서 압축 해제 로드. Supabase 설정은 docs/SETUP.md 참고.

기술 스택

Next.js 16 (App Router) · TypeScript · Tailwind CSS v4 · next-intl(ko/en) · Supabase (Auth + PostgreSQL/RLS) · playwright-core + @sparticuz/chromium · axe-core 4.12 · Zod · Vercel

테스트

npm run test                        # core 유닛 테스트 + 웹 테스트
npm run test:e2e -w @a11ychk/core   # 실제 크로미엄으로 fixture 스캔 E2E
npm run typecheck && npm run lint

보안 원칙

• 모든 시크릿은 환경변수로만 관리 — 저장소에는 .env.example만 존재
• 사용자 입력 URL은 SSRF 가드(스킴 검증 → DNS resolve → 사설 대역 차단 → 브라우저 DNS 핀 → redirect 재검증)를 통과
• Supabase RLS로 사용자 데이터 격리, service role은 서버에서 권한 검증 후에만 사용
• 검사 횟수 제한(일/주/월) + robots.txt 존중, CSP nonce·표준 보안 헤더 적용

기여

규칙 카탈로그(packages/core/src/catalog)의 한국어 개선 가이드 보강·매핑 교정·새 규칙 제안 PR을 가장 환영합니다. 코드가 아니어도 기여입니다 — CONTRIBUTING.md 참고.

도움이 되었다면 ⭐️ Star로 프로젝트를 응원해 주세요. 한국어 접근성 도구 생태계를 함께 키웁니다.

라이선스

분할 라이선싱 — 자세한 내용은 LICENSING.md 참고.

• 검사 엔진·규칙 카탈로그 (packages/core) · MCP 서버 (packages/mcp) · 크롬 확장 (apps/extension) · GitHub Action (action/) → Apache-2.0: 자유롭게 사용·수정·재배포·통합할 수 있습니다.
• 서비스 앱 (apps/web) → AGPL-3.0-only: 열려 있지만, 이 앱을 수정해 네트워크 서비스로 운영하면 수정 소스를 공개해야 합니다.