open-design 品牌引擎：从 ~20 字段 Seed 到完整设计系统、主题组件套件与成品的确定性推导

本文基于 open-design 仓库中 apps/daemon/src/brands/engine/README.md 展开，解析其品牌引擎（brand engine）的核心机制：一个 Ant Design 风格的最小化品牌输入（Seed，约 20 个字段）如何经确定性算法推导出完整设计 Token 系统、带主题的 HTML 组件套件（kit）和成品页面（landing / email / poster）。读完后你将掌握 buildBrandSystem / buildFromUrl 等公共 API 的调用方式、pnpm brand:build 与 POST /api/brand/build 两种驱动入口，以及 10 级色阶算法、default/dark/compact 三套主题的底层推导原理。

一、引擎定位与整体流水线

品牌引擎位于 apps/daemon/src/brands/engine/ 目录下，README 对其定位是：

一个 Ant Design 风格的品牌引擎：品牌被坍缩为一个极小的 Seed（约 20 个字段），确定性算法从它推导出整套风格系统、主题化组件套件和成品（landing / email / poster）。变体（light / dark / compact）是同一个 seed 跑过不同算法的结果，而非手工编写。

引擎目录的实际模块划分与流水线一一对应（见 index.ts 的 barrel 导出）：

  URL ──prefetch──▶ material ──seedFromMaterial──┐
                                                 ├─▶  Seed (SeedToken, ~20 fields)
  Brand kit ───────────────────seedFromBrand────┘
                                                 │
                              deriveTokens(seed, "default" | "dark" | "compact")
                                                 │
                                                 ▼
                                  DesignTokens  (the style system)
                  ┌──────────────────────┬──────────────────┬───────────────────┐
                  ▼                      ▼                  ▼                   ▼
            export                     kit              artifacts            (raw)
   tokens.json / variables.css   themed components   landing / email     primaryPalette
   theme.json (antd)             (var(--brand-*))    poster (HTML)        + 13 presets

模块	文件	职责
冻结契约	types.ts	SeedToken / DesignTokens / BrandSystem 类型定义 + CSS 变量命名工具（cssVar / varRef / flattenTokens），所有模块从这里导入类型，保证独立开发的模块保持对齐
调色板	palette.ts	@ant-design/colors 的 generate() 算法的零依赖移植 + 13 组预设色板
Seed 合成	seed.ts	唯一产出 seed 的入口：defaultSeed / seedFromBrand / seedFromMaterial 三条路径
Token 推导	derive.ts	引擎核心：Seed → 完整 DesignTokens，实现 default / dark / compact 三种算法
导出序列化	export.ts	tokensToJson / tokensToCssVars / tokensToThemeJson 三种可移植产物
组件套件	kit.ts	button / card / input / tag / alert / table / tabs 等纯函数组件 + renderKitPage 展示页
成品	artifacts/	landing / deck / poster / email / newsletter / form 六种成品渲染器
集成接缝	build.ts	buildBrandSystem / buildFromUrl / writeBrandSystem / slugify

README 强调了一个设计原则：每个下游值都可以追溯回 Seed，全部经由算法产生，没有任何手写的值。10 级色阶是 @ant-design/colors 的 generate() 的忠实、零依赖移植——标准蓝色色阶可逐位复现（README 中提及的逐位复现由品牌提取引擎测试 apps/daemon/tests/brand-extraction-engine.test.ts 所覆盖的测试体系保障）。

二、Seed：最小输入面（SeedToken）

types.ts 中的 SeedToken 是整个引擎的"唯一入口"。约 20 个字段分五类，每个字段的语义直接决定下游推导：

字段	类型	说明
colorPrimary	string	唯一的品牌种子色，成为色阶索引 5（第 6 级）
colorSuccess / colorWarning / colorError / colorInfo	string	语义功能色
colorLink	string	空字符串时推导时回退到 colorInfo
colorTextBase	string	浅色主题取 #000000、深色取 #ffffff；中性文字色由它按 alpha 推导出整级
colorBgBase	string	浅色主题 #ffffff、深色 #000000
fontFamily / fontFamilyCode	string	正文 / 代码字体栈
fontSize	number	基础正文字号（14px），整个模块化字号阶梯由此派生
borderRadius	number	基础圆角（6px）
sizeUnit / sizeStep	number	间距基础单位 / 步长（4 / 4），8px 网格即 sizeUnit*2
controlHeight	number	控件默认高度（32px）
lineWidth	number	线宽
motionUnit / motionBase	number	动效时长单位（0.1s）与基础偏移（0）
wireframe / motion	boolean	线框模式与全局动效开关

