我见过数十本品牌指南手册。美观的 PDF 文档，精心设计的排版，精选的配色方案，鼓舞人心的情绪板。但几乎每一本在交付后三个月内都会被忽视。

问题不在于团队不关心品牌一致性。问题在于大多数品牌指南是为董事会演讲而创建的，而不是为每天真正实施品牌的人——上午 9 点打开 Figma 的设计师和午夜写 CSS 的开发者。如果你的品牌指南存在于一份 47 页的 PDF 中，没人能搜索、复制或将其集成到工作流中，那你建造的是一个博物馆展品，而不是一个工具。

我将带你了解如何创建一本真正被使用的品牌指南。不是理论上的那种。而是开发者能在几秒内获取设计令牌，设计师无需询问 Slack 就能检查间距规则，新团队成员在第一周就能交付品牌一致的工作的那种。

目录

如何创建设计师和开发者会使用的品牌指南

为什么大多数品牌指南失败

让我们坦诚地说出失败的原因。我继承过来自机构、内部团队和自由职业者的品牌指南，同样的问题不断出现。

它们是动态世界中的静态文档

PDF 在 2010 年很有意义。在 2026 年，你的品牌存在于网络应用、移动应用、电子邮件模板、社交媒体、文档网站，以及可能在品牌指南编写时不存在的一些平台上。静态文档跟不上。

当你的品牌指南是 PDF 时，每次更新都意味着重新导出、重新上传，并希望每个人都下载新版本。剧透：他们不会的。

它们用设计师的语言而不是开发者的语言

大多数品牌指南由品牌设计师或机构创建。他们会指定主要蓝色是"Pantone 2935 C"，但不会提到它在十六进制中是 #0057B8，在 RGB 中是 rgb(0, 87, 184)，或在 HSL 中是 hsl(212, 100%, 36%)。他们会显示一个圆角按钮，但不会告诉你 border-radius 是 8px 或悬停状态变暗 10%。

开发者需要实现细节，而不仅仅是视觉参考。

它们回答错误的问题

一本花费六页讨论徽标清晰空间的品牌指南，但不解决徽标出现在移动导航栏中的深色背景上时该怎么办的情况，其优先级是错误的。最好的品牌指南回答人们日常实际提出的问题。

没有单一的事实来源

我参与过这样的项目：Figma 库中的品牌色与品牌指南不匹配，品牌指南与生产环境中的 CSS 变量也不匹配。当没有明确的规范源时，每个团队都会开发自己的解释。这就是你最终得到五种不同阴影的"品牌蓝"的方式。

功能性品牌指南应包含什么

这是我会包含的内容，按照谁需要它及其紧迫程度组织：

章节 主要受众 更新频率 格式优先级
品牌基础（使命、价值观、个性） 全体 很少 书面叙述
徽标使用 设计师、市场营销 偶尔 视觉示例 + 下载
配色系统 设计师 + 开发者 偶尔 令牌 + 视觉样本
排版 设计师 + 开发者 偶尔 令牌 + 样本
间距 & 布局 开发者 + 设计师 偶尔 令牌 + 网格规范
图标 设计师 + 开发者 频繁 库 + 使用规则
组件模式 开发者 + 设计师 频繁 实时示例 + 代码
语音 & 语调 文案、市场营销、客服 很少 书面指南 + 示例
摄影 & 插图 设计师、市场营销 偶尔 风格示例 + 做/不做
动作 & 动画 开发者 + 设计师 偶尔 规范 + 视频示例

注意，"频繁更新"的章节需要支持轻松更新的格式。这是关于下一部分的提示。

格式问题：PDF vs. Web vs. 两者都有

这是你将做出的最有影响力的决定，我有一个强硬的观点：你的品牌指南应该是一个网站。

