mobile-design

移动端设计系统

理念： 触控优先。注重电池续航。尊重平台特性。支持离线。 核心原则： 移动端不是小屏桌面端。考虑移动端的限制，并询问平台选择。

---

🔧 运行时脚本

运行以下脚本进行验证（不要阅读，只需运行）：

脚本	用途	用法
scripts/mobile_audit.py	移动端 UX 与触控审查	python scripts/mobile_audit.py <project_path>

---

🔴 必须：开始前阅读参考文件！

⛔ 阅读相关文件之前，请勿开始开发：

通用（始终阅读）

文件	内容	状态
mobile-design-thinking.md	⚠️ 反记忆：促使思考，防止 AI 默认行为	⬜ 首要关键
touch-psychology.md	菲茨定律、手势、触觉反馈、拇指区域	⬜ 关键
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	系统字体、动态字体、无障碍	⬜ 阅读
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 应用时
跨平台	两者均需阅读	平台差异点	React Native / Flutter

🔴 如果面向 iOS 开发 → 首先阅读 platform-ios.md！ 🔴 如果面向 Android 开发 → 首先阅读 platform-android.md！ 🔴 如果进行跨平台开发 → 两者都要阅读，并采用条件式平台逻辑！

---

⚠️ 关键：先询问，不要自行假设（必须）

停下！如果用户的请求较为开放，不要默认选择你偏好的方案。

未指定时必须询问：

方面	询问内容	原因
平台	“iOS、Android，还是两者都支持？”	会影响每一项设计决策
框架	“React Native、Flutter，还是原生开发？”	决定所采用的模式和工具
导航	“标签栏、抽屉，还是堆栈式导航？”	核心 UX 决策
状态	“使用什么状态管理方案？（Zustand/Redux/Riverpod/BLoC？）”	架构基础
离线	“是否需要支持离线使用？”	会影响数据策略
目标设备	“仅支持手机，还是也支持平板？”	布局复杂度

⛔ AI 移动端反模式（禁止清单）

🚫 这些是 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	任何更改都会导致每个项目重新渲染	始终对列表项目进行记忆化处理

触控／用户体验误区

❌ 绝不这样做	为什么不对	✅ 始终这样做
触控目标小于 44px	无法准确点击，令人沮丧	最小尺寸为 44pt（iOS）／48dp（Android）
目标之间的间距小于 8px	容易误触相邻目标	间距至少为 8-12px
仅支持手势交互	行动不便的用户无法使用	始终提供按钮作为替代方式
没有加载状态	用户会以为应用崩溃了	始终显示加载反馈
没有错误状态	用户会陷入困境，无法恢复	显示错误并提供重试选项
不处理离线情况	网络断开时会崩溃／卡住	优雅降级，并使用缓存数据
忽视平台惯例	用户会感到困惑，形成的肌肉记忆也会被打破	iOS 体验应符合 iOS 习惯，Android 体验应符合 Android 习惯

安全误区

❌ 绝不这样做	为什么不对	✅ 始终这样做
将令牌存储在 AsyncStorage 中	容易访问，在已取得 root 权限的设备上容易被盗取	使用 SecureStore / Keychain / EncryptedSharedPreferences
将 API 密钥硬编码	可从 APK/IPA 中反向工程提取	使用环境变量和安全存储
不进行 SSL 固定	可能遭受中间人攻击	在生产环境中固定证书
记录敏感数据	日志可能被提取	绝不记录令牌、密码和个人身份信息（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	底部操作面板／对话框
进度指示器	旋转指示器	线性进度条（Material）
下拉刷新	原生 UIRefreshControl	SwipeRefreshLayout

---

🧠 移动端用户体验心理学（快速参考）

触控的菲茨定律

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  ]

移动端特有的认知负荷

桌面端	移动端差异
多个窗口	一次只能处理一项任务
键盘快捷键	触控手势
悬停状态	不支持悬停（点击或不操作）
大视口	空间有限，需要垂直滚动
注意力稳定	注意力不断被打断

深入了解：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	框架、状态、存储决策

---

请记住： 移动端用户缺乏耐心、经常被打断，而且在小屏幕上用不精确的手指操作。请针对最糟糕的条件进行设计：网络状况差、单手操作、阳光强烈、电量低。如果在这些情况下都能正常运行，就能在任何情况下正常运行。