OpenDesign MongoDB 设计系统指南：来源证据、令牌合约与森林暗色视觉体系全解析-平芜编程栈

AI 应用
人工智能
AI 技能
设计系统
媒体生成

【免费下载链接】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/mongodb/source/evidence.md 为骨架，围绕 OpenDesign 仓库中 MongoDB 设计系统包的「来源证据（Source Evidence）」与「令牌合约（Token Contract）」机制展开，并深度展开其背后的视觉规范（森林暗色画布、霓虹绿强调色、三段式字体层级）与 56 个设计令牌的具体取值。读完本文，你将掌握该设计系统包的文件分工、TOKEN_SCHEMA审计报告的解读方式，以及如何在编码代理（Agent）场景下直接引用这套 tokens 与组件配方生成 MongoDB 风格的真实界面。

一、来源证据：这套设计系统从哪里来

source/evidence.md 是 MongoDB 设计系统包的「证据文件」，它首先划定了严谨的来源边界：

This Design System 2.0 backfill is derived from the curated OpenDesign bundled fixture. It does not claim a fresh crawl of the original upstream brand repository or website.

这是一条重要的诚实声明：本设计系统是 OpenDesign内置精选夹具（bundled fixture）的回填（backfill）产物，并非对 MongoDB 上游品牌仓库或官网的重新抓取。因此在引用本包时，不应声称拥有「原始上游来源证据」。

包含的 Fixture 文件

evidence.md 明确列出本回填所依赖的三个来源文件：

文件	作用
design-systems/mongodb/DESIGN.md	视觉意图、约束与反模式（anti-patterns）的完整文字规范
design-systems/mongodb/tokens.css	56 个设计令牌（CSS 自定义属性）的结构化绑定
design-systems/mongodb/components.html	参考组件夹具，含完整选择器与状态

从包的 manifest.json 可以看到，该包的source.type为bundled，importMode为normalized，并建议在视觉审查时参考 craft 规范（color、accessibility-baseline）。这也印证了 evidence.md 的定位：它是整个包的审计入口，而非普通的设计说明文档。

二、令牌合约：TOKEN_SCHEMA 如何映射回 tokens.css

evidence.md 的核心技术声明只有两句，却定义了整条可审计的令牌流水线：

source/token-contract.report.jsonmaps every TOKEN_SCHEMA binding back to the committedtokens.cssdeclaration line.design-tokens.jsonandtailwind-v4.cssare derived outputs and should be regenerated from the report and token stylesheet rather than edited by hand.

即：source/token-contract.report.json把每一个TOKEN_SCHEMA绑定都映射回已提交的tokens.css声明行号；而design-tokens.json与tailwind-v4.css是衍生产物，应基于报告与令牌样式表重新生成，而不是手工编辑。

审计报告的结构与评分

打开 source/token-contract.report.json，可以看到这份机器生成的报告包含三个关键部分：

summary（汇总）：共 56 个令牌，其中 26 个为A1-identity（身份层）、18 个为A1-structure（结构层）、26 个为A2（衍生层）、4 个为B-slot（槽位层）；aliasTokens为 2（即--surface-warm: var(--surface)、--border-soft: var(--border)）；评分 100 分、等级excellent、recommendRebuild: false。
tokens 数组：每个令牌记录name、layer、value、confidence（全部为high）、reason（统一声明为 bundled 回填，未做上游重爬）、sources（精确到tokens.css:33这样的行号）、sourceName。
sourceScope：open-design-bundled-fixture，确认数据来源域。

{ "name": "--accent", "layer": "A1-identity", "value": "#00ed64", "confidence": "high", "sources": ["tokens.css:63"], "sourceName": "--accent" }

对比 source/tokens.source.json 可以发现，两者 token 集合完全一致——tokens.source.json是简化版的源映射（只含name、value、layer、source），而token-contract.report.json是带评分与置信度的完整审计报告。打开 tokens.css 第 63 行，确实可以看到--accent: #00ed64;的声明，即证据链「报告行号 → 样式表声明」可以直接验证。

