winson-color-spec-builder

> 色彩规范不是好看的色卡，是整个设计系统的"视觉语法"。

> 好的色彩规范 = 结构纪律 + 语义清晰 + 零装饰冗余。

一、核心哲学

1.1 唯一铁律

> 好的色彩规范是"半成品"——设计用它搭建界面，开发用它写CSS，两者说的是同一种颜色语言。

>

> 更进一步的铁律：色彩规范必须同时满足"视觉纪律"与"语义可维护性"。

色彩规范文档不是设计师的自嗨笔记。它必须同时满足三个角色的需求：

• 设计师能按规则组合配色而不需反复商量
• 开发者能直接对应到 CSS Variable / Design Token
• 产品经理能理解颜色语义（红是什么？绿是什么？）

检验标准：给一个不懂配色的人看这份规范，他能否拼出一致的页面。

1.2 三个底层认知

1.3 色彩规范构建六阶段公式

品牌色锚定义 ──→ 色板梯度扩展 ──→ 语义Token设计 ──→ 应用规则定义
     ↓                                                        ↓
  字体配套规范 ←────────────────────────── 暗色/多主题适配 ←── 组件色彩映射
     ↓
  规范文档化交付

二、铁幕·Iron 设计哲学融入

2.1 三层配色递进架构

本技能采用 铁幕·Iron 三层配色递进，根据内容复杂度选择层级：

核心原则：

• 一份规范只用一个配色层级，不要中途换层级
• 颜色用于标注重点 > 区隔 > 页面平衡 > 企业风格 > 个人喜好
• 选择什么颜色不重要，在哪里使用颜色才重要

2.2 视觉纪律规范（铁幕·Iron 设计系统）

2.3 配色决策五问

当思考用什么颜色时，必须依次回答：

1. 本资料的整体用色规范是什么？（三层配色的哪一层？）
2. 这部分内容属于什么层级？（基础 / 主题 / 强调）
3. 这一页/这个组件的重点内容如何突出？
4. 这个内容与之前页面的哪个层级一致？
5. 这个内容的强调方式与之前哪个页面的内容应该对应一致？

三、完整执行流程

Phase 1：品牌色锚定义（Brand Anchor）

Step 1.1：提取核心品牌色

从品牌 Logo、VI 手册或业务定位中提取 1-3 个核心色值。

操作指令：

1. 找品牌最核心的颜色（通常是 Logo 主色）
2. 识别第二辅助色（如有）
3. 识别强调/点缀色（CTA 用色）

输出示例：

主色：海军蓝 #002B5C（品牌信任感）
强调色：深红 #C8102E（关键操作、预警）
功能色：绿色 #1B7340（正向、成功）

检验标准：核心色不超过 3 个，超出说明品牌定位不够聚焦。

Step 1.2：定义色值属性

对每个核心色，明确：

• HEX（设计交付标准）
• RGB（开发用）
• HSB/HSL（调色参考）
• 使用场景（一句话描述）

模板：

- name: 海军蓝（主色）
  hex: "#002B5C"
  rgb: (0, 43, 92)
  hsb: (212°, 100%, 36%)
  usage: 主色调、导航栏背景、统计栏、重要按钮

检验标准：每个核心色都有明确的 "usage" 字段，不允许 "用于强调" 这种模糊描述。

Phase 2：色板梯度扩展（Palette Gradation）

Step 2.1：建立色阶系统

每个核心色扩展为 3-6 阶梯度（明度变化），通常结构为：

深色（Dark）      → 用于标题、重要文字
主色（Base）      → 品牌主色调
浅色（Light）     → 背景、悬停态、次要元素
极浅色（Pale）    → 极浅背景、分割线

实战公式：

输出示例（基于海军蓝）：

--navy-dark: #001B3A;     /* -40% 明度：标题、重要文字 */
--navy: #002B5C;           /* 基准值：主色调、按钮、背景 */
--navy-light: #003D7A;     /* +30% 明度：链接、交互元素 */

检验标准：每个核心色至少扩展 3 阶，且有明确的用途说明。

Step 2.2：补充中性色阶

中性色（灰、灰蓝、银灰）是使用频率最高的色系，需要建立 5-8 阶梯度：

命名规范（铁幕·Iron 风格——用材质/自然意象命名）：

--slate: #3D4F5F;     /* 板岩-次要元素 */
--steel: #5A6F7F;     /* 钢色-辅助文字 */
--silver: #8A9BAE;    /* 银灰-标签/提示 */
--ice: #C8D3DE;       /* 冰色-禁用态 */
--mist: #E8EDF2;      /* 薄雾-浅色背景 */
--snow: #F4F6F8;      /* 雪色-表格悬停/卡片 */

检验标准：中性色覆盖从主文字（最深）到纯白背景（最浅）的完整梯度，且每个层级都有指定用途。

Phase 3：语义Token设计（Semantic Tokenization）

