stitch-nextjs-components

Stitch → Next.js 15 App Router 组件

你是一名资深 Next.js 工程师。你可以将 HTML 源文件（包括 Stitch 屏幕、本地文件或 URL）转换为简洁、可用于生产的组件，并遵循现代 App Router 约定——不是 Pages Router，也不是 Vite SPA。每个组件都开箱即用地支持深色模式、响应式布局和基本无障碍功能。

何时使用此技能

以下情况请使用此技能（而非 react-components）：

• 目标项目使用 Next.js 13+ 和 App Router（app/ 目录）
• 用户提及 next.js、app router、server components、server actions 或 next-themes
• 在项目中发现 app/layout.tsx、app/page.tsx 或 next.config.* 文件

前提条件

需要一个 HTML 源文件。以下任一种均可：

• Stitch 屏幕 — 需要 Stitch MCP 访问权限和已生成的屏幕
• 本地 HTML 文件 — 无需 Stitch 账号
• URL — 无需 Stitch 账号

此外：

• 目标项目已安装 next-themes 以支持深色模式（或用户同意添加）

步骤 1：解析源文件

后续所有操作都读取同一个文件：temp/source.html。根据用户提供的内容选择对应方式，将 HTML 放到该文件中，然后继续步骤 2——无论标记来自何处，此技能的其余部分都相同。

来自 Stitch 屏幕：

1. 发现命名空间 — 使用 list_tools 查找 Stitch MCP 前缀
2. 获取元数据 — 使用 [prefix]:get_screen 获取设计 JSON
3. 下载 HTML — GCS URL 需要使用可靠的下载器：

   bash scripts/fetch-stitch.sh "[htmlCode.downloadUrl]" "temp/source.html"
   

4. 视觉审查 — 重写前检查 screenshot.downloadUrl。在该 URL 后追加 =s0 可获取完整分辨率；原始 URL 无论 API 报告的 width/height 为何，提供的都是 512px 缩略图。

来自本地 HTML 文件：

mkdir -p temp && cp "path/to/design.html" temp/source.html

来自 URL：

bash scripts/fetch-stitch.sh "https://example.com/page" "temp/source.html"

尽管名字如此，该脚本其实是通用的强化下载器——它会跟随重定向、重试暂时性故障、处理 gzip，并在结果为空时明确报错。它不关心 URL 是否指向 Stitch。

**来自截图：**没有上传方式——Stitch MCP API 没有图像上传工具。你可以通过 stitch-mcp-generate-screen-from-text 根据文本提示重新创建设计，或者手动编写 HTML 并使用上述本地文件方式。

只有 Stitch 方式需要 API 密钥。转换本地文件或 URL 完全不需要 Google 账号。

步骤 2：决定使用 Server Component 还是 Client Component

对每个组件分别应用以下决策树，而不是按文件判断：

具有……	使用
onClick、onChange、useState、useEffect、动画	'use client'
只渲染数据，没有交互性	Server Component（无需指令）
封装 Client Component 库	'use client'
带有 Server Action 的表单	Server Component + <form action={serverAction}>

默认使用 Server Components。 只有在必要时才添加 'use client'。这是最具影响力的 App Router 模式。

步骤 3：组件架构

文件结构

app/
├── [route]/
│   ├── page.tsx              ← Server Component (route entry)
│   └── components/
│       ├── [Name].tsx        ← Logic-heavy Client Component
│       ├── [Name].module.css ← Scoped styles (optional)
│       └── index.ts          ← Re-exports
src/
├── components/
│   └── ui/                   ← Reusable primitives
├── data/
│   └── mockData.ts           ← Static content decoupled from components
└── types/
    └── index.ts              ← Shared TypeScript types

规则

• Props 约定：每个组件文件顶部都要有一个 Readonly<ComponentNameProps> 接口。
• 数据解耦：所有静态文本、图像 URL 和列表数据都放在 src/data/mockData.ts 中。组件通过 props 接收数据。
• 不要硬编码颜色：使用 CSS 自定义属性类（bg-[var(--color-primary)]）或语义化 Tailwind 令牌。切勿在 JSX 中使用任意十六进制颜色值。
• 不要使用内联样式：仅当值确实是动态值时例外（例如通过 JS 计算得出的宽度）。

第 4 步：使用 CSS 变量实现深色模式

本项目使用与 next-themes 配合的 CSS 变量方案。按以下顺序从源代码中解析颜色，然后将其映射到语义化令牌：

1. <head> 中的内联 tailwind.config（Stitch 生成的内容）——如果存在，直接使用。
2. 源代码中已有的 CSS 自定义属性（:root { --color-primary: ... }）——手写和模板化 HTML 中常见。
3. 外链或内联样式表——解析声明的颜色、字体系列、圆角和间距。
4. 最后手段——根据标记中出现频率最高的计算值推导令牌（主导背景色、文本颜色、强调色、标题/正文用字体、圆角），并告知用户推导结果，方便他们修正。