冻结的 Ant Design 亮色基线定义在 seed.ts 的 defaultSeed 中：主色 #1677ff、成功 #52c41a、警告 #faad14、错误 #ff4d4f、字号 14、圆角 6、间距 4/4、控件高度 32、线宽 1、动效单位 0.1。任何未被品牌覆盖的字段都会落回这份基线。

2.1 三条产出 Seed 的路径

seed.ts 是全引擎中唯一"生产" seed 的模块，刻意只依赖冻结的 SeedToken 类型与相邻的 Brand / PrefetchResult 契约，不触碰 palette / derive，保证 seed 面与后续 Token 计算方式解耦。

seedFromBrand(brand)——从已合成的 Brand kit 映射 seed（seed.ts）：

• colorPrimary ← 角色为 accent 的颜色；否则取第一个非中性角色色；都没有则回退默认值
• colorInfo ← 与 primary 相同
• colorLink ← 角色 accent-secondary；没有则留空
• colorSuccess ← 若 accent-secondary 读起来偏绿（色相 75–165° 且饱和度 > 0.25，见 isGreenish）则采用，否则保持 Ant 默认
• colorTextBase / colorBgBase ← 由 neutralBases() 解决：dark-first 品牌（同时携带置信度高的深色画布，亮度 ≤ 0.3，与浅色前景，亮度 ≥ 0.6）会保留其真实画布，使推导出的默认主题保持 on-brand；模糊情况（中灰画布、缺角色、深底深字）一律回退亮色基线
• fontFamily ← 正文字体族 + fallback + 系统栈尾部（Ant 默认 system UI 栈，含 CJK 与 emoji 字体）
• borderRadius ← parseInt(layout.radius) || 6
• 其余字段 ← defaultSeed

seedFromMaterial(material)——从 prefetch 原始素材确定性推断 seed（URL → seed 路径，无 LLM 参与）（seed.ts）：

• colorPrimary ← 对抓取到的颜色候选打分取最高分。打分函数 primaryScore 奖励使用频率（log2 阻尼，避免单一到处出现的边框色独占）与舒适明度带内的中高饱和度；硬拒极端色（亮度 > 0.92 或 < 0.06）和低饱和灰（饱和度 < 0.18 直接返回 -Infinity）
• 语义色（success / warning / error）保持稳定的 Ant 默认——注释中说明：仅凭频率无法可靠推断语义色
• fontFamily ← 实测字体 fonts[0].family 或第一个 @font-face 字体族
• 深色源站点仍会得到亮色的默认 kit，黑色画布交给 dark 算法负责

