| name | add-component-a11y-content |
| description | smarthr-design-system のコンポーネントページ向けのアクセシビリティコンテンツを作成・更新する。 対象コンポーネントの用途、実装例、デザインパターン、既存のアクセシビリティコンテンツを確認し、 一貫した構成と記述スタイルでアクセシビリティセクションを生成する。 「アクセシビリティコンテンツを追加して」「a11yセクションを作成して」 「コンポーネントページにアクセシビリティ情報を追加して」等の依頼に対応する。 |
| globs | ["src/content/articles/products/components/**/index.mdx"] |
コンポーネントページ アクセシビリティコンテンツ作成 SKILL
目的
smarthr-design-system のコンポーネントページ向けのアクセシビリティコンテンツを作成する。
目的は実装者がアクセシブルな実装を行うために必要な情報を提供することであり、アクセシビリティ教育やWCAG解説ではない。
コンポーネントページはアクセシビリティガイドラインではなく、コンポーネントの利用方法を説明する実装ガイドとして扱う。
情報収集戦略
1. 対象コンポーネントページ（全文）
src/content/articles/products/components/{コンポーネント名}/index.mdx
2. 既存スタイル参照（Button, Table の2件、各50行以内）
ButtonとTableのアクセシビリティセクションのみ参照。
start=$(grep -n "^## アクセシビリティ" src/content/articles/products/components/button/index.mdx | cut -d: -f1)
sed -n "${start},$((start+49))p" src/content/articles/products/components/button/index.mdx
start=$(grep -n "^## アクセシビリティ" src/content/articles/products/components/table/index.mdx | cut -d: -f1)
sed -n "${start},$((start+49))p" src/content/articles/products/components/table/index.mdx
3. コンポーネント実装（必要時のみ）
以下が不明な場合のみWebFetch:
- propsの役割（特にtype, aria-*関連）
- ARIA属性の使用パターン
- tabIndex、フォーカス管理
https://github.com/kufu/smarthr-ui/blob/master/packages/smarthr-ui/src/components/{コンポーネント名}/{コンポーネント名}.tsx
WebFetch prompt例: 「type propsの役割、ARIA属性、tabIndex/フォーカス管理の実装を抽出（実装コード不要、動作のみ）」
4. 関連ガイドライン（タイトル確認のみ）
find src/content/articles/accessibility -name "*.mdx" | grep -E "(accessible-name|keyboard|label|hover|focus)"
本文は全文読まず、各ファイルのタイトル（frontmatter の title）や見出し（h1/h2）だけ確認してリンクを生成。
読まない情報
- ❌ Storybook
- ❌ デザインパターン全文
- ❌ アクセシビリティガイドライン本文
コンテンツ追加条件
以下のいずれかに該当する場合のみ追加:
- 標準機能がある
- 追加実装が必要
- 実装ミスが発生しやすい
- 推奨パターンがある
記載内容
基本的なアクセシビリティ機能
コンポーネントが標準で提供する機能。
開発時の考慮点
利用者が追加で対応する必要がある内容。実装ミス、推奨パターンを含む。
記載しない内容
- WCAG、一般論、HTML/ARIA解説
- 他コンポーネント共通の内容
- ガイドライン重複内容
- コンポーネントページの他セクションで既に説明されている内容
- 「使用上の注意」「レイアウト」「デザインパターン」などで説明済みの内容は繰り返さない
- アクセシビリティ固有の観点のみを記載する
既存コンテンツとの重複チェック
アクセシビリティコンテンツを生成する前に、対象コンポーネントページの以下を確認：
- 使用上の注意
- レイアウト
- デザインパターン
- ライティング
これらのセクションで既に説明されている内容は、アクセシビリティセクションで繰り返さない。
アクセシビリティ固有の観点（スクリーンリーダー対応、キーボード操作、ARIA属性など）のみを記載する。
記載の根拠
実装または仕様で確認できた内容のみ記載（推測禁止）。
ライティングルール
- 見出しは実装者が行うアクションを書く
- 1見出し1ルールにする
- 「何をするべきか」→「なぜ必要か」の順で説明する
- 抽象的な表現を避ける
- ARIA属性やHTML属性の説明から始めない
- コンポーネント中心で説明する
実装例
実装例は以下のいずれかに該当する場合のみ追加する。
- 実装ミスが発生しやすい
- 推奨パターンが分かりにくい
- コード例があると理解しやすい
上記に該当しない場合は追加しない。
説明はコンセプトや判断基準を中心に記載し、実装例は理解を補助するために必要な場合のみ提供する。
実装例作成ルール
- SmartHR UI のコンポーネントを優先して使用する
- 関連するコンポーネントページおよびデザインパターンを確認し、推奨されている利用方法に従う
- SmartHR UI に同等のコンポーネントやパターンが存在する場合は独自実装を提案しない
- 独自実装が必要な場合は理由を明示する
- 良い実装例・悪い実装例は、実装ミスや推奨パターンを説明するために有効な場合のみ追加する
- コード例よりも判断基準や考え方の説明を優先する
Live Editorの使用基準
以下のいずれかに該当する場合は、良い実装例と悪い実装例の両方に editable 属性を追加する。
Live Editorを使用する場合：
- スクリーンリーダーで実際の読み上げを確認すると理解しやすい
- 例：
aria-label, aria-describedby, type="label" vs type="description" の違い
- DOM構造を開発者ツールで確認すると理解しやすい
- 例：ARIA属性の付与、フォーカス可能要素の有無、セマンティックHTML
- キーボード操作を実際に試すと理解しやすい
- アクセシビリティツリーで確認すると理解しやすい
Live Editorを使用しない場合：
- 静的なコード例で十分理解できる
- 視覚的な違いのみを示す場合
- 実行する必要がない（コードの書き方のみを示す）
重要：良い実装例と悪い実装例で統一する
- 両方とも
editable noIframe にする、または両方とも通常のコードブロックにする
- 片方だけ
editable にしない
記述形式：
DOM確認が有効な場合（両方ともeditable）：
良い実装例
<Tooltip message="追加" type="label">
<Button>
<FaCirclePlusIcon />
</Button>
</Tooltip>
悪い実装例
<Tooltip message="追加">
<Button>
<FaCirclePlusIcon />
</Button>
</Tooltip>
静的な説明で十分な場合（両方とも通常のコードブロック）：
良い実装例
<Button variant="tertiary" prefix={<FaCirclePlusIcon />}>項目を追加</Button>
悪い実装例
<Button variant="tertiary">項目を追加</Button>
noIframe属性について：
editable noIframe：コードと実行結果を同一画面で表示- DOM構造やアクセシビリティツリーを開発者ツールで確認する場合に推奨
- iframe分離がないため、スクリーンリーダーでの確認も容易
関連ページ
関連ページには、コンポーネントを利用する際に参考になるアクセシビリティコンテンツを追加する。
参照先:
/accessibility/**
より詳細な説明や判断基準が存在する場合のみ追加する。
以下の場合は追加しない。
- 本文で十分説明している
- コンポーネントとの関連性が低い
- 同じ内容を繰り返すだけになる
リンク先の見出しをそのまま利用し、独自に言い換えない。
リンク先のカテゴリ名を利用すること。
例:
記載形式:
- [{項目見出し} | アクセシビリティガイドライン]({link})
- [{項目見出し} | 弱視・ロービジョンのユーザビリティチェックリスト]({link})
出力形式
## アクセシビリティ
### 基本的なアクセシビリティ機能
- xxx
### 開発時の考慮点
#### xxxする
何をするべきか。
なぜ必要か。
### 関連ページ
- [{項目見出し} | アクセシビリティガイドライン]({link})
- [{項目見出し} | 弱視・ロービジョンのユーザビリティチェックリスト]({link})
出力前チェック
- コンポーネント固有の内容になっているか
- 一般論になっていないか
- 実装者が行うアクションになっているか
- 1見出し1ルールになっているか
- 推測を書いていないか
- 関連ページが重複していないか
- 本当にアクセシビリティセクションが必要か
- 既存コンテンツとの記述スタイルが揃っているか
- コンポーネントページ・既存アクセシビリティコンテンツ・デザインパターンを確認したか
実行手順
- 対象コンポーネントページ全文を Read
- Button, Table のアクセシビリティセクションのみ Read（各50行以内）
- 必要時のみ実装を WebFetch（propsやARIA属性が不明な場合）
- 関連ガイドラインを検索（本文は読まない）
- コンテンツを生成して Edit
