prototype-implement

Imported from wanyusheng63-alt/vocab-learn (.codebuddy/skills/prototype-implement/SKILL.md). Install upstream with npx skills add wanyusheng63-alt/vocab-learn --skill prototype-implement. Copyright stays with the author.

name: prototype-implement description: Implement prototype with best practices, start's with "prototype" template, built for frontend-only prototypes WITHOUT backend/database. Use this skill for: URL cloning, screenshot-to-code, design mockups, landing pages, and UI prototypes. This skill will init codebase and provide useful template information. NOT for full-stack applications - use web-implement instead. _meta_type: template _meta_template_name: prototype

Prerequisites

Initialize Project Template (MANDATORY):

REPO_ROOT/.genie/scripts/bash/setup-project.sh prototype

Generate docs/product/features.md before writing any code (Mode 3 only — not needed for URL clone or screenshot modes).

Validation: If Mode 3 and docs/product/features.md does not exist, STOP and create it first.

Core Principles

• WHEN the user is greeting, asking questions, or having a conversation, THEN:
  • Do NOT rush into development
  • Respond with brief, helpful answers
  • Wait for clear development requests before invoking the agent
• Foundation First, Then Premium (分层设计理念):
  1. 🏗️ Foundation Layer: Structure must be correct - semantic HTML, proper layout, accessibility, interaction states
  2. 🎨 Premium Layer: Then pursue design excellence - distinctive aesthetics, atmospheric effects, premium polish
  • ⚠️ Never sacrifice structural correctness for visual effects
• Design Excellence: Leverage SKILL frontend-design for creative, distinctive interfaces that avoid generic AI aesthetics
• Code Quality (Optional): Use SKILL web-design-guidelines to audit generated code for accessibility, performance, best practices
• ⛔ NO UNICODE EMOJI: NEVER use Unicode emoji in generated code. This is a HARD RULE with ZERO tolerance.
• Parallel Tool Calls: Execute independent operations simultaneously
• Less is More: Quality over quantity, focus on pixel-perfect accuracy
• Multi-Page First: Proactively break down into multiple pages and ensure proper navigation

📖 Detailed UI/UX Rules: uiux-foundation.md

⛔ Hard Rules - Zero Tolerance

⛔⛔⛔ Tailwind CSS v4 Compatibility (CRITICAL)

🚨 Template uses Tailwind v4, syntax differs significantly from v3!

Using v3 syntax will cause styles to not apply at all!

⛔ v4 Deprecated/Renamed Classes:

⛔ v4 Default Value Changes (Common Pitfalls):

⛔ v4 Syntax Changes:

// ❌ Important modifier position (v3)
<div className="!flex !bg-red-500">
// ✅ v4: Exclamation mark goes after
<div className="flex! bg-red-500!">

// ❌ CSS variable reference (v3)
<div className="bg-[--brand-color]">
// ✅ v4: Use parentheses
<div className="bg-(--brand-color)">

// ❌ Grid comma separator (v3)
<div className="grid-cols-[max-content,auto]">
// ✅ v4: Use underscore
<div className="grid-cols-[max-content_auto]">

Pre-generation Checklist:

1. Do not use deprecated/renamed class names
2. Explicitly specify color and width for ring/border
3. Important modifier goes after class name (flex! not !flex)

⛔⛔⛔ Web Content Extraction (Mode 1 CRITICAL)

MUST use web_content_fetcher.py, WebFetch tool is FORBIDDEN!

# ✅ CORRECT
python3 scripts/web_content_fetcher.py <url>

# ❌ FORBIDDEN - WebFetch tool cannot handle SPA/dynamic pages

⛔⛔⛔ Unicode Emoji Prohibition (CRITICAL - Zero Tolerance)

🚨 This is a HARD RULE, violations are serious errors! This rule has been repeatedly violated, must pay special attention!

Generated code MUST NOT contain any Unicode emoji characters (e.g., 🚀 ✨ 📧 🎨 etc.)

Violating this rule = Task failure, must regenerate!

Unicode emoji degrades professional and premium feel, MUST use lucide-react icons or SVG instead:

// ❌ FORBIDDEN - Unicode emoji (Generating such code = Task failure)
<span>🚀 Launch Product</span>
<h2>🎨 Design System</h2>

// ✅ CORRECT - Lucide React icons
import { Rocket, Palette } from "lucide-react";
<span><Rocket className="w-5 h-5" /> Launch Product</span>
<h2><Palette className="w-6 h-6" /> Design System</h2>

⛔ Pre-generation Self-check:

1. Search code for Unicode emoji characters
2. If found, MUST replace with lucide-react icons
3. 不自查就提交 = 违反规则

例外情况：仅当用户明确要求使用 emoji 时才可使用。

