---
name: hig-compliance
version: 1.0.0
description: >
  This skill should be used when the user asks to "check HIG compliance", "unify button labels", "fix icon consistency",
  or mentions "HIG準拠", "UI一貫性", "ボタン統一", "アイコン統一", "用語統一", "画面間の整合性", "横断UIチェック".
  Apple Human Interface Guidelines (HIG) based system-wide UI consistency check and correction.
  Takes optional argument: /hig-compliance <target-directory or instruction>
argument-hint: "<対象ディレクトリ or 指示>"
---

# HIG Compliance — Apple Human Interface Guidelines 準拠チェック・補正

Apple Human Interface Guidelines（https://developer.apple.com/jp/design/human-interface-guidelines/）
を権威ある基準として、**システム全体のUIの一貫性・完全性を横断的にチェックし、補正する**スキル。

Agent Team による並行実装で発生しがちな「画面ごとの微妙なずれ」を検出・修正することに特化する。

> **既存スキルとの棲み分け**:
> - `design-system-audit`: デザイントークン（数値体系）の整合性 → **数値レベル**
> - `ui-ux-design`: 個別画面のUI設計・レビュー・実装 → **画面レベル**
> - `hig-compliance`（本スキル）: HIG原則に基づくシステム横断の振る舞い・用語・構造の一貫性 → **システムレベル**

---

## 前提条件

| 参照ファイル | 用途 | フォールバック |
| ------------ | ---- | -------------- |
| `docs/development-patterns.md` | デザインシステム・UI規約 | `project-config.md` §7 を直接参照 |
| Apple HIG（公式URL） | UIガイドライン基準 | WebFetch で直接参照 |

### Apple HIG の参照方法

1. **WebFetch** で `https://developer.apple.com/jp/design/human-interface-guidelines/` を直接参照する
2. 該当カテゴリのページを必要に応じて個別に取得する（ボタン、ナビゲーション、アイコン等）
3. プロジェクトの `docs/development-patterns.md` に HIG ベースのルールが記載されていればそちらを優先する

---

## 基本姿勢

- **Apple HIG を第一基準とする** — 迷ったらHIGに立ち返る
- **システム全体の一貫性を最優先する** — 個別画面の「良さ」よりシステム全体の統一を重視する
- **ずれの検出は機械的・網羅的に行う** — 目視では見落とす微差こそ本スキルの対象
- **修正案は具体的かつ1つに絞る** — 「AかBか」ではなく「Aに統一」と断言する
- 判断に迷う場合のみユーザーに選択肢を提示する

---

## 使い方

```text
/hig-compliance                           # src/ 全体をチェック
/hig-compliance src/features/             # 特定ディレクトリのみ
/hig-compliance --fix                     # チェック + 自動補正
/hig-compliance --fix src/features/       # 特定ディレクトリ + 自動補正
/hig-compliance --glossary                # UI用語集の生成・更新のみ
```

### 出力先

- チェックレポート: `output/reports/review/HIG_COMPLIANCE_{YYYYMMDD}.md`
- UI用語集（生成時）: `docs/ui-glossary.md`

### 他スキルとの連携

| 前工程 | 本スキル | 後工程 |
| ------ | -------- | ------ |
| `/implementing-features` `/ui-ux-design` | `/hig-compliance` | `/code-review` `/e2e-testing` |
| `/design-system-audit` | `/hig-compliance` | — |

**推奨フロー**: 実装完了 → `design-system-audit`（トークン整合性）→ `hig-compliance`（HIG準拠・一貫性）→ `code-review`

---

## ワークフロー

### Phase 1: UI用語集の確立（初回 or `--glossary` 時）

プロジェクト全体で使用するUI用語を統一するための用語集を生成する。
`docs/ui-glossary.md` が存在しない場合、または `--glossary` 指定時に実行。

**1.1 現状の用語収集**

以下をサブエージェントで並行スキャンする:

