mobile-design

モバイルデザインシステム

理念: タッチ優先。バッテリーに配慮。プラットフォームを尊重。オフラインで動作可能。 中核原則: モバイルは小さなデスクトップではありません。モバイルの制約を考慮し、プラットフォームの選択を確認してください。

---

🔧 ランタイムスクリプト

検証のためにこれらを実行してください（読むのではなく、そのまま実行します）:

スクリプト	目的	使い方
scripts/mobile_audit.py	モバイル UX・タッチ監査	python scripts/mobile_audit.py <project_path>

---

🔴 必須: 作業前に参照ファイルを読むこと！

⛔ 関連ファイルを読むまで開発を開始しないでください:

共通（常に読む）

ファイル	内容	ステータス
mobile-design-thinking.md	⚠️ 暗記防止: 思考を促し、AI の既定パターンを防ぎます	⬜ 最優先
touch-psychology.md	Fitts の法則、ジェスチャー、ハプティクス、親指の届く範囲	⬜ 重要
mobile-performance.md	RN/Flutter のパフォーマンス、60fps、メモリ	⬜ 重要
mobile-backend.md	プッシュ通知、オフライン同期、モバイル API	⬜ 重要
mobile-testing.md	テストピラミッド、E2E、プラットフォーム固有のテスト	⬜ 重要
mobile-debugging.md	ネイティブと JS のデバッグ、Flipper、Logcat	⬜ 重要
mobile-navigation.md	タブ/スタック/ドロワー、ディープリンク	⬜ 読む
mobile-typography.md	システムフォント、Dynamic Type、アクセシビリティ	⬜ 読む
mobile-color-system.md	OLED、ダークモード、バッテリー配慮	⬜ 読む
decision-trees.md	フレームワーク/状態/ストレージの選択	⬜ 読む

🧠 mobile-design-thinking.md が最優先です！ このファイルにより、AI は暗記したパターンを使わずに考えるようになります。

プラットフォーム固有（対象に応じて読む）

プラットフォーム	ファイル	内容	読むタイミング
iOS	platform-ios.md	Human Interface Guidelines、SF Pro、SwiftUI パターン	iPhone/iPad 向けに開発する場合
Android	platform-android.md	Material Design 3、Roboto、Compose パターン	Android 向けに開発する場合
クロスプラットフォーム	上記both	プラットフォームの相違点	React Native / Flutter

🔴 iOS 向けに開発する場合 → まず platform-ios.md を読んでください！ 🔴 Android 向けに開発する場合 → まず platform-android.md を読んでください！ 🔴 クロスプラットフォームの場合 → 両方を読み、条件付きのプラットフォーム分岐ロジックを適用してください！

---

⚠️ 重要: 前提を置く前に必ず確認すること（必須）

停止してください！ ユーザーの依頼が自由形式の場合、お気に入りの選択肢を既定値として使わないでください。

指定がない場合は必ず確認すること:

項目	確認内容	理由
プラットフォーム	「iOS、Android、それとも両方ですか？」	すべての設計判断に影響します
フレームワーク	「React Native、Flutter、それともネイティブですか？」	パターンとツールが決まります
ナビゲーション	「タブバー、ドロワー、それともスタックベースですか？」	中核となる UX の判断です
状態管理	「どの状態管理を使いますか？（Zustand/Redux/Riverpod/BLoC？）」	アーキテクチャの基盤になります
オフライン	「オフラインでも動作する必要がありますか？」	データ戦略に影響します
対象デバイス	「スマートフォンのみですか、それともタブレットにも対応しますか？」	レイアウトの複雑さに影響します

⛔ AI モバイルのアンチパターン（YASAK LİSTESİ）

🚫 これらは必ず避けるべき AI の既定の傾向です！

パフォーマンスの禁止事項

