11 - UI 开发策略

1. 核心原则

功能骨架先行 → 丑但能用 → 验证商业价值 → AI 一轮美化

理由：

50% 的功能上线后发现不需要，早期美化 = 浪费
AI 美化 UI 的效率极高，一轮对话翻新一个页面
shadcn/ui 默认样式已经足够专业，不像毛坯房

2. Web 端技术栈

只需要这一套，不引入其他 UI 库：

工具	用途	为什么选它
shadcn/ui	组件库	复制到项目中完全可控，默认样式专业，后期改源码不受制于库
Tailwind CSS	样式	AI 写 Tailwind 极其熟练，实用类不需要命名
Radix UI	无头组件	shadcn 底层，交互逻辑完备（键盘导航、无障碍）
Lucide	图标	和 shadcn 风格一致，按需导入

为什么不选 Ant Design / MUI / Chakra

	shadcn/ui	Ant Design / MUI
代码归属	复制到你项目里，完全可控	在 node_modules，受制于库的版本
后期美化	直接改组件源码	要和库的样式系统对抗
AI 兼容性	AI 对 Tailwind 极其熟练	AI 经常写出过时的 API 用法
包体积	按需引入，零冗余	整包较重
默认样式	简洁现代	明显的"后台管理系统"味道

3. 移动端技术栈选型

根据需求复杂度选择，从轻到重：

方案一：响应式 Web（最轻，推荐起步）

适用：不需要原生能力（摄像头、推送、离线）
技术：Next.js + Tailwind 响应式 + PWA
成本：零额外技术栈，只需加响应式样式

做法：在现有 Next.js 项目上加 Tailwind 响应式断点即可。

typescript

// 已有的 PC 页面
<div className="grid grid-cols-4 gap-6">

// 加上移动端适配
<div className="grid grid-cols-1 md:grid-cols-2 lg:grid-cols-4 gap-4 md:gap-6">

加 PWA 支持（可安装到手机桌面）：

typescript

// next.config.js + next-pwa
const withPWA = require('next-pwa')({ dest: 'public' })
module.exports = withPWA({ /* next config */ })

优点：零学习成本，一套代码，AI 处理响应式很熟练缺点：无法调用原生能力，体验不如原生 App

方案二：React Native + Expo（原生体验，推荐正式移动端）

适用：需要原生体验、推送通知、摄像头等
技术：React Native + Expo + NativeWind
成本：新项目，但复用 React 技能和后端 API

为什么选 Expo 而不是裸 React Native：

	Expo	裸 React Native
环境搭建	`npx create-expo-app` 即用	需要配 Xcode + Android Studio
构建发布	EAS Build 云端构建	本地构建，环境问题多
原生模块	Expo SDK 覆盖 90% 常用能力	需要手动 link 原生模块
AI 开发效率	高，结构简单	中，原生桥接问题 AI 容易出错
热更新	EAS Update 支持 OTA 更新	需要 CodePush 等第三方

移动端 UI 组件库选择：

库	定位	推荐度
NativeWind	在 React Native 中用 Tailwind 语法	强烈推荐 — AI 写 Tailwind 最熟练，Web 端经验直接复用
Tamagui	Web + Native 通用组件	推荐 — 如果需要 Web 和 Native 共享组件
React Native Paper	Material Design 组件	可选 — 类似 shadcn 的开箱即用
Gluestack UI	NativeBase 继任者	可选 — 组件丰富，文档完善

推荐组合：

Expo + NativeWind + React Native Paper

理由：

Expo 简化构建和发布
NativeWind 让你用 Tailwind 写样式（和 Web 端一致，AI 效率最高）
React Native Paper 提供开箱即用的组件（类似移动端的 shadcn）

项目结构：

mobile-app/                    # 独立项目，复用后端 API
├── app/                       # Expo Router（类似 Next.js App Router）
│   ├── (tabs)/                # Tab 导航
│   │   ├── index.tsx          # 首页
│   │   ├── search.tsx         # 搜索
│   │   └── profile.tsx        # 个人中心
│   ├── _layout.tsx            # 根布局
│   └── [id].tsx               # 动态路由
├── components/                # 组件
├── services/                  # API 调用（复用后端接口）
├── hooks/                     # 自定义 Hooks
└── types/                     # 类型定义（可从 Web 端复制）

