react-native-design

React Native 设计

如果任由模型发挥，它每次设计出来的应用都一样：系统字体、一个蓝色强调色、一列样式相同的卡片，以及加载时的旋转指示器。这项技能会让 Agent 先阅读项目，选定适合当前应用的设计方向，以设计令牌为基础构建界面，并遵循 React Native 实际施加的规则交付。

典型输入：需要主题的应用创意、需要完整调色板的品牌色、要设计的屏幕，或“感觉不太对”的现有 UI。

这项技能的组织方式

本文件介绍操作流程。具体细节位于参考文件中——仅在任务需要时加载：

任务	加载
创建、扩展或审核颜色或主题	references/color-system.md
为项目所用技术栈编写样式或主题文件	references/styling-stacks.md
设计特定屏幕及其导航或布局	references/screen-patterns.md
选择设计方向、字体、动效、图标和领域模式	references/aesthetics.md
涉及阴影、模糊、图像、键盘、安全区域或列表的内容	references/platform-constraints.md

scripts/contrast.mjs 用于测量 WCAG 对比度（Node，无依赖）。每次新增或更改文本／表面组合时都要运行：

node scripts/contrast.mjs "rgba(255,255,255,0.6)" "#1C1C1E"

路径均相对于此技能所在的文件夹。

---

第 1 步——设计前先阅读项目

技术基线

