OpenDesign Flat 设计系统包实战指南面向 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-designFlat 设计系统包是 OpenDesign 仓库中design-systems/flat/目录下的一个可直接消费的 Design System 2.0 包其 USAGE.md 规定了 Agent 与审查者消费该包的契约先读哪份文件、如何粘贴令牌、如何复用组件、以及哪些行为被明确禁止。本文以该指南为骨架结合包内 DESIGN.md、tokens.css、components.manifest.json、design-tokens.json 与 source/ 审计文件展开帮助你理解并正确使用这一minimal、enterprise风格的扁平化设计系统包。一、Flat 包是什么位置、形态与包内结构OpenDesign 的设计系统目录按每个子目录即一个可移植设计系统包组织。仓库级说明见 design-systems/README.md目前内置目录收录了 151 个包每个包的最小机器可读形态统一为manifest.json DESIGN.md tokens.css三件套。Flat 包就是其中之一其稳定标识符为flat分类为Modern Minimal。design-systems/flat/目录下的完整文件构成如下文件/目录角色manifest.json包级元数据发现、溯源与声明的文件路径USAGE.md消费契约阅读顺序、Do / Avoid 守则DESIGN.md面向 Agent 的规范设计散文视觉意图、约束、反模式tokens.css编译后的语义令牌样式表唯一事实来源components.html参考组件 fixture精确选择器与状态components.manifest.json组件清单紧凑盘点 令牌引用分析design-tokens.json派生产物TOKEN_SCHEMA 契约数据tailwind-v4.css派生产物Tailwind v4 主题映射source/审计证据溯源报告、原始令牌、契约报告preview/可视化核对页colors / typography / spacingsystem/系统视图页index / kit / kit.dark / tokens.default从 manifest.json 可以看到包的来源声明为type: bundled、origin: OpenDesign curated bundled fixture——这是一个由 OpenDesign 策展的内置 fixture不是对上游品牌仓库的重新抓取这一点直接决定了下文Avoid守则中不得声称存在上游原始来源证据的规定。二、标准阅读顺序如何按契约消费一个设计系统包USAGE.md 第一条给出了明确的五步阅读顺序这是 Agent 与审查者都应该遵守的消费流程先读USAGE.md本身理解包的契约再读DESIGN.md掌握视觉意图、约束与反模式把tokens.css粘贴到第一个 artifact 的style块最前面然后再写组件 CSS——令牌先行组件样式必须建立在令牌之上用components.manifest.json做组件清单的紧凑盘点当需要精确选择器或状态细节时打开 components.html需要视觉核对时检查preview/页面。这套流程的关键思想是分层消费契约 → 意图 → 令牌 → 组件 → 视觉验证。其中第 3 步是硬性要求它的存在是为了保证任何生成物都从同一套语义令牌出发从而让跨品牌切换成为可能。三、设计基调minimal enterprise 的扁平化风格USAGE.md 的 Design Highlights 给出三条基调视觉风格minimal极简、enterprise企业级颜色立场primary、neutral、success、warning、danger 五类设计意图让输出对该风格家族可辨识同时保住可用性与可读性Primary 色#F2673C——来自样式基础的令牌。DESIGN.md 在此基础上展开了完整的视觉规范可作为风格实现的完整参照色彩体系除 Primary#F2673C外还有 Secondary#8B5CF6、Success#16A34A、Warning#D97706、Danger#DC2626、Surface#FFFFFF、Text#111827Neutral 则由 surface 令牌派生#FFFFFF用于官方格式兼容。使用上CTA 强调用 Primary大背景与卡片用 Surface正文用 Text 保证可读性。排版字号刻度为 12/14/16/20/24/32字体族 primaryInter、displayInter、monoJetBrains Mono字重覆盖 100–900。标题应承载风格个性正文则应优化扫读性与对比度。间距与栅格间距刻度 4/8/12/16/24/32跨区块保持一致的垂直节奏列与模块对齐到可预测的网格避免随意偏移。布局与构成偏好内部 padding 一致的内容块层级要直白——headline → support text → primary action在加边框或阴影之前先用留白分离区块。组件按钮——主操作用#F2673C次操作保持中性输入框——强 focus-visible 状态、清晰标签、可预测的错误提示卡片/区块——全页保持一致圆角、间距与抬升策略。动效与交互用微妙过渡突出 Primary 作为交互信号默认 150–250ms 的短促过渡与稳定缓动hover、focus-visible、active、disabled、loading 状态必须显式存在。语音与品牌语气与视觉一致——简洁、自信、产品相关微文案行动导向避免空泛填充标题保留风格身份UI 标签保持字面直白。反模式Anti-patterns已有令牌能解决的问题不得引入调色板外的颜色不得用统一字号/字重压平层级不得添加损害可读性或可访问性的装饰效果不得在同一界面混用无关的视觉隐喻。四、令牌契约tokens.css 与 56 个语义令牌的分层USAGE.md 要求把tokens.css原样粘贴进 artifact 的style块。完整内容如下design-systems/flat/tokens.css:root块共声明 56 个令牌:root { --bg: #f5f8ff; --surface: #ffffff; --surface-warm: #eaf1ff; --fg: #101828; --fg-2: #344054; --muted: #667085; --meta: #2563eb; --border: #d7e0ef; --border-soft: #edf2f8; --accent: #2563eb; --accent-on: #ffffff; --accent-hover: color-mix(in oklab, var(--accent), black 8%); --accent-active: color-mix(in oklab, var(--accent), black 14%); --success: #16a34a; --warn: #f59e0b; --danger: #ef4444; --font-display: Inter, system-ui, sans-serif; --font-body: Inter, system-ui, sans-serif; --font-mono: SF Mono, ui-monospace, Menlo, monospace; --text-xs: 12px; --text-sm: 14px; --text-base: 16px; --text-lg: 18px; --text-xl: 24px; --text-2xl: 36px; --text-3xl: 54px; --text-4xl: 76px; --leading-body: 1.52; --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: 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 52px rgba(16, 24, 40, 0.11); --focus-ring: 0 0 0 4px rgba(37, 99, 235, 0.22); --motion-fast: 150ms; --motion-base: 240ms; --ease-standard: cubic-bezier(0.2, 0, 0, 1); --container-max: 1180px; --container-gutter-desktop: 36px; --container-gutter-tablet: 24px; --container-gutter-phone: 16px; }4.1 令牌分层从 identity 到 slotdesign-tokens.json 按od-design-tokens/v1契约对这 56 个令牌做了分层归类source/token-contract.report.json 给出了同构报告层数量代表令牌语义A1-identity8--bg、--surface、--fg、--muted、--border、--accent、--font-display、--font-body风格身份的基础色与字体A1-structure18--text-*、--leading-*、--tracking-display、--section-y-*、--container-*结构尺寸字号、行高、区块节奏、容器B-slot4--surface-warm、--fg-2、--meta、--border-soft槽位令牌语义化中间层A226--accent-on/hover/active、--success/warn/danger、--space-*、--radius-*、--elev-*、--motion-*、--font-mono派生与功能令牌报告摘要显示56 个令牌全部有 source 背书sourceBackedTokens: 56其中 A1 层 26 个直接溯源、另有 26 个 fallback 令牌无别名令牌aliasTokens: 0契约评分为 100、等级excellent、recommendRebuild: false。每个令牌都带有sources字段指回tokens.css的具体声明行如tokens.css:16对应--accent形成契约数据 → 源样式表行号的双向可追溯。4.2 一个值得注意的事实文档声明与编译令牌的差异需要如实指出DESIGN.md 与 USAGE.md 声明的主色 Primary 为#F2673C但编译后的 tokens.css 中--accent实际为#2563eb同文件的--meta也是#2563eb。这正是 USAGE.md 要求把 tokens.css 原样粘贴、避免在复制的:root令牌块之外使用裸 hex 值的原因——以编译后的令牌样式表为准而不是以散文中的色值为准。若在生成物中直接写死#F2673C将无法享受令牌体系带来的跨品牌切换能力。五、组件清单components.manifest.json 与 components.htmlcomponents.manifest.json 是对 components.html 的机器可读盘点。其 fixture 统计为1 个 style 块、48 个选择器、26 个类、19 个元素令牌分析中 56 个声明令牌全部被引用或保留undeclaredReferenced: []即组件中没有引用任何未声明的令牌也没有游离裸值。组件被归纳为 8 个分组分组是否 present关键类引用令牌示例buttons按钮与 CTA✅.btn.btn-primary.btn-secondary--accent、--accent-on、--radius-md、--motion-fastinputs表单字段✅.field、input、label--border、--radius-sm、--focus-ringcards卡片与面板✅.panel.panel-head.tile.card-row.mini-card--surface、--elev-raised、--radius-lgbadges徽章/状态标签✅.status—links链接与行内动作✅a—typography字号刻度✅.eyebrow.lead、h1/h2/h3--text-4xl、--text-xl、--fg-2layout布局原语✅.container.metric-grid、mainsection--container-max、--section-y-*keyboard键盘提示❌——icons图标槽位❌——从 components.html 的实现看扁平化风格在代码层面落地为.btn-primary直接使用background: var(--accent):focus-visible统一挂box-shadow: var(--focus-ring).panel用color-mix(in oklab, var(--surface), transparent 4%)叠加 1px 边框与--elev-raised阴影.status::before用 8px 圆形色点表达在线状态.metric-grid以三等分网格与border-soft分隔线组织数据块。整个页面没有任何 3D 效果与投影堆叠符合 DESIGN.md二维极简的定位。响应式方面media (max-width: 860px)时 hero、lower、metric-grid、card-row 全部降为单列容器内边距随断点切换--container-gutter-*。六、派生产物tailwind-v4.css 与预览页6.1 Tailwind v4 主题映射tailwind-v4.css 是tokens.css的派生产物文件头明确声明Derived from tokens.css. Keep tokens.css as the source of truth.。它通过theme把 CSS 令牌桥接到 Tailwind 工具类命名空间import tailwindcss; import ./tokens.css; theme { --color-accent: var(--accent); --color-surface: var(--surface); --color-bg: var(--bg); --font-sans: var(--font-body); --spacing-4: var(--space-4); --shadow-raised: var(--elev-raised); --duration-fast: var(--motion-fast); /* ...其余映射见文件本体 */ }这意味着在 Tailwind v4 项目中可以写bg-accent、text-fg、shadow-raised、rounded-md等工具类而它们的值最终解析回tokens.css的:root令牌。切勿绕过 tokens.css 单独改这份文件——它是派生品应以令牌表为唯一事实来源。6.2 预览页与系统页preview/colors.html、preview/typography.html、preview/spacing.html分别提供色彩、排版、间距的可视化核对用于视觉 sanity check。system/index.html、system/kit.html、system/kit.dark.html系统视图与组件套件页含深色变体system/tokens.default.json 提供默认令牌的 JSON 形态。manifest.json 的preview字段显式声明了这三张预览页及其 rolecolors / typography / spacing说明预览页与包元数据是挂钩的。七、Do 与 AvoidAgent 使用守则逐条解析USAGE.md 的核心是四条 Do 与四条 Avoid逐条展开并结合包内证据如下Do应当做保留 schema 令牌名称原样不变保证跨品牌切换可靠。这一条由 design-tokens.json 的 TOKEN_SCHEMA 契约背书56 个令牌名、分层、行号溯源全部机器可校验改名即破坏契约。--accent只用于主操作、链接、焦点状态与一个明确的视觉焦点元素。这是一个页面只有一个主焦点的扁平化纪律components.html 中 accent 仅出现在.btn-primary、:focus-visible与 swatch 上与守则完全一致。先复用components.manifest.json里的组件分组再发明新控件。清单里 buttons / inputs / cards / badges / links / typography / layout 七组已 present覆盖常见界面要素只有 keyboard、icons 两组缺失时才需要新增。把source/文件当作 bundled fixture 回填的审计证据。source/evidence.md 记录了本包的来源范围与 fixture 清单source/token-contract.report.json 把每个契约绑定映射回tokens.css声明行审查时可据此核对任何令牌的值与出处。Avoid禁止做避免在复制的:root令牌块之外使用裸 hex 值——组件 CSS 只能引用var(--*)保证改令牌即可整体换肤。避免脱离tokens.css独立重定义 Tailwind 或 design-token 的值——tailwind-v4.css与design-tokens.json都是派生品绕过源头会引入双份真相。避免声称存在上游原始来源证据——包是curated bundled fixture而非对上游品牌的重新抓取manifest.json 与 source/evidence.md 均如此声明这是事实边界。避免添加components.html或DESIGN.md未体现的新组件配方——组件集是审查契约的一部分越界新增会让清单与实际产物脱节。八、审查者视角如何验证一个生成物合规结合全包结构审查者可建立如下核对清单令牌层artifact 的style是否以tokens.css的:root块开头组件中是否存在#hex裸值或脱离令牌的尺寸/颜色契约层用 source/token-contract.report.json 比对 56 个令牌的声明行与tokens.css实际内容确认没有漂移。组件层用 components.manifest.json 的 7 个 present 分组核对产物用到的类是否都在selectors/classes列表内新控件是否超出components.html所示范围。视觉层对照 preview/ 三张页面检查色值、字号刻度与间距刻度是否落在令牌区间内对照 system/kit.html 检查组件状态hover / focus-visible / disabled是否齐备。整套包的设计哲学可以概括为以tokens.css为唯一事实源、以components.manifest.json为组件边界、以source/为审计证据、以DESIGN.md为风格意图。Agent 按 USAGE.md 的读序与守则消费它就能稳定产出可辨识、可维护、可跨品牌切换的 Flat 风格界面审查者则依据同一套契约反向验证生成物是否越界。【免费下载链接】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），仅供参考