深入解析 OpenDesign 的 HUD 设计系统从证据链到 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导读本文以 OpenDesign 仓库中design-systems/hud主题设计系统包为对象从source/evidence.md的证据声明出发完整梳理 HUDHeads-Up Display平视显示设计语言在开源仓库中的落地形态包括色板与排版规则、组件实现、56 个语义 Token 的分层契约以及tokens.css、design-tokens.json、tailwind-v4.css之间单一事实来源的派生关系。读完本文你将掌握如何阅读一个 Design System 2.0 包的机器可读结构如何用证据链文件校验 Token 与源码声明行的一一对应以及如何在 Agent 提示词中正确引用该设计系统生成 HUD 风格界面。1. 证据文件在 HUD 包中的定位design-systems/hud/source/evidence.md是整个 HUD 设计系统包的审计说明。它只有三段内容却定义了该包最重要的元信息来源范围Source Scope明确指出该 Design System 2.0 回填backfill派生自 OpenDesign 精选的内置 fixtureopen-design-bundled-fixture并未声称对上游原始品牌仓库或网站进行全新爬取。这是一个诚实的前置声明你在仓库里看到的所有 HUD 样式均以打包 fixture 为准。包含的 fixture 文件DESIGN.md、tokens.css、components.html三份文件构成了 HUD 包的内容主体。Token 契约source/token-contract.report.json把每一个 TOKEN_SCHEMA 绑定映射回已提交的tokens.css声明行而design-tokens.json与tailwind-v4.css是派生产物应当从报告与 token 样式表重新生成而不是手工编辑。从包整体来看manifest.json中source.type为bundled、origin为OpenDesign curated bundled fixture与证据文件的声明完全一致。sourceFiles字段显式登记了证据文件source/evidence.md、来源 Tokensource/tokens.source.json与契约报告source/token-contract.report.json。可以说evidence.md 是该包机器可读、可审计的入口它告诉你哪些是来源、哪些是派生、哪些必须重新生成。2. HUD 视觉语言与设计规则DESIGN.md 核心HUD 的设计意图来自 DESIGN.md一套战斗机/直升机平视显示器的视觉语言——磷光绿phosphor green叠加在近黑色底上、全大写数据覆盖层、棱角分明的几何图形。设计目标是在 200 节航速、仪表气象条件下依然零歧义可读。2.1 色板与角色元素Hex角色Background#0A0A0A近黑主画布Surface#111316抬升面板、卡片背景Border#1E2328轻微面板分隔Primary#00FF41活动读数、全部数据值Secondary#7FFF00待机/变暗数值、非活动字段Tertiary#5A9A5A网格线、刻度、参考弧Warning#FFB800警示、系统通告Alert#FF3B3B关键告警、故障指示文档声明所有数据色在#0A0A0A上均通过 WCAG AA最低 4.5:1对比度。暗色模式是原生且唯一的模式——HUD 只存在于低照度或高眩光的座舱环境中按设计不存在亮色模式。:root { --color-bg: #0A0A0A; --color-surface: #111316; --color-border: #1E2328; --data-primary: #00FF41; --data-secondary: #7FFF00; --data-tertiary: #5A9A5A; --data-warning: #FFB800; --data-alert: #FF3B3B; }2.2 排版规则角色字号字重行高字体Display32px7001.0JetBrains MonoHeading12px7001.0Inter大写Body14px4001.2JetBrains MonoLabel10px6001.0Inter大写Micro8px7001.0Inter大写供目录提取用的字体栈font labels for catalog extraction为JetBrains Mono, ui-monospace, SFMono-Regular, SF Mono, Menlo, Consolas, monospaceDisplay/Body/Mono与Inter, -apple-system, BlinkMacSystemFont, Segoe UI, Helvetica, Arial, sans-serifHeading/Label/Micro。2.3 组件样式骨架数据读数Data Readout永远使用--data-primary.data-readout { font-family: JetBrains Mono, monospace; font-size: 14px; font-weight: 700; color: var(--data-primary); letter-spacing: 0.05em; } .data-readout-label { font-family: Inter, sans-serif; font-size: 10px; font-weight: 600; text-transform: uppercase; color: var(--data-tertiary); letter-spacing: 0.1em; }状态指示器Status Indicator的颜色直接映射运行状态.status-dot { width: 8px; height: 8px; border-radius: 50%; background: var(--data-primary); /* active */ } .status-dot.standby { background: var(--data-secondary); } .status-dot.warning { background: var(--data-warning); } .status-dot.alert { background: var(--data-alert); }2.4 布局、层级与反模式HUD 是叠加系统overlay system布局采用绝对定位的叠加层网格线以显示器中心准星为参照数据读数按更新频率聚类高度更新慢于空速告警状态覆盖所有其他信息层。深度通过不透明度与辉光表达而非投影阴影HUD 存在于单一视觉平面。响应式行为上HUD 叠加层与视口相对关键读数速度、高度、航向在任何尺寸下保持可见次要指示器隐藏或最小化布局使用 12 列网格并将数据面板锚定到屏幕边缘。DESIGN.md 明确列出的禁令同样重要tertiary 色只用于网格线与参考标记、不得用于正文或读数文本不动画化不传达运行状态的元素不提供亮色模式圆角不超过 50%不使用渐变仅纯色填充不以颜色作为唯一信息传达手段须以位置和标签强化。3. 从设计语言到可运行 Tokentokens.css 的真实契约需要特别指出DESIGN.md 中的--color-bg/--data-primary是面向人类阅读的角色名而包内真正被机器消费的语义 Token 位于 tokens.css其命名遵循 OpenDesign 全仓库统一的 TOKEN_SCHEMA。文件头注释将其描述为HUD interface language with dark transparent panels, cyan telemetry, and compact status readouts深色透明面板、青色遥测、紧凑状态读数。:root { --bg: #090b12; --surface: #121722; --surface-warm: #1b2233; --fg: #f8fafc; --fg-2: #cbd5e1; --muted: #94a3b8; --meta: #60a5fa; --border: #2a3447; --border-soft: #1d2636; --accent: #60a5fa; --accent-on: #06101d; --accent-hover: color-mix(in oklab, var(--accent), black 8%); --accent-active: color-mix(in oklab, var(--accent), black 14%); --success: #22c55e; --warn: #fbbf24; --danger: #fb7185; --font-display: IBM Plex Mono, ui-monospace, monospace; --font-body: IBM Plex Mono, ui-monospace, monospace; --font-mono: IBM Plex Mono, ui-monospace, monospace; --text-xs: 11px; --text-sm: 12px; --text-base: 14px; --text-lg: 16px; --text-xl: 20px; --text-2xl: 28px; --text-3xl: 40px; --text-4xl: 56px; --leading-body: 1.45; --leading-tight: 1.06; --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: 80px; --section-y-tablet: 60px; --section-y-phone: 42px; --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 24px 72px rgba(0, 0, 0, 0.42); --focus-ring: 0 0 0 4px rgba(96, 165, 250, 0.28); --motion-fast: 100ms; --motion-base: 180ms; --ease-standard: cubic-bezier(0.2, 0, 0, 1); --container-max: 1280px; --container-gutter-desktop: 36px; --container-gutter-tablet: 24px; --container-gutter-phone: 16px; }观察要点配色差异是正常的tokens.css中--bg为#090b12而非 DESIGN.md 的#0A0A0A、强调色--accent为青色#60a5fa而非磷光绿。这说明 DESIGN.md 描述的是品牌叙事层面的理想色板而tokens.css是实际编译进产物、经过契约校验的最终绑定。以tokens.css为准是使用该包的正确姿势。派生与派生源--accent-hover、--accent-active使用color-mix(in oklab, ...)表达式从--accent派生是 Token 之间依赖的典型示例。声明即契约components.manifest.json中tokens.declared列出的 56 个 Token 与tokens.css完全对应其中--accent-active、--danger、--elev-flat、--motion-base、--space-1、--space-12、--warn在 fixture 中未被引用unusedDeclared说明 schema 要求声明完备而不以是否被引用为准。4. Token 分层契约A1 / A2 / B-slot 是什么evidence.md提到TOKEN_SCHEMA binding其权威定义位于 packages/contracts/src/design-systems/token-schema.ts并经 design-systems/_schema/tokens.schema.ts 再导出。每个 Token 恰好属于四层之一由谁决定值、品牌缺省时发生什么区分A1-identity必备即品牌Token 本身就是品牌无法用任何回退替代。如--bg、--fg、--accent、字体栈。HUD 包中 A1-identity 共 8 个。A1-structure必备结构性决策字号阶梯、布局网格、区块节奏等没有跨品牌通用默认值的结构性 Token每个品牌自己编写。HUD 包中 A1-structure 共 18 个。A2最终 tokens.css 必备但存在合理回退当品牌的 DESIGN.md 未指定值时派生脚本PR-B会把_schema/defaults.css中的回退值内联进来。A2 之所以必备但可回退而非可选Agent 生成产物时是把某个品牌的:root块整体粘贴进单个style不存在运行时级联若缺失var()目标transition: var(--motion-fast)会变成空值导致规则被丢弃。HUD 包中 A2 共 26 个。B-slot可选槽位须可解析为跨品牌一致性而存在无丰富层级的品牌可别名到命名兄弟 Token。如--surface-warm可别名var(--surface)、--fg-2可别名var(--fg)。引用 B-slot 的组件在任何品牌上都能解析。HUD 包中 B-slot 共 4 个。C-extension品牌专属白名单制schema 之外的品牌专属名通用跨品牌组件禁止引用当 ≥2 个品牌需要同名时升级为 B-slot有全局默认时升级为 A2。token-schema.ts同时提供辅助函数getRequiredA1Names()、getRequiredA2Names()、getBSlotNames()、getAllSchemaNames()、isAllowedExtension()供 guard 脚本做程序化校验。5. 证据链的机器验证token-contract.report.json 与 tokens.source.jsonsource/目录下的三份文件构成完整的证据闭环token-contract.report.json641 行——契约报告。summary显示totalTokens: 56、declaredTokens: 56、sourceBackedTokens: 56即每一个 Token 都有tokens.css源码行背书sourceBackedA1: 26、fallbackTokens: 26A2 的回退值、aliasTokens: 0分层计数为 A1-identity 8、A1-structure 18、A2 26、B-slot 4。score: 100、grade: excellent、recommendRebuild: false。每条 Token 记录都带sources数组精确指向声明行例如--bg→tokens.css:7、--surface→tokens.css:8。tokens.source.json349 行——来源 Token 清单同样以tokens.css:行号逐条登记 56 个 Token 的 layer 归属例如--font-display属于 A1-identity、--text-4xl: 56px属于 A1-structure。evidence.md—— 声明上述两者的关系并规定design-tokens.json与tailwind-v4.css必须由报告 Token 样式表再生成regenerate而非手工编辑。从源码结构看该闭环由 scripts/check-tokens-fixture-sync.ts 的六个 guard 检查强制保证其中checkDesignSystemTokenFixtureSync要求components.html的:root与tokens.css的:root经规范化后逐字节等价其余检查分别覆盖 A1/A2/B-slot 必备声明、未知 Token 拦截、A2 默认值一致性。整个校验可独立运行pnpm exec tsx scripts/check-tokens-fixture-sync.ts或作为pnpm guard的一部分。6. 派生产物design-tokens.json 与 tailwind-v4.cssevidence.md明确design-tokens.json与tailwind-v4.css是派生输出它们的正确维护方式是从报告和tokens.css再生成。design-tokens.json格式为od-design-tokens/v1contract 为TOKEN_SCHEMA。每条 Token 带type如color与confidence: highsources回指tokens.css行号。其 summary 与契约报告完全一致score 100 / grade excellent。tailwind-v4.css头部注释写着 Derived from tokens.css. Keep tokens.css as the source of truth.通过import tailwindcssimport ./tokens.css再在theme块中把每个语义 Token 映射为 Tailwind v4 主题变量theme { --color-bg: var(--bg); --color-surface: var(--surface); --color-accent: var(--accent); --color-accent-on: var(--accent-on); --color-success: var(--success); --color-warn: var(--warn); --color-danger: var(--danger); --font-display: var(--font-display); --font-body: var(--font-body); --font-mono: var(--font-mono); --text-4xl: var(--text-4xl); --spacing-4: var(--space-4); --radius-pill: var(--radius-pill); --shadow-raised: var(--elev-raised); --shadow-focus-ring: var(--focus-ring); --duration-fast: var(--motion-fast); --ease-standard: var(--ease-standard); --container-max: var(--container-max); /* …其余映射见文件全文… */ }由此在 HUD 包中可以用bg-bg、text-fg、border-border、shadow-raised等 Tailwind 工具类而其值全部回落到tokens.css的:root。7. 组件 fixture 与预览页直观校验入口components.html自包含组件 fixture第一个style内嵌与tokens.css逐字节一致的:root因此可直接在浏览器中独立渲染。它示范了 hero 区eyebrow H1 lead 双按钮、panel 组件panel-head 状态徽标 metric-grid 指标网格、mini-card 与色板 swatch、输入控件、tile 卡片等。components.manifest.json机器可读的组件清单统计出 48 个选择器、26 个类、19 个元素把组件分组为 buttons、inputs、cards、badges、links、typography、layout 等 9 个组并为每个组列出其引用的 Token 集合——例如 buttons 组引用--accent、--accent-on、--motion-fast、--ease-standard、--radius-md等 12 个 Token这正是证据链延伸到组件粒度的体现。preview/ 目录colors.html、typography.html、spacing.html三个预览页通过link relstylesheet href../tokens.css /引入 Token用于视觉抽查。8. Agent 使用指南如何在提示词中落地 HUD 风格包内 USAGE.md 给出了 Agent 与审阅者的读取顺序契约先读 USAGE.md 理解包契约 → 读 DESIGN.md 了解视觉意图与反模式 → 把tokens.css粘贴到产物第一个style块 → 用components.manifest.json查组件清单、需要精确选择器时打开components.html→ 需要视觉检查时看preview/页。DESIGN.md 第 9 节为生成 HUD 风格界面提供了可直接采用的提示要点所有数据读数使用 JetBrains Mono标签一律 Inter 大写所有活动读数--data-primary设为#00FF41状态过渡用 150ms ease-out数据值变化用 100ms linear必须包含 active/standby/warning/alert 四态的状态指示器组件所有文本在#0A0A0A上须通过 4.5:1 对比度绝不添加装饰性动画或亮色模式变体。在 OpenDesign 的语境下design-systems/README.mdtokens.css的语义 Token 命名必须原样保留跨品牌切换才能保持可靠--accent用于主操作、链接、焦点态与单一视觉焦点优先复用components.manifest.json中的组件组而不是发明新控件source/目录只作为打包 fixture 回填的审计证据不得声称来自上游原始品牌爬取。9. 实践小结一套可审计的设计系统包回顾整个 HUD 包其工程价值在于把设计语言变成了可校验的机器契约人读DESIGN.md 描述品牌叙事、色板角色、排版与禁令含不提供亮色模式这类强约束机读tokens.css 提供 56 个按 A1/A2/B-slot 分层的语义 Tokencomponents.manifest.json提供组件→Token 的引用索引可审计source/evidence.md 声明来源范围token-contract.report.json把每个 Token 映射回tokens.css声明行并给出 100 分契约评分guard 脚本check-tokens-fixture-sync.ts在 CI 中强制:root逐字节一致、A1/A2/B-slot 必备、未知 Token 拦截可派生design-tokens.json与tailwind-v4.css全部由tokens.css再生成杜绝双源漂移。对想要在 OpenDesign 中新增或复用主题设计系统的开发者而言正确的路径是以tokens.css为唯一事实来源 → 让components.html的:root与之一致 → 由契约报告生成派生产物 → 用 guard 脚本兜底校验。HUD 包正是这一流程的完整范例。关键文件索引文件作用source/evidence.md来源范围声明与 Token 契约总纲DESIGN.md视觉语言、色板、排版、组件、禁令与 Agent 提示tokens.css56 个语义 Token 的权威:root绑定source/token-contract.report.jsonToken→声明行映射与契约评分source/tokens.source.json来源 Token 分层清单design-tokens.json派生 Design Tokens JSONtailwind-v4.css派生 Tailwind v4 主题映射components.html自包含组件 fixturecomponents.manifest.json组件分组与 Token 引用索引USAGE.mdAgent 读取顺序与使用规范manifest.json包元数据与文件登记token-schema.tsTOKEN_SCHEMA 分层契约权威定义check-tokens-fixture-sync.ts六项 guard 校验实现design-systems/README.md包目录结构与清单行为总览【免费下载链接】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），仅供参考