A11y Check

---

A11y Check が選ばれる理由

多くの自動チェックツールは、違反の一覧を英語で示すだけです。A11y Check は診断に とどまらず、改善作業につながる成果物を作成します。

• 🇰🇷 KWCAG 2.2 韓国語ルールカタログ — packages/core/src/catalog にある 113 個のルール（axe-core 98 個＋独自ルール 15 個。最新の数値はカバレッジドキュメントを参照）を WCAG 2.2 の達成基準と KWCAG 2.2 の検査項目（33 項目）に二重マッピングし、各ルールに韓国語の 改善ガイドを用意しています。このカタログ自体が、アクセシビリティの実務者や開発者にとって独立して役立つ資産です。
• 🔧 診断から修正へ — 違反ごとに韓国語の改善方法と、AI コーディングツール（Cursor・Copilot など）にそのまま入力できる **修正依頼ドキュメント（Markdown・JSON）**を自動生成します。
• 🧭 WCAG-EM 2.0 の方法論に準拠 — 代表ページのサンプル選定 → 自動チェック → チェッカーによる判定 → 総合適合率まで、 構造化された評価手順に従い、EARL レポートとしてエクスポートできます。
• 🙅 誠実な自動化 — 自動チェックで確定できない項目を隠さず、手動での確認方法とともに案内します。 「100％自動で合格」とは主張しません。
• 🧩 Chrome 拡張機能 — サイドパネルで現在のページをリアルタイムにチェックし、違反をページ上に直接表示します。

自動チェックツールで検出できるアクセシビリティの問題は一部にすぎません。このプロジェクトではその限界を明示し、 人による確認が必要な項目について、チェック方法とともに提示することを原則としています。

できること

	機能
チェック	axe-core ＋独自ルール（リフロー・フォーカス表示・キーボード・代替テキストの品質・メディア・マークアップの妥当性など）＋サイトレベルのチェック（タイトルの一意性・一貫したナビゲーション・複数の方法）
マッピング	すべての違反を WCAG 2.2 の達成基準と KWCAG 2.2 の検査項目に同時に対応付け
レポート	自動／手動／総合の適合率、KWCAG 33 項目マトリクス、認証準備状況の概要、変更前後の比較、PDF・CSV・EARL へのエクスポート
改善	ルール別の韓国語ガイド＋AI 修正依頼ドキュメント（MD/JSON）
拡張機能	Chrome 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 では、プラグイン 1 つで監査スキル 2 種類とチェックエンジン（MCP サーバー）がまとめてインストールされます。 開発中の localhost ページをその場でチェックし、違反ごとに韓国語の改善ガイドを受け取って 修正し、再チェックするまでを 1 回の会話で行えます。

/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/      규칙 카탈로그 → 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

Chrome 拡張機能は、**Chrome ウェブストア**から すぐにインストールできます。ソースからビルドする場合は、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: 열려 있지만, 이 앱을 수정해 네트워크 서비스로 운영하면 수정 소스를 공개해야 합니다.