OpenDesign Bento 设计系统使用指南：Agent 与评审者的设计系统 2.0 包契约

OpenDesign 仓库以「设计系统包（Design System Package）」的形式为编码 Agent 提供可复用的视觉风格资产。design-systems/bento/ 下的 Bento 包即是其中之一，它的核心价值在于：让 Agent 在生成页面时，能够遵循一套与现代 Bento 风格一致的设计令牌（Design Tokens）与组件规范，同时保证输出可被人类评审者核验。本文以该包的使用文档（design-systems/bento/USAGE.md）为主体，结合包内的令牌、组件清单与源码级证据，完整讲解 Bento 包的契约结构、令牌体系、组件清单、正确使用姿势与必须避开的反模式，帮助读者在 OpenDesign 工作流中直接、合规地消费这个设计系统包。

一、Bento 包是什么：一个「包契约」而非单纯的样式文件

Bento 包在 design-systems/bento/manifest.json 中被定义为 od-design-system-project/v1 规范下的标准设计系统项目，类别为 Layout & Structure（布局与结构），其定位是：

Bundled OpenDesign package for Bento, derived from curated DESIGN.md, tokens.css, and components.html fixtures.

也就是说，Bento 包并非对某个外部品牌仓库的实时爬取结果，而是基于 OpenDesign 官方整理的 bundled fixture（随包打包的基准文件） 生成的。这一点在包的元数据（source.type: "bundled"、source.origin: "OpenDesign curated bundled fixture"）以及 design-systems/bento/source/evidence.md 中都有明确声明：

This Design System 2.0 backfill is derived from the curated OpenDesign bundled fixture. It does not claim a fresh crawl of the original upstream brand repository or website.

理解这一点非常重要：使用 Bento 包时，不应声称其样式来自某个外部原始品牌站点，它代表的是 OpenDesign 内部整理并长期维护的风格基准。

从 manifest 可以看出包内各文件的分工（files 字段）：

字段	文件	职责
design	DESIGN.md	视觉意图、约束与反模式
tokens	tokens.css	设计令牌的权威样式源
designTokens	design-tokens.json	令牌的结构化 JSON 派生产物
tailwind	tailwind-v4.css	Tailwind v4 主题绑定派生产物
components	components.html	组件参考 fixture（精确选择器与状态）
componentsManifest	components.manifest.json	紧凑的组件清单
usage	USAGE.md	包使用指南（本文主体）
preview.dir	preview/	颜色/排版/间距的视觉预览页

二、推荐阅读顺序：消费 Bento 包的五个步骤

design-systems/bento/USAGE.md 给出了明确的阅读顺序，这是 Agent 与评审者消费本包的标准流程：

1. 先读 USAGE.md（本文），理解包契约的整体约定；
2. 再读 design-systems/bento/DESIGN.md，掌握视觉意图、约束与反模式；
3. 将 design-systems/bento/tokens.css 的内容粘贴到首个 artifact 的 <style> 块中，之后再编写组件 CSS——令牌先行，避免组件样式各自为政；
4. 使用 design-systems/bento/components.manifest.json 获取紧凑的组件清单；当需要精确的选择器或状态细节时，打开 design-systems/bento/components.html；
5. 需要视觉核验时，检查 preview/ 目录下的预览页面（preview/colors.html、preview/typography.html、preview/spacing.html）。

这套顺序的本质是「先契约、后意图、再令牌、次清单、终预览」的层层递进，保证 Agent 在动笔写任何 CSS 之前，风格地基已经就位。

三、设计要点：Bento 的视觉基调

Bento 包的设计定位总结在 design-systems/bento/DESIGN.md 中，并在 USAGE.md 的 Design Highlights 中浓缩为三条：

• Visual style（视觉风格）：modern, clean（现代、清爽）；
• Color stance（色彩立场）：primary, neutral, success, warning, danger（主色、中性、成功、警告、危险五类语义色）；
• Design intent（设计意图）：保持输出对该风格家族可辨识的同时，兼顾可用性与可读性。

DESIGN.md 对视觉主题的描述更为形象：模块化网格布局 + 卡片式块（card-like blocks）+ 清晰层级 + 柔和间距 + 微妙的视觉对比，目标是构建「organized, scannable interfaces（组织有序、可快速扫读的界面）」。在 design-systems/bento/components.html 的 meta description 中，这一风格被进一步描述为「modular bento interface with friendly tiles, soft borders, and balanced product density（友好瓦片、柔和边框、均衡的产品密度）」。

3.1 色彩语义（DESIGN.md 声明值）

DESIGN.md 给出的是风格层面（style foundations）的语义色，供理解意图使用：

