accessibility-compliance

accessibility-compliance スキルの概要

accessibility-compliance スキルでできること

accessibility-compliance は、Web とモバイル UI の実装にそのまま落とし込めるアクセシビリティ改善ガイダンスを、エージェントに出させるためのスキルです。特に WCAG 2.2、ARIA の使い分け、キーボード操作、スクリーンリーダー対応、モバイルアクセシビリティを重視しています。汎用的なアクセシビリティチェックリストを書く用途よりも、実際のインターフェース実装を進めるチームに向いています。

accessibility-compliance を導入すべき人

このスキルが特に合うのは、次のようなケースです。

• accessibility-compliance for UX Audit を必要とする UX 監査担当者
• コンポーネントのアクセシビリティ不具合を修正する frontend engineer
• アクセシブルな操作パターンを定義したい design systems team
• フォーム、ダイアログ、メニューなどのインタラクティブ UI を提供する product team
• VoiceOver や TalkBack を踏まえたガイダンスが必要な mobile / cross-platform team

「この画面やコンポーネントを、具体的な修正案付きで WCAG 準拠に近づけたい」という仕事なら、広い設計プロンプトよりもこのスキルのほうが実用的です。

generic prompt と違う理由

accessibility-compliance skill の大きな価値は、曖昧な原則論ではなく、実装可能なアクセシビリティ対応パターンにモデルの出力を絞り込めることです。リポジトリには、次のような焦点の合ったリファレンスがあります。

• references/wcag-guidelines.md
• references/aria-patterns.md
• references/mobile-accessibility.md

そのため、ARIA より semantic HTML を優先する判断、アクセシブルなフォーム構造、キーボード挙動の改善、モバイル向けタッチターゲットの確認といった実務に向いています。

accessibility-compliance install 前に確認したいポイント

accessibility-compliance install を検討する多くの人が気にするのは、主に次の点です。

• 方針文ではなく、コード寄りの具体的な修正案が出るか
• Web とモバイルの両方をカバーしているか
• 監査だけでなく実装支援にも使えるか
• ネイティブセマンティクスと ARIA の使い分けに方針があるか
• UI コンポーネントレビュー時の往復を減らせるか

この観点では、かなり堅実です。特に、WCAG の考え方、ARIA パターン、モバイルアクセシビリティを 1 つにまとめて扱える実務的な広さが、このスキルの強みです。

向いているケース・向いていないケース

向いているケース:

• インタラクティブなコンポーネントの監査
• 既存コードのアクセシビリティ不具合修正
• ダイアログ、アコーディオン、フォーム、ナビゲーションのアクセシブルな挙動設計
• フォーカス順序、ラベル、読み上げ、reduced-motion 対応の見直し

向いていないケース:

• 特定の法域における法的コンプライアンス解釈
• これ単体での自動テスト環境構築
• アクセシビリティと無関係なピクセル単位の見た目レビュー
• 参照ガイダンスの範囲を超える、深いプラットフォーム固有 native API 対応

accessibility-compliance スキルの使い方

導入方法と呼び出し方

upstream の SKILL.md には install command が明記されていないため、directory 経由で使う場合は通常リポジトリから追加します。

npx skills add https://github.com/wshobson/agents --skill accessibility-compliance

呼び出すときは、単に「アクセシビリティをチェックして」ではなく、具体的なタスクを与えるのが重要です。対象のコンポーネント、操作フロー、画面構成がある程度わかる状態だと、このスキルは特に力を発揮します。

まず読むべきファイル

素早く立ち上げるなら、次の順で確認するのがおすすめです。

1. plugins/ui-design/skills/accessibility-compliance/SKILL.md
2. plugins/ui-design/skills/accessibility-compliance/references/wcag-guidelines.md
3. plugins/ui-design/skills/accessibility-compliance/references/aria-patterns.md
4. plugins/ui-design/skills/accessibility-compliance/references/mobile-accessibility.md

この順番は、多くのチームの進め方に沿っています。最初に準拠目標、次に実装パターン、最後にプラットフォーム特有の注意点を見る流れです。

accessibility-compliance をうまく使うために必要な入力

accessibility-compliance usage の質は、入力の具体性に大きく左右されます。少なくとも次は渡してください。

• コンポーネントまたはページの種類
• 現在の code / markup
• framework (React, Next.js, Vue, plain HTML, React Native)
• インタラクションの挙動
• 目標基準（通常は WCAG 2.2 AA）
• 対象デバイス範囲: desktop web, mobile web, iOS, Android
• 監査ツールやユーザーテストで見つかっている既知の問題

