Hig Compliance

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原則に基づくシステム横断の振る舞い・用語・構造の一貫性 → システムレベル

前提条件

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に統一」と断言する
• 判断に迷う場合のみユーザーに選択肢を提示する

使い方

/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

他スキルとの連携

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

ワークフロー

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

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

1.1 現状の用語収集

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

1.2 用語の標準化

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

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

1.3 docs/ui-glossary.md 出力

# 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」セクションに基づく。

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

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

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

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

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

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

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

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

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

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

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

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

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

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

Phase 3: 一貫性分析

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

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

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

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

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

3.3 UX状態実装マトリクス

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

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

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

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

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

自動補正（--fix）

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

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

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

自動補正の安全基準:

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

出力契約

レポート出力仕様

重要度定義

指摘記述フォーマット

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

レポートフォーマット

# 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 によるプッシュ