Open Design 入门: 开源版 Claude Design 的正确打开方式

项目简介

Open Design 是 Claude Design 的开源替代方案，由 nexu-io/open-design 开发和维护。

它的核心理念很直接：不重复造轮子。你电脑上已有的编码代理（Claude Code、Codex、Cursor Agent 等 16 种 CLI）直接成为设计引擎，配合 31 种可组合的设计技能和 72 套品牌级设计系统，在本地完成整个设计流程。

关键特性一览：

---

目标读者画像

• 前端/全栈开发者：想用 AI 辅助生成设计稿，但不想学 Figma复杂操作
• 个人开发者：需要快速产出 landing page、移动端原型、产品演示
• 设计团队：希望本地优先、不依赖云端的设计自动化方案
• AI 工具爱好者：想探索已有编码代理在设计领域的潜力

---

核心依赖与环境

Node.js ~24
pnpm 10.33.x（通过 Corepack 管理）
操作系统：macOS / Windows / Linux

Open Design 会自动扫描 PATH 上已安装的编码代理。如果你的机器上没有任何 CLI，它会引导你配置 BYOK 模式（需要 API Key）。

---

完整项目结构树

open-design/
├── apps/
│   ├── daemon/                 # 本地服务（Express + SQLite）
│   │   └── src/
│   │       ├── agents.ts       # 编码代理检测与适配器
│   │       ├── skills.ts       # 技能加载器
│   │       └── server.ts       # API 路由
│   └── web/                    # Next.js 16 前端
│       └── src/
│           ├── prompts/        # 提示词模板
│           ├── artifacts/      # 产物解析
│           └── components/     # UI 组件
├── skills/                     # 31 种设计技能
│   ├── web-prototype/          # 网页原型
│   ├── mobile-app/             # 移动端 App
│   ├── dashboard/              # 仪表盘
│   ├── guizang-ppt/            # 演示文稿
│   └── ...
├── design-systems/             # 72 套设计系统
│   ├── linear-app/
│   ├── vercel/
│   ├── anthropic/
│   └── ...
├── assets/frames/              # 设备框架（iPhone、Pixel、iPad、MacBook）
└── .od/                        # 运行时数据（SQLite、项目文件）

---

手把手步骤

1) 克隆仓库并安装依赖

git clone https://github.com/nexu-io/open-design.git
cd open-design
corepack enable
pnpm install

corepack enable 会自动读取 package.json 中锁定的 pnpm 版本（10.33.x），确保团队环境一致。

2) 启动本地开发服务器

pnpm tools-dev run web

启动成功后会打印两个 URL：

✅ Daemon running at http://localhost:17456
✅ Web running at http://localhost:17573

用浏览器打开 Web URL 即可开始使用。

3) 选择编码代理

首次打开 Web 界面，Open Design 会自动检测你 PATH 上的编码代理。

支持的 16 种 CLI：

界面右上角的模型选择器会显示已检测到的代理。如果没有任何 CLI，点击选择 BYOK 模式，用你的 API Key 通过 OpenAI/Anthropic/Azure/Gemini 接口运行。

4) 选择设计技能

入口页面列出 31 种技能，按场景分组：

• Design：web-prototype（默认）、mobile-app、mobile-onboarding、gamified-app、wireframe-sketch、critique、tweaks
• Marketing：saas-landing、pricing-page、blog-post、email-marketing、social-carousel、magazine-poster、motion-frames、sprite-animation
• Operation/Engineering/Product：dashboard、docs-page、pm-spec、team-okrs、meeting-notes、kanban-board、eng-runbook、finance-report、invoice、hr-onboarding
• Deck（演示文稿）：guizang-ppt（默认）、simple-deck、replit-deck、weekly-update

根据你的需求点击对应技能，比如选择 mobile-app 来生成移动端原型。

5) 选择设计系统

技能选择后会展示设计系统面板。默认提供 default（Neutral Modern）和 warm-editorial（Warm Editorial）两种起始系统。

完整库包含 72 套品牌设计系统：