Route Attributes (CRITICAL for pages.json)

Every Route in App.tsx MUST include these attributes:

// ✅ CORRECT - with data-genie attributes
<Route path="/" data-genie-key="Home" data-genie-title="Home Page" element={<Index />} />
<Route path="/about" data-genie-key="About" data-genie-title="About Us" element={<About />} />

// ❌ WRONG - missing data-genie attributes (pages.json will be empty!)
<Route path="/" element={<Index />} />

Componentization Rules (组件化规则)

Core Principle: 生成的代码应具备良好的可维护性、可复用性和可扩展性

Complexity Thresholds (复杂度阈值)

组件拆分决策树

页面 > 200 行？ ─Yes→ 拆分到 components/
                 │     ├─ 布局类 → layout/
                 │     ├─ 业务类 → [feature]/
                 │     └─ 通用类 → common/
                 └No→ useState > 3？ ─Yes→ 提取 hooks/
                                     └No→ 条件渲染 > 3层？ ─Yes→ 用查找表

第三方库强制使用

MUST DO (必须遵守)

1. Extract Sub-Components: 页面 > 200 行时，拆分为 Header/Content/Footer 等子组件
2. Extract Custom Hooks: 状态逻辑 > 30 行时，提取到 hooks/use-xxx.ts
3. Extract Types: 类型定义 > 10 行时，集中到 types/ 目录
4. Layout Components: Header/Footer 必须提取为共享组件，不允许每个页面重复
5. Lookup Tables: 条件渲染超过 3 个分支时，使用配置对象替代 if/else

Directory Structure (目录结构)

frontend/src/
├── components/
│   ├── ui/           # shadcn/ui (不修改)
│   ├── layout/       # Header, Footer, PageLayout
│   ├── common/       # Logo, SearchBar, UserAvatar
│   └── [feature]/    # product/, cart/, checkout/
├── hooks/            # use-cart.ts, use-auth.ts
├── types/            # product.ts, user.ts
├── data/             # mockProducts.ts (原型数据)
└── pages/            # 页面组件

📖 Detailed Patterns: componentization-patterns.md

Component Library Rules (React)

Core Concept: Component library provides structure and interactions, visual styles from design_system.json

Component Mapping Table

⛔⛔⛔ Animation Components (CRITICAL — Zero Tolerance)

🚨 此规则被反复违反！页面切换有动画但页面内容没有动画 = 任务失败！

模板预置了三个动画组件，必须全部使用：

⛔ 三层动画缺一不可！只用前两层 = 违反规则！

⛔ Navbar/Header/Sidebar 布局规则 (CRITICAL)

Navbar / Header / Sidebar / 任何共享布局组件必须放在 <AnimatedRoutes> 外部，否则每次页面切换都会：

• 销毁并重新创建这些组件
• 让这些组件参与页面过渡动画（抖动、闪烁、延迟）

// ✅ CORRECT App.tsx — Navbar outside AnimatedRoutes
<BrowserRouter>
  <Navbar />  {/* ✅ 在外部，不参与动画 */}
  <AnimatedRoutes>
    <Route path="/" element={<PageTransition><Home /></PageTransition>} />
    <Route path="/about" element={<PageTransition><About /></PageTransition>} />
  </AnimatedRoutes>
</BrowserRouter>

// ✅ Dashboard 布局 — Sidebar + Header outside AnimatedRoutes
<BrowserRouter>
  <div className="flex min-h-screen">
    <Sidebar />  {/* ✅ 在外部 */}
    <div className="flex-1 flex flex-col">
      <Header />  {/* ✅ 在外部 */}
      <main className="flex-1">
        <AnimatedRoutes>
          <Route path="/dashboard" element={<PageTransition><Dashboard /></PageTransition>} />
        </AnimatedRoutes>
      </main>
    </div>
  </div>
</BrowserRouter>

// ❌ WRONG — Navbar inside AnimatedRoutes (每次切换都闪烁)
<AnimatedRoutes>
  <Route path="/" element={<><Navbar /><Home /></>} />
</AnimatedRoutes>

// ❌ WRONG — Navbar inside each page (每次切换都重建)
function Dashboard() {
  return (<><Navbar /><main>...</main></>);
}

// ❌ WRONG — Sidebar inside PageTransition (参与动画)
<Route path="/dashboard" element={
  <PageTransition>
    <div className="flex">
      <Sidebar />
      <Dashboard />
    </div>
  </PageTransition>
} />

⛔ 页面内 MotionPrimitives 强制使用规则

// ✅ CORRECT - 页面内使用 MotionPrimitives
import { FadeIn, Stagger, HoverLift, fadeUp, motion } from "@/components/MotionPrimitives";

