# UI 设计规范(框架式:设计令牌 + 官方组件底座 + 防遮挡安全)

> 定位:**框架式 UI 规范**——只定义「整体基调」(配色/字体/动画时长等设计令牌)与「组件复用纪律」「防遮挡安全」三件事;**具体页面与组件视觉由 AI 按本框架自主完成,暂不对单页面效果做精细化定义**。适配企业交付场景:用户不参与设计决策(业务调性问题除外),AI 按业务类型默认定调性(后台管理→克制专业;数据看板→清晰层级;门户/营销→品牌表现力)。完整方法论见技能 `.claude/skills/ui-new`、`ui-ux-design`、`ui-ux-pro-max`、`superdesign`、`ui-audit`;技术实现一律落在 04-技术栈规范 栈内(Angular + Tailwind),禁止引入任何第三方 UI 库;**组件层一律以包内官方组件底座(ui-kit)为唯一来源**(复制步骤与依赖见 `ui-kit/README使用说明.md`),见「二、组件复用纪律」。

## 负面清单(Do Not)

- [禁止] **使用浏览器原生控件直接承载交互**(零样式原生 button/input/select/checkbox/dialog 等):所有组件必须经官方底座或其扩展封装后使用
- [禁止] **引入任何第三方 UI 组件库**(Angular Material/NG-ZORRO/PrimeNG/Ant Design 等):组件层一律使用官方底座 ui-kit 及其扩展
- [禁止] 复用此前试做的旧版 ui-kit 组件与样式(效果未达预期,已否决;**本条仅针对旧试做库,现行官方底座 ui-kit 不受此限,且为默认组件来源**)
- [禁止] **对单页面效果做精细化定义**:不写页面级像素规格、视觉稿级描述、逐页线框;单页视觉由 AI 在框架内自主发挥
- [禁止] **遮挡、覆盖**:固定/悬浮元素不设层级或不按分层表取值;内容区被固定顶栏/侧栏/底部栏遮挡;文本与内容溢出无截断/滚动处理
- [禁止] 颜色/字号/时长/间距写魔法值(必须来自设计令牌);通用默认色(如 #007bff)
- [禁止] 同一界面出现 16 种以上颜色;仅用颜色传达信息(必须配文字/图标)
- [禁止] 对比度低于 WCAG AA(正文 4.5:1、大字与 UI 组件 3:1);移动端可点击区域小于 44×44px;正文字号小于 16px
- [禁止] 无意义动画、微交互时长超过 600ms、忽略 prefers-reduced-motion
- [禁止] 组件只有默认态,缺失 Hover/Active/Focus/Disabled/Loading 或空/加载/错误三态
- [禁止] 绕过底座重复造轮子:底座已有组件不允许在业务项目里另写一套同功能组件
- [禁止] 把色值、间距、组件选型等技术设计决策抛给非技术用户(按 01-沟通协作.md 澄清分级,业务语义层面才问)

## 一、设计令牌(框架基座,与官方底座同源)

设计令牌以官方底座 ui-kit 的 token 体系为准(`src/styles.css` 定义 CSS 变量,`tailwind.config.js` 映射为工具类),业务项目引入底座时整套继承,禁止另起一套 token:

1. **[必须] 配色四件套**:表面(`--canvas`/`--surface`/`--surface-2`/`--surface-hover`/`--surface-active`)、边框(`--edge`/`--edge-strong`)、文本(`--ink`/`--ink-2`/`--muted`/`--faint`/`--inverse`)、主色与语义色(`--primary` 系列 + success/danger/warning/info 及其 subtle 变体);模板只写语义工具类(`bg-surface`/`text-ink`/`border-edge`/`bg-primary` 等),组件禁止写死颜色;**明暗两套主题**(`<html class="dark">` 覆盖变量)与**主题色切换**(`<html data-accent="blue|violet|emerald|rose|amber|cyan">`)由底座 ThemeService 统一控制,从设计之初同时考虑;对比度以浅底深字为默认基调(实测不达标必须调令牌,禁止靠阴影凑合)。
2. **[必须] 字体**:字号层级 ≤10 档(基准示例:12/13/14/16/18/20/24/30/36/48),行高正文 1.4-1.6、标题 1.1-1.3,正文默认 16px,行宽 45-75 字符;字体 ≤2 种组合(中文优先 Noto Sans SC/Noto Serif SC),字重 ≤3 档。
3. **[必须] 动画时长**:微交互 150-200ms / 入场 300-400ms / 页面级 ≤600ms;标准缓动 cubic-bezier(0.2,0,0,1),弹性曲线仅用于重点反馈;只动画 transform/opacity,禁止动画 width/height/position;必须响应 prefers-reduced-motion(底座全局动画工具类已内置该媒体查询)。
4. **[必须] 间距/圆角/阴影**(整体基调配套,一次定死):间距 8pt 网格(4/8/12/16/24/32/48/64);圆角 3 档(小 4-6px 输入/标签、中 8-10px 按钮/卡片、大 12-16px 弹层);阴影按高程使用底座四级令牌(`shadow-soft`/`shadow-card`/`shadow-pop`/`shadow-overlay`,模糊随高程递增、方向一致)。

## 二、组件复用纪律(官方底座为唯一组件来源)

5. **[必须] 官方组件底座(ui-kit)**:桌面 74 + 移动 56 个组件,Signal 驱动、亮暗/主题色内置,位于包内 `ui-kit/`(复制自官方仓库,随交付维护升级);**底座浮层面板统一 fixed + FloatingPanelController 定位**(v1.1 起,`theme/floating-panel.ts` + `theme/floating-position.ts` 纯函数,`absolute + mt-*` 旧模式禁止);使用方式为**整目录复制**(`ui-kit/src/app/ui/` + `styles.css`/`styles.scss` token + `tailwind.config.js` 映射 + FontAwesome 依赖),依赖清单、复制步骤与非自包含连带说明见 `ui-kit/README使用说明.md`,复制后归项目所有、可按需修改。
6. **[必须] 组件一律取自底座**:页面/模板层组件优先从底座复制使用;底座没有的组件,按底座编写约定**扩展自建并回写底座**——Signal API(`input()`/`output()`/`model()`,不用 `@Input` 装饰器)、布尔输入 `input(false, { transform: booleanAttribute })`、新控制流 `@if`/`@for`、样式 Tailwind 优先、`.scss` 只放 `:host` 与复杂样式、每组件独立文件夹四件套(`.ts`/`.html`/`.scss`/`.spec.ts`)、选择器前缀 `ui-`(移动端 `ui-m-`)。原生控件只作为组件内部底层实现,页面/模板层禁止直接出现无样式原生控件。**扩展回写先例**:year-month-picker(桌面第 74 个组件,业务项目自建后回写底座,见 CHANGELOG v1.1)。
7. **[必须] 组件状态完整**:Default/Hover/Active/Focus/Disabled/Loading 六态 + 空/加载/错误三态(底座组件已内置,扩展组件必须同标准);按钮最小高度 44px;Focus 有清晰焦点环(底座全局 `:focus-visible` 已提供);Loading 优先骨架屏(底座 Skeleton)。
8. **[必须] 模式唯一**:同一功能/组件一个项目内只做一种方案,禁止同类组件多种样式并存;选型冲突时以底座实现为准。
9. **[必须] 具体 UI 由 AI 完成**:页面布局、组件样式、间距取舍由 AI 在令牌与底座组件清单内自主决策并留痕;成体系 UI 改造(≥3 页面或新页面体系)先出「令牌+组件清单+页面骨架」方案(走 17-工程执行纪律.md 规划门禁),禁止只写代码无方案。

## 三、防遮挡覆盖(布局安全底线)

10. **[必须] z-index 分层表**(与底座 `--z-*` 令牌一致,组件内禁止随手写层级,一律引用变量或语义层级):

| 层 | 令牌 / 值 | 用途 |
|---|---|---|
| 内容层 | 0(默认) | 页面内容/卡片/表格 |
| 吸顶层 | `--z-affix: 900` | 固钉/回到顶部/Sticky 导航 |
| 悬浮层 | `--z-float: 950` | 悬浮按钮/悬浮气泡/底部 TabBar |
| 遮罩层 | `--z-mask: 980` | 局部透明遮罩(选择器/筛选等) |
| 浮层 | `--z-popover: 1000` | 下拉菜单/气泡/Tooltip/日期面板 |
| 弹窗层 | `--z-modal: 1100` | Modal/抽屉及遮罩(多开由 OverlayStackService 递增) |
| 右键菜单层 | `--z-context-menu: 1150` | 右键菜单 |
| 命令面板层 | `--z-palette: 1200` | 命令面板全屏遮罩 |
| 预览层 | `--z-preview: 1300` | 图片预览灯箱 |
| 通知层 | `--z-toast: 1400` | Toast/全局通知(永远最高) |

11. **[必须] 固定元素安全区**:fixed/sticky 顶栏、侧栏、底部操作栏必须为内容区预留占位(如内容容器 padding-top=顶栏高度变量),禁止内容被固定元素遮挡;移动端底部栏必须避开浏览器安全区(env(safe-area-inset-bottom) 等,底座移动端组件已处理)。
12. **[必须] 溢出处理**:文本溢出必须截断(ellipsis/line-clamp)或换行,禁止溢出覆盖相邻内容;容器内容超长必须滚动;表格小屏必须横向滚动(min-width 容器,底座 Table/DataTable 已内置);图片/图表容器必须约束尺寸。
13. **[必须] 弹层互斥与层级管理**:同一时刻只允许一个最高层弹层;Modal 必须带遮罩、支持 Escape/遮罩点击关闭、焦点陷阱(底座 Modal/Drawer 已内置);Toast 固定于视口角落且可堆叠不遮挡底部操作区;弹层间不允许互相压住主操作(禁止 z-index 竞高)。**组件内浮层(下拉/气泡/日期面板)必须用底座 fixed + FloatingPanelController 定位模式,禁止 absolute 定位导致被 overflow 容器裁剪**;**删除类二次确认一律走居中 ui-modal,popconfirm 仅用于需确认但非删除的场景,或者不用**。

## 四、可访问性底线(WCAG 2.2 AA,保留)

14. **[必须] 对比度与语义**:对比度见负面清单;语义化 HTML(header/main/nav/section/article)、标题层级不跳级、Tab 顺序符合视觉顺序、交互元素可键盘操作、图片有 alt(装饰图空 alt)、图标按钮有 aria-label。
15. **[必须] 触控与缩放**:可点击区域 ≥44×44px(底座移动端组件已按此设计);界面在 200% 缩放下不破版。

## 五、UI 审查(聚焦框架纪律,不评审单页美学)

16. **[必须] 交付前自审五维**:①**无遮挡覆盖**(z-index 是否按分层表、固定元素安全区、溢出截断/滚动实测)②**令牌一致**(无魔法值/颜色字号时长全部来自底座令牌)③**底座一致**(组件取自底座、无绕过底座另造同功能组件、扩展组件已按约定回写)④**组件一致**(同功能同组件、六态+三态完整、无原生控件裸露)⑤**可访问性**(对比/键盘/焦点/触控)。
17. **[必须] ui-kit 使用验证清单**:业务项目引入 ui-kit 后,交付前须逐项确认并留痕——①`src/app/ui/` 整目录复制自 `ui-kit/src/app/ui/`(含 components/mobile/theme/index.ts);②`src/styles.css` 与 `src/styles.scss` 已复制;③`tailwind.config.js` 已合并 ui-kit 的 `theme.extend.colors` 与 `boxShadow`;④`angular.json` styles 已加入 FontAwesome `all.min.css`;⑤页面/模板层优先使用 `ui-*` 组件,无裸露原生控件;⑥无第三方 UI 组件库依赖。
18. **[必须] 审查结论以代码实测为准**:遮挡、覆盖、溢出必须实际运行/截图验证,禁止仅凭印象定性;fail/warn 项发布前必须实测复核。

## 建议规则

- [建议] 图标:统一使用底座内置的 FontAwesome 免费 solid 图标(`<i class="fa-solid fa-xxx">` 或底座 Icon 组件),风格与尺寸(16/20/24/32)统一;含义不明确的图标必须配文字;装饰性图标 aria-hidden。
- [建议] 设计资产留痕:令牌、组件清单、页面骨架写入 docs/(与 11-文档体系.md 衔接);UI 改动与数据模型/接口无关时不必走完整技术方案文档,但必须按黄金规则 10 留痕。
- [建议] 复杂页面(仪表盘/多区块)先画 ASCII 线框再实现;简单页面(表单/列表)可直接按令牌+底座组件清单装配。
- [建议] 底座组件的实时预览与 API 文档见官方仓库 showcase 应用;包内按 `ui-kit/README使用说明.md` 的组件清单选型,再读对应组件目录源码动手。