企业官网建设流程全解析

OpenDesign 设计系统源证据与 Token 合约：Lamborghini 包的可追溯性审计机制解析

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

设计系统 2.0（Design System 2.0）为 OpenDesign 引入了可审计的"源证据（source evidence）"体系：每个设计系统包不仅要交付可用的 tokens、组件与视觉规范，还必须说明"这些内容从何而来、可信度如何"。本文以 design-systems/lamborghini 包为实例，拆解其source/evidence.md声明、Token 合约报告（token-contract.report.json）的追溯机制、以及派生产物（design-tokens.json、tailwind-v4.css）与源文件之间的生成关系，帮助你理解 OpenDesign 设计系统包的目录契约与审计语义，并掌握在 Agent 工作流中正确使用这套包的方法。

一、源证据是什么：包的"来源声明"与边界

阅读 source/evidence.md 会发现，它不是一份普通的设计文档，而是一份来源审计声明，回答了三个关键问题：

1. 包的来源范围（Source Scope）：该包是"Design System 2.0 backfill"，源自 OpenDesign 捆绑的精选 fixture（curated bundled fixture），不声称对原始上游品牌仓库或网站进行了全新爬取（"It does not claim a fresh crawl of the original upstream brand repository or website"）。
2. 包含的 fixture 文件：明确列出了三个支撑文件——DESIGN.md（视觉规范）、tokens.css（Token 声明）、components.html（参考组件）。
3. Token 合约（Token Contract）：声明source/token-contract.report.json将每一个TOKEN_SCHEMA绑定映射回已提交的tokens.css声明行；而design-tokens.json与tailwind-v4.css是派生输出，应基于报告与 token 样式表重新生成，而非手工编辑。

这一声明的价值在于诚实性边界：它明确区分了"基于上游品牌观察整理的规范"与"对上游代码的抓取"，避免 Agent 或审查者误把二次整理素材当作品牌官方源码。这一点在包级元数据中也有对应体现——manifest.json 的source字段标记为{ "type": "bundled", "origin": "OpenDesign curated bundled fixture" }，并采用importMode: "normalized"的导入模式。

二、包的目录契约：四层文件体系

整个 lamborghini 包 遵循固定的目录契约，从 manifest.json 的files字段可以还原出完整映射：

从源码结构看，source/目录承载的是"审计证据"职责，USAGE.md 明确要求"Treatsource/files as audit evidence for the bundled fixture backfill"——即source/下的文件用于证明捆绑 fixture 回填的可追溯性，而非直接供组件引用。

三、Token 合约报告：从 Token 名到 CSS 声明行的双向映射

Token 合约机制是这套审计体系的核心。source/token-contract.report.json 以TOKEN_SCHEMA为契约，为每一个 Token 记录四个关键字段：

{ "name": "--bg", "layer": "A1-identity", "value": "#050505", "confidence": "high", "sources": ["tokens.css:8"], "sourceName": "--bg" }

其中：

• name与sourceName：报告内的 Token 名与被绑定的 CSS 变量名；
• layer：Token 所属的语义分层（详见下文）；
• value：解析后的最终值；
• sources：以tokens.css:行号形式精确指向声明行——这是"可追溯"的关键证据；
• confidence：本次报告中全部为high，理由统一为"Bundled tokens.css declares …; no upstream recrawl was performed for this backfill"（捆绑 tokens.css 已声明该 Token，本次回填未执行上游重新爬取）。

3.1 四个语义分层

报告把 56 个 Token 划分为四个层级（layerCounts）：

从分层可以推断这套 TOKEN_SCHEMA 的设计意图：A1-identity承载不可妥协的品牌识别值，A1-structure承载排版与布局骨架，B-slot是品牌色向组件槽位的桥接，A2则是可被组件自由消费的功能 Token。跨品牌切换时，正是依靠保持A1层 Token 名不变、仅替换值，才能实现 USAGE.md 中所说的"cross-brand switching stays reliable"。

3.2 统计指标与分级