方案三：Capacitor（Web 套壳，折中方案）

适用：已有 Web 应用，想快速上架 App Store
技术：Next.js + Capacitor
成本：在现有 Web 项目上加壳，改动最小

bash

npm install @capacitor/core @capacitor/cli
npx cap init
npx cap add ios
npx cap add android

优点：现有 Web 代码几乎不改，能调用部分原生能力缺点：性能和体验不如 React Native，复杂交互有卡顿

方案四：Taro（推荐国内多端场景）

适用：需要微信小程序 + H5，可选 React Native
技术：Taro 3.x + React + NutUI
成本：一套代码编译到多端，React 技能直接复用

为什么选 Taro：

	Taro	uni-app
语法	React/Vue 均支持，推荐 React	Vue 为主
TypeScript	原生支持，开发体验好	支持但生态偏弱
小程序	微信/支付宝/百度/字节全覆盖	同样全覆盖
AI 兼容性	React 语法 AI 最熟练	Vue 语法 AI 也熟练
社区	京东维护，中文生态完善	DCloud 维护，中文生态完善

推荐组合：

Taro 3.x + React + NutUI + TypeScript

项目结构：

taro-app/
├── src/
│   ├── pages/              # 页面
│   │   ├── index/
│   │   └── detail/
│   ├── components/         # 组件
│   ├── services/           # API 调用（复用后端接口）
│   ├── types/              # 类型定义
│   └── app.config.ts       # 多端配置
├── config/                 # 编译配置
└── project.config.json     # 小程序项目配置

优点：一套代码多端运行，React 生态 + 中文社区完善缺点：复杂原生能力不如 React Native，调试链路较长

选择决策树

需要移动端吗？
├── 不确定 → 先做响应式 Web + PWA（方案一）
├── 需要微信小程序 → Taro（方案四，推荐国内场景）
├── 需要上架 App Store，原生要求不高 → Capacitor 套壳（方案三）
└── 需要原生体验/推送/摄像头 → React Native + Expo（方案二）

4. 三阶段 UI 开发工作流

第一阶段：功能骨架（不关心好不好看）

目标：数据流跑通，交互逻辑正确。

提示词：
"用 shadcn/ui 实现 [页面名] 页面的功能骨架：
- 数据展示用 Table
- 表单用 Form + zod 校验
- 操作反馈用 Toast
- 不需要花时间在样式上，能用就行
- 先跑通数据流：组件 → API → Service → 数据库"

防止 AI 过度设计的关键提示词：

功能优先，不要花时间在样式上。
使用 shadcn/ui 默认样式，不要自定义。
只做 [具体功能]，不要加额外的 UI 优化。
不要加动画、渐变、阴影等装饰性样式。

这个阶段的组件选择：

要展示列表     → Table（简单）/ DataTable（带分页排序）
要用户填表     → Form + zod
要确认操作     → AlertDialog（危险操作）/ Dialog（普通弹窗）
要反馈结果     → Toast
要选择选项     → Select（单选）/ Combobox（可搜索）
要开关设置     → Switch
要导航菜单     → 顶部 NavigationMenu / 侧边 Sidebar
要展示卡片     → Card
要加载等待     → Skeleton
要标签分类     → Badge
要分步操作     → Tabs

每个页面必须处理三种状态：

tsx

// 加载中
if (isLoading) return <Skeleton />

// 空数据
if (data.length === 0) return <EmptyState message="暂无数据" />

// 错误
if (error) return <Alert variant="destructive">{error.message}</Alert>

// 正常展示
return <DataTable data={data} />

第二阶段：功能验证（跑真数据）

关注：数据流正确、校验完整、错误状态处理不关注：颜色、间距、动画、响应式

第三阶段：UI 美化（功能稳定后）

