OpenDesign 最佳实践指南

🏗️ 架构理解

OpenDesign 由三个核心轴组成，理解它们是使用好这个工具的前提：

关键目录结构

open-design-main/
├── apps/
│   ├── daemon/        # 守护进程（linter、critique 系统）
│   ├── web/           # Web 前端界面
│   └── desktop/       # Electron 桌面壳
├── skills/            # 31 个技能（产出物类型）
├── design-systems/    # 72 个设计系统
├── craft/             # 通用设计规范（11 个文件）
├── plugins/           # 插件系统
└── .od/               # 运行时数据（SQLite + 配置）

⚙️ 环境配置

Node.js 版本要求

推荐启动方式

已配置好的 start.bat 位于 D:\01_APP\OpenDesgin\open-design-main\start.bat，已内置 Node.js 24 路径切换。双击即可启动。

# 手动启动命令
export PATH="/d/05_Coding/.env/NodeJS24:$PATH"
cd "/d/01_APP/OpenDesgin/open-design-main"
pnpm tools-dev start web --daemon-port 24729 --web-port 20026

数据目录

🔄 标准设计流程

从需求到最终产出，遵循以下 6 步工作流：

💬 Prompt 技巧

好的 Brief 公式

[目标] + [目标用户] + [关键功能] + [参考产品] + [设计系统偏好]

示例：
"为一个面向中小企业的 SaaS 发票工具设计落地页，
核心功能是自动发票生成和 expense 追踪，
参考产品是 Stripe 的简洁感，
使用 Linear 风格的设计系统。"

Prompt 避坑

🎨 设计系统选择

OpenDesign 内置了 72 个品牌级设计系统，每个都有完整的 9 段 DESIGN.md 规范。以下是按场景推荐的精选列表：

🚫 反 AI 模板化规范

OpenDesign 内置了 craft/anti-ai-slop.md，这是保证产出不像"AI 生成的"的核心规范。以下是七大重罪（P0 必须修复）：

如何注入"灵魂"

目标是 ~80% 成熟模式 + ~20% 差异化选择。这 20% 应该体现在：

• 一个大胆的视觉动作 — 一个排版选择、一个色彩决定、一个意外的比例
• 声音和微文案 — "Start tracking" 比 "Get started" 更有产品感
• 一个用户会记住的微交互 — 按钮按下移动 2px、数字递增动画
• 一个只有用过产品的人才会放的细节 — 键盘快捷键提示、产品特定的状态徽章

📐 Craft 设计规范

OpenDesign 的 craft/ 目录包含 11 个通用设计规范文件，覆盖 UI 设计的各个维度：

关键规则精选

排版

• ALL CAPS 文本需要 ≥ 0.06em 的 letter-spacing
• 保持三种字重节奏（regular / medium / bold），不要创造第四种
• Display 文本使用 var(--font-display)，不要硬编码字体

色彩

• 每个屏幕最多 2 次 使用 var(--accent) 强调色
• 不要在 :root 外使用超过 ~12 个原始 hex 值 — 使用 Design Tokens
• 不要用颜色单独传递信息（需配合图标或文字标签）

加载状态

• < 300ms：不需要加载指示器
• 300ms - 2s：骨架屏
• 2s - 10s：带标签的 spinner
• 10s - 60s：确定进度条 + 取消按钮
• > 60s：停止并给出错误/重试选项

触控区域

• 最小触控区域：24×24 CSS px（WCAG 2.2 AA 标准）
• iOS 推荐：44×44 pt
• Material 3 推荐：48×48 dp

🧠 UX 认知法则

OpenDesign 内置了基于原始研究文献的 UX 法则，这些法则决定了 UI 的组合方式（放什么、放多少、放哪里）：

感知与视觉分组

• 接近法则 (Proximity) — 组内间距 8-12px，组间间距 32-48px。均匀间距会让什么都不像一组。
• 相似法则 (Similarity) — 等效元素必须有相同样式（每行列表相同 class、所有次要按钮相同）。
• 共同区域 (Common Region) — 内部 padding ≥ 16px，用边框 + 微着色背景区分。页面上到处都是边框会消弱信号。
• 选择性注意 (Selective Attention) — 为单一目标动作保留最强视觉对比，让辅助内容退后。
• 冯·雷斯托夫效应 (Von Restorff) — 推荐定价层、活跃导航项必须在视觉上与众不同。

