OpenDesign Agentic 设计系统包使用契约USAGE.md 如何指导 Agent 消费 Design System 2.0 包【免费下载链接】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本文以 design-systems/agentic/USAGE.md 为主体讲清 OpenDesign Design System 2.0 包中面向 Agent 的使用契约五步读取顺序Read Order、tokens.css令牌契约的粘贴时机、components.manifest.json紧凑组件清单的用法以及 Do/Avoid 硬性边界。读完本文你可以理解一个设计系统包如何被 daemon 装配进 Agent 提示词并能在自己的 Agent 工作流中按同一契约稳定地复用任意 bundled 设计系统包。1. USAGE.md 在包结构中的位置OpenDesign 的design-systems/目录下每个子目录都是一个可移植的设计系统包。按 design-systems/README.md 的说法内置目录当前包含 151 个包每个包都有同一套最小机器可读形状design-systems/slug/ ├── manifest.json ├── DESIGN.md └── tokens.cssmanifest.json拥有稳定的发现元数据、来源provenance和声明的包路径DESIGN.md是面向 Agent 的规范性设计散文tokens.css是规范化的、已编译的语义令牌样式表。在这个最小形状之上包可以声明一批富包文件rich package files其中就包括本文主角USAGE.md 面向 Agent 的读取顺序与使用指南 components.html 独立组件 fixture components.manifest.json 派生的组件/令牌索引 design-tokens.json 派生的 Design Tokens JSON tailwind-v4.css 派生的 Tailwind v4 映射 preview/ 带索引的预览页 source/ 导入证据、片段与令牌报告README 明确指出这些字段是活跃的运行时输入而不是结构性占位符These fields are active runtime inputs, not structural placeholders提示词组装会消费USAGE.md、tokens.css、组件信息、导入模式、craft 绑定以及由 manifest 派生的 pull index。也就是说USAGE.md不是给人类阅读的 README而是写给 Agent 的路由器——告诉它在生成产物时应该按什么顺序读取哪些文件。design-systems/agentic/USAGE.md 是agentic包的这份契约全文很短结构固定为四部分Read Order读取顺序、Design Highlights设计要点、Do、Avoid。下面按这四部分逐项展开。2. 五步读取顺序Read Order原文档给出的读取顺序如下此处为 USAGE.md 的完整继承先读本文件USAGE.md理解包契约读DESIGN.md获取视觉意图、约束和反模式anti-patterns在编写组件 CSS 之前先把tokens.css粘贴进产物第一个style块用components.manifest.json获取紧凑的组件清单当需要精确选择器或状态时再打开components.html当需要做视觉 sanity check 时检查preview/页面。这五步的设计意图是渐进式披露Agent 先拿到契约与散文意图再把令牌契约作为不可变底料注入产物组件细节按需下钻避免一开始就把整个包的 2000 多行 fixture HTML 塞进上下文。对 agentic 包而言这五步具体落到这些文件DESIGN.md即 design-systems/agentic/DESIGN.md共九节Visual Theme Atmosphere、Color、Typography、Spacing Grid、Layout Composition、Components、Motion Interaction、Voice Brand、Anti-patterns描述了一个以对话式 AI 为先、控件精简、结果清晰、面向 agentic 工作流的委派任务流界面。tokens.css即 design-systems/agentic/tokens.css:root中的语义令牌契约详见第 4 节。components.manifest.json即 design-systems/agentic/components.manifest.json由components.html与tokens.css派生的索引。preview/按 manifest 声明agentic 包含三个预览页——preview/colors.html、preview/typography.html、preview/spacing.html分别对应colors、typography、spacing三种 role。值得注意的是第 3 步的顺序要求先粘贴 tokens再写组件 CSS。这保证了组件样式只能消费令牌变量而不是旁路硬编码与 Avoid 一节不要在被复制的:root令牌块之外使用原始十六进制色值形成闭环。3. manifest.jsonagentic 包的文件声明design-systems/agentic/manifest.json 是这份使用契约的目录页声明了 USAGE.md 所引用文件的实际位置。关键字段摘录如下{ schemaVersion: od-design-system-project/v1, id: agentic, name: Agentic, category: Themed Unique, source: { type: bundled, origin: OpenDesign curated bundled fixture }, files: { design: DESIGN.md, tokens: tokens.css, designTokens: design-tokens.json, tailwind: tailwind-v4.css, components: components.html }, usage: USAGE.md, componentsManifest: components.manifest.json, importMode: normalized, craft: { applies: [], suggested: [color, accessibility-baseline], exemptions: [] }, preview: { dir: preview, pages: [ ... ] }, sourceFiles: { evidence: source/evidence.md, tokens: source/tokens.source.json, report: source/token-contract.report.json } }对 USAGE.md 契约的支撑关系usage字段显式声明本包的使用指南就是USAGE.mdcomponentsManifest声明紧凑索引文件。daemon 读取资产时正是按manifest?.usage ?? USAGE.md这样的声明优先、默认名兜底策略定位文件见第 7 节源码。importMode: normalized表示该包是规范化导入的产物daemon 提示词中会带上designSystemImportMode字段取值normalized | hybrid | verbatim让 Agent 知晓当前包的导入形态。craft.suggested推荐两个 craft 参考color、accessibility-baseline对应仓库根目录下 craft/color.md 与 craft/accessibility-baseline.md 这类工艺规范属于 DESIGN.md 与 skill 正文之间的补充规则层。sourceFiles三个路径对应审计证据文件与 Do 一节把source/文件视为 bundled fixture 回填的审计证据直接呼应见第 8 节。4. 被粘贴的令牌契约tokens.css 的:root块USAGE.md 第 3 步要求粘贴的 tokens.css 是一个完整的:root变量块按语义分组如下数值均取自该文件分组代表令牌值背景/表面--bg/--surface/--surface-warm#0b1020/#131b2f/#182343文本层级--fg/--fg-2/--muted/--meta#f8fafc/#cbd5e1/#8ea0b8/#60a5fa边框--border/--border-soft#293653/#1e2a43强调色--accent/--accent-on#60a5fa/#06111f强调色派生--accent-hover/--accent-activecolor-mix(in oklab, var(--accent), black 8%/14%)语义状态色--success/--warn/--danger#22c55e/#fbbf24/#fb7185字体--font-display/--font-body/--font-monoInter / Inter / JetBrains Mono字号阶梯--text-xs…--text-4xl12 / 13 / 15 / 17 / 22 / 32 / 48 / 66 px行距与字距--leading-body/--leading-tight/--tracking-display1.55 / 1.06 / -0.02em间距8pt 基线--space-1…--space-124 / 8 / 12 / 16 / 20 / 24 / 32 / 48 px分区间距--section-y-desktop/tablet/phone96 / 68 / 48 px圆角--radius-sm/md/lg/pill8 / 12 / 20 px / 9999px投影--elev-flat/--elev-ring/--elev-raisednone / 1px 边框环 / 0 24px 72px 深阴影焦点环--focus-ring0 0 0 4px rgba(96, 165, 250, 0.28)动效--motion-fast/--motion-base/--ease-standard130ms / 220ms /cubic-bezier(0.2, 0, 0, 1)容器--container-max/ gutterdesktop/tablet/phone1200px / 36 / 24 / 16 px文件头注释点明了这个包的视觉定位agent workflow interface with dark command surfaces, blue automation signals, and traceable task cards深色命令面板、蓝色自动化信号、可追溯任务卡。Do 规则与令牌的关系USAGE.md 要求用--accent承担主操作、链接、焦点态和一个清晰的焦点元素。在 agentic 包里--accent就是蓝色#60a5fa与深色表面构成自动化信号语义--focus-ring也用同一蓝色系保证焦点状态与强调色一致。一个值得注意的张力DESIGN.md第 2 节 Color 表中把#FF5701列为 PrimaryUSAGE.md 的 Design Highlights 也继承了Primary:#FF5701— Token from style foundations但编译后的tokens.css实际采用的是深蓝底、蓝色强调的面板风格。按 design-systems/README.md 的定义tokens.css是canonical compiled semantic-token stylesheet规范化编译产物而 daemon 在组装提示词时是把tokens.css契约追加在DESIGN.md 散文之后、用于消歧令牌名与组件形状的见第 7 节。因此 USAGE.md 的 Avoid 规则——不要在被复制的:root令牌块之外使用原始十六进制值——恰好给出了裁决方式产物的实际观感以粘贴进来的令牌块为准DESIGN.md 中的散文色值只作为风格家族层面的描述。Agent 若把#FF5701直接写进组件 CSS反而会违反包契约。5. 紧凑组件清单components.manifest.jsonUSAGE.md 第 4 步的紧凑组件清单是 design-systems/agentic/components.manifest.json它按 design-systems/README.md 的说明由components.html与tokens.css派生derived files are caches rather than competing sources of truth。其结构分四块fixture 统计title为 Agentic - reference componentsfixture 含 1 个 style 块、48 个选择器、26 个 class、19 个元素——Agent 可由此判断清单的可信规模而无需打开完整的 components.html。tokens 审计declaredtokens.css 中声明的 56 个令牌、referencedfixture CSS 实际引用的 49 个、unusedDeclared已声明但 fixture 未用的 7 个--accent-active、--danger、--elev-flat、--motion-base、--space-1、--space-12、--warn、undeclaredReferenced引用了未声明令牌本包为空数组——即无幽灵令牌。selectors / classes / elements全量选择器、类名与元素清单例如.btn、.btn-primary、.panel、.field、input:focus等。groups按组件语义归组这是 Do 规则在自造新控件之前先复用components.manifest.json里的组件组的落地依据。agentic 的 9 个组及其present状态组 id标签存在buttons按钮与 CTA是inputs表单字段与控件是cards卡片与面板是badges徽章、chips、状态标签是links链接与行内操作是keyboard键盘提示否icons图标槽位否typography字号阶梯与文本工具类是layout布局基元是每个存在的组还列出该组选择器与引用的令牌。例如buttons组选择器为.btn、.btn-primary、.btn-primary:hover、.btn-secondary、.btn-secondary:hover、.btn:focus-visible引用令牌--accent、--accent-on、--border、--ease-standard、--elev-ring、--fg、--font-body、--motion-fast、--radius-md、--space-5、--surface、--text-sm——这等于告诉 Agentagentic 风格的主按钮就是蓝色令牌 中圆角 快动效这一组合复刻或扩展控件时照此消费即可。6. Do / Avoid使用契约的硬性边界USAGE.md 的 Do/Avoid 两节是整份契约的约束核心原文如下完整继承DoPreserve the schema token names exactly so cross-brand switching stays reliable.精确保持 schema 令牌名保证跨品牌切换的可靠性。Use--accentfor primary actions, links, focus states, and one clear focal element.主操作、链接、焦点态和一个清晰焦点元素统一使用--accent。Reuse component groups fromcomponents.manifest.jsonbefore inventing new controls.自造新控件之前先复用组件清单中的组件组。Treatsource/files as audit evidence for the bundled fixture backfill.把source/文件视为 bundled fixture 回填的审计证据。AvoidAvoid raw hex values outside the copied:roottoken block.在被复制的:root令牌块之外不要使用原始十六进制色值。Avoid redefining Tailwind or design-token values independently oftokens.css.不要独立于tokens.css另行重定义 Tailwind 或设计令牌值。Avoid claiming original upstream source evidence; this package is based on the curated bundled fixture.不要声称拥有原始上游来源证据本包基于精选的 bundled fixture。Avoid adding new component recipes that are not represented incomponents.htmlorDESIGN.md.不要添加components.html或DESIGN.md中未体现的新组件配方。逐条解释其工程含义第一条 Do 是跨品牌切换的前提。OpenDesign 的语义令牌 schema--bg、--surface、--fg、--accent、--space-*等在所有包间保持同名组件 CSS 只写var(--accent)而不写具体色值于是同一套组件代码可以在任意 bundled 包之间切换而无需改动——这也是 Why 粘贴令牌块而不是复制色值的根本原因。Avoid 第二条针对 Tailwind 生态包内派生了 design-systems/agentic/tailwind-v4.css由tokens.css派生如果 Agent 另行手写theme值或自定义 design token就会与派生映射失配。Avoid 第三、四条与 source/evidence.md 的声明一致agentic 是 curated fixture 回填不是对上游品牌的实时抓取详见第 8 节Agent 在输出描述性文字时不得把 fixture 冒充官方一手来源。7. 运行时链路daemon 如何消费 USAGE.mdUSAGE.md 的 Read Order 不是文档洁癖它与 daemon 侧的资产读取、提示词组装一一对应。资产读取。apps/daemon/src/design-systems/index.ts 中的readDesignSystemAssets并行读取四类文件const [usageMd, tokensCss, fixtureHtml, componentsManifestJson] await Promise.all([ readManifestFileOptional(brandRoot, manifest?.usage ?? USAGE.md), readFileOptional(path.join(brandRoot, manifest?.files.tokens ?? tokens.css)), manifest?.files.components undefined manifest ! null ? Promise.resolve(undefined) : readFileOptional(path.join(brandRoot, manifest?.files.components ?? components.html)), readManifestFileOptional(brandRoot, manifest?.componentsManifest ?? components.manifest.json), ]);返回的资产对象还包含pullIndexbuildDesignSystemPullIndex(manifest)生成的、供后续 pull-channel 使用的 richer-files 清单、importMode、craft 绑定等。同文件中 第 855-875 行 的designSystemAssetsRootFingerprint把manifest.json、USAGE.md、tokens.css、components.html、components.manifest.json一起纳入指纹计算——任何一份改动都会使该品牌的提示词缓存失效并触发重新组装。这也解释了 design-systems/README.md 的说法目录在每次/api/design-systems请求时扫描修改包之后刷新 Design System 界面即可无需重启 daemon。提示词组装。apps/daemon/src/prompts/system.ts 中的系统提示字段注释把 USAGE.md 的角色说得最直白// - designSystemUsageMd — optional USAGE.md router that tells // agents how to consume this package.其余字段一一对应 Read Order 的产物designSystemTokensCss逐字tokens.css:root 契约Agent 粘贴进产物style、designSystemComponentsManifest由 components.html 派生的简洁结构化摘要、designSystemFixtureHtml无法派生 manifest 时的逐字回退、designSystemPullIndexmanifest 派生的轻量 richer-files 列表。注释还说明拼装顺序When present they are appended AFTER the DESIGN.md block so prose still sets the high-level voice and the structured form disambiguates token names worked component shapes追加在 DESIGN.md 块之后散文定调结构化形式消歧令牌名与组件形状并提供了OD_DESIGN_TOKEN_CHANNEL0环境变量作为该 token 通道的 kill switch。导入时自动生成。对导入进来的包契约同样成立apps/daemon/src/design-systems/import.ts 的导入流程会把USAGE.md列入产物文件清单并通过renderUsageMd(displayName, scan)写入一份按扫描结果渲染的 USAGE.md约 第 454 行 将usage: USAGE.md写进 manifest。也就是说 bundled 包由维护者手写、导入包由 importer 生成但 Agent 面对的都是同一份router契约。8. 来源与审计source/ 目录的三重证据Do 规则要求把source/文件视为 bundled fixture 回填的审计证据agentic 包的 source/ 目录正好提供三份source/evidence.md声明本包derived from the curated OpenDesign bundled fixture且 does not claim a fresh crawl of the original upstream brand repository or website不声称对上游品牌仓库或网站的实时抓取列明纳入的 fixture 文件为 DESIGN.md、tokens.css、components.html。source/token-contract.report.json按 evidence.md 的说法maps every TOKEN_SCHEMA binding back to the committed tokens.css declaration line——把 schema 中的每个令牌绑定映射回 tokens.css 的具体声明行是令牌契约的逐行审计底稿。source/tokens.source.json回填时的令牌源数据。evidence.md 同时规定 design-systems/agentic/design-tokens.json 与 design-systems/agentic/tailwind-v4.css 是derived outputs应由报告与令牌样式表再生成而非手改——这与 Avoid 第二条不得独立于 tokens.css 重定义令牌值从维护侧和消费侧共同封死了旁路。9. 小结把 USAGE.md 当作可执行的提示词约束把 design-systems/agentic/USAGE.md 放回它在 OpenDesign 体系中的位置它是 Design System 2.0 包契约里给 Agent 的调度层与 DESIGN.md意图层、tokens.css契约层、components.manifest.json索引层共同构成散文定调、令牌定界、索引定形的三层消费模型daemon 的readDesignSystemAssets与系统提示字段保证了 Read Order 不是纸面流程而是真实的提示词组装路径source/证据文件则约束了 Agent 对外表述的来源边界。如果你在 OpenDesign 中切换品牌、审查产物配色或用自建 fixture 回填新包按 USAGE.md 的五步顺序执行、并守住 Do/Avoid 四条正四条反的边界就能让产物的视觉一致性可追溯、可审计。【免费下载链接】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创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考