| スキャン対象 | 手法 | 収集内容 |
| ------------ | ---- | -------- |
| ボタンラベル | Grep で `>保存<` `>キャンセル<` `label=` `title=` `aria-label=` 等を収集 | 全ボタンのキャプション一覧 |
| ページタイトル | Grep で `<h1` `<title` `PageTitle` `Header` コンポーネントを収集 | 全画面タイトル一覧 |
| ナビゲーション | Grep でメニュー・タブ・ブレッドクラムのラベルを収集 | ナビゲーション項目一覧 |
| フォームラベル | Grep で `<label` `placeholder=` を収集 | フォーム項目一覧 |
| アラート・通知 | Grep で `toast` `alert` `confirm` `dialog` のメッセージを収集 | 通知メッセージ一覧 |
| 空状態 | Grep で `empty` `no-data` `EmptyState` を収集 | 空状態メッセージ一覧 |

**1.2 用語の標準化**

HIG の原則に基づいて用語を標準化する:

- **動詞の統一**: 「保存」「セーブ」「保管」→ 1つに統一
- **キャンセル系の統一**: 「キャンセル」「取消」「戻る」「閉じる」→ 文脈に応じて使い分けルールを定義
- **確認系の統一**: 「OK」「確認」「はい」「了解」→ HIG準拠の推奨表現に統一
- **破壊的操作**: 「削除」「消去」「除去」→ HIG に従い動詞で明示（「〜を削除」）

**1.3 `docs/ui-glossary.md` 出力**

```markdown
# UI用語集

## ボタンラベル標準

| 操作 | 標準ラベル | NG例 | HIG根拠 |
| ---- | ---------- | ---- | -------- |
| 新規作成 | 作成 | 新規、追加、新しく作る | Buttons: 簡潔で動作を示す動詞 |
| 保存 | 保存 | セーブ、保管、OK | Buttons: 具体的な動詞を使う |
| 削除 | 削除 | 消す、除去、消去 | Buttons: 破壊的操作は明確に |
| 取消 | キャンセル | 取消、やめる、戻る | Buttons: 「キャンセル」を標準とする |
| 確認 | [具体的な動詞] | OK、はい、確認 | Buttons: 「OK」より具体的な動詞を推奨 |

## ページタイトル標準

| パターン | 形式 | 例 |
| -------- | ---- | -- |
| 一覧画面 | [名詞]一覧 or [名詞] | ユーザー一覧 |
| 詳細画面 | [名詞]詳細 or [名詞名] | ユーザー詳細 |
| 作成画面 | [名詞]を作成 | ユーザーを作成 |
| 編集画面 | [名詞]を編集 | ユーザーを編集 |
| 設定画面 | 設定 or [カテゴリ]設定 | 通知設定 |

## アイコン使用標準

| 操作 | 標準アイコン | 必須/推奨 |
| ---- | ------------ | --------- |
| 追加 | Plus / PlusCircle | 推奨 |
| 削除 | Trash2 | 必須 |
| 編集 | Pencil / Edit | 推奨 |
| 検索 | Search | 必須 |
| 設定 | Settings / Gear | 必須 |
| 戻る | ArrowLeft / ChevronLeft | 必須 |
| 閉じる | X | 必須 |
| メニュー | Menu / MoreHorizontal / MoreVertical | 必須 |
| フィルタ | Filter / SlidersHorizontal | 推奨 |
| ソート | ArrowUpDown | 推奨 |

## 通知メッセージ標準

| 種別 | 形式 | 例 |
| ---- | ---- | -- |
| 成功 | 「[名詞]を[動詞]しました」 | ユーザーを作成しました |
| エラー | 「[名詞]の[動詞]に失敗しました」 | ユーザーの作成に失敗しました |
| 確認 | 「[名詞]を[動詞]しますか？」 | このユーザーを削除しますか？ |
| 警告 | 「[影響の説明]。[動詞]しますか？」 | この操作は取り消せません。削除しますか？ |
```

---

