品牌色彩的数字化表达：从设计规范到代码变量的转换与验证

一、"品牌蓝"到底是什么蓝？——一个颜色的四种表述

设计师传给我品牌色的定义：PDF 中是 CMYK(100,80,0,0)，Figma 中是 #1677FF，iOS 端是 RGB(22,119,255)，Android 端是 ARGB(0xFF1677FF)。更要命的是，运营物料的"品牌蓝"在 Photoshop 里手动调亮了一点，"为了让宣传图更醒目"。

同一个颜色，六种表述，零种一致性保障。当一个品牌色无法在组织的所有输出媒介上严格一致地呈现时，品牌识别就开始瓦解——而瓦解速度比你想象的快。

品牌色彩的数字化表达，要解决的核心问题是：建立从"设计师说了算的颜色"到"所有端严格一致的代码变量"的单向数据流。

二、色彩从设计到代码的完整流转

flowchart LR A[Figma 色彩样式] --> B[Token 提取工具] B --> C[tokens.json<br/>唯一真理源] C --> D1[CSS Custom Properties] C --> D2[Sass/Less 变量] C --> D3[Android colors.xml] C --> D4[iOS Asset Catalog] C --> D5[React Native theme] C --> D6[Tailwind config] D1 --> E1[Web 应用] D2 --> E1 D3 --> E2[Android App] D4 --> E3[iOS App] D5 --> E4[React Native] D6 --> E1 C --> F[CI 验证管道] F --> G1[色彩空间一致性检查] F --> G2[跨端渲染对比] F --> G3[对比度合规检查]

三、品牌色彩管理系统实现

// brand-color/color-management.ts // 品牌色彩管理系统 // 从单一真理源(tokens.json)自动生成多平台色彩变量 import fs from 'fs'; import { parseToRgb, toColorString } from 'polished'; /** 色彩定义（单一真理源） */ interface ColorToken { /** Token 名称，如 'brand.primary' */ name: string; /** 十六进制颜色值，如 '#1677FF' */ value: string; /** 色彩语义描述 */ description: string; /** * 该色彩在各上下文中的推荐用途 * 用于自动生成多平台变量时的语义映射 */ usage: { web?: string[]; // CSS 属性列表 mobile?: string[]; // 移动端用途 print?: string[]; // 印刷用途 }; } /** * Figma Token 导出 → 统一色彩规格 * * 接收 Figma Plugin 导出的 JSON，转换为平台无关的 ColorToken 数组 */ async function importFromFigma(figmaExportPath: string): Promise<ColorToken[]> { const raw = JSON.parse(fs.readFileSync(figmaExportPath, 'utf-8')); return normalizeTokens(raw); } /** * 生成 Web CSS 变量文件 * * 输出格式：CSS Custom Properties（:root 块） */ function generateCSSVariables(tokens: ColorToken[]): string { let css = ':root {\n'; for (const token of tokens) { const varName = token.name.replace(/\./g, '-'); css += ` --color-${varName}: ${token.value};\n`; // 同时生成 RGB 版本（方便配合 opacity 使用） const rgb = parseToRgb(token.value); css += ` --color-${varName}-rgb: ${rgb.red}, ${rgb.green}, ${rgb.blue};\n`; } css += '}\n'; return css; } /** * 生成 Android colors.xml * * Android 使用 ARGB 格式：#AARRGGBB * 注意：Alpha 默认 FF（完全不透明） */ function generateAndroidColors(tokens: ColorToken[]): string { let xml = '<?xml version="1.0" encoding="utf-8"?>\n'; xml += '<resources>\n'; for (const token of tokens) { const name = token.name.replace(/\./g, '_'); // 添加 FF alpha 前缀 xml += ` <color name="color_${name}">FF${token.value.replace('#', '')}</color>\n`; } xml += '</resources>\n'; return xml; } /** * 生成 iOS Asset Catalog (Contents.json) * * iOS 使用 sRGB 色彩空间的 UIColor 定义 * 生成 Swift 文件而非 plist——这样可以直接 import 使用 */ function generateIOSColors(tokens: ColorToken[]): string { let swift = '// Auto-generated from design tokens — do not edit manually\n'; swift += 'import UIKit\n\n'; swift += 'extension UIColor {\n'; swift += ' // Brand Colors\n'; for (const token of tokens) { const rgb = parseToRgb(token.value); const name = token.name .split('.') .map((part, i) => i === 0 ? part : part.charAt(0).toUpperCase() + part.slice(1)) .join(''); swift += ` /// ${token.description}\n`; swift += ` static let ${name} = UIColor(\n`; swift += ` red: ${(rgb.red / 255).toFixed(3)},\n`; swift += ` green: ${(rgb.green / 255).toFixed(3)},\n`; swift += ` blue: ${(rgb.blue / 255).toFixed(3)},\n`; swift += ` alpha: 1.0\n`; swift += ` )\n\n`; } swift += '}\n'; return swift; }