报告summary块给出的关键审计指标如下：

{ "totalTokens": 56, "declaredTokens": 56, "sourceBackedTokens": 56, "sourceBackedA1": 26, "fallbackTokens": 26, "aliasTokens": 0, "score": 100, "grade": "excellent", "recommendRebuild": false }

• totalTokens/declaredTokens均为 56，说明没有缺失声明；
• sourceBackedTokens: 56说明每个 Token 都能在tokens.css中找到声明行；
• sourceBackedA1: 26对应A1-identity（8）+A1-structure（18），即品牌身份与结构层全部有源支撑；
• fallbackTokens: 26恰好等于A2层数量，可推断A2层 Token 使用了回填值（其值同样来自捆绑的tokens.css，但语义上属于功能回退而非品牌识别）；
• aliasTokens: 0，即没有 Token 以别名（alias）形式引用其他 Token；
• 综合score: 100、grade: "excellent"、recommendRebuild: false，表示该包契约完整，无需重建。

四、派生产物：design-tokens.json 与 tailwind-v4.css 的生成关系

evidence.md 特别强调：design-tokens.json与tailwind-v4.css是派生输出（derived outputs），应从token-contract.report.json与tokens.css重新生成，而不应手工编辑。这意味着它们不是"第二份事实来源"，而是同一份真相的两种工程化投影：

• design-tokens.json 将 56 个 Token 投影为带type的 JSON 结构（color、fontFamily、dimension、number、shadow、duration、cubicBezier），供需要程序化读取 Token 的工具链消费；
• tailwind-v4.css 文件头直接写明 "Derived from tokens.css. Keep tokens.css as the source of truth."，并通过 Tailwind v4 的@theme指令把tokens.css的:root变量逐项映射为 Tailwind 主题变量，例如--color-accent: var(--accent)、--spacing-4: var(--space-4)、--shadow-raised: var(--elev-raised)。

从文件头注释与映射结构可以确认工程链路为：tokens.css（唯一事实来源）→token-contract.report.json（绑定审计）→ 生成design-tokens.json与tailwind-v4.css。因此任何 Token 值调整都应落在tokens.css的:root块内，再重新生成派生产物，避免两处漂移。

五、Token 源文件：tokens.css 的 56 个绑定

tokens.css 是整条链路的根。其:root块按语义分组声明了全部 56 个 Token，每组与token-contract.report.json的layerCounts一一对应：

颜色（品牌身份与插槽）：--bg: #050505、--surface: #141414、--surface-warm: #211b0b、--fg: #f8f4e6、--fg-2: #d8ceb0、--muted: #9b927d、--meta: #d4af37、--border: #3a321d、--border-soft: #282315、--accent: #d4af37、--accent-on: #050505。

交互与语义色：--accent-hover: color-mix(in oklab, var(--accent), black 8%)、--accent-active: color-mix(in oklab, var(--accent), black 14%)、--success: #39a852、--warn: #f7c948、--danger: #e63946。值得注意的是，hover/active 态使用 CSScolor-mix(in oklab, …)从基准色派生，而非硬编码另一组 hex——这正是"单一事实来源"思想的体现。

字体与排版：--font-display: "Lamborghini", "Eurostile", Arial, sans-serif、--font-body: "Inter", Arial, sans-serif、--font-mono: "SF Mono", ui-monospace, Menlo, monospace；字号阶梯--text-xs: 12px至--text-4xl: 90px；行高--leading-body: 1.48、--leading-tight: 0.96；字距--tracking-display: -0.025em。

间距与容器：8px 基数衍生出--space-1: 4px到--space-12: 48px；区块纵向留白--section-y-desktop: 112px/--section-y-tablet: 80px/--section-y-phone: 56px；容器约束--container-max: 1240px与三个断点的 gutter（40px / 28px / 18px）。