function HomePage() {
  return (
    <main>
      {/* Hero 区域 */}
      <FadeIn>
        <h1>Welcome</h1>
        <p>Description...</p>
      </FadeIn>
      
      {/* 特性卡片列表 - Stagger + HoverLift */}
      <Stagger className="grid grid-cols-3 gap-6">
        {features.map((f) => (
          <motion.div key={f.id} variants={fadeUp}>
            <HoverLift>
              <Card>{f.title}</Card>
            </HoverLift>
          </motion.div>
        ))}
      </Stagger>
      
      {/* CTA 按钮 */}
      <FadeIn delay={0.3}>
        <Button>Get Started</Button>
      </FadeIn>
    </main>
  );
}

// ❌ WRONG - 没有使用 MotionPrimitives，页面内容静态无动画
function HomePage() {
  return (
    <main>
      <h1>Welcome</h1>  {/* ❌ 没有 FadeIn */}
      <div className="grid grid-cols-3 gap-6">  {/* ❌ 没有 Stagger */}
        {features.map((f) => (
          <Card key={f.id}>{f.title}</Card>  {/* ❌ 没有 HoverLift */}
        ))}
      </div>
    </main>
  );
}

⛔ 生成页面组件前必须自查：

1. Navbar/Header/Sidebar 是否在 AnimatedRoutes 外部?
2. 是否导入了 FadeIn, Stagger, HoverLift from MotionPrimitives?
3. Hero/标题是否用 <FadeIn> 包裹?
4. 列表/网格是否用 <Stagger> 包裹，子元素是否有 variants={fadeUp}?
5. 卡片是否用 <HoverLift> 包裹?
6. 没有动画的静态组件 = 违反规则，必须重写！

Critical Rules (MANDATORY)

1. Component for Structure: Use shadcn/ui components, NOT HTML elements
2. Style from Design System: All visual styles from design_system.json, NOT component defaults
3. Navigation: Use React Router (<Link>), NOT <a href>
4. Form Validation: Use react-hook-form + zod, NOT manual useState
5. Toast: Use toast() from sonner, NOT alert() or hand-written Toast
6. Mobile Menu: Use <Sheet> component, NOT hand-written fixed div
7. Icons: Use lucide-react, NOT emoji or Unicode
8. No Unicode Emoji: Use SVG icons or lucide-react for all icons
9. Route Attributes: Every <Route> MUST have data-genie-key and data-genie-title

📖 Detailed Component Usage: frontend-patterns.md 📖 Animation Patterns: animation-patterns.md 📖 Creative Animations: Use ui-animation skill for ReactBits creative effects (Hero text, backgrounds, cursors)

Foundation vs Premium (分层设计理念)

⚠️ 常见错误：
❌ 只关注 Premium → 视觉花哨但结构混乱、交互缺失
❌ 只关注 Foundation → 结构正确但设计平庸、缺乏记忆点

✅ 正确做法：
Foundation 100% 正确 + Premium 主动拔高 = 专业且高端

📖 Detailed UI/UX Foundation: uiux-foundation.md 📖 Premium Design Guide: mode3-design-workflow.md

Three Modes of Operation

User Input
    │
    ├─ Has URL? ──────────────────→ Mode 1 (URL Clone) ⭐ 最高优先级
    │   (任何 http/https 链接)
    │
    ├─ Has screenshot/image? ─────→ Mode 2 (Screenshot to Code)
    │   ├─ Single image ──────────→ Mode 2a: Single Screenshot
    │   └─ Multiple images ───────→ Mode 2b: Multi-Screenshot
    │
    └─ Text requirements only? ───→ Mode 3 (Design from Requirements)
                                      └─ ⚠️ Invoke frontend-design skill!

⛔ Mode 判断优先级（严格遵守）

判断顺序：URL 检测 > 图片检测 > 关键词匹配

1. 有 URL → 一定是 Mode 1，不管用户说什么（"做个原型"、"帮我设计"都不影响）
2. 有截图/图片 → 一定是 Mode 2
3. 只有文字描述 → Mode 3

Mode Detection Keywords

High-Fidelity Principle (Mode 1 & Mode 2)

The core goal is pixel-perfect replication:

1. 📐 Structure Replication: Strictly replicate source DOM structure
2. 🎨 Visual Replication: Use exact color values from source
3. 🖼️ Resource Reuse: Prioritize source images/icons
4. 📝 Content Preservation: Keep ALL text/copy exactly as source
5. ✨ Interaction Replication: Preserve hover effects, animations, transitions

📖 Detailed Workflows: code-generation-rules.md

Output Requirements

Default Output by Mode

⛔ MANDATORY Generation Order

Mode 1 (URL Clone) - 6 Phase 严格顺序:

