OpenDesign 中 ClaudeAnthropicDesign System 2.0 包使用指南包契约、Token 体系与 Agent 集成实践【免费下载链接】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/claude/包的 USAGE.md 为核心讲解该设计系统包的完整契约如何按阅读顺序消费包内文件、如何将 56 个语义 Token 落地到 artifact 中、如何在组件层面复用既有配方以及 Do / Avoid 纪律如何保证跨品牌切换的可靠性。读完本文你将掌握在 OpenDesign 的 Design System 流程中正确引用、审计和扩展 Claude 风格设计系统的完整方法并理解USAGE.md在包生成管线中的真实角色。一、包定位一份面向 Agent 与审查者的使用契约在 OpenDesign 的design-systems/目录中每个子目录都是一个可移植的设计系统包portable design-system package。根据 design-systems/README.md选择某个包后它的设计上下文会被组合进 Agent 的提示词prompt composition因此每个包都必须有稳定的机器可读结构design-systems/slug/ ├── manifest.json # 稳定发现元数据、来源声明、文件路径声明 ├── DESIGN.md # 面向 Agent 的规范化设计散文视觉意图 └── tokens.css # 规范化编译后的语义 Token 样式表claude包在此基础上进一步声明了更丰富的运行时输入文件。打开 manifest.json 可以看到完整清单usage→USAGE.md面向 Agent 的路由文档也就是本文的核心files.design/files.tokens/files.designTokens/files.tailwind/files.components分别指向 DESIGN.md、tokens.css、design-tokens.json、tailwind-v4.css、components.htmlcomponentsManifest→ components.manifest.json紧凑组件清单preview→preview/下的 colors.html、typography.html、spacing.html 三个视觉检查页sourceFiles→ source/evidence.md、source/tokens.source.json、source/token-contract.report.json导入器证据与 Token 契约报告。该包的source.type为bundledorigin为 OpenDesign curated bundled fixture。这一点非常关键source/evidence.md 明确说明这份 Design System 2.0 回填backfill基于仓库内精选的捆绑夹具生成并不声称对上游品牌仓库或网站做过新鲜爬取。因此在使用时不应引用上游原始来源证据这正是 USAGE.md 中 Avoid 纪律的来源。二、Read Order包内文件的消费顺序USAGE.md 第一部分定义了一套固定的阅读顺序Read Order目的是让 Agent 和审查者在有限上下文内高效理解包契约先读 USAGE.md 本身理解包契约的边界与约束再读 DESIGN.md获取视觉意图、约束与反模式anti-patterns将 tokens.css 粘贴进第一个 artifact 的style块再编写组件 CSS使用 components.manifest.json 作为紧凑组件清单当需要精确选择器或状态时打开 components.html需要视觉抽查时检查preview/页面。这套顺序的逻辑是“先契约、后意图、再实现、最后验证”Token 名称是跨品牌切换的稳定接口schema组件清单是复用边界预览页则承担视觉回归的职责。从源码看这个顺序并非 claude 包独有——import.ts 中的renderUsageMd为所有导入的设计系统生成结构相同的 USAGE.md其 Read Order 骨架DESIGN.md → tokens.css → components.manifest.json → preview → source正是这里手写版本的模板来源。三、Design HighlightsClaude 风格的四个支柱USAGE.md 用四个要点概括了该包的设计亮点全部在 tokens.css 与 DESIGN.md 中有精确的数值背书亮点承载 Token说明暖羊皮纸画布--bg: #f5f4ed唤起高级纸张而非屏幕的质感components.html的 reset 块用background: var(--bg)直接落地自定义 Anthropic 字体家族--font-display/--font-body/--font-monoSerif 用于标题、Sans 用于 UI、Mono 用于代码三者各司其职赤陶色品牌强调--accent: #c96442温暖、质朴、刻意“去科技感”是屏幕上唯一的彩色元素专属暖调中性色--fg/--muted/--meta等每一个灰色都带有黄棕底色全系统不存在冷蓝灰DESIGN.md将其概括为 “literary salon”文学沙龙气质版面节奏像杂志跨页、标题行高 1.10–1.30、正文行高 1.60读起来更像读一篇散文而不是扫一个产品页。组件夹具 components.html 的 hero 文案 Thoughtful conversations, made tangible. 以及三张 feature 卡片Parchment surface tokens / Terracotta discipline / Serif-sans hierarchy正是对这四支柱的可视化演练。四、Token 体系深度解析56 个语义 Token 的分层契约tokens.css是包的 Token 单一事实来源source of truth整个:root块定义了56 个 CSS 自定义属性。这些 Token 按语义分组建议在实际开发中按组消费4.1 表面Surface三级--bg: #f5f4ed; /* Parchment 羊皮纸 —— 页面主背景绝不用纯白 */ --surface: #faf9f5; /* Ivory 象牙白 —— 卡片、抬升容器 */ --surface-warm: #e8e6dc; /* Warm Sand 暖沙 —— 按钮背景、显著交互面 */层级关系为Parchment (bg) → Ivory (surface) → Warm Sand (surface-warm)。DESIGN.md反复强调纯白#ffffff只保留给特定按钮表面永远不要作为页面背景——暖奶油色本身就是 Claude 的人格。4.2 前景与文本Foreground四级--fg: #141413; /* Anthropic Near Black —— 主文本、深色主题表面 */ --fg-2: #3d3d3a; /* Dark Warm —— 深色文本链接、强调次级文本 */ --muted: #5e5d59; /* Olive Gray 橄榄灰 —— 次级正文 */ --meta: #87867f; /* Stone Gray 石灰 —— 三级文本、脚注、元数据 */注释中写着“Anthropic Near Black 是任何主要科技品牌中最暖的黑色”——它不是纯黑而是带轻微橄榄暖调的深色。4.3 强调色与语义色--accent: #c96442; /* Terracotta —— 唯一主品牌色 */ --accent-on: #faf9f5; /* accent 作为背景时的前景色 */ --accent-hover: color-mix(in oklab, var(--accent), black 8%); --accent-active: color-mix(in oklab, var(--accent), black 14%); --success: #17a34a; --warn: #eab308; --danger: #b53333; /* Error Crimson 暖红 */值得注意的实现细节hover/active 态没有手写新色值而是用color-mix(in oklab, ...)在 OKLab 色彩空间内混入 8%/14% 黑色派生保证始终与--accent同源。4.4 字体、字号与行高--font-display: Anthropic Serif, Georgia, Times New Roman, serif; --font-body: Anthropic Sans, Arial, system-ui, -apple-system, sans-serif; --font-mono: Anthropic Mono, ui-monospace, JetBrains Mono, Menlo, monospace; --text-xs: 10px; --text-sm: 14px; --text-base: 16px; --text-lg: 20px; --text-xl: 25px; --text-2xl: 32px; --text-3xl: 52px; --text-4xl: 64px; --leading-body: 1.6; --leading-tight: 1.1; --tracking-display: 0em;DESIGN.md§3 给出了完整的排版层次表Display/Hero 用 64px Serif 500 行高 1.10Section Heading 52px 行高 1.20正文 17px 行高 1.60Overline 用 10px 加 0.5px 字距。核心纪律是Serif 只用一个字重500——不用 bold、不用 light让所有标题像出自同一位作者。4.5 间距、圆角与层级--space-1: 4px; ... --space-12: 48px; /* 8px 基础单位 */ --radius-sm: 8px; --radius-md: 12px; --radius-lg: 16px; --radius-pill: 9999px; --elev-flat: none; --elev-ring: 0 0 0 1px var(--border); /* 标志性“光环”阴影 */ --elev-raised: rgba(0,0,0,0.05) 0px 4px 24px; /* Whisper 极柔投影 */ --focus-ring: 0 0 0 3px rgba(56,152,236,0.3); /* Focus Blue —— 全系统唯一冷色 */阴影哲学在DESIGN.md§6 有精辟总结Claude 用暖调 ring shadow0px 0px 0px 1px代替传统投影这是一个“假装成边框的阴影或者说技术上算是阴影的边框”真正需要投影时也只用 0.05 透明度、24px 模糊的极柔效果。--focus-ring中的 Focus Blue#3898ec是整个系统唯一的冷色且只服务于键盘焦点的无障碍需求。4.6 Token 契约的机器可读证据Token 体系并非散落的 CSS而是被两套机器可读产物锁定的design-tokens.json契约od-design-tokens/v1/TOKEN_SCHEMA56 个 token 全部 source-backed其中 A1-identity 8 个、A1-structure 18 个、A2 26 个、B-slot 4 个契约评分 100、评级excellent、recommendRebuild: false且0 个别名 token、0 个未声明引用——即 components.html 中用到的一切变量都能在 tokens.css 中找到声明source/token-contract.report.json为每个 token 记录声明行号如tokens.css:24是契约的审计底账。source/evidence.md 同时提醒design-tokens.json与tailwind-v4.css是派生产物应由报告与 Token 样式表重新生成不应手工编辑。五、组件清单复用优先于发明components.manifest.json 是紧凑组件清单schemaVersion 1。它统计出夹具的规模50 个选择器、25 个类、25 个元素、1 个样式块并声明“每个可见值都通过 var(--*) 来自 tokens.css”。清单按 8 个组件组组织每组带present状态、选择器列表和tokenReferences该组实际引用的 Token组标签代表选择器关键 Token 引用buttons按钮与 CTA.btn,.btn-primary,.btn-secondary--accent-hover,--surface-warm,--radius-sm,--focus-ringinputs表单字段.field input,.field input:focus-visible--border-soft,--radius-md,--metacards卡片面板.card--border,--elev-raised,--surfacebadges徽章状态.badge,.badge-dot,.badge-success--successlinks链接a,a:hover--accentkeyboard键盘提示kbd—icons图标槽.icon—typography排版工具类.eyebrow,.lead,.body-muted,h1-h3--font-display,--text-2xl,--leading-tightlayout布局原语.container,.stack-3/4/6,.features-grid--container-max,--space-4同时清单暴露了 8 个已声明但未使用unusedDeclared的 token--danger、--elev-flat、--elev-ring、--motion-base、--radius-lg、--space-1、--text-3xl、--warn它们是留给未来扩展的保留槽位。当需要精确选择器或状态时应打开 components.html 查看完整实现。该文件包含三块可复用的真实场景hero 区.btn-primary赤陶主 CTA .btn-secondary暖沙次级按钮 kbd快捷键 .badge-success状态徽章、features 卡片网格Ivory 表面 1px Border Cream Whisper 阴影、表单区:focus-visible用 Focus Blue 的输入框。例如主按钮的完整配方.btn-primary { background: var(--accent); color: var(--accent-on); box-shadow: var(--accent) 0px 0px 0px 0px, var(--accent) 0px 0px 0px 1px; } .btn-primary:hover { background: var(--accent-hover); } .btn-primary:active { background: var(--accent-active); } .btn:focus-visible { outline: none; box-shadow: var(--focus-ring); }六、Tailwind v4 映射同一 Token 契约的第二出口tailwind-v4.css 是派生产物头部注释明确要求“以 tokens.css 为事实来源”。它通过theme把 56 个语义 token 映射为 Tailwind 工具类例如import tailwindcss; import ./tokens.css; theme { --color-bg: var(--bg); --color-accent: var(--accent); --color-surface-warm: var(--surface-warm); --font-display: var(--font-display); --text-4xl: var(--text-4xl); --shadow-ring: var(--elev-ring); --shadow-focus-ring: var(--focus-ring); --spacing-section-desktop: var(--section-y-desktop); --container-max: var(--container-max); }命名空间上做了规整颜色进--color-*、字体进--font-*、字号进--text-*、间距进--spacing-*、阴影进--shadow-*、时长进--duration-*。这意味着你可以写bg-bg、text-muted、font-display、shadow-ring等工具类同时所有值仍然解析自同一份tokens.css。七、Do / Avoid 纪律保证跨品牌切换可靠性的四条铁律USAGE.md 的最后两部分定义了使用与禁止事项它们共同服务于“schema token 名称稳定 → 跨品牌切换可靠”这一核心目标。Do应当精确保留 schema token 名称——这是跨品牌cross-brand切换可靠性的基础名称一旦漂移design-tokens.json契约的undeclaredReferenced检查就会失败使用--accent承担主操作、链接、焦点状态且全页只保留一个清晰焦点元素——赤陶色是最高信号颜色用得越少越有力优先复用components.manifest.json中的组件组而不是发明新控件——组件组就是复用边界把source/文件当作捆绑夹具回填的审计证据——evidence.md与token-contract.report.json用于追溯每个值的来源。Avoid禁止不要在复制的:roottoken 块之外使用裸 hex 色值——所有颜色必须走 token不要独立于tokens.css重新定义 Tailwind 或 design-token 值——tailwind-v4.css只做引用映射不改值不要声称拥有上游原始来源证据——本包基于精选的捆绑夹具bundled fixturemanifest.json的source.type: bundled与source/evidence.md已明确这一点不要添加components.html或DESIGN.md中未体现的新组件配方——超出夹具范围的组件会破坏清单的审计一致性。配套地DESIGN.md§7 给出了更细的设计级 Dos and Donts不用冷蓝灰、Serif 字重不超过 500、圆角不小于 6px、不用重投影、不用纯白作页面背景、不用几何/科技风插画、正文行高不低于 1.40、mono 字体只用于代码、标题禁止混入 sans。八、Agent Prompt 指南把规范翻译成指令DESIGN.md§9 提供了可直接喂给 Agent 的提示词模板建议与 Do/Avoid 配合使用。快速色值速查品牌 CTATerracotta Brand (#c96442)→--accent页面背景Parchment (#f5f4ed)→--bg卡片表面Ivory (#faf9f5)→--surface主文本Anthropic Near Black (#141413)→--fg次级文本Olive Gray (#5e5d59)→--muted三级文本Stone Gray (#87867f)→--meta浅色边框Border Cream (#f0eee6)→--border深色表面Dark Surface (#30302e)→--elev-raised场景下的容器一个完整的组件提示词示例Create a hero section on Parchment (#f5f4ed) with a headline at 64px Anthropic Serif weight 500, line-height 1.10. Use Anthropic Near Black (#141413) text. Add a subtitle in Olive Gray (#5e5d59) at 20px Anthropic Sans with 1.60 line-height. Place a Terracotta Brand (#c96442) CTA button with Ivory text, 12px radius.迭代指南归纳为七条一次只聚焦一个组件引用具体颜色名而非“灰色”始终指定暖调变体明确说明 Serif/Sans 分工阴影只说 ring shadow (0 0 0 1px) 或 whisper shadow绝不说泛化的 drop shadow指定暖背景插画保持有机、手绘感。九、源码级佐证USAGE.md 在包管线中的真实角色USAGE.md不是孤立的手写文档而是 OpenDesign 设计系统导入管线的标准产物。在 apps/daemon/src/design-systems/import.ts 中USAGE.md与DESIGN.md、tokens.css、design-tokens.json、tailwind-v4.css、components.html、components.manifest.json、manifest.json一起构成每个导入包的固定文件集第 162 行调用renderUsageMd(displayName, scan)生成它。renderUsageMdimport.ts会基于ProjectScan自动填充 Design Highlights包描述、检测到的技术栈、CSS 自定义属性数量、代表性源组件并生成统一的 Read Order、Do / Avoid 骨架。它的 Do 列表同样强调保留源项目的语义角色、以tokens.css为规范化契约、通过source/token-contract.report.json甄别 fallback 权重较高的导入Avoid 列表则提醒不要盲目把源片段贴进生产代码、不要把 fallback 值当作高置信度来源证据、不要在生成产物中重命名标准 token。而在运行时侧apps/daemon/src/design-systems/index.ts 把usageMd作为包的“可选 Agent 路由文档”读取默认文件名即USAGE.md说明这份文档会在运行时被加载并参与提示词组合。换言之你读到的 USAGE.md 既是给人看的指南也是被 daemon 消费的包契约的一部分。十、预览与审计工作流包的preview/目录提供三个轻量视觉检查页全部通过link relstylesheet href../tokens.css引用真实 tokenpreview/colors.html颜色抽查preview/typography.html排版抽查其文案明确说明“预览只使用 schema token以便审查者确认包在 OpenDesign artifacts 间可移植”preview/spacing.html间距抽查。推荐审计路径先用components.manifest.json核对组件组与 token 引用 → 再对design-tokens.json的score/grade与undeclaredReferenced为空确认契约健康 → 最后打开 preview 页面做视觉回归。全部文件只读查看即可无需运行构建。结语ClaudeAnthropicDesign System 包是 OpenDesign Design System 2.0 体系的一个典型样本DESIGN.md定义“为什么”tokens.css定义“是什么值”components.html定义“怎么组合”components.manifest.json与design-tokens.json定义“契约是否健康”而USAGE.md则把这一切编排成 Agent 可执行、审查者可验证的消费顺序。遵循 Read Order、严守 Token 命名、复用组件组、以source/为审计证据——这套方法不仅适用于 claude 包也适用于design-systems/下任何遵循同构型的包。【免费下载链接】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），仅供参考
