Open Design 的 Apple 设计系统来源证据与 Token 契约：fixture 溯源、逐行绑定与派生输出的可审计机制-港品优选

Open Design 的 Apple 设计系统来源证据与 Token 契约：fixture 溯源、逐行绑定与派生输出的可审计机制

【免费下载链接】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

Apple 风格设计系统是 Open Design 仓库中design-systems/apple目录下的一个「Design System 2.0 回填」产物。本文以 design-systems/apple/source/evidence.md 为核心骨架，系统讲解该设计系统的来源范围声明、三个核心 fixture 文件的分工、token-contract.report.json的逐 Token 溯源契约，以及design-tokens.json与tailwind-v4.css这类派生输出为何必须由脚本再生成而不能手改；同时结合 tokens.css 与 tokens.schema.ts 的源码注释，还原品牌 prose 描述被翻译成 lint 强制 token 名的完整链路，并给出 Agent 实战使用这套设计系统时应遵循的粘贴与生成规则。

一、什么是「来源证据」：evidence.md 的定位

evidence.md是design-systems/apple/source/目录下的一份声明性文档，全文只有四个小节，但它的作用是整个 Apple 设计系统可审计性的根基：

Source Scope（来源范围）：明确声明这套系统是从 OpenDesign 捆绑的精选 fixture 派生的回填（backfill），而不是对上游品牌仓库或官网的新一轮爬取。这一声明划定了证据边界——后续所有 Token 值的"置信度"都以此为上限。
Included Fixture Files（包含的 fixture 文件）：列出三个支撑文件：DESIGN.md（人类可读的品牌语言分析）、tokens.css（机器可读的 Token 绑定）、components.html（组件落地示例）。
Token Contract（Token 契约）：规定source/token-contract.report.json将每一个 TOKEN_SCHEMA 绑定映射回tokens.css中具体的声明行；同时规定design-tokens.json和tailwind-v4.css是派生输出，必须从报告与 token 样式表再生成，禁止手工编辑。

换句话说，evidence.md 回答的是审计者最关心的问题："这套设计系统里的每一个值，是从哪里来的、凭什么成立？"答案就是——来自捆绑 fixture，且每条绑定都有文件与行号可查。

证据目录的整体结构

Apple 设计系统的完整文件布局（位于 design-systems/apple）：

路径	角色
DESIGN.md	品牌语言分析：色彩、字体、组件、布局、响应式、Agent 提示词
tokens.css	机器可读的`:root`Token 声明（56 个绑定）
components.html	组件落地 HTML 示例
source/token-contract.report.json	Token 契约报告：每个 Token → 来源行号
source/tokens.source.json	精简版 Token 来源清单（同样带行号）
design-tokens.json	派生输出（JSON 形态）
tailwind-v4.css	派生输出（Tailwind v4 形态）
system/index.html、`kit.html`、`kit.dark.html`	系统预览与组件套件
preview/ 下`colors.html`、`spacing.html`、`typography.html`	单维度可视化预览

DESIGN.md还有 DESIGN-zh.md、DESIGN-ja.md 等十余种语言的翻译版本，可见这套文档本身被当作可多语言消费的规范资产来维护。

二、三个核心 fixture 的分工：从品牌语料到机器 Token

evidence.md 把支撑文件限定为三个，它们的职责互补且不重叠：

1. DESIGN.md —— 人类语义层

DESIGN.md 用 prose 描述 Apple 的设计语言，核心结论包括：

视觉基调：精确的编辑式系统，在"画廊般的宁静"与"零售密度信息块"之间交替；界面 chrome 刻意弱化，让产品影像成为叙事前景。
双档运行模式：营销面（首页、Environment）用电影感黑/浅章节；商务面（Store、购买流程）收紧间距、增加工具控件与卡片堆叠——同一套品牌语法下的 showcase mode 与 transaction mode。
关键色彩：绝对黑#000000与浅苹果灰#f5f5f7构成二元章节节奏；单一蓝色系（#0071e3、#0066cc、#2997ff）承担全部动作与链接语义。
字体体系：SF Pro Display 承担 hero 与商品层级，SF Pro Text 承担导航、控件与密集商务文案；正文基线为 17px，正文行高 1.47。
圆角分级：5px（微工具）→ 8–12px（标准控件）→ 16–18px（卡片/商务面板）→ 28–36px（焦点模块）→ 56/100/980px（胶囊与签名 CTA）→ 50%（圆形选择控件）。
Do's and Don'ts：例如"Do 保持中性三元组（黑/浅灰/白）作为结构基底"、"Don't 引入与 Apple 蓝竞争的宽泛次强调色板"。
Agent Prompt Guide：Quick Color Reference 快速取色表 + 五个示例组件提示词 + 六步迭代指南。

2. tokens.css —— 机器语义层

tokens.css 是这套设计系统的机器可读形式，文件头部注释明确写出其存在理由：

DESIGN.md 告诉人类 Apple 用"Pale Apple Gray（#f5f5f7）"作为主浅色面、"Apple Action Blue（#0071e3）"作为主强调色，但 Agent 必须把这些 prose 名称翻译成 lint 强制执行的标准化 Token 名（--surface、--accent）——而这一步翻译正是 Token 误用的高发地带。本文件把品牌翻译一次，让 Agent 复制结构而不是发明结构。