Phase 1: Web Content Extraction
         → python3 scripts/web_content_fetcher.py <url>

Phase 2: 读取关键文件 (⛔ 强制，不可跳过)
         → cat clone_blueprint.md
         → cat image_manifest.json
         → cat element_colors.json

Phase 3: Structure Analysis (⛔ 必须输出文件)
         → 输出: <domain>_content/structure_analysis.md

Phase 4: React Code Generation
         → 对照 structure_analysis.md 逐 Section 生成
         → 图片路径从 image_manifest.json 查表

Phase 5: Blueprint Validation (⛔ 强制执行)
         → python3 scripts/validate_clone.py
         → 修复 CRITICAL 问题直到 PASS/WARN

Phase 6: Build & Preview
         → npm run build

Mode 2 (Screenshot) - 4 Phase:

Phase 1: Design System Extraction (扩展版)
         → AI 视觉分析截图
         → 输出: docs/design_system.json (必须包含 gradients/shadows/effects)

Phase 2: Structure Analysis (思考步骤)
         → 分析布局、组件层级、交互元素

Phase 3: React Code Generation + Image Replacement
         → ⛔ 代码生成时强制对照截图还原风格
         → python3 scripts/search_images.py --dir frontend/src/pages
         → 验证: grep 无 placehold.co 残留

Phase 4: Build & Preview
         → npm run build

风格提取方法 (Mode 2 Phase 1 思考步骤)

Mode 3 (Requirements) - 4 Phase:

Phase 0: Design System
         → 调用 frontend-design / ui-ux-pro-max skill
         → 输出: docs/design_system.json

Phase 1: Component Decision (思考步骤)

Phase 2: Generate React + Image Replacement
         → python3 scripts/search_images.py --dir frontend/src/pages
         → 验证: grep 无 placehold.co 残留

Phase 3: Build & Preview
         → npm run build

⚠️ Mode 1 (6 Phase) 还原度要求最高，Mode 2/3 (5 Phase) 相对简化。

Output Structure (All Modes)

