fmode-app/rules/18-UI设计规范.md

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,模糊随高程递增、方向一致)。

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

1. [必须] 官方组件底座(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,复制后归项目所有、可按需修改。
2. [必须] 组件一律取自底座:页面/模板层组件优先从底座复制使用;底座没有的组件,按底座编写约定扩展自建并回写底座——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)。
3. [必须] 组件状态完整:Default/Hover/Active/Focus/Disabled/Loading 六态 + 空/加载/错误三态(底座组件已内置,扩展组件必须同标准);按钮最小高度 44px;Focus 有清晰焦点环(底座全局 :focus-visible 已提供);Loading 优先骨架屏(底座 Skeleton)。
4. [必须] 模式唯一:同一功能/组件一个项目内只做一种方案,禁止同类组件多种样式并存;选型冲突时以底座实现为准。
5. [必须] 具体 UI 由 AI 完成:页面布局、组件样式、间距取舍由 AI 在令牌与底座组件清单内自主决策并留痕;成体系 UI 改造(≥3 页面或新页面体系)先出「令牌+组件清单+页面骨架」方案(走 17-工程执行纪律.md 规划门禁),禁止只写代码无方案。

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

1. [必须] 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/全局通知(永远最高)

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

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

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

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

1. [必须] 交付前自审五维:①无遮挡覆盖(z-index 是否按分层表、固定元素安全区、溢出截断/滚动实测)②令牌一致(无魔法值/颜色字号时长全部来自底座令牌)③底座一致(组件取自底座、无绕过底座另造同功能组件、扩展组件已按约定回写)④组件一致(同功能同组件、六态+三态完整、无原生控件裸露)⑤可访问性(对比/键盘/焦点/触控)。
2. [必须] 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 组件库依赖。
3. [必须] 审查结论以代码实测为准:遮挡、覆盖、溢出必须实际运行/截图验证,禁止仅凭印象定性;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 的组件清单选型,再读对应组件目录源码动手。