原因如下：

  • 可搜索。 一个想知道次要颜色调色板的设计师可以使用 Cmd+F 而不是翻阅 30 页。
  • 可链接。 你可以分享一个指向某人需要的确切部分的 URL。"在 brand.company.com/components/buttons 检查按钮规范"比"它在 PDF 的第 34 页"有用得多。
  • 始终最新。 更新一次，每个人立即看到更改。
  • 交互式。 你可以嵌入实时代码示例、颜色选择器、令牌生成器和组件预览。
  • 易于复制。 开发者可以直接复制十六进制代码、CSS 变量和代码片段。

我们已经使用 Next.js 和 Astro 构建了品牌文档网站，两者都适合这个用例。Astro 特别好，因为品牌指南主要是内容，带有一些交互式岛屿——正是 Astro 的架构为之设计的。

也就是说，保留 PDF 导出以供某人需要离线参考或客户想要打印时使用。但 PDF 应该是次要工件，而不是主要工件。

实用架构

对于基于网络的品牌指南，我会这样构建它：

brand-docs/
├── src/
│   ├── content/
│   │   ├── foundations/
│   │   │   ├── mission.mdx
│   │   │   ├── colors.mdx
│   │   │   ├── typography.mdx
│   │   │   └── spacing.mdx
│   │   ├── identity/
│   │   │   ├── logo.mdx
│   │   │   ├── photography.mdx
│   │   │   └── illustration.mdx
│   │   ├── components/
│   │   │   ├── buttons.mdx
│   │   │   ├── forms.mdx
│   │   │   └── cards.mdx
│   │   └── voice/
│   │       ├── tone.mdx
│   │       └── writing-guidelines.mdx
│   ├── tokens/
│   │   ├── colors.json
│   │   ├── typography.json
│   │   └── spacing.json
│   └── components/
│       ├── ColorSwatch.astro
│       ├── TokenTable.astro
│       └── ComponentPreview.astro

使用 MDX 意味着你的内容团队可以用 Markdown 编写，同时在需要的地方嵌入交互式组件。tokens/ 目录成为单一事实来源，为文档网站和你的生产代码提供信息。

如何创建设计师和开发者会使用的品牌指南 - 架构

构建设计令牌基础

设计令牌是品牌指南和实际代码库之间的桥梁。如果你还没有使用它们，它们是存储视觉设计决策——颜色、字体、间距、阴影等——的命名实体，格式可以被多个平台使用。

这是一个令牌文件的实际例子：

{
  "color": {
    "brand": {
      "primary": {
        "$value": "#0057B8",
        "$type": "color",
        "$description": "主要品牌蓝色。用于主要操作、关键 UI 元素和品牌重音。"
      },
      "primary-light": {
        "$value": "#3385D6",
        "$type": "color",
        "$description": "主要的较浅变体。用于悬停状态和次要强调。"
      },
      "primary-dark": {
        "$value": "#003D80",
        "$type": "color",
        "$description": "主要的较深变体。用于活跃/按下状态。"
      }
    },
    "semantic": {
      "success": { "$value": "#16A34A", "$type": "color" },
      "warning": { "$value": "#EAB308", "$type": "color" },
      "error": { "$value": "#DC2626", "$type": "color" },
      "info": { "$value": "{color.brand.primary}", "$type": "color" }
    }
  },
  "spacing": {
    "xs": { "$value": "4px", "$type": "dimension" },
    "sm": { "$value": "8px", "$type": "dimension" },
    "md": { "$value": "16px", "$type": "dimension" },
    "lg": { "$value": "24px", "$type": "dimension" },
    "xl": { "$value": "32px", "$type": "dimension" },
    "2xl": { "$value": "48px", "$type": "dimension" },
    "3xl": { "$value": "64px", "$type": "dimension" }
  }
}

这遵循 W3C 设计令牌社区组格式（在 2025 年成为候选推荐）。Style Dictionary、Tokens Studio 或更新的 Cobalt UI 等工具可以将这些令牌转换为 CSS 自定义属性、Tailwind 配置值、iOS Swift 常量、Android XML 资源——无论你的平台需要什么。

