OpenDesign Minimal 设计系统完全指南：从 DESIGN.md 品牌规范到 tokens.css 语义令牌的落地实践

OpenDesign Minimal 设计系统完全指南：从 DESIGN.md 品牌规范到 tokens.css 语义令牌的落地实践

【免费下载链接】open-design🎨 Best DeepSeek Harness Design Plugin. The open-source Claude Design alternative. 🖥️ Local-first desktop app. 🖼️ Your coding agent becomes the design engine: prototypes, landing pages, dashboards, slides, images & video — real files, HTML/PDF/PPTX/MP4 export. 🤖 Claude Code / Codex / Cursor / DeepSeek Harness / OpenCode & 20+ CLIs via BYOK.项目地址: https://gitcode.com/gh_mirrors/opend/open-design

本指南围绕 OpenDesign 仓库中 design-systems/minimal/DESIGN.md 这一核心设计规范文档展开，结合同目录下的 tokens.css、components.html、design-tokens.json 与 USAGE.md 等源码资产，系统讲解 Minimal 风格的设计语言：如何用留白、克制的色彩与干净的字排实现"最大清晰度"，以及这套规范如何被 OpenDesign 打包成可供 Agent 消费的机器可读设计系统。读完本文，你将掌握 Minimal 风格的令牌体系、组件实现细节、反模式约束，以及如何在 OpenDesign 的产物生成流程中正确引用这套设计系统。

1. Minimal 设计系统在 OpenDesign 中的定位

OpenDesign 仓库将设计系统组织为可移植的"包（package）"结构，每个子目录都是一个独立设计系统包。根据 design-systems/README.md，仓库中每个打包目录都具备统一的最小机器可读形态：

design-systems/<slug>/ ├── manifest.json ├── DESIGN.md └── tokens.css

• manifest.json承载稳定的发现元数据、来源（provenance）与声明路径；
• DESIGN.md是面向 Agent 的权威设计散文（canonical design prose）；
• tokens.css是编译后的权威语义令牌样式表（canonical compiled semantic-token stylesheet）。

Minimal 包位于 design-systems/minimal/，其 manifest.json 声明schemaVersion为od-design-system-project/v1，category为 "Modern & Minimal"，并且额外挂载了USAGE.md、components.html、components.manifest.json、design-tokens.json、tailwind-v4.css、preview/与source/等"丰富包文件"。这些文件不是结构占位符，而是活跃的运行时输入：提示词组合（prompt composition）会消费USAGE.md、tokens.css与组件信息。这意味着 Minimal 的规范不仅停留在文档层面，还会真正进入 Agent 的提示上下文，指导其生成产物。

从 manifest.json 可见，Minimal 的craft.suggested建议应用 craft/color.md 与 craft/accessibility-baseline.md 两条工艺准则，说明该风格对色彩纪律与可访问性基线有明确诉求。

2. 视觉主题与氛围：极简、干净、自信

原文档对 Minimal 的定位是一句话式的风格宣言：极简（stripped-back）设计，以留白、干净的字排与克制的色彩换取最大的清晰度与专注度。它属于 "Modern & Minimal" 类别，其三重支柱是：

• 视觉风格：minimal（极简）、clean（干净）、bold（自信有力）；
• 色彩立场：primary、neutral、success、warning、danger 五个语义层级；
• 设计意图：让产出物一眼可辨属于该风格家族，同时保持可用性与可读性。

这一意图在配套的组件参考页 components.html 中被提炼为一句更具体的产品语言（fixture 描述原文）："minimal product language with white space, black text, hairline borders, and quiet interaction"——留白、黑字、发丝级边框、安静克制的交互。这四组关键词可以看作 Minimal 的"指纹"，任何产物都应能通过这四点被识别为 Minimal 风格。

3. 色彩系统：从品牌意图到语义令牌

3.1 DESIGN.md 声明的品牌色

原文档给出 Minimal 的品牌色彩层级：

文档同时给出三条使用纪律：