REPO_ROOT/
├── docs/
│   ├── design_system.json          ← Design system (ALL MODES)
│   └── product/
│       └── features.md             ← Feature documentation
├── frontend/
│   └── src/pages/*.tsx             ← React pages (ALL MODES)
└── <domain>_content/               ← Mode 1 only: Fetched content
    ├── source.html
    ├── structure_analysis.md       ← Mode 1 必须输出
    ├── clone_blueprint.md
    ├── element_colors.json
    ├── image_manifest.json
    └── css/

路径说明：

• docs/design_system.json - 设计系统文件（所有 Mode 共用）
• frontend/src/pages/ - React 页面组件（所有 Mode）

Design System JSON Schema

基础版 (All Modes):

{
  "meta": {
    "project_name": "Project Name",
    "source_mode": "url_clone | screenshot | requirements",
    "style": "minimalist | tech | luxury | etc."
  },
  "colors": {
    "primary": "#HEX",
    "secondary": "#HEX",
    "accent": "#HEX",
    "background": "#HEX",
    "surface": "#HEX",
    "text_primary": "#HEX",
    "text_secondary": "#HEX",
    "border": "#HEX"
  },
  "typography": {
    "font_primary": "Font Name",
    "font_display": "Font Name",
    "sizes": { "h1": "48px", "h2": "36px", "h3": "24px", "body": "16px" }
  },
  "spacing": { "unit": 4, "scale": [4, 8, 16, 24, 32, 48, 64] },
  "border_radius": { "sm": "4px", "md": "8px", "lg": "16px" }
}

扩展版 (Mode 2 必须包含):

{
  "meta": { "..." },
  "colors": { "..." },
  "typography": { "..." },
  "spacing": { "..." },
  "border_radius": { "..." },
  
  "gradients": {
    "primary": "linear-gradient(135deg, #667eea 0%, #764ba2 100%)",
    "hero_bg": "linear-gradient(180deg, #0a0a0a 0%, #1a1a2e 100%)",
    "card_overlay": "linear-gradient(to bottom, transparent 0%, rgba(0,0,0,0.8) 100%)"
  },
  "shadows": {
    "card": "0 4px 6px -1px rgba(0,0,0,0.1), 0 2px 4px -1px rgba(0,0,0,0.06)",
    "card_hover": "0 20px 25px -5px rgba(0,0,0,0.1), 0 10px 10px -5px rgba(0,0,0,0.04)",
    "button": "0 4px 14px 0 rgba(102, 126, 234, 0.39)",
    "glow": "0 0 40px rgba(102, 126, 234, 0.4)"
  },
  "effects": {
    "blur": { "sm": "4px", "md": "8px", "lg": "16px" },
    "opacity": { "overlay": 0.8, "disabled": 0.5 },
    "backdrop_blur": "blur(12px)"
  },
  "transitions": {
    "default": "all 0.3s ease",
    "fast": "all 0.15s ease",
    "slow": "all 0.5s ease",
    "spring": "all 0.4s cubic-bezier(0.34, 1.56, 0.64, 1)"
  },
  "section_styles": [
    {
      "name": "Hero",
      "background": "gradient:hero_bg",
      "text_color": "#FFFFFF",
      "special_effects": ["glow", "particles"]
    },
    {
      "name": "Features",
      "background": "#FFFFFF",
      "text_color": "#1a1a2e",
      "card_style": "glass"
    }
  ]
}

Mode Workflows (Overview)

Mode 1: URL Clone → 调用 url-clone Sub-Agent

⛔ 触发条件：用户输入包含 URL (http/https)

有 URL 就是 Mode 1，不管用户说什么（"做原型"、"帮我设计"、"复刻"都不影响）

Goal: 100% 1:1 pixel-perfect replication of source site

调用方式

检测到 URL 后，立即委派给 url-clone sub-agent：

当用户输入包含 http:// 或 https:// 时：
1. 识别为 Mode 1
2. 获取当前项目路径：运行 pwd 或使用已知路径
3. 调用 url-clone sub-agent
4. ⚠️ 必须在调用时明确告知项目路径！
   格式："项目路径: /absolute/path/to/project"
5. 传递 URL 参数
6. 等待 sub-agent 完成

⛔ 重要：必须告知 sub-agent 项目路径，否则文件可能生成到错误目录！

Sub-Agent 职责

url-clone sub-agent 负责完整的克隆流程：

核心原则（Sub-Agent 遵守）

⛔ 这是数据转换任务，不是内容创作！

✅ 引号内文案 → 原样复制，一字不改
✅ 颜色值 → 使用精确 HEX，禁止 Tailwind 近似
✅ 图片路径 → 从 manifest 查表，禁止编造

❌ 禁止"发挥"或"改写"文案
❌ 禁止用 bg-black 替代 #0a0a0f
❌ 禁止调用 frontend-design skill

进度跟踪

Sub-agent 会在 <domain>_content/progress.md 中记录进度：

## Section 进度
| # | Section | 状态 | 自检 |
|---|---------|------|------|
| 1 | header | ✅ 完成 | 文案✓ 颜色✓ |
| 2 | hero | ⏳ 进行中 | - |
| 3 | features | ⬜ 待处理 | - |

完成标准

Sub-agent 完成后会报告：

• 生成的 Section 数量
• 生成的页面数量
• npm run build 是否成功
• 任何需要注意的问题

错误处理

如果 sub-agent 执行失败：

1. 检查 progress.md 确定失败位置
2. 查看失败 Section 的自检记录
3. 可以从失败点重新调用 sub-agent 继续

📖 Sub-Agent 详细规则: ../../../agents/url-clone.md

Mode 2: Screenshot to Code

⛔ 触发条件：用户提供了截图/图片，但没有 URL

有图片就是 Mode 2（前提是没有 URL，URL 优先级更高）

Goal: Pixel-perfect reproduction of design mockup (设计风格 + UI 结构)

⚡ Mode 2 只输出 React，不生成 HTML 原型

Phase 1: Design System Extraction (扩展版)
         → AI 视觉分析截图，提取完整设计系统
         → 输出: docs/design_system.json (必须包含 gradients/shadows/effects)

Phase 2: Structure Analysis (思考步骤)
         → 分析截图的布局、组件层级、交互元素
         → 不输出文件，在生成前完成

Phase 3: React Code Generation + Image Replacement
         → ⛔ 边看截图边写代码，确保风格还原
         → 执行: python3 scripts/search_images.py --dir frontend/src/pages
         → 验证: grep -r "placehold.co" frontend/src/ 必须返回空

Phase 4: Build & Preview
         → npm run build 验证编译

⛔⛔⛔ CRITICAL: Mode 2 风格还原核心约束

🚨 截图模式最常见的问题：UI 结构对了，但风格丢失！

原因：AI 倾向于用 Tailwind 默认值近似，而不是还原截图中的精确样式。

Phase 1: design_system.json 扩展版 (MANDATORY)

Mode 2 的 design_system.json 必须包含以下扩展字段：

{
  "meta": { "source_mode": "screenshot", "..." },
  "colors": { "primary": "#667eea", "..." },
  "typography": { "..." },
  
  "gradients": {
    "primary": "linear-gradient(135deg, #667eea 0%, #764ba2 100%)",
    "hero_bg": "linear-gradient(180deg, #0a0a0a 0%, #1a1a2e 100%)",
    "glow": "radial-gradient(circle at 80% 20%, rgba(102,126,234,0.3) 0%, transparent 50%)"
  },
  "shadows": {
    "card": "0 4px 6px -1px rgba(0,0,0,0.1)",
    "card_hover": "0 20px 25px -5px rgba(0,0,0,0.1)",
    "button": "0 4px 14px 0 rgba(102,126,234,0.39)"
  },
  "effects": {
    "glass": "backdrop-filter: blur(12px); background: rgba(255,255,255,0.1)",
    "glow": "box-shadow: 0 0 40px rgba(102,126,234,0.4)"
  }
}

Phase 3: 代码生成风格约束 (CRITICAL)

⛔ 写代码时必须遵守以下规则：

规则 1: 渐变必须用 style 属性

// ❌ WRONG - Tailwind 没有精确渐变，会丢失风格
<section className="bg-gradient-to-b from-gray-900 to-gray-800">

// ✅ CORRECT - 用 style 还原截图中的精确渐变
<section style={{ background: 'linear-gradient(180deg, #0a0a0a 0%, #1a1a2e 100%)' }}>

规则 2: 阴影必须用精确值

// ❌ WRONG - shadow-lg 是 Tailwind 默认值，不是截图中的阴影
<div className="shadow-lg">

// ✅ CORRECT - 用 style 或自定义类还原精确阴影
<div style={{ boxShadow: '0 4px 14px 0 rgba(102,126,234,0.39)' }}>

规则 3: Hover 效果必须实现

// ❌ WRONG - 没有 hover 效果，交互感缺失
<button className="bg-purple-500 rounded-full">

// ✅ CORRECT - 完整的 hover 效果
<button 
  className="rounded-full text-white transition-all duration-200 hover:-translate-y-0.5"
  style={{
    background: 'linear-gradient(135deg, #667eea 0%, #764ba2 100%)',
    boxShadow: '0 4px 14px 0 rgba(102,126,234,0.39)'
  }}
>

规则 4: 光效装饰必须还原

// ❌ WRONG - 忽略了截图中的光效装饰
<section className="bg-black">
  <h1>Title</h1>
</section>

// ✅ CORRECT - 还原光效
<section className="relative" style={{ background: 'linear-gradient(180deg, #0a0a0a 0%, #1a1a2e 100%)' }}>
  {/* 光效装饰 */}
  <div 
    className="absolute top-0 right-0 w-1/2 h-1/2 pointer-events-none"
    style={{ background: 'radial-gradient(circle at 80% 20%, rgba(102,126,234,0.3) 0%, transparent 50%)' }}
  />
  <h1>Title</h1>