为什么禁止手改衍生文件

design-tokens.json 的source字段明确写着"tokensCss": "tokens.css"与"tokenContractReport": "source/token-contract.report.json"，而 tailwind-v4.css 的第一行注释是：

/* Derived from tokens.css. Keep tokens.css as the source of truth. */

tailwind-v4.css通过@import "./tokens.css"与@theme { --color-bg: var(--bg); ... }把每个 CSS 变量映射为 Tailwind v4 主题令牌（如--color-accent、--font-display、--spacing-12、--shadow-raised、--duration-fast）。这意味着：唯一的手工编辑入口是tokens.css，其余文件都应从「报告 + 令牌样式表」重新生成，否则会产生漂移（drift）。这也正是 USAGE.md 中「避免在tokens.css之外直接定义 Tailwind 或设计令牌值」的原因。

三、从令牌到视觉：森林暗色的 MongoDB 设计语言

令牌值本身只是数据，真正定义「为什么是这些值」的是 DESIGN.md。它把 MongoDB 官网描述为「deep-forest-meets-terminal」体验：最深的青黑（teal-black）画布#001e2b承载数据库的密度与森林树冠的纵深，其上只有一个霓虹绿强调色#00ed64在脉冲发光——不是赛博朋克的冷霓虹，而是「在黑暗中生长的生物荧光绿」。

双模设计（Dual-Mode）

MongoDB 体系最显著的结构特征是双模世界：

暗色世界：#001e2b（Forest Black）背景 +#00ed64（MongoDB Green）强调，用于 hero 与特性区块；
亮色世界：白色背景 + 银青边框#b8c4c2，用于内容区块。

两个模式之间的切换产生强烈的戏剧化对比，且模式之间严禁混用（见下文 Do's and Don'ts）。

完整的色板角色表

DESIGN.md §2给出了每个色值的功能角色，与其在 tokens.css 中的绑定一一对应：

角色	色值	令牌	用途
Forest Black	`#001e2b`	`--bg`	主暗色画布（绝不使用纯黑）
MongoDB Green	`#00ed64`	`--accent`	唯一品牌强调色：高亮、下划线、渐变
Dark Green	`#00684a`	`--accent-hover`	按钮边框、亮色下的链接文本
Action Blue	`#006cfa`	—（组件内联）	次强调色：链接、交互高亮
Hover Blue	`#3860be`	—（组件内联）	所有链接 hover 的目标色
Teal Active	`#1eaedb`	—（组件内联）	按钮 hover 背景
Deep Teal	`#1c2d38`	`--surface`	暗色按钮背景、次级暗色面板
Teal Gray	`#3d4f58`	`--border`	暗色表面边框
Cool Gray	`#5c6c75`	`--meta`	暗色下的弱化文本
Silver Teal	`#b8c4c2`	`--muted`	亮色表面边框、分隔线、说明文本
Light Input	`#e8edeb`	`--fg-2`	暗色表面输入文本
Pure White	`#ffffff`	`--fg`	亮色区块背景、暗色上的按钮文本
Black	`#000000`	—	亮色表面上的正文文本

值得注意的实现细节：tokens.css 的注释指出，--accent-on是Forest Black 而非白色——因为霓虹绿足够亮，深色文字在绿色 CTA 上的对比度远高于白色文字；--accent-hover直接采用品牌自有的 muted Dark Green#00684a（来自 DESIGN.md §2），而不是合成压暗；--accent-active则用现代 CSS 的color-mix(in oklab, var(--accent-hover), black 12%)在 OKLab 色彩空间压暗 12%，保证色彩数学上的可复现。

阴影：把品牌色带进纵深体系

这是 MongoDB 体系中最独特的设计决策——主阴影使用青色调染色：

