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聚焦、Enter提交）
• 标签与输入框关联（label for）
• 错误状态提供ARIA描述

4.1.2 密码框（Password）

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

组件结构：

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

状态定义：同输入框

尺寸规格：同输入框

交互行为：

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

密码强度等级：

无障碍要求：同输入框

4.1.3 选择器（Select）

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

组件结构：

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

状态定义：同输入框

尺寸规格：同输入框

交互行为：

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

无障碍要求：

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

4.1.4 开关（Switch）

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

组件结构：

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

状态定义：

尺寸规格：

交互行为：

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

无障碍要求：

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

4.2 反馈组件

4.2.1 加载框（Loading）

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

组件结构：

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

类型：

尺寸规格：

交互行为：

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

无障碍要求：

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

4.2.2 提示框（Alert）

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

组件结构：

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

类型：

状态定义：

交互行为：

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

无障碍要求：

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

4.2.3 Toast

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

组件结构：

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

类型：同Alert

位置：

交互行为：

• 自动消失（默认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 ▼]  │  ← 分页器
└──────┴──────┴──────┴──────┘

分页规范：

功能特性：

状态定义：

尺寸规格：

交互行为：

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

无障碍要求：

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

4.3.2 标签（Tag）

描述：用于分类和标记

组件结构：

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

类型：

状态定义：

交互行为：

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

无障碍要求：

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

4.3.3 徽章（Badge）

描述：用于显示通知数量

组件结构：

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

状态定义：

尺寸规格：

交互行为：

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

无障碍要求：

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

4.4 导航组件

4.4.1 面包屑（Breadcrumb）

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

组件结构：

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

状态定义：

交互行为：

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

无障碍要求：

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

4.4.2 标签页（Tabs）

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

组件结构：

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

状态定义：

尺寸规格：

交互行为：

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

无障碍要求：

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

4.5 组件状态设计

通用状态规范：

状态优先级：

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

4.6 交互模式和动画效果

过渡动画：

交互反馈：

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

4.7 响应式设计规则

断点定义：

组件响应式：

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

5. 无障碍标准

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

设计系统结构

颜色系统

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

颜色规范示例：

排版系统

字号层级：
├── 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）

排版规范：

间距系统

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

阴影系统

圆角系统

无障碍标准（WCAG 2.2）

四大原则（POUR）

对比度要求

交互要求

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

输入参数

输出格式

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