值得注意的一个防御性细节：isRenderableFontFamily（types.ts）会拒绝任何携带 CSS 语法字符的"字体族"——因为某些提取器抓到的是 CSS 源码文本（如 Tailwind v4 的 --theme(--default-font-family），一个未配对的括号就会吞掉后面所有 :root 声明，让整个 kit 失去样式。

三、色阶算法：generate() 的忠实移植

palette.ts 是整个 Token 系统唯一的色彩来源：derive.ts 把 primary 和每个功能色都喂给 generate()；13 组 presets 为图表 / 标签 / 子品牌提供现成色板。

3.1 10 级色阶的常数

const hueStep = 2;                // 色相阶梯
const saturationStep = 0.16;      // 饱和度阶梯,浅色部分
const saturationStep2 = 0.05;     // 饱和度阶梯,深色部分
const brightnessStep1 = 0.05;     // 亮度阶梯,浅色部分
const brightnessStep2 = 0.15;    // 亮度阶梯,深色部分
const lightColorCount = 5;       // 浅色数量,主色上
const darkColorCount = 4;        // 深色数量,主色下

generate(baseColor, opts) 的输出是 [5 个更浅, base, 4 个更深] 共 10 级的小写 #rrggbb 数组，索引 5 ≈ 输入种子色。几个算法要点（对应 palette.ts 中逐行移植的 Ant 注释）：

• 色相转向：60–240° 的"冷区"与暖区色相移动方向相反（getHue）
• 饱和度边界修正：灰色（h=0 且 s=0）不改饱和度；最浅一级（第 5 个浅色格）的饱和度被限制在 0.06–0.1 之间，整体下限 0.06
• 明度阶梯：浅色部分每级 +0.05，深色部分每级 -0.15

HSV/RGB 互转是内联实现的，刻意对齐 tinycolor 的取整方式，以保证标准蓝色阶梯与 @ant-design/colors 逐位一致。

3.2 深色主题的 darkColorMap 混合

调用 generate(color, { theme: "dark", backgroundColor }) 时，10 级浅色阶梯会按一份"混合配方"重新叠加到深色背景（默认 #141414）上（palette.ts）：

const darkColorMap: Array<{ index: number; opacity: number }> = [
  { index: 7, opacity: 0.15 },
  { index: 6, opacity: 0.25 },
  { index: 5, opacity: 0.3 },
  { index: 5, opacity: 0.45 },
  { index: 5, opacity: 0.65 },
  { index: 5, opacity: 0.85 },
  { index: 4, opacity: 0.9 },
  { index: 3, opacity: 0.95 },
  { index: 2, opacity: 0.97 },
  { index: 1, opacity: 0.98 },
];

即"深色阶梯的每一步 = 对应浅色阶梯的某一级以指定不透明度混合到深色画布上"，这是 Ant Design 深色主题色阶的标准做法。

3.3 13 组预设色板

presets 由 12 个真实 Ant Design 种子色 + grey 共 13 组构成（palette.ts）：red #F5222D、volcano #FA541C、orange #FA8C16、gold #FAAD14、yellow #FADB14、lime #A0D911、green #52C41A、cyan #13C2C2、blue #1677FF、geekblue #2F54EB、purple #722ED1、magenta #EB2F96、grey #666666。每组阶梯都由 generate() 现场计算，而非手打——保证与上面的算法永远同步。

四、deriveTokens：一个 Seed，三套主题

derive.ts 的 deriveTokens(seed, algorithm) 是引擎之心，签名接受 "default" | "dark" | "compact" 三种算法（默认 "default"）。核心思想与 Ant Design 一致：从约 30 个种子推导数百个 map token，没有任何值是手工的，三套主题变体只是同一 seed 跑不同数学。

4.1 画布解析与 dark-first 判定

derive 首先判定种子是否为 dark-first 品牌（seedPrefersDark，derive.ts）：colorBgBase 亮度 ≤ 0.3 且 colorTextBase 亮度 ≥ 0.6（与 seed.ts 的 neutralBases 使用完全相同的阈值）。判定结果影响三处：

• dark-first 种子在所有算法中都保留其真实深色画布，variables.css、kit.html 直接按深色推导
• 导出的 theme.json 必须携带 "dark" 算法标记——defaultThemeAlgorithm(seed) 是所有 theme.json 生产方必须经由的唯一决策点，否则 ConfigProvider 消费者会在深色画布上应用亮色算法
• 纯 dark 算法的画布回退为近黑 #141414，仅作为亮色优先品牌的兜底

4.2 语义色状态映射

10 级色阶到交互状态的映射在 statesFromPalette（derive.ts）中完成，0 基索引为：bg=[0]、bgHover=[1]、border=[2]、borderHover=[3]、hover=[4]、base=[5]、active=[6]、text=[8]。暗色下 hover / active 会按 Ant 暗色算法的方式移位（hover 变浅、active 取更浅一档），保证深色画布上的状态可读性。colorLink 为空时以 colorInfo 兜底，与 SeedToken 契约一致。

4.3 中性色 alpha 阶梯

中性文字 / 填充 / 边框不是调色出来的，而是把 colorTextBase 按固定 alpha 叠加到画布上（alphaOver 预合成出不透明 hex，供消费者直接画）。两套 alpha 表（neutralAlphas）：

档位	default / compact（亮）	dark
text 四级	88 / 65 / 45 / 25 %	85 / 65 / 45 / 25 %
fill 四级	15 / 6 / 4 / 2 %	18 / 12 / 8 / 4 %
border	15 %	18 %
borderSecondary	6 %	12 %
layout 画布着色	4 %	4 %

default 与 compact 共享亮色中性阶梯——颜色层与密度层是正交的。

4.4 字号、间距、几何与动效的推导

• 字号阶梯：fontSizeLadder(base) 取 10 级，第 1 级（索引 1）强制为基础字号，其余为 round(base * e^((i-1)/5)) 再对齐偶数（Ant 的 genFontSizes 公式）。base=14 时产出 [12,14,18,22,26,32,38,46,58,70]。源码注释坦承这与 Ant v5 公开发布的手工调优阶梯（[12,14,16,20,24,30,38,46,56,68]）在中间几级相差几 px——发布版是曲线拟合的，而引擎坚持"以忠实移植的算法输出为准"
• 间距阶梯：8 级 = sizeUnit*(sizeStep + n)。默认 4/4 种子下偏移 [-3,-2,-1,0,1,2,4,8] 恰好产出 [4,8,12,16,20,24,32,48]（8px 网格即 sizeUnit*2）；compact 把有效 sizeStep 从 4 压到 2，偏移改为 [-1,0,0,1,2,2,4,6]，整级塌缩为 [4,8,8,12,16,16,24,32]——颜色完全不变，只有密度变化
• 圆角：由种子圆角按比例推出 XS ≈ /3、SM ≈ ×2/3、LG = +2px（6 → 2 / 4 / 6 / 8）
• 控件高度：compact 下 controlHeight 固定为 28，XS/SM/LG 保持 0.5× / 0.75× / 1.25× 比例
• 动效：fast/mid/slow = motionBase + motionUnit × 1/2/3，默认 0.1s / 0.2s / 0.3s；缓动曲线固定为 Ant 签名曲线 cubic-bezier(0.645, 0.045, 0.355, 1) 与 cubic-bezier(0.215, 0.61, 0.355, 1)

4.5 DesignTokens 的形态

输出 DesignTokens（types.ts）采用扁平的 antd 风格命名，与 CSS 自定义属性 1:1 对应：长度是 px 数字、行高与字重是无单位数字、时长是秒字符串（"0.2s"）、颜色与字体族是字符串。它包含 algorithm 标记、primary 全状态（Bg/BgHover/Border/BorderHover/Hover/Active/Text）、五组功能色状态、中性四级文字 / 填充 / 背景 / 边框、完整排版与几何段、动效段，以及两段原始数据：primaryPalette（10 级主色阶）与 presets（13 组预设），供色板墙 / 图表 / 子品牌直接取用。

五、导出：JSON、CSS 变量与 antd theme.json

export.ts 是纯格式化器，只依赖冻结的 ./types 契约，不导入任何引擎实现模块：

DesignTokens ──tokensToJson──▶       tokens.json       (raw, inspectable)
DesignTokens ──tokensToCssVars──▶    variables.css     (--brand-* custom props)
SeedToken    ──tokensToThemeJson──▶ theme.json        (antd ConfigProvider)

• tokensToJson(tokens)：完整 Token 集的 JSON.stringify 输出，即 tokens.default.json 等文件
• tokensToCssVars(tokens, selector = ":root")：名称与值直接来自 flattenTokens，因此 CSS 输出与 kit / artifacts 中每个 varRef("colorPrimary") 严格一致。扁平化规则（types.ts）：数组（palette）展开为 <name>-<1 基索引>，对象（presets）展开为 <name>-<key>-<1 基索引>，algorithm 字段跳过；数值按前缀加 px（fontSize|size|borderRadius|lineWidth|controlHeight 开头），lineHeight|fontWeight 保持无单位
• CSS 变量命名：cssVar("colorPrimaryBg") → --brand-color-primary-bg；varRef("colorPrimary", fallback?) → var(--brand-color-primary[, fallback])
• tokensToThemeJson(seed, algorithm)：把种子近乎 1:1 映射到 antd 的 seed-token 面（颜色、字体、字号、圆角、sizeUnit/sizeStep、controlHeight、lineWidth、motion 单位），并记录应应用的 algorithm；空的 colorLink 会被丢弃，让 antd 从 colorInfo 自行推导，与引擎内部的回退行为镜像

六、Kit 与 Artifacts：同一套标记，自动换肤

kit.ts 中的每个组件都是返回 HTML 字符串的纯函数，颜色 / 间距 / 排版只来自派生 Token 的 CSS 自定义属性（var(--brand-*)，经 varRef）。没有任何针对单个品牌的手工调参：:root Token 块一变，同一份标记自动重新换肤——这就是"一个 Seed 产出横跨 light / dark / compact 的一致性组件集"的机制。

• 片段函数：button（primary/default/dashed/text/link × sm/md/lg）、card、input、tag、alert（success/info/warning/error 四张脸）、swatches、typeScale，以及更丰富的 avatar / stat / divider / textarea / select / checkbox / switchToggle / tabs / breadcrumb / pagination / progress / steps / table / accordion / testimonial / pricingCard
• renderKitPage(tokens, opts) 返回完整独立文档：它内联由 flattenTokens 直接构建的 :root{ --brand-… } 块（不依赖 export.ts，kit 必须能独立站住），并内联 KIT_CSS 表达内联样式写不出的 hover / focus / details[open] 状态
• Artifacts 层（artifacts/）按 kind 拆分出 landing / deck / poster / email / newsletter / form 渲染器与 generic 兜底；renderArtifact(kind, brand, tokens) 接受所有 AssetKind，没有专属布局的 kind 回退到一个合理的 card+button 页

七、BrandSystem 与产出文件清单

buildBrandSystem（build.ts）把整个流水线封装成一个内存中的输出包：

BrandSystem = { slug, seed, themes: { default, dark, compact }, files }

files 是 { 相对路径 → 文件内容 } 映射，可直接写盘、经 HTTP 返回或离线检视。writeBrandSystem(system, outDir)（build.ts）负责落盘。最终产物清单（继承自 README 的 "Produced files" 表）：

路径	内容
seed.json	生效 SeedToken 的生成快照；持久化覆写应放在 brand.json.seed
tokens.default.json / .dark.json / .compact.json	每个算法下完整派生的 DesignTokens
variables.css	:root{}（亮）+ .dark{}（暗）CSS 自定义属性
variables.dark.css	深色主题的独立 :root{}
theme.json	antd ConfigProvider 主题（{ token, algorithm }）
kit.html / kit.dark.html	主题化组件展示页
artifacts/landing.html · email.html · poster.html	成品页面
index.html	画廊：文件索引 + 实时 iframe 预览
BRAND-SYSTEM.md	人类可读摘要 + 如何重新换肤的说明
logos/*	（仅 URL 路径）下载的 logo 候选

八、Agent 驱动方式：一条命令

8.1 CLI

# 从已合成的 brand kit（离线、确定性）：
pnpm brand:build path/to/brand.json [outDir]

# 直接从站点 URL（确定性 prefetch → seed → system；无 LLM）：
pnpm brand:build https://stripe.com [outDir]

默认 outDir 为 ./out/<slug>，命令会打印文件树与 index.html 的路径（slugify 见 build.ts）。

Node 24 兼容性说明（README 原文要点）：Node 24 会剥离 TS 类型，但不会给引擎内部的无扩展名相对导入补上 .ts，因此 pnpm brand:build 会以注册了 scripts/ts-resolve-hook.mjs 的方式重新拉起 node——这是一个零依赖的 ESM 解析器垫片，把 ./palette 映射到 ./palette.ts。无需修改源码或构建配置。

8.2 HTTP API

POST /api/brand/build（Node runtime；路由实现在 apps/daemon/src/brand-routes.ts，测试见 apps/daemon/tests/brand-routes.test.ts 与 apps/daemon/tests/brands-cli.test.ts）：

// from a URL
{ "url": "https://stripe.com", "write": false }

// from a brand kit, also writing to disk
{ "brand": { /* Brand */ }, "write": true, "outDir": "./out/acme" }