### Phase 2: HIG準拠チェック（8カテゴリ）

以下のカテゴリを**サブエージェントで並行スキャン**する。

#### カテゴリ A: ボタン・アクションの一貫性

HIGの「Buttons」「Menus」「Toggles」セクションに基づく。

| チェック項目 | 検出方法 | HIG根拠 |
| ------------ | -------- | -------- |
| 同一操作のキャプションが画面間で異なる | 用語集と照合 | 「一貫性のある用語を使う」 |
| 破壊的ボタンに警告スタイルが適用されていない | `variant="destructive"` `color="error"` 等の有無 | 「破壊的アクションは視覚的に区別する」 |
| 確認ダイアログで「OK」が使われている | Grep で `>OK<` `"OK"` | 「具体的な動詞を使用する」 |
| ボタンの配置順序が画面間で異なる | 主アクション/副アクションの左右位置 | 「主アクションは一貫した位置に配置」 |
| アイコンのみのボタンにラベルがない | `aria-label` `title` の有無 | 「アクセシビリティ」 |

#### カテゴリ B: アイコンの完全性・一貫性

HIGの「Icons」「SF Symbols」セクションに基づく。

| チェック項目 | 検出方法 | HIG根拠 |
| ------------ | -------- | -------- |
| 同一操作に異なるアイコンが使用されている | アイコンimport一覧と操作の対応を分析 | 「同じ概念には同じアイコンを使う」 |
| アイコンが設定されるべき箇所に欠落している | 用語集のアイコン標準と照合 | 「一貫性」 |
| アイコンサイズが画面間で異なる | `size=` `width=` `height=` `className` の値を比較 | 「視覚的な一貫性」 |
| テキストとアイコンの組み合わせが不統一 | ボタン内の `<Icon>` + テキストパターンを比較 | 「テキストとアイコンの関係性」 |

#### カテゴリ C: ナビゲーション・画面遷移の一貫性

HIGの「Navigation bars」「Tab bars」「Sidebars」セクションに基づく。

| チェック項目 | 検出方法 | HIG根拠 |
| ------------ | -------- | -------- |
| 戻るボタンのスタイル・位置が画面間で異なる | ナビゲーションコンポーネントの実装比較 | 「予測可能なナビゲーション」 |
| パンくずリストの有無が画面間で不統一 | Breadcrumb コンポーネントの使用状況 | 「ユーザーの現在位置を示す」 |
| ページ遷移のアニメーションが不統一 | transition / animation の使用パターン | 「一貫した遷移」 |
| モーダル vs ページ遷移の使い分けが不統一 | Dialog/Sheet の使用基準 | 「モーダルの適切な使用」 |

#### カテゴリ D: フォーム・入力の一貫性

HIGの「Text fields」「Labels」「Entering data」セクションに基づく。

| チェック項目 | 検出方法 | HIG根拠 |
| ------------ | -------- | -------- |
| 同じ種類の入力フィールドのスタイルが異なる | Input / Select / Textarea の variant/size 比較 | 「一貫した入力体験」 |
| プレースホルダーの文体が統一されていない | placeholder テキストの表現パターン | 「ヒントテキストは簡潔に」 |
| バリデーションエラーの表示方法が異なる | エラーメッセージの表示パターン比較 | 「インラインでのフィードバック」 |
| 必須/任意の表示方法が統一されていない | required マーク・ラベルの形式 | 「明確なラベリング」 |
| フォームのレイアウト（縦/横）が不統一 | フォーム構造の比較 | 「予測可能なレイアウト」 |

#### カテゴリ E: フィードバック・状態表示の一貫性

HIGの「Alerts」「Progress indicators」「Status」セクションに基づく。

