• 文档

本文基于开源仓库 awesome-design-md 中提取的 ClickHouse 设计系统分析文档，完整还原其 YAML 设计令牌体系（色彩、字体、间距、圆角、组件），并结合该仓库的设计文档规范，讲解如何让 AI 编码代理 / 设计代理读一份 Markdown 设计文档即可生成与 ClickHouse 官网视觉高度一致的界面。读完本文，你将掌握 ClickHouse「黑底 + 电光黄」品牌语言的完整令牌取值、组件规格、响应式断点与迭代守则，并可直接将这套规范复制进自己的项目驱动 AI 生成 UI。

一、背景：这份 DESIGN.md 是什么

本仓库（awesome-design-md）是一个DESIGN.md 精选集合：每一份DESIGN.md都是从真实网站提取出的纯文本设计系统文档，供 AI 代理（coding agents / design agents）读取并据此生成视觉一致的 UI。按仓库 README.md 的说明，其理念来自 Google Stitch 引入的 DESIGN.md 概念——一份普通的 Markdown 文件即可定义项目的视觉语言，无需 Figma 导出、JSON schema 或专门工具：

• AGENTS.md：告诉编码代理“如何构建项目”；
• DESIGN.md：告诉设计代理“项目应该如何呈现、如何感受”。

design-md/clickhouse/目录下即 ClickHouse 的完整设计分析文档，包含三大部分：YAML frontmatter（设计令牌）+ Overview（视觉基调）+ 分章节的规范细则（色彩、字体、布局、层级、形状、组件、Do's and Don'ts、响应式、迭代指南、已知缺口）。这是一份面向 AI 生成的“可直接执行”的设计系统，而非停留在描述层面的品牌手册。

二、文档结构与令牌引用语法

ClickHouse 的DESIGN.md采用「YAML frontmatter 定义令牌 + Markdown 正文阐述规则」的双层结构。文档内所有取值均通过{token.refs}语法引用 YAML 中定义的令牌，任何位置都不内联十六进制色值——这是本文件最重要的工程约束（见 Iteration Guide 第 3 条）。例如：

colors: primary: "#faff69"

正文中即写作：主色为{colors.primary}（#faff69）。组件定义同样引用令牌，如按钮的backgroundColor: "{colors.primary}"。这种引用方式确保改动一处令牌、全站同步，也便于 AI 代理直接展开成 CSS 变量或 Tailwind 配置。

三、视觉主题与品牌基调（Overview）

ClickHouse 的营销界面是数据库 / 数据平台品类中对比度最高的界面。核心基调可以浓缩为一句话：

近纯黑画布（{colors.canvas}— #0a0a0a）+ 电光黄（{colors.primary}— #faff69）作为唯一的品牌电压。

黄色的使用遵循「元素层面稀缺、色带层面慷慨」的节奏：单个元素上只用一点（主 CTA、统计数字、“GET STARTED” 徽章），但在整幅铺满的黄色 CTA 卡片上却毫不吝啬。白色粗体（weight 700）无衬线文字锚定正文的编辑感。

文档还给出了品类对比定位：Snowflake 用冷蓝色渐变、Databricks 用红 + 石板灰，而 ClickHouse 只押注一种电光黄来完成全部品牌工作。代码块、终端输出、产品 UI 片段都直接内嵌在深色{colors.surface-card}（#1a1a1a）卡片中，贯穿每一页。

字体层面：全部使用Inter，display 标题用 700 且负字距（-1 到 -2.5px），副标题与按钮 600，正文 400。系统没有衬线副声部——单一几何人文主义无衬线字体，通过缩放和字重构建层级。

关键特征清单（Key Characteristics）

• 近纯黑画布（{colors.canvas}— #0a0a0a）+ 白色文字；系统不存在浅色模式营销界面；
• 电光黄主色（{colors.primary}— #faff69）：用于主 CTA、大型统计数字（"2.8k+"、"74k+"）、整幅黄色 CTA 色带；
• Inter 字重 700（display）/ 600（副标题 + 按钮）/ 400（正文），无衬线对立声部；
• 深色表面卡片（{colors.surface-card}— #1a1a1a）承载特性卡、代码窗口与产品 mockup，卡片仅比画布略亮，色块对比微妙；
• 代码块在{colors.surface-card}内用JetBrains Mono渲染，SQL 语法高亮采用克制的蓝 / 黄 / 灰；
• 统计数字 = 黄色 + 无衬线 700 + 超大字号，承载可信度时刻（"779+"、"2.8k+"、"47k+" 社区 / 贡献者 / star 数）；
• 圆角层级化：{rounded.md}（8px）用于按钮，{rounded.lg}（12px）用于内容卡，除标签徽章外不使用 pill；
• 大区块之间使用{spacing.section}（96px）的章节节奏。

四、色彩系统（Colors）

