OpenDesign 中的 Cohere 设计系统包使用指南：Design System 2.0 契约、Token 与组件落地-迪斯科星球

OpenDesign 中的 Cohere 设计系统包使用指南：Design System 2.0 契约、Token 与组件落地

【免费下载链接】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

本指南以 design-systems/cohere/USAGE.md 为骨架，系统讲解 OpenDesign 仓库中「Cohere」设计系统包（Design System 2.0）的完整使用契约：从文件阅读顺序、包内文件职责，到tokens.css的 Token 绑定、components.manifest.json的组件清单，以及面向 Agent 与代码评审者的 Do / Avoid 约束。读完本文，你将掌握如何在 OpenDesign 中正确引用该品牌包生成符合 Cohere 视觉语言的 artifact，并理解其背后的 schema 校验与契约机制。

一、包定位与阅读顺序：先读 USAGE，再动手

design-systems/cohere/USAGE.md是整个 Cohere 包面向「OpenDesign agents and reviewers」的入口文档。它不重复视觉细节，而是约定一套固定的阅读与消费顺序，保证任何 Agent 拿到该包时都能以同一套心智模型工作：

先读USAGE.md，理解包契约（package contract）——即本指南所依据的文件。
再读DESIGN.md，获取视觉意图（visual intent）、约束（constraints）与反模式（anti-patterns）。该文件位于 design-systems/cohere/DESIGN.md，正文以「Design System Inspired by Cohere」为题，类别为 AI & LLM，完整描述了主题氛围、调色板、排版层级、组件样式、布局、响应式行为以及 Agent Prompt Guide。
把tokens.css粘贴进第一个 artifact 的<style>块，之后再写组件 CSS——Token 是唯一事实来源。
使用 design-systems/cohere/components.manifest.json 作为紧凑型组件清单；当需要精确选择器（exact selectors）或状态（states）时，打开 design-systems/cohere/components.html。
需要视觉抽查（visual sanity check）时，翻阅 preview/ 下的静态预览页。

从包清单 design-systems/cohere/manifest.json 可以看到，该包遵循od-design-system-project/v1schema，usage字段指向USAGE.md，importMode为normalized，并声明了craft建议项（color、accessibility-baseline）与三个 preview 页面（preview/colors.html、preview/typography.html、preview/spacing.html）。

二、设计亮点：Cohere 视觉签名的四个支柱

USAGE.md用四条要点概括 Cohere 品牌包的视觉基因，它们在DESIGN.md中有完整展开：

明亮白色画布 + 冷灰边框：页面主体为 Pure White（#ffffff），边框使用 Border Cool（#d9d9dd）与 Lightest Gray（#f2f2f2），营造企业级清爽感。
22px 签名圆角：这是最独特的 "Cohere card" 圆润度。DESIGN.md强调"THE Cohere radius"，所有主卡片、主图片与主容器都必须使用 22px，而不是常见的 8–12px。
双字体系统：CohereText（display 衬线体，用于大标题）与 Unica77（正文无衬线体，Swiss 几何风格），形成"权威感与工程清晰度并存"的品牌人格。
企业级色彩克制：整体几乎只有黑、白、冷灰，配合极少的紫蓝强调色（Interaction Blue#1863dc只出现在 hover/focus 交互态）。

DESIGN.md还补充了深紫 hero 全宽色带、ghost/透明按钮 hover 变蓝、CohereMono 大写代码标签等特征。该品牌包的 source/evidence.md 明确说明：此包基于 OpenDesign 策展的 bundled fixture 派生，不主张来自上游品牌仓库或官网的全新爬取证据——USAGE.md的 Avoid 列表也要求不要声称原始上游源码证据。

三、Token 契约：tokens.css 是唯一事实来源

USAGE.md的 Do 列表第一条就是「Preserve the schema token names exactly so cross-brand switching stays reliable」，即精确保留 schema token 名称，以保证跨品牌切换的可靠性。承载这一契约的是 design-systems/cohere/tokens.css，其:root块按语义分区分组，共 56 个 Token：

Surface：--bg: #ffffff、--surface: #fafafa（Snow）、--surface-warm: var(--surface)（无暖色层，调色板严格冷调）。
Foreground：--fg: #000000（Cohere Black）、--fg-2: #212121（Near Black）、--muted: #93939f（Muted Slate）、--meta: var(--muted)。
Border：--border: #d9d9dd（Border Cool）、--border-soft: #f2f2f2（Lightest Gray）。
Accent：--accent: #1863dc（Interaction Blue，仅用于 hover/focus，从不作为 ambient 常驻色）、--accent-on: #ffffff、--accent-hover: color-mix(in oklab, var(--accent), black 8%)、--accent-active: color-mix(in oklab, var(--accent), black 16%)。
Semantic 状态色：--success: #16a34a、--warn: #eab308、--danger: #ef4444——保留给状态而非装饰。
Typography：--font-display（CohereText → Space Grotesk → Inter → system-ui）、--font-body（Unica77 → Inter → Arial）、--font-mono（CohereMono → JetBrains Mono）；字号阶梯--text-xs: 12px到--text-4xl: 72px；--leading-tight: 1.0、--tracking-display: -0.02em（≈ 72px 时的 -1.44px 负字距）。
Spacing：8px 基准单位，--space-1: 4px至--space-12: 48px；区块节奏--section-y-desktop: 60px/--section-y-tablet: 48px/--section-y-phone: 32px。
Radius：--radius-sm: 8px（对话框、导航）、--radius-md: 22px（主签名圆角）、--radius-lg: 22px（大型容器同款）、--radius-pill: 9999px（按钮与状态标签）。
Elevation / Focus / Motion / Layout：--elev-flat: none、--elev-ring（1px 细描边）、--elev-raised（极轻 hover 阴影）、--focus-ring: 0 0 0 2px var(--accent)、--motion-fast: 150ms、--motion-base: 200ms、--ease-standard: cubic-bezier(0.2, 0, 0, 1)、--container-max: 1440px及桌面/平板/手机三档 gutter（32/24/16px）。