| チェック項目 | 検出方法 | HIG根拠 |
| ------------ | -------- | -------- |
| ローディング表示の方式が画面間で異なる | Spinner / Skeleton / Progress の使用比較 | 「一貫したフィードバック」 |
| 成功/エラー通知の表示方法が異なる | toast / alert / banner の使い分け比較 | 「フィードバックの一貫性」 |
| 空状態のデザインが画面間で異なるか欠落 | EmptyState コンポーネントの使用比較 | 「コンテンツが無い場合もガイダンスを提供」 |
| 確認ダイアログの構造が画面間で異なる | Dialog 内の構造（タイトル/説明/ボタン）比較 | 「アラートの構造」 |
| エラー画面のデザインが統一されていない | ErrorBoundary / error page の比較 | 「エラー時のガイダンス」 |

#### カテゴリ F: タイポグラフィ・テキストの一貫性

HIGの「Typography」セクションに基づく。

| チェック項目 | 検出方法 | HIG根拠 |
| ------------ | -------- | -------- |
| 見出し階層が画面間で異なる | h1-h6 / text-xl 等の使用パターン比較 | 「明確な情報階層」 |
| 日付・時刻のフォーマットが不統一 | 日付表示パターンの収集・比較 | 「一貫したフォーマット」 |
| 数値のフォーマットが不統一 | 数値表示（カンマ区切り・単位）の比較 | 「一貫したフォーマット」 |
| 文末表現の不統一 | 「〜です」「〜する」等の文体比較 | 「一貫したトーン」 |

#### カテゴリ G: レイアウト・構造の一貫性

HIGの「Layout」「Lists and tables」セクションに基づく。

| チェック項目 | 検出方法 | HIG根拠 |
| ------------ | -------- | -------- |
| 一覧画面のレイアウト（テーブル/カード/リスト）が不統一 | 一覧表示コンポーネントの比較 | 「一貫したコンテンツ表示」 |
| 詳細画面のセクション構造が不統一 | セクション分割パターンの比較 | 「予測可能な構造」 |
| ページヘッダーの構造が不統一 | タイトル+アクションボタンの配置比較 | 「一貫したヘッダー構造」 |
| リストアイテムの構造が不統一 | リスト項目の内部構造比較 | 「一貫したリスト表示」 |

#### カテゴリ H: アクセシビリティの一貫性

HIGの「Accessibility」セクションに基づく。

| チェック項目 | 検出方法 | HIG根拠 |
| ------------ | -------- | -------- |
| フォーカス順序が論理的でない | tabIndex の使用パターン | 「論理的なフォーカス順序」 |
| 画像の alt テキストが欠落している | `<img` `<Image` の alt 属性チェック | 「代替テキスト」 |
| カラーのみで情報を伝えている箇所がある | 色+アイコン/テキストの併用チェック | 「色だけに依存しない」 |
| タッチターゲットが小さすぎる | ボタン/リンクのサイズ確認（44x44pt以上） | 「最小タッチターゲット」 |

---

### Phase 3: 一貫性分析

Phase 2 の収集データを基に、**画面間の差異をマトリクスで可視化**する。

**3.1 ボタンキャプション一貫性マトリクス**

```text
| 操作 | 画面A | 画面B | 画面C | 統一案 | 状態 |
|------|-------|-------|-------|--------|------|
| 保存 | 保存  | セーブ | 保存する | 保存 | NG |
| 削除 | 削除  | 削除  | 消去   | 削除 | NG |
| 戻る | 戻る  | キャンセル | 閉じる | (文脈依存) | 要判断 |
```

**3.2 アイコン使用一貫性マトリクス**

```text
| 操作 | 画面A | 画面B | 画面C | 統一案 | 状態 |
|------|-------|-------|-------|--------|------|
| 編集 | Pencil | Edit2 | — (欠落) | Pencil | NG |
| 削除 | Trash2 | Trash | Trash2 | Trash2 | NG |
| 追加 | Plus  | Plus  | PlusCircle | Plus | NG |
```

**3.3 UX状態実装マトリクス**