1. 运行环境——Expo 还是裸 React Native：查看 package.json、app.json / app.config.* 和入口文件。
2. React Native 版本——0.82 及更高版本仅运行于新架构，因此可使用 boxShadow、filter 和 display: 'contents'。旧项目使用这些功能前，先确认是否支持。
3. 核心 UI 库——react-native-safe-area-context、react-native-reanimated、react-native-gesture-handler、expo-router / @react-navigation/*、expo-blur、expo-image。
4. 样式技术栈——StyleSheet、NativeWind、styled-components 或 Restyle（见 styling-stacks.md）。

遵循项目中已有的技术栈和约定。除非用户提出要求，否则不要引入新的样式系统或主题模型。

新项目还是现有项目？

新项目（没有主题或屏幕）：可完全自由发挥。编写任何组件前，先定义颜色、字体比例和间距单位（工作流 A）。

现有项目：检查主题文件和现有屏幕，然后问自己：如果只使用现有设计系统，这次改动会显而易见，还是只会带来些无关紧要的变化？

• 设计系统足够灵活（有多层表面、完整的字体比例和间距网格）：在其范围内完成设计。
• 设计系统成为瓶颈（调色板单一、只有一种字号、缺少表面层次）：停下来询问：

“若要带来明显的改进，我需要[添加展示字体／增加表面层次／扩展调色板]。你希望我： A）严格沿用现有设计系统（改动较小、更稳妥） B）先提出设计系统的扩展方案（我会先展示方案，再修改任何代码）”

绝不要悄悄扩展设计系统。如果只会带来像素级的变化，也绝不要默默局限于现有系统。

步骤 2 — 确定设计方向

编写代码前，先回答以下问题（自行判断或询问用户）：

1. 目的与受众 — 这个屏幕解决什么问题，谁会使用，在什么场景下使用（通勤、健身房、办公桌前），每次使用几秒或几分钟。
2. 一种美学方向 — 电影感、编辑风、奢华、粗野主义、俏皮、实用主义、有机、新粗野主义（见 aesthetics.md 中的表格）。“简洁现代”不算一种方向。
3. 主题 — 深色、浅色，或两者兼有。若两者兼有，必须按角色映射语义化令牌。
4. 一个令人难忘的设计决策 — 用户最先注意到什么，这款应用与最相似的 10 个竞品相比有何不同。

极简和极繁都行。真正行不通的是只贯彻了一半的设计方向。

---

步骤 3 — 运行匹配的工作流

A. 从头创建主题

1. 推断或询问类别、受众和设计方向。
2. 根据情绪基调选择主色相，然后选择配色方案（默认使用分裂互补色方案）——参见 color-system.md。
3. 构建完整的令牌结构：表面、强调色（包括强调色上的文字）、文本、边框、语义色。
4. **使用脚本测量每组文字与表面的对比度。**继续之前，先修复每一处未通过的问题。
5. 字体：一种有个性的展示字体，加一种易读的正文字体（@expo-google-fonts/*）。字体系列最多两种。
6. 字体层级（展示、大标题、标题、正文、说明文字、标签）、间距网格（4 或 8）、圆角组（无、sm、md、lg、full）。
7. 输出：完整的主题文件 + 类型 + 字体加载代码。

B. 改进现有主题

1. 阅读所有主题文件（颜色、排版、间距、组件）。
2. 审核：表面层级是否清晰可见？强调色在每种表面上是否易读？语义色是否有别于强调色？字体层级是否有足够跨度（最小与最大字号的比例 ≥ 3:1）？间距是否遵循网格？对比度是否经过测量，而非凭目测判断？
3. 按视觉影响挑选最重要的 3 个问题。
4. 提出修复方案，以修改前 → 修改后的十六进制值和测得的比例呈现，每项附上一行理由。

C. 根据用户提供的颜色创建主题

1. 将颜色转换为 HSL：色相系列、饱和度、亮度。
2. 饱和度最高或最具辨识度的颜色作为强调色。
3. 基于这些颜色生成缺失的角色和表面层级。
4. 测量每组颜色的对比度。输出完整主题，并标明哪些颜色来自用户。

D. 设计特定视图

1. 检查现有主题和组件——基于已有内容进行设计。
2. 从 screen-patterns.md 中选择模式。
3. 仅使用主题令牌——不得引入系统之外的新颜色。
4. 设计所有状态（见下文）。
5. 输出：完整的视图代码；如果项目将样式和类型拆分到单独文件，也一并输出。

---

硬性规则

以下每一项都会破坏渲染效果或无障碍体验。完整列表和修复方法见 platform-constraints.md。

• ❌ background: 'linear-gradient(...)' — 会被静默忽略。请使用 expo-linear-gradient。
• ❌ display: 'grid' 或 'block'、CSS 伪选择器（:hover、::before）、px / em / rem 单位。
• ❌ 首字母大写的命名颜色（'Red'）——仅支持小写形式。
• ❌ 未指定尺寸的网络图片——渲染尺寸为 0×0。
• ❌ 使用 react-native 中的核心 SafeAreaView——它已弃用，而且从未处理过 Android。请使用 react-native-safe-area-context。
• ❌ 忽略边到边布局——在 Android 16 上，内容会绘制到系统栏下方；请使用内边距补偿系统插入区域。
• ❌ 在 Android 上使用 BlurView 却未设置 blurMethod——它会渲染为半透明视图，而非模糊效果。
• ❌ 可点击元素超出其父元素边界——它们在 Android 上无法接收触摸事件。
• ❌ 自定义字体使用 fontWeight: 'bold'——请加载并设置对应字重的准确字体文件。
• ❌ 凭目测判断对比度——请使用脚本测量。
• ❌ 在组件中硬编码颜色，而不使用令牌。
• ❌ 将破坏性操作放在容易误触的位置，或不提供确认步骤。
• ❌ 字体系列超过两种。

每个屏幕都有各种状态

只有设计好以下所有状态，屏幕设计才算完成：

状态	设计
加载（首次）	骨架屏形状贴合真实内容，并带有动态闪光效果。不要使用居中旋转指示器
加载（刷新）	使用下拉刷新或内联指示器；内容保持可见
空状态（首次使用）	图标或插图 + 说明 + 主要 CTA
空状态（删除后）	提供上下文提示（例如“还没有收藏内容”）
错误（网络）	使用通俗易懂的消息 + 重试。绝不显示堆栈跟踪
错误（验证）	每个字段内联显示：图标 + 文本
成功	显示 Toast 或动画，2-4 秒后消失
离线	显示横幅 + 仍可查看缓存内容

骨架屏应与内容形状相符：深色背景使用 rgba(255,255,255, 0.05-0.08)，浅色背景使用 rgba(0,0,0, 0.04-0.08)。约 2 秒后，改为显示部分内容或进度。

---

安全地编辑样式文件

编辑样式时最常见的问题是声明重复：插入了新代码块，却保留了旧代码块。

1. 编辑前读取整个文件，并找到要替换的准确代码块。
2. 替换整个代码块，从 export const 开始，直到结尾的反引号或花括号。绝不要只替换部分匹配内容。
3. 每个组件只保留一个版本——不要在文件顶部添加新版本，却把旧版本留在下面。
4. 编辑后检查错误。 Cannot redeclare block-scoped variable 表示存在重复声明；删除过时的副本。

如果替换时无法匹配，请重新读取文件，并使用原文重试。

---

输出要求

生成的代码必须：

• 开箱即用——不能有占位符、不能有 // TODO，也不能缺少导入项。
• 使用项目现有的样式方案。
• 处理适用的安全区域、全屏边到边布局以及 iOS/Android 差异。
• 引入字体时包含字体加载代码；创建主题时包含完整的令牌文件。
• 尊重字体缩放，除非项目有意选择不支持。
• 在 375pt 宽的屏幕（iPhone SE / 13 mini）和约 430pt 宽的屏幕（Pro Max）上均能正常显示。

交付前检查清单

• 使用 scripts/contrast.mjs 测量每组文本与表面颜色的对比度，达到对应字号的 AA 标准
• 所有颜色均来自令牌——组件中不使用十六进制颜色值
• 触控目标 ≥ 44pt（iOS）/ 48dp（Android）
• 间距符合基础网格
• 已设计加载、空状态和错误状态
• 已处理安全区域和全屏边到边布局
• 不使用仅适用于 Web 的 CSS
• 至少能看到三个不同的字体排版层级
• 有一个让用户第一眼就能注意到的设计决策