执行者交接：Phase 1-2 由 Developer Agent 完成，Phase 3 交给 Designer Agent。Designer Agent 会先跑视觉诊断清单（agents/designer/knowledge/visual-checklist.md）修高频问题，再按风格预设或 design-spec 做整体美化。

这是 AI 效率最高的环节。功能已经稳定，改的是样式不是逻辑，风险很低。详细的美化方法论、6 套风格预设和工具配置见 doc-24 UI 美化指南。

推荐做法：先用 /product-design 生成 docs/design-spec.md，AI 美化时直接读取 Token 系统获取确定的色值/间距/字体，多页面视觉自动统一。无 design-spec.md 时回退到自然语言描述（每次会话可能不一致）。

提示词模板（有 design-spec.md 时）：
"按 docs/design-spec.md 的 Token 系统做 UI 美化，保持现有功能不变，只改样式，加基础响应式"

提示词模板（无 design-spec.md 时）：
"对整个应用做 UI 美化：风格简洁现代，配色中性灰 + [强调色]，优化间距/字体/颜色统一，加基础响应式，保持功能不变"

提示词模板（单页面美化）：
"美化 [页面名] 页面：
- 参考 [网站/截图]（如果有）
- 重点优化视觉层次和间距
- 不改功能逻辑"

如果需要更精细的风格控制，使用 ui-ux-pro-max Skill：

"用 ui-ux-pro-max 给这个应用做整体美化，
风格：minimalism，配色方案：slate + blue accent"

设计参考资源

美化阶段需要设计参考。核心原则：选有现成代码实现的设计系统作基础，再用截图参考指导风格，AI 还原度最高。

可直接出代码的组件库

资源	链接	用途
shadcn/ui	ui.shadcn.com	首选组件库，复制粘贴即用
Magic UI	magicui.design	动效组件，适合有动画的界面
Aceternity UI	ui.aceternity.com	炫酷现代组件，含现成代码
Tailwind UI	tailwindui.com	官方付费组件库，设计模式可参考

AI 编程专用工具

工具	链接	用途
v0.dev	v0.dev	Vercel 出品，自然语言生成 React UI，可直接复制代码或作参考
21st.dev	21st.dev	AI 友好的组件集合
Realtime Colors	realtimecolors.com	预览配色在真实页面的效果，选好色值告诉 AI

截图参考来源

来源	链接	最佳用法
Mobbin	mobbin.com	截取真实 App 界面，让 AI "照这个风格做"
Godly	godly.website	截取网页设计，让 AI 还原布局
Dribbble	dribbble.com	搜具体场景（dashboard UI、pricing page），截图作 prompt
Figma Community	figma.com/community	免费 UI Kit，截图给 AI 生成对应代码

Figma MCP 工作流

配置 Figma MCP 后（见 doc-05 §4.2），支持设计稿与代码的双向流转。

Figma → Code（Design-to-Code）：

在 Figma 选中目标 Frame → 复制链接 → 粘贴到 Claude Code → AI 自动调用 get_design_context（结构化布局）+ get_screenshot（视觉参考）→ 审查生成代码 → Playwright 截图对比验证还原度。

Code → Figma（2026 新能力，需 Remote MCP）：

调用 generate_figma_design 将运行中的 UI 推送到 Figma → 设计师在 Figma 标注/精修 → 开发者通过 MCP 拉取更新继续迭代。

Code Connect — 组件映射桥梁：

设置后 MCP 响应包含真实 import 语句和属性映射，AI 直接复用已有组件：

无代码方式：Figma 内 Code Connect UI 面板，为组件绑定代码片段
CLI 方式：npx figma connect setup → 编写映射文件 → npx figma connect publish
自定义指令：在 Figma 组件上添加 "Add instructions for MCP"，指导 AI 使用方式

组件优先的渐进式实现：

先用 get_variable_defs 提取设计 tokens，再从小到大逐层实现：Design Tokens → 原子组件(button, input) → 组合组件(card, nav) → 页面区域 → 完整页面。

大文件处理： get_design_context 对复杂页面可能返回 35 万+ token。先用 get_metadata 获取高层节点地图，再按节点 ID 逐段调用 get_design_context 获取特定区域，分段实现。

