OpenDesign 中的 Ollama 设计系统包：evidence.md 证据链、Token 契约与极简黑白设计令牌的完整实现

• AI 应用
• 人工智能
• AI 技能
• 设计系统
• 媒体生成

本文围绕 OpenDesign 仓库内design-systems/ollama/设计系统包的审计证据文件 source/evidence.md 展开，系统讲解该 Design System 2.0 backfill 的来源范围、fixture 文件清单、Token 契约机制，以及背后完整的 Ollama 极简设计语言——从 DESIGN.md 的视觉规范到 tokens.css 的 56 个设计令牌、再到 Tailwind v4 派生输出与同步守卫。读完本文，你将掌握如何阅读与复用一套已入库的第三方品牌设计系统，理解其“token 声明 → 契约报告 → 派生产物”的证据链闭环，并能将其直接用于 Agent 生成前端工件的实践中。

一、evidence.md 是什么：一次 backfill 的“审计证据文件”

在 OpenDesign 的design-systems/目录下，每个品牌（ollama、stripe、figma 等）都是一个可被 Agent 直接消费的“设计系统包”。其中ollama/source/evidence.md是这套包的元证据文件——它不描述具体样式，而是说明这套系统是从哪里来的、包含哪些文件、以及 token 如何被验证。

全文只有三个要点：

1. 来源范围（Source Scope）：这是 Design System 2.0 的 backfill（回填），派生自 OpenDesign 官方捆绑（bundled）的精选 fixture，并不声称对上游品牌官网做过全新爬取。这一点在 manifest.json 中有对应声明："source": { "type": "bundled", "origin": "OpenDesign curated bundled fixture" }。
2. 包含的 fixture 文件：DESIGN.md（设计规范）、tokens.css（令牌样式表）、components.html（参考组件）。
3. Token 契约：source/token-contract.report.json把每一个 TOKEN_SCHEMA 绑定映射回tokens.css的具体声明行；而design-tokens.json与tailwind-v4.css是派生输出，应当从报告与令牌样式表重新生成，而不是手工编辑。

一句话概括：evidence.md 是保证“设计系统来源可信、token 有据可查”的审计入口。它的价值在于让任何 Agent 或审查者都能沿着文件路径和行号，从“契约报告”一路追到“真实声明”，避免出现无法溯源、凭空捏造的设计令牌。

二、包的完整文件布局：证据文件、令牌与产物

design-systems/ollama/是一个自洽、可验证的包，完整结构如下（均以仓库根目录为基准）：

manifest.json中files、preview、sourceFiles三个字段将上述文件正式登记为包的组成部分，并声明"importMode": "normalized"（归一化导入模式）以及craft.suggested为color与accessibility-baseline，提示使用本系统时应重点关注配色与无障碍基线。

三、Token 契约：从报告到tokens.css声明的逐行映射

evidence.md点名的核心机制是source/token-contract.report.json。这份报告以TOKEN_SCHEMA为契约，为每个 token 记录：

• name / value：token 名与解析后的值；
• layer：所属层（A1-identity、A1-structure、A2、B-slot），对应_schema的分层模型；
• sources：指向tokens.css中的声明行号（如tokens.css:79）；
• confidence / reason：置信度与原因说明。

报告顶部的summary是整套契约的可量化结论：

{ "totalTokens": 56, "declaredTokens": 56, "sourceBackedTokens": 56, "sourceBackedA1": 26, "fallbackTokens": 26, "aliasTokens": 2, "layerCounts": { "A1-identity": 8, "B-slot": 4, "A2": 26, "A1-structure": 18 }, "score": 100, "grade": "excellent", "recommendRebuild": false }

从中可以读出三层含义：

• 56 个 token全部有源可查（sourceBackedTokens = 56），评分 100、评级excellent，因此无需重建（recommendRebuild: false）；
• 26 个 A1 层 token 直接来自品牌身份（identity）声明，18 个来自结构（structure），26 个是 A2 层语义 token；
• 2 个 alias token（--surface-warm、--border-soft）通过var(--surface)、var(--border)引用，体现“单一事实源”的设计。

与之配套的 source/tokens.source.json 是更朴素的源清单，例如--bg记录为{ "value": "#ffffff", "layer": "A1-identity", "source": "tokens.css:79" }。行号即证据——这正是 evidence.md 所强调的“每个 TOKEN_SCHEMA 绑定都能映射回提交的tokens.css声明行”。

四、设计语言本体：Ollama 的“激进极简主义”

要理解这套 token 为什么这样取值，必须读 DESIGN.md。它描绘的品牌是：本地运行 LLM 的终端优先工具，纯黑白、无阴影、无渐变、二元圆角——“设计的缺席本身就是设计”。

4.1 视觉主题与关键特征

• 纯白画布，界面零彩色（唯一例外是键盘焦点环）；
• SF Pro Rounded 标题字体带来苹果式的柔和感；
• 二元圆角系统：容器 12px、一切可交互元素 9999px（胶囊）；
• 零阴影——层次完全靠背景色差与 1px 边框表达；
• 极低的内容密度：首页短小聚焦，只讲三件事（运行模型、配合应用、集成）。

