企业官网建设流程全解析

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

导读

本文以 OpenDesign 仓库中 PlayStation 设计系统包 的 source/evidence.md 为线索，讲解 Design System 2.0 回填（backfill）机制中"来源证据 + Token 契约"的落地方式。读完本文，你将掌握：PlayStation 设计系统包的完整文件结构与读取顺序、TOKEN_SCHEMA四层 Token 架构的含义、token-contract.report.json如何把每个 Token 精确映射回tokens.css声明行，以及为什么design-tokens.json与tailwind-v4.css属于"只可再生、不可手改"的派生产物。

一、evidence.md 的定位：一份来源范围声明

source/evidence.md是整个 PlayStation 设计系统包的"审计入口"。它只有两段核心声明：

• Source Scope（来源范围）：该 Design System 2.0 回填内容衍生自 OpenDesign 精选的内置 fixture（bundled fixture），并未对上游品牌仓库或官网进行全新抓取（"It does not claim a fresh crawl of the original upstream brand repository or website"）。
• Included Fixture Files（包含的 fixture 文件）：列出包内三个核心源文件。

这一声明同时被包的 manifest.json 以结构化字段固化：其source字段为{ "type": "bundled", "origin": "OpenDesign curated bundled fixture" }，并在sourceFiles字段中索引了evidence、tokens、report三个证据文件：

"sourceFiles": { "evidence": "source/evidence.md", "tokens": "source/tokens.source.json", "report": "source/token-contract.report.json" }

而 source/tokens.source.json 与 evidence.md 遥相呼应：其sourceScope同样是"open-design-bundled-fixture"，brandId为"playstation"，files列表与 evidence.md 的 "Included Fixture Files" 完全一致。这意味着证据声明不仅在 prose 中，也在 JSON 中机器可读。

二、包结构总览：manifest 定义的文件契约

依据 design-systems/_schema/manifest.schema.ts（其 schemaVersion 常量od-design-system-project/v1与 manifest.json 一致），一个设计系统包的发现层（discovery layer）由manifest.json描述。PlayStation 包的files契约如下：

其中 preview 目录包含 colors.html、typography.html、spacing.html 三页，供人工或拉取通道做视觉校验。

三、Token 契约：report 文件的结构与评分

evidence.md 指出：source/token-contract.report.json把每一个 TOKEN_SCHEMA 绑定映射回已提交的tokens.css声明行。查看 token-contract.report.json 的顶层摘要：

