oa-design

这是什么？适合谁？

oa-design 把 Open Analytics（已上线产品）的设计语言打包成三种形态：Agent Skill、类型检查的组件配方、shadcn 式 CLI。GitHub 114 Stars（MIT 协议）。

它回答的问题是「你们家 dashboard 为什么长这样、动效为什么这么顺」—答案是：每个 hex 色值、弹簧常数、圆角、缓动曲线都从已上线产品里原样提取，并附上设计理由，再以 Agent 可执行的形式交付。

一句话概括这套语言：白色表面 + 连续曲率圆角，安放在安静的灰色舞台上，单一墨色绘制，单一弹簧驱动。

三种获取方式：

1. CLI（shadcn 式）：npx getopen-design add tab-bar toast 把配方装进项目
2. Claude Code Skill：cp -r oa-design/skills/oa-design .claude/skills/
3. 任意 Agent / 纯规则：一个 DESIGN-SKILL.md 汇总全部语言，Cursor/Codex/任意聊天 Agent 指向它即可

内容结构：

• skills/oa-design/：SKILL.md（十条规则+弹簧表+索引）、_root.css（可安装令牌块）、12 个组件配方（每个内嵌完整源码）、多个指南（令牌/布局/组件/动效/落地页/文案）
• components/：配方所嵌入的类型检查源码（squircle-card、button、dropdown、tab-bar、modal、multi-step-dialog、skeleton、notice-strip、floating-pill、toast、header-morph、reveal）
• cli/：getopen-design npm 包

配方永不手写：node build/sync.mjs 把编译后的组件源码注入每个配方（--cli 同步进 npm 包），所以 MD 里的代码就是 npm run typecheck 通过的代码。

适合人群：

• B 端 SaaS/数据产品开发者：想要「分析产品级」的克制动效与设计系统
• 用 Agent 建 dashboard 的团队：把设计决策外包给一套有理由的语言
• 设计系统建设者：学习「产品级设计语言如何工程化封装」的范本

不适合：需要强烈品牌个性的 C 端营销页（这套语言刻意安静）；非 TS/React 技术栈（组件与 CLI 面向该生态）。

使用前提：React + TS 项目（组件形态）；或任意 Agent（DESIGN-SKILL.md 形态）。

准备工作

1. 运行环境：React + TypeScript 项目（CLI/组件形态）；或任意支持规则的 Agent（纯 MD 形态）。
2. 获取：按需选三种方式之一（见快速上手）。
3. 成本：免费开源（MIT）；设计语言本身可自由采用。
4. 时间预算：CLI 装配方 2 分钟；Skill 全量理解 20 分钟。

3 步快速上手

第 1 步：选形态并安装

# 方式 A：CLI 装配方进项目（shadcn 式）
npx getopen-design list                 # 看有什么
npx getopen-design add tab-bar toast    # 装进 ./oa-design
npx getopen-design tokens               # 只要令牌 CSS

# 方式 B：Claude Code Skill
git clone https://github.com/OpenLabs-so/oa-design
cp -r oa-design/skills/oa-design .claude/skills/oa-design

第 2 步：给 Agent 立规则（非 Claude 生态）

把 DESIGN-SKILL.md 放进项目，在你的 Agent 规则里加一句：

When building or styling UI, follow DESIGN-SKILL.md in full.

第 3 步：构建 UI

用 oa-design 的语言建一个数据分析 dashboard：
左侧 tab-bar 导航、顶部 header-morph 滚动变形头部、
卡片用 squircle-card、数据加载用 skeleton。

预期结果：组件从配方落地、令牌从 _root.css 生效、动效走七弹簧常量表。成功判定：卡片圆角是连续曲率（不是普通 border-radius）、所有过渡用同一弹簧手感、灰白舞台+单墨色的克制配色贯穿全页。

常见踩坑

踩坑 1：绕过令牌直接改色

• 现象：局部硬编码 hex，「单墨色」体系被打破，页面出现脏色。
• 原因：习惯性直接写颜色值。
• 解决：所有颜色走 _root.css 令牌；要改气质改令牌，不局部覆盖。

踩坑 2：混用其他动画库的默认缓动

• 现象：部分组件动效「手感」与整体不一致。
• 原因：_lib/ 里的七个弹簧常数是整体手感的核心，绕开即失真。
• 解决：新动效也用这组常量（SKILL.md 的弹簧表就是为此准备的）。