4.2 色彩角色（完整色板）

渐变系统：无。视觉分隔完全来自纯色块与单像素边框。

4.3 字体栈与层级

三组字体栈（DESIGN.md §3 原文）：

--font-display: "SF Pro Rounded", system-ui, -apple-system, system-ui; --font-body: ui-sans-serif, system-ui, "Apple Color Emoji", "Segoe UI Emoji", "Segoe UI Symbol", "Noto Color Emoji"; --font-mono: ui-monospace, SFMono-Regular, Menlo, Monaco, Consolas, "Liberation Mono", "Courier New", monospace;

层级要点：Display 48px/500/行高 1.0；Section Heading 36px；Sub-heading 30px；Body 16px/行高 1.5；代码层 12–16px 走 monospace。只用 400 与 500 两种字重，标题行高压缩到 1.0、正文放宽到 1.43–1.56，靠“行高对比”而非“字重对比”建立层级。

4.4 组件规范摘要

• Gray Pill（主按钮）：#e5e5e5背景、#262626文字、10px 24px内边距、1px solid #e5e5e5边框、9999px 胶囊圆角；
• White Pill（次按钮）：白底、#404040文字、1px solid #d4d4d4边框；
• Black Pill（CTA）：纯黑底白字，最大强调；
• 卡片/容器：白或 Snow 底、1px solid #e5e5e5边框、唯一的 12px 圆角、零阴影；
• 输入框：白底、1px solid #e5e5e5、胶囊圆角、聚焦显示 Ring Blue 环、占位符 Silver；
• 导航：透明无边框，左侧 logo + 黑色 16px 文字链接，中间胶囊搜索框，右侧 “Sign in” 链接 + 黑色胶囊 “Download” CTA；
• 特色组件：胶囊 Tab、模型标签（Light Gray 底深色字）、终端命令块（monospace + 12px 圆角边框容器 + 复制按钮）、集成网格（按 Coding / Documents & RAG / Automation / Chat 分 Tab）。

4.5 布局、间距与层级

• 间距基准 8px，扩展刻度 4/6/8/9/10/12/14/16/20/24/32/40/48/88/112px；按钮统一10px 24px；区块纵向间距 88–112px（“留白即品牌”）；
• 容器最大宽约 1024–1280px 居中；Hero 单列居中，功能区块两列（文字左、代码右）；
• 深度模型只有两级：Flat（无阴影无边框）与 Bordered（1px solid #e5e5e5）——零阴影是刻意决定，层次靠内容层级与字重传达。

4.6 Do's and Don'ts（浓缩）

Do：纯白背景；所有交互元素用 9999px；容器用 12px；严格灰度；显示标题用 SF Pro Rounded 500；零阴影；低内容密度；命令用 monospace；按钮统一10px 24px胶囊。

Don't：引入任何彩色；使用 12px–9999px 之间的圆角；加阴影；字重超过 500；添加除羊驼吉祥物以外的装饰插图；使用渐变；超过两列布局；边框粗于 1px；添加 hover 动画。

4.7 响应式断点

Hero 文字 48px → 36px → 30px 渐进缩放；触控目标轻松超过 44×44px。

4.8 Agent Prompt Guide（可直接复用）

DESIGN.md §9 提供了一组开箱即用的示例提示，例如：

• “在纯白（#ffffff）上创建 hero：插图居中于 48px SF Pro Rounded weight 500、行高 1.0 的标题上方，Pure Black 文字；下方放一个黑色胶囊 CTA（9999px 圆角、10px 24px 内边距）与一个灰色胶囊按钮。”
• “设计一个代码块：12px 圆角、1px solid #e5e5e5边框、白底，命令用 ui-monospace 16px，无阴影。”
• “构建胶囊 Tab 栏：激活态 Light Gray 底 + Near Black 文字，非激活透明底 + Stone 文字。”

迭代守则：一次只做一个组件；所有值保持灰度；圆角永远在“9999px 或 12px”二选一；阴影恒为零；字重恒为 400/500；“觉得装饰过度就去掉”——少即是多。

五、tokens.css 的五条关键决策：规范如何落地为令牌

tokens.css 在头部注释里记录了把 DESIGN.md 翻译成 token 时的五个决策，这是理解整套取值的关键：

