OpenDesign Professional 设计系统包使用指南：Agent 与评审者的 2.0 契约解读

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 给出了五步阅读顺序，这是包作者对消费流程的明确设计，值得逐条展开：

1. 先读本文件（USAGE.md），理解包契约的整体约定，包括 Token 命名、组件来源、证据链语义。
2. 再读 DESIGN.md，获取视觉意图、约束与反模式（anti-patterns）。这是“为什么这样做”的依据。
3. 将tokens.css粘贴到第一个 artifact 的<style>块中，且在编写任何组件 CSS 之前完成。这保证所有组件样式都建立在同一套语义 Token 之上，而不是各自为政的魔法数字。
4. 使用components.manifest.json作为紧凑的组件清单；当需要精确选择器（selector）或状态（state）细节时，打开 components.html。
5. 需要视觉检查时查看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 style）：modern（现代）。
• 色彩立场（Color stance）：primary、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 还进一步给出了全套色彩语义：

使用建议：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: 760（h1）这类非整百字重，说明 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-identity（8 个）：品牌身份层，如--bg、--surface、--fg、--muted、--border、--accent、--font-display、--font-body；
• A1-structure（18 个）：结构层，如全部--text-*字号、行高、section 纵向间距、容器宽度与 gutter；
• B-slot（4 个）：槽位层，如--surface-warm、--fg-2、--meta、--border-soft；
• A2（26 个）：派生/补充层，如--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。它记录的关键统计包括：

• fixture：styleBlockCount: 1、selectorCount: 48、classCount: 26、elementCount: 19；
• tokens：56 个声明 Token 中 44 个被引用，7 个未使用（--accent-active、--danger、--elev-flat、--motion-base、--space-1、--space-12、--warn），undeclaredReferenced: []表示不存在“未声明却被引用”的悬空 Token——契约自洽；
• groups：把组件归为 8 个组，其中 6 个存在（buttons、inputs、cards、badges、links、typography、layout），2 个缺失（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-sm；
• inputs：.field、input、input:focus、label；
• cards：.card-row、.panel、.panel-head、.tile，引用--border、--elev-raised、--radius-lg、--surface；
• typography：.eyebrow、.lead、h1–h3，引用--fg-2、--text-4xl、--text-lg、--text-xl；
• layout：.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最小高度 46px，focus 时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.css（Token）→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