OpenDesign GitHub 设计系统包使用指南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本篇指南围绕 OpenDesign 仓库中 design-systems/github 设计系统包的使用契约USAGE.md展开面向使用 OpenDesign 生成与评审界面的 Agent 与代码评审者系统讲解包的阅读顺序、文件职责、Token 语义与操作准则。读完本文你将掌握如何按契约消费一个品牌设计系统包——从粘贴tokens.css到复用组件清单、再到以source/文件完成审计闭环并理解其中每个规范背后的源码级依据。包契约一个品牌包是什么OpenDesign 的design-systems/目录为每个品牌维护一份独立的 Design System 2.0 包。以 GitHub 为例manifest.json明确声明了该包的结构化元数据schemaVersionod-design-system-project/v1定义包清单的版本契约id/name/categorygithub/GitHub/Developer Tools用于跨品牌检索与分类files指向包内五个核心产物——DESIGN.md设计意图、tokens.cssToken 样式表、design-tokens.json结构化 Token 清单、tailwind-v4.cssTailwind v4 派生层、components.html组件参考夹具usage指向USAGE.md即本文讲解的包使用指南componentsManifest指向components.manifest.json紧凑型组件清单preview声明preview/目录下的三张预览页colors / typography / spacingsourceFiles指向source/下的审计证据evidence、tokens 源文件、契约报告。换句话说一个包 设计意图DESIGN Token 契约tokens.css 组件证据components.html 审计证据source/ 使用指南USAGE.md的完整闭环。USAGE.md是这个闭环的入口与包契约本身。阅读顺序按契约消费一个包USAGE.md明确给出了五步阅读顺序这是 Agent 与评审者消费该包的规范路径每一步都对应一个具体产物先读本文档USAGE.md理解包契约的整体约定再读 DESIGN.md掌握视觉意图、约束与反模式anti-patterns把 tokens.css 粘贴到第一个 artifact 的style块中在编写任何组件 CSS 之前先建立 Token 基线使用 components.manifest.json 作为紧凑型组件清单当需要精确选择器或状态细节时打开 components.html需要视觉核验时检查preview/页面preview/colors.html、preview/typography.html、preview/spacing.html。这套顺序背后是一个清晰的依赖关系先理解为什么DESIGN.md再建立基础设施tokens.css随后才是用什么组件manifest → components.html最后是长什么样preview。跳过任何一步都可能导致组件 CSS 先于 Token 基线落笔破坏跨品牌切换的可靠性。设计要点GitHub 品牌的四个签名动作USAGE.md用四句话概括了该包的视觉签名全部可以在 tokens.css 与 DESIGN.md 中得到源码级印证设计要点Token 证据含义纯白画布或深海军黑无暖色调--bg: #ffffff、--surface: #f6f8fatokens.css第 30-31 行暗色为#0d1117表面无暖色分层--surface-warm直接别名到--surface发丝级灰边框定义每个窗格--border: #d0d7de第 41 行配--border-soft: #d8dee4用描边而非阴影传达结构密度优先Primer 蓝 GitHub 绿双主色--accent: #0969da、--accent-hover: #0550ae--success: #1a7f37第 45-51 行蓝管交互绿只管成功/合并状态高密度列表行留白罕见--text-base: 14px、行内边距 16px 横向 / 12px 纵向第 66、82-89 行14px 正文是 GitHub 产品密度的身份标识DESIGN.md进一步补充了品牌基座system-ui 字体栈贯穿全产品无自定义 web 字体代码用 SFMono/Menlo/ConsolasOcticon 风格 16px/24px 图标药丸形状态徽章带强色彩语义。Token 契约56 个 Token 的分层语义tokens.css是包的核心基础设施。从 source/token-contract.report.json 与 design-tokens.json 的契约摘要可知该包共声明56 个 Token全部有源码背书契约评分 100grade: excellent。Token 按TOKEN_SCHEMA分层A1-identity8 个品牌身份层如--bg、--surface、--fg、--muted、--border、--accent、--font-display、--font-bodyA1-structure18 个结构层如字体刻度--text-xs(12px) 到--text-4xl(32px)、行高--leading-body: 1.5、--tracking-display: -0.01em、容器--container-max: 1280px与三档 section 节奏A226 个实现层如间距--space-1(4px) 到--space-12(48px)、圆角--radius-sm(6pxPrimer 通用圆角)、阴影--elev-*、焦点环--focus-ring: 0 0 0 3px rgba(9,105,218,0.3)、动效--motion-fast(80ms) /--motion-base(200ms)B-slot4 个槽位层如--surface-warm、--fg-2、--meta均为品牌层的别名保证跨品牌切换时槽位语义稳定。关键设计决策在tokens.css头部注释中说明--text-base: 14px14px 正文即产品密度、--radius-sm: 6px交互元素统一圆角、--accent-active使用color-mix(in oklab, var(--accent), black 14%)计算按下态。components.manifest.json的 token 分析还给出declared58 项、referenced组件实际引用与unusedDeclared三份清单undeclaredReferenced为空证明组件 CSS 没有脱离 Token 体系的裸值引用。组件清单先用清单再翻夹具components.manifest.json以brandId: github组织了一份紧凑组件盘点夹具统计显示 components.html 包含 1 个 style 块、44 个选择器、21 个类与 21 个元素覆盖八个组件组groupsbuttons.btn、.btn-default、.btn-outline、.btn-primary及其 hover、:focus-visible引用--accent、--radius-sm、--surface等 12 个 Tokeninputs.field系列label / input / placeholder / focus引用--focus-ring实现 Primer 焦点环badges.status-pill.status-open/.status-closed/.status-merged/.status-draftcardspresent: false——GitHub 包刻意不提供营销大卡片这与quiet chrome、显式边框的护栏一致links、icons.icon16px 槽位、typography.body-muted、.body-sm、.eyebrow、layout.container、.stack-3、.stack-4、.hero-grid、.features-grid各司其职。使用准则是先复用 manifest 中的组件组再考虑发明新控件。components.html中每个可见值都来自tokens.css——例如.btn-primary的底色#1f883d、hover 变为var(--success)状态徽章的四个状态色#1a7f37/#cf222e/#8250df/#6e7781均以字面量锚定在组件夹具内未脱离 Token 体系。Do四条正向操作准则USAGE.md给出的正向准则每条都能在仓库中找到支撑严格保留 schema Token 名称——TOKEN_SCHEMA契约如--accent、--success、--space-4是跨品牌切换的稳定接口。design-tokens.json中每个 Token 都带sourceName与sources如tokens.css:30字段改名会直接破坏契约报告的可追踪性。用--accent承担主操作、链接、焦点态与唯一视觉焦点——components.html中链接色、输入框 focus 边框、outline 按钮 hover 均落在--accent上符合 Primer 蓝唯一交互色语义。优先复用components.manifest.json中的组件组——八组组件已覆盖按钮、输入、徽章、排版、布局等高频场景避免重复发明。把source/文件当作捆绑夹具回填的审计证据——source/evidence.md 明确声明该包源自 OpenDesign 精选的捆绑夹具bundled fixture并未对上游品牌仓库/网站进行全新抓取这是引用时必须如实标注的事实边界。Avoid四条反模式红线禁止在复制的:rootToken 块之外使用裸 hex 值——components.html的夹具自我声明Every visible value comes from tokens.css — no raw hex, no off-token type维护同样的纪律才能让跨品牌切换与契约审计成立。禁止脱离tokens.css单独重定义 Tailwind 或设计 Token 值——tailwind-v4.css 是派生产物其文件头明确写着Derived from tokens.css. Keep tokens.css as the source of truth所有theme绑定--color-accent: var(--accent)等都只是 Token 的再映射。禁止声称存在原始上游源码证据——本包基于精选捆绑夹具source/evidence.md与manifest.json的source.type: bundled、origin: OpenDesign curated bundled fixture是唯一可引用的来源声明。禁止添加components.html与DESIGN.md中不存在的组件配方——组件组清单groups中的present: false项如 cards、keyboard即有意留白新增配方会破坏审计闭环。审计证据链与派生产物治理包内source/目录构成完整的证据链source/evidence.md声明来源范围bundled fixture、不声称上游抓取与三条包含的夹具文件source/token-contract.report.json把每个TOKEN_SCHEMA绑定映射回tokens.css的声明行如--bg→tokens.css:30给出分层统计与契约评分source/tokens.source.jsonToken 的原始源数据。治理规则同样明确design-tokens.json与tailwind-v4.css是派生输出应依据契约报告与 Token 样式表重新生成而不是手工编辑——这让tokens.css 单一事实源在生成链路上成立。结语USAGE.md的价值在于它把品牌包如何被正确消费写成了一份可执行的契约先读 DESIGN 理解意图先贴 Token 再写 CSS先查 manifest 再翻夹具用 source/ 文件约束事实边界。对在 OpenDesign 中生成界面或评审产物的 Agent 而言遵循这五步顺序与 Do/Avoid 清单就能稳定产出高保真、可审计、可跨品牌切换的 GitHub 风格界面——而这一切的根始终扎在 tokens.css 这一个事实源上。【免费下载链接】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），仅供参考 OpenDesign GitHub 设计系统包使用指南：Design System 2.0 契约解读与实战
OpenDesign GitHub 设计系统包使用指南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本篇指南围绕 OpenDesign 仓库中 design-systems/github 设计系统包的使用契约USAGE.md展开面向使用 OpenDesign 生成与评审界面的 Agent 与代码评审者系统讲解包的阅读顺序、文件职责、Token 语义与操作准则。读完本文你将掌握如何按契约消费一个品牌设计系统包——从粘贴tokens.css到复用组件清单、再到以source/文件完成审计闭环并理解其中每个规范背后的源码级依据。包契约一个品牌包是什么OpenDesign 的design-systems/目录为每个品牌维护一份独立的 Design System 2.0 包。以 GitHub 为例manifest.json明确声明了该包的结构化元数据schemaVersionod-design-system-project/v1定义包清单的版本契约id/name/categorygithub/GitHub/Developer Tools用于跨品牌检索与分类files指向包内五个核心产物——DESIGN.md设计意图、tokens.cssToken 样式表、design-tokens.json结构化 Token 清单、tailwind-v4.cssTailwind v4 派生层、components.html组件参考夹具usage指向USAGE.md即本文讲解的包使用指南componentsManifest指向components.manifest.json紧凑型组件清单preview声明preview/目录下的三张预览页colors / typography / spacingsourceFiles指向source/下的审计证据evidence、tokens 源文件、契约报告。换句话说一个包 设计意图DESIGN Token 契约tokens.css 组件证据components.html 审计证据source/ 使用指南USAGE.md的完整闭环。USAGE.md是这个闭环的入口与包契约本身。阅读顺序按契约消费一个包USAGE.md明确给出了五步阅读顺序这是 Agent 与评审者消费该包的规范路径每一步都对应一个具体产物先读本文档USAGE.md理解包契约的整体约定再读 DESIGN.md掌握视觉意图、约束与反模式anti-patterns把 tokens.css 粘贴到第一个 artifact 的style块中在编写任何组件 CSS 之前先建立 Token 基线使用 components.manifest.json 作为紧凑型组件清单当需要精确选择器或状态细节时打开 components.html需要视觉核验时检查preview/页面preview/colors.html、preview/typography.html、preview/spacing.html。这套顺序背后是一个清晰的依赖关系先理解为什么DESIGN.md再建立基础设施tokens.css随后才是用什么组件manifest → components.html最后是长什么样preview。跳过任何一步都可能导致组件 CSS 先于 Token 基线落笔破坏跨品牌切换的可靠性。设计要点GitHub 品牌的四个签名动作USAGE.md用四句话概括了该包的视觉签名全部可以在 tokens.css 与 DESIGN.md 中得到源码级印证设计要点Token 证据含义纯白画布或深海军黑无暖色调--bg: #ffffff、--surface: #f6f8fatokens.css第 30-31 行暗色为#0d1117表面无暖色分层--surface-warm直接别名到--surface发丝级灰边框定义每个窗格--border: #d0d7de第 41 行配--border-soft: #d8dee4用描边而非阴影传达结构密度优先Primer 蓝 GitHub 绿双主色--accent: #0969da、--accent-hover: #0550ae--success: #1a7f37第 45-51 行蓝管交互绿只管成功/合并状态高密度列表行留白罕见--text-base: 14px、行内边距 16px 横向 / 12px 纵向第 66、82-89 行14px 正文是 GitHub 产品密度的身份标识DESIGN.md进一步补充了品牌基座system-ui 字体栈贯穿全产品无自定义 web 字体代码用 SFMono/Menlo/ConsolasOcticon 风格 16px/24px 图标药丸形状态徽章带强色彩语义。Token 契约56 个 Token 的分层语义tokens.css是包的核心基础设施。从 source/token-contract.report.json 与 design-tokens.json 的契约摘要可知该包共声明56 个 Token全部有源码背书契约评分 100grade: excellent。Token 按TOKEN_SCHEMA分层A1-identity8 个品牌身份层如--bg、--surface、--fg、--muted、--border、--accent、--font-display、--font-bodyA1-structure18 个结构层如字体刻度--text-xs(12px) 到--text-4xl(32px)、行高--leading-body: 1.5、--tracking-display: -0.01em、容器--container-max: 1280px与三档 section 节奏A226 个实现层如间距--space-1(4px) 到--space-12(48px)、圆角--radius-sm(6pxPrimer 通用圆角)、阴影--elev-*、焦点环--focus-ring: 0 0 0 3px rgba(9,105,218,0.3)、动效--motion-fast(80ms) /--motion-base(200ms)B-slot4 个槽位层如--surface-warm、--fg-2、--meta均为品牌层的别名保证跨品牌切换时槽位语义稳定。关键设计决策在tokens.css头部注释中说明--text-base: 14px14px 正文即产品密度、--radius-sm: 6px交互元素统一圆角、--accent-active使用color-mix(in oklab, var(--accent), black 14%)计算按下态。components.manifest.json的 token 分析还给出declared58 项、referenced组件实际引用与unusedDeclared三份清单undeclaredReferenced为空证明组件 CSS 没有脱离 Token 体系的裸值引用。组件清单先用清单再翻夹具components.manifest.json以brandId: github组织了一份紧凑组件盘点夹具统计显示 components.html 包含 1 个 style 块、44 个选择器、21 个类与 21 个元素覆盖八个组件组groupsbuttons.btn、.btn-default、.btn-outline、.btn-primary及其 hover、:focus-visible引用--accent、--radius-sm、--surface等 12 个 Tokeninputs.field系列label / input / placeholder / focus引用--focus-ring实现 Primer 焦点环badges.status-pill.status-open/.status-closed/.status-merged/.status-draftcardspresent: false——GitHub 包刻意不提供营销大卡片这与quiet chrome、显式边框的护栏一致links、icons.icon16px 槽位、typography.body-muted、.body-sm、.eyebrow、layout.container、.stack-3、.stack-4、.hero-grid、.features-grid各司其职。使用准则是先复用 manifest 中的组件组再考虑发明新控件。components.html中每个可见值都来自tokens.css——例如.btn-primary的底色#1f883d、hover 变为var(--success)状态徽章的四个状态色#1a7f37/#cf222e/#8250df/#6e7781均以字面量锚定在组件夹具内未脱离 Token 体系。Do四条正向操作准则USAGE.md给出的正向准则每条都能在仓库中找到支撑严格保留 schema Token 名称——TOKEN_SCHEMA契约如--accent、--success、--space-4是跨品牌切换的稳定接口。design-tokens.json中每个 Token 都带sourceName与sources如tokens.css:30字段改名会直接破坏契约报告的可追踪性。用--accent承担主操作、链接、焦点态与唯一视觉焦点——components.html中链接色、输入框 focus 边框、outline 按钮 hover 均落在--accent上符合 Primer 蓝唯一交互色语义。优先复用components.manifest.json中的组件组——八组组件已覆盖按钮、输入、徽章、排版、布局等高频场景避免重复发明。把source/文件当作捆绑夹具回填的审计证据——source/evidence.md 明确声明该包源自 OpenDesign 精选的捆绑夹具bundled fixture并未对上游品牌仓库/网站进行全新抓取这是引用时必须如实标注的事实边界。Avoid四条反模式红线禁止在复制的:rootToken 块之外使用裸 hex 值——components.html的夹具自我声明Every visible value comes from tokens.css — no raw hex, no off-token type维护同样的纪律才能让跨品牌切换与契约审计成立。禁止脱离tokens.css单独重定义 Tailwind 或设计 Token 值——tailwind-v4.css 是派生产物其文件头明确写着Derived from tokens.css. Keep tokens.css as the source of truth所有theme绑定--color-accent: var(--accent)等都只是 Token 的再映射。禁止声称存在原始上游源码证据——本包基于精选捆绑夹具source/evidence.md与manifest.json的source.type: bundled、origin: OpenDesign curated bundled fixture是唯一可引用的来源声明。禁止添加components.html与DESIGN.md中不存在的组件配方——组件组清单groups中的present: false项如 cards、keyboard即有意留白新增配方会破坏审计闭环。审计证据链与派生产物治理包内source/目录构成完整的证据链source/evidence.md声明来源范围bundled fixture、不声称上游抓取与三条包含的夹具文件source/token-contract.report.json把每个TOKEN_SCHEMA绑定映射回tokens.css的声明行如--bg→tokens.css:30给出分层统计与契约评分source/tokens.source.jsonToken 的原始源数据。治理规则同样明确design-tokens.json与tailwind-v4.css是派生输出应依据契约报告与 Token 样式表重新生成而不是手工编辑——这让tokens.css 单一事实源在生成链路上成立。结语USAGE.md的价值在于它把品牌包如何被正确消费写成了一份可执行的契约先读 DESIGN 理解意图先贴 Token 再写 CSS先查 manifest 再翻夹具用 source/ 文件约束事实边界。对在 OpenDesign 中生成界面或评审产物的 Agent 而言遵循这五步顺序与 Do/Avoid 清单就能稳定产出高保真、可审计、可跨品牌切换的 GitHub 风格界面——而这一切的根始终扎在 tokens.css 这一个事实源上。【免费下载链接】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），仅供参考