common-ui-design-spec

name	common-ui-design-spec
description	UI设计规范技能，提供设计系统、配色方案、排版规则、无障碍标准等专业UI设计指导
trigger	需要创建或遵循UI设计规范时
disable-when	已有成熟的设计系统且无需变更时
category	common
tags	["ui","design","spec","system","accessibility","wcag"]

common-ui-design-spec

功能描述

UI设计规范技能提供专业的设计系统指导，包括配色方案、排版规则、间距系统、组件规范、无障碍标准等。基于业界最佳实践，帮助团队建立统一的视觉语言和交互规范。

触发条件

• 新项目需要建立设计系统时
• 需要为产品定义配色方案时
• 需要确保无障碍设计合规时
• 需要统一组件样式和交互规范时

何时使用

• 项目初始化阶段需要定义设计规范时
• 开发过程中需要参考设计规范时
• 代码审查时需要检查设计合规性时
• 需要生成设计文档时

何时不使用

• 已有完善的设计系统且无需调整时
• 仅需要简单的页面修改时
• 用户明确不需要设计规范时

核心功能

1. 设计系统定义

• 颜色系统（主色、辅色、中性色、语义色）
• 排版系统（字体、字号、行高、字重）
• 间距系统（统一的间距令牌）
• 阴影系统（层级和深度）
• 圆角系统（统一的圆角大小）

2. 配色方案

• 行业适配的配色方案推荐
• 对比度检查（WCAG 2.1 AA/AAA）
• 配色方案生成器
• 深色模式支持

3. 排版规则

• 字体选择和组合
• 字号层级系统
• 行高和字间距
• 可读性最佳实践

4. 组件规范

4.1 表单组件

4.1.1 输入框（Input）

描述：用于接收用户输入的文本框

组件结构：

┌─────────────────────────────────┐
│  [图标] 输入占位符 [清除按钮]     │
└─────────────────────────────────┘

状态定义：

状态	样式	说明
默认	灰色边框	未交互状态
聚焦	主色边框 + 阴影	用户点击或Tab进入
悬停	边框变深	鼠标悬停
禁用	灰色背景 + 禁用光标	不可输入
错误	红色边框 + 错误图标	输入校验失败
成功	绿色边框 + 成功图标	输入校验通过

尺寸规格：

尺寸	高度	字体大小
xs	32px	12px
sm	36px	13px
md	40px	14px
lg	48px	16px

交互行为：

• 聚焦时显示清除按钮（有内容时）
• 支持前缀/后缀图标
• 支持字数统计
• 回车触发提交

无障碍要求：

• 支持键盘导航（Tab聚焦、Enter提交）
• 标签与输入框关联（label for）
• 错误状态提供ARIA描述

4.1.2 密码框（Password）

描述：用于输入密码的安全输入框

组件结构：

┌─────────────────────────────────┐
│  [锁图标] ******** [眼睛图标]    │
└─────────────────────────────────┘

状态定义：同输入框

尺寸规格：同输入框

交互行为：

• 默认隐藏密码（显示●●●●）
• 点击眼睛图标切换显示/隐藏
• 支持密码强度提示条

密码强度等级：

等级	颜色	条件
弱	红色	< 6位或单一字符类型
中	橙色	6-8位或两种字符类型
强	绿色	≥ 8位且三种字符类型

无障碍要求：同输入框

4.1.3 选择器（Select）

描述：用于从选项列表中选择值

组件结构：

┌─────────────────────────────────┐
│  请选择 [下拉箭头]               │
└─────────────────────────────────┘
            ▼
┌─────────────────────────────────┐
│  [勾选] 选项1                    │
│  [勾选] 选项2                    │
│  [勾选] 选项3                    │
└─────────────────────────────────┘

状态定义：同输入框

尺寸规格：同输入框

交互行为：

• 点击展开下拉列表
• 支持搜索过滤
• 支持多选（复选框）
• 支持远程搜索

无障碍要求：

• 键盘上下键导航选项
• Enter确认选择
• Esc关闭下拉

4.1.4 开关（Switch）

描述：用于切换两种状态（开/关）

组件结构：

┌───────┐     ┌─────────────┐
│   ●   │     │       ●     │
└───────┘     └─────────────┘
  关闭状态        开启状态

状态定义：

状态	样式	说明
开启	主色背景，圆点在右	状态为真
关闭	灰色背景，圆点在左	状态为假
禁用	半透明	不可切换

尺寸规格：

尺寸	宽度	高度
sm	32px	18px
md	40px	22px
lg	48px	26px

交互行为：

