中级 阅读时长 25 分钟 前置要求：Node.js、React 基础

AI 驱动产品设计的
操作系统

通过结构化的 AI 工作流，将模糊的产品想法转化为生产就绪的 React 组件。Design OS 通过 Claude Code 斜杠命令，引导你完成从愿景到导出的每一步。

开始交互式实验 在 GitHub 查看 →

学习目标

  • 使用 Node.js 与 Claude Code 在本地搭建并配置 Design OS 环境
  • 按顺序执行 5 个核心规划指令，完成产品愿景、路线图与设计系统定义
  • 生成带 TypeScript 类型与样例数据的可投产 React 组件
  • 诊断并修复常见的 AI 生成错误
  • 导出完整交付包，支持渐进式或一站式落地

TL;DR

30 秒核心概念

Design OS 通过结构化的三阶段指令工作流消除“空白页综合症”。你提供产品愿景并回答交互式提问，它会自动生成设计系统、数据模型、应用壳以及 React 组件。按顺序运行斜杠命令、审阅输出并迭代，最后导出可投产的代码包与实现提示词。

工作流总览

Design OS 是一个线性流程，每个阶段都基于前一阶段的成果。在进入第二阶段前务必完成第一阶段的全部步骤。

重要：第二阶段是循环的——路线图中的每个分区都要重复这一套步骤。

基础

前置条件

开始使用 Design OS 前，请确保你具备：

  • 已安装 Node.js v18+ 与 npm
  • 一款 AI 编码代理 —— 推荐 Claude Code（Design OS 自带定制斜杠命令）
  • 对 React 与组件化架构有基本了解

关键概念

Section（分区）
核心工作单元。通常由 3-5 个分区组成，可独立设计。
Design Tokens（设计令牌）
以 CSS 自定义属性与 Tailwind 配置形式定义视觉语言。
Data Model（数据模型）
系统中的“名词”——用户创建、查看、管理的各类实体。
Application Shell（应用壳）
侧边栏、顶部导航或极简页头，为产品提供一致的导航结构。

常见误区

❌ “Design OS 会生成后端代码”

Design OS 只覆盖前端设计层。后端可任意选择（Rails、Laravel、Next.js API Routes、Python、Go 等）。导出的组件通过 props 接收数据与回调。

❌ “步骤可以跳过或任意顺序执行”

每个命令都依赖前一步的产物。未先运行 /shape-section 就执行 /design-screen 会导致输出混乱。

阶段一：产品规划

在动手设计界面前先打好基础。这 5 个命令必须按顺序执行。

1. 产品愿景（Product Vision）

WHY：AI 需要上下文。本命令会创建产品概览文件，作为后续生成的锚点；没有它，AI 无法理解你要做什么。

HOW：运行命令并按提示回答产品名称、描述、要解决的问题、核心特性等问题。越具体越好，模糊输入只会产生模糊输出。

WHEN：永远第一步——所有 Design OS 项目的 0 号步骤。

生成：

product/product-overview.md

2. 产品路线图（Product Roadmap）

WHY：把产品拆分为 3-5 个可管理的分区。每个分区都会成为导航项，并可独立设计。

HOW：AI 会依据产品概览给出分区建议。一起讨论顺序——首个分区应覆盖核心功能，其余在此基础上递进。

WHEN：在完成产品愿景后立刻进行。

生成：

product/product-roadmap.md

3. 数据模型（Data Model）

WHY：定义系统里的“名词”——如 User、Device、Reading、Report，保证各分区的数据结构一致。

HOW：关注概念而非数据库表。用自然语言描述实体，AI 会追问关系（1 对多、多对多）。

WHEN：在路线图之后、设计令牌之前完成。

生成：

product/data-model/data-model.md

4. 设计令牌（Design Tokens）

WHY：在编写组件前先确定视觉身份（色彩与字体），确保全局一致性。

HOW：从 Tailwind 调色板（blue、indigo、emerald 等）与 Google Fonts 中选择。AI 会根据产品类型给出组合建议。

5. 应用壳（Application Shell）

WHY：创建包裹所有分区的持久导航与布局，让用户在全局拥有一致的导航体验。

HOW：选择壳模式：侧边栏导航（仪表盘类）、顶部导航（简易应用）或极简页头（单一用途工具）。

阶段二：分区设计

此阶段是循环的，对路线图中的每个分区重复执行这些命令。

分区设计循环

Shape Section → Sample Data → Design Screen → （可选：Screenshot）→ 继续下一个分区

1. Shape Section（分区定型）

WHY：在写任何代码前先定义该分区的功能需求，相当于分区的规格文档。

HOW：回答分区用途、主要用户流程（关键动作）以及 UI 要求。还需说明该分区是否使用应用壳或是独立页面。

WHEN：设计每个分区的起点。

生成：

product/sections/[section-id]/spec.md

2. Sample Data（样例数据）

WHY：生成逼真的模拟数据，使 UI 在无后端情况下也能开发与测试，同时生成 TypeScript 接口确保类型安全。