// brand-color/color-validator.ts // 跨平台色彩一致性验证 import { parseToRgb, meetsContrastGuidelines } from 'polished'; import { Page } from 'playwright'; /** * 色彩一致性验证器 * * 在 CI 中运行，确保： * 1. 各平台的色彩值与 tokens.json 一致 * 2. 色彩对比度满足 WCAG AA 标准 * 3. CMYK 与 RGB 的色彩偏移在可接受范围内 */ class ColorValidator { /** * 检测色彩色差（Delta E 2000 算法） * * 判断两个颜色在人眼看来是否"相同" * Delta E < 1：肉眼无法区分 * Delta E 1-3：几乎不可察觉 * Delta E > 3：可察觉的差异（品牌色不可接受） */ async validateCrossPlatform( webUrl: string, androidColorXmlPath: string, iosColorSwiftPath: string ): Promise<ValidationReport> { const report: ValidationReport = { passed: true, issues: [] }; // 1. 验证 Web CSS 变量值与 tokens.json 一致 const browser = await require('playwright').chromium.launch(); const page = await browser.newPage(); await page.goto(webUrl); const cssVarValues = await page.evaluate(() => { const styles = getComputedStyle(document.documentElement); const vars: Record<string, string> = {}; // 遍历所有以 --color 开头的 CSS 变量 for (let i = 0; i < document.styleSheets.length; i++) { try { const rules = document.styleSheets[i].cssRules; for (const rule of rules) { // 检查 :root 规则中的变量声明 } } catch (e) { /* CORS 限制 */ } } return vars; }); await browser.close(); // 2. 色彩对比度验证 // 检查所有前景色-背景色配对 for (const token of this.tokenSpecs) { if (token.usage?.web?.includes('text')) { // 文本色需要与所有背景色配对检查 for (const bgToken of this.tokenSpecs.filter(t => t.usage?.web?.includes('background'))) { const ratio = this.calculateContrastRatio(token.value, bgToken.value); if (ratio < 4.5) { report.issues.push({ severity: 'error', message: `文本色 ${token.name}(${token.value}) 在背景色 ${bgToken.name}(${bgToken.value}) 上的对比度为 ${ratio.toFixed(2)}:1，不满足 WCAG AA 标准(4.5:1)` }); report.passed = false; } } } } return report; } /** * 计算 WCAG 对比度 */ private calculateContrastRatio(fg: string, bg: string): number { const l1 = this.relativeLuminance(fg); const l2 = this.relativeLuminance(bg); const lighter = Math.max(l1, l2); const darker = Math.min(l1, l2); return (lighter + 0.05) / (darker + 0.05); } private relativeLuminance(hex: string): number { const rgb = parseToRgb(hex); const toLinear = (c: number) => { const s = c / 255; return s <= 0.04045 ? s / 12.92 : Math.pow((s + 0.055) / 1.055, 2.4); }; return 0.2126 * toLinear(rgb.red) + 0.7152 * toLinear(rgb.green) + 0.0722 * toLinear(rgb.blue); } }

/* * ========================================== * RGB 变量的正确使用方式 * ========================================== * * 为什么需要同时定义 hex 和 rgb 两个版本？ * * --color-brand-primary: #1677FF; * → 用于纯色场景：color, background, border * * --color-brand-primary-rgb: 22, 119, 255; * → 用于需要 alpha 通道的场景： * background: rgba(var(--color-brand-primary-rgb), 0.1); ✅ * box-shadow: 0 0 0 3px rgba(var(--color-brand-primary-rgb), 0.2); ✅ */ :root { --color-brand-primary: #1677FF; --color-brand-primary-rgb: 22, 119, 255; } /* 使用示例：品牌色 10% 透明度的背景 */ .tag { background: rgba(var(--color-brand-primary-rgb), 0.1); color: var(--color-brand-primary); border: 1px solid rgba(var(--color-brand-primary-rgb), 0.2); }

四、CMYK ↔ RGB 的跨媒介陷阱

屏幕永远不等于印刷。RGB 是加色模式（光叠加），CMYK 是减色模式（油墨叠加）。两者的色域（gamut）不重叠——某些鲜艳的 RGB 颜色在 CMYK 中根本印不出来。

品牌色彩必须定义屏幕主值（RGB hex）和印刷主值（CMYK）作为两个独立的真理源。它们是"同一品牌色在不同媒介上的最优近似"，而不是"同一个数值的不同表示"。试图用公式把 hex 转成 CMYK 必定失败——需要设计师在两个媒介上分别确认。

暗黑模式下的品牌色需要独立 Token。--color-brand-primary在暗黑模式下的值往往不是单纯的 RGB 数字调整（如直接变亮会导致视觉刺眼），而是需要设计师在暗黑背景下重新选定。独立 Token：--color-brand-primary-dark。

五、总结

品牌色彩的数字化表达是"减少组织内色彩熵增"的系统工程：

1. 唯一真理源：tokens.json是所有平台颜色值的唯一源头
2. 自动生成：Web CSS、Android XML、iOS Swift 均由脚本从 Token 文件自动生成
3. 自动验证：CI 中检查各平台颜色值与 Token 文件的一致性 + 对比度合规
4. RGB 双变量模式：同时提供 hex 和 rgb 版本，覆盖纯色和透明度场景

核心原则：改品牌色只改tokens.json一行，所有端自动同步。