• 点击切换状态
• 支持拖拽切换
• 切换时有过渡动画

无障碍要求：

• 键盘Space切换
• 提供ARIA状态描述

4.2 反馈组件

4.2.1 加载框（Loading）

描述：用于表示操作正在进行中

组件结构：

┌─────────────────────────────────┐
│     ○○○                          │  ← 旋转动画
│     加载中...                     │
└─────────────────────────────────┘

类型：

类型	说明	适用场景
旋转器	圆形旋转动画	轻量级加载
骨架屏	占位骨架	页面级加载
进度条	进度指示	文件上传、任务进度
按钮加载	按钮内旋转器	提交操作

尺寸规格：

尺寸	直径	边框宽度
sm	20px	2px
md	28px	3px
lg	40px	4px

交互行为：

• 加载时禁用交互
• 支持自定义加载文案
• 支持全屏遮罩

无障碍要求：

• 提供ARIA live区域通知加载状态
• 加载完成后恢复焦点

4.2.2 提示框（Alert）

描述：用于向用户显示重要信息

组件结构：

┌─────────────────────────────────┐
│ [图标] 提示内容 [关闭按钮]        │
└─────────────────────────────────┘

类型：

类型	颜色	图标	用途
Info	蓝色	信息图标	一般信息提示
Success	绿色	成功图标	操作成功提示
Warning	橙色	警告图标	需要注意的信息
Error	红色	错误图标	错误信息提示

状态定义：

状态	说明
默认	显示提示内容
关闭	点击关闭按钮隐藏
可关闭	显示关闭按钮
不可关闭	无关闭按钮

交互行为：

• 支持自动关闭（可配置时长）
• 支持手动关闭
• 支持点击遮罩关闭

无障碍要求：

• 使用ARIA role="alert"
• 支持键盘Esc关闭

4.2.3 Toast

描述：用于短暂显示操作结果

组件结构：

          ┌─────────────────┐
          │ [图标] 提示内容   │
          └─────────────────┘

类型：同Alert

位置：

位置	说明
top-center	顶部居中
top-right	顶部右侧
bottom-center	底部居中
bottom-right	底部右侧

交互行为：

• 自动消失（默认3秒）
• 点击可手动关闭
• 多个Toast堆叠显示

无障碍要求：

• 使用ARIA live区域
• 不打断用户操作

4.2.4 进度条（Progress）

描述：用于显示任务进度

组件结构：

┌─────────────────────────────────┐
│ ████████████░░░░░░░░░░░░░░░░░   │
│           50%                   │
└─────────────────────────────────┘

类型：

类型	说明
线性	水平进度条
环形	圆形进度指示器
仪表盘	半圆进度指示器

状态定义：

状态	样式
进行中	主色进度条
成功	绿色进度条
错误	红色进度条
暂停	橙色进度条

交互行为：

• 实时更新进度
• 支持进度标签显示
• 支持动画效果

无障碍要求：

• 使用ARIA role="progressbar"
• 提供aria-valuenow/aria-valuemin/aria-valuemax

4.3 数据展示组件

4.3.1 表格（Table）

描述：用于展示结构化数据

组件结构：

┌──────┬──────┬──────┬──────┐
│ 列1  │ 列2  │ 列3  │ 操作  │  ← 表头（可固定）
├──────┼──────┼──────┼──────┤
│ 数据 │ 数据 │ 数据 │ [按钮] │  ← 数据行
│ 数据 │ 数据 │ 数据 │ [按钮] │
│ 数据 │ 数据 │ 数据 │ [按钮] │
├──────┼──────┼──────┼──────┤
│ 共100条  1/10  [上一页] [下一页]  页大小：[10 ▼]  │  ← 分页器
└──────┴──────┴──────┴──────┘

分页规范：

项目	说明
默认页大小	10
可选页大小	10 / 20 / 50
分页器位置	底部居中
分页信息	显示总数、当前页/总页数
跳转	支持输入页码跳转

功能特性：

特性	说明
排序	点击表头切换升序/降序
筛选	表头下拉筛选
行选择	单选/多选（复选框）
固定表头	滚动时表头固定
固定列	首列/末列固定
加载态	骨架屏或加载提示
空状态	无数据时显示空状态提示

状态定义：

状态	说明
正常	显示数据
加载中	骨架屏或加载动画
空状态	显示空状态图标和提示
错误状态	显示错误提示和重试按钮

尺寸规格：

项目	规格
行高	48px
表头高度	44px
表格边框	1px #E8E8E8
单元格内边距	12px 16px

交互行为：