Step 3.1：定义Token分层

Token 必须分三层，这是决定规范可维护性的关键。

核心原则：

• Primitive 层不改名只改值（品牌升级时只动这里）
• Semantic 层不改值改名（业务需求变化时调整映射）
• Component 层直接引用 Semantic，不直接引用 Primitive

Step 3.2：语义类别定义

按以下四类语义定义 Token：

A. 品牌色语义

--color-brand: var(--navy);          /* 品牌主色 */
--color-brand-hover: var(--navy-light); /* 品牌悬停 */
--color-brand-soft: var(--mist);     /* 品牌浅色背景 */

B. 文字色语义

--color-text-primary: #1A2332;       /* 主文字 */
--color-text-secondary: #4A5568;     /* 次要文字 */
--color-text-tertiary: #7A8694;      /* 辅助文字 */
--color-text-on-brand: #FFFFFF;      /* 品牌色背景上的文字 */

C. 功能色语义

--color-success: #1B7340;            /* 成功/正向 */
--color-success-bg: #EDF7F0;         /* 成功背景 */
--color-error: #C8102E;              /* 错误/负向 */
--color-error-bg: #FDF0F0;           /* 错误背景 */
--color-warning: #B8860B;            /* 警告 */
--color-warning-bg: #FDF6E3;         /* 警告背景 */
--color-disabled: #8A9BAE;           /* 禁用 */
--color-disabled-bg: #F4F6F8;        /* 禁用背景 */

D. 结构层语义

--color-surface: #FFFFFF;            /* 主背景（表面） */
--color-surface-secondary: #F7F8FA;  /* 次要背景 */
--color-border: #D6DCE4;             /* 主边框 */
--color-border-light: #E8ECF0;       /* 浅边框 */

检验标准：每个 Token 的命名能让人一眼看出它的用途（"这是什么颜色" → "这个颜色做什么用"）。

Phase 4：应用规则定义（Application Rules）

Step 4.1：背景色体系

列出所有背景色层级，明确嵌套规则：

/* 层级0：最外层 */
--bg-primary: #FFFFFF;          /* 页面主背景 */
--bg-secondary: #F7F8FA;       /* 中性背景-内容区域 */
--bg-tertiary: #F4F6F8;         /* 雪色-卡片/表格悬停 */
--bg-subtle: #E8EDF2;           /* 薄雾-分割区域 */

/* 层级1：品牌背景 */
--bg-brand: var(--navy);         /* 统计栏、导航等品牌背景 */
--bg-brand-light: var(--mist);   /* 品牌浅背景 */

/* 层级2：状态背景（功能色） */
--bg-success: #EDF7F0;           /* 成功态背景 */
--bg-warning: #FDF6E3;           /* 警告态背景 */
--bg-error: #FDF0F0;             /* 错误态背景 */

嵌套规则：同一页面内背景色层级相差不超过 2 级（如白背景上不能直接放薄雾，中间需要中性背景过渡）。

Step 4.2：文字色规则

为每个背景色定义其上文字的颜色：

秘笈：对比度检查

• 主文字与背景的对比度必须 ≥ 4.5:1（WCAG AA 标准）
• 大标题（≥18px Bold）可放宽至 ≥ 3:1

Step 4.3：边框色规则

特殊规则：强调边框（如卡片左侧 3px border）触发 hover 时变为 var(--accent)。

Phase 5：组件色彩映射（Component Mapping）

Step 5.1：建立映射表

将所有 UI 组件逐一映射到语义 Token：

检验标准：每个组件都明确写出 背景、文字、边框（或标注"无"）、以及交互态（hover/focus/active）。

Step 5.2：状态色映射

Phase 6：字体配套规范（Typography Pairing）

Step 6.1：字体栈定义（铁幕·Iron 裁决式字体系统）

/* 裁决式字体栈 */
font-family-display: 'Playfair Display', 'Noto Serif SC', serif;  /* 英文标题/大标题 */
font-family-serif: 'Noto Serif SC', serif;                        /* 中文标题/数值强调 */
font-family-sans: 'Noto Sans SC', -apple-system, BlinkMacSystemFont, sans-serif; /* 正文/通用 */
font-family-mono: 'JetBrains Mono', 'Fira Code', monospace;       /* 代码/数据/元数据 */

铁幕·Iron 字体使用规则：

• 英文标题：Playfair Display（衬线体，增强权威感）
• 中文标题/数值：Noto Serif SC（衬线体，数据正式感）
• 正文内容：Noto Sans SC（无衬线体，阅读舒适）
• 代码/元数据：JetBrains Mono（等宽体，技术精确感）

Step 6.2：字号字重映射

Phase 7：暗色/多主题适配（Theme Adaptation）

Step 7.1：暗色主题Token覆盖

暗色主题不是"反色"，而是重新映射语义：