• AI & LLM：claude、cohere、mistral-ai、ollama、x-ai…
• 开发工具：cursor、vercel、linear-app、supabase、posthog、sentry…
• 产品：notion、figma、airtable、intercom、raycast…
• 电商：shopify、airbnb、uber、nike、starbucks…
• 汽车：tesla、bmw、ferrari、lamborghini…
• 其他：apple、ibm、nvidia、spotify…

也可以上传自己的 DESIGN.md 文件，定义品牌色、字体、间距等 9 个维度的设计规范。

6) 发送设计指令

在输入框输入你的设计需求，比如：

make me a mobile onboarding flow for a fitness app with dark theme

填写表单后再提交，代理会：

1. 生成 TodoWrite 计划并实时流式更新
2. 读取技能模板和设计系统
3. 执行 5 维度自检（哲学、层级、执行、特异性、克制）
4. 输出 <artifact> 代码
5. 在沙箱 iframe 中渲染预览

7) 预览与导出

设计稿渲染后，你可以：

• 实时编辑：在右侧文件工作区直接修改 HTML/CSS
• 下载：导出为 HTML（内联资源）、PDF、PPTX、ZIP 或 Markdown
• 保存到磁盘：点击「Save to disk」，产物保存到 .od/artifacts/
• 继续对话：告诉代理「把按钮改成圆角」或「换个配色」，它会基于当前稿继续修改

其他常用命令：

# 查看运行状态
pnpm tools-dev status

# 查看日志
pnpm tools-dev logs

# 停止所有服务
pnpm tools-dev stop

# 重启（换端口场景）
pnpm tools-dev restart --daemon-port 17456 --web-port 17573

# 诊断问题
pnpm tools-dev check

---

修改已有项目

很多人拿到 Open Design 的第一反应是「这不就是生成新页面的工具吗」。其实它完全可以用来修改已有项目，而且不需要你的项目里有什么 DESIGN.md。

核心逻辑很简单：代理有完整的文件系统访问权限——Read、Write、Bash、WebFetch 全都有。让它分析你的代码，它就能理解你的设计语言，然后基于现有风格输出。

用方向选择器快速建立视觉基线

没有设计规范时，Turn 2 会弹出 5 个预设方向，每个都是确定性的 OKLch 调色板 + 字体栈：

选一个方向后，代理会用这个调色板覆盖技能模板的 :root 变量，后续所有组件都会遵循这套规范。

上传截图，让代理提取设计语言

这是更贴合实际项目的用法。Open Design 内置了品牌资产提取协议：

1. Locate  — 定位截图中的关键颜色区块
2. Download — 下载截图到项目目录
3. Grep hex — 提取 hex 色值
4. Codify   — 写入 brand-spec.md
5. Vocalise — 代理基于 brand-spec.md 输出，而非凭记忆猜测

操作方式很简单：

"Here's our current app, I want you to match the styles"
# 然后附加截图或粘贴现有页面的 URL

代理会解析截图中的主色、辅色、字体、间距特征，生成 brand-spec.md，之后的修改都基于这份规范。

直接读取代码，比截图更精准

代理默认的工作目录是 .od/projects/<id>/，但你可以把已有项目放进去：

# 把你的项目复制到 Open Design 的工作目录
cp -r ~/my-app/.   .od/projects/<项目ID>/

或者用 MCP 服务器直接让代理跨目录读取（见下一节）。

然后发送这类指令：

"Read all .css files in ./src/styles and extract the color palette"

"Read the component library at ./components/. Generate a new
form component using the same spacing and border-radius tokens"

"I see you use Tailwind. Add a new button variant that matches
your existing primary/secondary button styles"

代理会遍历文件、解析 CSS 变量 / Tailwind 配置、提取设计 token，然后生成与现有代码风格一致的产物。

MCP 服务器：跨项目读取设计文件

不想复制文件？Open Design 提供了 MCP 服务端，可以让你的编码代理直接读取 Open Design 项目中的文件。

在 Open Design 的 Settings → MCP Server 页面，有针对不同客户端的配置指引。配置好后，你在其他项目（如 ~/my-app）中运行的 Claude Code / Cursor 代理可以直接查询 Open Design 中打开项目的设计文件。

针对修改场景的推荐流程