圆角、阴影与动效：--radius-sm: 2px至--radius-pill: 9999px；--elev-flat: none、--elev-ring: 0 0 0 1px var(--border)、--elev-raised: 0 28px 84px rgba(0,0,0,0.54)、--focus-ring: 0 0 0 4px rgba(212,175,55,0.32)；时长--motion-fast: 120ms、--motion-base: 210ms；缓动--ease-standard: cubic-bezier(0.16, 1, 0.3, 1)。

components.html 第 11–69 行的<style>块原样内嵌了这一整套:root声明，可作为"Token 先于组件"这一使用约束的现场印证。

六、使用方式：OpenDesign Agent 与审查者的阅读顺序

USAGE.md 给出了明确的包消费顺序，这也是 Agent 生成页面时的实操指引：

1. 先读USAGE.md理解包契约；
2. 再读 DESIGN.md 获取视觉意图、约束与反模式；
3. 把 tokens.css 的:root块整体粘贴到第一个 artifact 的<style>块中，再编写组件 CSS；
4. 用 components.manifest.json 做组件清单速查，需要精确选择器或状态时打开 components.html；
5. 需要视觉核对时打开preview/下的 colors.html、typography.html、spacing.html。

同时，USAGE.md 划定了四条硬性约束：

• 保留 schema Token 名不变，以保证跨品牌切换可靠；
• 使用--accent承担主操作、链接、焦点态与唯一视觉焦点，避免在:root之外使用裸 hex 值；
• 优先复用components.manifest.json中的组件分组，而不是发明新控件；
• 不得声称持有原始上游来源证据——本包基于捆绑 fixture，且不得添加components.html或DESIGN.md未覆盖的新组件配方。

6.1 组件清单佐证

components.manifest.json 的groups数组显示该包已覆盖 8 类组件组中的 6 类：buttons、inputs、cards、badges、links、typography、layout（keyboard 与 icons 标记为present: false）。其中 buttons 组引用了--accent、--accent-on、--elev-ring、--radius-md、--space-5、--text-sm等 Token；cards 组引用--elev-raised、--radius-lg、--muted等。同时报告了undeclaredReferenced: []与unusedDeclared列表（含--danger、--warn、--space-1等 7 个声明但未在组件中使用的 Token）——这套"声明 / 引用 / 未使用 / 未声明"的对照本身就是 Token 治理的一部分。

6.2 视觉规范要点（供 Agent 生成时对照）

DESIGN.md 定义了"黑底 + 单一金色强调"的极简体系，可作为生成页面时的风格校验清单：页面以纯黑#000000为底（Token 化为--bg: #050505），--accent（#d4af37，接近品牌 Gold）仅用于主 CTA；显示级标题一律大写、行高 0.92–1.19、字距收紧；按钮与卡片圆角为 0（Token 化为--radius-sm: 2px起档）；深度不靠阴影，而靠表面明度分层（#000000 → #181818 → #202020 → #494949，对应 Token 化的--bg → --surface与--elev-*阴影族）；hover 交互只允许颜色/透明度变化，禁止 scale 与 translate 动画。

七、小结：证据链、事实源与工程化的三层关系

综合 source/evidence.md 与包内各文件，可以归纳出 OpenDesign 设计系统 2.0 包的三层数据关系：

1. 事实源（source of truth）：tokens.css的:root声明与DESIGN.md的视觉规范；
2. 审计层（audit evidence）：source/token-contract.report.json将 56 个 Token 逐一绑定到tokens.css:行号，source/tokens.source.json提供 Token 快照，source/evidence.md声明来源范围与"非上游爬取"的边界；
3. 工程投影（derived outputs）：design-tokens.json（程序化 JSON）与tailwind-v4.css（Tailwind v4@theme映射）由审计层与事实源重新生成，禁止手工编辑。

对使用这套体系的 Agent 而言，正确姿势是：以USAGE.md为入口、以tokens.css为唯一事实源、以components.manifest.json为组件复用清单、以source/为可追溯性审计凭证——既拿到了可运行的视觉系统，也保留了"每个值从哪一行声明而来"的完整证据链。

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