Accessibility Checker

Overview

Run consistent accessibility reviews driven by a CSV checklist, producing verifiable reports with:

• Results per checklist item: Pass / Fail / N/A / Needs review
• Evidence: File paths, code snippets, story names, URLs, reproduction steps
• Fixes: Concrete, actionable changes with implementation details

This skill works with PR diffs, partial context, or full component reviews.

---

Quick Start

Automated Report Generation

スクリプトは対象リポジトリのルートから、スキル内のパスを指定して実行する。--output などの引数は対象リポジトリのルートからの相対パス。

# Generate report from checklist
python .claude/skills/accessibility-checker/scripts/generate_report.py --component button

# Quick component check
python .claude/skills/accessibility-checker/scripts/check_component.py src/components/ui/button/

# Validate checklist CSV
python .claude/skills/accessibility-checker/scripts/validate_checklist_csv.py

AI-Assisted Review

For comprehensive reviews requiring code understanding and context:

1. Run automated checks first
2. Review checklist items with AI analysis
3. Update report with findings
4. Generate action items

---

Required Inputs

1. Scope (What to Check)

• Component(s): src/components/ui/button/
• Page(s): src/app/dashboard/
• Storybook story(ies): Specific stories or all stories
• PR/branch: GitHub PR number or branch name
• File list: Specific files to review

2. Checklist CSV

• Default location: assets/checklist.csv
• Format: Japanese headers (automatically mapped)
• Columns:
  • 達成基準 → Success criterion ID (e.g., 2.4.7)
  • 項目 → Check name/category
  • レベル → WCAG level (A / AA / AAA)
  • 確認ポイント → What to verify
  • 単体チェック可否 → Component-level feasibility
  • Reactでの実装例 → Implementation hints
  • デザインチェック可否 → Design review feasibility
  • 備考 → Additional notes

If checklist is missing or unclear: Ask user for location and column meanings.

---

Intended Usage

1. Review

Run checklist against target (PR / story / page / component) and produce structured findings report.

2. Component-by-Component

Review each component/story, focusing on applicability and evidence collection.

3. Fix

Apply minimal, safe code changes per component, then re-check affected items: 該当するチェックリスト項目を再判定し、プロジェクトの lint / test を実行して、結果をレポートの「テスト / 検証」に記録する。

🛑 Fix は既定の動作ではない（このスキルで最優先のルール）

このスキルの既定の成果物は レポート生成（"Generate Report" / workflow.md の "3. Review"）まで。 コードの書き換え（workflow.md の "4. Fixes"）は以下を満たしたときだけ行う。

※ ステップ番号は SKILL.md の Quick Workflow（1〜4）と workflow.md（1〜7）で振り方が異なる。 停止位置は番号ではなく名前で判断すること。

• ユーザーが「直して」「修正して」と明示的に依頼した場合に限る。 「a11y チェックして」「レビューして」という依頼は修正の承認ではない
• 修正に入る前に、Fail / Needs review の一覧を提示し、どれを直すかユーザーに選んでもらう。 「見つかったので全部直しておきました」をやらない
• 一度に触るのは選ばれた対象のスコープ内だけ。レビュー中に視界に入った別コンポーネントや 別ファイルの問題は、直さずレポートの「フォローアップ候補」に積む
• Fail の指摘が正しくても、修正が公開 API の変更（props の削除・リネーム・挙動変更）を伴う場合は 実装せず提案に留める（Deprecate Risky APIs Progressively の方針を参照）

English: Reporting is the default deliverable. Only modify code when the user explicitly asks for fixes, and only within the scope they approved — never fix everything you found on your own initiative.

---

Workflow

For detailed workflow (including status updates), see:

• references/workflow.md - Step-by-step procedures
• references/project-policy.md - Project-specific policies

Quick Workflow Summary

Step 1: Confirm Scope

• Ask or infer: What artifacts are in scope?
• PR: Prioritize changed UI surfaces and related stories/tests
• Storybook: Use as primary evidence source
• Code only: Provide best-effort review, mark unverifiable as Needs review

Step 2: Load Checklist

# Validate checklist format
python .claude/skills/accessibility-checker/scripts/validate_checklist_csv.py .claude/skills/accessibility-checker/assets/checklist.csv