HOW：AI 读取分区规格，提出数据结构，并生成 5-10 条真实且包含边界情况的样例记录。

WHEN：在 Shape Section 之后、Design Screen 之前。

生成：

product/sections/[section-id]/data.json
product/sections/[section-id]/types.ts

3. Design Screen（界面设计）

WHY：让规格与样例数据落地为可运行的 React UI，AI 会生成具备完整样式的投产组件。

HOW：AI 读取规格，创建通过 props 接收数据与回调的组件。若分区存在多视图（列表/详情/表单），可多次运行。

WHEN：生成样例数据之后。

会生成什么

  • 可导出的组件 —— 基于 Props，可移植到任意 React 项目
  • 预览封装 —— 在 Design OS 中导入样例数据便于测试
  • 完整 Tailwind 样式与响应式断点
  • 通过 dark: 变体支持深浅色模式

⚠️ 提醒：生成界面后请重启开发服务器（npm run dev）以便在浏览器中看到更新。

阶段三：导出

当所有分区设计完成（或你准备交付时），生成完整的实现包。

何时导出

符合以下条件即可导出：

  • 已完成产品愿景与路线图
  • 至少有一个分区生成了界面
  • 对当前设计方向满意

导出并非一次性的——后续添加分区后可再次导出。

导出内容

  • 可直接使用的提示词 — 复制/粘贴到你的编码代理
  • 实现说明 — 支持一站式或渐进式两种模式
  • 设计系统文件 — tokens.css、fonts.md 等
  • 全部组件 — 携带类型与样例数据
  • 测试指引 — 每个分区的 TDD 规格

最佳实践 vs 反模式

✓ 请务必：先检查类型

运行 /sample-data 后先看 types.ts。数据结构错了，UI 必然跟着错；尽早发现问题。

// Verify entity shapes match your expectations
interface Device {
  id: string;
  status: 'active' | 'offline' | 'error';
}

✗ 避免：手改临时生成文件

不要手动修改 .design-os/temp 下的组件，下一次命令会覆盖。用斜杠命令来迭代。

// Bad: Manual edits in temp folder = lost work
// Good: Run /design-screen again with feedback

✓ 请务必：遵循顺序

命令彼此依赖。先完成阶段一再进入阶段二；先 /shape-section 再 /sample-data。

✗ 避免：模糊输入

AI 会映射你的具体程度。“一个做点东西的仪表盘”只会得到泛化输出；“用于实时监控太阳能板效率并提供设备级告警的仪表盘”才能得到贴合的组件。

完整示例 ⭐

这是最重要的部分，展示 Design OS 在真实场景中的端到端使用方式。

场景：构建完整的 “Settings” 分区

目标：打造包含密码修改与通知偏好的用户设置页。

前置条件

  • 已完成阶段一（愿景、路线图、设计令牌、应用壳）
  • 产品路线图中已有 “Settings” 分区

操作步骤

终端 — Settings 分区
# 步骤 1：定义分区范围
/shape-section
? 分区名称：Settings
? 目的：允许用户修改密码与通知偏好
? 用户流程：
1. 更新邮箱/密码
2. 切换通知渠道
3. 删除账号
✔ 已创建 product/sections/settings/spec.md

# 步骤 2：生成样例数据
/sample-data
✔ 已创建包含 UserSettings 接口的 types.ts
✔ 已创建带样例偏好的 data.json

# 步骤 3：生成 UI
/design-screen
? 哪个视图：Settings Main
✔ 生成 SettingsView.tsx
✔ 生成 ProfileForm.tsx
✔ 生成 NotificationToggle.tsx

# 步骤 4：预览（先重启 dev server）
npm run dev
服务器已运行于 localhost:3000

预期结果

一个完整样式的 Settings 页面组件，接受 currentUser、onUpdateProfile、onUpdateNotifications、onDeleteAccount 等 props，包含表单校验与响应式布局。

可选变体

  • 多标签设置：在 /shape-section 指定 Settings 包含 Profile、Notifications、Security 标签
  • 团队设置：如果应用有团队功能，在范围中加入团队管理流程

场景：复杂数据可视化

问题：仪表盘需要图表，但 AI 可能生成与所用图表库不兼容的代码。

解决方案

在 /product-vision 中声明你的图表库，这样生成的组件都会保持兼容。

终端 — 图表集成
/product-vision
? 技术要求或约束：
"Use Recharts for all data visualization. Use date-fns for date formatting."

# 之后设计仪表盘时：
/design-screen
AI 会生成兼容 Recharts 的组件：
✔ 生成 EnergyChart.tsx（使用 Recharts）

关键洞察

产品概览会被后续所有命令读取。越早声明库偏好，越能确保生成代码一致。

其他边界情况

  • 空状态：在 /shape-section 指明“需优雅处理空数据”
  • 超长列表：在需求中写明“为 1000+ 条记录使用虚拟列表”
  • 无障碍：在愿景中写明“必须符合 WCAG 2.1 AA”

场景：渐进式实现策略

目标：利用导出包按分区受控落地，在每个里程碑间进行代码评审。