关键提示：

逐组件生成，不要一次选择整个页面
指定技术栈："使用 shadcn/ui 组件 + 项目 design token，不要 inline style"
配置 Code Connect 后优先复用已有组件，避免从零生成

美化阶段推荐工作流

1. 找参考 → Mobbin / Godly / Dribbble 找到喜欢的设计，截图保存
2. 定配色 → Realtime Colors 确认配色方案，记录具体色值
3. 给 AI  → 截图 + 文字需求一起发（"参考这个风格，做一个后台 Dashboard"）
4. 指定栈 → 要求使用 shadcn/ui + Tailwind，生成代码质量最高
5. 迭代   → 先出基础结构，再逐步调整细节

5. 可用的 MCP 和 Skill

MCP 配置

json

{
  "mcpServers": {
    "shadcn": {
      "command": "npx",
      "args": ["-y", "@anthropic/shadcn-ui-mcp@latest"]
    },
    "context7": {
      "command": "npx",
      "args": ["-y", "@upstash/context7-mcp@latest"]
    },
    "playwright": {
      "command": "npx",
      "args": ["@playwright/mcp@latest"]
    },
    "figma": {
      "type": "http",
      "url": "https://mcp.figma.com/mcp"
    }
  }
}

MCP	UI 开发中的用途
shadcn MCP	查组件用法、获取示例代码、发现可用组件
Context7	查 Next.js/React 最新 API、Tailwind 新特性
Playwright	美化后截图验证 UI 是否正确渲染
Figma MCP	从设计稿提取结构化布局和 design tokens（见 §4.3 和 doc-05 §4.2）

/ui-page Skill

markdown

---
name: ui-page
description: >
  快速生成 UI 页面骨架。新增页面时使用。
  用 shadcn/ui 默认样式，功能优先不美化。
---

# 快速 UI 页面生成

生成页面 "$ARGUMENTS"：

## 规则
- 使用 shadcn/ui 组件，不自定义样式
- 使用项目现有的 layout 结构
- 列表用 Table，表单用 Form + zod，弹窗用 Dialog
- 必须处理三种状态：加载中（Skeleton）、空数据、错误
- 必须连接真实 API，不用 mock 数据
- 不做样式美化

## 页面类型速查
| 类型 | 组件组合 |
|------|---------|
| 列表页 | Table + Pagination + 搜索 Input + 新增 Button |
| 详情页 | Card + Tabs + 返回 Button |
| 表单页 | Form + zod schema + Submit Button + Toast |
| 仪表盘 | Card 网格 + 数字统计 |

## 步骤
1. 确认页面类型和数据来源（API 接口）
2. 检查 shadcn/ui 是否已安装需要的组件，未安装则先安装
3. 生成页面组件 + 对应的 API Route（如果还没有）
4. 跑通数据流，验证功能正确

IMPORTANT：功能优先。不要花时间在颜色、间距、动画上。

6. 写入 CLAUDE.md 的 UI 规则

markdown

## UI 开发规则

- 使用 shadcn/ui 组件库，不引入其他 UI 库
- 功能开发阶段使用默认样式，不做自定义美化
- 每个页面必须处理三种状态：加载中、空数据、错误
- 表单必须用 zod 做校验
- 新增页面前先检查 /components/ui 中已有哪些组件
- NEVER 从零写 CSS，全部用 Tailwind 实用类
- NEVER 在功能未稳定时花时间美化 UI
- NEVER 引入 Ant Design / MUI / Chakra 等其他组件库

## Figma MCP 规则（配置 Figma MCP 后添加）

- 使用 MCP 提供的 localhost 图片/SVG 源，不额外引入图标包
- 优先使用项目 src/components/ui 中已有的组件
- 匹配 Figma 设计保真度，布局和间距以设计稿为准
- 使用设计 tokens 而非硬编码颜色/间距值

7. 移动端额外的 CLAUDE.md 规则

如果使用 Taro（推荐国内场景）

markdown

## 移动端规则（Taro）