• CTA 强调优先使用 Primary（#0C0C09）；
• 大面积背景与卡片使用 Surface（#F4F4F1）；
• 正文保持 Text（#0C0C09）以确保可读性。

3.2 tokens.css：运行时真正生效的语义令牌

需要说明的是，DESIGN.md描述的是品牌意图层，而实际注入产物<style>块的是编译后的语义令牌文件 tokens.css。从源码看，tokens.css给出了更贴近真实产品渲染的令牌组：

:root { --bg: #ffffff; --surface: #fafafa; --surface-warm: #f5f5f5; --fg: #111111; --fg-2: #3a3a3a; --muted: #777777; --meta: #111111; --border: #e2e2e2; --border-soft: #eeeeee; --accent: #111111; --accent-on: #ffffff; --accent-hover: color-mix(in oklab, var(--accent), black 8%); --accent-active: color-mix(in oklab, var(--accent), black 14%); --success: #168a46; --warn: #b7791f; --danger: #c53030; /* ... 其余见 tokens.css */ }

对比可见：DESIGN.md中 Primary#0C0C09、Secondary#312C85等更接近"品牌色板"的语义描述，而tokens.css落地为--accent: #111111、--bg: #ffffff等偏产品化的近黑/近白体系——这是文档意图与编译产物之间自然存在的"翻译层"。从 USAGE.md 的约束可以确认运行时权威是 tokens.css：它明确要求"不要在生产代码中引入:root令牌块之外的裸十六进制色值""不要脱离tokens.css独立重定义 Tailwind 或设计令牌值"。

tokens.css还演示了两个值得注意的实现手法：

1. oklab 色彩混合：--accent-hover与--accent-active使用color-mix(in oklab, var(--accent), black 8%/14%)派生，hover/active 状态不依赖手工取色，令牌可随主色自动联动；
2. 层级化灰阶：--bg（白）→--surface→--surface-warm→--border-soft→--border→--muted→--fg-2→--fg（近黑）构成完整的表面/边框/文字灰阶阶梯，这与"发丝级边框"的产品语言一一对应。

3.3 令牌契约审计：design-tokens.json

design-tokens.json 是结构化令牌契约的审计产物（格式od-design-tokens/v1），其summary字段给出了可验证的质量数据：

• 总令牌数 56，声明令牌 56，全部有 source 回溯（sourceBackedTokens: 56）；
• 分层统计：A1-identity8 个、A1-structure18 个、A226 个、B-slot4 个；
• 综合评分100 分，等级 excellent，recommendRebuild: false。

每个令牌条目都记录layer、confidence、sources（如tokens.css:7）等审计字段，说明 Minimal 包的令牌资产经过了契约校验流程，属于"源可回溯"的高置信度令牌，这为跨品牌切换时"保留 schema 令牌名不变"（USAGE.md 的 Do 清单第一条）提供了数据基础。

4. 排版系统：桌面优先的富有表现力的字阶

原文档对排版的定位是：desktop-first expressive scale（桌面优先的富有表现力的字阶），并给出：

• 字体家族：primary = Open Sans，display = Inter，mono = Inconsolata；
• 字重：100–900 全部可用；
• 分工原则：标题承载风格个性（headings carry the style personality），正文优化可扫读性与对比度。

落到 tokens.css 中，排版的运行时令牌为：

--font-display: Inter, system-ui, sans-serif; --font-body: Inter, system-ui, sans-serif; --font-mono: "SF Mono", ui-monospace, Menlo, monospace; --text-xs: 12px; --text-sm: 14px; --text-base: 16px; --text-lg: 18px; --text-xl: 22px; --text-2xl: 32px; --text-3xl: 48px; --text-4xl: 64px; --leading-body: 1.55; --leading-tight: 1.08; --tracking-display: -0.02em;

这里同样存在意图层与实现层的差异：DESIGN.md声明 primary=Open Sans、mono=Inconsolata，而tokens.css落地为 Inter 系正文与 SF Mono 系等宽字体。二者并不冲突——DESIGN.md描述风格家族，tokens.css提供可直接渲染的字体栈回退链（system-ui 等系统字体兜底）。

组件参考页 components.html 展示了排版令牌在真实 CSS 中的用法，值得逐条研读：

• 标题族：h1, h2, h3 { font-family: var(--font-display); line-height: var(--leading-tight); letter-spacing: var(--tracking-display); }，其中h1使用--text-4xl（64px）且字重 760、max-width: 820px；
• 眉题（eyebrow）：.eyebrow { font-family: var(--font-mono); font-size: var(--text-xs); font-weight: 700; letter-spacing: 0.12em; text-transform: uppercase; }——等宽字体 + 全大写 + 宽字距，是 Minimal 风格极具辨识度的装饰性元素；
• 导语（lead）：.lead { color: var(--fg-2); font-size: var(--text-lg); max-width: 640px; }——用次级文字色而非加粗来区分层级，符合"保持层级但保持克制"的原则。

从 components.manifest.json 的groups可知，typography组件组（.eyebrow、.lead、h1–h3）引用--fg-2、--text-4xl、--text-lg、--text-xl四个令牌。

5. 间距与网格：4 的倍数与一致的垂直节奏

原文档给出 Minimal 的间距规则：

• 间距刻度（spacing scale）：4/8/12/16/24/32；
• 各区块与组件之间保持一致的垂直节奏（vertical rhythm）；
• 列与模块对齐到可预测的网格，禁止临时偏移。

tokens.css将这一刻度扩展为完整的间距变量族，并补充了区块级与容器级的尺寸令牌：

--space-1: 4px; --space-2: 8px; --space-3: 12px; --space-4: 16px; --space-5: 20px; --space-6: 24px; --space-8: 32px; --space-12: 48px; --section-y-desktop: 112px; --section-y-tablet: 80px; --section-y-phone: 56px; --container-max: 1120px; --container-gutter-desktop: 36px; --container-gutter-tablet: 24px; --container-gutter-phone: 16px;

值得注意的两点实现细节：

1. 区块纵向留白是响应式的：section在桌面/平板/手机分别使用--section-y-desktop/tablet/phone（112/80/56px），由 components.html 中的媒体查询驱动（max-width: 1023px与max-width: 639px两档断点）；
2. 容器采用 max-inline 居中 + 响应式 gutter：.container { max-width: var(--container-max); margin-inline: auto; padding-inline: var(--container-gutter-desktop); }，平板与手机断点分别切换 gutter 为 24px/16px。

"用留白而非边框或阴影来分隔"是第 5 节布局原则在间距层的落实——tokens.css中的--elev-flat: none与--elev-ring: 0 0 0 1px var(--border)也从令牌层面支持了"优先白空间、其次 1px 发丝边框、最后才是投影"的层级策略。

6. 布局与构图：清晰内容块与明显层级

原文档的布局法则可以浓缩为三条：

• 优先使用内部内边距一致的清晰内容块；
• 保持明显层级：大标题（headline）→ 支持性文字（support text）→ 主操作（primary action）；
• 在添加边框或阴影之前，先用留白划分关注区域。

components.html 的 hero 区就是这条法则的完整示范：

<div class="stack"> <p class="eyebrow">Minimal design system</p> <h1>Quiet interface system</h1> <p class="lead">Strict reduction, generous whitespace, and almost invisible component chrome.</p> <div class="actions" aria-label="Reference actions"> <a class="btn btn-primary" href="#">Primary action</a> <a class="btn btn-secondary" href="#">Secondary action</a> </div> </div>

其视觉顺序严格遵循 eyebrow → h1 → lead → actions 的递进；.stack > * + * { margin-block-start: var(--space-4); }用相邻兄弟选择器统一了纵向间距，避免逐元素手写 margin。而 components.manifest.json 的layout组件组则覆盖.container、section、main、metric-grid等布局原语，token 引用集中在容器 gutter 与区块纵向间距上——印证了"布局 = 间距令牌的组合"这一 Minimal 式思路。

7. 组件规范：按钮、输入框与卡片

原文档对组件的约束是：

• 按钮：主操作使用#0C0C09，次操作保持中性；
• 输入框：强 focus-visible 状态、清晰标签、可预期的错误提示；
• 卡片/区块：全页面保持一致的圆角、间距与抬升（elevation）策略。

components.manifest.json 给出了组件族的完整清单与令牌引用，可用作实现时的"组件契约"：

（keyboard与icons两个组件组在 Minimal 中标记为present: false，即该风格不预设键盘提示与图标插槽。）

几个值得展开的实现细节：

• 按钮最小触控高度 44px：.btn { min-height: 44px; padding: 0 var(--space-5); }，并过渡background-color/border-color/color/transform/box-shadow五个属性（140ms +--ease-standard）；
• 主/次按钮的状态分化：主按钮.btn-primary:hover仅加深背景并translateY(-1px)；次按钮.btn-secondary:hover将边框与文字色切换为--accent——一次操作、一个品牌信号；
• 焦点环统一：.btn:focus-visible与input:focus都使用box-shadow: var(--focus-ring)（即0 0 0 3px rgba(17, 17, 17, 0.18)），符合"焦点状态共享同一品牌信号"的原则；
• 状态点（status dot）：.status::before用 8px 圆形 +--success填充 +--radius-pill，配合等宽字体大写标签，是"quiet interaction"下的低噪音状态表达；
• 指标网格（metric-grid）：三等分 +--border-soft分隔线，.metric strong用--text-2xl的 display 字体凸显数字，.metric span用--muted灰化说明文字。

该 manifest 的tokens区块还给出质量数据：声明令牌 56 个、被引用 49 个、未使用 7 个（--accent-active、--danger、--elev-flat、--motion-base、--space-1、--space-12、--warn），undeclaredReferenced: []——即组件页面没有引用任何未声明的令牌，令牌纪律执行到位。

8. 动效与交互：150–250ms 的短促有目的的过渡

原文档对动效的要求是：

• 使用突出 Primary（#0C0C09）的微妙过渡作为交互信号；
• 默认短促、有目的的过渡（150–250ms），搭配稳定缓动；
• hover、focus-visible、active、disabled、loading 五种状态必须显式存在。

tokens.css将其落实为三个动效令牌：

--motion-fast: 140ms; --motion-base: 220ms; --ease-standard: cubic-bezier(0.2, 0, 0, 1);

140ms（fast，用于 hover/状态微交互）与220ms（base，用于较大变化）恰好落在文档建议的 150–250ms 窗口上下沿；cubic-bezier(0.2, 0, 0, 1)是典型的"快入慢出"产品级缓动。从 components.html 可以看到--motion-fast配合--ease-standard被统一应用于按钮过渡，而卡片/面板的抬升则通过--elev-raised（0 12px 30px rgba(0,0,0,0.08)）实现"极轻的浮起"，避免夸张投影破坏极简气质。

9. 语气与品牌：简洁、自信、面向产品

原文档第 8 节定义了 Minimal 的文案基调：

• 语气应呼应视觉风格：简洁（concise）、自信（confident）、产品化（product-specific）；
• 微文案（microcopy）保持行动导向，避免通用套话；
• 标题保留风格个性，UI 标签保持字面直白。

这条规则在 components.html 中可以直接读到范例："Quiet interface system"（标题，有风格个性）、"Primary action / Secondary action"（按钮标签，完全字面直白）、"Reference input"（表单标签，直白无修饰）、"online"（状态徽标，二字即达意）。文案与视觉双轨并行的原则，使 Minimal 既能被识别为"有性格的风格家族"，又不会牺牲界面功能的可理解性。

10. 反模式：四条纪律红线

原文档最后给出四条不可逾越的反模式，这是 Minimal 风格"护城河"：

1. 不引入色板外的颜色——当现有令牌能解决问题时，禁止新增色值（呼应 USAGE.md 的":root令牌块之外禁用裸 hex"）；
2. 不扁平化层级——禁止全文使用同一字号/字重，否则标题将失去表现力（呼应 DESIGN.md 第 3 节"headings carry the style personality"）；
3. 不添加损害可读性或可访问性的装饰效果——呼应 manifest 中craft.suggested的 craft/color.md 与 craft/accessibility-baseline.md；
4. 不在同一界面混用无关的视觉隐喻——保持单一风格语言。

11. 在 Agent 产物中正确使用 Minimal 包

USAGE.md 给出了面向 Agent 与评审者的标准使用顺序，这也是在 OpenDesign 流程中消费该包的操作手册：

1. 先读USAGE.md理解包契约；
2. 再读DESIGN.md掌握视觉意图、约束与反模式；
3. 将tokens.css粘贴进第一个产物（artifact）的<style>块，然后再编写组件 CSS；
4. 用components.manifest.json作为紧凑组件清单，需要精确选择器或状态细节时打开components.html；
5. 需要视觉抽查时，查看preview/下的预览页（preview/colors.html、preview/typography.html、preview/spacing.html）。

与之配套的"必须做 / 必须避免"清单：

Do

• 精确保留 schema 令牌名，保证跨品牌切换的可靠性；
• 用--accent表达主操作、链接、焦点状态与唯一视觉焦点；
• 优先复用components.manifest.json中的组件组，而非发明新控件；
• 将source/目录（source/evidence.md、source/tokens.source.json、source/token-contract.report.json）视为打包回填的审计证据。

Avoid

• 在复制的:root令牌块之外使用裸 hex 色值；
• 脱离tokens.css独立重定义 Tailwind 或设计令牌值；
• 声称有原始上游来源证据（本包基于精选打包 fixture 派生）；
• 添加components.html与DESIGN.md之外的组件配方。

11.1 Tailwind v4 桥接

如果产物使用 Tailwind v4，tailwind-v4.css 提供了自动桥接：它通过@import "tailwindcss"与@import "./tokens.css"引入基础，再在@theme块中将语义令牌映射为 Tailwind 主题变量（如--color-accent: var(--accent)、--font-sans: var(--font-body)、--shadow-focus-ring: var(--focus-ring)、--duration-fast: var(--motion-fast)、--spacing-section-desktop: var(--section-y-desktop)）。文件头注释明确"Derived from tokens.css. Keep tokens.css as the source of truth."（派生自 tokens.css，以 tokens.css 为唯一事实来源）——这再次强化了令牌单一来源的纪律。

12. 小结：一份规范，两层资产，一条纪律

回顾整个 Minimal 包，其设计工程化的关键在于**"意图—令牌—组件"三层一致性**：

• 意图层：DESIGN.md 以人类/Agent 可读的散文定义风格家族（留白、黑字、发丝边框、安静交互）与反模式红线；
• 令牌层：tokens.css（56 个语义令牌，审计评分 100/excellent）将意图编译为可直接渲染的 CSS 变量，并以 design-tokens.json 提供可追溯契约；
• 组件层：components.html 与 components.manifest.json 提供可复用、可审计的组件实现与清单（48 个选择器、26 个类、9 个组件组）。

对开发者而言，最核心的一条纪律贯穿始终：以tokens.css为唯一事实来源，先复制令牌块，再写组件 CSS；能用令牌解决的，绝不引入新值。只要守住这条纪律，Minimal 风格就能在 OpenDesign 的任何产物（落地页、原型、仪表盘、幻灯片）中保持一致、可信、可跨品牌切换。

【免费下载链接】open-design🎨 Best DeepSeek Harness Design Plugin. The open-source Claude Design alternative. 🖥️ Local-first desktop app. 🖼️ Your coding agent becomes the design engine: prototypes, landing pages, dashboards, slides, images & video — real files, HTML/PDF/PPTX/MP4 export. 🤖 Claude Code / Codex / Cursor / DeepSeek Harness / OpenCode & 20+ CLIs via BYOK.项目地址: https://gitcode.com/gh_mirrors/opend/open-design