关键的见解：你的品牌指南和生产代码应该使用相同的令牌文件。 当品牌蓝色改变时，你更新一个 JSON 文件，它就会传播到任何地方。

/* 从令牌生成 */
:root {
  --color-brand-primary: #0057B8;
  --color-brand-primary-light: #3385D6;
  --color-brand-primary-dark: #003D80;
  --spacing-xs: 4px;
  --spacing-sm: 8px;
  --spacing-md: 16px;
  /* ... */
}

编写人们真正会读的指南

这是一个难以接受的事实：没人在品牌指南中阅读长篇散文解释。他们扫描。他们寻找具体问题的答案。你的写作需要考虑到这一点。

虔诚地使用"做/不做"格式

每条规则都应该附带正确和不正确使用的视觉或文字示例。不仅仅是"在徽标周围保持足够的清晰空间"。显示具有正确间距的徽标。显示它被塞在角落里。标记一个为"做"，另一个为"不做"。完成。

为扫描而写

  • 慷慨地使用项目符号
  • 将每段中的关键信息加粗
  • 将段落保持在最多 2-3 句
  • 对规范使用表格
  • 在每页的顶部包括快速参考部分

解释原因

这是区分人们遵循的品牌指南和他们绕过的品牌指南的地方。当你说"不要将徽标放在繁忙的摄影背景上"时，也要说为什么：徽标的细节会丢失，在小尺寸上降低识别度。

当人们理解推理时，他们可以在品牌指南未预见的情况下做出良好的判断。而且总会有一些你未预见到的情况。

包括边界情况

品牌指南说徽标的最小尺寸是 24px 高。很好。但是收藏夹图标呢？应用图标？社交媒体头像？电子邮件签名？解决真实世界中困扰人们的边界情况，而不仅仅是理想情景。

连接设计和代码的组件文档

这是大多数品牌指南停止的地方，设计系统开始的地方，但我主张你的品牌指南至少应该包括基础组件。按钮、表单输入、卡片、导航模式——每个页面上出现的构建块。

对于每个组件，记录：

视觉规范

属性 值
Border Radius var(--radius-md) / 8px
Padding var(--spacing-sm) var(--spacing-md) / 8px 16px
Font Size var(--font-size-sm) / 14px
Font Weight var(--font-weight-semibold) / 600
Min Height 40px
Transition all 150ms ease-in-out

状态定义

默认、悬停、活跃、焦点、禁用、加载。对于每个状态，指定确切的视觉变化。不要让开发者猜测"悬停"是什么样子。

代码示例

// React 示例
<Button variant="primary" size="md">
  Get Started
</Button>

// HTML + CSS 类示例
<button class="btn btn-primary btn-md">
  Get Started
</button>

使用指南

何时使用主按钮与次按钮。每页有多少个主按钮（提示：一个）。标签约定是什么（"Save"而不是"Save Changes"，或无论你的品牌决定什么）。

如果你正在使用 headless CMS 设置，这些组件模式变得特别重要，因为内容编辑需要知道哪些组件可用以及它们的使用意图。

语音和语调：每个人都跳过的部分

开发者倾向于跳过这一部分，这是个错误。如果你曾经写过错误信息、工具提示、确认对话、占位符文本或 404 页面，你就一直是品牌语音的写手。开发者编写的面向用户的复制比大多数人意识到的要多。

一个好的语音和语调部分包括：

品牌语音属性

选择 3-5 个形容词来描述你的品牌如何交流。对于每一个，提供一个范围：

我们是... 但不是...
友好的 随意或马虎的
知识渊博的 居高临下的
直接的 生硬或冷漠的
自信的 傲慢的

按上下文划分的语调变化

你的语音保持一致，但语调随上下文而变化。购买后的成功信息应该与结账期间的错误信息感觉不同。

  • 成功状态： 温暖、简洁、欢庆但不过度。"Your order is confirmed!" 而不是 "WOOHOO! 🎉🎉🎉"
  • 错误状态： 同情、清晰、面向解决方案。"We couldn't process your payment. Check your card details and try again." 而不是 "Payment failed."
  • 空状态： 有帮助、鼓励。"No projects yet. Create your first one to get started." 而不是 "No data."