语义	色值	用法建议
Primary	#FAD4C0	CTA 强调（Attention 焦点）
Secondary	#80A1C1	次级强调
Success / Warning / Danger	#16A34A / #D97706 / #DC2626	状态语义色
Surface	#FFF5E6	大面积背景与卡片
Text	#111827	正文文字，保证可读性
Neutral	#FFF5E6	由 surface token 派生，用于官方格式兼容

DESIGN.md 同时给出了三条色彩使用建议：Primary 用于 CTA 强调；Surface 用于大面积背景与卡片；正文一律使用 Text 色以保证可读性。

3.2 实际令牌：以 tokens.css 为准

需要特别区分的是：DESIGN.md 中的色值是风格层面的描述，而 design-systems/bento/tokens.css 中的 :root 令牌块才是实际编码时直接引用的权威值（importMode: "normalized"，manifest 中已声明）。tokens.css 实际落地为浅色系 Bento 风格（如 --bg: #f5f8ff、--accent: #2563eb），两者并不冲突——DESIGN.md 描述家族风格意图，tokens.css 提供该包实际分发的令牌绑定。USAGE.md 的规则明确要求：禁止在复制的 :root 令牌块之外使用裸十六进制色值，所有颜色都必须走令牌。

四、令牌体系深度解析：56 个结构化令牌

design-systems/bento/tokens.css 是 Bento 包的令牌权威源，共声明 56 个 CSS 自定义属性，分为四大类：

4.1 颜色令牌（Color）

• 身份层（identity）：--bg: #f5f8ff、--surface: #ffffff、--fg: #101828、--muted: #667085、--border: #d7e0ef、--accent: #2563eb；
• 槽位层（slot）：--surface-warm: #eaf1ff、--fg-2: #344054、--meta: #2563eb、--border-soft: #edf2f8；
• 派生层（A2）：--accent-on: #ffffff、--success: #16a34a、--warn: #f59e0b、--danger: #ef4444。

值得注意的现代 CSS 技巧：--accent-hover 与 --accent-active 使用 color-mix(in oklab, var(--accent), black 8%/14%) 在 OKLab 色彩空间中由主色动态派生，避免了手写两套 hover/active 色值，也让派生色与主色在感知上保持一致。

4.2 字体与排版令牌（Typography）

• 字体族：--font-display: Inter, system-ui, sans-serif、--font-body: Inter, ...、--font-mono: "SF Mono", ui-monospace, Menlo, monospace；
• 字号阶梯：--text-xs: 12px → --text-sm: 14px → --text-base: 16px → --text-lg: 18px → --text-xl: 24px → --text-2xl: 36px → --text-3xl: 54px → --text-4xl: 76px；
• 行高与字距：--leading-body: 1.52、--leading-tight: 1.06、--tracking-display: -0.025em。

4.3 间距与栅格令牌（Spacing & Grid）

• 间距阶梯：--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: 96px / --section-y-tablet: 68px / --section-y-phone: 48px；
• 容器：--container-max: 1180px，gutter 分三档 36px / 24px / 16px（desktop/tablet/phone）。

4.4 圆角、投影与动效令牌（Radius / Elevation / Motion）

• 圆角：--radius-sm: 10px、--radius-md: 16px、--radius-lg: 24px、--radius-pill: 9999px；
• 投影：--elev-flat: none、--elev-ring: 0 0 0 1px var(--border)（细描边）、--elev-raised: 0 20px 52px rgba(16, 24, 40, 0.11)（悬浮卡片）、--focus-ring: 0 0 0 4px rgba(37, 99, 235, 0.22)（焦点环）；
• 动效：--motion-fast: 150ms、--motion-base: 240ms、--ease-standard: cubic-bezier(0.2, 0, 0, 1)。

4.5 令牌分层与契约审计（token-contract.report.json）

design-systems/bento/source/token-contract.report.json 记录了每个令牌的分层归属（layer）与契约背书（confidence: high）。56 个令牌全部分布在四个层：

• A1-identity（8 个）：品牌身份层，如 --bg、--surface、--fg、--muted、--accent、字体族等；
• A1-structure（18 个）：结构层，如字号阶梯、行高、section 节奏、容器宽度等；
• B-slot（4 个）：槽位层，如 --surface-warm、--fg-2、--meta、--border-soft；
• A2（26 个）：派生层，如 hover/active 派生色、状态色、间距、圆角、投影、动效等。

该报告给每个令牌都标注了 sources（精确到 tokens.css 的行号，如 tokens.css:7），并给出汇总评分 score: 100 / grade: "excellent"、recommendRebuild: false。这说明包的令牌契约完整、无需重建。依据 design-systems/bento/source/evidence.md，design-tokens.json 与 tailwind-v4.css 均为派生产物，应基于报告与 tokens.css 重新生成，而不是手工编辑——这是保证跨品牌切换可靠性的关键纪律。

4.6 派生产物一：design-tokens.json