踩坑 3：把这套语言用在 C 端大促页

• 现象：页面「高级」但没有购买冲动。
• 原因：这套语言为分析产品设计—安静、克制、单墨色；营销页需要张力。
• 解决：B 端 dashboard 用 oa-design；C 端营销页另选（如 silk-design 的动效目录路线）。

踩坑 4：squircle-card 被当成普通圆角卡

• 现象：卡片看起来「差不多了」但缺少那种苹果式的顺滑曲率。
• 原因：连续曲率圆角（squircle）与 border-radius 的视觉差异细微但关键，用错实现即丢失。
• 解决：用配方内嵌的组件源码（含正确实现），别自己用 border-radius 近似。

踩坑 5：手改配方 MD 里的代码

• 现象：下次 sync 修改被覆盖。
• 原因：配方是构建产物（sync.mjs 从 components/ 注入），不是手写源。
• 解决：改 components/ 下的 TS 源码再跑 sync；消费侧则在装出的组件外套一层定制。

踩坑 6：以为必须全盘采用

• 现象：项目已有设计系统，纠结要不要推翻。
• 原因：把「设计语言」当成「全有或全无」。
• 解决：三种粒度自由取用—只拿令牌 CSS / 只拿几个组件配方 / 全套语言。DESIGN-SKILL.md 明示可部分采用。

初级用法

1. 只要令牌：npx getopen-design tokens 拿走配色/圆角/字体令牌块，套在任意项目。
2. 单组件升级：项目里只换 tab-bar（或 toast）一个组件，立刻获得产品级手感。
3. AI 建页的默认审美：DESIGN-SKILL.md 挂进规则，Agent 产出不再「AI 味花花绿绿」。

高级玩法

1. 七弹簧体系扩展：以 _lib/ 的弹簧常数为基准，为自定义组件推导同族常数，保持手感统一。
2. 落地页配方套用：指南含 landing 专册（布局/动效/文案），直接按册子出 B 端产品官网。
3. 白标定制：在 _root.css 令牌层替换品牌色与圆角旋钮，整套组件库瞬间白标。
4. 设计评审基准：12 个配方 + 设计理由本身就是团队的 UI 评审 checklist。

小技巧

1. 先读 SKILL.md 的十条规则：它是整套语言的索引与约束，比直接看组件快。
2. --all --code 一次拿全：评估阶段用 npx getopen-design add --all --code 全量拉下来浏览。
3. skeleton 与数据到达动效配对：reveal 组件配 skeleton 是这套语言的招牌组合，别只用 skeleton。
4. header-morph 慎配视差：两者都吃滚动事件，同页同时用要调优先级。
5. notice-strip 替代 alert：体系内的信息条比原生 alert 视觉一致。

常见问题 FAQ

Q1: 和 shadcn/ui 什么关系？

A: 分发方式相同（CLI 装配方），内容定位不同：shadcn/ui 是通用组件库（大而全）；oa-design 是单一设计语言的完整实现（克制而统一）—每个值都来自同一个上线产品且有理由说明。两者可共存：oa-design 管设计语言，shadcn 补长尾组件。

Q2: 必须用 Open Analytics 吗？

A: 不必。设计语言独立开源（MIT），与产品无绑定；Open Analytics 只是语言的「出处证明」。

Q3: 非 React 项目能用吗？

A: 令牌 CSS（_root.css）与 DESIGN-SKILL.md 的规则层技术栈无关，任何项目可吃；组件配方与 CLI 面向 React + TS，Vue/Svelte 需按配方逻辑移植。

Q4: 「单一弹簧」会不会让页面单调？

A: 这是有意的设计—分析产品的动效应该「感觉不到动效」。七个弹簧常数覆盖了不同交互的力度谱系（按钮/modal/抽屉各不相同），统一的是手感而非单一曲线。

Q5: 114 stars，成熟度如何判断？

A: 这套语言的可信度来自它是「从上线产品逆向提取」而非凭空设计—每个值都有出处（shipped product）和理由，且组件经过 typecheck 门禁。单人/小团队维护的风险用锁版本缓解。

参考链接

• GitHub 仓库
• Open Analytics 产品

本文基于公开资料整理（GitHub 仓库 README，数据核验日期 2026-08-25），AI 辅助生成。