hig-compliance

name	hig-compliance
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 指示>
allowed-tools	Read, Glob, Grep, Edit, Write, Bash(git *), Agent, WebSearch, WebFetch
context	main

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

---

使い方

/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 出力

テンプレート(ボタンラベル/ページタイトル/アイコン/通知メッセージの4標準表)は references/ui-glossary-template.md を参照。

---

Phase 2: HIG準拠チェック(8カテゴリ)

references/hig-check-categories.md に定義された8カテゴリ(A: ボタン・アクション / B: アイコン / C: ナビゲーション / D: フォーム・入力 / E: フィードバック・状態表示 / F: タイポグラフィ / G: レイアウト・構造 / H: アクセシビリティ)をサブエージェントで並行スキャンする。各カテゴリのチェック項目・検出方法・HIG根拠は参照ファイルを参照。

---

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: 不整合の分類と優先度

分類	基準	優先度	自動修正
キャプション不一致	同一操作で異なるラベル	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	改善余地のある箇所	文体の微差、レイアウトの軽微な差異

指摘記述フォーマット

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

PASS条件: 全 MUST 指摘に統一案が付いている / --fix 実行時は修正後にテストが通っている / 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 | — |
|  |  | — |

---

用語集のメンテナンス

• 初回: 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 によるプッシュ

関連参照(必要に応じて Claude が load)

@.claude/quality-gates.md @.claude/pitfalls.md