design-systems/bento/design-tokens.json 是令牌的结构化 JSON 视图（format: "od-design-tokens/v1"），把 CSS 变量映射为带类型的令牌对象（如 --bg 的 type: "color"、--text-sm 的 type: "dimension"、--elev-raised 的 type: "shadow"、--motion-fast 的 type: "duration"、--ease-standard 的 type: "cubicBezier"），并记录每个令牌的 layer、confidence 与 sources 行号。这份 JSON 适合被工具链读取，是「机器可读的令牌契约」。

4.7 派生产物二：tailwind-v4.css

design-systems/bento/tailwind-v4.css 展示了如何把 tokens.css 桥接到 Tailwind CSS v4 的 @theme 指令：

/* Derived from tokens.css. Keep tokens.css as the source of truth. */
@import "tailwindcss";
@import "./tokens.css";

@theme {
  --color-bg: var(--bg);
  --color-accent: var(--accent);
  --color-success: var(--success);
  --font-display: var(--font-display);
  --text-2xl: var(--text-2xl);
  --spacing-4: var(--space-4);
  --radius-md: var(--radius-md);
  --shadow-raised: var(--elev-raised);
  --duration-fast: var(--motion-fast);
  --ease-standard: var(--ease-standard);
  /* ... */
}

文件头注释明确写着 "Keep tokens.css as the source of truth"——tokens.css 是唯一权威源，Tailwind 主题只是它的映射层。这与 USAGE.md 中「不要脱离 tokens.css 单独重定义 Tailwind 或设计令牌值」的规则完全一致：使用 @theme 做桥接、而非重造。

五、组件清单：components.manifest.json 与 components.html

5.1 清单统计（manifest 提取的事实）

design-systems/bento/components.manifest.json 是对 design-systems/bento/components.html 的自动提取结果，记录了 fixture 的规模与令牌引用关系：

• fixture 规模：1 个 <style> 块、48 个选择器、26 个类名、19 个元素类型；
• 令牌健康度：declared（已声明）与 referenced（被引用）各 56/55 项，undeclaredReferenced: []（不存在未声明却被引用的令牌——引用面完全闭合）；unusedDeclared 列出了声明但未被组件引用的令牌（如 --accent-active、--danger、--elev-flat、--motion-base、--space-1、--space-12、--warn），这些令牌为组件外使用预留；
• 选择器覆盖：.btn、.btn-primary、.btn-secondary、.field、input:focus、.panel、.tile、.metric、.status、.eyebrow、.lead、.hero、.container、.stack、.card-row、.mini-card 等；
• 组件组（groups）：清单将组件归为 9 个组，其中 7 组存在、2 组（keyboard、icons）不存在。

5.2 八个组件组的令牌依赖

清单为每个组件组记录了完整的 tokenReferences，这相当于「组件 ↔ 令牌」的依赖图谱：

组件组	状态	关键选择器/类	引用的核心令牌
buttons	存在	.btn、.btn-primary、.btn-secondary、:hover、:focus-visible	--accent、--accent-on、--border、--elev-ring、--radius-md、--space-5、--motion-fast、--ease-standard
inputs	存在	.field、input、input:focus、label	--border、--radius-sm、--space-2/4/5、--surface
cards	存在	.card-row、.panel、.panel-head、.tile	--border、--elev-raised、--radius-lg、--surface
badges	存在	.status（无选择器条目）	—（组件独立，令牌引用为空）
links	存在	元素 a	—
keyboard	不存在	—	—
icons	不存在	—	—
typography	存在	.eyebrow、.lead、h1、h2、h3	--fg-2、--text-4xl、--text-xl、--text-lg
layout	存在	.container、section、main、.metric-grid	--container-gutter-phone/tablet、--section-y-desktop

此外清单还统计了 literals：组件样式中有 3 处颜色表达式、24 处像素值、4 处硬编码字体族——这些是评审时值得留意的「未走令牌」痕迹。

5.3 参考 fixture 的实战要点（components.html）

design-systems/bento/components.html 是完整的可运行参考页，其关键实现要点可以直接复用到自己的 artifact 中：

• 按钮：主按钮用 background: var(--accent) + color: var(--accent-on)，hover 用 var(--accent-hover) 并 translateY(-1px)；次按钮用 var(--surface) + var(--elev-ring) 描边；两者共享 min-height: 44px 的触达尺寸与 transition（150ms + --ease-standard），并通过 .btn:focus-visible { box-shadow: var(--focus-ring) } 提供键盘焦点反馈；
• 输入框：.field 使用 grid 布局管理 label 与 input 的间距；input:focus 时 border-color: var(--accent) + var(--focus-ring)；
• 卡片与面板：.panel 使用 color-mix(in oklab, var(--surface), transparent 4%) 的半透明表面 + --elev-raised 悬浮投影 + --radius-lg；内部 .metric-grid 三列均分、.card-row 两列均分；
• 状态徽章：.status 用等宽字体 + 大写 + 字距，配合 .status::before 的 8px 圆点（--radius-pill + --success）表示在线状态；
• 响应式断点：max-width: 1023px 时容器 gutter 降为 tablet 档、section 纵向节奏降为 tablet 档；max-width: 860px 时 hero/lower/metric-grid/card-row 全部坍缩为单列；max-width: 639px 时进入 phone 档。

