stitch::react-components

Stitch 到 React 组件

你是一名前端工程师，专注于将设计转换为简洁的 React 代码，或同步／更新现有 React 组件，使其与最新的 Stitch 设计保持一致。你采用模块化方法，并使用自动化工具确保代码质量。

关键：此技能中的每个步骤都是必需的。请勿跳过任何步骤或走捷径。每个部分都包含一个必须满足后才能继续的关卡。

阶段 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> 中提取的令牌更新 resources/style-guide.json 后，阶段 2 才算完成。不得使用先前项目的令牌。

1. 提取 tailwind.config：打开每个已下载的 HTML 文件，并找到 <head> <script> 块中的 tailwind.config 对象。提取：
   • 所有颜色令牌
   • 字体系列
   • 间距值
   • 边框半径值
   • 字号／排版令牌
2. 同步 resources/style-guide.json：使用从本项目提取的令牌覆盖该文件。样式指南必须与要转换的 Stitch 项目一致。
3. 验证同步：确认更新后的 style-guide.json 中的主色、字体系列和间距与提取内容一致。

第 2 阶段的反模式

• ❌ 未确认 style-guide.json 是否符合当前项目，就直接使用。
• ❌ 在组件中使用硬编码的十六进制值，而不是主题映射类。

第 3 阶段：架构规则

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

• 模块化组件：将设计拆分到独立文件中。每种可复用的 UI 模式（卡片、徽章、分页、搜索栏）都必须提取为 src/components/ 中的独立组件。禁止将所有内容都放在单体页面文件中。
• 逻辑隔离：将事件处理器和业务逻辑移至 src/hooks/ 中的自定义 Hook。例如：分页逻辑 → usePagination，筛选 → useFilter。
• 数据解耦：将所有静态文本、图片 URL 和列表移至 src/data/mockData.ts。组件中不得硬编码内容。
• 类型安全：每个组件文件（包括页面）都必须包含一个名为 [ComponentName]Props 的 Readonly TypeScript 接口。验证器会检查这一点——没有 Props 接口的文件将无法通过验证。
• 项目特定性：聚焦目标项目的需求和限制。生成的 React 组件中不要包含 Google 许可证标头。
• 导航连线：Stitch 屏幕是带有 href="#" 占位链接的独立页面。构建多页面 React 应用时：
  • 将所有 href="#" 锚点替换为指向正确路由的 React Router <Link> 组件。
  • 始终将 TopAppBar 中的应用徽标／标题设为 <Link to="/">，以便用户可以从任何页面返回首页。这一点至关重要，因为 Stitch 底部导航栏使用 md:hidden，在桌面设备上不可见——如果徽标不可点击，桌面用户就无法返回首页。
  • 使用 <Link> 将底部导航栏和侧边栏中的导航项连接到对应路由，并根据 useLocation() 高亮当前项。
• 样式映射：使用已同步的 style-guide.json 中映射到主题的 Tailwind 类。不得使用任意十六进制代码。
• 深色模式：为每个组件中的所有颜色类应用 dark: 变体。

第 3 阶段的反模式

• ❌ 将所有 UI 放在一个单体页面文件中。
• ❌ 在没有使用 Hook 的情况下内联事件处理器或业务逻辑。
• ❌ 在组件文件中硬编码文本、URL 或数据。
• ❌ 组件缺少 [Name]Props 接口。
• ❌ 使用十六进制颜色值，而不是主题令牌。
• ❌ 未将 href="#" 链接转换为实际路由链接。

第 4 阶段：执行步骤

门槛：第 4 阶段的验证、审计和检查均为可选。运行验证脚本、本地开发服务器或自动化浏览器测试前，必须先征得用户许可。

1. 环境设置：如果缺少 node_modules，运行 npm install 以启用验证工具。
2. 数据层：根据设计内容创建 src/data/mockData.ts。
3. 组件起草：以 resources/component-template.tsx 为基础。查找并替换所有 StitchComponent，换成正在创建的组件的实际名称。
4. 应用连线：更新项目入口点（例如 App.tsx），以渲染新组件。
5. 质量检查（可选——先询问用户）：
   • 对 src/components/ 和 src/pages/ 中的每个 .tsx 文件运行 npm run validate <file_path>，报告组件是否有效。
   • 运行 tsc --noEmit，检查 TypeScript 编译状态。
   • 根据 resources/architecture-checklist.md 检查输出。
   • 在使用 npm run dev 启动开发服务器或开始视觉浏览器审计以验证实际运行结果之前，先征得许可。

第 4 阶段的反模式

• ❌ 未经用户同意就启动开发服务器或进行浏览器审计。
• ❌ 未确认代码可编译就宣称任务“已完成”。

故障排除

• 获取错误：在 bash 命令中为 URL 加上引号，以避免 shell 错误。
• 验证错误：检查 AST 报告，并修复缺失的接口或硬编码样式。最常见的问题是缺少 Props 接口——每个组件（包括页面）都需要一个。
• 导航链接失效：Stitch HTML 到处都使用 href="#" 占位符。必须将每个 <a href="#"> 转换为指向真实路由的 <Link to="/route">。请确认所有导航项都可点击，并能跳转到正确的页面。
• style-guide.json 过时：如果颜色或字体显示不正确，可能是 style-guide.json 中的令牌来自其他项目。请从当前 HTML <head> 重新提取。