• #Decision 1 —--bg是纯白，--surface才是“抬升”：默认品牌习惯是米色底 + 白色表面（追求卡片暖意），Ollama 反过来——#ffffff是画布，#fafafa（Snow）是最微弱的抬升，--surface-warm直接别名到--surface（品牌天然灰度，无暖色第三层）。
• #Decision 2 —--accent是纯黑而非彩色 CTA：整个界面灰度，唯一彩色例外是键盘焦点环；承担 accent 角色的“Download / Create account”黑胶囊是黑底白字，所以--accent: #000000、--accent-on: #ffffff，且 hover/active变亮（#262626→#404040）而非变暗。
• #Decision 3 — 所有交互圆角坍缩为胶囊：--radius-sm、--radius-lg、--radius-pill全部解析为 9999px，--radius-md才是 12px 容器角，保证组件取到--radius-sm时继承品牌立场而不是一个游离的 8px。
• #Decision 4 — 每个层级都是发丝线边框环，绝非模糊阴影：--elev-flat: none、--elev-ring: 0 0 0 1px var(--border)、--elev-raised镜像--elev-ring——深度只能来自 1px 边框环。
• #Decision 5 — 显示字体是 SF Pro Rounded：圆润的字形终端就是品牌表达；非 Apple 平台回退 system-ui（栈中重复的system-ui是刻意逐字复刻 DESIGN.md，便于“散文 ↔ token”审计）。

同时文件规定：保持增量式扩展，绝不发明 DESIGN.md 或 craft 契约中不存在的 token 名——Ollama 不在 BRAND_EXTENSIONS 名单内，任何未知 token 都会触发unknown-token-allowlist守卫失败。语义色（--success: #16a34a、--warn: #eab308、--danger: #dc2626）是为了 schema 完整性绑定到回退值，供错误 toast 与守护进程健康检查等运行时场景使用，禁止作为装饰。

六、派生输出与同步守卫：为什么不能手工编辑

evidence.md明确指出design-tokens.json与tailwind-v4.css是派生输出。以 tailwind-v4.css 为例，它只做一件事——把 tokens.css 的:root值桥接进 Tailwind v4 的@theme：

@import "tailwindcss"; @import "./tokens.css"; @theme { --color-bg: var(--bg); --color-surface: var(--surface); --color-accent: var(--accent); --font-display: var(--font-display); --radius-md: var(--radius-md); --shadow-ring: var(--elev-ring); /* ... 其余 token 同理 */ }

这意味着项目里可以同时用bg-surface、text-muted、rounded-pill等 Tailwind 工具类，但它们的值始终解析回 tokens.css。同样，design-tokens.json 是从 token 样式表生成的机器可读版本。

为了保证“源文件 ↔ 组件 fixture”不被手工改动破坏，仓库提供了守卫脚本 scripts/check-tokens-fixture-sync.ts（并被 scripts/guard.ts 引用）。tokens.css 注释里写得很明确：components.html内嵌的:root块是去掉注释后的同一份声明，归一化后必须逐字节同步，否则tokens-fixture-sync守卫会失败。因此正确的工作流永远是：

1. 修改 tokens.css（唯一事实源）；
2. 重新生成design-tokens.json、tailwind-v4.css与components.html的内嵌:root；
3. 运行tokens-fixture-sync守卫确认同步。

七、Agent 与审查者的使用流程（USAGE.md 阅读顺序）

USAGE.md 给出了标准使用协议：

1. 先读 USAGE.md理解包契约；
2. 读DESIGN.md掌握视觉意图、约束与反模式；
3. 把tokens.css 的:root块逐字粘贴到工件第一个<style>中，之后一律通过var(--name)引用；
4. 用components.manifest.json做组件清单速查（fixture 显示 70 个 selector、34 个 class、26 个元素、1 个 style 块），需要精确选择器或状态时打开components.html；
5. 需要视觉抽查时查看preview/下的颜色、间距、排版三页。

使用铁律同样重要：不得在:root块之外使用裸十六进制值；不得脱离 tokens.css 独立重定义 Tailwind 或 design-token 值；不得声称拥有上游原始来源证据（本包基于精选 fixture）；不得新增 components.html 或 DESIGN.md 中不存在的组件配方。跨品牌切换时，保留 schema token 名不变即可保证可靠性——这正是“Design System 2.0 归一化”的核心收益。

八、总结：一条可审计的第三方设计系统落地路径

从 source/evidence.md 出发，我们完整走通了一条链路：

来源声明（bundled fixture，不冒称爬取上游）→ fixture 文件集（DESIGN.md / tokens.css / components.html）→ Token 契约报告（56 个 token 逐行映射、评分 100）→ 派生产物（design-tokens.json / tailwind-v4.css）→ 同步守卫（check-tokens-fixture-sync.ts）→ Agent 消费（USAGE.md 五步流程）。

这套“证据文件 + 契约报告 + 守卫脚本”的机制，让第三方品牌设计系统在 OpenDesign 仓库中既可以被 Agent 直接粘贴复用，又经得起逐行溯源审计；而 Ollama 案例本身则示范了如何把“纯黑白、零阴影、二元圆角、双字重、低密度留白”的激进极简语言，精确翻译成一组自洽、可验证、可跨框架复用的设计令牌。读者若要在自己的工件事务中复刻这套流程，只需照搬design-systems/ollama/的文件结构与同步策略，即可获得同样可审计、可回归的品牌设计系统包。

• AI 应用
• 人工智能
• AI 技能
• 设计系统
• 媒体生成