</section>

风格还原自查清单

每写完一个 Section，必须自查：

• 背景是渐变还是纯色？渐变方向对吗？
• 阴影深度对吗？有 hover 加深效果吗？
• 有没有光效/光晕装饰？
• 按钮是圆角还是全圆角？有阴影吗？
• 卡片有没有玻璃态/模糊效果？
• 整体色调和截图一致吗？

⚠️ alt 属性写法要求：

// ❌ 错误 - 太模糊，搜不到好图
<img src="https://placehold.co/600x400" alt="image" />

// ✅ 正确 - 具体描述，能搜到合适的图
<img src="https://placehold.co/600x400" alt="Professional team meeting in modern office" />
<img src="https://placehold.co/400x400" alt="Young woman smiling portrait" />

⚠️ 交互体验推断 (Mode 2 特有)

截图只展示静态画面，必须基于视觉线索推断合理的交互体验。

推断原则：

• 合理性：交互设计应符合用户直觉和行业惯例
• 完整性：所有可交互元素都应有对应的交互行为
• 反馈性：每个操作都应有视觉/状态反馈

📖 Detailed Workflow: code-generation-rules.md

Mode 3: Design from Requirements

⛔ 触发条件：只有文字描述，没有 URL 也没有图片

⚠️ 如果用户输入包含 URL → 走 Mode 1，不是 Mode 3！

Goal: Create distinctive, memorable interfaces from text requirements

⚡ Mode 3 只输出 React，不生成 HTML 原型

⛔⛔⛔ Mode 3 必读 (MANDATORY BEFORE CODING)

🚨 Mode 3 必须先完成设计系统创建，跳过设计步骤会导致产品方向偏差！

1. 调用 frontend-design skill 获取创意方向（必选，Phase 0）
2. 阅读 mode3-design-workflow.md 的"PC/移动端高端感要点"
3. 确定"记忆点": 独特布局/字体处理/标志动画/大胆配色

Phase 0: Design Thinking (MANDATORY)
         → 调用 SKILL `frontend-design` 获取创意方向
         → 调用 SKILL `ui-ux-pro-max` 搜索风格/配色/字体
         → 输出: docs/design_system.json

