OpenDesign Loom 设计系统包使用指南：从包契约到 Agent 出图

本指南面向在 OpenDesign 中调用或二次开发 Loom Design System 2.0 包的开发者与评审者，系统讲解该包的阅读顺序、包契约、token 语义、组件清单与使用红线，并结合仓库内 design-systems/loom/ 的实际文件给出源码级佐证。读完你将掌握：如何按正确顺序消费一个设计系统包、如何在不破坏跨品牌切换的前提下复用其 token、以及如何让 Agent 生成符合 Loom 风格且可读性达标的界面。

一、Loom 包是什么：一份可被 Agent 直接消费的设计系统包

在 OpenDesign 仓库中，design-systems/ 目录下的每个子目录都是一个可移植的设计系统包。选中某个包后，其设计上下文会被组合进 Agent 的 prompt（详见 design-systems/README.md）。Loom 包（design-systems/loom/manifest.json）属于 Themed & Unique 类别，主题是「异步视频协作工具」：以紫色主色、友好明亮的面板、视频优先的布局为核心特征——干净、亲切、专业，但绝不「企业化」。

每个包的最小编译形态包含三个必需文件：

design-systems/<slug>/
├── manifest.json     # 稳定发现元数据、来源与声明路径
├── DESIGN.md         # 面向 Agent 的权威设计叙述
└── tokens.css        # 编译后的语义 token 样式表

Loom 包在此基础上还附带了完整的高级文件集，它们都是活跃的运行时输入，而非占位符：

文件	角色
USAGE.md	Agent 面对的使用顺序与包契约指南（本文主体）
components.html	独立组件夹具（fixture），含精确选择器与状态
components.manifest.json	由 components.html 与 tokens.css 派生的组件/token 索引
design-tokens.json	派生的 Design Tokens JSON
tailwind-v4.css	由 tokens.css 派生的 Tailwind v4 映射
preview/	可索引的预览页（colors / spacing / typography）
source/	导入器证据、token 契约报告

二、阅读顺序：消费一个设计系统包的标准姿势

USAGE.md 规定了严格的阅读顺序，这是 Agent 与评审者都应当遵守的契约：

1. 先读 USAGE.md 本身，理解包契约；
2. 再读 DESIGN.md，掌握视觉意图、约束与反模式；
3. 将 tokens.css 粘贴进第一个产物的 <style> 块，再编写组件 CSS——token 是一切组件的底层；
4. 用 components.manifest.json 做紧凑的组件清单速查；当需要精确选择器或具体状态（hover、focus-visible、active、placeholder）时，打开 components.html；
5. 需要视觉抽查时，查看 preview/ 下的页面：colors.html、spacing.html、typography.html。

这条顺序的用意在于：先建立「为什么这么设计」的心智模型（DESIGN.md），再注入「可复制的 token 基座」（tokens.css），最后才看「具体怎么写」的组件实现（manifest + HTML fixture）。跳过任何一步都容易写出「形似而神不似」的产物。

三、设计亮点：这一风格族的核心识别特征

USAGE.md 明确列出四条设计亮点，也是判断产物是否「像 Loom」的标尺：

• 视觉风格：干净、友好、内容优先（clean, friendly, content-first）；
• 色彩立场：明亮表面 + 紫色强调（bright surfaces with purple accent）；
• 设计意图：让产物在这一风格族内可被一眼认出，同时保住可用性与可读性；
• 红线：不得把 Tertiary 色 #9B9CA3 用作正文文本——它只用于时间戳和元数据。

在 DESIGN.md 中，这一识别特征被进一步固化为完整的色彩与排版体系：

3.1 表面色板（Surface Palette）

Token	Hex	用途
Background	#FFFFFF	主画布
Surface	#F7F7F8	卡片、侧边栏、浮起面板
Border	#E4E4E7	分隔线、输入框边框

3.2 数据色板（Data Palette）

Token	Hex	用途
Primary	#625DF5	CTA、激活态、视频进度
Primary Hover	#5048E5	按钮 hover 态
Text	#1F1F23	全部文本
Text Secondary	#6B6D76	时间戳、元数据、字幕
Text Tertiary	#9B9CA3	占位符、禁用态
Error	#D64770	错误状态
Recording	#EF440C	录制中指示灯

3.3 排版阶梯（Typography）

角色	字号	字重	行高
Display	28px	700	1.2
H1	22px	600	1.3
H2	18px	600	1.4
Body	14px	400	1.5
Body Small	13px	400	1.5
Caption	12px	400	1.4
Button	14px	500	1.2
Micro	11px	500	1.2