USAGE.md的 Avoid 列表要求不要使用复制的:rootToken 块之外的原始 hex 值，也不要脱离tokens.css独立重定义 Tailwind 或 design-token 值。这正是 Token 契约的意义：OpenDesign 用TOKEN_SCHEMA约束每个 Token 的名称、类型、层级与来源。

Token 的机器可验证证据

design-systems/cohere/design-tokens.json 是od-design-tokens/v1格式的派生产物，其摘要显示：56 个 Token 全部有源码支撑（sourceBackedTokens: 56），层级分布为 A1-identity（8）、A1-structure（18）、A2（26）、B-slot（4），契约得分 100、评级 excellent。其中 B-slot 仅 4 个（--surface-warm、--fg-2、--meta以及 alias），其余为 A1/A2 原始定义。

design-systems/cohere/source/token-contract.report.json 把每一个 TOKEN_SCHEMA 绑定映射回tokens.css的具体声明行（例如--bg→tokens.css:21、--radius-md→tokens.css:98）。按照 source/evidence.md 的说明，design-tokens.json与tailwind-v4.css均为派生输出，应由报告与 Token 样式表重新生成，而不是手工编辑。

Tailwind v4 桥接层

若你在 artifact 中使用 Tailwind v4，design-systems/cohere/tailwind-v4.css 提供了标准的桥接方式：文件头明确标注 "Derived from tokens.css. Keep tokens.css as the source of truth."，随后@import "tailwindcss"、@import "./tokens.css"，并在@theme块内把 Token 逐一映射为 Tailwind 命名空间（--color-bg: var(--bg)、--color-accent: var(--accent)、--radius-md: var(--radius-md)、--shadow-focus-ring: var(--focus-ring)等）。这样既能在 Tailwind 工具类中使用bg-bg、text-muted、rounded-md等，又保证值仍由tokens.css单一来源驱动，与 Avoid 约束一致。

四、组件清单：components.manifest.json 与 components.html

USAGE.md推荐优先使用components.manifest.json作为紧凑清单，仅在需要精确选择器或状态时打开components.html。清单本身是一份可重建的缓存（manifest.json 中的componentsManifest字段），由components.html加tokens.css派生而来，包含：

fixture 元数据：1 个<style>块、48 个选择器、25 个 class、25 个元素。
Token 使用审计：declared（56 个已声明 Token）、referenced（组件实际引用的 Token）、unusedDeclared（已声明但未在 fixture 中引用的，如--danger、--warn、--elev-*、--radius-lg等）、undeclaredReferenced（空数组——说明组件没有引用任何未声明的 Token，契约干净）。
组件分组（groups）：buttons、inputs、cards、badges、links、keyboard、icons、typography、layout 共 9 组，每组列出选择器、class、元素与所引用的 Token。例如 buttons 组引用--accent、--fg-2、--focus-ring；badges 组引用--muted、--radius-pill、--space-2、--text-xs；layout 组引用--container-max、--container-gutter-*、--space-3、--space-6等。
选择器与类名全集：如.btn/.btn-primary/.btn-primary:hover/.btn-secondary/.btn:focus-visible、.card、.field、.badge、.eyebrow、.lead、.hero-grid、.features-grid、.stack-3/4/6等。

对应地，design-systems/cohere/components.html 是独立的组件 fixture 页面：其<style>块内联了与tokens.css一致的:rootToken 定义，再按 48 个选择器组织真实可用的组件样式。当需要确认某个状态（如:focus-visible焦点环、hover 变蓝）或精确选择器写法时，直接查这个文件比猜更可靠。

组合预览页

需要视觉抽查时，preview/ 提供三个独立静态页面：colors.html（颜色）、typography.html（排版）、spacing.html（间距），对应 manifest.json 中 preview 数组声明的三个 role。它们是纯静态 HTML，可直接在浏览器打开。

五、排版与色彩实操：DESIGN.md 的关键数值

虽然USAGE.md不重复视觉细节，但作为包契约的一部分，引用DESIGN.md中的关键规格能让 Token 使用更准确（DESIGN.md的 Agent Prompt Guide 一节也提供了可直接复用的 prompt 片段）：