一个词汇表

这是不起眼但非常有用的。创建一个首选术语表：

使用 不要使用
Sign in Log in
Email address Email
Free trial Trial period
Dashboard Home page
Team members Users

术语的一致性比大多数团队意识到的重要得多。

保持品牌指南活跃

最大的风险不是构建一本坏的品牌指南。而是构建一本好的品牌指南，但由于没人维护它而逐渐变得无关。

分配所有权

有人需要拥有品牌指南。不是"设计团队"——一个特定的人。他们不需要自己进行每次更新，但他们负责审查变更、解决冲突并确保准确性。

使用版本控制

如果你的品牌指南是一个网站（就像它应该的那样），将其存储在 Git 中。这给了你：

  • 每次修改的变更日志
  • 在其上线前审查变更的能力（拉取请求）
  • 建议更新需要利益相关者批准的分支
  • 如果出了问题可以回滚

安排季度审查

为季度品牌指南审查设置定期日历事件。遍历每个部分：它仍然准确吗？有应该记录的新模式吗？人们是否在绕过任何指南因为它们实际上不起作用？

让贡献变得容易

最好的品牌指南接受来自整个团队的贡献。一个开发者注意到记录的按钮填充不考虑图标按钮？他们应该能够提交修复。使用类似开源项目的贡献模型：提议变更、获得审查、合并。

品牌文档的工具和平台

这是我在 2026 年实际会考虑的：

工具 最适合 价格范围 方法
Supernova 来自 Figma 的设计系统文档 $49-199/月 从设计工具自动化
zeroheight 品牌 + 设计系统文档 $79-299/月 混合：视觉编辑器 + Figma 同步
Storybook 组件文档 免费（开源） 代码优先、与代码库相关
Astro + MDX 自定义品牌指南网站 免费（自托管） 完全控制，开发者友好
Next.js + MDX 带动态功能的自定义 免费（自托管） 完全控制，React 生态系统
Notion 轻量级 / 早期阶段 免费-$10/用户/月 快速设置、自定义有限
Frontify 企业品牌管理 自定义定价 完整的 DAM + 指南

对于我们合作的大多数团队，使用 Astro 或 Next.js 的自定义构建的解决方案最终成为最好的长期投资。它前期工作更多，但你获得完整的体验控制，你可以直接集成设计令牌，并且你没有经常性的 SaaS 账单。如果你想探索这条路径，我们很乐意讨论架构。

对于需要本周运行的团队，zeroheight 已明显改进，其 Figma 集成意味着设计师可以贡献而无需接触代码。

真实世界的品牌指南架构

让我描述我们在多个客户项目上成功使用的架构。它是主观的，但它起作用。

第 1 层：设计令牌（事实来源）

一个包含 W3C 设计令牌格式 JSON 令牌文件的 Git 存储库。这些通过 Style Dictionary 转换为平台特定输出：CSS 自定义属性、Tailwind 配置、Figma 变量（通过 Tokens Studio）和 Swift/Kotlin 常量。

第 2 层：Figma 库

通过 Tokens Studio 使用令牌的 Figma 组件库。设计师在 Figma 中工作，那里的组件与令牌匹配。令牌的变更会传播到 Figma（经过审查）。

第 3 层：代码组件库

一个使用由相同令牌生成的 CSS 自定义属性的 React（或框架无关的）组件库。这存在于它自己的包或 monorepo 工作区中。

第 4 层：文档网站（品牌指南）

一个 Astro 网站，其中：

  • 读取令牌 JSON 文件并自动生成视觉文档
  • 从代码组件库渲染实时组件预览
  • 包括品牌叙述、语音/语调和使用指南的 MDX 内容
  • 当下面的任何层改变时自动部署
