OpenDesign Design System 2.0 实战：Lingo 包使用契约与 Agent 提示词集成指南

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

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

点击查看免费下载

导读

Lingo 是 OpenDesign 仓库design-systems/目录下按 Design System 2.0 规范打包的创意类设计系统（Creative & Artistic），其 USAGE.md 是该包面向 OpenDesign Agent 与人工评审者的"包使用契约"入口文档。本文以 USAGE.md 为骨架，结合该包的 manifest.json、DESIGN.md、tokens.css、components.html 及 daemon 侧消费代码，完整讲解：如何按正确顺序阅读包内文件、如何把语义 token 注入生成产物的<style>块、如何借助组件清单复用既有控件，以及 daemon 在组合 Agent 提示词时如何读取 USAGE.md。读完本文，你将掌握 OpenDesign 生态中"设计系统包 → Agent 提示词 → 生成产物"这条链路的完整用法，并能独立评审或使用任意同构包。

包结构与阅读顺序：USAGE.md 定义的五步工作流

Design System 2.0 的每个包都围绕固定的机器可读骨架展开（见 design-systems/README.md）：manifest.json持有发现元数据与来源声明，DESIGN.md是面向 Agent 的规范文案，tokens.css是编译后的规范语义 token 样式表。Lingo 包在此基础上进一步携带了components.html、components.manifest.json、design-tokens.json、tailwind-v4.css、preview/与source/等富文件。

USAGE.md 用五条**阅读顺序（Read Order）**规定了消费该包的必经流程，这也正是 Agent 组合设计上下文时应当遵循的执行序列：

1. 先读 USAGE.md 本身，理解整个包的使用契约与约束边界；
2. 再读 DESIGN.md，获取视觉意图（visual intent）、约束（constraints）与反模式（anti-patterns）；
3. 把 tokens.css 粘贴到第一个产物的<style>块中，然后再写组件 CSS——token 是一切样式的地基；
4. 用 components.manifest.json 做紧凑的组件清单查询；当需要精确选择器或状态细节时，打开 components.html 查看完整 fixture；
5. 需要视觉核验时，检查preview/目录下的预览页（colors.html、typography.html、spacing.html）。

这条顺序的本质是"契约 → 意图 → 令牌 → 组件 → 视觉核验"的渐进下钻：先用最短的元数据建立心智模型，再逐层获取实现所需的精确信息，避免 Agent 在生成时"凭感觉"发散。

Lingo 的设计基调：bold、playful 与四色立场

USAGE.md 的Design Highlights用四行速写勾勒了 Lingo 的视觉身份：

• 视觉风格：大胆、俏皮（bold, playful）；
• 色彩立场：primary、neutral、success、warning、danger 五类语义色位；
• 设计意图：在保持该风格家族可辨识度的同时，守住可用性与可读性底线；
• Primary 主色：#58CC02——来自样式基座的 token。

DESIGN.md 对色彩立场做了更细的展开：Primary#58CC02、Secondary#CE82FF、Success#58CC02、Warning#FFC800、Danger#FF4B4B、Surface#FFFFFF、Text#3C3C3C、Neutral#FFFFFF（由 surface token 派生，以保证官方格式兼容）。用法上强调：CTA 强调用 Primary、大面积背景与卡片用 Surface、正文保持 Text 色以保障可读性。

这里有一个值得评审者注意的事实细节：DESIGN.md / USAGE.md 文案中的品牌绿#58CC02与该包实际编译产物存在色板差异。包内 tokens.css 声明的--accent实为柔和的紫罗兰#6d4aff，页面背景--bg为暖白紫#fbf9ff，components.manifest.json 的 fixture 描述也写作 "global localization product language, soft violet action, warm white surfaces"。按照 design-systems/README.md 的规定，tokens.css是"规范编译语义 token 样式表"，因此生成产物时以 tokens.css 的:root声明为准，USAGE.md 中#58CC02更多表达的是"来自样式基座的设计意图"。这正是 USAGE.md "Preserve the schema token names exactly"（保持 schema token 名称完全一致）这一约束要解决的问题：token 名称是跨品牌切换的稳定契约，色值则允许随包内实现演进。

