apple-design

Apple デザインシステムとヒューマンインターフェイスガイドライン（HIG）

このスキルは、iOS、iPadOS、macOS、watchOS、visionOS、および最新の Apple 品質の Web UI において、**Apple のヒューマンインターフェイスガイドライン（HIG）**で定義されている正確な原則、視覚仕様、コンポーネントアーキテクチャ、タイポグラフィの指標、カラートークン、モーションカーブ、自動コンプライアンス監査を、AI コーディングエージェントに提供します。

---

🎯 運用モード

モード 1 — ゼロからデザインして構築する

Apple スタイルの新しい画面、アプリ、Web インターフェイスの作成を依頼された場合：

1. プラットフォーム標準のナビゲーション方式を選択します（例：iOS のボトムタブバー、macOS／iPad のサイドバー、visionOS のオーナメント）。
2. 8pt の空間グリッドと連続したスクワークル曲率（G2 continuity）を設定します。
3. 光学的なトラッキング規則に従って、SF Pro／New York のタイポグラフィスケールを適用します。
4. セマンティックなダイナミックカラー（ライトモードと OLED ダークモード）と Liquid のすりガラス素材を実装します。
5. Apple のスプリング物理特性（cubic-bezier(0.25, 1, 0.5, 1)）と触覚的なアクティブフィードバック（scale(0.97)）を適用します。

モード 2 — Apple HIG 準拠監査とスコアリング

既存のコードベース、モックアップ、コンポーネントをレビューする場合：

1. 監査ツール node skills/apple-design/scripts/audit-apple-design.mjs を実行し、0〜100 の採点基準による自動静的スキャンを行います。
2. WCAG のコントラストを正確に数値で検証し、44×44pt のタッチターゲットを検証します。
3. 5 つの中核的な柱に沿って、**Apple HIG 監査スコアカード**に記入します。
4. 確度タグを付けて、優先順位を付けた指摘事項を提示します：
   • 🟢 ツールで検証済み：CLI ツールで統計的に測定済み（例：コントラスト比、ボタンの寸法、静的 CSS ルール）。
   • 🟡 デバイスでのテストが必要：ハードウェアを使った操作が必要（例：300% のダイナミックタイプ、「透明度を下げる」の切り替え、VoiceOver の読み上げ階層）。
   • 🔴 推定：状況に応じたデザイン上のトレードオフ、または主観的な美的評価。

---

🛠️ Apple HIG 準拠 CLI エンジン

組み込みの監査エンジン（skills/apple-design/scripts/audit-apple-design.mjs）には、4 つのサブコマンドがあります：

# 1. Full Codebase Static Scan with 0-100 Scorecard (Default)
npm run audit
# or: node skills/apple-design/scripts/audit-apple-design.mjs [path]

# 2. WCAG Relative Luminance Contrast Ratio Check
node skills/apple-design/scripts/audit-apple-design.mjs contrast "#8E8E93" "#FFFFFF"
# -> Contrast Ratio: 3.26:1 [🔴 FAILED - Needs >= 4.5:1]

# 3. Tap Target Sizing Validation (44x44 pt minimum)
node skills/apple-design/scripts/audit-apple-design.mjs target 32 32
# -> Tap Target: 32x32 pt [🔴 FAILED - Minimum 44x44 pt]

# 4. Batch JSON Automated Verification
node skills/apple-design/scripts/audit-apple-design.mjs batch audit.json

監査の採点基準：

• 基本スコア：100 点。
• 減点：違反 1 件につき -10 点。
• スコアカードの分類：
  • 🟢 90〜100 点：リリース可能 — 優れた基準を満たしています。
  • 🟡 70〜89 点：リリース前に修正が必要 — App Store／本番環境に出す前に修正が必要です。
  • 🔴 70 点未満：体系的な再設計が必要 — アーキテクチャまたはアクセシビリティに重大な違反があります。

---

1. デザインの基本理念

Apple のインターフェイスは、次の 3 つの主要な柱に基づいて構築されています。

1. 明瞭さ：

   • テキストはあらゆるサイズで読みやすく、アイコンは正確で見分けやすく、誰にでも理解できるものです。
   • 装飾は控えめで、目的に沿っています。コンテンツは常に、装飾的な UI より視覚的に優先されます。
   • ネガティブスペース（余白）はゆとりを生み、視覚的な階層を明確にします。

2. コンテンツ優先：

   • 流れるようなモーション、半透明の素材、鮮明なタイポグラフィが、コンテンツと競合することなく、その魅力を高めます。
   • 背景はコンテンツを引き立て、ユーザーが主要なタスクに集中しているときは UI が控えめになります。

3. 奥行き：

   • 明確な視覚レイヤー、リアルな照明、鏡面ハイライト、物理的なスプリング特性によって、空間的な階層と触覚的なリアリティを表現します。
   • 高さや素材によって、強いドロップシャドウや刺激の強い輪郭線を使わずに、操作できる要素であることを伝えます。

---

2. Apple デザインの普遍的な理念と重要なルール

🚫 禁止するアンチパターン（絶対に避けること）

