ios-design-system

Airbnb iOS デザインシステムのベストプラクティス

SwiftUI iOS 26／Swift 6.2 アプリ向けの、独自の方針に基づく厳格なデザインシステムエンジニアリングです。影響度順に優先順位付けされた、8 つのカテゴリーにわたる 50 のルールを収録しています。Airbnb の Design Language System（DLS）、Airbnb Swift Style Guide、Apple Human Interface Guidelines、および WWDC セッションをもとにしています。すべてのビューで @Equatable、状態管理に @Observable を使用し、スタイルプロトコルを主要なコンポーネント API とすることを必須としています。

必須のアーキテクチャ整合性

このスキルは swift-ui-architect と併用することを想定しています。すべてのコード例は、次の変更不可の制約に従っています。

• 機能モジュールが依存するのは Domain + DesignSystem のみで、Data に直接依存しない
• ミュータブルな UI 状態には @Observable を使用し、ObservableObject／@Published は使用しない
• すべてのビューに @Equatable マクロを付ける
• コンポーネントの主要なスタイリング API としてスタイルプロトコルを使用する（Airbnb DLS のパターン）
• カラー値の信頼できる情報源としてアセットカタログを使用する
• デザインシステムのモジュール境界にはローカル SPM パッケージを使用する

スコープと関連する兄弟スキル

このスキルは インフラストラクチャ層 であり、デザインシステム自体の 構築方法 を扱います。兄弟スキルと併用する場合：

兄弟スキル	重点分野	このスキルの重点分野
swift-ui-architect	アーキテクチャ（モジュール化された MVVM-C、ルートシェル、プロトコル境界）	デザインシステムのインフラストラクチャ（トークン、スタイル、ガバナンス）
ios-design	デザインプリミティブ（セマンティックカラー、タイポグラフィ）の 使用	プリミティブを提供するトークンシステムの エンジニアリング
ios-ui-refactor	ビジュアル品質の問題の 監査／修正	ガバナンスと自動化による問題の 予防
ios-hig	HIG 準拠のパターン	準拠を容易にする アセットとコンポーネントのインフラストラクチャ

Clinic アーキテクチャ契約（iOS 26／Swift 6.2）

このスキルのガイダンスはすべて、Clinic のモジュール化された MVVM-C アーキテクチャを前提としています。

• 機能モジュールがインポートするのは Domain + DesignSystem のみ（Data や兄弟機能はインポートしない）
• App ターゲットが集約点となり、DependencyContainer、具象コーディネーター、および Route Shell の接続を所有する
• Domain は純粋な Swift を保ち、モデルに加えてリポジトリ、*Coordinating、ErrorRouting、AppError の各契約を定義する
• Data は SwiftData／ネットワーク／同期／リトライ／バックグラウンド I/O を担い、Domain のプロトコルを実装する
• 読み取り／書き込みフローでは、デフォルトで stale-while-revalidate の読み取りと、楽観的なキュー書き込みを使用する
• ViewModel はリポジトリプロトコルを直接呼び出す（デフォルトのユースケース／インタラクター層は設けない）

適用する場面

次のような場合に、これらのガイドラインを参照してください。

• 新しい iOS アプリのデザインシステムをセットアップするとき
• トークンアーキテクチャ（カラー、タイポグラフィ、スペーシング、サイズ）を構築するとき
• 再利用可能なコンポーネントスタイル（ButtonStyle、LabelStyle、カスタム DLS プロトコル）を作成するとき
• アセットカタログ（カラー、画像、アイコン）を整理するとき
• その場しのぎのスタイルから、ガバナンスのあるトークンシステムへ移行するとき
• 自動化によってスタイルのばらつきを防ぎ、一貫性を徹底するとき
• ホワイトラベルアプリやマルチブランドアプリ向けのテーマ基盤を構築するとき
• ガバナンスされていないカラー、ハードコードされた値、シャドウトークンについて PR をレビューするとき

優先度別のルールカテゴリー

優先度	カテゴリー	影響度	プレフィックス	ルール数
1	トークンアーキテクチャ	CRITICAL	token-	6
2	カラーシステムエンジニアリング	CRITICAL	color-	7
3	コンポーネントスタイルライブラリ	CRITICAL	style-	10
4	タイポグラフィスケール	HIGH	type-	5
5	スペーシングとサイズのシステム	HIGH	space-	5
6	一貫性とガバナンス	HIGH	govern-	7
7	アセット管理	MEDIUM-HIGH	asset-	5
8	テーマとブランドのインフラストラクチャ	MEDIUM	theme-	5

クイックリファレンス

1. トークンアーキテクチャ（重大）

• token-three-layer-hierarchy - Raw → Semantic → Component のトークンレイヤーを使用します
• token-enum-over-struct - トークンの名前空間にはケースレス enum を使用します
• token-single-file-per-domain - デザイン領域ごとにトークンファイルを1つ用意します
• token-shapestyle-extensions - ShapeStyle を拡張してドット構文の色を実現します
• token-asset-catalog-source - アセットカタログを色トークンのソースとして使用します
• token-avoid-over-abstraction - 3つのレイヤーを超える過度な抽象化は避けます