❌ やってはいけないこと	問題点	✅ 必ずやること
長いリストに ScrollView を使う	すべてのアイテムを描画するため、メモリが爆発的に増える	FlatList / FlashList / ListView.builder を使う
renderItem 関数をインラインで定義する	毎回のレンダリングで新しい関数が作られ、全アイテムが再レンダリングされる	useCallback + React.memo を使う
keyExtractor を省略する	インデックスベースのキーは並べ替え時にバグを引き起こす	データ由来の一意で安定したIDを使う
getItemLayout を省略する	レイアウトが非同期になり、スクロールがカクつく	アイテムの高さが固定の場合は提供する
どこでも setState() を使う	不要なウィジェットの再構築が発生する	状態のスコープを絞り、const コンストラクタを使う
Native driver を false にする	アニメーションが JS スレッドにブロックされる	常に useNativeDriver: true を使う
本番環境で console.log を使う	JS スレッドを大きくブロックする	リリースビルド前に削除する
React.memo / const を使わない	何か変更があるたびに全アイテムが再レンダリングされる	リストアイテムは必ずメモ化する

タッチ/UX の禁止事項

❌ やってはいけないこと	問題点	✅ 必ずやること
タッチターゲットが 44px 未満	正確にタップできず、ユーザーが不満を感じる	最小 44pt (iOS) / 48dp (Android)
ターゲット間の間隔が 8px 未満	隣の要素を誤ってタップしてしまう	最低 8〜12px の間隔を確保する
ジェスチャーのみの操作	運動機能に障がいのあるユーザーが利用できない	必ずボタンによる代替手段を用意する
ローディング状態がない	ユーザーはアプリがクラッシュしたと思う	必ずローディングのフィードバックを表示する
エラー状態がない	ユーザーが行き詰まり、復旧する方法がない	リトライオプション付きのエラーを表示する
オフライン処理がない	ネットワークが切断されるとクラッシュまたは停止する	段階的に機能を縮退させ、キャッシュされたデータを使う
プラットフォームの慣習を無視する	ユーザーが混乱し、体に染みついた操作が崩れる	iOS は iOS らしく、Android は Android らしくする

セキュリティの禁止事項

❌ やってはいけないこと	問題点	✅ 必ずやること
トークンを AsyncStorage に保存する	容易にアクセスされ、root化された端末で盗まれる	SecureStore / Keychain / EncryptedSharedPreferences を使う
API キーをハードコードする	APK/IPA からリバースエンジニアリングされる	環境変数やセキュアストレージを使う
SSL ピンニングを省略する	MITM 攻撃が可能になる	本番環境では証明書をピン留めする
機密データをログに出力する	ログから抽出される可能性がある	トークン、パスワード、PII は決してログに出力しない

アーキテクチャの禁止事項

❌ やってはいけないこと	問題点	✅ 必ずやること
UI にビジネスロジックを書く	テストできず、保守もできない	サービス層に分離する
すべてをグローバル状態で管理する	不要な再レンダリングが発生し、複雑になる	基本はローカル状態とし、必要な場合にのみ引き上げる
ディープリンクを後回しにする	通知や共有が機能しなくなる	初日からディープリンクを計画する
dispose/クリーンアップを省略する	メモリリークやゾンビリスナーが発生する	購読やタイマーをクリーンアップする

---

📱 プラットフォーム判断マトリクス

統一するか、分岐させるか

                    UNIFY (same on both)          DIVERGE (platform-specific)
                    ───────────────────           ──────────────────────────
Business Logic      ✅ Always                     -
Data Layer          ✅ Always                     -
Core Features       ✅ Always                     -
                    
Navigation          -                             ✅ iOS: edge swipe, Android: back button
Gestures            -                             ✅ Platform-native feel
Icons               -                             ✅ SF Symbols vs Material Icons
Date Pickers        -                             ✅ Native pickers feel right
Modals/Sheets       -                             ✅ iOS: bottom sheet vs Android: dialog
Typography          -                             ✅ SF Pro vs Roboto (or custom)
Error Dialogs       -                             ✅ Platform conventions for alerts

クイックリファレンス: プラットフォームの既定値

