ui-design-system

UI 设计系统

生成设计令牌、创建调色板、计算排版比例、构建组件系统，并准备开发者交接文档。

---

目录

• 触发词
• 工作流
  • 工作流 1：生成设计令牌
  • 工作流 2：创建组件系统
  • 工作流 3：响应式设计
  • 工作流 4：开发者交接
• 工具参考
• 快速参考表
• 知识库

---

触发词

在以下情况下使用此技能：

• “生成设计令牌”
• “创建调色板”
• “构建排版比例”
• “计算间距系统”
• “创建设计系统”
• “生成 CSS 变量”
• “导出 SCSS 令牌”
• “设置组件架构”
• “记录组件库文档”
• “计算响应式断点”
• “准备开发者交接”
• “将品牌色转换为调色板”
• “检查 WCAG 对比度”
• “构建 8pt 网格系统”

---

请先澄清

生成令牌或系统之前，请确认以下信息。如果有任何信息未知或含糊，请提问，不要自行假设：

• 品牌主色（hex） — 完整调色板的基础色（决定色阶并用于 WCAG 对比度检查）
• 风格预设 — 现代、经典或活泼（决定字体、圆角和阴影样式）
• 输出格式和框架 — 用于 Tailwind/styled-components/Figma 的 CSS、SCSS 或 JSON（决定导出方式和开发者交接内容）

停止规则：只询问对输出影响最大的 2-3 项。如果用户说“先随便起草”，则继续操作，并在交付内容开头列出你的假设。

工作流

工作流 1：生成设计令牌

情景： 已有品牌色，需要一套完整的设计令牌系统。

步骤：

1. 确定品牌色和风格

   • 品牌主色（hex 格式）
   • 风格偏好：modern | classic | playful

2. 使用脚本生成令牌

   python scripts/design_token_generator.py "#0066CC" modern json
   

3. 检查生成的类别

   • 颜色：主色、辅助色、中性色、语义色、表面色
   • 排版：fontFamily、fontSize、fontWeight、lineHeight
   • 间距：基于 8pt 网格的比例（0-64）
   • 边框：圆角、宽度
   • 阴影：从 none 到 2xl
   • 动画：时长、缓动
   • 断点：从 xs 到 2xl

4. 导出为目标格式

   # CSS custom properties
   python scripts/design_token_generator.py "#0066CC" modern css > design-tokens.css
   
   # SCSS variables
   python scripts/design_token_generator.py "#0066CC" modern scss > _design-tokens.scss
   
   # JSON for Figma/tooling
   python scripts/design_token_generator.py "#0066CC" modern json > design-tokens.json
   

5. 验证无障碍性

   • 检查颜色对比度是否符合 WCAG AA（普通文本为 4.5:1，大号文本为 3:1）
   • 确认已为语义色定义对比色

---

工作流 2：创建组件系统

情景： 需要使用设计令牌构建组件库结构。

步骤：

1. 定义组件层级

   • 原子：按钮、输入框、图标、标签、徽标
   • 分子：表单字段、搜索栏、卡片、列表项
   • 有机体：页眉、页脚、数据表格、模态框
   • 模板：DashboardLayout、AuthLayout

2. 将令牌映射到组件

   组件	使用的令牌
   按钮	颜色、尺寸、边框、阴影、排版
   输入框	颜色、尺寸、边框、间距
   卡片	颜色、边框、阴影、间距
   模态框	颜色、阴影、间距、z-index、动画

3. 定义变体模式

   尺寸变体：

   sm: height 32px, paddingX 12px, fontSize 14px
   md: height 40px, paddingX 16px, fontSize 16px
   lg: height 48px, paddingX 20px, fontSize 18px
   

   颜色变体：

   primary: background primary-500, text white
   secondary: background neutral-100, text neutral-900
   ghost: background transparent, text neutral-700
   

4. 记录组件 API

   • 属性接口及类型
   • 变体选项
   • 状态处理（悬停、激活、聚焦、禁用）
   • 无障碍性要求

5. 参考： 请参阅 references/component-architecture.md

---

工作流 3：响应式设计

场景： 你需要设置断点、流体排版或响应式间距。

步骤：

1. 定义断点

   名称	宽度	目标设备
   xs	0	小型手机
   sm	480px	大型手机
   md	640px	平板电脑
   lg	768px	小型笔记本电脑
   xl	1024px	台式电脑
   2xl	1280px	大屏幕

