apple-native-ui

Apple ネイティブ UI

スクリーンショットを模倣するのではなく、プラットフォームの操作性、アクセシビリティ、適応性に関する規約に従うことで、ネイティブな使い心地のインターフェースを構築し、レビューします。

対象から始める

対象プラットフォーム、最低 OS バージョン、SwiftUI と UIKit/AppKit の境界、対応する入力方式（タッチ、ポインター、キーボード、VoiceOver、Digital Crown、リモコン、視線／手）、主要なフォームファクターを特定します。適用できる根拠がない限り、iPhone の慣習を macOS、iPad のマルチタスク、watchOS、tvOS、visionOS に持ち込まないでください。

カスタムで再構築する前に、システムコントロール、セマンティックカラー、テキストスタイル、セーフエリア API、ナビゲーションコンテナー、プレゼンテーション API を優先してください。カスタム UI にも、同等のアクセシビリティ、フォーカス、状態、キャンセルの動作を維持してください。

最新のプラットフォームガイダンス

SDK や OS のリリースによって変わる可能性がある API、動作、デザインの慣習、検証方法を提示または実装する前に、Apple Developer Documentation、Human Interface Guidelines、関連する WWDC セッションなど、Apple の最新の一次情報を確認してください。新しい API を推奨する前にプロジェクトのデプロイメントターゲットを確認し、Apple の最新ガイダンスとリポジトリ固有の互換性制約を区別してください。ここにある例は長期的に有効な規約を示すものであり、リリース固有のドキュメントに代わるものではありません。

macOS のワークフロー

macOS を対象とする場合は、複雑なインターフェースの計画、構築、移植、レビューを始める前に、references/macos-native-workflows.md を読んでください。コマンド、ウインドウと書類、選択とフォーカス、ペーストボードとドラッグ＆ドロップ、取り消し、状態復元、設定、Finder との相互運用性、動作に基づく検証について、Mac 固有のワークフローを追加します。

モデルやビューを iPadOS と共有する場合でも、Mac 版は独立したワークフローとして扱ってください。サイズ変更に対応した iPad レイアウトだけでは、完全な Mac アプリとは言えません。

状態と識別性

状態は最も狭い安定した境界で所有します。データを表示するだけの子ビューには値を渡し、親の状態を編集する子ビューにはバインディングを渡します。body に副作用を含めず、リストには安定した識別子を設定してください。

@Observable final class ProfileModel {
    var name = ""
    var isSaving = false
}

struct ProfileScreen: View {
    @State private var model = ProfileModel()

    var body: some View {
        Form {
            TextField("Name", text: $model.name)
            Button("Save") { save() }
                .disabled(model.name.isEmpty || model.isSaving)
        }
    }
}

注入された値を @State に変換したり、変更可能なリストの識別子に位置インデックスを使ったりしないでください。また、タスクを表す場合は Button、NavigationLink、Toggle などのネイティブコントロールを使い、onTapGesture は使わないでください。

プラットフォームの規約

• 対象プラットフォームに応じて、NavigationStack／NavigationSplitView、シート、アラート、確認ダイアログ、ツールバーを使用します。戻る、閉じる、キャンセル、フォーカス復元の各経路を確認してください。
• セマンティックカラーと Dynamic Type に対応したタイポグラフィを使用します。切り詰め、クリッピング、固定フレームを追加する前に、特大サイズのテキストをテストしてください。
• セーフエリア、分割表示、ウインドウのサイズ変更、回転、外部キーボード、ポインター、レイアウト方向は、例外的なブレークポイントではなく、レイアウトへの入力として扱ってください。
• デプロイメントターゲットが許す場合は @Observable、@State、@Binding、@Bindable を優先してください。バージョン固有の API は利用可能な場合に限って使用し、実際に機能する代替手段を用意してください。
• アニメーションは値に応じて駆動し、「視差効果を減らす」が有効な場合もタスクを維持してください。テストや報告を行う前に、観測可能な終了状態を待ってください。

アクセシビリティ

アクセシビリティは ARIA ではなく、ネイティブのアクセシビリティツリーによって表現されます。VoiceOver のラベル、値、ヒント、特性、グループ化、読み上げ順序、調整可能なアクション、フォーカス移動、無効化されたコントロールを確認してください。装飾的な画像は非表示にし、意味のある画像や曖昧なアイコンにはラベルを付けてください。

Button(action: play) {
    Image(systemName: "play.fill")
}
.accessibilityLabel("Play preview")

Image(systemName: "sparkles")
    .accessibilityHidden(true)

シミュレーター、デバイス、XCUITest、アクセシビリティ、フォームファクターの根拠については、references/apple-verification.md を読んでください。ネイティブ検証に関する主張を行う前に、必ず目を通してください。

レビュー結果

指摘はソースパスまたは観察対象のデバイスに関連付けます。根拠がソースのみか、実際に描画された画面に基づくかを明記します。該当するプラットフォームと入力方式を示してください。iOS に関する指摘が自動的に macOS にも当てはまるわけではありません。

推奨 / 避ける

推奨	避ける
意図的なスタイルを備えたシステムコントロール	コントロールの代わりにクリック可能なスタックや画像を使うこと
セマンティックなフォント、色、アダプティブなレイアウト	テキストが大きい場合やウィンドウが小さい場合に崩れる固定サイズ
安定した ID と明示的な状態管理	インデックスを ID として使うことや、body に隠された副作用
プラットフォームごとの検証	シミュレーターのスクリーンショットを、すべてのターゲットでの証明として扱うこと
有用なフォールバックを備えたバージョン判定	対応ユーザーを黙って切り捨てる、無条件の新しい API