Forest Shadow：rgba(0, 30, 43, 0.12) 0px 26px 44px, rgba(0, 0, 0, 0.13) 0px 7px 13px（对应--elev-raised，见 tokens.css 第 152 行）；
Standard Shadow：rgba(0, 0, 0, 0.15) 0px 3px 20px；
Subtle Shadow：rgba(0, 0, 0, 0.1) 0px 2px 4px。

DESIGN.md §6将其定义为 Level 0–4 的完整纵深阶梯，且明确：即使阴影落在白色表面上，rgba(0,30,43,...)的青色调也让阴影属于 MongoDB 的色彩世界，而不是中性的黑色阴影。tokens.css还额外提供了--focus-ring: 0 0 0 3px color-mix(in oklab, var(--accent), transparent 70%)——键盘焦点环也是品牌强调色的 30% 透明度光晕，而不是通用蓝环。

四、排版：衬线权威 + 几何正文 + 等宽标签的三段式体系

DESIGN.md §3定义了三个字体家族的明确分工：

字体	职责
MongoDB Value Serif	巨型 hero 标题（96px），编辑级的权威感
Euclid Circular A	正文与 UI 文本，罕见的 300–700 宽字重跨度
Source Code Pro	代码与标签，超宽字距（1px–3px）的大写处理

tokens.css 第 83–85 行对应的字体栈为：

--font-display: "MongoDB Value Serif", "Times New Roman", Times, ui-serif, Georgia, serif; --font-body: "Euclid Circular A", "Akzidenz-Grotesk Std", -apple-system, "Segoe UI", Helvetica, Arial, sans-serif; --font-mono: "Source Code Pro", ui-monospace, "SF Mono", "JetBrains Mono", Menlo, Monaco, Consolas, monospace;

字号层级（Hierarchy）速查表

DESIGN.md §3的完整层级表（均已落入tokens.css的--text-*令牌）：

角色	字体	字号	字重	行高	字距
Display Hero	Value Serif	96px（`--text-4xl`）	400	1.20	normal
Display Secondary	Value Serif	64px（`--text-3xl`）	400	1.00	normal
Section Heading	Euclid Circular A	36px（`--text-2xl`）	500	1.33	normal
Sub-heading	Euclid Circular A	24px（`--text-xl`）	500	1.33	normal
Body Large	Euclid Circular A	20px（`--text-lg`）	400	1.60	normal
Body	Euclid Circular A	18px	400	1.33	normal
Body Light	Euclid Circular A	16px（`--text-base`）	300	1.50–2.00	normal
Nav / UI	Euclid Circular A	16px	500	1.00–1.88	0.16px
Code Label	Source Code Pro	14px（`--text-sm`）	400–500	1.14	1–2px，uppercase
Code Micro	Source Code Pro	9px	600	2.67	2.5px，uppercase

四个排版原则值得单独强调：衬线只服务于权威标题（96px 的衬线 hero 是数据库公司的编辑级宣言）；字重 300 是正文默认（轻盈的阅读体验与厚重的暗色背景形成对比）；宽字距大写等宽标签是「数据库字段名」式技术路标；300→400→500→700 四档字重比多数设计系统更宽，支撑更细粒度的层级。

五、组件样式与布局原则

按钮三态

DESIGN.md §4 定义了三种按钮（对应 components.manifest.json 中buttons组的.btn、.btn-primary、.btn-secondary）：

Primary Green（暗色表面）：背景#00684a，文字#000000，半径 100px 药丸形，边框1px solid #00684a，hover 缩放 1.1，active 缩放 0.85；
Dark Teal 按钮：背景#1c2d38，文字#5c6c75，hover 时背景变#1eaedb、文字转白并translateX(5px)；
Outlined（亮色表面）：透明背景，文字#001e2b，边框1px solid #b8c4c2，半径 4–8px。

卡片、表单与签名装饰