• ダークテーマで紫・バイオレットを使わない：ダーク背景に紫色のフォントやバイオレットのアクセントボタンを使用しないでください。Apple System Blue（#0A84FF）またはセマンティックなシステムカラーを使用してください。
• 強いドロップシャドウを使わない：拡散されていない濃い黒のボックスシャドウ（box-shadow: 0 4px 10px rgba(0,0,0,0.5)）を使用しないでください。複数レイヤーのアンビエントな拡散（box-shadow: 0 8px 24px rgba(0, 0, 0, 0.08), 0 1px 2px rgba(0, 0, 0, 0.04)）を使用してください。
• 鋭角・幾何学的な角を使わない：インタラクティブなコントロール、カード、入力欄の角丸を0pxにしたり、不規則で連続性のない角にしたりしないでください。
• サイズを調整していない大きなタイポグラフィを使わない：文字間隔を詰めず（-0.02em～-0.03em／-0.5px～-1.2px）に、大きな見出し（>24px）を表示しないでください。
• 標準外のタッチターゲットを使わない：クリック可能な要素を、44×44 pt（iOS 標準）または28×28 pt（macOS のコンパクトポインター）より小さくしないでください。
• 単純な静的 CSS トランジションを使わない：物理的な UI インタラクションにease-in-outを使用しないでください。常に滑らかなスプリング物理または Apple のイージングカーブを使用してください。

---

3. ビジュアルの基礎

A. タイポグラフィシステム（San Francisco と New York）

• 主要なインターフェイスフォント：SF Pro（-apple-system, BlinkMacSystemFont, "SF Pro Display", "SF Pro Text", "Helvetica Neue", sans-serif）
• 等幅フォント：SF Mono（ui-monospace, "SF Mono", Menlo, Monaco, Consolas, monospace）
• セリフフォント：New York（"New York", ui-serif, Georgia, Cambria, serif）

タイポグラフィのスケールとオプティカルサイズのルール：

スタイル	サイズ（pt/px）	ウェイト	行の高さ	トラッキング／文字間隔
大見出し	34px	Bold (700)	41px	-0.022em (-0.75px)
タイトル 1	28px	Bold / SemiBold	34px	-0.020em (-0.56px)
タイトル 2	22px	Bold / SemiBold	28px	-0.018em (-0.40px)
タイトル 3	20px	SemiBold (600)	25px	-0.015em (-0.30px)
ヘッドライン	17px	SemiBold (600)	22px	-0.012em (-0.20px)
本文	17px	Regular (400)	22px	-0.010em (-0.17px)
コールアウト	16px	Regular (400)	21px	-0.008em (-0.13px)
サブヘッドライン	15px	Regular (400)	20px	-0.005em (-0.08px)
脚注	13px	Regular (400)	18px	0.000em (0.00px)
キャプション 1	12px	Regular (400)	16px	0.005em (+0.06px)
キャプション 2	11px	Regular / Medium	13px	0.010em (+0.11px)

---

4. マテリアル、半透明効果、スペキュラーガラス

Apple のマテリアルは、鮮やかさを保ちながら視覚的な奥行きを生み出すため、背後のコンテンツをぼかします。

/* Authentic Apple Ultra-Thin Frosted Glass Material */
.apple-material-ultrathin {
  background: rgba(255, 255, 255, 0.72);
  backdrop-filter: blur(20px) saturate(190%);
  -webkit-backdrop-filter: blur(20px) saturate(190%);
  border: 1px solid rgba(255, 255, 255, 0.45);
  box-shadow: 0 4px 20px rgba(0, 0, 0, 0.04), 0 1px 2px rgba(0, 0, 0, 0.02);
}

@media (prefers-color-scheme: dark), [data-theme="dark"] {
  .apple-material-ultrathin {
    background: rgba(28, 28, 30, 0.75);
    backdrop-filter: blur(25px) saturate(190%);
    -webkit-backdrop-filter: blur(25px) saturate(190%);
    border: 1px solid rgba(255, 255, 255, 0.12);
    box-shadow: 0 8px 32px rgba(0, 0, 0, 0.35), 0 1px 3px rgba(255, 255, 255, 0.05) inset;
  }
}

---

5. アニメーションの物理特性（Apple のスプリングカーブ）

インタラクティブな UI に線形または標準的なイージングカーブを使用しないでください。本格的な Apple のスプリング物理を使用してください。

スプリングパラメーターのリファレンス：

• インタラクション／タップのフィードバック：mass: 1, stiffness: 350, damping: 35（CSS の近似値：cubic-bezier(0.25, 1, 0.5, 1)）
• シート表示／モーダルのスライド：mass: 1.2, stiffness: 280, damping: 28（CSS の近似値：cubic-bezier(0.32, 0.72, 0, 1)）
• 素早いスイッチ／トグル：mass: 0.8, stiffness: 450, damping: 30

/* Apple Native Motion Classes */
.apple-spring-interactive {
  transition: transform 0.35s cubic-bezier(0.25, 1, 0.5, 1),
              opacity 0.25s ease;
}

.apple-spring-interactive:active {
  transform: scale(0.965);
}

---

6. 同梱リソースと Apple HIG の全ライブラリ

• Apple HIG ドキュメント総合カタログ（skills/apple-design/references/INDEX.md）：全 172 件のガイドライン項目を検索できる完全なインデックスです。
• Apple HIG 監査スコアカードのテンプレート：標準的な 5 つの柱による評価スコアカードです。
• アセットとプリセット：
  • skills/apple-design/assets/apple-tokens.css：デザイン用 CSS 変数トークンをすべて含むスタイルシートです。
  • skills/apple-design/assets/apple-components.css：すぐに使える CSS コンポーネント（ボタン、Glass カード、セグメントコントロール、シート）です。
  • skills/apple-design/assets/tailwind.preset.apple.js：Tailwind 設定用プリセットです。
  • skills/apple-design/assets/swiftui-cheat-sheet.md：SwiftUI の慣用的なパターンをまとめた資料です。
• CLI 自動化ツール：
  • npm run audit：コードベースをスキャンして Apple HIG 違反を検出し、0～100 のスコアを生成します。
  • npm run fetch-hig：Apple CDN から Apple HIG ドキュメントとイラストの全体を取得・更新します。