2. 计算流体排版

   公式：clamp(min, preferred, max)

   /* 16px to 24px between 320px and 1200px viewport */
   font-size: clamp(1rem, 0.5rem + 2vw, 1.5rem);
   

   预先计算的比例：

   --fluid-h1: clamp(2rem, 1rem + 3.6vw, 4rem);
   --fluid-h2: clamp(1.75rem, 1rem + 2.3vw, 3rem);
   --fluid-h3: clamp(1.5rem, 1rem + 1.4vw, 2.25rem);
   --fluid-body: clamp(1rem, 0.95rem + 0.2vw, 1.125rem);
   

3. 设置响应式间距

   令牌	移动端	平板电脑	桌面端
   --space-md	12px	16px	16px
   --space-lg	16px	24px	32px
   --space-xl	24px	32px	48px
   --space-section	48px	80px	120px

4. 参考： 参见 references/responsive-calculations.md

---

工作流 4：开发交接

场景： 你需要将设计令牌交接给开发团队。

步骤：

1. 以所需格式导出令牌

   # For CSS projects
   python scripts/design_token_generator.py "#0066CC" modern css
   
   # For SCSS projects
   python scripts/design_token_generator.py "#0066CC" modern scss
   
   # For JavaScript/TypeScript
   python scripts/design_token_generator.py "#0066CC" modern json
   

2. 准备框架集成

   React + CSS Variables：

   import './design-tokens.css';
   
   <button className="btn btn-primary">Click</button>
   

   Tailwind Config：

   const tokens = require('./design-tokens.json');
   
   module.exports = {
     theme: {
       colors: tokens.colors,
       fontFamily: tokens.typography.fontFamily
     }
   };
   

   styled-components：

   import tokens from './design-tokens.json';
   
   const Button = styled.button`
     background: ${tokens.colors.primary['500']};
     padding: ${tokens.spacing['2']} ${tokens.spacing['4']};
   `;
   

3. 与 Figma 同步

   • 安装 Tokens Studio 插件
   • 导入 design-tokens.json
   • 令牌会自动与 Figma 样式同步

4. 交接检查清单

   • 已将令牌文件添加到项目中
   • 已配置构建流水线
   • 已导入主题/CSS 变量
   • 组件库已对齐
   • 已生成文档

5. 参考： 参见 references/developer-handoff.md

---

工具参考

design_token_generator.py

根据品牌颜色生成完整的设计令牌系统。

参数	可选值	默认值	说明
brand_color	Hex 颜色	#0066CC	品牌主色
style	modern, classic, playful	modern	设计风格预设
format	json, css, scss, summary	json	输出格式

示例：

# Generate JSON tokens (default)
python scripts/design_token_generator.py "#0066CC"

# Classic style with CSS output
python scripts/design_token_generator.py "#8B4513" classic css

# Playful style summary view
python scripts/design_token_generator.py "#FF6B6B" playful summary

输出类别：

类别	说明	关键值
colors	色板	primary, secondary, neutral, semantic, surface
typography	字体系统	fontFamily, fontSize, fontWeight, lineHeight
spacing	8pt 网格	0-64 比例、语义间距（xs-3xl）
sizing	组件尺寸	container, button, input, icon
borders	边框值	radius（按样式）、width
shadows	阴影样式	none 至 2xl、inner
animation	动效令牌	duration, easing, keyframes
breakpoints	响应式断点	xs, sm, md, lg, xl, 2xl
z-index	层级系统	从 base 到 notification

---

快速参考表

颜色比例生成

步骤	亮度	饱和度	使用场景
50	固定为 95%	30%	微妙的背景
100	固定为 95%	38%	浅色背景
200	固定为 95%	46%	悬停状态
300	固定为 95%	54%	边框
400	固定为 95%	62%	禁用状态
500	原始值	70%	基础/默认颜色
600	原始值 × 0.8	78%	深色悬停状态
700	原始值 × 0.6	86%	激活状态
800	原始值 × 0.4	94%	文本
900	原始值 × 0.2	100%	标题

排版比例（1.25x 比率）

尺寸	值	计算方式
xs	10px	16 ÷ 1.25²
sm	13px	16 ÷ 1.25¹
base	16px	基础值
lg	20px	16 × 1.25¹
xl	25px	16 × 1.25²
2xl	31px	16 × 1.25³
3xl	39px	16 × 1.25⁴
4xl	49px	16 × 1.25⁵
5xl	61px	16 × 1.25⁶

WCAG 对比度要求

等级	普通文本	大号文本
AA	4.5:1	3:1
AAA	7:1	4.5:1

大号文本：常规字重 ≥18pt 或粗体 ≥14pt

样式预设