```text
| 画面 | ローディング | エラー | 空状態 | 確認ダイアログ |
|------|------------|--------|--------|-------------|
| 画面A | Spinner | toast | ✅ | ✅ |
| 画面B | Skeleton | alert | — | ✅ |
| 画面C | Spinner | toast | ✅ | — |
```

---

### Phase 4: 不整合の分類と優先度

| 分類 | 基準 | 優先度 | 自動修正 |
| ---- | ---- | ------ | -------- |
| **キャプション不一致** | 同一操作で異なるラベル | HIGH | ✅ 可能 |
| **アイコン欠落** | 標準アイコンが設定されるべき箇所に無い | HIGH | ✅ 可能 |
| **アイコン不一致** | 同一操作で異なるアイコン | HIGH | ✅ 可能 |
| **確認ダイアログの「OK」使用** | 具体的動詞に置換すべき | MEDIUM | ✅ 可能 |
| **フィードバック方式の不一致** | toast/alert の混在等 | MEDIUM | ⚠️ 部分的 |
| **空状態の欠落** | 他画面にはある空状態が無い | MEDIUM | ❌ 新規実装 |
| **レイアウトパターンの不一致** | ページヘッダー構造の差異等 | MEDIUM | ⚠️ 部分的 |
| **文体・フォーマットの不一致** | 日付形式、敬体/常体の混在 | LOW | ✅ 可能 |
| **a11y 不備** | alt欠落、タッチターゲット不足 | HIGH | ⚠️ 部分的 |

---

### Phase 5: レポート出力 or 自動補正

#### レポートのみ（デフォルト）

`output/reports/review/HIG_COMPLIANCE_{YYYYMMDD}.md` に出力。

#### 自動補正（`--fix`）

以下の順序で修正を適用する:

1. **キャプション統一**: 用語集に基づき、ボタン/リンクのラベルを一括置換
2. **アイコン統一**: 用語集のアイコン標準に基づき、import とコンポーネントを修正
3. **確認ダイアログ修正**: 用語集で1:1マッピングが定義されている場合のみ「OK」→ 具体的動詞に置換
4. 修正後にビルド・lint・テストを実行して破壊的変更がないことを確認

> **レポートのみ（自動補正対象外）**: アイコン欠落補完（新規要素追加が必要）、フォーマット統一（日付・数値の関数変更は影響範囲が広い）。これらはレポートに記載し人間の判断に委ねる。

**自動補正の安全基準**:
- 用語集で 1:1 マッピングが定義されている変換のみ実行
- 複数候補がある場合はレポートに記載して人間に委ねる
- 修正前後で機能が変わらないことをテストで確認

---

## 出力契約

### レポート出力仕様

| セクション | 必須 | 制約 |
| ---------- | ---- | ---- |
| チェック概要 | ✅ | スキャン範囲・ファイル数・チェック項目数 |
| 用語集との照合結果 | ✅ | 一致率・不一致一覧 |
| カテゴリ別チェック結果 | ✅ | A〜H の各カテゴリ。0件でも見出しは残す |
| 一貫性マトリクス | ✅ | ボタン・アイコン・UX状態の比較表 |
| 不整合一覧 | ✅ | HIGH→MEDIUM→LOW の順 |
| 修正サマリー（`--fix` 時のみ） | 条件付き | 修正ファイル数・修正内容・テスト結果 |
| 推奨アクション | ✅ | 人間の判断が必要な項目 |
| HIG準拠スコア | ✅ | カテゴリ別スコア + 総合スコア |

### 重要度定義

| レベル | 判定基準 | 例 |
| ------ | -------- | -- |
| **MUST** | HIG明示違反、同一操作でのUI矛盾、a11y不備 | 同じ「保存」操作で異なるキャプション、アイコン欠落 |
| **SHOULD** | HIG推奨との乖離、パターン不一致 | ローディング表示の不統一、空状態の欠落 |
| **CONSIDER** | 改善余地のある箇所 | 文体の微差、レイアウトの軽微な差異 |

### 指摘記述フォーマット