弱い入力:

• “Make this accessible.”

強い入力:

• “Review this React modal for WCAG 2.2 AA. Check keyboard trap behavior, focus return, accessible name/description, escape handling, and screen reader announcements. Suggest code changes before release.”

曖昧な依頼を良い prompt に変える

良い accessibility-compliance guide の prompt は、通常次の 5 要素で構成されます。

1. 対象 UI
2. ユーザー操作
3. 準拠目標
4. 期待する成果物
5. 制約

例:

• “Use the accessibility-compliance skill to audit this checkout form for WCAG 2.2 AA. Identify failures by issue, explain user impact, and provide corrected JSX for labels, error messaging, field grouping, and keyboard flow. Keep the current visual design if possible.”

「best practices を教えて」と頼むよりも、この形のほうが修正可能なアウトプットを引き出せます。

UX Audit でのおすすめ workflow

accessibility-compliance for UX Audit として使うなら、次の順番が有効です。

1. まず問題点の洗い出しを依頼する
2. 次に重大度とユーザー影響を聞く
3. その後、各問題に対応する修正案を出させる
4. 改訂後の markup や component code を求める
5. 最後に再テスト用チェックリストを作らせる

こうすると、最初の回答が概念論だけで終わるありがちな失敗を避けられます。このスキルは、監査結果から実装詳細へ踏み込ませたときに最も役立ちます。

ページ全体だけでなくコンポーネント単位で使う

このスキルは、再利用されるインタラクションパターンに特に強いです。相性が良い対象の例は次のとおりです。

• dialogs と focus traps
• accordions
• menus と disclosures
• forms と validation
• tabs
• carousels
• icon buttons
• mobile touch targets

こうした領域は、generic prompt だと ARIA を過剰に使ったり、キーボード操作やスクリーンリーダー挙動を見落としたりしやすいところです。

リファレンスから実務上読み取れること

同梱されているリファレンスからは、実際の運用上、次の 3 つが重要だと読み取れます。

• ARIA を足す前に semantic HTML を優先する
• 既定のベースラインは WCAG 2.2 AA として扱う
• desktop のキーボード操作だけでなく、モバイルアクセシビリティも考慮する

実務ではここが効きます。まともな prompt にするなら、「不要な ARIA は避け、追加する場合は理由も示す」と明示しておくのが有効です。

accessibility-compliance でより強い出力を得る prompt パターン

次のような形式で依頼すると効果的です。

• Context: “This is a React checkout drawer.”
• Target: “Meet WCAG 2.2 AA.”
• Review scope: “Keyboard access, focus order, visible labels, error association, live region announcements.”
• Constraints: “Do not rewrite the design system API.”
• Deliverable: “Return prioritized issues, corrected JSX, and a manual test checklist.”

この構成は、自由度の高いレビュー依頼よりも一貫して良い accessibility-compliance usage につながります。

期待できる出力

accessibility-compliance skill の良い回答には、通常次の内容が含まれます。

• ユーザー影響に結びついた issue list
• アクセシビリティ原則や基準への言及
• 具体的な markup / code の修正案
• キーボード操作とフォーカス挙動の注意点
• スクリーンリーダーでの名前付けや読み上げ案内
• 必要に応じたモバイル固有の補足

原則論だけでコードレベルの修正に踏み込まないなら、prompt が広すぎる可能性が高いです。

accessibility-compliance スキル FAQ

accessibility-compliance は初心者にも向いていますか？

はい。ただし、基本的な UI 構造を理解していることが前提に近いです。markup、component、監査結果などを渡せるほど、このスキルの価値は高まります。初心者でも使えますが、なぜそのセマンティクスや ARIA の選択が必要なのかは、追加で掘り下げて聞く前提になります。

普通のアクセシビリティ prompt より良いですか？

実装用途では、たいていこちらのほうが有利です。通常の prompt だと “add alt text” や “ensure keyboard navigation” のような一般論に寄りがちです。accessibility-compliance skill は、リポジトリ内の参照情報に沿って、WCAG 2.2、ARIA パターン、モバイルアクセシビリティの観点に出力を留めやすいのが強みです。

自動アクセシビリティテストの代わりになりますか？

いいえ。これは automated tool や manual review を補完するものです。静的ツールが見落としやすいフォーカス管理、読み上げタイミング、モバイル操作の細部などについて、問題の解釈、修正案の提示、コンポーネント挙動のレビューに使うのが適しています。

accessibility-compliance を使わないほうがいいのはどんなときですか？

次のような場合は別手段を選ぶべきです。