Checklist columns are automatically mapped from Japanese headers.

Step 3: Execute Checks

For each checklist item:

1. Determine applicability: If item doesn't apply, mark N/A with reason
2. When failing:
   • Capture evidence (location, problem, manifestation)
   • Propose fix with minimal, safe changes
3. When passing:
   • Record evidence briefly (what was checked)

Design-system guarantees (per project policy): Mark Pass with evidence like:

• "Design-system guaranteed (Figma). No code-level action required unless token deviation exists."

Do not claim tools or tests were executed unless they actually were. If unverifiable, use Needs review.

Step 4: Generate Report

出力場所（必須）: a11y レビューレポートは 対象リポジトリの docs/pr/<component>-a11y-review.md に書き出します。

• ここで言う docs/pr/ は 対象リポジトリ（リポジトリのルート）配下 の docs/pr/ ディレクトリを指します
• スキル内部の reports/ や examples/ ではない（あくまで template 置き場であり成果物の保存先ではない）
• 同様に docs/a11y-reports/ 等の独自パスも使わない
• ファイル名は kebab-case + -a11y-review.md サフィックス（例: button-a11y-review.md、segmented-control-a11y-review.md）
• 同名レポートが既にあれば上書き更新する（更新履歴は git log で追える）

既定の書き方: 下の Report structure の 8 セクションに沿って書く（既存レポート docs/pr/tabs-a11y-review.md 等と同じ構成）。examples/ のテンプレートや scripts/generate_report.py の出力は下書きの起点として使ってよいが、最終形は Report structure に合わせる。

# テンプレートから始める場合の例（対象リポジトリのルートで実行することを想定）
cp .claude/skills/accessibility-checker/examples/component-report.md docs/pr/button-a11y-review.md

Report structure:

1. 対象 / Target: コンポーネント名 + 関連ファイル + レビュー契機
2. 参照したチェックリスト / 方針: checklist パス + project policy + 使っている primitive（Radix 等）が自動提供する ARIA
3. チェック結果: ID / 項目 / Level / 確認ポイント / Result / Evidence / Fix / Notes の 7 列テーブル（assets/checklist.csv の全項目）。最後の Fix / Notes は 1 列で、列名は既存レポート（docs/pr/tabs-a11y-review.md 等）に合わせる
4. Summary: Pass / Fail / Needs review / N/A の件数
5. 対応内容: Fail / Needs review への対処方針
6. Regression 確認（refactor 後のレビューの場合）: 変更前後の挙動差分
7. テスト / 検証: 関連テスト件数と内容
8. フォローアップ候補: 後続で確認したい事項

既存レポート（docs/pr/tabs-a11y-review.md 等）の構造に揃える。

---

Project-Specific Policy (sparkle-design)

This repo has specific conventions about where guarantees live.

Color/Contrast Guaranteed in Figma

Color/contrast criteria (e.g., 1.4.1 / 1.4.3 / 1.4.11) are primarily guaranteed by Figma.

• In code reviews: Do not require code changes by default
• Mark Needs review if:
  • Token deviations exist (custom colors, style overrides)
  • States (disabled/hover/active/loading) are custom-built outside guarantee scope

Deprecate Risky APIs Progressively

For accident-prone APIs that frequently lead to WCAG violations, prefer non-breaking deprecation.

Example: WCAG 2.5.2 Pointer Cancellation

• Avoid onMouseDown / onPointerDown / onTouchStart for actions
• Prefer onClick (activation on release)
• Implementation: Add @deprecated JSDoc + dev warnings; reduce Storybook exposure

See references/project-policy.md for details.

---

Automated Tools

Generate Report

# Full report from checklist
python .claude/skills/accessibility-checker/scripts/generate_report.py --checklist .claude/skills/accessibility-checker/assets/checklist.csv

# Component-specific report — 出力先は必ず docs/pr/<component>-a11y-review.md
python .claude/skills/accessibility-checker/scripts/generate_report.py --component button --output docs/pr/button-a11y-review.md

# Use custom template
python .claude/skills/accessibility-checker/scripts/generate_report.py --template .claude/skills/accessibility-checker/examples/component-report.md