字体族统一为 "Inter", -apple-system, BlinkMacSystemFont, "Segoe UI", Helvetica, Arial, sans-serif，代码字体为 ui-monospace, SFMono-Regular, "SF Mono", Menlo, Consolas, monospace。

四、Token 契约深挖：从 tokens.css 到派生产物

USAGE.md 强调「原样保留 schema token 名称，跨品牌切换才可靠」。Loom 包的 token 真实来源是 tokens.css，它在 :root 中声明了 56 个语义 token，并附带了大量设计注释，例如：

• 前景三档文本：--fg: #1f1f23（Ink 主文本）、--muted: #6b6d76（Slate 次要文本，在白底上满足 4.5:1）、--meta: #9b9ca3（Mist 占位/禁用，禁止用于正文）；
• 圆角阶梯：--radius-sm: 4px（输入框）、--radius-md: 6px（按钮）、--radius-lg: 8px（卡片/缩略图）、--radius-pill: 9999px（头像、状态点、徽章）；
• 纯阴影层级：--elev-flat、--elev-ring、--elev-raised——卡片深度只靠阴影表达，禁止加边框（对应 DESIGN.md §6）；
• 动效节奏：--motion-fast: 100ms（按钮按压）、--motion-base: 200ms（卡片 hover）、--ease-standard: cubic-bezier(0.22, 1, 0.36, 1)；
• 容器与栅格：--container-max: 1200px，桌面/平板/手机的内边距分别为 24/20/16px，区块纵向节奏 72/48/32px；
• 焦点环：--focus-ring: 0 0 0 3px color-mix(in oklab, var(--accent), transparent 85%)，约等于 rgba(98, 93, 245, 0.15) 的紫色光晕。

这些 token 通过三层派生链路向下游流转：

1. design-tokens.json —— 由 token 契约报告派生，按 TOKEN_SCHEMA 分层（A1-identity 8 个、B-slot 4 个、A2 26 个、A1-structure 18 个），当前评分 100、评级 excellent、无需重建；
2. tailwind-v4.css —— 由 tokens.css 派生的 Tailwind v4 @theme 映射，把 --bg 映射为 --color-bg、--space-4 映射为 --spacing-4、--radius-lg 映射为 --radius-lg 等，可直接 @import "tailwindcss"; @import "./tokens.css"; 后使用；
3. source/token-contract.report.json —— 把每个 TOKEN_SCHEMA 绑定映射回 tokens.css 的声明行，作为审计证据。

需要特别注意：派生文件是缓存而非竞争性事实源。design-tokens.json 与 tailwind-v4.css 都应在 token 契约报告与 tokens.css 变更后重新生成，而不是手工编辑。

五、组件清单：在发明新控件之前先复用

USAGE.md 的「Do」要求：在发明新控件之前，先从 components.manifest.json 复用组件组。Loom 包的组件索引（components.manifest.json）统计了整个夹具：1 个 style 块、57 个选择器、31 个类、27 个元素，并按功能划分为 9 个组件组：

组 id	含义	关键选择器 / 类	依赖的核心 token
buttons	按钮与 CTA	.btn、.btn-primary、.btn-secondary	--accent-hover、--radius-md、--motion-fast、--space-4
inputs	表单与控件	.field、.field input、.field-help	--bg、--border、--radius-sm、--meta（placeholder）
cards	卡片与面板	.card、.card:hover	--elev-raised、--radius-lg、--motion-base
badges	徽章与状态标签	.badge、.badge-dot、.badge-muted、.badge-recording	--radius-pill、--muted、--danger、--text-xs
links	链接与行内操作	a、a:hover	--accent
keyboard	键盘提示	kbd	--font-mono、--border、--radius-sm
icons	图标槽位	.icon	无（16×16 SVG）
typography	排版刻度与文本工具	h1/h2/h3、.lead、.eyebrow、.body-muted、.body-sm	--font-display、--text-2xl、--tracking-display、--muted
layout	布局原语	.container、.row-between、.stack-3/4、.hero-grid、.features-grid	--container-max、--space-4、栅格断点

索引还给出了两个非常有用的质量信号：

• unusedDeclared（已声明未使用）：--border-soft、--elev-flat、--elev-ring、--fg-2、--surface-warm、--text-3xl、--warn 等 token 在夹具中暂未消费；
• undeclaredReferenced（已引用未声明）：为空——说明夹具中没有游离的「幽灵 token」，契约是自洽的。

