管理系统UI 统一设计规范skill
name: ui-design-system
description: 项目 UI 统一设计规范。覆盖组件选用策略、颜色 token 体系、字体排印、间距布局、交互状态、表单搜索模式和可用性规则。
适用场景
- 新建项目时建立视觉基线
- UI 评审时作为一致性门禁
- 组件库选型和定制
一、组件选用策略
UI 能力选择优先级：
1. 项目已有公共组件（src/components/） ↓ 不满足2. Ant Design6内置组件 ↓ 不满足3. 页面内部自研组件（不进入 src/components/） ↓ 确认 ≥2 页面长期复用4. 上提到 src/components/ 成为公共组件禁止：Ant Design 已有的 Button、Modal、Table、Form、Tag、Empty、Spin 等，不自研替代品。
二、颜色 Token 体系
设计原则
- 所有颜色通过 CSS 变量表达，禁止裸色值
- 使用
--app-*前缀命名空间 - 每个颜色同时提供 RGB 版本，用于
rgba(var(--app-*-rgb), alpha)透明度叠加
Token 分层
--app-primary / --app-primary-rgb 主色 --app-primary-dim 主色（弱化） --app-surface / --app-surface-rgb 表面/卡片背景 --app-surface-variant / --app-surface-variant-rgb 次级表面 --app-surface-low / --app-surface-low-rgb 更低层级表面 --app-on-surface 表面上的文字色 --app-on-surface-variant 表面上的次级文字 --app-outline / --app-outline-rgb 边框/分割线 --app-outline-variant / --app-outline-variant-rgb 次级边框 --app-error / --app-error-rgb 错误/危险色 --app-success 成功色 --app-warning 警告色 --app-radius-sm / --app-radius-md / --app-radius-lg 圆角 --app-font-size-sm / --app-font-size-base / --app-font-size-title 字号 --app-line-height-sm / --app-line-height-base / --app-line-height-title 行高亮/暗主题切换
/* 亮色（默认） */:root{--app-primary:#1677ff;--app-primary-rgb:22,119,255;--app-surface:#ffffff;--app-surface-rgb:255,255,255;--app-on-surface:#1a1a1a;}/* 暗色 */:root[data-theme="dark"]{--app-primary:#4096ff;--app-primary-rgb:64,150,255;--app-surface:#141414;--app-surface-rgb:20,20,20;--app-on-surface:#e8e8e8;}主题切换只改document.documentElement.dataset.theme，不操作 DOM class。
使用示例
// ✅ 正确 .my-card { color: var(--app-on-surface); background: rgba(var(--app-surface-variant-rgb), 0.2); border: 1px solid rgba(var(--app-outline-variant-rgb), 0.16); border-radius: var(--app-radius-md); } // ❌ 错误 .my-card { color: #333; background: #f5f5f5; }三、字体排印
字号层级
| Token | 值 | 用途 |
|---|---|---|
--app-font-size-sm | 12px | 标签、辅助文字、badge |
--app-font-size-base | 14px | 正文、表格、表单 |
--app-font-size-title | 16px | 区块标题 |
行高规则
- 正文：1.5（14px 字号）
- 标题：1.4（16px 字号）
- 标签：1.45（12px 字号）
letter-spacing默认0或normal- 字号禁止使用
vw/vh单位
字重
- 标题：600
- 正文：400
- 标签：600
文字颜色
- 主要文字：
var(--app-on-surface) - 次要文字/说明：
var(--app-on-surface-variant) - 链接/可点击文字：
var(--app-primary)
四、间距与布局
间距尺度
| 尺寸 | 值 | 用途 |
|---|---|---|
| xs | 4px | 图标与文字间距 |
| sm | 8px | 同类元素间距 |
| md | 12-16px | 区块内边距、卡片间距 |
| lg | 20-24px | 大区块间距、section padding |
布局模式
页面级：padding: 20px 24px，最大宽度 1440px
卡片级：padding: 20px，圆角var(--app-radius-md)
区块标题：margin-bottom: 14px，padding-left: 4px
网格
- 简单并排：
display: flex; gap: var(--app-gap-md) - 复杂布局：
display: grid; grid-template-columns: ... - 响应式：
@media (max-width: 960px)时切换为单列
五、交互状态
每个交互入口必须覆盖以下状态：
| 状态 | 表达方式 |
|---|---|
| 默认 | 正常渲染 |
| hover | 背景微变、颜色微调 |
| active/pressed | 按压缩放或颜色加深 |
| disabled | 灰色 +cursor: not-allowed |
| loading | Spin 或按钮内 loading 图标 |
| empty | <Empty>组件，有意义的描述文案 |
| error | <Alert>或<Result>展示错误信息 |
状态过渡
- 颜色/背景变化：
transition: all 0.15s ease - 展开/折叠：
transition: max-height 0.25s ease - 淡入：
opacity+transition
删除/危险操作
- 必须弹出确认：
modal.confirm({ title: '确认删除', okButtonProps: { danger: true } }) - 删除按钮颜色：
danger属性或var(--app-error)
六、表单与搜索
搜索表单模式
- 输入框
onChange只更新草稿态 - 回车 / 点击"查询"按钮 → 提交草稿，发起请求，回到第一页
- "重置"按钮 → 清空草稿 + 已提交条件，回到第一页
- 输入框必须支持回车触发搜索
表单项
- 必填项：
rules={[{ required: true }]} - 最大长度：通过
maxLength属性限制 - 占位符：
placeholder="请输入xxx"（中文）
提交按钮
- 提交中：
loading属性，同时禁用按钮防重复 - 表单校验失败时不提交，自动滚动到第一个错误字段
七、数据展示
状态映射
后端状态码不直接展示，必须映射为中文显示值：
constSTATUS_MAP:Record<string,string>={open:'处理中',closed:'已关闭',pending:'待处理',};空值展示
- 文本：显示
-或暂无 - 列表：使用
<Empty>组件 - 可选字段：不显示空标签
时间格式
- 精确到分钟：
2024-07-10 14:30 - 相对时间：
3 分钟前（不超过 24 小时内的场景）
八、可用性
- 图标按钮必须有
title或aria-label - 可点击元素用 Button/Link/Menu 等语义组件，不用
div模拟 - 弹窗必须有
destroyOnClose避免状态残留 - 页面标题使用
h2/h3层级 - 区块使用
<section aria-label="...">标注 - 操作按钮文案表达具体动作：
"创建工单"而非"提交"、"确认删除"而非"确定"