ui-design-system

UI 设计系统

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

---

目录

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

---

触发词

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

• "generate design tokens"
• "create color palette"
• "build typography scale"
• "calculate spacing system"
• "create design system"
• "generate CSS variables"
• "export SCSS tokens"
• "set up component architecture"
• "document component library"
• "calculate responsive breakpoints"
• "prepare developer handoff"
• "convert brand color to palette"
• "check WCAG contrast"
• "build 8pt grid system"

---

工作流

工作流 1：生成设计令牌

场景： 你有一个品牌主色，需要一套完整的设计令牌系统。

步骤：

1. 确定品牌主色和风格

   • 品牌主色（十六进制格式）
   • 风格偏好：modern | classic | playful

2. 使用脚本生成令牌

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

3. 检查生成的类别

   • 颜色：primary、secondary、neutral、semantic、surface
   • 字体排版：fontFamily、fontSize、fontWeight、lineHeight
   • 间距：基于 8pt 网格的比例（0-64）
   • 边框：radius、width
   • 阴影：none 至 2xl
   • 动画：duration、easing
   • 断点：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. 定义组件层级

   • 原子组件：Button、Input、Icon、Label、Badge
   • 分子组件：FormField、SearchBar、Card、ListItem
   • 有机体组件：Header、Footer、DataTable、Modal
   • 模板：DashboardLayout、AuthLayout

2. 将令牌映射到组件

   组件	使用的令牌
   Button	colors、sizing、borders、shadows、typography
   Input	colors、sizing、borders、spacing
   Card	colors、borders、shadows、spacing
   Modal	colors、shadows、spacing、z-index、animation

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

   • 带类型的 Props 接口
   • 变体选项
   • 状态处理（hover、active、focus、disabled）
   • 无障碍要求

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 变量：

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

   Tailwind 配置：

   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	十六进制颜色	#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.25 倍比例）

尺寸	数值	计算方式
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	原子设计、命名约定、props 模式
responsive-calculations.md	断点、流体字体、网格系统
developer-handoff.md	导出格式、框架设置、Figma 同步

---

验证检查清单

令牌生成

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

组件系统

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

无障碍

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

开发交接

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