OpenDesign Ferrari 设计系统包使用指南USAGE.md 的 Agent 契约、Token 粘贴约定与派生文件链【免费下载链接】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/ferrari/USAGE.md 为骨架完整展开 OpenDesign「Design System 2.0」包中 Ferrari 包的阅读顺序、设计要点与 Do/Avoid 规则并结合 daemon 提示词组装源码、包 manifest 契约与 token schema说明这些规则背后的运行时机制——读完后你既知道 Agent 使用一个设计系统包的正确步骤也知道每条规则由哪个守卫脚本和哪段源码保证。USAGE.md 是什么Design System 2.0 包中的 Agent 契约design-systems/README.md 定义了包的形态design-systems/slug/下至少包含manifest.json、DESIGN.md、tokens.css三个文件在此之上可以声明更丰富的文件其中就包括「agent-facing read order and usage guide」——即USAGE.md。仓库当前内置 151 个设计系统包design-systems/ferrari/ 是其中一个manifest 中id: ferrari、category: Automotive其 manifest.json 通过usage: USAGE.md字段声明了这个指南文件的身份。关键点在于USAGE.md不是给人看的说明书而是「运行时输入」。daemon 在组装 agent 提示词时会把USAGE.md的内容作为「How to use this design system」章节注入提示词见 apps/daemon/src/prompts/system.ts 中designSystemUsageMd的用途注释与usageBlock拼接逻辑若包没有USAGE.md则退回一段默认的DEFAULT_DESIGN_SYSTEM_USAGE内容为「读 DESIGN.md、把 tokens.css 原样贴入第一个style、参照组件清单对齐组件形态」。因此 Ferrari 包里的 USAGE.md 实质上是覆盖了默认指引的、包级定制路由器——它决定了 Agent 读到 Ferrari 包时先看什么、后看什么、哪些文件可以跳过。五步阅读顺序Read OrderUSAGE.md 第一节给出的阅读顺序是先读 USAGE.md 本身理解包的契约package contract读 DESIGN.md获取视觉意图、约束与反模式anti-patterns把 tokens.css 原样贴入产出物artifact的第一个style块然后再写任何组件 CSS用 components.manifest.json 获取紧凑的组件清单只有当需要精确的 selector 或状态细节时才打开 components.html在需要视觉合理性检查时查看 preview/ 页面包含preview/colors.html、preview/typography.html、preview/spacing.html三个页面见 manifest 的preview.pages声明。这个顺序值得注意的两点tokens 先于组件 CSS第 3 步强制 token 先行。这与 design-systems/_schema/AGENTS.md 解释的「artifact 粘贴约束」直接相关——Agent 生成的产出物是把某一个品牌的:roottoken 块粘贴进单个style的独立 HTML不存在与品牌全局样式表并列加载的机制因此如果组件 CSS 先写了裸 hex 值就永远无法被品牌切换所覆盖。manifest 是索引fixture 是全文第 4 步把components.manifest.json定位为「紧凑清单」。该文件是从components.htmltokens.css派生的可重建缓存其source字段明确写了这两个来源Ferrari 包的派生结果记录了 fixture 统计1 个 style 块、48 个 selector、26 个 class、19 个元素。Agent 先读 JSON 索引控制 token 消耗仅在需要精确 selector/状态时才加载 HTML 全文这正是派生文件存在的意义。设计要点Design HighlightsUSAGE.md 的「Design Highlights」给出了 Ferrari 系统的四条核心特征它们是 DESIGN.md 中九大章节视觉主题、色彩、字体、组件、布局、深度、Do/Dont、响应式、Agent 提示词指南的高度压缩明暗对照chiaroscuro布局深黑章节与干净的白色编辑面板交替出现Ferrari 红#DA291C极端克制地使用——它是强调色accent不是氛围色atmosphere跃马徽标作为孤立的 hero 元素悬浮于纯黑void-black背景之上FerrariSans 专有字体紧凑比例、中等字重。对照 tokens.css 可以验证「accent 而非 atmosphere」这条规则在 token 层的落实整份:root中语义角色被显式拆分为--accent、--accent-on、--accent-hover、--accent-active一族用color-mix(in oklab, var(--accent), black 8%/14%)派生 hover/active 态而背景--bg、表面--surface、前景--fg等氛围层全部是黑/暖灰/米白色系与强调色完全解耦。Do 与 Avoid两组硬约束USAGE.md 的第三、四节是可直接执行成检查项的规则。完整继承如下Do应该做精确保留 schema token 名称这样跨品牌切换cross-brand switching才可靠用--accent表示主操作、链接、focus 状态以及唯一的焦点元素在自造新控件之前先复用 components.manifest.json 里的组件组把 source/ 目录下的文件当作「bundled fixture backfill」的审计证据。Avoid不要做在粘贴进产出物的:roottoken 块之外使用裸 hex 值脱离 tokens.css 独立地重新定义 Tailwind 或 design-token 的值声称拥有「上游原始来源证据」——本包基于 curated bundled fixture而非对上游品牌的实时爬取添加components.html或DESIGN.md中未体现的新组件配方。这四条 Avoid 规则分别对应仓库中真实的约束机制裸 hex 禁令对应_schema文档中解释的 artifact-paste 约束产出物内任何var(--motion-fast)引用若解析不到会「静默损坏」silently break同理绕过 token 的裸 hex 让跨品牌切换失去意义。禁止独立重定义 Tailwind 值对应派生文件契约tailwind-v4.css 的第一行注释就是Derived from tokens.css. Keep tokens.css as the source of truth.整个文件只做theme里var(...)的别名映射如--color-accent: var(--accent)、--spacing-4: var(--space-4)不写任何字面量。禁止虚报上游证据在 source/evidence.md 中被明确落实该文件声明本包「derived from the curated OpenDesign bundled fixture」source字段仅列出DESIGN.md、tokens.css、components.html三个 fixture 文件不含任何新鲜爬取声明。组件配方边界由components.manifest.json的派生关系保证它是components.htmltokens.css的可重建缓存仓库的守卫脚本如 scripts/check-design-system-manifests.ts、scripts/check-design-system-package-quality.ts会验证提交的 manifest 与新鲜派生结果一致防止「新增组件配方」只出现在一处而失步。源码印证daemon 如何消费 USAGE.md从源码结构看USAGE.md的消费点在 apps/daemon/src/prompts/system.ts第 709 行定义了DEFAULT_DESIGN_SYSTEM_USAGE——没有 USAGE.md 时的兜底指引第 768 行附近的注释说明designSystemUsageMd是「optional USAGE.md router that tells [the agent] how to use the system」第 1274–1279 行完成拼接存在则用usageMd否则用默认值最终注入提示词中形如## How to use this design system — Ferrari的章节。也就是说Ferrari 包里 USAGE.md 的每一条规则阅读顺序、accent 用法、fixture 审计要求都会以原文形式进入生成 agent 的系统提示词而不是仅作为仓库里的静态文档。包的其他运行时输入tokens.css、组件信息、importMode: normalized、craft绑定也在同一组装链路中被消费manifest.json 里的craft.suggested声明了color与accessibility-baseline两个 craft 指南建议对该包生效craft.applies与exemptions均为空。manifest.json 文件清单每个文件的角色manifest.jsonschemaVersion: od-design-system-project/v1声明了 Ferrari 包的完整文件面字段文件角色files.designDESIGN.md面向 agent 的规范设计文本canonical design prosefiles.tokenstokens.css规范编译后的语义 token 样式表files.designTokensdesign-tokens.json派生的 Design Tokens JSONfiles.tailwindtailwind-v4.css派生的 Tailwind v4theme映射files.componentscomponents.html独立组件 fixtureusageUSAGE.md本文的 Agent 契约componentsManifestcomponents.manifest.json由 fixture 派生的组件/token 索引preview.pagespreview/colors.html、preview/typography.html、preview/spacing.html静态预览页colors / typography / spacing 三个 rolesourceFilessource/evidence.md、source/tokens.source.json、source/token-contract.report.json导入证据、token 契约报告按 design-systems/README.md 的划分components.manifest.json、design-tokens.json、tailwind-v4.css都是「缓存而非竞争的真源」前者从components.html与tokens.css派生design-tokens.json从 token 契约报告派生且必须与tokens.css一致tailwind-v4.css从tokens.css派生。包级守卫manifest 守卫与 package-quality 守卫负责验证声明路径的安全与存在、JSON 索引可解析、派生文件与新鲜派生结果一致、token 契约与组件 fixture 无漂移。Token 约定为什么必须把 tokens.css 逐字贴入USAGE.md 第 3 步的「先贴 tokens 再写组件 CSS」不是风格建议而是由 token schema 的四层模型强制的。design-systems/_schema/AGENTS.md 把共享 token 分为四层A1-identity / A1-structure品牌决定、缺失即守卫失败如--bg、--accent、--font-display、字号阶梯、--container-max、--section-y-*A2品牌可省略、有 fallback但在 derive 脚本落地前每个品牌必须显式声明所有 A2 token如--motion-fast、--success、--space-4、--font-mono否则产出物中transition: var(--motion-fast)会静默失效B-slot更丰富的语义层如--fg-2、--surface-warm、--border-soft品牌要么写独立值要么原样 alias 到兄弟 token--fg-2: var(--fg)不允许省略。对照 tokens.cssFerrari 包完整声明了这四类背景/前景/强调色、8 级字号--text-xs12px 到--text-4xl88px、8 级间距--space-1到--space-12、三档 section 垂直间距desktop 112px / tablet 80px / phone 56px、圆角、阴影--elev-flat/raised/ring、红色 focus ring--focus-ring: 0 0 0 4px rgba(220, 0, 0, 0.30)、动效130ms / 220ms与容器宽度--container-max: 1240px。正因为产出物是单文件粘贴整份:root必须自包含——这就是「token 名精确保留 块外禁裸 hex」两条 Do/Avoid 规则的底层原因也是跨品牌切换同一份组件代码换:root即换品牌能成立的前提。Ferrari 系统的设计参数速查结合 DESIGN.md 的「Agent Prompt Guide」章节agent 在使用该包生成界面时的关键参数是色彩角色主 CTA 用 Ferrari Red#DA291C亮面#FFFFFF、暗面#000000、次级暗面#303030正文近黑#181818次级文本#666666、三级#8F8F8F、边框#CCCCCC按钮 hover 为青色#1EAEDB链接 hover 为藏青#3860BE赛车黄#FFF200/#F6E500仅限赛车传统语境字体FerrariSansfallback Arial/Helvetica/sans-serif标题默认 500 字重章节标题 26px/1.20Body-Font 小标签全大写 1px 字距形态交互元素 2px 圆角、按钮 12px/10px padding、卡片无阴影无描边深度来自黑/白表面色对比与摄影本身节奏黑沉浸→ 白编辑→ 黑 的章节交替每屏 Ferrari Red 只允许出现一处否则失去权威性。这些参数在 preview/ 三个页面中有可视化对照可作为 USAGE.md 第 5 步「视觉 sanity check」的落点。落地清单Agent 与评审者工作流把 USAGE.md 的规则收敛为可执行的检查流生成界面前确认产出物第一个style块是逐字的 tokens.css:root块对照 source/token-contract.report.json 可核验每个 token 声明行组件选型先查 components.manifest.json 的组件组与 token 声明列表再决定是否打开 components.html 核对 48 个 selector 的具体状态样式用--accent而非硬编码红色承载唯一焦点元素语义色--success/--warn/--danger不与品牌红混用——DESIGN.md 明确警告红#F13A2C与品牌红#DA291C是刻意的区分视觉校验时打开 preview/colors.html、preview/typography.html、preview/spacing.html若涉及包本身的改动按 design-systems/_schema/AGENTS.md 的要求运行守卫仓库根pnpm guard并跑pnpm typecheck确认 manifest、派生文件一致性与 token 契约全部通过涉及包目录结构的更完整作者指南见 docs/design-systems.md。需要特别保留的边界Ferrari 包是bundled curated fixturemanifestsource.type: bundled、source/evidence.md 声明不声称上游新鲜爬取且品牌参照类设计系统包定位是「美学灵感」而非官方品牌资产见 design-systems/README.md 的 Attribution 一节——在文章中引用或对外描述该包时应保持这一事实边界。【免费下载链接】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），仅供参考