显示层级：Hero 用 CohereText 72px / weight 400 / line-height 1.0 / letter-spacing -1.44px；Display Secondary 60px（-1.2px）；Section Heading 48px；Sub-heading 32px（-0.32px）；Feature Title 24px。
正文层级：Body Large 18px、Body/Button 16px（line-height 1.5）、Button Medium 14px weight 500、Caption 14px、Uppercase Label 14px（letter-spacing 0.28px）、Small 12px、Code Micro 8px。
按钮三态：Ghost（透明底、Cohere Black 文字，hover 时文字转 Interaction Blue 且 opacity 0.8，focus 为 2px 实线 Interaction Blue outline）、Dark Solid（深底白字 CTA）、Outlined（描边次级操作）。
深度与阴影哲学：Cohere 几乎无阴影，层级靠背景色对比（白色卡片置于紫色 band 之上）与冷灰边框传达，--elev-raised也只是极轻的 6% 黑色阴影。
间距与断点：8px 基准单位，卡片内边距约 24–32px，区块间距 56–60px（且不得低于 40px）；响应式断点从 <425px 到 1440–2560px，数据集中检测到 26 个断点，属于颗粒度最细的一档。

六、Do 与 Avoid：Agent 与评审者的验收清单

USAGE.md用 Do / Avoid 两段给出可直接照做的行为准则，这是代码评审（review）时的主要依据：

Do（应做）

精确保留 schema token 名称，确保跨品牌切换（cross-brand switching）时映射稳定。
使用--accent承担主操作、链接、焦点状态，以及页面上唯一明确的焦点元素（one clear focal element）。
优先复用 components.manifest.json 中的组件分组，而不是自行发明新控件。
把source/下的文件当作审计证据，用于 bundled fixture 回填（backfill）的核验。

Avoid（应避免）

避免在复制的:rootToken 块之外使用原始 hex 值——一切颜色必须走 Token。
避免独立于tokens.css重定义 Tailwind 或 design-token 值——单一事实来源不可破坏。
避免声称原始上游源码证据——本包基于 OpenDesign 策展的 bundled fixture，source/evidence.md 对此有明确声明。
避免添加components.html或DESIGN.md未覆盖的新组件配方——新增组件必须能追溯到现有 fixture 或设计文档。

DESIGN.md的 Do's and Don'ts 进一步补充了视觉层面的红线：主卡片圆角只用 22px、不引入暖色、不用重阴影、正文不用 700+ 字重、紫色只用于全宽 section 而不用作卡片表面色、区块间距不低于 40px、按钮默认即 ghost 态不加装饰。

七、包契约的底层机制：schema 与守护脚本

Cohere 包之所以能被 Agent 与 LLM 可靠消费，根因在于 OpenDesign 用 schema 与守护脚本把它"钉死"为标准形状。仓库 design-systems/_schema/AGENTS.md 说明：每个 tokenized brand 必须满足TOKEN_SCHEMA契约（规范运行时副本在 packages/contracts 下），项目清单形状由manifest.schema.ts约束，任何已存在的design-systems/<brand>/manifest.json都由 scripts/check-design-system-manifests.ts 校验。Cohere 包的manifest.json完全符合该约定（schemaVersionod-design-system-project/v1，固定文件名DESIGN.md/tokens.css/components.html/USAGE.md/components.manifest.json/source/等）。

从manifest.json的source字段（type:bundled，origin: OpenDesign curated bundled fixture）可以看出，该包属于"策展打包"而非实时爬取，这与 USAGE 中"不得声称原始上游证据"的约束互为印证。此外，manifest 声明importMode: normalized，说明导入时做了规范化处理；craft.applies为空、craft.suggested建议color与accessibility-baseline两条 craft 规范，供生成阶段的后续约束参考。

八、多语言与其余配套文件

除DESIGN.md英文版外，该包还提供 15 种本地化设计说明（DESIGN-zh.md、DESIGN-ja.md、DESIGN-ko.md、DESIGN-ar.md、DESIGN-de.md、DESIGN-es.md、DESIGN-fr.md、DESIGN-id.md、DESIGN-it.md、DESIGN-nl.md、DESIGN-pl.md、DESIGN-pt-br.md、DESIGN-ru.md、DESIGN-tr.md、DESIGN-uk.md、DESIGN-vi.md、DESIGN-zh-tw.md），便于不同语言场景下的 Agent 与评审者阅读。source/目录内还包含tokens.source.json（导入时的原始 Token 快照），与token-contract.report.json、evidence.md共同构成可审计的溯源链。

结语

Cohere 是 OpenDesign Design System 2.0 体系中具有鲜明签名（22px 圆角、双字体、冷调克制的色彩）的品牌包。使用它的正确姿势是：先读 USAGE.md 理解契约，再读 DESIGN.md 把握视觉意图，将 tokens.css 作为唯一 Token 来源，以 components.manifest.json 与 components.html 为准复用组件，并用 preview/ 做最终视觉核验。严格遵循 Do / Avoid 清单，就能保证产物既符合 Cohere 品牌语言，又满足 OpenDesign 的 schema 契约与跨品牌切换的稳定性要求。

创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考

企业官网建设流程全解析