• 点击表头排序
• 点击复选框选择行
• 双击行可编辑（如支持）
• 支持拖拽调整列宽

无障碍要求：

• 使用语义化表格结构（thead/tbody/th）
• 支持键盘导航（上下键切换行）
• 筛选下拉支持键盘操作

4.3.2 标签（Tag）

描述：用于分类和标记

组件结构：

┌──────────┐
│ 标签内容 [×] │
└──────────┘

类型：

类型	颜色	用途
默认	灰色	普通标签
主色	主色背景	重要标签
成功	绿色	成功状态
警告	橙色	警告状态
错误	红色	错误状态

状态定义：

状态	说明
默认	显示标签
可关闭	显示关闭按钮
选中	高亮显示

交互行为：

• 点击关闭按钮移除标签
• 支持点击选中/取消选中

无障碍要求：

• 使用ARIA role="tag"
• 关闭按钮支持键盘操作

4.3.3 徽章（Badge）

描述：用于显示通知数量

组件结构：

    ┌─┐
    │5│  ← 徽章
┌───┴─┴───┐
│ 图标/按钮 │
└──────────┘

状态定义：

状态	说明
默认	显示数量
圆点	只显示红点（无数字）
最大值	超过99显示99+
零值	隐藏或显示0

尺寸规格：

尺寸	宽度	高度	字体大小
sm	18px	18px	10px
md	20px	20px	12px
lg	24px	24px	14px

交互行为：

• 点击清除通知
• 悬停显示详情

无障碍要求：

• 使用ARIA role="status"
• 提供数量描述

4.4 导航组件

4.4.1 面包屑（Breadcrumb）

描述：用于显示当前页面在层级结构中的位置

组件结构：

首页 / 产品中心 / 电子产品 / 手机  ← 当前页面

状态定义：

状态	样式
当前页	主色文字
可点击	灰色文字，悬停变主色
分隔符	/（可自定义）

交互行为：

• 点击导航到对应页面
• 支持下拉菜单（有子项时）

无障碍要求：

• 使用ARIA role="navigation"
• 使用ol/li语义化结构

4.4.2 标签页（Tabs）

描述：用于在同一区域切换不同内容

组件结构：

┌─────────────────────────────────┐
│ [标签1 ●] [标签2] [标签3]        │  ← 标签栏
├─────────────────────────────────┤
│                                 │
│      标签1的内容区域             │
│                                 │
└─────────────────────────────────┘

状态定义：

状态	样式
激活	主色文字 + 底部下划线
未激活	灰色文字
悬停	文字变深
禁用	灰色禁用样式

尺寸规格：

项目	规格
标签高度	48px
标签间距	24px
下划线宽度	与文字等宽
下划线高度	2px

交互行为：

• 点击切换标签
• 支持键盘左右键切换
• 支持懒加载（点击时加载内容）

无障碍要求：

• 使用ARIA role="tablist/tab/tabpanel"
• 标签与内容区域关联

4.5 组件状态设计

通用状态规范：

状态	定义	触发条件
默认	初始状态	页面加载完成
悬停	鼠标悬停	onMouseEnter
聚焦	键盘聚焦	onFocus
激活	点击按下	onMouseDown
禁用	不可交互	disabled=true
错误	校验失败	表单验证失败
成功	校验通过	表单验证通过
加载	数据加载中	异步请求中

状态优先级：

禁用 > 加载 > 错误 > 成功 > 聚焦 > 悬停 > 默认

4.6 交互模式和动画效果

过渡动画：

场景	动画类型	时长
组件显隐	淡入淡出	200ms
展开收起	高度变化	300ms
状态切换	颜色渐变	150ms
弹出层	缩放 + 淡入	200ms

交互反馈：

• 点击按钮有按压效果
• 悬停时有视觉变化
• 操作成功/失败有明确反馈
• 加载状态有进度指示

4.7 响应式设计规则

断点定义：

设备	断点	布局策略
手机	< 576px	单列布局，隐藏次要内容
平板	576px - 768px	双列布局
桌面	768px - 992px	标准布局
大屏	≥ 992px	完整布局

组件响应式：

• 表格在移动端可横向滚动或转为卡片
• 表单在移动端堆叠排列
• 导航在移动端转为汉堡菜单
• 按钮在移动端全宽显示

5. 无障碍标准

• WCAG 2.2 合规检查
• 键盘导航支持
• 屏幕阅读器兼容性
• 颜色对比度要求

设计系统结构

颜色系统