```text
- [ ] `ファイルパス:行番号` 指摘内容。**HIG根拠**: 該当ガイドライン。**統一案**: 具体的な修正。**対象画面**: 影響する画面一覧。
```

---

## レポートフォーマット

```markdown
# HIG準拠チェックレポート: {YYYY-MM-DD}

## チェック概要
- スキャン範囲: {src/ 全体 or 特定ディレクトリ}
- スキャン対象ファイル数: X
- 画面（ページ）数: Y
- チェック項目数: Z
- 用語集: {docs/ui-glossary.md を使用 / 新規生成}

## 用語集との照合結果
- ボタンキャプション一致率: X%
- アイコン標準充足率: X%
- 不一致項目数: X

## カテゴリ別チェック結果

### A: ボタン・アクションの一貫性
- [ ] `file:line` 指摘。**HIG根拠**: xxx。**統一案**: yyy。

### B: アイコンの完全性・一貫性
...

### C: ナビゲーション・画面遷移の一貫性
...

### D: フォーム・入力の一貫性
...

### E: フィードバック・状態表示の一貫性
...

### F: タイポグラフィ・テキストの一貫性
...

### G: レイアウト・構造の一貫性
...

### H: アクセシビリティの一貫性
...

## 一貫性マトリクス

### ボタンキャプション
| 操作 | 画面A | 画面B | ... | 統一案 | 状態 |
| ---- | ----- | ----- | --- | ------ | ---- |

### アイコン使用
| 操作 | 画面A | 画面B | ... | 統一案 | 状態 |
| ---- | ----- | ----- | --- | ------ | ---- |

### UX状態実装
| 画面 | ローディング | エラー | 空状態 | 確認ダイアログ |
| ---- | ------------ | ------ | ------ | -------------- |

## 不整合一覧

### MUST（必須修正）
- [ ] ...

### SHOULD（推奨修正）
- [ ] ...

### CONSIDER（検討）
- [ ] ...

## 修正サマリー（--fix 実行時のみ）
- 修正ファイル数: X
- 修正内容:
  - [修正概要]
- ビルド結果: pass / fail
- テスト結果: X passed, Y failed

## 推奨アクション
1. [人間の判断が必要な項目]

## HIG準拠スコア
| カテゴリ | スコア | 評価 |
| -------- | ------ | ---- |
| A: ボタン・アクション | X/100 | — |
| B: アイコン | X/100 | — |
| C: ナビゲーション | X/100 | — |
| D: フォーム・入力 | X/100 | — |
| E: フィードバック | X/100 | — |
| F: タイポグラフィ | X/100 | — |
| G: レイアウト・構造 | X/100 | — |
| H: アクセシビリティ | X/100 | — |
| **総合** | **X/100** | — |
```

---

## 用語集のメンテナンス

- **初回**: Phase 1 で自動生成 → ユーザーレビュー → `docs/ui-glossary.md` に保存
- **更新**: `/hig-compliance --glossary` で再スキャン・差分表示
- **実装時参照**: `/implementing-features` 実行時に `docs/ui-glossary.md` を参照させることで、新規画面でもずれを防止

### 用語集を他スキルに連携する方法

`docs/ui-glossary.md` が存在する場合、以下のスキルが自動参照する:
- `/implementing-features`: 新規UI実装時にキャプション・アイコンを用語集に準拠
- `/ui-ux-design`: レビュー時に用語集との照合をチェック項目に追加
- `/code-review`: UI変更を含むレビュー時に用語集準拠を確認

> **連携の前提**: 上記スキルの「デザインシステム確認」ステップで `docs/ui-glossary.md` を読み込むよう、
> `docs/development-patterns.md` のデザインシステムセクションに用語集への参照を記載すること。

---

## 禁止事項

- 用語集に定義されていない独自のキャプション・ラベルの追加
- HIG の原則に反するUI変更
- アイコンの恣意的な変更（用語集の標準に従う）
- `--no-verify` によるフック迂回
- `--force` によるプッシュ