要素	iOS	Android
基本フォント	SF Pro / SF Compact	Roboto
最小タッチターゲット	44pt × 44pt	48dp × 48dp
戻る操作	左端からのスワイプ	システムの戻るボタン/ジェスチャー
下部タブのアイコン	SF Symbols	Material Symbols
アクションシート	下部から表示される UIActionSheet	Bottom Sheet / Dialog
進捗表示	スピナー	リニアプログレス (Material)
プルトゥリフレッシュ	ネイティブの UIRefreshControl	SwipeRefreshLayout

---

🧠 モバイル UX の心理学 (クイックリファレンス)

タッチ操作のためのフィッツの法則

Desktop: Cursor is precise (1px)
Mobile:  Finger is imprecise (~7mm contact area)

→ Touch targets MUST be 44-48px minimum
→ Important actions in THUMB ZONE (bottom of screen)
→ Destructive actions AWAY from easy reach

親指ゾーン (片手操作)

┌─────────────────────────────┐
│      HARD TO REACH          │ ← Navigation, menu, back
│        (stretch)            │
├─────────────────────────────┤
│      OK TO REACH            │ ← Secondary actions
│       (natural)             │
├─────────────────────────────┤
│      EASY TO REACH          │ ← PRIMARY CTAs, tab bar
│    (thumb's natural arc)    │ ← Main content interaction
└─────────────────────────────┘
        [  HOME  ]

モバイル特有の認知負荷

デスクトップ	モバイルとの違い
複数のウィンドウ	一度に取り組むタスクは1つ
キーボードショートカット	タッチジェスチャー
ホバー状態	ホバーはなし (タップするか、何もない)
大きなビューポート	限られたスペース、縦方向のスクロール
安定した注意力	絶えず中断される

詳しくは: touch-psychology.md

---

⚡ パフォーマンスの原則 (クイックリファレンス)

React Native の重要ルール

// ✅ CORRECT: Memoized renderItem + React.memo wrapper
const ListItem = React.memo(({ item }: { item: Item }) => (
  <View style={styles.item}>
    <Text>{item.title}</Text>
  </View>
));

const renderItem = useCallback(
  ({ item }: { item: Item }) => <ListItem item={item} />,
  []
);

// ✅ CORRECT: FlatList with all optimizations
<FlatList
  data={items}
  renderItem={renderItem}
  keyExtractor={(item) => item.id}  // Stable ID, NOT index
  getItemLayout={(data, index) => ({
    length: ITEM_HEIGHT,
    offset: ITEM_HEIGHT * index,
    index,
  })}
  removeClippedSubviews={true}
  maxToRenderPerBatch={10}
  windowSize={5}
/>

Flutter の重要ルール

// ✅ CORRECT: const constructors prevent rebuilds
class MyWidget extends StatelessWidget {
  const MyWidget({super.key}); // CONST!

  @override
  Widget build(BuildContext context) {
    return const Column( // CONST!
      children: [
        Text('Static content'),
        MyConstantWidget(),
      ],
    );
  }
}

// ✅ CORRECT: Targeted state with ValueListenableBuilder
ValueListenableBuilder<int>(
  valueListenable: counter,
  builder: (context, value, child) => Text('$value'),
  child: const ExpensiveWidget(), // Won't rebuild!
)

アニメーションのパフォーマンス

GPU-accelerated (FAST):     CPU-bound (SLOW):
├── transform               ├── width, height
├── opacity                 ├── top, left, right, bottom
└── (use these ONLY)        ├── margin, padding
                            └── (AVOID animating these)

完全なガイドはこちら: mobile-performance.md

---

📝 チェックポイント（モバイル作業の前に必須）

モバイルコードを書く前に、必ずこのチェックポイントを完了してください:

🧠 CHECKPOINT:

Platform:   [ iOS / Android / Both ]
Framework:  [ React Native / Flutter / SwiftUI / Kotlin ]
Files Read: [ List the skill files you've read ]

3 Principles I Will Apply:
1. _______________
2. _______________
3. _______________

Anti-Patterns I Will Avoid:
1. _______________
2. _______________

例:

🧠 CHECKPOINT:

Platform:   iOS + Android (Cross-platform)
Framework:  React Native + Expo
Files Read: touch-psychology.md, mobile-performance.md, platform-ios.md, platform-android.md

3 Principles I Will Apply:
1. FlatList with React.memo + useCallback for all lists
2. 48px touch targets, thumb zone for primary CTAs
3. Platform-specific navigation (edge swipe iOS, back button Android)

Anti-Patterns I Will Avoid:
1. ScrollView for lists → FlatList
2. Inline renderItem → Memoized
3. AsyncStorage for tokens → SecureStore

🔴 チェックポイントを埋められませんか？ → 戻ってスキルファイルを読んでください。

---

🔧 フレームワーク決定ツリー

WHAT ARE YOU BUILDING?
        │
        ├── Need OTA updates + rapid iteration + web team
        │   └── ✅ React Native + Expo
        │
        ├── Need pixel-perfect custom UI + performance critical
        │   └── ✅ Flutter
        │
        ├── Deep native features + single platform focus
        │   ├── iOS only → SwiftUI
        │   └── Android only → Kotlin + Jetpack Compose
        │
        ├── Existing RN codebase + new features
        │   └── ✅ React Native (bare workflow)
        │
        └── Enterprise + existing Flutter codebase
            └── ✅ Flutter

完全な決定ツリーはこちら: decision-trees.md

---

📋 開発前チェックリスト

モバイルプロジェクトを開始する前に

• プラットフォームは確定していますか？（iOS / Android / 両方）
• フレームワークは選定済みですか？（RN / Flutter / ネイティブ）
• ナビゲーションパターンは決まっていますか？（タブ / スタック / ドロワー）
• 状態管理は選定済みですか？（Zustand / Redux / Riverpod / BLoC）
• オフラインの要件は把握していますか？
• 初日からディープリンクを計画していますか？
• 対象デバイスは定義されていますか？（スマートフォン / タブレット / 両方）

画面ごとに

• タッチターゲットは 44〜48px 以上ですか？
• 主要な CTA は親指の届く範囲にありますか？
• 読み込み状態はありますか？
• 再試行付きのエラー状態はありますか？
• オフライン時の処理を考慮していますか？
• プラットフォームの慣習に従っていますか？

リリース前

• console.log は削除されていますか？
• 機密データには SecureStore を使用していますか？
• SSL ピンニングは有効ですか？
• リストは最適化されていますか（memo、keyExtractor）？
• アンマウント時のメモリクリーンアップはありますか？
• 低スペックデバイスでテストしましたか？
• すべてのインタラクティブな要素にアクセシビリティラベルがありますか？

---

📚 リファレンスファイル

特定の分野についてより詳しく知りたい場合:

ファイル	使用するタイミング
mobile-design-thinking.md	最初に読むこと！ 暗記に頼らず、文脈に基づいて考えるためのガイド
touch-psychology.md	タッチ操作、Fitts の法則、ジェスチャー設計の理解
mobile-performance.md	RN / Flutter の最適化、60fps、メモリ / バッテリー
platform-ios.md	iOS 固有のデザイン、HIG への準拠
platform-android.md	Android 固有のデザイン、Material Design 3
mobile-navigation.md	ナビゲーションパターン、ディープリンク
mobile-typography.md	タイプスケール、システムフォント、アクセシビリティ
mobile-color-system.md	OLED の最適化、ダークモード、バッテリー
decision-trees.md	フレームワーク、状態管理、ストレージの決定

---

覚えておいてください: モバイルユーザーはせっかちで、作業を中断されることが多く、小さな画面を不正確な指で操作しています。最悪の条件を想定して設計してください：不安定なネットワーク、片手操作、強い日差し、低いバッテリー残量。そこで動作すれば、どこでも動作します。