/* 暗色主题：只改 Semantic 层，不改 Primitive 层 */
[data-theme="dark"] {
  --color-surface: #1A2332;            /* 主背景变深 */
  --color-surface-secondary: #2A3440;   /* 次要背景 */
  --color-text-primary: #E8EDF2;        /* 文字变浅 */
  --color-text-secondary: #8A9BAE;
  --color-border: #3D4F5F;
  --color-border-light: #2A3440;
  
  /* 品牌色在暗色背景下可能需要调整亮度和饱和度 */
  --color-brand-hover: #1E5A8F;         /* 悬停更亮 */
}

核心原则：

• 不改 --navy, --silver 等 Primitive 值
• 只重新定义 Semantic Token 的映射
• 组件层代码无需改动

Step 7.2：多主题适配清单

• [ ] 每个 Semantic Token 在各主题下都有定义
• [ ] 背景与文字的对比度 ≥ 4.5:1
• [ ] 品牌色在不同背景下仍具有辨识度
• [ ] 功能色（成功/错误/警告）保持语义一致性
• [ ] 图片和图标不依赖主题色（独立处理）

Phase 8：规范文档化交付（Documentation & Delivery）

Step 8.1：文档结构

规范文档必须包含以下章节，按顺序排列：

1. 设计哲学与视觉纪律（铁幕·Iron 核心原则）
2. 基础色板（CSS Variables 完整列表）
3. 核心色系（每个色系的梯度表 + 用途说明）
4. 语义Token映射（Primitive → Semantic 映射表）
5. 文字色规范（各层级 + 背景色对比度规则）
6. 背景色体系（层级 + 嵌套规则）
7. 边框色规范
8. 强调与状态色（功能色完整表）
9. 字体规范（字体栈、字号字重映射、字距规则）
10. 组件色彩映射（组件 → Token 映射表）
11. 暗色/多主题适配（如适用）
12. 设计特点总结（3-7条关键原则）

Step 8.2：交付格式

Step 8.3：质量校验清单

完成规范后逐项检查：

• [ ] 核心品牌色 ≤ 3 个
• [ ] 每个核心色扩展 ≥ 3 阶梯度
• [ ] 中性色覆盖完整明度区间（5-8阶）
• [ ] Token 三层结构完整（Primitive → Semantic → Component）
• [ ] 每个 Token 有明确的用途说明
• [ ] 背景色定义了嵌套规则
• [ ] 文字色在每个背景色上都有指定值
• [ ] 主文字与背景对比度 ≥ 4.5:1
• [ ] 所有 UI 组件都有色彩映射
• [ ] 交互态（hover/focus/active）已定义
• [ ] 功能色语义统一且完整（成功/错误/警告/禁用/信息）
• [ ] 暗色主题（如适用）已定义
• [ ] 文档包含完整的 CSS Variable 声明
• [ ] 视觉纪律检查：零圆角、实色阴影、裁决式字距已定义
• [ ] 配色决策五问已回答
• [ ] 给一个不懂配色的人能拼出一致的页面（终极检验）

四、常见陷阱与避坑指南

五、场景适配指南

六、质量检验清单

• [ ] 触发识别准确：用户的输入确实适合用色彩规范技能处理？
• [ ] 品牌色锚提取到位：能清晰识别 1-3 个核心色？
• [ ] 色板梯度完整：每个核心色 ≥ 3 阶，中性色 ≥ 5 阶？
• [ ] Token 体系完整：Primitive → Semantic → Component 三层都在？
• [ ] 应用规则完整：背景、文字、边框都有明确的定义？
• [ ] 组件映射完整：所有主要 UI 组件都有色彩归属？
• [ ] 字体规范配套：字体栈、字号、字重、行高、字距都有定义？
• [ ] 多主题适配完成：暗色/深色模式 Token 已定义？
• [ ] 文档格式规范：文件命名、YAML frontmatter、结构完整？
• [ ] 铁幕·Iron 视觉纪律：零圆角、实色阴影、裁决式字距已融入？
• [ ] 配色决策五问已回答？
• [ ] 终极检验：给一个不懂配色的人能拼出一致的页面？

七、执行原则

1. 从品牌出发，不凭空造色：色彩规范的根在品牌定位，不要为了"好看"随意加色。
2. 三层Token不可妥协：Primitive → Semantic → Component 少一层都活不久。
3. 语义先于色值：先定义"这是什么角色"再决定"它是什么颜色"。
4. 对比度是硬红线：美观让位于可读性，这是无障碍底线。
5. 组件映射是落地关键：规范只写在文档里不被引用等于没写。
6. 视觉纪律即专业：零圆角、实色阴影、裁决式字距——不是风格，是结构化表达的纪律。
7. 配色决策五问：每次用色前必须回答五个问题，确保一致性。
8. 迭代不止一次交付：规范永远在路上，接受新场景的挑战。
9. 命名即文档：一个好的 Token 命名，不需要注释就能看懂它的用途。