Quick Component Check

# Check component directory
python .claude/skills/accessibility-checker/scripts/check_component.py src/components/ui/button/

# Check specific file with verbose output
python .claude/skills/accessibility-checker/scripts/check_component.py src/components/ui/button/index.tsx --verbose

Note: This performs basic static analysis. For comprehensive checking, use AI-assisted review.

Export Summary

# Export from docs/pr/ where reports live
python .claude/skills/accessibility-checker/scripts/export_summary.py --reports docs/pr/

# Export to file
python .claude/skills/accessibility-checker/scripts/export_summary.py --reports docs/pr/ --output summary.md

Validate Checklist

# Validate CSV structure
python .claude/skills/accessibility-checker/scripts/validate_checklist_csv.py .claude/skills/accessibility-checker/assets/checklist.csv

---

References

For detailed information, consult these references:

• references/wcag-quick-reference.md - WCAG 2.1/2.2 criteria with React examples
• references/common-violations.md - Top 10 violations and fixes
• references/testing-guidelines.md - Automated and manual testing approaches

Load references as needed during review.

---

Report Examples

Report templates available in examples/:

• component-report.md - Detailed component review
• pr-review-summary.md - PR accessibility review
• status-update.md - README status updates

---

Output Format

Findings Table

Report structure の「チェック結果」と同じ 7 列で書く。

ID	項目	Level	確認ポイント	Result	Evidence	Fix / Notes
1.1.1	Non-text Content	A	Icons have text alternatives	Pass	button.tsx:42, has aria-label	-
2.1.1	Keyboard	A	Keyboard accessible	Fail	No onKeyDown for custom div	Add keyboard handler
2.4.7	Focus Visible	AA	Focus indicator visible	Pass	:focus-visible styles present	-
4.1.2	Name, Role, Value	A	Accessible name provided	Needs review	Cannot verify without running	Check with screen reader

---

Guardrails

• Prefer correctness over completeness: "Needs review" is acceptable
• Don't invent evidence: No fake audits or tool outputs
• Avoid long WCAG explanations: Keep it checklist-driven
• Be specific: Provide file paths, line numbers, concrete fixes
• Verify assumptions: Check actual code, don't assume

---

<!-- ========== AI アシスタント向け指示（ユーザーにそのまま見せない） ========== -->

AI Assistant Notes

Execution Guidelines

1. Always validate checklist first: Run validate_checklist_csv.py
2. Start with automated checks: Run check_component.py for quick issues
3. Use templates: Copy appropriate template for report structure
4. Load references as needed: Don't load all references upfront
5. Be evidence-driven: Every Pass/Fail needs concrete evidence
6. Mark Needs review liberally: Better to flag uncertainty than guess

Common Patterns

Full review workflow:

# 1. Validate checklist
python .claude/skills/accessibility-checker/scripts/validate_checklist_csv.py

# 2. Quick automated check
python .claude/skills/accessibility-checker/scripts/check_component.py src/components/ui/button/

# 3. Generate structured report — 出力先は必ず docs/pr/<component>-a11y-review.md
python .claude/skills/accessibility-checker/scripts/generate_report.py --component button --output docs/pr/button-a11y-review.md

# 4. AI reviews each item, updates report with findings

# 5. Export summary for README
python .claude/skills/accessibility-checker/scripts/export_summary.py --reports docs/pr/ --output summary.md

Progressive Disclosure

• Always available: This SKILL.md (overview and workflow)
• Load when checking: references/wcag-quick-reference.md (specific criteria)
• Load on issues: references/common-violations.md (known problems)
• Load for testing: references/testing-guidelines.md (how to verify)

---

Bundled Resources

• assets/checklist.csv: Project checklist (Japanese headers, auto-mapped)
• scripts/validate_checklist_csv.py: CSV validation helper
• scripts/generate_report.py: Report generation automation
• scripts/check_component.py: Quick static analysis
• scripts/export_summary.py: Summary export for README updates
• references/workflow.md: Detailed operational procedures
• references/project-policy.md: Sparkle-design specific policies
• references/*.md: WCAG guides, violations, testing
• examples/*.md: Report templates