决策制定

• 希克定律 (Hick's Law) — 决策时间随选项数量对数增长。任何决策屏幕限制 3-5 个可见主选项。
• 选择过载 (Choice Overload) — 定价页 3-4 个层级，恰好一个标记为"推荐"。设置面板 ≤ 5 个命名分组。
• 锚定效应 (Anchoring) — 用户看到的第一个数字会重新加权后续所有数字。推荐定价层放在锚定比较的位置。
• 帕累托法则 (80/20) — 识别 2-3 个驱动主要用户路径的核心动作，视觉上强调它们。

记忆与学习

• 米勒定律 (Miller's Law) — 工作记忆可靠地容纳约 4 个项目。设置页分 "Account / Notifications / Privacy / Billing / Danger zone" 五个分组，优于 30 个开关的平铺列表。
• 峰终定律 (Peak-End Rule) — 体验记忆由情感峰值和结尾主导，而非平均值。在流程结束时做"庆祝"成功状态，中间步骤保持平静。
• 蔡加尼克效应 (Zeigarnik Effect) — 未完成的任务会产生拉回完成的张力。用进度条（"3 of 5 steps"）引导完成。保留用于真正有益的引导流程，勿用于暗模式。

交互

• 菲茨定律 (Fitts's Law) — 目标越大越近越快。高频操作放在自然拇指弧度内（移动端）。
• 目标梯度效应 (Goal-Gradient) — 离目标越近动力越强。展示已完成的先决条件（"saved profile"、"imported team"）作为进度。

🔧 Skills 系统

每个 Skill 对应一种产出物类型。OpenDesign v0.5.0 包含 31 个 Skills：

如何 Craft 被注入

每个 Skill 的 front-matter 中可以声明需要的 Craft 规范：

od:
  craft:
    requires: [typography, color, anti-ai-slop]

这样只有声明的规范会被注入到 Agent 的 system prompt 中，避免不相关的内容浪费 token。

🤖 Agent 配置

OpenDesign 不自带 Agent，而是桥接到你已有的 AI 编码 CLI。

当前配置

你的 .od/app-config.json 已配置为：

{
  "agent": "claude",
  "designSystem": "default"
}

推荐的 Claude Code + Codex 双 Agent 协作

1. Claude Code：定义项目的 CLAUDE.md 设计系统
2. OpenDesign：根据 Brief 生成初始 UI 组件/页面
3. Claude Code：将组件集成到项目中，做代码审查
4. 浏览器预览：在真实浏览器中检查效果
5. Codex：根据截图做增量调整（多模态截图修正）
6. Claude Code：最终测试和部署

📦 导出与部署

导出格式

集成到项目的最佳实践

1. 在 OpenDesign 中生成并审查设计
2. 导出 HTML 代码
3. 用 Claude Code 的 code-reviewer Agent 审查生成的代码
4. 修复类型安全和可访问性问题
5. 集成到项目组件库
6. 编写测试覆盖新增组件

🔍 故障排查

快速命令

# 检查服务状态
D:\01_APP\OpenDesgin\open-design-main\status.bat

# 停止服务（找到并杀死进程）
ps aux | grep "open-design\|tools-dev"
kill <pid>

# 检查端口是否空闲
node -e "const net=require('net'); [20026,24729].forEach(p=>{const s=net.createServer(); s.on('error',e=>console.log('Port '+p+': OCCUPIED')); s.listen(p,'127.0.0.1',()=>{console.log('Port '+p+': FREE');s.close();});});"

📚 参考资料

• OpenDesign GitHub 仓库
• OpenDesign 官方网站
• OpenDesign Guide — 完整使用指南
• OpenDesign Tutorials — 官方教程集合
• Claude Design vs Open Design 对比 (WotAI)
• 3 步构建开源 AI 设计系统 (APIYI)
• Open Design in 20 Minutes — 完整 Setup + Demo (YouTube)
• 开源版 Claude Design？Open Design 完整体验
• Craft 规范来源：refero_skill (MIT License, Refero Design)