2. カラーシステムの設計（重大）

• color-organized-xcassets - 役割ごとにフォルダーグループを作成し、カラーアセットを整理します
• color-complete-pairs - カスタムカラーごとに両方の外観を定義します
• color-limit-palette - カスタムカラーをセマンティックトークン20個未満に抑えます
• color-no-hex-in-views - ビューのコードでは Color リテラルや hex 値を使用しません
• color-system-first - カスタムトークンよりもシステムカラーを優先します
• color-tint-not-brand-everywhere - ブランドカラーをアプリの tint に設定し、あちこちに散在させないようにします
• color-audit-script - ビルドスクリプトで管理されていないカラーを監査します

3. コンポーネントスタイルライブラリ（重大）

• style-dls-protocol-pattern - 複雑な DLS コンポーネントにはカスタムスタイルプロトコルを定義します
• style-equatable-views - すべてのデザインシステムのビューに @Equatable を適用します
• style-accessibility-first - 個々のビューではなく、スタイルプロトコルにアクセシビリティを組み込みます
• style-protocol-over-wrapper - ラッパービューではなく Style プロトコルを使用します
• style-static-member-syntax - カスタムスタイルに静的メンバー構文を用意します
• style-environment-awareness - スタイルが環境値に応じて変化するようにします
• style-view-for-containers-modifier-for-styling - コンテナーにはビューを、スタイリングにはモディファイアを使用します
• style-catalog-file - コンポーネントの種類ごとにスタイルカタログファイルを1つ用意します
• style-configuration-over-parameters - 多数のパラメーターよりも構成用の構造体を優先します
• style-preview-catalog - すべてのスタイルを含むプレビューカタログを作成します

4. タイポグラフィのスケール（高）

• type-scale-enum - システムスタイルをラップするタイプスケールの enum を定義します
• type-system-styles-first - カスタムスタイルよりもシステムのテキストスタイルを優先します
• type-custom-font-registration - 一元化した拡張機能でカスタムフォントを登録します
• type-max-styles-per-screen - 画面ごとのタイポグラフィのバリエーションを3～4種類に抑えます
• type-avoid-font-design-mixing - アプリごとに1種類のフォントデザインを使用します

5. 間隔とサイズのシステム（HIGH）

• space-token-enum - 間隔トークンを大文字・小文字を区別しない列挙型として定義します
• space-radius-tokens - コンポーネントの種類ごとに角の半径トークンを定義します
• space-no-magic-numbers - ビューのレイアウトコードでハードコードされた数値をゼロにします
• space-insets-pattern - 複合的なパディングには EdgeInsets 定数を使用します
• space-size-tokens - 一般的な寸法のサイズトークンを定義します

6. 一貫性とガバナンス（HIGH）

• govern-naming-conventions - すべてのトークンで一貫した命名規則を徹底します
• govern-spm-package-boundary - デザインシステムをローカルの SPM パッケージとして分離します
• govern-single-source-of-truth - すべての視覚的な値に定義箇所を一つだけ設けます
• govern-lint-for-tokens - SwiftLint のルールを使用してトークンの使用を徹底します
• govern-design-system-directory - 専用のディレクトリにトークンを分離します
• govern-migration-incremental - トークンへの移行を段階的に進めます
• govern-prevent-local-tokens - 機能モジュールでローカルトークンを定義できないようにします

7. アセット管理（MEDIUM-HIGH）

• asset-separate-catalogs - 色、画像、アイコン用にアセットカタログを分けます
• asset-sf-symbols-first - カスタムアイコンより先に SF Symbols を使用します
• asset-icon-export-format - PDF/SVG のベクターを使用し、複数の PNG は使用しません
• asset-image-optimization - 圧縮とオンデマンドリソースを使用します
• asset-naming-convention - すべてのアセットで一貫した命名規則を使用します

8. テーマとブランドの基盤（MEDIUM）

• theme-environment-key - テーマの伝播には EnvironmentKey を使用します
• theme-dont-over-theme - 必要がない限り、テーマシステムの構築は避けます
• theme-tint-for-brand - ブランドを表現する主な手段として .tint() を使用します
• theme-light-dark-only - カスタムテーマではなく、明るい／暗い表示には ColorScheme を使用します
• theme-brand-layer-separation - ブランドアイデンティティとシステムの仕組みを分離します

使用方法

詳しい説明とコード例については、各リファレンスファイルをお読みください。

• セクションの定義 - カテゴリー構成と影響度
• ルールのテンプレート - 新しいルールを追加するためのテンプレート

リファレンスファイル

ファイル	説明
references/_sections.md	カテゴリーの定義と順序
assets/templates/_template.md	新しいルール用のテンプレート
metadata.json	バージョンとリファレンス情報