OpenDesign 的 Colorful 设计系统包使用指南：从令牌契约到组件落地的完整实战

OpenDesign 的 Colorful 设计系统包使用指南从令牌契约到组件落地的完整实战【免费下载链接】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-designColorful 是 OpenDesign 仓库中以design-systems/colorful/目录形式内置的 Design System 2.0 设计系统包面向编码 Agent 与人工审查者reviewer提供一套高对比、活泼、高级感的视觉语言。本指南以 USAGE.md 为核心骨架结合包内tokens.css、components.html、manifest.json等真实产物与仓库设计系统规范完整讲解该包的阅读顺序、令牌契约、组件清单与使用边界读完你可以在自己的 Artifact 或页面中正确接入 Colorful 令牌、复用其组件配方并确保跨品牌切换时令牌命名稳定可靠。一、包契约概览Colorful 是什么、包含哪些文件Colorful 属于 Design System 2.0 体系下的一个bundled内置打包包。根据 manifest.json它通过od-design-system-project/v1模式描述自身id / namecolorful/ColorfulcategoryBold Expressive大胆与表现力source.typebundled来源于 OpenDesign 官方整理的固定样例curated bundled fixture并非对上游品牌站点的重新抓取这一点在 source/evidence.md 中有明确声明craft 建议color与accessibility-baseline色彩与可访问性基线previewpreview/目录下提供colors.html、typography.html、spacing.html三个视觉预览页用于快速核对视觉效果包内核心文件分工如下文件角色USAGE.md包使用契约先读本文件DESIGN.md视觉意图、约束与反模式tokens.css规范化的令牌绑定canonical compiled tokens唯一事实源components.html参考组件实现精确选择器与状态以它为准components.manifest.json紧凑的组件清单design-tokens.json从 tokens.css 派生的结构化令牌 JSONtailwind-v4.css从 tokens.css 派生的 Tailwind v4 主题绑定source/审计证据evidence.md、token-contract.report.json、tokens.source.json在仓库层面docs/design-systems.md定义了 Design System 2.0 的通用目录约定每个包目录都应当包含DESIGN.md、tokens.css、components.html与manifest.json且tokens.css是所有派生产物的唯一事实源。Colorful 包严格遵循了这一约定。二、推荐阅读顺序Read OrderUSAGE.md 给出了面向 Agent 与审查者的固定阅读顺序这是正确使用该包的起点先读本文件USAGE.md理解包契约与使用边界再读 DESIGN.md掌握视觉意图、约束与反模式anti-patterns将tokens.css粘贴到第一个 Artifact 的style块中再编写组件 CSS——令牌先行组件跟随使用components.manifest.json作为紧凑的组件清单当需要精确选择器或状态细节时打开components.html需要做视觉核对时查看preview/页面。这套顺序的核心思想是契约 → 意图 → 令牌 → 组件 → 视觉验证的渐进式工作流避免在缺乏令牌与组件依据的情况下凭空发明样式。三、设计亮点与设计意图Design HighlightsColorful 的设计定位可以从 DESIGN.md 与 USAGE.md 中归纳为四点视觉风格高对比high-contrast、活泼playful、高级感premium色彩立场primary / neutral / success / warning / danger 五类语义色齐备设计意图让输出对本风格家族保持可辨识度的同时兼顾可用性与可读性主色#3B82F6来自 style foundations 的令牌值需要特别留意的是DESIGN.md中给出的主色#3B82F6属于风格基础层的描述性令牌而tokens.css中真正落到页面上的--accent为#ff6b00饱和橙色。两者并不矛盾——前者描述风格家族的身份主色后者是该包在当前页面里承担交互强调角色的实际令牌。这正是 Design System 2.0 中identity 令牌与slot 令牌分层设计的体现详见下文令牌分层。四、tokens.css 深度解析令牌分层与关键取值tokens.css 是 Colorful 包的规范令牌样式表。文件头部注释点明了其气质colorful product language with warm bright canvas and saturated action color温暖明亮的画布 饱和的行动色。全部令牌声明在:root块内共 56 个令牌。根据 source/token-contract.report.json 与 design-tokens.json 的统计令牌分为四层层数量含义代表令牌A1-identity8品牌身份层承载风格基底--bg、--surface、--fg、--muted、--border、--accentA1-structure18结构层定义排版、间距、容器节奏--text-*、--space-*、--container-max、--section-y-*A226组件/交互层状态与控件令牌--accent-hover、--radius-*、--elev-*、--motion-*B-slot4语义槽位层组件消费的接口令牌--surface-warm、--fg-2、--meta、--border-softreport 给出的契约体检结果是score: 100、grade: excellent、recommendRebuild: false56 个令牌全部sourceBacked有 tokens.css 声明行背书逐条映射到tokens.css:7至tokens.css:62等声明行。4.1 色彩令牌语义色令牌值用途--bg#fff8d7页面暖色画布底色--surface#ffffff卡片、大背景等表面色--surface-warm#ffef9f暖色表面mini-card 等--fg#1d1836正文文字色保证可读性--fg-2#4c426c次级文字lead、label--muted#796f91弱化信息metric 注释、tile 描述--meta#ff6b00元信息/眉题eyebrow、status--accent#ff6b00主行动色唯一焦点元素--accent-on#ffffff主行动色上的前景色--success#2e9d57成功态status 指示灯--warn#ffb020警告态--danger#e5484d危险态--border#eadfba常规描边--border-soft#f5eccd细分隔线值得一提的实现细节--accent-hover与--accent-active使用color-mix(in oklab, var(--accent), black 8% / 14%)派生而不是硬编码另一个 hex——这保证了状态色永远与主色同源也是 components.html 中.btn-primary:hover能自动跟随主题变化的原因。4.2 排版令牌字号阶梯--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展示标题负字距字体族display/body 均使用Inter, system-ui, sans-serifmono 使用SF Mono, ui-monospace, Menlo, monospace字重DESIGN.md声明支持 100–900 全梯度标题常用 700/760如h1为font-weight: 7604.3 间距、圆角、阴影、动效与容器令牌间距8pt 基线--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 18px 44px rgba(29, 24, 54, 0.14)、--focus-ring: 0 0 0 4px rgba(255, 107, 0, 0.26)动效--motion-fast: 150ms、--motion-base: 240ms、--ease-standard: cubic-bezier(0.2, 0, 0, 1)容器--container-max: 1180pxgutter 按断点分为--container-gutter-desktop: 36px、--container-gutter-tablet: 24px、--container-gutter-phone: 16px这些取值与 DESIGN.md 中8pt baseline grid150–250ms 过渡稳定缓动的约束一一对应属于可直接照搬进style块的完整令牌集。五、组件清单从 manifest 到参考实现components.manifest.json 是紧凑的组件盘点入口其 fixture 统计显示参考实现共 1 个 style 块、48 个选择器、26 个类、19 个元素。令牌审计区分了declared56 个声明、referenced46 个被组件引用与unusedDeclared7 个声明但未在参考实现中使用如--accent-active、--danger、--elev-flat、--warn等undeclaredReferenced为空——说明组件没有引用任何未声明的令牌契约自洽。5.1 组件分组groupsmanifest 按功能把组件划分为 8 个分组group id标签是否 present涉及选择器/类buttonsButtons and calls to action是.btn、.btn-primary、.btn-secondary及 hover/focus-visible 态inputsForm fields and controls是.field、input、input:focus、labelcardsCards and panels是.card-row、.panel、.panel-head、.tilebadgesBadges, chips, and status labels是.statuslinksLinks and inline actions是a元素keyboardKeyboard hints否—iconsIcon slots否—typographyTypography scale and text utilities是.eyebrow、.lead、h1–h3layoutLayout primitives是.container、.metric-grid、section每个分组还记录了tokenReferences例如 buttons 组消费--accent、--accent-on、--border、--ease-standard、--elev-ring、--fg、--font-body、--motion-fast、--radius-md、--space-5、--surface、--text-sm共 12 个令牌。这意味着只要 tokens.css 完整粘贴组件配方就能拿到全部依赖无需引入额外硬编码值。5.2 参考实现中的关键状态components.html 是精确选择器与状态的权威来源值得注意的实现要点.btn使用min-height: 44px触控友好尺寸过渡覆盖 background-color、border-color、color、transform、box-shadow 五个属性时长统一--motion-fast--ease-standard.btn:focus-visible使用box-shadow: var(--focus-ring)呈现 4px 橙色焦点环:hover时主按钮背景切到--accent-hover并轻微上移translateY(-1px)次按钮则是描边与文字转向--accentinput:focus同样复用--focus-ringborder-color: var(--accent)保证焦点、悬停、状态共用同一套系统信号components.html 中的文案原话.status::before用 8px--radius-pill圆点 --success表达在线状态与--meta文字色共同构成徽章态响应式max-width: 860px时.hero、.lower、.metric-grid、.card-row全部降为单列max-width: 639px时容器 gutter 收窄到--container-gutter-phone。六、派生产物与审计证据链Colorful 包不是一份 CSS 走天下而是围绕单一事实源建立了一套可审计的产物链tokens.css是唯一事实源按 source/evidence.md 的说明design-tokens.json与tailwind-v4.css都是派生输出应当由契约报告与令牌样式表重新生成而不应手工编辑design-tokens.json以od-design-tokens/v1格式输出 56 个令牌每个令牌带typecolor/dimension/fontFamily/number/duration/cubicBezier/shadow、layer、confidence: high与sources行号映射tailwind-v4.css通过import ./tokens.csstheme块把--color-*、--font-*、--text-*、--spacing-*、--radius-*、--shadow-*、--duration-*、--ease-*全部桥接为 Tailwind v4 主题变量供bg-accent、text-fg、rounded-md这类工具类直接使用source/token-contract.report.json逐条把每个 TOKEN_SCHEMA 绑定映射回tokens.css的声明行作为契约体检报告本包 100 分 / excellentsource/evidence.md声明证据边界——本包源自 OpenDesign 官方固定样例不声称抓取过上游品牌仓库或网站也不应据此宣称原始上游来源证据。这一事实源 派生物 审计报告的结构与仓库docs/design-systems.md中描述的 Design System 2.0 规范一致tokens.css必须满足共享令牌 schema由packages/contracts/src/design-systems/token-schema.ts定义并通过design-systems/_schema/再导出最终tokens.css需包含每个必需令牌且与DESIGN.md的表述互相印证。七、使用规范Do 与 AvoidUSAGE.md 明确给出了使用与禁止事项这是包契约中约束力最强的部分。应当做的Do原样保留 schema 令牌名--accent、--surface、--fg等名字必须逐字保留跨品牌切换cross-brand switching的可靠性完全依赖令牌命名稳定用--accent表达强调主操作、链接、焦点态以及页面中唯一清晰的焦点元素都使用--accent让交互信号全系统一致先复用组件组写新控件前先查components.manifest.json是否已有可复用的组件组避免重复发明把source/当审计证据source/evidence.md、token-contract.report.json用于核对bundled fixture backfill是否与tokens.css声明一致。应当避免的Avoid禁止在粘贴的:root令牌块之外使用裸 hex 值任何颜色都应走令牌否则会破坏主题替换能力禁止脱离tokens.css独立重定义 Tailwind 或 design-token 值tailwind-v4.css、design-tokens.json都是派生物改它们会造成证据链断裂undeclaredReferenced会从空变为非空禁止声称有原始上游来源证据本包基于 curated bundled fixture不能宣称抓取过上游品牌源站source/evidence.md 的明确边界禁止添加components.html或DESIGN.md中不存在的组件配方新增配方必须有参考实现背书。结合 DESIGN.md 的反模式清单还可补充两条实践红线不要引入调色板之外的色彩当已有令牌能解决问题时不要用同一种字号/字重压平层级hierarchy 必须清晰标题 → 支撑文本 → 主行动。八、实操一个最小接入示例综合上述契约一个规范的 Colorful 页面接入流程可以概括为复制 tokens.css 的整个:root块到首个 Artifact 的style中这是 Read Order 第 3 步的硬性要求按components.manifest.json的 groups 挑选组件组buttons / inputs / cards / badges / typography / layout从 components.html 复制对应选择器文本与颜色一律引用令牌color: var(--fg)、background: var(--surface)、border-radius: var(--radius-md)不写裸值需要 Tailwind 时直接基于 tailwind-v4.css 的theme映射使用bg-accent、text-fg、rounded-md等工具类需要视觉核对时打开 preview/colors.html、preview/typography.html、preview/spacing.html 三页对照预期效果。如果需要了解 Design System 2.0 的整体约定目录结构、manifest schema、tokens.css 编写规范可继续阅读仓库级文档 docs/design-systems.md 与 design-systems/README.md。九、小结Colorful 包的独特价值在于它把风格气质温暖画布 饱和橙色行动色落实为一套完全令牌化、可审计、可跨品牌切换的工程契约USAGE.md定义使用边界DESIGN.md定义视觉意图tokens.css提供 56 个分层令牌components.html给出 48 个选择器的参考实现source/目录则用 100 分契约报告锁死证据链。对 Agent 而言遵循粘贴 tokens.css → 查询 manifest → 复用组件 → 只用令牌的流程即可在保持 Colorful 风格可辨识度的同时产出可读、可访问且可维护的界面对审查者而言source/token-contract.report.json的undeclaredReferenced与unusedDeclared两个字段就是最直接的合规体检项。【免费下载链接】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），仅供参考