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; }

三、字体排印

字号层级

行高规则

• 正文：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)

四、间距与布局

间距尺度

布局模式

页面级：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)时切换为单列

五、交互状态

每个交互入口必须覆盖以下状态：

状态过渡

• 颜色/背景变化：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="...">标注
• 操作按钮文案表达具体动作："创建工单"而非"提交"、"确认删除"而非"确定"