方面	Modern	Classic	Playful
无衬线字体	Inter	Helvetica	Poppins
等宽字体	Fira Code	Courier	Source Code Pro
默认圆角	8px	4px	16px
阴影	多层、微妙	单层	柔和、明显

---

知识库

references/ 中的详细参考指南：

文件	内容
token-generation.md	颜色算法、HSV 色彩空间、WCAG 对比度、字体比例
component-architecture.md	原子化设计、命名约定、属性模式
responsive-calculations.md	断点、流体排版、网格系统
developer-handoff.md	导出格式、框架设置、Figma 同步

---

验证清单

令牌生成

• 已提供十六进制格式的品牌颜色
• 样式符合项目要求
• 已生成所有令牌类别
• 语义颜色包含对比度值

组件系统

• 已实现所有尺寸（sm、md、lg）
• 已实现所有变体（primary、secondary、ghost）
• 所有状态均正常工作（hover、active、focus、disabled）
• 仅使用设计令牌（无硬编码值）

无障碍访问

• 颜色对比度符合 WCAG AA
• 焦点指示器清晰可见
• 触控目标 ≥ 44×44px
• 使用语义化 HTML 元素

开发者交接

• 已按要求的格式导出令牌
• 已记录框架集成方式
• 已同步设计工具
• 已完成组件文档

---

故障排除

问题	原因	解决方案
生成的颜色未通过 WCAG 对比度检查	品牌颜色过浅或饱和度过高	在浅色背景上使用更深的色阶（600+）显示文本；使用对比度工具检查
令牌导出值不正确	格式参数或颜色语法错误	确保十六进制颜色带引号（例如 "#0066CC"）；确认格式为 json、css 或 scss
字体比例过大或过小	默认的 1.25x 比例不适合设计	修改 DesignTokenGenerator 类中的 type_scale_ratio（更紧凑时设为 1.125，更宽松时设为 1.333）
SCSS 变量与现有变量冲突	令牌命名冲突	为所有令牌添加项目命名空间前缀（编辑导出函数）
设计工具显示的颜色不一致	生成颜色比例时十六进制值发生舍入	使用 JSON 导出作为真实数据源；通过 Tokens Studio 插件同步
间距值与网格不对齐	自定义间距与 8pt 网格混用	仅使用生成的间距系统中的值；避免使用任意像素值
暗色模式下的阴影令牌显示异常	阴影针对浅色背景设计	创建单独的暗色模式阴影令牌，并使用较低的不透明度值

---

成功标准

标准	目标	衡量方式
令牌一致性	代码库中不含硬编码的颜色／间距值	Lint 规则违规次数
符合 WCAG AA	所有文本颜色的对比度均达到 4.5:1	自动对比度检查器或人工审查
导出格式覆盖	CSS、SCSS 和 JSON 均可正确生成	使用每种格式运行生成器；验证输出
设计与开发同步	令牌更新到代码部署间隔 <24h	从 Figma 变更到上线所需的时间
组件令牌覆盖率	100% 的组件使用设计令牌	审查组件样式中的硬编码值
字体排版一致性	所有文本均使用设计系统的字体比例	对所有页面进行视觉审查
响应式行为	流体排版在所有断点下均正常工作	在 xs、sm、md、lg、xl、2xl 宽度下测试

---

范围与限制

范围内：

• 根据品牌色生成完整的设计令牌
• 生成调色板（主色、辅助色、中性色、语义色）
• 带有模块化比例的字体排版系统
• 基于 8pt 网格的间距系统
• 组件尺寸、边框、阴影和动画令牌
• 导出为 CSS 自定义属性、SCSS 变量和 JSON
• 响应式断点定义
• WCAG 对比度参考表

范围外：

• 暗色模式令牌生成（需要单独映射调色板）
• 动画／动效设计库
• 图标系统生成
• 运行时主题切换实现
• Figma 插件或 API 集成（使用 Tokens Studio）
• 视觉回归测试
• 设计稿转代码（使用 Figma Dev Mode 或 Locofy）

---

集成点

工具／平台	集成方式	用例
Figma / Tokens Studio	将 JSON 输出导入为令牌源	将设计工具与代码令牌同步
Tailwind CSS	将 JSON 令牌用作 tailwind.config.js 主题	根据设计系统配置 Tailwind
styled-components / Emotion	在主题提供程序中导入 JSON 令牌	CSS-in-JS 主题化
Style Dictionary	将 JSON 输出用作源令牌	多平台令牌构建（iOS、Android、Web）
Storybook	将令牌与组件故事配合使用	记录组件的视觉变化
CI/CD	在构建流水线中生成令牌	品牌变更时自动更新令牌