颜色分类：
├── Primary（主色）- 品牌识别色
├── Secondary（辅色）- 辅助功能色
├── Neutral（中性色）- 文本和背景
├── Semantic（语义色）- 成功/警告/错误/信息
└── Accent（强调色）- 点缀和突出

颜色规范示例：

颜色	用途	十六进制
Primary	品牌主色	#0052CC
Primary Light	主色浅版	#E5F0FF
Secondary	辅色	#F2F4F7
Success	成功状态	#36B37E
Warning	警告状态	#FFAB00
Error	错误状态	#E53935
Info	信息提示	#177FFF

排版系统

字号层级：
├── Display 1 - 超大标题（48px）
├── Display 2 - 大标题（36px）
├── Heading 1 - 一级标题（24px）
├── Heading 2 - 二级标题（20px）
├── Heading 3 - 三级标题（18px）
├── Body Large - 大正文（16px）
├── Body - 正文（14px）
├── Body Small - 小正文（12px）
└── Caption - 说明文字（11px）

排版规范：

元素	字号	行高	字重
标题 H1	24px	1.2	600
标题 H2	20px	1.3	600
正文	14px	1.5	400
小文字	12px	1.4	400

间距系统

间距令牌（基于4px基准）：
├── 0 - 0px
├── xs - 4px
├── sm - 8px
├── md - 16px
├── lg - 24px
├── xl - 32px
├── 2xl - 48px
└── 3xl - 64px

阴影系统

层级	用途	CSS值
Shadow 0	无阴影	none
Shadow 1	卡片悬浮	0 2px 4px rgba(0,0,0,0.06)
Shadow 2	卡片默认	0 4px 12px rgba(0,0,0,0.08)
Shadow 3	弹窗	0 8px 24px rgba(0,0,0,0.12)
Shadow 4	模态框	0 16px 48px rgba(0,0,0,0.16)

圆角系统

大小	用途	CSS值
none	直角	0
sm	小圆角	4px
md	默认圆角	8px
lg	大圆角	12px
xl	超大圆角	16px
full	圆形	9999px

无障碍标准（WCAG 2.2）

四大原则（POUR）

原则	描述	关键要求
Perceivable	可感知	对比度4.5:1、替代文本、字幕
Operable	可操作	键盘导航、44px触摸目标、跳过链接
Understandable	可理解	清晰标签、错误提示、一致导航
Robust	健壮性	语义HTML、ARIA、屏幕阅读器兼容

对比度要求

文本类型	AA标准	AAA标准
正常文本（<18pt）	4.5:1	7:1
大文本（≥18pt）	3:1	4.5:1
UI组件/图形	3:1	4.5:1

交互要求

• 触摸目标最小 44×44px
• 焦点指示器可见（3:1对比度）
• 所有交互元素支持键盘操作
• 时间限制内容可暂停/延长

输入参数

参数名	类型	必填	说明
projectType	String	是	项目类型（saas/ecommerce/enterprise/consumer等）
brandColor	String	否	品牌主色，十六进制
colorScheme	String	否	配色方案（light/dark/system）
fontSizeBase	Number	否	基础字号，默认14
accessibilityLevel	String	否	无障碍级别（aa/aaa），默认aa
components	Array	否	需要生成规范的组件列表，默认全部

输出格式

{
  "designSystem": {
    "colors": {
      "primary": "#0052CC",
      "secondary": "#F2F4F7",
      "success": "#36B37E"
    },
    "typography": {
      "fontFamily": "Inter, -apple-system, sans-serif",
      "baseSize": 14,
      "lineHeight": 1.5
    },
    "spacing": {
      "xs": 4,
      "sm": 8,
      "md": 16
    },
    "accessibility": {
      "contrastRatio": "4.5:1"
       
    
  

使用流程

1. 确定项目类型和品牌色
2. 生成设计系统配置
3. 应用到组件和页面
4. 验证无障碍合规性
5. 输出设计规范文档

最佳实践

1. 系统优先：使用设计令牌而非硬编码值
2. 一致性：保持颜色、间距、字体的统一
3. 无障碍优先：设计阶段考虑WCAG合规
4. 响应式设计：适配多种屏幕尺寸
5. 状态完整：设计所有状态（正常/悬停/禁用/错误）

参考来源：

• https://mohablog.com/python-ai-ui-ux-skill-development/
• https://skillmd.ai/how-to-build/uiux-design-expert/
• https://github.com/gabeosx/agent-skills/blob/main/skills/ux-designer/SKILL.md
• https://ant.design/ (Ant Design 组件规范)
• https://m3.material.io/ (Material Design 3)
• https://arco.design/ (Arco Design 组件规范)