文件开头的 7 条"品牌专属 schema 决策"（non-obvious bindings）值得逐一注意，它们是理解tokens.css设计意图的钥匙：

--surface-warm绑定到真实中间层级#fbfbfd，不是--surface的别名——Apple 的浅色阶梯真实存在三段（纯白零售画布、近白亮度偏移带、浅灰特性区），折叠会抹掉真实品牌特征。
--fg-2、--meta、--border-soft均绑定独立值而非别名——Apple 的中性文字斜坡是经典四段式（近黑墨 → 工具深灰 → 次级中性灰 → 中边框灰），schema 的 B 槽位可干净映射。
--radius-pill绑定980px 而非 9999px——Apple 发布的 CSS 中签名胶囊 CTA 的字面值就是 980px，这个数字本身就是品牌可辨识细节。
--accent-hover是提亮（#0077ed）而非压暗——Apple 的蓝色按钮 hover 时微微变亮；schema 默认的黑混合公式会与之冲突。--accent-active压暗到#0066cc（即文档化的 Body Link Blue）。
--tracking-display为-0.015em——对应 80px hero 的 -1.2px，更紧会在小字号下崩坏，更松则失去 Apple 的机械感。
--section-y-desktop为 100px——比 schema 默认 80px 更慷慨，呼吸空间让产品影像"说话"。
--ease-standard为cubic-bezier(0.28, 0, 0.22, 1)——Apple 风格的"强减速后静止"，从不反弹。

3. components.html —— 落地示例层

components.html 提供组件级落地示例（manifest 见 components.manifest.json），将 Token 组合为按钮、卡片、输入框、导航、轮播点等真实 UI。三份 fixture 合起来构成「语义 → Token → 组件」的完整证据链。

三、Token 契约：逐条绑定可审计

3.1 token-contract.report.json 的构成

source/token-contract.report.json 是契约的核心交付物，其结构分为两部分：

summary 聚合统计：

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

tokens 数组中每个条目形如：

{ "name": "--accent", "layer": "A1-identity", "value": "#0071e3", "confidence": "high", "reason": "Bundled tokens.css declares --accent; no upstream recrawl was performed for this backfill.", "sources": ["tokens.css:114"], "sourceName": "--accent" }

关键字段解读：

layer：Token 所属分层。共有四个层：A1-identity（品牌身份值，如--bg、--fg、--accent、字体栈）、A1-structure（结构决策，如字号阶梯、容器宽度、章节纵向节奏）、A2（可回退的派生值，如--accent-on、圆角、动效、投影）、B-slot（schema 预留的"槽位"别名，如--fg-2、--meta、--surface-warm、--border-soft）。
confidence：本报告中全部为"high"，原因统一为"捆绑的 tokens.css 声明了该值；本次回填未进行上游重爬"——这与 evidence.md 的 Source Scope 声明严格一致。
sources："tokens.css:114"形式的文件 + 行号引用，实现"每一个 TOKEN_SCHEMA 绑定都能映射回提交的tokens.css声明行"的契约承诺。
score: 100 / grade: "excellent"：56/56 个 Token 均有来源支撑、0 个别名 Token、无需重建，这是报告对自身完整性的量化结论。

source/tokens.source.json是同一信息的精简版本（brandId: "apple"，同样逐 Token 附source: "tokens.css:77"行号），可作为报告的低开销替代品。

3.2 Token 分层与共享 schema 的关系

tokens.css头部注释声明了契约来源：

标准 Token 名：来自 design-systems/_schema/tokens.schema.ts 的TOKEN_SCHEMA——该文件实际只是转发导出 packages/contracts/src/design-systems/token-schema.ts。也就是说，--surface、--accent这类"lint 强制执行的标准名"由跨包共享的 contracts 定义。
A2 回退值：来自 design-systems/_schema/defaults.css。Apple 覆盖了其中的--motion-base、--ease-standard、--elev-raised、--focus-ring、--radius-pill五项，其余与默认值一致。
Lint 强制：来自 apps/daemon/src/lint-artifact.ts——:root之外出现超过 12 个裸十六进制色值记 P1，非 Token 强调色记 P0。

3.3 三层分层的实际语义（以 Apple 为例）

将四个 layer 与 Apple 的具体值对照，可以看清每一层承担的不同职责：

A1-identity（8 个）——品牌不可妥协的身份值：

Token	值	含义
`--bg`	`#ffffff`	默认页面背景（纯白零售/hero 画布）
`--surface`	`#f5f5f7`	卡片与特性区抬升的浅苹果灰
`--fg`	`#1d1d1f`	浅色画布上的主文字（近黑墨，非纯黑）
`--muted`	`#6e6e73`	次级说明文字
`--border`	`#d2d2d7`	默认分隔线与卡片边缘
`--accent`	`#0071e3`	唯一的持久彩色——动作蓝
`--font-display`	`"SF Pro Display", ...`	Display 族 + 完整回退链
`--font-body`	`"SF Pro Text", ...`	Text 族 + 完整回退链