前置条件

  • 已通过 /export-product 完成导出
  • 已将 product-plan/ 复制到目标代码库

操作步骤

实现代理会话
# 里程碑 1：基础
打开：product-plan/prompts/section-prompt.md
设置 SECTION_NAME = "Foundation"
设置 NN = "01"
以 Plan Mode 递交提示词

# 代理阅读指令并追问：
"认证方式？OAuth、JWT 还是 session？"
"单租户还是多租户？"

# 澄清后，代理实施：
✔ 安装设计令牌
✔ 创建数据模型类型
✔ 配置路由

# 评审、测试后进入里程碑 2...

渐进式的好处

  • 更易评审——在问题积累前就被发现
  • 节奏灵活——分区之间可暂停
  • 掌控力强——由你决定每个里程碑何时就绪

场景：AI 生成了无效代码

问题：生成的组件存在 TypeScript 错误或引用了未定义变量。

修复步骤

终端 — 错误恢复
# 首次生成失败
/design-screen
✔ 生成 DashboardView.tsx

# 运行开发服务器
npm run dev
✖ Error: Cannot find name 'UserData'
✖ Error: Property 'status' does not exist

# 方案 1：携带错误上下文重跑
/design-screen
? 额外上下文：
“请修复这些错误：Cannot find name 'UserData'。Property 'status' does not exist on type Device.”

# AI 分析并重新生成
✔ 重新生成 DashboardView.tsx
✔ 补充缺失的 types.ts 引用
✔ 修正属性引用

预防建议

  • 在运行 /design-screen 前先审查 types.ts
  • 在 /shape-section 明确数据结构
  • 每次生成后都运行 dev server，尽早暴露错误

若仍无法解决

删除生成文件，带更详细的上下文重跑命令。AI 在命令之间不保留记忆，提供完整错误信息有助于纠偏。

术语速览

Slash Command（斜杠命令）
以 “/” 开头的 Claude Code 命令，用于触发 Design OS 工作流。
Handoff Package（交付包）
包含全部资源、提示词与实施说明的导出包。
Section Spec（分区规格）
定义分区用途、用户流程与 UI 需求的 Markdown 文档。
Design Tokens（设计令牌）
以 CSS 变量与 Tailwind 配置存储的原子化视觉值（颜色、字体、间距）。
Application Shell（应用壳）
包裹分区内容的持久化导航/布局层（侧边栏、顶部导航等）。
Preview Wrapper（预览封装）
在 Design OS 开发服务器中导入样例数据以渲染 UI 的封装组件。
One-Shot Implementation（一站式实现）
在单次 AI 会话中用合并指令完成整个产品的构建。
Incremental Implementation（渐进式实现）
按里程碑逐段构建，并在各分区之间进行评审。

故障排除

原因： Tailwind 配置未更新，或开发服务器未重启。

解决方案：

  1. Re-run /design-tokens and verify tailwind.config.js was updated
  2. Restart the dev server: npm run dev
  3. Hard refresh the browser (Cmd+Shift+R / Ctrl+Shift+R)

原因： 不在 Design OS 项目目录或 Claude Code 未启动。

解决方案：

  1. Verify you're in the project root: ls .claude/commands
  2. Start Claude Code: claude
  3. Try the command again

原因： types.ts 与组件不匹配，或缺少导入。

解决方案：

  1. Check types.ts in the section folder—are interfaces correct?
  2. Re-run /design-screen with error context: "Fix error: [paste error message]"
  3. If persistent, re-run /sample-data first to regenerate types

原因： 某些分区未完成（缺少规格、数据或界面）。

解决方案：

  1. Check product/sections/ — each section should have spec.md, types.ts, and data.json
  2. Check src/sections/ — each section should have component files
  3. Complete missing steps, then re-run /export-product

命令速查表

命令 阶段 生成
/product-vision 1. 规划 product-overview.md
/product-roadmap 1. 规划 product-roadmap.md
/data-model 1. 规划 data-model.md
/design-tokens 1. 规划 colors.json, typography.json
/design-shell 1. 规划 AppShell.tsx, MainNav.tsx, UserMenu.tsx
/shape-section 2. 设计 sections/[id]/spec.md
/sample-data 2. 设计 data.json, types.ts
/design-screen 2. 设计 [Component].tsx files
/screenshot-design 2. 设计 [screen-name].png
/export-product 3. 导出 product-plan/ folder + .zip

自我测评

在真实项目中使用前先检验你的理解。

Q1：何时定义 Design Tokens？

Q2：若在 /sample-data 之前运行 /design-screen 会怎样？

Q3：“Preview Wrapper” 组件的作用是什么？

Q4：复杂的大型产品应采用哪种实现方式？

后续步骤

准备好动手了吗？

  1. 安装 Node.js v18+（如未安装）
  2. 克隆仓库：git clone https://github.com/buildermethods/design-os.git my-project
  3. 运行 npm install 与 npm run dev
  4. 启动 Claude Code：claude
  5. 运行你的第一个命令：/product-vision
前往 GitHub 开始

延伸阅读