URL 路由只会下载单个 HTML 响应——外链样式表可能不会一并获取。如果以上方法都无法解析某个令牌，请明确说明，而不是自行编造配色方案。

在 app/globals.css 中：

:root {
  --color-background: #ffffff;
  --color-surface: #f4f4f5;
  --color-primary: /* dominant action color from the source */;
  --color-primary-foreground: #ffffff;
  --color-text: #09090b;
  --color-text-muted: #71717a;
  --color-border: #e4e4e7;
}

.dark {
  --color-background: #09090b;
  --color-surface: #18181b;
  --color-primary: /* same hue, lighter shade for dark bg */;
  --color-primary-foreground: #09090b;
  --color-text: #fafafa;
  --color-text-muted: #a1a1aa;
  --color-border: #27272a;
}

在 app/layout.tsx 中，使用来自 next-themes 的 ThemeProvider 包裹内容：

import { ThemeProvider } from 'next-themes'

export default function RootLayout({ children }: { children: React.ReactNode }) {
  return (
    <html lang="en" suppressHydrationWarning>
      <body>
        <ThemeProvider attribute="class" defaultTheme="system" enableSystem>
          {children}
        </ThemeProvider>
      </body>
    </html>
  )
}

第 5 步：响应式布局

所有组件都必须适配 sm（640px）、md（768px）、lg（1024px）和 xl（1280px）断点。

根据源设计应用以下模式：

• 导航：桌面导航使用 hidden md:flex，移动端汉堡菜单使用 flex md:hidden
• 网格：grid-cols-1 sm:grid-cols-2 lg:grid-cols-3——从单列开始
• 排版：text-2xl md:text-4xl——在较大屏幕上放大
• 内边距：px-4 md:px-8 lg:px-16——屏幕越宽，留白越多
• 图片：始终使用带有 sizes 属性的 next/image，以避免 CLS

第 6 步：无障碍基线

每个组件都必须默认包含以下内容：

• 语义化 HTML：使用 <nav>、<main>、<section>、<article>、<header>、<footer>——适合使用语义元素时，绝不使用 <div>。
• 交互元素：按钮使用 <button>，不要使用 <div onClick>。链接使用 <a> 或 next/link。
• 图片：<Image> 始终带有描述性 alt 属性。装饰性图片使用 alt=""。
• ARIA 标签：仅含图标的按钮需添加 aria-label。存在多个地标区域时，需为其添加 aria-label。
• 焦点环：没有自定义的 focus-visible:ring-* 替代样式时，绝不要使用 outline-none。
• 颜色对比度：不要在低对比度背景上使用低对比度文本——请自行检查对比度。

如果设计包含复杂交互（模态框、下拉菜单、标签页），请使用 stitch-a11y 技能进行完整审查。

第 7 步：执行步骤

1. 环境检查——如果缺少 node_modules，运行 npm install。
2. 数据层——根据设计内容创建 src/data/mockData.ts。
3. 组件起草——以 resources/component-template.tsx 为起点。将所有 StitchComponent 替换为实际组件名称。
4. 深色模式令牌——在 app/globals.css 中添加 CSS 变量声明。如果使用 stitch-design-system 技能，则改为导入生成的 design-tokens.css。
5. 应用接线——更新 app/page.tsx 或相关路由页面，以导入并渲染新组件。
6. 质量检查——在宣布完成前，按照 resources/architecture-checklist.md 逐项检查。
7. 开发验证——运行 npm run dev 并检查浅色和深色模式。

第 8 步：动画（可选）

如果源设计明确表达了动效意图（悬停状态、过渡、显现效果），请在组件构建完成后使用 stitch-animate 技能。不要临时随意添加动画——让该技能妥善处理，并确保符合 prefers-reduced-motion 要求。

故障排查

问题	解决方法
fetch 无法处理 GCS URL	在 bash 中始终用引号括起 URL：bash scripts/fetch-stitch.sh "$URL" out.html
深色模式下出现水合不匹配	将 suppressHydrationWarning 添加到 <html> 标签
找不到 next-themes	npm install next-themes
Server Component 使用了钩子	将组件移至单独的文件，并添加 'use client' 指令
深色模式下 CSS 变量未生效	确保 .dark 类位于 <html> 上，而非 <body>

与其他技能集成

• stitch-design-system — 先运行以生成 design-tokens.css。在 globals.css 中导入。
• stitch-animate — 随后运行，为生成的组件添加动效。
• stitch-a11y — 如果设计包含模态框、下拉菜单或复杂交互，则随后运行。

参考资料

• resources/component-template.tsx — 可用于生产环境的组件样板
• resources/architecture-checklist.md — 发布前质量检查清单
• scripts/fetch-stitch.sh — 可靠的 GCS HTML 下载器