A1-structure（18 个）——品牌化的结构决策：--text-xs(12px) 到--text-4xl(80px) 的八级字号、--leading-body(1.47) 与--leading-tight(1.05)、--tracking-display(-0.015em)、--section-y-*(100/64/40px)、--container-max(1024px) 与三级 gutter(22/18/16px)。

A2（26 个）——带共享默认值的可覆盖项：--accent-on、--accent-hover、--accent-active、语义三色、--font-mono、间距阶梯、圆角、投影、焦点环、动效。A2 项的默认值来源是defaults.css，Apple 只在其上做了 5 处覆盖（见上文 schema 决策）。

B-slot（4 个）——--surface-warm、--fg-2、--meta、--border-soft。这是 schema 为"品牌中文字面常见但默认无值"的槽位；defaults.css明确说明 B-slot 通过各品牌tokens.css内的var()别名解析，不由默认文件提供。

四、派生输出：为什么禁止手改

evidence.md 对design-tokens.json和tailwind-v4.css给出了明确的操作纪律：

design-tokens.json和tailwind-v4.css是派生输出，应从报告和 token 样式表再生成，而非手工编辑。

背后的工程理由（可从仓库结构推断）：

单一事实源（Single Source of Truth）：tokens.css的:root块是唯一权威声明；token-contract.report.json是它与共享 schema 之间的绑定审计记录。任何 JSON / Tailwind 形态都只是同一事实的不同投影。
防漂移（Drift）：defaults.css头部注释揭示了仓库的防漂移契约——存在名为design-system: A2 defaults parity的 guard 检查，断言defaults.css中每条声明与tokens.schema.ts对应条目的fallback字段一致，两边必须同步更新。同理，派生输出若被手改，就会与tokens.css脱节，而下次再生成会覆盖手改内容。
可再生的机器链路：契约报告把每个 Token 值锚定到行号，意味着派生脚本可以稳定地重放生成过程——这正是score: 100 / recommendRebuild: false想要表达的：当前状态自洽，无需人工介入重建。

五、Agent 实战：如何使用这套设计系统生成工件

5.1 标准工作流

依据tokens.css头部注释，Agent 使用 Apple 设计系统生成工件时应当遵循：

把tokens.css的:root { ... }块逐字粘贴到所生成工件第一个<style>中；
之后所有样式一律通过var(--name)引用，不再书写裸十六进制值；
不要发明tokens.css或共享 schema 中不存在的 Token 名（"Keep this file additive"——只覆盖值，不改键名）；
对派生 Token 的需求（如 JSON 配置、Tailwind 主题）应走再生成脚本，而非直接编辑派生文件。

5.2 lint 强制的两条红线

从tokens.css引用的 apps/daemon/src/lint-artifact.ts 可以确认两条硬性检查：

:root之外的裸十六进制色值超过 12 个 → P1 问题：强制 Agent 在组件层级用 Token 而非散落色值。
非 Token 的强调色 → P0 问题：强制蓝色系动作语义只能来自--accent家族，杜绝 Agent 自造色值冒充品牌强调色。

5.3 品牌语言速查（Agent Prompt 参考）

DESIGN.md第 9 节提供了可直接投喂给 Agent 的提示词，例如：

"Design an Apple-style product hero on a black canvas (#000000) with SF Pro Display semibold headline (48-56px), concise supporting copy, and two capsule CTAs using#0071e3and#1d1d1f."
"Create a commerce configuration panel on white (#ffffff) with 18px rounded cards,#86868bborder fields, SF Pro Text 17px body copy, and compact option selectors."

迭代顺序也有明确指引：先锁中性基底（#000000/#f5f5f7/#ffffff）→ 再调强调色（保持稀缺）→ 按"display 字号 → 正文可读性 → 微标签"顺序调排版 → 按组件类别匹配圆角（field/card/capsule/circle）→ 从 showcase 到 commerce 逐步加密 → 最后验证产品影像仍是最强视觉层。

六、已知边界与证据缺口

evidence.md 与 DESIGN.md 都诚实标注了这套系统的边界：

语义状态色：DESIGN.md明确记录"提取的页面集中未持续观察到独立的 error/warning/success 语义色板"，因此tokens.css的--success/--warn/--danger原样继承 schema 默认值（#16a34a/#eab308/#dc2626），并在注释中要求"任何表面面积上保留低于 5% 的使用比例"。
交互微状态：部分交互微状态随模块而异，未表示为通用系统 Token；个别零售模块存在上下文特定的排版覆盖，未出现在全部五个分析页面中。
来源边界：所有值都来自捆绑 fixture（open-design-bundled-fixture），而非上游官网重爬——因此任何"置信度"描述都不应被解读为对实时上游的核对。

这些缺口非但无损文档价值，反而是证据纪律的体现：能证明的写证据，不能证明的写边界。对于任何要在自己品牌上克隆此模板的团队，tokens.css的收尾建议同样适用——新品牌应覆盖值、保留键名、保持文件纯增量演进，并让每条绑定都能像 Apple 这样回溯到一行可审计的声明。

创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考

企业官网建设流程全解析