品牌与强调色（Brand & Accent）

表面色（Surface）

文字色（Text）

语义 / 强调色（Semantic / Accent）

值得注意的是：语义色与产品 UI 相关，而营销界面几乎只使用黄 + 黑 + 灰阶。语义色体系独立存在，但不会侵入营销页面的品牌表达。

五、字体系统（Typography）

字体族（Font Family）

• Inter：承担一切——display、正文、导航、按钮、说明文字；
• JetBrains Mono：仅用于代码块；
• 回退栈：-apple-system, BlinkMacSystemFont, "Segoe UI", Roboto, sans-serif。

单一字体族是刻意决策：Inter 的 700 / 600 / 400 三档字重即可覆盖完整层级，无需衬线或 display 对立声部。Inter 在自信粗体下的几何人文主义性格，赋予 ClickHouse 一种“精密、工程化”的观感，与其性能优先的数据库定位吻合。

完整层级表（Hierarchy）

原则（Principles）

• Display 字重全尺寸保持700；
• 负字距（-1 到 -2.5px）是必备项——Inter 700 若无负字距会显得过宽、像 Apple 营销风；收紧的字距正是 ClickHouse“精密、工程化”观感的来源；
• 正文与标签保持 400 / 500 / 600 字重；层级靠「字号 + 字重」构建，而非字体族对比。

字体替代（Font Substitutes）

文档记录：Inter 是开源且被选定的字体。若获得授权，Söhne是接近的商业替代；Geist是另一款现代替代。除此之外不应更换字体族。

六、布局系统（Layout）

间距系统（Spacing System）

• 基础单位：4px；
• 令牌序列：{spacing.xxs}4px ·{spacing.xs}8px ·{spacing.sm}12px ·{spacing.md}16px ·{spacing.lg}24px ·{spacing.xl}32px ·{spacing.xxl}48px ·{spacing.section}96px；
• 区块间距：{spacing.section}（96px）用于主要编辑带之间；
• 卡片内边距：特性卡 / 定价档位用{spacing.xl}（32px）；代码窗口卡 / 活动卡用{spacing.lg}（24px）。

网格与容器（Grid & Container）

• 最大内容宽度：约1280px居中；
• 编辑区正文：单一 12 列网格；hero 常用7/5 分割（左 H1，右代码 mockup）；
• 特性卡网格：桌面 3 列、平板 2 列、移动端 1 列；
• 定价网格：桌面 3–4 列、移动端 1 列。

留白哲学（Whitespace Philosophy）

ClickHouse 使用致密、略微压缩的留白——符合开发者工具品牌的定位：宽松到足以编辑式阅读，紧凑到呈现“工程级”而非“营销柔”的感觉。区块节奏 96px 为标准，特性卡内边距维持 32px。

七、层级与深度（Elevation & Depth）

整个系统不使用投影（drop shadow）。深度来自黑画布与{colors.surface-card}（比画布略亮的色调）之间的对比——这种对比微妙而克制，更像“工程级暗面板”而非“浮起卡片”。

装饰性深度（Decorative Depth）

• 代码窗口卡自带内部产品 chrome——行号、语法高亮、底部状态栏——在不依赖外部阴影的情况下增加视觉密度；
• 黄底黑字的对比承担了 CTA 的主要“抬升”工作。

八、形状与圆角（Shapes）

圆角的层级化非常明确：按钮 8px、内容卡 12px、pill 仅限标签徽章——Do's and Don'ts 中会再次强调这一点。

九、组件体系（Components）

组件定义位于 YAML frontmatter 的components:段，每个组件通过backgroundColor/textColor/typography/rounded/padding/height等键引用令牌，构成可执行规格。

顶部导航（Top Navigation）

top-nav——黑色导航栏固定顶部：64px 高、{colors.canvas}背景。左侧 ClickHouse logo + 字标，中左为横向主菜单（Product, Use Cases, Pricing, Resources, Customers），右侧为 “Sign in” + “Get Started”{component.button-primary}（黄色）。菜单项使用{typography.nav-link}（Inter 14px / 500）。

按钮（Buttons）

卡片与容器（Cards & Containers）

输入与表单（Inputs & Forms）

标签 / 徽章（Tags / Badges）

标签页 / 筛选（Tab / Filter）

category-tab+category-tab-active——暗色页签导航：未激活为透明 + muted 文字；激活为 surface-card 背景 + on-dark 文字。内边距 8px × 14px、圆角{rounded.md}。

CTA / 页脚（CTA / Footer）

十、Do's and Don'ts（使用守则）

Do（应该做）

