# Common UI Design Spec

> UI设计规范技能，提供设计系统、配色方案、排版规则、无障碍标准等专业UI设计指导

- Skill: `bage2014/common-ui-design-spec` (Agent Skill)
- Install (CLI): `npx skillmds@latest add bage2014/common-ui-design-spec`
- Raw SKILL.md: https://api.skillmd.com/api/skills/bage2014/common-ui-design-spec/raw
- Safety review: pending
- Works with: Claude Code, Claude.ai, OpenAI Codex
- Category: Coding & Dev Tools
- Author: bage2014 (https://skillmd.com/u/bage2014)
- Updated: 2026-09-17
- Page: https://skillmd.com/skills/bage2014/common-ui-design-spec

---


# 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 | 否 | 需要生成规范的组件列表，默认全部 |

## 输出格式

```json
{
  "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",
      "touchTarget": "44px"
    }
  }
}
```

## 使用流程

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 组件规范)