卡片：亮色模式白底 +1px solid #b8c4c2；暗色模式#001e2b/#1c2d38+1px solid #3d4f58；半径 16/24/48px 三档；阴影用 forest-tinted 主阴影（--elev-raised）；
表单：暗色输入文字#e8edeb，内边距12px 12px 12px 8px，输入框半径 4px（--radius-sm）；
霓虹绿强调下划线：0px 2px 2px 0px solid #00ed64（底部 + 右侧边框），用于特性标题与高亮文本，另有#006cfa蓝色变体——这是整个体系最具辨识度的装饰元素，也是 components.manifest.json 中.accent-underline类所对应的实现；
Source Code 标签系统：14px 大写 + 1–2px 字距，置于标题上方作为「章节类别标记」。

布局与间距

基础单位 8px，规模 1/4/7/8/10/12/14/15/16/18/20/24/32px（含 7/14/15/18 等奇数子层，用于精细的字型对齐，仅组件内部使用）；tokens.css的--space-*覆盖 4/8/12/16/20/24/32/48 的结构性节奏；
内容最大宽度 1200px（--container-max），桌面/平板/手机槽距分别为 24/16/12px；
圆角阶梯：1–2px（徽章）→ 4px（输入框）→ 8px（卡片/链接）→ 16px（标准卡）→ 20px（开关）→ 24px（大面板）→ 30–32px（图片容器）→ 48px（hero 卡）→ 100–999px（药丸按钮）→ 9999px（最大药丸）；
留白哲学：通过模式切换制造呼吸感——暗色 hero/特性区块用 80px+ 的慷慨纵向内边距（--section-y-desktop: 96px），而亮色内容区块更紧凑、卡片网格更密。

六、响应式与「该做/不该做」清单

断点策略

DESIGN.md §8定义六个断点：Mobile Small（<425px，紧致单列）→ Mobile（425–768px）→ Tablet（768–1024px，双列网格开始）→ Desktop（1024–1280px）→ Large Desktop（1280–1440px）→ Ultra-wide（>1440px，最大宽度与慷慨边距）。折叠策略上：hero 的 96px 衬线标题逐级缩到 64px；导航从横向 mega-menu 收进汉堡菜单；特性卡片从多列堆叠为单列；暗/亮模式在任何尺寸下都保持各自模式不变。

Do's and Don'ts（可直接用于 Agent 约束）

应当：

暗色区块用#001e2b（forest-black），绝不用纯黑；
MongoDB Green#00ed64要吝啬使用以获得最大电力冲击（每屏不超过 1–2 处，tokens.css 注释建议 ≤2 处/屏）；
MongoDB Value Serif只用于 hero/展示级标题，其余一律 Euclid Circular A；
Source Code Pro 大写 + 宽字距（1–3px）用于技术标签；
主卡片抬升用青色调阴影rgba(0,30,43,0.12)；
保持暗/亮双模的戏剧化对比；正文默认字重 300；主操作按钮用 100px 药丸半径。

禁止：

禁止用纯黑#000000作暗色背景；
禁止把霓虹绿铺在背景上——它只服务于文本、下划线和小面积高亮；
禁止使用标准灰色阴影，始终用青色调（rgba(0,30,43,...)）；
禁止把衬线字体用在正文；禁止收窄 Source Code Pro 标签的字距（宽字距本身就是身份）；
禁止在同一区块内混用暗/亮处理；禁止暖色（调色板严格为冷色：teal、green、blue）；
禁止遗漏绿色强调下划线——它是签名装饰元素。

七、Agent 提示词指南：让编码代理直接产出 MongoDB 风格

DESIGN.md §9 专门为 Agent 提供了可直接复制的提示词配方，结合本包文件可以按以下顺序落地（来自 USAGE.md 的 Read Order）：

先读 USAGE.md 理解包契约；
读 DESIGN.md 理解视觉意图与反模式；
把tokens.css粘贴进首个 artifact 的<style>块，再写组件 CSS；
用 components.manifest.json 做紧凑组件清单（含 9 个组件组：buttons/inputs/cards/badges/links/keyboard/icons/typography/layout，每个组都标注了tokenReferences），需要精确选择器或状态时打开 components.html；
需要视觉核验时打开 preview/colors.html、preview/typography.html、preview/spacing.html。