响应：

{
  "slug": "stripe",
  "themes": ["default", "dark", "compact"],
  "files": { "seed.json": "…", "variables.css": "…", "index.html": "…", … },
  "writtenTo": "./out/stripe"   // only when write: true
}

URL 路径下的二进制 logo 资源会以 *.b64 字符串条目返回，由 writeBrandSystem / write: true 解码为真实字节写盘。

8.3 公共 API（代码层集成）

从 barrel index.ts（@/lib/brand/engine）导入：

import {
  buildBrandSystem,   // Brand  → BrandSystem (offline)
  buildFromUrl,       // URL    → BrandSystem (one prefetch hop, no LLM)
  writeBrandSystem,   // BrandSystem + outDir → writes files to disk
  slugify,
  // lower-level building blocks
  deriveTokens, defaultSeed, seedFromBrand, seedFromMaterial,
  generate, presets,
  tokensToJson, tokensToCssVars, tokensToThemeJson,
  button, card, input, tag, alert, swatches, typeScale, renderKitPage,
  renderArtifact, renderArtifactGallery,
  // helpers + types
  cssVar, varRef, flattenTokens,
  type SeedToken, type ThemeAlgorithm, type DesignTokens, type BrandSystem,
} from "@/lib/brand/engine";

九、Recipes：改色、暗色/紧凑、新增成品类型