- 使用 Taro 3.x + React 语法
- 组件使用 NutUI（京东风格，Taro 深度适配）
- 路由使用 Taro Router，页面在 app.config.ts 中注册
- API 调用复用 Web 端相同的后端接口
- 共享类型定义（从 Web 端 types/ 复制）
- 样式用 CSS Modules 或 Tailwind（通过 weapp-tailwindcss 插件）
- NEVER 直接使用 wx.xxx 原生 API，用 Taro.xxx 封装
- NEVER 在页面组件中直接调用接口，统一走 services/ 层

如果使用 React Native

markdown

## 移动端规则（React Native）

- 使用 Expo Router 做路由（类似 Next.js App Router）
- 样式使用 NativeWind（Tailwind 语法）
- 组件使用 React Native Paper
- API 调用复用 Web 端相同的后端接口
- 共享类型定义（从 Web 端 types/ 复制或用 monorepo）
- NEVER 使用 React Native 的 StyleSheet.create（用 NativeWind）
- NEVER 直接操作原生模块，优先使用 Expo SDK

8. 与其他子系统的关系

Agent 分工：Developer Agent 负责 Phase 1-2（功能骨架+验证），Designer Agent 负责 Phase 3（视觉诊断+美化）
产品设计契约：/product-design 生成 product-spec.md + design-spec.md，为 UI 开发提供确定性输入
CLAUDE.md：UI 开发规则写入
Skills：/ui-page 读取 product-spec + design-spec 后生成页面骨架
MCP：shadcn MCP 查组件、Context7 查文档、Playwright 截图验证、Figma MCP 提取 Token
Hooks：post-edit-format.sh 自动格式化 TSX 文件
测试：Playwright E2E 覆盖核心用户流程（用例从 product-spec 用户旅程转化）
可靠性：UI 层的测试覆盖要求最低（组件渲染测试即可）

11 - UI 开发策略 ​

1. 核心原则 ​

2. Web 端技术栈 ​

为什么不选 Ant Design / MUI / Chakra ​

3. 移动端技术栈选型 ​

方案一：响应式 Web（最轻，推荐起步） ​

方案二：React Native + Expo（原生体验，推荐正式移动端） ​

方案三：Capacitor（Web 套壳，折中方案） ​

方案四：Taro（推荐国内多端场景） ​

选择决策树 ​

推荐技术栈总览 ​

4. 三阶段 UI 开发工作流 ​

第一阶段：功能骨架（不关心好不好看） ​

第二阶段：功能验证（跑真数据） ​

第三阶段：UI 美化（功能稳定后） ​

设计参考资源 ​

可直接出代码的组件库 ​

AI 编程专用工具 ​

截图参考来源 ​

Figma MCP 工作流 ​

美化阶段推荐工作流 ​

5. 可用的 MCP 和 Skill ​

MCP 配置 ​

/ui-page Skill ​

6. 写入 CLAUDE.md 的 UI 规则 ​

7. 移动端额外的 CLAUDE.md 规则 ​

如果使用 Taro（推荐国内场景） ​

如果使用 React Native ​

8. 与其他子系统的关系 ​

11 - UI 开发策略

1. 核心原则

2. Web 端技术栈

为什么不选 Ant Design / MUI / Chakra

3. 移动端技术栈选型

方案一：响应式 Web（最轻，推荐起步）

方案二：React Native + Expo（原生体验，推荐正式移动端）

方案三：Capacitor（Web 套壳，折中方案）

方案四：Taro（推荐国内多端场景）

选择决策树

推荐技术栈总览

4. 三阶段 UI 开发工作流

第一阶段：功能骨架（不关心好不好看）

第二阶段：功能验证（跑真数据）

第三阶段：UI 美化（功能稳定后）

设计参考资源

可直接出代码的组件库

AI 编程专用工具

截图参考来源

Figma MCP 工作流

美化阶段推荐工作流

5. 可用的 MCP 和 Skill

MCP 配置

/ui-page Skill

6. 写入 CLAUDE.md 的 UI 规则

7. 移动端额外的 CLAUDE.md 规则

如果使用 Taro（推荐国内场景）

如果使用 React Native

8. 与其他子系统的关系