• legal advice や認証判断が必要なとき
• コードベース全体を完全自動でスキャンしたいとき
• 参照パターンを超える深い native mobile platform 固有対応が必要なとき
• アクセシビリティ以外の UX critique が目的のとき

これはガイダンス用のスキルであり、コンプライアンス保証そのものではありません。

モバイルアクセシビリティにも十分対応していますか？

AI skill としては、比較的しっかりしています。専用の mobile-accessibility.md で、touch target のサイズ、spacing、iOS / Android におけるスクリーンリーダー配慮が扱われています。そのため、desktop web だけを前提にしたアクセシビリティ prompt より、モバイルレビュー用途でも信頼しやすいです。

design system の作業にも使えますか？

はい。再利用コンポーネントのアクセシブルなデフォルトを定義する用途に向いています。特に、semantics、keyboard handling、ARIA state、focus management を複数プロダクトで一貫させたい場面で有効です。

accessibility-compliance スキルを改善するには

要約ではなく実物の artifact を渡す

accessibility-compliance の結果を最も手早く改善する方法は、実際の JSX、HTML、React Native code、注釈付き screenshot、または操作手順を段階的に渡すことです。曖昧なプロダクト要約だけでは、focus order、labels、announcements をこのスキルは安定して推定できません。

recommendations だけでなく issue mapping を求める

より強い依頼の形は次のとおりです。

• “List each issue, affected users, violated principle or criterion, and exact fix.”

こう依頼すると、監査可能なアウトプットになりやすくなります。この構造がないと、回答は一般的なアドバイスに流れがちです。

どこまで変更してよいかを明示する

アクセシビリティ修正は、design system 上の制約とのトレードオフになりやすいものです。エージェントが次のどこまで許されるかを、あらかじめ伝えてください。

• markup のみ変更可能
• ARIA は必要な場合のみ追加可能
• component hierarchy の再構成が可能
• わかりやすさのため copy の修正が可能
• 現行デザインがアクセシブルでない場合は interaction pattern の変更も可能

これは多くのユーザーが思う以上に、結果の質を左右します。

よくある失敗: ARIA の使いすぎ

アクセシビリティ対応で起きやすい問題の 1 つが、native HTML で十分な場面でも ARIA を足しすぎることです。出力を改善したいなら、次を明示してください。

• “Prefer native semantic elements and only use ARIA when native semantics are insufficient.”

この指示はリポジトリの ARIA リファレンスとも整合しており、質の低い修正案を減らせます。

よくある失敗: 状態変化の見落とし

初回の回答では、labels や focus は拾えても、動的な振る舞いを落とすことがよくあります。次の点は明示的に確認させてください。

• focus の侵入と復帰
• expanded / collapsed state の読み上げ
• validation error の関連付け
• live regions を使った非同期 status messaging
• relevant な場合の reduced motion と high contrast への配慮

こうした観点を入れると、accessibility-compliance guide の実用性は大きく上がります。

初回回答のあとに反復する

最初の監査のあと、次のような追い依頼が有効です。

• “Rewrite the component with the fixes applied.”
• “Prioritize only release-blocking issues.”
• “Convert this into QA test steps.”
• “Explain what should be tested with screen readers.”
• “Separate WCAG AA requirements from nice-to-have AAA improvements.”

これにより、このスキルは単なる reviewer ではなく、実際のデリバリー支援として機能します。

リポジトリの references は必要なものだけ読む

最初からリポジトリ全体を読む必要はありません。課題に応じて、次のように当たりを付けるのが効率的です。

• semantic structure や conformance target が論点なら: references/wcag-guidelines.md
• widget behavior や roles が論点なら: references/aria-patterns.md
• touch targets や mobile AT が論点なら: references/mobile-accessibility.md

この読み分けをすると、accessibility-compliance install 後の立ち上がりも採用判断も速くなります。

rationale を求めて信頼性を高める

各修正について、キーボード利用者、スクリーンリーダー利用者、ロービジョンの利用者、モーションに敏感な利用者にとってなぜ重要かを説明させてください。これにより表面的な修正を見抜きやすくなり、レビュー時に実装工数を正当化しやすくなります。

本番投入しやすい出力を得る最善の方法

価値の高い accessibility-compliance usage を得るなら、次の要素を 1 回でまとめて要求するのが最も効果的です。

• 優先度付き findings
• 修正済み code
• rationale
• manual verification checklist
• 残っているリスクや前提条件

多くのチームが実際に必要としているのは、「アクセシビリティを改善したい」で止まらず、「今すぐ実装して検証できる」状態に進めるこの一式です。