改品牌色。 设置 seed.colorPrimary 或编辑 Brand 中的 accent 颜色角色。对已注册的品牌项目，把覆写持久化到 brand.json.seed，然后运行 od brand finalize <brand-id>。不要直接编辑 system/seed.json——finalize 会重新生成它。改一处后，10 级色板、所有交互状态、primary 背景 / 边框，以及所有引用 var(--brand-color-primary) 的组件会同步更新（这正是"全部值可追溯到 Seed"的设计承诺）。

亮 → 暗 / 紧凑。 两者都是同一 seed 跑不同算法：加载 variables.dark.css（或加 .dark class）即得暗色；tokens.compact.json 收紧间距与控件高度（controlHeight 28、间距阶梯塌缩至 [4,8,8,12,16,16,24,32]），颜色保持完全一致。

新增成品类型。 renderArtifact(kind, brand, tokens) 已接受所有 AssetKind（landing | deck | poster | email | newsletter | form），没有专属布局的 kind 回退到 card+button 页。要把新 kind 打进产物包，把它加入 build.ts 的 ARTIFACT_KINDS 常量（当前为 ["landing", "deck", "poster", "email", "newsletter", "form"]）；要给专属布局，则新增 renderXxx(brand, tokens) 并在 renderArtifact 中加一个 case。

十、小结：为什么"小 Seed"是关键

open-design 品牌引擎把 Ant Design 的 token 思想压缩成一条可审计的单向管线：SeedToken（~20 字段）→ deriveTokens(algorithm) → DesignTokens → export / kit / artifacts。三条工程决策值得复用：

1. 唯一入口：seed 是引擎唯一的输入面，seed.ts 独立于 palette / derive，三条产出路径（default / Brand / material）收敛到同一类型；
2. 确定性可验证：色阶算法忠实移植 @ant-design/colors 并由测试锁定逐位一致，"改一个色"的所有下游变化（状态、背景、组件引用）由算法保证同步；
3. 变体即算法：dark / compact 不是另写的一套值，而是同一 seed 经过不同数学（darkColorMap 混合 / 密度阶梯塌缩），使三套主题永远互不漂移。

对需要"给任意品牌/站点一键生成可落地设计系统"的 Agent 型应用，这套 Seed → Tokens → Kit → Artifacts 的接缝（buildBrandSystem / buildFromUrl / writeBrandSystem）可以直接作为集成参考：离线 Brand 输入走 buildBrandSystem，在线 URL 输入走 buildFromUrl，两者产出同一形状的 BrandSystem，随后无论写盘、HTTP 返回还是内存检视都一致。