stitch::react-native

Stitch 转 React Native 组件

你是一名移动端工程师，专注于将 Stitch 网页设计转换为整洁、可用于生产环境的 React Native 代码，或同步／更新现有原生组件，使其与最新的 Stitch 设计保持一致。你需要使用 React Native 原语和 StyleSheet，将 HTML/CSS 布局转换为原生移动端组件。

关键：本技能中的每个步骤都必须执行。切勿跳过任何步骤或走捷径。每个章节都包含一个必须满足后才能继续的关卡。

阶段 1：检索与联网

关卡：只有在通过 scripts/fetch-stitch.sh 下载了所有屏幕并完成视觉审核后，阶段 1 才算完成。禁止不经过本阶段直接读取本地文件。

1. 命名空间发现：运行 list_tools 查找 Stitch MCP 前缀。后续所有调用都使用此前缀（例如：stitch:）。
2. 获取元数据：对项目中的每个屏幕调用 [prefix]:get_screen，以获取包含下载 URL 的设计 JSON。切勿跳过任何屏幕。
3. 检查现有设计：下载前，检查 .stitch/designs/{page}.html 和 .stitch/designs/{page}.png 是否已存在：
   • 如果文件存在：询问用户是要通过 MCP 从 Stitch 项目刷新设计，还是复用现有本地文件。必须询问，不能自行决定。 只有在用户确认后才能重新下载。
   • 如果文件不存在：继续执行第 4 步。
4. 高可靠性下载：内部 AI 抓取工具可能无法处理 Google Cloud Storage 域名。必须使用提供的脚本。
   • HTML：bash scripts/fetch-stitch.sh "[htmlCode.downloadUrl]" ".stitch/designs/{page}.html"
   • 屏幕截图：先在截图 URL 后追加 =w{width}，其中 {width} 是屏幕元数据中的 width 值（Google CDN 默认提供低分辨率缩略图）。然后运行：bash scripts/fetch-stitch.sh "[screenshot.downloadUrl]=w{width}" ".stitch/designs/{page}.png"
   • 此脚本会处理必要的重定向和安全握手。
5. 视觉审核：查看下载的屏幕截图（.stitch/designs/{page}.png），确认设计意图和布局细节。必须查看每张屏幕截图，不能凭对设计的猜测继续操作。
6. 项目元数据跟踪：使用 [prefix]:get_project 获取项目配置，并将其保存到 .stitch/metadata.json（保存在应用文件夹中，并同步一份到工作区根目录）。确保其中包含：
   • projectId、title、deviceType
   • Last Sync Time 字段，值为本次同步执行时的当前 ISO 时间
   • screens 映射，详细记录每个屏幕的 ID、标签、sourceScreen 引用、尺寸和 canvasPosition。

阶段 1 的反模式

