OpenDesign Professional 设计系统包使用指南Agent 与评审者的 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/professional这一 Design System 2.0 包展开系统讲解它的包契约package contract、阅读顺序、设计要点、Token 体系与组件清单并结合仓库内的tokens.css、components.html、components.manifest.json、design-tokens.json等真实文件给出可落地的使用规则。读完本文你将掌握如何让编码 Agent 严格遵循 Professional 风格族输出界面如何用 Token 与组件清单做跨品牌一致性校验以及如何把source/目录当作可审计的证据链使用。一、包的定位Design System 2.0 的机器可读契约design-systems/professional/是 OpenDesign 设计系统目录下的一个可移植包。根据仓库 design-systems/README.md 的说明每个子目录都是一个独立的设计系统包从 Design System 界面或受支持的项目创建流程中选中某个包时其设计上下文会被组合进 Agent 的提示词prompt中。当前打包目录包含 151 个包每个包的最小结构为design-systems/slug/ ├── manifest.json ├── DESIGN.md └── tokens.css其中manifest.json负责稳定发现元数据与来源信息DESIGN.md是面向 Agent 的权威设计文案tokens.css是编译后的语义 Token 样式表。而 Professional 包在最小结构之上进一步声明了富文件集rich files其 manifest.json 明确列出了这些字段{ schemaVersion: od-design-system-project/v1, id: professional, name: Professional, category: Professional Corporate, description: Bundled OpenDesign package for Professional, derived from curated DESIGN.md, tokens.css, and components.html fixtures., source: { type: bundled, origin: OpenDesign curated bundled fixture }, files: { design: DESIGN.md, tokens: tokens.css, designTokens: design-tokens.json, tailwind: tailwind-v4.css, components: components.html }, usage: USAGE.md, componentsManifest: components.manifest.json, importMode: normalized, craft: { applies: [], suggested: [color, accessibility-baseline] }, preview: { dir: preview, pages: [ { path: preview/colors.html, role: colors, title: Colors }, { path: preview/typography.html, role: typography, title: Typography }, { path: preview/spacing.html, role: spacing, title: Spacing } ] }, sourceFiles: { evidence: source/evidence.md, tokens: source/tokens.source.json, report: source/token-contract.report.json } }USAGE.md 正是这个包的“使用说明”即本篇文章的主体。它面向两类读者OpenDesign Agent在生成界面时消费该包和评审者reviewer在审查产物时校验是否符合契约。这一“读者即使用者”的双重定位决定了它的内容以规则和约束为主而非泛泛的介绍。二、阅读顺序Agent 消费该包的推荐路径USAGE.md 给出了五步阅读顺序这是包作者对消费流程的明确设计值得逐条展开先读本文件USAGE.md理解包契约的整体约定包括 Token 命名、组件来源、证据链语义。再读 DESIGN.md获取视觉意图、约束与反模式anti-patterns。这是“为什么这样做”的依据。将tokens.css粘贴到第一个 artifact 的style块中且在编写任何组件 CSS 之前完成。这保证所有组件样式都建立在同一套语义 Token 之上而不是各自为政的魔法数字。使用components.manifest.json作为紧凑的组件清单当需要精确选择器selector或状态state细节时打开 components.html。需要视觉检查时查看preview/页面即 preview/colors.html、preview/typography.html、preview/spacing.html 三个预览页。从实现层面看这一步一对应着实际消费链路USAGE.md、tokens.css与组件信息都会进入提示词组合prompt composition这在design-systems/README.md的“Rich package files”一节有明确说明——这些字段是运行时输入不是结构占位符。因此阅读顺序不是个人偏好而是 Agent 正确解析包内容的必要步骤。三、设计要点速览现代、商务、可读USAGE.md 提炼了该包的设计特征视觉风格Visual stylemodern现代。色彩立场Color stanceprimary、secondary、neutral、success、warning、danger 六类语义色。设计意图Design intent让输出对这一风格族保持可辨识度recognizable同时保住可用性与可读性usability and readability。主色Primary#FECE14——来自 style foundations 的 Token。值得注意的是#FECE14亮黄色是 DESIGN.md 中记载的“风格基调主色”而实际编译后的 tokens.css 中交互主色--accent是#2563eb蓝色。二者并不冲突#FECE14是风格家族的识别色identity--accent是界面交互语义色action。评审者在阅读时应区分“品牌识别色”与“组件语义色”两个层面避免用错 Token 层次。DESIGN.md 还进一步给出了全套色彩语义语义值说明Primary#FECE14来自 style foundations 的 TokenCTA 强调用Secondary#000000来自 style foundations 的 TokenSuccess#16A34A来自 style foundations 的 TokenWarning#D97706来自 style foundations 的 TokenDanger#DC2626来自 style foundations 的 TokenSurface#FFFFFF大背景与卡片用Text#111827正文用保证易读性Neutral#FFFFFF由 surface Token 派生用于官方格式兼容使用建议CTA 强调用 Primary#FECE14大面积背景与卡片用 Surface#FFFFFF正文保持 Text#111827以确保对比度。四、Token 体系tokens.css 的完整结构与语义分层tokens.css是本包 Token 的唯一事实来源source of truth。它定义了 56 个 Token涵盖颜色、字体、字号、间距、圆角、阴影、动效与容器八个维度。USAGE.md 要求“将 tokens.css 粘贴进第一个 artifact 的style块”因此理解其结构是正确使用的前提。4.1 颜色 Token--bg: #f5f8ff; /* 页面背景极浅蓝 */ --surface: #ffffff; /* 卡片/面板表面 */ --surface-warm: #eaf1ff; /* 暖色表面浅蓝渐变区/迷你卡片 */ --fg: #101828; /* 主前景/正文 */ --fg-2: #344054; /* 次级前景/说明文字 */ --muted: #667085; /* 弱化文字 */ --meta: #2563eb; /* 元信息/眉标eyebrow颜色 */ --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;hover/active 状态使用 CSScolor-mix(in oklab, ...)派生而非写死新色值这保证了任何主题覆盖后状态色仍然自洽——这是 Token 化状态管理的典型手法。4.2 字体与排版 Token--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; /* 标题字距 */DESIGN.md 说明排版采用移动优先的紧凑字号阶梯mobile-first compact scale标题承载风格个性正文优化扫描性与对比度。字重覆盖 100–900 全档。components.html 中实际使用了font-weight: 760h1这类非整百字重说明 Inter 变量字体在该包中被当作可用资源。4.3 间距、圆角与容器 Token--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; --container-max: 1180px; --container-gutter-desktop: 36px; --container-gutter-tablet: 24px; --container-gutter-phone: 16px;间距遵循 4/8/12/16/24/32 阶梯与 DESIGN.md 的“Spacing scale: 4/8/12/16/24/32”一致圆角按 10/16/24/9999 四档容器最大宽度 1180px并针对桌面/平板/手机分别给出 36/24/16px 的 gutter。components.html 中的媒体查询media (max-width: 1023px)与(max-width: 639px)正是这套响应式值的消费方。4.4 阴影与动效 Token--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);动效时长与 DESIGN.md 的“150–250ms 短促过渡”建议吻合缓动函数cubic-bezier(0.2, 0, 0, 1)是标准“快速进入、稳定结束”的曲线。焦点环--focus-ring是可达性基线accessibility-baseline的关键支撑manifest 的craft.suggested字段也推荐了 craft/color.md 与 craft/accessibility-baseline.md 作为配套规范。五、design-tokens.json分层契约与质量评分design-tokens.json 是由tokens.css派生的规范化 Token 清单采用od-design-tokens/v1格式。它的 summary 字段提供了非常有用的审计信息{ totalTokens: 56, declaredTokens: 56, sourceBackedTokens: 56, sourceBackedA1: 26, fallbackTokens: 26, aliasTokens: 0, layerCounts: { A1-identity: 8, B-slot: 4, A2: 26, A1-structure: 18 }, score: 100, grade: excellent, recommendRebuild: false }Token 被分为四个语义层A1-identity8 个品牌身份层如--bg、--surface、--fg、--muted、--border、--accent、--font-display、--font-bodyA1-structure18 个结构层如全部--text-*字号、行高、section 纵向间距、容器宽度与 gutterB-slot4 个槽位层如--surface-warm、--fg-2、--meta、--border-softA226 个派生/补充层如--accent-on、hover/active、success/warn/danger、间距、圆角、阴影、动效。每个 Token 条目都带有confidence: high、sources如tokens.css:7与sourceName实现了从派生 JSON 反查回 CSS 声明行的完整溯源。评分 100、等级excellent、recommendRebuild: false说明当前派生产物与 Token 源完全同步无需重建。六、components.manifest.json组件清单的机器索引components.manifest.json 是紧凑的组件索引USAGE.md 推荐用它做日常清单只有需要精确选择器时才打开 components.html。它记录的关键统计包括fixturestyleBlockCount: 1、selectorCount: 48、classCount: 26、elementCount: 19tokens56 个声明 Token 中 44 个被引用7 个未使用--accent-active、--danger、--elev-flat、--motion-base、--space-1、--space-12、--warnundeclaredReferenced: []表示不存在“未声明却被引用”的悬空 Token——契约自洽groups把组件归为 8 个组其中 6 个存在buttons、inputs、cards、badges、links、typography、layout2 个缺失keyboard、icons。每个组件组都列出了对应选择器、类与所引用的 Token。例如buttons.btn、.btn-primary、.btn-primary:hover、.btn-secondary、.btn-secondary:hover、.btn:focus-visible引用--accent、--accent-on、--border、--ease-standard、--elev-ring、--fg、--font-body、--motion-fast、--radius-md、--space-5、--surface、--text-sminputs.field、input、input:focus、labelcards.card-row、.panel、.panel-head、.tile引用--border、--elev-raised、--radius-lg、--surfacetypography.eyebrow、.lead、h1–h3引用--fg-2、--text-4xl、--text-lg、--text-xllayout.container、section引用--container-gutter-phone、--container-gutter-tablet、--section-y-desktop。这份清单直接支撑了 USAGE.md 的 Do 规则“优先复用 components.manifest.json 中的组件组而不是发明新控件”因为它把“可复用什么”变成了机器可查询的结构化数据。七、components.html精确选择器与状态的唯一权威当需要精确选择器或状态细节时应打开 components.html。它是一份 136 行的独立 HTML fixture内嵌完整:rootToken 块与组件 CSS展示了一个“专业服务”界面hero 区、.eyebrow眉标、.lead导语、主次按钮、.panel面板、.metric-grid指标网格、.card-row卡片行、.mini-card迷你卡、.field表单域、.status状态标签、.swatches色板等。几个值得注意的实现细节按钮.btn-primary使用background: var(--accent); color: var(--accent-on)hover 时background: var(--accent-hover)并translateY(-1px).btn-secondary使用var(--surface)底 var(--border)描边 var(--elev-ring)细环hover 时边框与文字转向 accent。焦点态统一用box-shadow: var(--focus-ring)。表单input最小高度 46pxfocus 时border-color: var(--accent)并叠加--focus-ring符合 DESIGN.md 的“strong focus-visible states”要求。状态点.status::before是一个 8px 的圆点background: var(--success)用--radius-pill保证正圆。响应式media (max-width: 860px)下 hero、lower、metric-grid、card-row 均塌缩为单列。需要留意的是manifest 中components.manifest.json的literals字段报告了colorExpressions: 3、pixelValues: 24、hardcodedFontFamilies: 4——即组件内仍有少量硬编码值。这正是 USAGE.md 中 Avoid 规则“避免在复制的:rootToken 块之外使用裸十六进制值”的审查对象评审者可以用这些指标定位需要收敛的硬编码点。八、Do 与 Avoid四条正向规则与四条红线USAGE.md 的核心约束浓缩为 Do / Avoid 两组规则本节逐条给出实操解读。8.1 Do应该做保持 schema Token 名称完全不变这样跨品牌切换cross-brand switching才可靠。从实现看tokens.css的 56 个 Token 名被design-tokens.json逐一索引、被components.html的 48 个选择器引用任何改名都会让派生产物与契约报表token-contract.report.json失配进而破坏 check-design-system-manifests.ts 等仓库检查脚本的通过条件。用--accent承担主操作、链接、焦点态以及一个明确的视觉焦点元素。这是“克制”的体现——整个页面只允许一个 focal element 使用 accent避免多主色互相争抢。优先复用components.manifest.json中的组件组而不是发明新控件。复用对象包括 buttons、inputs、cards、badges、links、typography、layout 七个可用组。把source/文件当作打包 fixture 回填backfill的审计证据。source/evidence.md明确声明本包“不声称抓取了上游品牌仓库或网站”只基于 OpenDesign 策展的 bundled fixture因此审查时证据边界清晰。8.2 Avoid不要做不要在用:rootToken 块之外使用裸十六进制值。所有颜色应经由 Token 引用这与literals.colorExpressions指标互为表里。不要脱离tokens.css单独重定义 Tailwind 或 design-token 值。这一点由 tailwind-v4.css 的实现直接佐证——它的theme块内每个映射都是--color-accent: var(--accent)形式的变量引用文件头注释明确写着“Derived from tokens.css. Keep tokens.css as the source of truth”派生自 tokens.css请保持 tokens.css 为唯一事实来源。不要声称存在原始上游来源证据本包基于策展的 bundled fixture来源声明以manifest.json的source字段为准type: bundled、origin: OpenDesign curated bundled fixture。不要添加components.html或DESIGN.md中不存在的组件配方。新增组件意味着扩展契约必须同步修改 fixture 与清单而不是悄悄外挂。九、Tailwind v4 映射Token 如何进入 Tailwind 生态tailwind-v4.css 展示了本包与 Tailwind v4 的集成方式通过theme指令把 CSS 变量重新绑定为 Tailwind 设计键。文件开头import tailwindcss与import ./tokens.css两行确立了“Token 源 → 主题映射”的依赖方向。映射约定值得注意颜色统一为--color-*键如--color-accent: var(--accent)、--color-fg: var(--fg)字体键--font-display/--font-body/--font-mono原样透传并额外增加--font-sans: var(--font-body)以对齐 Tailwind 的默认字体插槽间距被重命名为--spacing-*如--spacing-4: var(--space-4)section 间距与容器 gutter 也映射为--spacing-section-*与--spacing-container-*阴影键--shadow-flat/--shadow-ring/--shadow-raised/--shadow-focus-ring分别绑定--elev-flat/--elev-ring/--elev-raised/--focus-ring时长键--duration-fast/--duration-base绑定--motion-fast/--motion-base。因此在 Tailwind 项目中bg-accent、text-fg、shadow-raised、duration-fast等工具类都会回落到 Professional 的 Token 值上实现“一处改 Token、全域生效”。十、预览页与配套规范交付前的自检手段preview/目录提供了 colors、typography、spacing 三个独立预览页用于视觉抽查colors 页展示完整色板含.swatch系列typography 页验证字号阶梯与行高spacing 页核对间距节奏。评审流程建议为USAGE.md契约→DESIGN.md意图→tokens.cssToken→components.manifest.json/components.html组件→preview/视觉回归。此外manifest.json的craft.suggested推荐了两份配套规范craft/color.md 与 craft/accessibility-baseline.md。结合 DESIGN.md 的排版、对比度与可访问性要求建议在生成界面时让 Agent 同时携带这两份 craft 规范以保证颜色对比与焦点可达性符合基线。十一、小结design-systems/professional是 OpenDesign Design System 2.0 体系下一个结构完整、可审计、机器可读的包USAGE.md定义了契约与阅读顺序tokens.css是 56 个语义 Token 的唯一事实来源components.html与components.manifest.json提供组件级精确索引design-tokens.json与source/token-contract.report.json保证派生产物可溯源、评分 100、零悬空引用。对 Agent 而言正确的消费路径是先粘 Token、再查组件清单、最后对照 DESIGN.md 与 craft 规范生成对评审者而言则应以“Token 名不变、无裸色值、无未声明组件、无虚假来源声明”四条红线完成验收。这套机制让跨品牌切换如从 Professional 切到 minimal 或 clean可以依赖稳定的 schema Token 名称平滑进行正是 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创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考