1. 打开 Open Design，选一个接近你项目风格的技能（如 web-prototype）

2. Turn 1 表单：
   - Surface: Web
   - Audience: 现有用户群体
   - Tone: 与现有产品保持一致

3. Turn 2 方向选择：
   - 想保持一致 → 上传现有页面截图，让代理提取 brand-spec.md
   - 允许适度重设计 → 选一个方向作为视觉基线

4. 发送指令：
   "Add a settings page to my existing project at ./src,
    match the color palette and typography from the attached screenshot"

代理会：

1. 读取截图 → 提取 brand-spec.md（或读取代码中的 CSS 变量）
2. 读取你项目的现有文件
3. 在新页面中复用主色、辅色、字体
4. 输出可运行的 HTML，风格与现有项目一致

---

常见问题排查

Q1: Node 版本不对，报错 Requested version v24.x.x is not currently installed

Open Design 要求 Node 24。用 nvm 或 fnm 安装：

nvm install 24 && nvm use 24
# 或
fnm install 24 && fnm use 24

如果用 fnm，确保 shell 配置文件加载了 fnm env（参考 fnm 官方文档）。

Q2: 编码代理未被检测到

Open Design 在首次启动时扫描 PATH。确认 CLI 已安装且全局可用：

# 验证某个代理
which claude     # macOS/Linux
where claude     # Windows

# 如果已安装但仍未检测，尝试重启服务
pnpm tools-dev stop && pnpm tools-dev start web

Q3: 端口被占用

默认端口 17456（daemon）和 17573（web）可能已被占用：

# 换到其他端口
pnpm tools-dev run web --daemon-port 17457 --web-port 17574

Q4: 设计系统切换后样式没变

Open Design 的设计系统通过读取 DESIGN.md 中的 CSS 变量注入。每次切换系统后，代理会在新对话中使用新变量，已生成的老对话不会自动刷新。开启新对话即可应用新系统。

Q5: 预览 iframe 加载空白

沙箱 iframe 使用 srcdoc 渲染。如果内容未显示：

1. 检查浏览器控制台是否有 CSP 错误
2. 确认广告拦截插件未拦截 iframe 加载
3. 点击「Download HTML」下载后在本地直接打开验证

Q6: BYOK 模式报 API Key 错误

BYOK 代理位于 /api/proxy/{anthropic,openai,azure,google}/stream。确认：

1. Settings 页面配置的 baseUrl 正确（OpenAI 兼容格式）
2. API Key 有效且有对应模型权限
3. 未填写 apiKey 字段时，服务端会拒绝请求（SSRF 防护）

---

扩展阅读 / 进阶方向

添加自定义设计技能

技能以 SKILL.md + assets/ + references/ 文件夹形式存在，遵循 Claude Code 的 SKILL.md 规范。

在 skills/ 下新建文件夹，添加 SKILL.md 并定义 od: frontmatter（mode、scenario、design_system.requires 等），重启服务后自动出现在技能选择器。

导入 Claude Design 导出包

Anthropic 的 Claude Design 支持导出 ZIP。将 ZIP 拖拽到 Open Design 的欢迎对话框，POST /api/import/claude-design 会解析并重建项目，代理可以无缝接续编辑。

集成 MCP 服务器

Open Design 提供 stdio MCP 服务端。在 Claude Code/Cursor/VS Code 等 MCP 客户端中配置，代理可以直接读取 Open Design 项目中的设计文件和素材，无需手动导出 ZIP。

构建桌面端 App

Electron 桌面版支持 macOS（Apple Silicon）和 Windows（x64）：

# macOS
pnpm tools-pack mac build --to all
pnpm tools-pack mac install

# Windows
pnpm tools-pack win build --to nsis
pnpm tools-pack win install

打包后的 App 可独立运行，数据存放在系统 AppData 目录。

扩展媒体生成能力

除了代码产物，Open Design 还集成了图片（gpt-image-2）、视频（Seedance 2.0、HyperFrames）和音频（Suno、Udio）生成模型。配置 API Key 后，设计流程中可以直接产出 .mp4、.png 等媒体文件。

---

项目地址：nexu-io/open-design