当需要精确复刻某个状态（比如 .btn-primary:active 的 --accent-active、.field input:focus-visible 的焦点环、.thumbnail-meta 的录制角标）时，直接打开 components.html 查看完整实现。该文件包含完整的 hero、features、form 三段式页面夹具，以及视频缩略图、播放圆钮、录制徽章（REC）等 Loom 标志性元素。

六、Do 与 Avoid：四条使用红线

USAGE.md 的规则部分可以直接作为 Agent 与评审者的 checklist：

应当做（Do）

• 原样保留 schema token 名称，保证跨品牌切换（cross-brand switching）依然可靠；
• 用 --accent 承担主操作、链接、焦点态，以及唯一一个清晰的视觉焦点元素；
• 优先复用 components.manifest.json 中的组件组，而不是发明新控件；
• 将 source/ 目录文件视为「捆绑夹具回填」的审计证据（详见 source/evidence.md）。

不要做（Avoid）

• 不要在复制的 :root token 块之外写裸 hex 值；
• 不要脱离 tokens.css 单独重定义 Tailwind 或设计 token 值；
• 不要声称存在「上游原始来源证据」——本包基于 OpenDesign 精选的捆绑夹具（source/evidence.md 明确说明：不声称对上游品牌仓库或官网做过全新抓取）；
• 不要添加 components.html 或 DESIGN.md 中不存在的组件配方。

七、视觉细则与无障碍约束：让 Loom 风格站得住

DESIGN.md 是 Loom 包的第二份权威文档，它对「如何不破坏这套风格」给出了更细的约束，其中几条尤其容易被忽视：

• Tertiary 禁用：#9B9CA3 只用于时间戳/元数据，不可用作正文；
• 语义色不得直接作文本：必须与对比度足够的背景搭配使用；
• 按钮行高：禁止使用 line-height: 1.0——会裁切变音符号、emoji 与 CJK 字形，最低使用 1.2；
• Error 色的对比度陷阱：#D64770 在白底上 14px 小文本对比度仅 4.2:1，低于 AA 阈值 4.5:1，只可用于 18px+ 大文本或搭配更深背景；白色文字配 #D64770 背景同样是 4.2:1（不达标），应改用浅粉 #FDECEE 背景 + 深红文字；
• 触控目标：所有断点下最小 44×44px；
• 响应式：窄屏时视频缩略图堆叠在元数据与操作之上；≥768px 时切换为「视频居左、操作居右」的双栏布局。

manifest.json 中还声明了 craft 绑定：suggested: <a href="https://link.gitcode.com/i/3b403aeebb7f38d291db92585ccef1e0" target="_blank">"color", "accessibility-baseline"]，即该包建议配套仓库中的 [color 与 accessibility-baseline 规范一起使用，进一步印证了 Loom 风格对色彩纪律与无障碍的重视。

八、给 Agent 的 Prompt 要点：复刻 Loom 风格的完整清单

DESIGN.md §9 给出了面向 Agent 的生成提示词要点，与 USAGE.md 的阅读顺序配套使用效果最佳：

• 所有 UI 文本使用 Inter，代码片段使用 ui-monospace；
• 圆角：卡片 --radius-lg（8px）、按钮 --radius-md（6px）、输入框 --radius-sm（4px）；
• 动效：卡片 hover 200ms ease-out、按钮按压 100ms；
• 必须包含一个 1.5s 脉冲动画的录制指示点；
• 所有 CTA 与激活态使用主色 #625DF5；
• 使用 Secondary 文本 #6B6D76 前确认其在白底上满足 4.5:1；Tertiary #9B9CA3 仅限时间戳/元数据。

九、在 OpenDesign 中的实际消费路径

Loom 包在 OpenDesign 中的消费不限于手工读文件：根据 design-systems/README.md，产品会从设计系统面板或支持的项目创建流程中选择包，并将其设计上下文组合进 Agent prompt；/api/design-systems 每次请求都会重新扫描目录，因此包内文件变更后刷新面板即可生效，无需重启守护进程。manifest.json 的 importMode: "normalized" 说明该包以规范化模式导入，source.type: "bundled" 则标识其来自 OpenDesign 精选捆绑夹具。此外，仓库还提供本地文件夹、GitHub 与 shadcn 三种导入流程，以及 od design-systems import-* CLI；仓库自有的批量同步器是 scripts/sync-design-systems.ts。完整的包编写规范与评审清单见 docs/design-systems.md，schema 契约见 design-systems/_schema/AGENTS.md。

需要说明的是：本包是「灵感来源于 Loom 风格」的设计系统包，属于美学参考，并非 Loom 品牌的官方资产——这一点在 design-systems/README.md 的 Attribution 一节有明确表述。