实操第一步：把 tokens.css 注入产物的<style>块

USAGE.md 要求"在写任何组件 CSS 之前，先把 tokens.css 粘贴进第一个产物的<style>块"。这是因为 Lingo 的全部视觉语言都收敛在:root的 CSS 自定义属性中。完整契约如下（共 56 个 token）：

:root { /* 色彩：身份层（A1） */ --bg: #fbf9ff; /* 页面背景，暖白紫 */ --surface: #ffffff; /* 卡片/面板表面 */ --fg: #1d1b2a; /* 主前景文本 */ --muted: #786f8f; /* 次级弱化文本 */ --border: #ded7f0; /* 标准描边 */ --accent: #6d4aff; /* 品牌强调色（紫罗兰） */ --accent-on: #ffffff; /* accent 之上的前景 */ /* 色彩：槽位层（B-slot）与衍生层（A2） */ --surface-warm: #f1ecff; /* 暖色表面，迷你卡片用 */ --fg-2: #4f4863; /* 次级前景，lead 文本 */ --meta: #6d4aff; /* eyebrow/状态元信息色 */ --border-soft: #eee9f8; /* 弱描边，分隔线用 */ --accent-hover: color-mix(in oklab, var(--accent), black 8%); --accent-active: color-mix(in oklab, var(--accent), black 14%); --success: #22a06b; --warn: #e6a700; --danger: #e5484d; /* 字体 */ --font-display: Inter, system-ui, sans-serif; --font-body: Inter, system-ui, sans-serif; --font-mono: "Roboto Mono", ui-monospace, Menlo, monospace; /* 字号阶梯 */ --text-xs: 12px; --text-sm: 14px; --text-base: 16px; --text-lg: 18px; --text-xl: 24px; --text-2xl: 34px; --text-3xl: 50px; --text-4xl: 70px; --leading-body: 1.55; --leading-tight: 1.05; --tracking-display: -0.025em; /* 间距与版式节奏 */ --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; /* 圆角与阴影 */ --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 48px rgba(45, 36, 85, 0.12); --focus-ring: 0 0 0 4px rgba(109, 74, 255, 0.24); /* 动效与容器 */ --motion-fast: 150ms; --motion-base: 230ms; --ease-standard: cubic-bezier(0.22, 1, 0.36, 1); --container-max: 1160px; --container-gutter-desktop: 36px; --container-gutter-tablet: 24px; --container-gutter-phone: 16px; }

几个值得展开的实现要点：

• hover/active 用color-mix()派生而非硬编码新色值：--accent-hover与--accent-active分别基于--accent混入 8% / 14% 黑色。这保证了"只改--accent一处，整套交互状态自动跟随"，也呼应了 USAGE.md "Avoid raw hex values outside the copied:roottoken block"（避免在:root之外使用裸十六进制色值）的约束。
• 字号与间距都走离散阶梯：字号 12/14/16/18/24/34/50/70px，间距 4/8/12/16/20/24/32/48px，与 DESIGN.md 的 Scale 与 Spacing scale 一一对应，组件间必须复用这些步进值而非临时取值。
• focus-ring 是统一的可访问性信号：--focus-ring用 4px 的 accent 半透明光晕；components.html 中按钮与输入框的 focus 态都引用它，保证键盘导航可辨识。

组件清单：先查 components.manifest.json，再动手

USAGE.md 的第三条 Do 是"在发明新控件之前，先复用 components.manifest.json 中的组件分组"。该清单是从 components.html 自动抽取的结构化索引（schemaVersion 1），包含四个维度：fixture 规模统计（1 个 style 块、48 个选择器、26 个类、19 个元素）、token 使用审计（declared / referenced / unused / undeclared）、选择器与类名全集、以及按用途分组的组件列表。

清单定义的9 个组件分组如下：

分组 id	含义	是否存在于 fixture	涉及选择器/类	引用的核心 token
buttons	按钮与 CTA	是	.btn、.btn-primary、.btn-secondary、:hover、:focus-visible	--accent、--accent-on、--elev-ring、--radius-md、--motion-fast、--ease-standard
inputs	表单字段与控件	是	.field、input、input:focus、label	--border、--radius-sm、--focus-ring、--space-*
cards	卡片与面板	是	.card-row、.panel、.panel-head、.tile	--elev-raised、--radius-lg、--surface、--border
badges	徽章、chip 与状态标签	是	.status	无（使用内联元素伪元素）
links	链接与行内动作	是	a	无
keyboard	键盘提示	否	—	—
icons	图标槽位	否	—	—
typography	字号阶梯与文本工具	是	.eyebrow、.lead、h1–h3	--text-4xl、--text-xl、--text-lg、--fg-2
layout	布局原语	是	.container、section、.metric-grid	--container-gutter-*、--section-y-desktop

这份清单对 Agent 有直接的"先用后造"价值：buttons、inputs、cards、badges、links已具备可复用形状，生成页面时应当优先组合这些既有配方；而keyboard、icons标记为present: false，意味着该风格家族不预设键盘提示与图标槽位，遇到这类需求时应克制新增配方（USAGE.md 明确禁止添加 components.html / DESIGN.md 未表达的组件配方）。

清单里的 token 审计字段同样值得利用：unusedDeclared列出已声明但未被组件引用的 token（--accent-active、--danger、--elev-flat、--motion-base、--space-1、--space-12、--warn），undeclaredReferenced为空——这说明组件 fixture 对 token 的引用是自洽的。评审者在检查新代码时，可据此判断是否引入了"声明了却没用"的冗余 token。

组件实现参照：components.html 的关键配方

当需要精确选择器或状态细节时，以 components.html 为参照。它同时是可独立打开的完整页面（自带内联:roottoken 块与全部样式）和配方库。其核心样式骨架可归纳为：

/* 按钮：44px 最小触控高度，圆角走 radius-md，动效 150ms */ .btn { display: inline-flex; align-items: center; justify-content: center; min-height: 44px; padding: 0 var(--space-5); border: 1px solid transparent; border-radius: var(--radius-md); font: 700 var(--text-sm) / 1 var(--font-body); } .btn:focus-visible { outline: none; box-shadow: var(--focus-ring); } .btn-primary { background: var(--accent); color: var(--accent-on); } .btn-primary:hover { background: var(--accent-hover); transform: translateY(-1px); } .btn-secondary { background: var(--surface); color: var(--fg); border-color: var(--border); box-shadow: var(--elev-ring); } /* 面板：半透明表面 + raised 阴影 + 大圆角 */ .panel { background: color-mix(in oklab, var(--surface), transparent 4%); border: 1px solid var(--border); border-radius: var(--radius-lg); box-shadow: var(--elev-raised); overflow: hidden; } /* 状态徽章：伪元素小圆点，success 语义色 */ .status { display: inline-flex; align-items: center; gap: var(--space-2); color: var(--meta); font: 700 var(--text-xs) / 1 var(--font-mono); text-transform: uppercase; letter-spacing: 0.08em; } .status::before { width: 8px; height: 8px; border-radius: var(--radius-pill); background: var(--success); content: ""; } /* 输入框：focus 时 accent 描边 + focus-ring */ input { width: 100%; min-height: 46px; padding: 0 var(--space-4); border: 1px solid var(--border); border-radius: var(--radius-sm); background: var(--surface); color: var(--fg); font: inherit; } input:focus { outline: none; box-shadow: var(--focus-ring); border-color: var(--accent); }

fixture 同时演示了响应式断点策略：容器 gutter 与 section 纵向留白分别用--container-gutter-*与--section-y-*三档 token（desktop 1024px+ / tablet 640–1023px / phone <640px），hero、lower栅格在 860px 以下坍缩为单列。这种"token 驱动断点"的做法，让响应式无需硬编码具体像素。

Tailwind v4 与 Design Tokens 的派生层

USAGE.md 要求"不要脱离 tokens.css 独立重定义 Tailwind 或 design-token 值"。包内两个派生文件正是这条约束的落地产物：

• tailwind-v4.css：@import "./tokens.css"之后，通过 Tailwind v4 的@theme块把全部语义 token 映射为工具类主题（如--color-accent: var(--accent)、--spacing-4: var(--space-4)、--shadow-raised: var(--elev-raised)、--duration-fast: var(--motion-fast)）。文件头部注释明确写着 "Derived from tokens.css. Keep tokens.css as the source of truth."（派生自 tokens.css，以 tokens.css 为唯一事实源）；
• design-tokens.json：符合od-design-tokens/v1格式的机器可读 token 清单，56 个 token 全部标记confidence: high，分层计数为 A1-identity 8、A1-structure 18、B-slot 4、A2 26，整体评分 100、评级 excellent、recommendRebuild: false。

在 source/evidence.md 中可以看到这套派生机制的设计意图：该包是基于 OpenDesign 策展的 bundled fixture（curated bundled fixture）回填的，不声明抓取过上游品牌仓库或网站；design-tokens.json与tailwind-v4.css是派生输出，应当从 token 契约报告与 tokens.css 重新生成，而非手工编辑。这也是 USAGE.md "Avoid claiming original upstream source evidence"（不要声称拥有上游原始来源证据）一条的出处。

审计证据链：token-contract.report.json

source/token-contract.report.json 是 TOKEN_SCHEMA 契约的回溯报告：为 56 个 token 中的每一个都记录了layer（分层）、value、confidence与sources（精确到 tokens.css 的行号，如tokens.css:16对应--accent）。这把"语义 token 名称"与"物理声明位置"之间建立了可审计的映射，正是 USAGE.md "Treatsource/files as audit evidence for the bundled fixture backfill"（把 source/ 文件当作回填审计证据）所指的证据链。评审者核对 token 时，可以通过该报告快速定位声明行并验证数值一致性。

运行机制：daemon 如何把 USAGE.md 组合进 Agent 提示词

USAGE.md 不只是给人看的说明，它在 OpenDesign daemon 的提示词组合链路中是被真实消费的运行时输入。从源码可以确认以下事实：

• apps/daemon/src/design-systems/index.ts 在读取包内容时以manifest?.usage ?? 'USAGE.md'解析使用文档路径——即 manifest.json 的usage字段指向 USAGE.md，未声明时回退到同名默认文件；
• apps/daemon/src/prompts/system.ts 定义了designSystemUsageMd提示词通道，注释明确说明它是"可选的 USAGE.md 路由器，告诉 Agent 如何消费该包"，与designSystemTokensCss（逐字注入 tokens.css 的:root契约）、designSystemComponentsManifest（从 components.html 派生的紧凑结构化摘要）、designSystemFixtureHtml（verbatim components.html 回退）等通道一起，在 DESIGN.md 块之后追加进提示词——先用散文确立高层基调，再用结构化形态消歧 token 名称与组件形状；
• apps/daemon/src/design-systems/import.ts 展示了 USAGE.md 的生成模板（renderUsageMd），说明导入新品牌时 daemon 会自动产出同构的 USAGE.md（包含 "Pastetokens.cssinto the first<style>block" 等指令），保证 151 个包（见 design-systems/README.md）的使用契约结构一致。

由此可以推断完整链路：用户在设计系统界面选中 Lingo 包 → daemon 扫描包目录并读取 manifest 声明的文件 → 提示词组合器把 USAGE.md 路由指令 + tokens.css 契约 + 组件清单注入 Agent 上下文 → Agent 按阅读顺序执行。理解这条链路，评审者就能明白为什么 USAGE.md 的措辞（"paste into the first artifact<style>block"）如此命令式——它最终会被原样送进 Agent 的提示词。

Agent 与评审者守则：Do 与 Avoid 详解

USAGE.md 的 Do / Avoid 两节是该包的行为红线，逐条展开如下。

Do（应当遵守）：

1. 精确保留 schema token 名称——跨品牌切换（cross-brand switching）的可靠性建立在名称契约之上，改名会破坏design-tokens.json的回溯映射与 Tailwind 派生层；
2. 用--accent承载主操作、链接、焦点态与唯一视觉焦点——强调元素应当"一个页面一个主焦点"，避免同时点亮多个 accent 元素稀释注意力；
3. 从 components.manifest.json 的组件分组中复用控件——buttons/inputs/cards/badges/links已有成型配方，先组合、再按需微调；
4. 把source/文件当作回填审计证据——检查 token 一致性时以token-contract.report.json的 sources 行号为锚点。

Avoid（坚决避免）：

1. 避免在复制的:roottoken 块之外使用裸十六进制色值——所有颜色必须经由 token 引用，这是保证主题可切换、可审计的底线；
2. 避免脱离 tokens.css 独立重定义 Tailwind 或 design-token 值——tokens.css 是唯一事实源，派生文件一律从它生成；
3. 避免声称拥有上游原始来源证据——本包基于策展的 bundled fixture，不虚构原始抓取来源；
4. 避免添加 components.html / DESIGN.md 未表达的组件配方——新增配方必须先在 fixture 与规范文档中有据可依。

视觉核验与工作流收尾

当需要视觉 sanity check 时，打开preview/目录的三个独立页面：colors.html核验色板与 token 映射、typography.html核验字号阶梯与行高节奏、spacing.html核验间距步进与区块留白。它们与 components.html 一样是自包含的静态页面，可直接在浏览器中打开比对。

对 Agent 而言，一次完整的 Lingo 包使用流程是：读 USAGE.md 建立契约 → 读 DESIGN.md 建立风格心智 → 把 tokens.css 粘贴进产物<style>块 → 查 components.manifest.json 复用组件分组 → 需要时打开 components.html 取精确选择器 → 用 preview/ 页面做视觉收尾；对评审者而言，则按同一路径反向核验：token 名称是否保持、色值是否全部走 token、组件是否复用既有配方、是否有越界的新配方或裸色值。这套双向工作流正是 OpenDesign Design System 2.0"可被 Agent 消费、可被评审审计"的包契约设计目标。

赞分享

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

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

点击查看免费下载

相关推荐

• OpenDesign Cosmic 设计系统包使用指南：Agent 与评审者的 Design System 2.0 契约实操

  OpenDesign Cosmic 设计系统包使用指南：Agent 与评审者的 Design System 2.0 契约实操 Cosmic 是 OpenDesi

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

• OpenDesign Agentic 设计系统包使用契约：USAGE.md 如何指导 Agent 消费 Design System 2.0 包

  OpenDesign Agentic 设计系统包使用契约：USAGE.md 如何指导 Agent 消费 Design System 2.0 包 本文以 desi

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

• OpenDesign 企业级（Corporate）设计系统包使用指南：Design System 2.0 契约、Token 与组件装配实战

  OpenDesign 企业级（Corporate）设计系统包使用指南：Design System 2.0 契约、Token 与组件装配实战 本指南面向 Open

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

上一篇：A2UI Angular Framework Adapter 解析：用 Angular Signals 构建 Agent 驱动的动态 UI 渲染层

下一篇：从0到1部署ruadapt_qwen2.5_3B_finetuned_v3-openmind：适合初学者的完整指南 🚀