六、预览页与系统页：视觉核验途径

包的 preview/ 目录提供三个自包含的视觉预览页，供快速核验令牌效果：colors（preview/colors.html）、typography（preview/typography.html）、spacing（preview/spacing.html）。manifest 的 preview.pages 字段为每页标注了 role（colors/typography/spacing）与 title，机器可读。

此外，system/ 目录包含系统级展示页（system/index.html、system/kit.html、system/kit.dark.html）以及 system/tokens.default.json，用于查看整套系统的组件套件形态。其中 kit.dark.html 的存在表明该包也维护了深色套件的展示形态。

七、使用纪律：Do 与 Avoid（包契约的红线）

design-systems/bento/USAGE.md 用最精炼的方式划定了 Agent 与评审者的行为边界，这是本包契约的执行层面核心：

7.1 应当做（Do）

• 完整保留 schema 令牌名称：跨品牌切换的可靠性建立在令牌名一致之上——品牌 A 与品牌 B 的包都叫 --accent、--surface，切换时只需换令牌块，组件代码零改动；
• 用 --accent 表达主操作：主操作、链接、焦点状态，以及页面中唯一清晰的焦点元素，都应落在 --accent 上；
• 先复用组件组，再发明新控件：遇到新需求时，优先在 design-systems/bento/components.manifest.json 的组件组中寻找可复用的组，而不是凭空造新控件；
• 把 source/ 目录当作审计证据：source/evidence.md、source/token-contract.report.json、source/tokens.source.json 是随包回填（fixture backfill）的审计依据，评审时以此核验令牌来源。

7.2 应当避免（Avoid）

• 避免在复制的 :root 令牌块之外使用裸十六进制值：一切颜色走令牌，防止风格漂移；
• 避免脱离 tokens.css 独立重定义 Tailwind 或设计令牌值：Tailwind 主题只能做映射（参考 design-systems/bento/tailwind-v4.css 的 @theme 桥接模式），不能另起炉灶；
• 避免声称存在原始上游来源证据：本包基于随包整理的 bundled fixture，不是对上游品牌仓库/官网的新爬取（design-systems/bento/source/evidence.md 有明确声明）；
• 避免添加 components.html 或 DESIGN.md 中不存在的组件配方：新增组件必须先有对应的参考 fixture 或设计文档支撑，否则会破坏包的可审计性。

八、反模式清单：DESIGN.md 的十条红线

design-systems/bento/DESIGN.md 在章节 2～8 分别给出色彩、排版、间距栅格、布局构成、组件、动效交互、语气品牌的具体约束，并在末尾列出四条反模式（Anti-patterns）：

1. 不要在有现成令牌可解决问题时引入调色板之外的色彩；
2. 不要用相同字号/字重铺满所有文本而压平层级；
3. 不要添加降低可读性或可访问性的装饰性效果；
4. 不要在同一个界面混用互不相关的视觉隐喻。

这四条与 USAGE.md 的 Avoid 相互呼应：前者管「视觉意图层」，后者管「工程执行层」，两层共同保证 Bento 风格的输出既统一又可维护。

九、在 OpenDesign 工作流中如何落地

综合上述内容，Agent 在 OpenDesign 中消费 Bento 包的推荐落地流程为：

1. 初始化令牌：将 design-systems/bento/tokens.css 的 :root 块完整粘贴进 artifact 首个 <style> 块；
2. 复用组件：对照 design-systems/bento/components.manifest.json 的组件组（buttons/inputs/cards/badges/links/typography/layout）挑选已有配方；需要精确选择器或状态时参考 design-systems/bento/components.html；
3. 遵守层级纪律：主操作走 --accent，正文走 --fg，次要信息走 --muted/--fg-2，背景走 --surface/--bg，反馈走 --success/--warn/--danger；
4. 保证交互可达：焦点环用 --focus-ring，动效用 --motion-fast（150ms）+ --ease-standard，hover/active 派生色用 --accent-hover/--accent-active；
5. 视觉核验：需要时打开 preview/ 三页或 system/kit.html 做人工对比；
6. 接受评审约束：不得引入裸色值、不得绕过 tokens.css 重定义主题、不得添加无 fixture 支撑的新组件、不得声称上游原始来源。

遵循上述流程，Agent 产出的页面即可稳定保持 Bento 风格家族的可辨识度，同时满足 OpenDesign 评审者对令牌契约、组件复用与来源可审计的全部要求。