{ "schemaVersion": 1, "contract": "TOKEN_SCHEMA", "generatedAt": "2026-06-06T00:00:00.000Z", "sourceScope": "open-design-bundled-fixture", "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 全部在tokens.css中有声明（declaredTokens: 56）、全部有来源支撑（sourceBackedTokens: 56），因此综合评分 100、等级 excellent、无需重建。

report 的tokens数组为每个 Token 提供五元组证据记录，例如：

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

注意reason字段与 evidence.md 的口径完全一致——凡是来源都标注 "Bundled tokens.css declares ...; no upstream recrawl"，避免把内置 fixture 误当作上游一手证据。这正是证据边界工程化的体现。

四、TOKEN_SCHEMA 四层架构：A1 / A2 / B-slot 的含义

report 中layerCounts的四个分层并非 PlayStation 私有，而是来自契约定义 packages/contracts/src/design-systems/token-schema.ts 的TokenLayer联合类型：

export type TokenLayer = "A1-identity" | "A1-structure" | "A2" | "B-slot";

• A1-identity：必选层，Token 即品牌本身，无法用 fallback 替代（如--bg、--surface、--accent、--font-display）。PlayStation 包中该层有 8 个。
• A1-structure：必选结构层（18 个），承载字号、行高、版式与布局节奏（如--text-4xl、--section-y-desktop、--container-max）。
• A2：通用派生层（26 个），是 A1 的补充与默认值来源。
• B-slot：可选槽位（4 个），专为跨品牌一致性而设——当 ≥2 个品牌需要同一语义时才提升为 B-slot。PlayStation 包中--surface-warm、--fg-2、--meta、--border-soft均为 B-slot，且其中--fg-2、--meta直接用var(--fg)、var(--muted)做别名（report 的aliasTokens: 2即指这两个）。

用layerCounts核对：8 + 4 + 26 + 18 = 56，与totalTokens完全闭合。

五、tokens.css：品牌决策在 Token 层的编码

evidence.md 指向的 tokens.css 是整个契约的物理载体，其头部注释明确说明该文件"把品牌决策编码进 Token 层"。与 DESIGN.md 对照可验证几条核心规则：

• 三表面通道（three-surface channel）：--bg: #000000（Console Black，masthead/hero 画布）→--surface: #ffffff（Paper White，编辑性面板）→--surface-warm: #f5f7fa（Ice Mist，渐变终点）。
• "青色永不休止"规则：--accent: #0070cc（PlayStation Blue，不可动摇的锚点）与--accent-hover: #1eaedb（PlayStation Cyan）被刻意分开放置——cyan 只存在于 hover/focus 层，从不出现在静止背景。
• 180ms 交互窗口：--motion-fast: 180ms、--motion-base: 200ms、--ease-standard: cubic-bezier(0.2, 0, 0, 1)共同构成"power-on"（开机）式 hover 手感。
• 半径系统收缩到 schema 主干：DESIGN.md 描述的是十一档半径（2/3/6/12/13/19/20/24/36/48/999px），tokens.css 只承载 6/12/24/999 四档，3px 的输入框半径由组件层覆盖--radius-sm实现——注释明确写了 "Inputs override --radius-sm with their own 3px at component layer"。
• 阴影阶梯只留两档：--elev-flat: none与--elev-raised: rgba(0, 0, 0, 0.08) 0 5px 9px 0，呼应 DESIGN.md "whisper-or-shout"（要么耳语要么呐喊）的 0.06/0.08/0.16/0.8 四档阴影哲学，中间档被刻意剔除。

report 中每个sources引用的行号与 tokens.css 一一对应（如--bg在tokens.css:27、--focus-ring在tokens.css:131），读者可自行核验。

六、派生产物：design-tokens.json 与 tailwind-v4.css 的再生原则

evidence.md 第三段给出了最重要的工程约束：

design-tokens.json和tailwind-v4.css是派生输出，应当从 report 与 token 样式表重新生成，而不是手工编辑。

该原则在 packages/contracts/src/design-systems/derived-token-outputs.ts 中有对应实现支撑——其输出契约同样声明contract: 'TOKEN_SCHEMA'。也就是说，PlayStation 包内两个派生文件（design-tokens.json 与 tailwind-v4.css）的正确维护方式是：先改tokens.css（或源 Token 数据），再跑生成器刷新 report 与派生文件，保证三处永不漂移。这与 report 中recommendRebuild: false的语义一致——当前状态下契约与源已对齐，无需重建。

同样地，components.manifest.json 也是从components.html+tokens.css派生的可重建缓存（source.componentsHtml与source.tokensCss字段标明了其输入），不应手工维护。

七、证据边界：为什么"不回填一手抓取"是刻意的

evidence.md 反复出现的措辞——"derived from the curated OpenDesign bundled fixture"、"no upstream recrawl was performed"——构成整包的使用红线。USAGE.md 的 "Avoid" 一节把它翻译成三条纪律：

1. 避免在复制的:rootToken 块之外使用裸 hex 值；
2. 避免脱离tokens.css独立重定义 Tailwind 或 design-token 值；
3. 避免宣称拥有上游一手来源证据——本包基于精选内置 fixture。

这套边界防止了两类事故：一是 Agent 误把 fixture 当作官方文档引用，二是派生文件与源文件之间出现手工漂移。在 manifest.schema.ts 中，DesignSystemProjectSource联合类型明确区分了bundled/local/github/shadcn四种来源，bundled类型只允许type与origin两个键——从 schema 层面就限制了"内置包假装有上游 URL"的可能。

八、实践：如何按契约读取并使用 PlayStation 包

USAGE.md 给出推荐的读取顺序，与 evidence.md 的证据路径相互配合：

1. 先读 USAGE.md 理解包契约；
2. 再读 DESIGN.md 获取视觉意图、约束与反模式（其中第 9 节 "Agent Prompt Guide" 提供了可直接投喂给生成 Agent 的 CTA/英雄区/封面瓦片/商店按钮等 5 条示例提示词，以及 8 步迭代审计清单）；
3. 把 tokens.css 粘贴进首个 artifact 的<style>块，再写组件 CSS；
4. 用 components.manifest.json 做组件清单速查，需要精确选择器或状态时打开 components.html（该文件含 63 个选择器、28 个类、1 个<style>块，并在 hover 规则中落实了 cyan 填充 +transform: scale(1.2)的品牌交互签名）；
5. 需要视觉校验时打开 preview 三页；
6. 涉及来源审计时，回到 source/evidence.md 与 source/token-contract.report.json 核对每个 Token 的出处。

小结

PlayStation 设计系统包的source/evidence.md看似简短，实则是 Design System 2.0 回填机制的"诚信开关"：它用 prose（evidence.md）+ JSON（token-contract.report.json / tokens.source.json）+ schema（manifest.schema.ts / token-schema.ts）三层结构，把"哪些 Token 来自哪里、哪些文件可手改、哪些文件只能再生"固化成了机器可校验的契约。对使用该包的 Agent 而言，遵循 evidence.md 定义的边界，就是保证跨品牌切换可靠、派生产物不漂移、来源声明不失真的前提。

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