graph TD
    A[Design Tokens JSON] --> B[Style Dictionary]
    B --> C[CSS Custom Properties]
    B --> D[Figma Variables]
    B --> E[Tailwind Config]
    B --> F[Mobile Constants]
    C --> G[Component Library]
    G --> H[Brand Documentation Site]
    A --> H

这个架构的妙处在于品牌指南不是一个需要手动更新的独立文档。它是从驱动你生产代码的同一来源生成的。当令牌改变时，文档在下一次部署时自动更新。

这是我们在 headless CMS 项目 和 Next.js 构建 上定期进行的工程类型。原则无论你是为初创公司还是企业构建设计系统都是相同的。

常见问题

从零开始创建品牌指南需要多长时间？ 对于具有设计令牌、组件文档和基于网络格式的彻底品牌指南，预期 4-8 周的专注工作。这假设你已经有一个定义的品牌身份（徽标、颜色、排版已选择）。如果你从零开始品牌身份，再添加 4-6 周的品牌发现和设计阶段。一个最小可行品牌指南——颜色、排版、徽标使用、基本语音指南——可以在 2 周内完成。

开发者应该参与创建品牌指南吗？ 绝对应该。这是我看到的最大的错失机会之一。从一开始就至少涉及一名资深开发者。他们会早期发现不切实际的规范（"这个字体没有用于代码块的等宽变体"），确保令牌结构对实现有意义，并倡导他们实际使用的文档类型。最好的品牌指南由设计和工程合著。

品牌指南和设计系统之间有什么区别？ 品牌指南定义品牌的样子、声音和感觉。设计系统提供实现——实际的组件、模式和代码来建立品牌。实际上，这条线是模糊的，最好的方法结合了两者。你的品牌指南应该包含足够的实现细节以有用，你的设计系统应该参考品牌原则以便人们理解组件背后的"为什么"。

当品牌演变时，你如何处理品牌指南的版本控制？ 对你的令牌和清晰记录的重大变更使用语义版本控制。次要的色彩调整是修补。向调色板添加新颜色是次要版本。改变主要品牌色是主要版本。当你的品牌指南存在于 Git 中时，你免费获得这个。标记发布、编写变更日志并通过与你使用代码发布相同的渠道进行通信。

设计令牌是什么，我们真的需要它们吗？ 设计令牌是代表你设计决策的命名值——color-brand-primary: #0057B8 而不是到处硬编码十六进制值。如果你有超过一个开发者、超过一个平台或任何维护一段时间内一致性的意图，你需要它们。它们是将你的品牌指南从参考文档转变为可执行系统的机制。W3C 设计令牌规范自其 2025 年候选推荐以来已显著成熟，工具支持在 2026 年是可靠的。

我们应该使用 SaaS 工具还是构建自定义品牌指南网站？ 取决于你的团队规模和技术能力。少于 10 人且没有专职前端开发者？使用 zeroheight 或 Notion 快速运行。超过 10 人、多种产品或可维护它的开发团队？构建一个自定义网站。自定义路线前期成本更多，但在灵活性、与你的令牌管道的集成以及零定期许可费方面有回报。查看我们的定价页面了解自定义文档网站构建所涉及的内容。

品牌指南中的组件文档应该有多详细？ 详细到足以让新开发者无需提问就能正确实现组件。这意味着每个状态的视觉规范、你的主要框架中的代码示例、使用指南（何时使用、何时不使用）、可访问性要求和响应性行为说明。如果你发现自己在 Slack 上对组件回答同一个问题两次，答案应该进入品牌指南。

你如何获得团队认同实际使用品牌指南？ 三个有效的策略：首先，让检查品牌指南比在 Slack 上提问更快——这意味着好的搜索、清晰的导航和复制粘贴就绪的值。其次，将其集成到你的工作流中——在 PR 审查检查清单、Figma 文件描述和入职文档中添加品牌指南链接。第三，让人们为其贡献。当团队集体拥有品牌指南时，他们投入于其成功。最糟糕的事情是将其视为来自上方的要求，没有人有输入权。