Phase 1: Component Decision (思考步骤)
         → 对照组件语义决策矩阵选择正确组件
         → 不输出文件，在生成前完成

Phase 2: React Code Generation + Image Replacement (合并步骤)
         → 生成所有页面 .tsx 文件 (placehold.co + 详细 alt)
         → 执行: python3 scripts/search_images.py --dir frontend/src/pages
         → 验证: grep -r "placehold.co" frontend/src/ 必须返回空

Phase 3: Build & Preview
         → npm run build

⛔ 组件语义决策 (Phase 1 - CRITICAL)

错误的组件选型会导致 UI 结构走样！

📊 数据展示 - 用户如何浏览？

📦 容器 - 操作复杂度？

常见错误：

⭐ 高端设计质感 (CRITICAL)

高端 = 克制 + 细节，不是堆砌效果

6 大核心要素（❌ 平庸 vs ✅ 高端）：

⛔ 常见错误：

交互组件要求

📖 详细规则: mode3-design-workflow.md

React Template (Overview)

Prototype vs Full Application

Multi-Page First

⛔ Forbidden: Stuffing all content into one page component
✅ Required: Each navigation link corresponds to an independent page file

Structure Source by Mode

Key Steps

1. Copy Images: cp -r <project>_content/images/* frontend/public/images/
2. Build Verification: cd frontend && npm run build 2>&1 (auto-fix max 3 times)

📖 Detailed Workflow: react-template-workflow.md

Quick Checklist

⛔ 最小必检清单 (交付前 30 秒 - MUST CHECK)

所有 Mode:

• grep -r "placehold.co" frontend/src/ 返回空
• 无 Unicode emoji (🚀✨📧 等) - 用 lucide-react 替代
• npm run build 成功
• 每个 <Route> 有 data-genie-key 和 data-genie-title
• Header/Footer 提取为共享组件
• 无手写 <button>/<input>，全部用 shadcn/ui

Mode 1 专属 (由 url-clone sub-agent 处理):

• Sub-agent 已完成（检查 progress.md 所有 Section 为 ✅）
• 图片路径从 image_manifest.json 查表
• 文案与 section 文件完全一致

Mode 2 专属:

• design_system.json 包含 gradients/shadows/effects
• 渐变/阴影用 style 属性（非 Tailwind 类）

Mode 3 专属:

• 已调用 frontend-design 或 ui-ux-pro-max skill
• 有明确的设计方向和记忆点

Mode 1: url-clone Sub-Agent 检查 (由 sub-agent 自动执行)

Mode 1 委派给 url-clone sub-agent 处理，以下检查由 sub-agent 自动完成。 主 agent 只需检查 progress.md 确认所有 Section 完成。

• 🔴 progress.md 所有 Section 标记为 ✅
• 🔴 文案完全一致 - 引号内文字原样复制
• 🔴 颜色使用精确值 - 禁止 Tailwind 近似色
• 🔴 图片路径从 manifest 查表 - 禁止编造

Mode 2 Phase 1: Design System Extraction (扩展版)

• 🔴 design_system.json 包含 gradients: 至少提取 2-3 个渐变
• 🔴 design_system.json 包含 shadows: 卡片/按钮/悬停阴影
• 🔴 design_system.json 包含 effects: blur/opacity/backdrop

Mode 2 风格还原 (CRITICAL)

• 🔴 渐变用 style 属性: style={{ background: 'linear-gradient(...)' }}
• 🔴 阴影用精确值: style={{ boxShadow: '0 4px 14px ...' }}
• 🔴 hover 效果完整: transition-all + hover:-translate-y-0.5
• 🔴 光效装饰还原: 截图中有光晕/渐变装饰要实现
• 🔴 禁止 Tailwind 默认值: 不用 blue-500, gray-900, shadow-lg 等
• 🔴 渐变还原: Hero/按钮渐变与截图一致
• 🔴 特效还原: 光晕/模糊/玻璃态效果
• 🔴 色调一致: 整体配色氛围与截图一致

Mode 1 Clone Fidelity (CRITICAL)

• 🔴 对照 structure_analysis.md 生成代码
• 🔴 背景色正确: 浅色区域用 bg-white，深色用 bg-black
• 🔴 布局方向正确: 横排用 flex-row/grid-cols-3，竖排用 flex-col
• 🔴 SVG 已提取: Logo 使用 SVG 组件，不是文字
• 🔴 CSS 合并: 使用 css_merger.py 脚本（自动过滤第三方库）
• 🔴 字体精确值: h1 使用精确像素值（非 text-6xl）
• 🔴 original.css imported in App.tsx
• 🔴 Copy/text content 100% verbatim from source

Componentization (CRITICAL)

• 🔴 单个组件不超过 200 行
• 🔴 复杂状态逻辑提取到自定义 Hook
• 🔴 Header/Footer 使用共享组件，不重复
• 🔴 条件渲染使用查找表，不超过 3 层 if/else

Design System Compliance (CRITICAL)

• 🔴 Read design_system.json before generating code
• 🔴 Mode 1: Use ALL colors from element_colors.json - 不只是 primary/secondary/accent
• 🔴 Mode 2: Use gradients/shadows/effects from design_system.json
• 🔴 No Tailwind default colors used (blue-500, etc.)

Tailwind v4 Compatibility (CRITICAL)

• 🔴 废弃类名: 不用 flex-grow/flex-shrink/shadow-sm/rounded-sm/blur-sm
• 🔴 v4 替代: 用 grow/shrink/shadow-xs/rounded-xs/blur-xs
• 🔴 ring/border: 显式指定颜色 ring-3 ring-blue-500 / border border-gray-200
• 🔴 Important: 放后面 flex! 不是 !flex
• 🔴 验证: 生成后检查样式是否正确渲染

Mode 1 Multi-Page (CRITICAL)

• 🔴 Analyzed source navigation structure
• 🔴 Generated ALL pages from nav links (minimum 5-8 pages)
• 🔴 Each nav link has independent .tsx file
• 🔴 App.tsx contains routes for ALL pages
• 🔴 All pages share same Header/Footer components

Navigation System

• 🟠 Every nav link has corresponding page
• 🟠 All pages share same design system
• 🟡 Browser back/forward works

Image Assets (与代码生成合并)

• 🔴 Mode 1: 图片路径从 image_manifest.json 查表获取
• 🔴 Mode 2/3: 每写完一个 .tsx 立即执行 search_images.py
• 🔴 Mode 2/3 alt 描述: 必须具体描述图片内容，不能写 "image" 或 "photo"
  • ❌ alt="image" / alt="photo" / alt="placeholder"
  • ✅ alt="Professional team meeting in modern office"
  • ✅ alt="Young woman smiling portrait"
• 🔴 验证: grep -r "placehold.co" frontend/src/ 返回空

Mode 2 Interaction Inference (截图模式交互推断)

• 🔴 视觉线索分析: 头像排列、Tab 样式、卡片探出等
• 🔴 推断合理交互: 选择器、Tab、轮播、展开收起
• 🔴 状态反馈: hover/active/focus 状态

Mode 3 (组件决策 + 高端设计 - CRITICAL)

• 🔴 组件选型: 列表用 List Item / 展示用 Card / 确认用 Dialog / 表单用 Sheet
• 🔴 视觉层次: 4层深度 (背景→内容→交互→聚焦)
• 🔴 质感纹理: backdrop-blur + shadow + border-white/10
• 🔴 配色克制: ≤3色相，1强调色+中性灰
• 🔴 动效节奏: 微交互150ms / 状态300ms / 入场500ms
• 🔴 交互反馈: hover状态 / Toast / 骨架屏 / Sheet菜单

⛔ FINAL CHECK: No Unicode Emoji

Before submitting ANY code, search for:
🚀 ✨ 🎨 📧 ✅ ❌ 💡 ⭐ 🔒 📊 📱 🎯 🔥 💪 👍 ❤️ ... (ANY emoji)

• 🔴 CRITICAL: Searched entire codebase for Unicode emoji
• 🔴 CRITICAL: All emoji replaced with lucide-react icons

📖 Complete Checklist: quality-checklist.md

Technical References

Core Workflow Guides

• componentization-patterns.md: Component extraction, hooks, file organization, composition patterns
• interactive-prototype.md: React interactive patterns (Dialog, Sheet, Form, Toast)
• react-template-workflow.md: React project structure, compilation verification
• frontend-patterns.md: shadcn/ui component mapping, forbidden patterns
• mode3-design-workflow.md: Design from requirements workflow, premium design guide
• code-generation-rules.md: Strict rules for colors, images, measurements
• uiux-foundation.md: Layout, interaction, accessibility, animation rules

External Skills (Invoke as needed)

• SKILL frontend-design: Creative design guidance for distinctive interfaces
• SKILL web-design-guidelines: Code quality audit for accessibility, performance, best practices

Design & Layout

• design_system_extraction.md: Design token extraction
• layout_precision_guide.md: Pixel-perfect layout techniques
• typography_guide.md: Font extraction and matching

Quality & Animation

• quality-checklist.md: Pre-delivery validation checklist, React component compliance
• animation-patterns.md: CSS animation patterns

Scripts Reference

All scripts are located in the scripts/ directory relative to this skill.

⚠️ Note: Interactive Prototype phase prohibits calling Python scripts, other phases can use scripts normally.