• 每页锚定黑画布，黄 + 黑组合就是品牌电压；
• 把{colors.primary}（黄）留给主 CTA、统计数字与整幅黄色 CTA 色带——元素级稀缺 + 色带级慷慨正是黄色力量的来源；
• 每个 display 标题使用 Inter 700 且字距 -1 到 -2.5px；
• 在{component.code-window-card}中展示真实 SQL 代码块——ClickHouse 是数据库，要展示查询本身，不要画营销插画式的查询；
• 用{component.stat-callout}数字建立可信度（社区规模、贡献者、性能基准）——黄色统计数字是签名式表达；
• 每个区块用{spacing.section}（96px）锚定垂直节奏。

Don't（不要做）

• 不要引入第二种品牌色——ClickHouse 是单色 + 黄；
• 不要将 display 字重加粗到 700 以上，也不要用 500 做标题——层级靠字号而非字重渐变；
• 不要在正文或大型表面填充中使用黄色（刻意黄色卡除外）；
• 不要在小型徽章之外使用圆角按钮 / 药丸——标准按钮圆角是 8px（md）；
• 不要连续两个区块重复同一种表面模式——黑画布 → 暗色特性卡 → 黄色 CTA 卡 → 黑画布 → 代码窗口卡；
• 不要用抽象插画替代 SQL 代码 mockup——代码本身就是营销电压；
• 不要添加系统未编码的 hover 样式。

十一、响应式行为（Responsive Behavior）

断点（Breakpoints）

触控目标（Touch Targets）

• {component.button-primary}最小 40 × 40px；
• {component.button-icon-circular}恰好 36 × 36——略低于 WCAG 44px 建议，视觉居中；
• {component.text-input}高度 40px。

折叠策略（Collapsing Strategy）

• 顶部导航在 < 768px 折叠为汉堡菜单；
• hero 7-5 网格移动端变单列；
• 特性卡网格减少列数而非缩放；
• 代码窗口卡保持字号，移动端在卡片内横向滚动；
• 定价卡 4 → 2 → 1 折叠，精选黄色档位保持视觉差异。

图片行为（Image Behavior）

• 暗色 mockup 内的代码块保持固定字号，移动端横向滚动而非换行；
• 单色客户 logo 条保持原生宽度，移动端换行排列。

十二、迭代指南（Iteration Guide）

文档为后续维护者规定了迭代规范，这也是 AI 代理扩展这套系统时应遵循的准则：

1. 一次只关注一个组件，引用其 YAML 键（如{component.code-window-card}、{component.pricing-tier-card-featured}）；
2. 既有组件的变体（-active、-disabled、-focused）作为独立条目存在；
3. 全程使用{token.refs}，永不内联 hex；
4. 永远不记录 hover——只记录默认态与 Active/Pressed 态；
5. display 标题保持 Inter 700 + 负字距，正文保持 Inter 400；
6. 黄 + 黑组合是品牌契约，不要用次要强调色软化它；
7. 不确定如何强调时：先放大 Inter 700，再考虑加色。

十三、已知缺口（Known Gaps）

原文档对自身的局限做了诚实记录，使用时应知晓以下边界：

• 电光黄 #faff69 是从截图中采样的，ClickHouse 官方可能发布略有差异的官方品牌色；
• Inter 字重轴超出 400 / 500 / 600 / 700 的取值未正式化——仅记录了观察到的静态字重；
• 动画与过渡时长（代码打字机效果、统计数字计数动画）不在范围内；
• 除{component.text-input-focused}外的表单校验状态未提取；
• 实际 ClickHouse Cloud 产品表面（查询控制台、监控仪表盘、表浏览器）与营销站点共享部分令牌，但增加了大量文档范围外的产品专属组件；
• 客户 logo 条的精确透明度 / 处理方式有所变化——muted 灰是近似值。

十四、如何在你的项目中落地这套设计语言

结合本仓库 README.md 的使用流程，落地步骤非常简单：

1. 将 design-md/clickhouse/DESIGN.md 复制到你的项目根目录；
2. 对 AI 编码代理或 Google Stitch 说一句“build me a page that looks like this”；
3. 代理即可基于 YAML 令牌生成视觉一致的 UI——包括黑画布底色、黄色 CTA、96px 章节节奏、代码窗口卡等全部规格。

如果你要基于这份文档手工实现（而非交给代理），核心执行顺序是：先落地colors段为 CSS 变量，再落地typography段为字体工具类（注意 Inter 700 的负字距），随后按rounded/spacing建立间距与圆角刻度，最后按components段逐个实现按钮、卡片、导航与页脚，并遵守第十节的 Do's and Don'ts 与第十一节的响应式断点。参考文件：clickhouse 设计分析文档、仓库总说明、贡献指南。

总而言之，ClickHouse 的这份 DESIGN.md 是“数据库品类最高对比度界面”的完整可执行规范：一套黑 + 黄令牌、一套 Inter 字重层级、一套克制无投影的表面系统，外加清晰的守则与断点。它既是一份品牌分析，更是一份开箱即用的 AI 生成 UI 设计输入。

• 文档