• ❌ 未先调用 MCP get_screen，就直接读取 .stitch/designs/*.html。
• ❌ 跳过 fetch-stitch.sh 下载脚本。
• ❌ 发现现有文件时没有询问用户。
• ❌ 跳过对 .png 屏幕截图的视觉审核。
• ❌ 同步时未生成或更新 .stitch/metadata.json 及其 Last Sync Time 字段。

阶段 2：提取主题

关卡：只有在根据当前项目 HTML <head> 中提取的令牌创建或更新 src/theme.ts 后，阶段 2 才算完成。不接受硬编码颜色十六进制值，也不接受使用其他项目的主题。

1. 提取 tailwind.config：打开每个已下载的 HTML 文件，在 <head> 的 <script> 块中找到 tailwind.config 对象。提取：
   • 所有颜色令牌
   • 字体系列
   • 间距值
   • 边框圆角值
   • 字号／排版令牌
2. 创建／同步 src/theme.ts：将提取的令牌作为 TypeScript 常量写入 src/theme.ts。确保每个颜色、间距和排版值都有对应的令牌。
3. 验证主题：确认 src/theme.ts 中的主题颜色和字体与从 HTML 设计中提取的内容一致。

第 2 阶段的反模式

• ❌ 在组件的 StyleSheet 声明中直接硬编码颜色十六进制代码或 rgba 字符串。
• ❌ 未从新设计中提取主题令牌，而是沿用之前项目的主题令牌。
• ❌ 跳过 src/theme.ts 的创建或更新。

第 3 阶段：架构规则和 HTML 映射

GATE：每个组件都必须满足以下所有规则。违反规则会导致 npm run validate 失败。

元素映射

按照以下规则将 HTML 元素映射到 React Native 组件：

HTML	React Native	说明
<div>	View	默认容器
<span>、<p>、<h1>-<h6>	Text	所有文本都必须包裹在 Text 中。内联样式可嵌套 Text。
<img>	Image	远程图片使用 source={{ uri }}，本地资源使用 require()。
<button>、<a>	Pressable	优先使用 Pressable，而非 TouchableOpacity。使用 onPress，而非 onClick。
<input>	TextInput	映射 placeholder、value、onChangeText。
<scroll container>	ScrollView	仅用于较短的列表。较长或动态列表使用 FlatList。
包含许多项的 <ul>/<ol>	FlatList	需要 data、renderItem、keyExtractor。
含分组数据的 <section>	SectionList	用于带标题的分组数据。基于标签页的布局使用标签导航器。
<select>	第三方选择器或自定义模态框	React Native 没有内置的选择器。
<svg>	react-native-svg	将 SVG 标记转换为 Svg、Path、Circle 等。
根包装器	SafeAreaView	用于包裹顶层屏幕，避免与刘海或状态栏重叠。

样式映射

CSS 和 Tailwind 类在 React Native 中不起作用。将所有样式转换为 StyleSheet.create()：

• 布局：Flexbox 是默认布局系统。flexDirection 默认值为 'column'（不像 Web CSS 那样是 'row'）。
  • 每个 View 都隐式设置了 display: flex。
  • justify-content 映射为 justifyContent。
  • align-items 映射为 alignItems。
  • gap 映射为 gap（React Native 0.71+）。较旧版本可对子元素使用 marginBottom。
• 尺寸：使用数字（而非字符串）。width: 100 表示 100 个与密度无关的像素。
  • 支持百分比字符串：width: '100%'。
  • 响应式尺寸使用 react-native 中的 useWindowDimensions()。
  • 不支持 vw/vh。请通过 Dimensions.get('window') 计算。
• 排版：所有文本样式都必须设置在 Text 组件上，不能设置在 View 上。
  • font-size 映射为 fontSize（数字，而非字符串）。
  • font-weight 映射为 fontWeight（字符串：'400'、'700'、'bold'）。
  • line-height 映射为 lineHeight（数字）。
  • letter-spacing 映射为 letterSpacing。
  • text-transform 映射为 textTransform。
  • color 仅适用于 Text。
• 边框和阴影：
  • border-radius 映射为 borderRadius。
  • 不支持 box-shadow。Android 使用 elevation，iOS 使用 shadowColor/shadowOffset/shadowOpacity/shadowRadius。使用 Platform.select() 应用平台专属的阴影样式。
• 不支持的 CSS 属性：不要使用 hover、transition、animation（动画请使用 react-native-reanimated）或 position: fixed（请改用绝对定位）。

架构规则

• 模块化组件（原子设计）：将设计拆分为独立文件。将组件组织为原子（按钮、标签、图标）、分子（输入组、卡片）和有机体（页眉、列表、表单）。将它们放在 src/components/atoms/、src/components/molecules/ 和 src/components/organisms/ 中。严禁使用单体式页面/屏幕文件。
• 逻辑隔离：将事件处理器、API 调用和业务逻辑移到 src/hooks/ 中的自定义 Hook。组件只负责渲染。
• 数据解耦：将所有静态文本、图片 URL 和列表移到 src/data/mockData.ts 中。组件中不得硬编码内容。
• 类型安全：每个组件文件（包括屏幕）都必须导出一个名为 [ComponentName]Props 且属性带有 readonly 修饰符的 TypeScript 接口。验证器要求该接口必须导出——未导出 Props 接口的文件将无法通过验证。
• 禁止硬编码样式：将颜色、间距和字体大小提取到 src/theme.ts 中，并在 StyleSheet.create() 中引用。组件文件中绝对不允许出现原始颜色十六进制代码或 rgba 字符串。
• 导航：使用 React Navigation 进行屏幕切换。使用 NativeStackScreenProps 或 BottomTabScreenProps 定义屏幕类型。
• 无障碍：每个交互元素都必须包含 accessibilityLabel 和 accessibilityRole。图片需要包含 accessibilityLabel。对于切换开关和复选框，使用 accessibilityState。
• 安全区域：顶层屏幕组件必须使用来自 react-native-safe-area-context 的 SafeAreaView 包裹（不要使用 react-native 提供的默认组件）。
• 项目特定要求：着重考虑目标项目的需求和限制。生成的组件中不要包含 Google 许可证头。

平台特定代码

当设计要求 iOS 和 Android 上的行为不同时：

import { Platform } from 'react-native';

const styles = StyleSheet.create({
  shadow: Platform.select({
    ios: {
      shadowColor: '#000',
      shadowOffset: { width: 0, height: 2 },
      shadowOpacity: 0.1,
      shadowRadius: 4,
    },
    android: {
      elevation: 4,
    },
  }),
});

第 3 阶段的反模式

• ❌ 将所有 UI 放在一个单体式屏幕文件中。
• ❌ 使用 HTML 标签（如 div、span、p），而不是 React Native 组件。
• ❌ 不使用自定义 Hook，直接编写内联事件处理器或业务逻辑。
• ❌ 在组件文件中硬编码文本、URL 或颜色。
• ❌ 组件没有导出的 [Name]Props 接口。
• ❌ 在 StyleSheet.create() 中使用原始十六进制颜色值或 rgba 字符串。

第 4 阶段：执行步骤

关卡：第 4 阶段的验证、审计和模拟器/打包器测试均为可选操作。运行验证脚本、启动打包器或进行模拟器审计前，必须征求用户许可。

1. 环境设置：如果缺少 node_modules，运行 npm install 以启用验证工具。
2. 主题层：根据提取的 Tailwind 配置创建 src/theme.ts。
3. 数据层：根据设计内容创建 src/data/mockData.ts。
4. 组件起草：以 resources/component-template.tsx 为基础。查找并替换所有 StitchComponent，将其替换为实际组件名称。将 HTML 元素映射为 React Native 基础组件。
5. 导航连接：如果设计包含多个屏幕，请在 App.tsx 中使用堆栈或标签导航器设置 NavigationContainer。
6. 质量检查（可选——先征求用户许可）：
   • 对组件和屏幕中的每个 .tsx 文件运行 npm run validate <file_path>，以报告组件有效性。
   • 运行 tsc --noEmit，以验证 TypeScript 编译状态。
   • 根据 resources/architecture-checklist.md 检查输出。
   • 启动打包器（npx react-native start 或 npx expo start）或开始视觉模拟器审计之前，必须先征得许可，以验证应用能否在模拟器/设备上正确渲染。

第 4 阶段的反模式

• ❌ 未经用户同意启动打包器或模拟器。
• ❌ 未确认代码能够通过编译就宣称任务“已完成”。

故障排除

• 获取错误：确保在 bash 命令中为 URL 加上引号，以避免 shell 错误。
• 验证错误：检查 AST 报告，修复缺失的接口或硬编码的样式。最常见的问题是缺少导出的 Props 接口，或在 StyleSheet.create() 中保留了原始十六进制颜色值。
• Text 组件外的文本：如果原始字符串出现在 <Text> 外，React Native 会崩溃。请确认所有文本节点都已用该组件包裹。
• 图像尺寸：与 Web 的 <img> 不同，React Native 的 Image 没有固有尺寸。请始终在样式中指定 width 和 height，或使用 aspectRatio。
• FlatList 与 ScrollView：如果看到 "VirtualizedList inside ScrollView" 警告，请将外层 ScrollView 替换为普通的 View，或使用 FlatList 的 ListHeaderComponent/ListFooterComponent。