可直接使用的示例提示词（节选自 DESIGN.md §9）

Hero：「Create a hero on forest-black (#001e2b) background. Headline at 96px MongoDB Value Serif weight 400, line-height 1.20, white text with 'potential' highlighted in MongoDB Green (#00ed64). Subtitle at 18px Euclid Circular A weight 400. Green pill CTA (#00684a, 100px radius). Neon green gradient glow behind product screenshot.」
卡片：「Design a card on white background: 1px solid #b8c4c2 border, 16px radius, shadow rgba(0,30,43,0.12) 0px 26px 44px. Title at 24px Euclid Circular A weight 500. Body at 16px weight 300. Source Code Pro 14px uppercase label above title with 2px letter-spacing.」
技术标签：「Create technical label: Source Code Pro 14px, text-transform uppercase, letter-spacing 2px, weight 500, #00ed64 color on dark background.」
药丸按钮：「Design a pill button: #1c2d38 background, 1px solid #3d4f58 border, 100px radius, #5c6c75 text. Hover: #1eaedb background, white text, translateX(5px).」

迭代清单（Iteration Guide）

先做模式决策：暗色#001e2b用于 hero/特性，白色用于内容；
霓虹绿是电光——每个区块最多用一次以获得最大冲击；
衬线标题塑造编辑权威——绝不用于正文；
字重 300 的正文创造轻盈阅读体验——不要默认 400；
Source Code Pro 大写 + 宽字距是「数据库之声」；
青色调阴影让一切保持在 MongoDB 的色彩世界内。

同时遵循 USAGE.md 的硬约束：严格保留 schema 令牌名以保证跨品牌切换可靠；--accent用于主操作、链接、焦点态与一个清晰的焦点元素；优先复用components.manifest.json中的组件组而非自造新控件；source/目录仅作为 bundled fixture 回填的审计证据。

八、证据链自查：一份可验证的令牌清单

为方便你在仓库中逐条核对，这里给出 evidence.md 所指向证据链的完整落点（report 行号 → tokens.css 声明行）：

令牌	值	报告来源行	所属层
`--bg`	`#001e2b`	tokens.css:33	A1-identity
`--surface`	`#1c2d38`	tokens.css:34	A1-identity
`--fg`	`#ffffff`	tokens.css:42	A1-identity
`--accent`	`#00ed64`	tokens.css:63	A1-identity
`--accent-on`	`#001e2b`	tokens.css:64	A2
`--accent-hover`	`#00684a`	tokens.css:65	A2
`--font-display`	MongoDB Value Serif 栈	tokens.css:83	A1-identity
`--text-4xl`	96px	tokens.css:99	A1-structure
`--radius-pill`	9999px	tokens.css:142	A2
`--elev-raised`	forest-tinted 阴影	tokens.css:152	A2
`--focus-ring`	霓虹绿 30% 光晕	tokens.css:160	A2
`--container-max`	1200px	tokens.css:172	A1-structure

从token-contract.report.json的 summary 可以看到：56 个令牌全部declared、全部sourceBacked、26 个sourceBackedA1、26 个fallback、2 个别名，审计得分 100、等级excellent、recommendRebuild: false——这是一条闭环且零漂移的令牌供应链。

九、小结

source/evidence.md虽短，却是整个 MongoDB 设计系统包的「可信度锚点」：它用两段话划定了来源边界（bundled fixture 回填、非上游爬取）、列明了三个 fixture 文件、并定义了「报告映射行号 → 样式表声明」的审计契约与「tokens.css 为唯一真源、其余文件重新生成」的维护纪律。配合 DESIGN.md 的完整视觉规范、tokens.css 的 56 个令牌绑定、components.manifest.json 的组件组清单以及 USAGE.md 的落地顺序，这套「森林暗色 + 霓虹绿 + 衬线权威 + 青调阴影」的设计语言完全可以被编码代理直接消费，生成真实、可导出、风格统一的 MongoDB 风格界面。