@facto-to/design-system 0.1.0-beta.6 → 0.1.0-beta.8

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
@@ -0,0 +1,498 @@
1
+ # Facto UI Standard — 详细规则与验收附录
2
+
3
+ **规则版本:1.2 · 文档修订:1.2.24 · 公开版1 · 2026-09-29**
4
+
5
+ 日常阅读从 [简明执行规范](ui-standard.md) 开始。本附录收录 v1.2 的完整规则、数值、规则编号和验收要求,按所做任务查询,不必从头通读。它是同一标准的规范性附录,不是另一套设计方案;主文未展开的要求仍有效,摘要有歧义时以此处完整规则为准。
6
+
7
+ | 要查什么 | 入口 |
8
+ |---|---|
9
+ | UI-only 边界、框架/组件库适配 | [边界](#boundaries)、[采用方式](#adoption) |
10
+ | 全部字体、空间、颜色与状态值 | [字体](#typography)、[空间](#spacing)、[颜色](#colors) |
11
+ | 表单控件、浮层及其他组件 | [控件](#controls)、[浮层](#overlays)、[组件族](#families) |
12
+ | 多端、键盘、放大和系统辅助模式 | [响应式](#responsive)、[可访问性](#accessibility) |
13
+ | Mock、完整测试矩阵、记录与通过判定 | [验收协议](#acceptance)、[判定规则](#governance) |
14
+ | Link 借鉴与历史来源 | [来源](#sources) |
15
+
16
+ **公共适用边界(1.2.24):** 本标准只规定可公共化的字体、字重、色彩、间距、表面、组件状态、多端适配、可访问性和验收证据。页面业务状态、卡计划归并、支付路径、认证提交策略和分页查询规则不属于公共UI标准,由各应用在自己的仓库中定义。业务场景资料不随公共包分发。公共组件接收展示状态和动作,由业务层决定含义与触发。
17
+
18
+ <a id="boundaries"></a>
19
+
20
+ ## 0. 最高门禁:逻辑层与 API 不变
21
+
22
+ **G01 优先级最高。** 以本规范开展的 UI 审计、样式优化或视觉迁移,必须保持业务逻辑、交互结果及 API 契约和访问行为不变。视觉一致性不得成为改动逻辑的理由。
23
+
24
+ 禁止借 UI 工作修改:金额/费率/额度计算,数据转换或格式化逻辑,权限/鉴权/业务条件,输入校验,可见或可用条件,筛选/排序/分页,state/effect/hook,事件处理与提交时机,disabled 条件,焦点管理逻辑,路由,存储,feature flag,SDK 调用,以及 endpoint/method/query/body/header、query key、缓存/失效、请求或 RPC/订阅的次数、顺序、触发、取消和重试;后端、数据库、依赖和运行配置不自动纳入。
25
+
26
+ - **G02 明确任务边界:** 每次实施先登记 app、目录、共享包及允许文件。全局标准适用不等于一次任务可以修改所有前端;共享 token 的变化必须显式纳入范围并列出全部消费者。当前文档制定不授权产品改动。
27
+ - **G03 允许视觉修改:** 字体角色、颜色、边框、圆角、阴影、图标尺寸、padding/margin/gap、容器尺寸、对齐和响应式排版,以及不改变语义与操作结果的展示标记/class。
28
+ - **G04 敏感布局专项证明:** display/visibility/overflow/order/pointer-events/touch-action、sticky/fixed、z-index、DOM wrapper、原生表单关联、label/ARIA 和 portal 周边改动须检查操作可达性、阅读/Tab 顺序与副作用。禁止更换有状态组件的类型、key、挂载条件/数量、provider 或 portal 边界;禁止双挂载业务子树后用 CSS 隐藏一个版本。
29
+ - **G05 合理几何变化:** 不要求 DOM、焦点坐标、滚动位置或 accessibility tree 字节相同;要求已有任务仍可完成,输入/校验/权限/结果不变,且没有新增、删除或重排外部副作用。
30
+ - **G06 超范围问题:** 必须调整逻辑/API 才能解决的缺陷标 `OUT-OF-SCOPE-OPEN`,另列依赖;不能偷偷修逻辑,也不能因禁止修逻辑而给缺陷判通过。
31
+
32
+ 本门禁约束 **UI-only 工作**。独立、明确授权的业务开发按自己的需求实施;它仍须遵守视觉和可访问性规则,但本文不替代其业务授权、测试或安全审查。
33
+
34
+ <a id="profiles"></a>
35
+
36
+ ## 1. 依据、适用性与品牌方向
37
+
38
+ 每条审计结论标明依据类别:**A** 为适用的 WCAG 要求或可复现的不可读/遮挡/不可达缺陷;**B** 为本文的 Facto 设计规则;**C** 为有场景证据支持的层级、比例、密度和视觉完成度判断。偏离 Link 像素不构成缺陷,偏离 Facto B 规则且无登记变体则构成一致性问题。不能只凭源码 class、截图印象或自动扫描为零判断通过。
39
+
40
+ **品牌基线:** 温暖中性画布、清楚的白色/浅色内容面、近黑主文字与主要操作、克制使用绿色。金融数据、状态和操作优先;避免装饰抢过金额,避免把所有卡片都做成强阴影/渐变,避免把所有标签加粗。字体、颜色、圆角、密度各自承担稳定角色。
41
+
42
+ | 场景 profile | 内容与默认密度 | 特别要求 |
43
+ |---|---|---|
44
+ | `dashboard` 用户工作区 | 常规内容与舒适设置/表单;数据列表可用明确紧凑变体 | 金额、卡标识、状态、权限与安全提示完整 |
45
+ | `workbench` 管理/开发者端 | 14/20 数据文字;紧凑表格/工具栏仅在精细指针环境启用 | 长 ID、日志、筛选、分页、批量选择、权限态均登记;不能以高密度隐藏操作 |
46
+ | `hosted` 认证/支付/接入流程 | 舒适输入与主要操作;按嵌入容器宽度布局 | 金额/币种/费用/收款对象保持优先;嵌入高度、跨域第三方控件、键盘单独验收 |
47
+ | `reading` 文档/说明 | 正文16/28,阅读列最大72ch | 内容结构、代码/表格局部滚动、链接与导航可辨 |
48
+
49
+ 宽度不能推断输入能力。iPad、触屏笔记本及带鼠标平板默认按混合输入处理,不能因桌面布局而缩小触控框。营销视觉可以登记独立品牌 profile;公共控件、可访问性和关键内容规则仍适用,本文不规定营销插画与艺术方向。
50
+
51
+ <a id="adoption"></a>
52
+
53
+ ## 2. Token、版本与落地方式
54
+
55
+ **S01 三层角色:** primitive 原始值 → semantic 用途 → component 配方。组件引用角色,不随页面任意改 HEX/字重/圆角。同一个 semantic token 在不同主题可对应不同值;状态色必须配套其表面。下文点号名称是规范角色 ID,不假定现有包已经导出同名 API。
56
+
57
+ **S02 采用清单:** 每个前端登记 `standard_version / app-profile / token-adapter / typography-role-map / component-variant-map / layer-map / supported-themes / breakpoints-containers / exceptions / test-command-map`。优先复用当前组件与应用实际使用的共享包,但不强制特定框架,不以升级依赖或替换控件作为视觉迁移捷径。
58
+
59
+ **S03 现状与目标分离:** 现有源码/发布包的默认值可能与本规范不同;它们是迁移基线,不能覆盖本文。映射缺失或不一致登记为待采用项;在单独获准的迁移中处理,禁止全局替换后只验一个页面。基础组件、实际承载页与共享包消费者分别验收。
60
+
61
+ **S04 变体只有明确用途:** 变体必须有名字、适用条件、完整配方、状态和对应案例。路由选择器、是否有 helper、继承来源或 CSS 加载顺序不能成为另一套隐形设计规则。光学调整允许2px,须注明对象和理由;不能因为数字不是4的倍数便判失败。
62
+
63
+ <a id="typography"></a>
64
+
65
+ ## 3. 字体与信息层级
66
+
67
+ 以下是根字号16px、100%缩放时的 CSS px 等价值;文字优先用 rem,行高以随文字缩放的等效值实现。不得锁用户缩放或用 transform 缩小整页。保留 Inter 作为 Latin 首选;CJK 使用系统中日韩回退字体,记录声明字体、加载资产及实际渲染字形,不能把 `font-family: Inter` 当成中文也由 Inter 渲染的证据。字体加载失败时仍须可读且不裁切。
68
+
69
+ | 角色 ID | 字号/行高 | 字重 | 使用条件 |
70
+ |---|---:|---:|---|
71
+ | `type.page-title` | 24/32 | 600 | 独立页面/对象主标题;不可与 shell 标题重复制造两个主标题 |
72
+ | `type.shell-title` | 20/28 | 600 | 应用外壳页头;可用主内容宽度小于600时为18/28/600 |
73
+ | `type.dialog-title` | 20/28 | 600 | 默认Sheet/详情浮层及Passkey正文标题;不按“安全/复杂”自动分配 |
74
+ | `type.section-title` | 16/24 | 600 | 内容区、卡片标题 |
75
+ | `type.group-label` | 13/20 | 600 | Profile/Security 等设置分组 |
76
+ | `type.settings-label` | 16/24 | 500 | 设置项;有无说明都用同一角色 |
77
+ | `type.data-label` | 14/20 | 500 | 紧凑列表主标签、工作台字段名 |
78
+ | `type.value` / `type.input` | 16/24 | 400 | 设置值/输入;数据表的值使用下方 data-value |
79
+ | `type.data-value` / `type.body` / `type.helper` | 14/20 | 400 | 表格值、正文、说明、错误/费用说明 |
80
+ | `type.field-label` | 14/20 | 500 | 持久外置表单标签 |
81
+ | `type.compact-label` / `type.badge` | 12/16 | 500 | 持久浮动标签/状态标签/表头 |
82
+ | `type.meta` | 12/16 | 400 | 次要时间、补充元数据;关键错误或费用不得降至此角色 |
83
+ | `type.action` | 14/20 | 500 | 常规按钮与文字操作 |
84
+ | `type.action.large` | 16/24 | 500 | 舒适主表单操作 |
85
+ | `type.amount` | 28/36 | 600 | 摘要金额;其他 hero 尺度需登记 |
86
+ | `type.reading` | 16/28 | 400 | 连续长文 |
87
+ | `type.code` | 13/20 | 400 | 等宽代码/日志;不是普通金额默认字体 |
88
+
89
+ **T01 字距:** 默认0。page-title 与 amount 可采用−0.02em的命名展示变体;其他角色不得继承全局负字距。中文回退需复验,不复制 Link 的420字重。常规使用400/500/600;700仅限登记的品牌或特别强调用途,不用于整页设置标签。
90
+
91
+ **T02 层级:** 同层标签、值、说明和操作跨页面一致。以字号/字重/颜色/间距共同建立层级;“Connect”须具有稳定操作线索,不能与只读值完全同样式。不得为了让标签看起来轻而削弱金额、错误和辅助说明对比。
92
+
93
+ **T03 完整内容:** 关键任务标题、金额/币种/单位、费用、关键状态、卡末四位和操作含义不能依赖鼠标 hover 才完整。长文本可换行;非关键次要名称可截断,但须有适用于键盘与触控的既有完整阅读入口。禁止纯 CSS 伪元素承载唯一关键数据。
94
+
95
+ **T04 金融排版:** 数值列右对齐、同列小数和正负号可辨,使用 tabular-nums 稳定扫描;数值与币种/单位保持关联但可在受控位置换行。不得更改数值舍入、地址缩写或格式化算法来适配宽度。卡名可收缩/换行,末四位和识别标记不得被 flex 挤没;同名卡也能区分。
96
+
97
+ **T05 长值与手机列表:** URL、地址及其他不可随意缩写的长值在自己的值列换行,必要时由该列局部滚动;保留实际字符串及相邻标签关系。手机列表仍直接呈现状态和日期/时间的文字或等价图标信息,颜色点只可作辅助,不能成为唯一状态或时间线索。
98
+
99
+ <a id="spacing"></a>
100
+
101
+ ## 4. 空间、容器、密度与表面
102
+
103
+ **L01 尺度:** 4/8/12/16/20/24/32 为常用空间,40/48/64用于大型区块。边框1px、光学2px不属于间距违规。宽度/高度必须注明 border-box 或内容框,不从截图放大倍率反推 CSS px。
104
+
105
+ | 关系或容器 | 默认配方 | 命名变体/条件 |
106
+ |---|---|---|
107
+ | 标签→说明 | 4 | 跨行仍保持关联 |
108
+ | 外置标签→输入 / 图标→操作文字 | 8 / 8 | 图标与行主内容间16 |
109
+ | 分组标题→卡片 | 12 | 独立 section 之间32 |
110
+ | 同组字段垂直间距 | 16 | 两个并列字段之间12;段落间16 |
111
+ | 常规卡片内容 padding | 24 | `card.compact`20;主内容区小于600时两者16 |
112
+ | 卡片之间/网格 gap | 16 | 独立工作区 section gap32 |
113
+ | 页面水平 gutter | 24 | 主内容区小于600时16;安全区在此之外且仅计算一次 |
114
+ | `layout.reading-form` | 最大640,默认与页面标题同起点 | 普通短表单;独立Hosted/认证使用居中变体 |
115
+ | `layout.workspace` | 最大1280,剩余空间居中 | 数据工作区可登记`workspace.fluid`,内容保持可扫描 |
116
+ | `layout.prose` | 最大72ch | reading profile;不限制表格必要二维区域 |
117
+ | `radius.control/card/dialog` | 12 / 16 / 24 | button/badge为pill;圆形icon按钮单独角色 |
118
+ | 普通卡片 | 无阴影;按相邻表面用1px装饰边框 | 不以浅边框作为唯一必需控件边界 |
119
+ | 浮层 shadow | `0 8px 32px rgba(18,20,17,.12)` | 阴影仅辅助分层;不能代替边界/焦点 |
120
+ | scrim | `rgba(18,20,17,.32)` | 不强制背景模糊;透明度变化须复验层级 |
121
+
122
+ **L02 设置行:** padding `16px`,图标/主内容/尾部间16;单行自然最小高度56(24行盒+上下各16),带说明自然高度80(24+4+20+32),均为 min-height 而非固定高。辅助说明不能触发主标签变粗。尾部值过长时允许换行或下一行;状态和操作不得挤压标签。
123
+
124
+ 通用信息行使用独立图标列、可收缩内容列和操作列;短标签和值可同行,长内容自然换行。只读项不得带导航暗示,实际操作须有足够命中区。
125
+
126
+ **L03 空间决策:** “小于600”指所属页面主内容区/组件声明的父容器,不包括侧栏,不按设备名称判断。嵌套卡片不得各自重复叠加页面 gutter。组件先定义最小内容宽度,再重排;不能靠整体缩小字号保留列数。既有断点迁移若需新增运行逻辑,受 G01 限制。
127
+
128
+ **L04 视觉完成度:** 同一阅读轴的标题、表单、列表与分隔线对齐;留白体现关系而非平均铺满。窄屏不出现孤立小块与大面积无用途留白,宽屏不把短表单拉成一整行;空态、loading 与最终布局保持合理连续性。
129
+
130
+ <a id="colors"></a>
131
+
132
+ ## 5. 色彩与对比配方
133
+
134
+ 语义角色用于统一文字、操作、状态与焦点,并不要求实现主题系统。只有其他前端本来已实际支持的主题才纳入其各自清单和验收;未来新增主题必须另有明确功能范围。forced-colors等系统辅助模式属于可访问性压力测试,不是新增产品主题,仍独立检查。
135
+
136
+ | 语义角色 ID | 浅色默认值 | 用途/成对验证 |
137
+ |---|---|---|
138
+ | `surface.canvas` | `#f5f5f4` | 页面画布 |
139
+ | `surface.default` | `#ffffff` | 主容器 |
140
+ | `surface.subtle` | `#f3f3f2` | 次级面 |
141
+ | `text.primary` | `#121411` | 上述中性面;白底18.52:1 |
142
+ | `text.secondary` | `#62655f` | 白/画布/次级面分别5.92/5.43/5.33:1 |
143
+ | `action.primary.background` | `#171716` | 与自身foreground配对17.94:1 |
144
+ | `action.primary.foreground` | `#ffffff` | 主操作文字/图标 |
145
+ | `action.primary.background.hover` | `#2c2e2a` | 主操作hover |
146
+ | `action.primary.background.pressed` | `#080908` | 主操作pressed |
147
+ | `action.secondary.background` | `#f3f3f2` | 次操作默认 |
148
+ | `action.secondary.foreground` | `#121411` | 次操作文字/图标 |
149
+ | `action.secondary.border` | transparent | 次操作默认不要求边框 |
150
+ | `action.secondary.background.hover` | `#eaeae7` | 次操作hover |
151
+ | `action.secondary.background.pressed` | `#ddded9` | 次操作pressed |
152
+ | `action.link.foreground` | `#0b6b4b` | 白/次级面6.52/5.88:1;同时有下划线或明确操作形状 |
153
+ | `action.link.foreground.hover` | `#0b6b4b` | 保留颜色、加强下划线 |
154
+ | `action.link.foreground.pressed` | `#084d36` | 文字操作pressed |
155
+ | `action.danger.background` | `#9f2333` | 危险主操作底色,与status独立映射 |
156
+ | `action.danger.foreground` | `#ffffff` | 危险主操作文字/图标 |
157
+ | `action.danger.background.hover` | `#851d2b` | 危险操作hover |
158
+ | `action.danger.background.pressed` | `#6f1723` | 危险操作pressed |
159
+ | `focus.ring` | `#121411` | 中性焦点;与link/success/selected绿色独立映射 |
160
+ | `focus.isolation` | `#ffffff` | 复杂背景隔离边;与轮廓一起复验 |
161
+ | `brand.accent` | `#00d64f` | 品牌强调/装饰;不可默认搭白字;近黑文字对比9.46:1 |
162
+ | `status.success.foreground` | `#0b6b4b` | 与success.surface配对6.05:1 |
163
+ | `status.success.surface` | `#e7fbf2` | 成功提示承载面 |
164
+ | `status.warning.foreground` | `#805300` | 与warning.surface配对6.22:1 |
165
+ | `status.warning.surface` | `#fff7df` | 警告提示承载面 |
166
+ | `status.danger.foreground` | `#9f2333` | 与danger.surface配对6.88:1;不代指危险按钮底色 |
167
+ | `status.danger.surface` | `#fff0f2` | 错误提示承载面 |
168
+ | `status.info.foreground` | `#175c9c` | 与info.surface配对6.14:1 |
169
+ | `status.info.surface` | `#eaf3fb` | 信息提示承载面 |
170
+ | `border.decorative` | `#e7e7e5` | 非必需的卡片/行分隔 |
171
+ | `control.background` | `#f5f5f5` | 中性填充输入/选择控件默认底色 |
172
+ | `control.foreground` | `#121411` | 输入/选择控件默认内容 |
173
+ | `control.border` | transparent | 中性填充输入/选择控件默认边框;与次按钮边框角色分开 |
174
+ | `control.border.hover` | `#121411` | 可用控件hover边界 |
175
+ | `control.selected.background` | `#0b6b4b` | 选中标记底色,与success独立映射 |
176
+ | `control.selected.foreground` | `#ffffff` | 选中标记/滑块 |
177
+ | `control.invalid.border` | `#9f2333` | invalid边界;错误正文用status.danger.foreground |
178
+ | `state.disabled.foreground` | `#62655f` | 配合disabled.background为4.91:1 |
179
+ | `state.disabled.background` | `#eaeae7` | 禁用有底控件 |
180
+ | `state.disabled.border` | `#e7e7e5` | 禁用边界;保留选中含义 |
181
+ | `skeleton.base` | `#f3f3f2` | 骨架基础面 |
182
+ | `skeleton.highlight` | `#eaeae7` | 骨架变化面,reduce-motion时静态 |
183
+
184
+ 以上比值由不透明 sRGB 成对计算、四舍五入展示,门槛判断使用未舍入值。**V01** 它们不覆盖透明文字、混色、hover、卡品牌背景、图片/渐变或未知主题;这些组合须单独测实际合成后颜色。`text.secondary`不是所有彩色背景通用色;彩色提示用对应status前景,透明badge重新验证宿主表面。
185
+
186
+ **V02 语义独立:** 成功/危险/警告同时有文字或图标线索;不能仅靠颜色判断交易状态。品牌绿色不自动代表成功;品牌卡面/发行商卡色不当通用警告。卡号在每个品牌底色上满足对比,不够时采用可读前景或中性承载层,不用固定白色透明度碰运气。
187
+
188
+ **V03 焦点与系统模式:** 常规文本输入、搜索、textarea、原生select和自定义select默认`control.background`与透明`control.border`;焦点为白底、单层2px `focus.ring`内描边、`outline-offset:-2px`且无box-shadow。复合输入只在整组可见外壳绘制一层,子输入不得重复。按钮及其他非输入仅keyboard focus为2px `focus.ring`外轮廓、外距2px且无重复阴影;深色背景需要白色隔离边时,按实际背景、对比和截图登记例外。invalid+focus必须仍显式保留错误边界/文字,允许使用danger而非绿色,不改变既有状态策略、语义标签、品牌绿色或成功映射。不得覆盖浏览器焦点却不给替代。hidden原生checkbox/switch的focus-visible必须投射到可见控件;checked+focus、disabled+checked分别验收。forced-colors使用`Highlight`,不把唯一状态放在可能消失的box-shadow或背景图里。
189
+
190
+ <a id="controls"></a>
191
+
192
+ ## 6. 控件完整配方与状态
193
+
194
+ 所有尺寸为默认100%字排的最小值;文本增行/放大时组件必须增长。下列高度为 border-box min-height,padding为最小内容内边距,边框占位纳入实际几何,不能为凑固定高裁字。`pill`指充分圆角,不限制多行按钮高度。
195
+
196
+ | 控件/变体 | 字排 | 最小高/目标 | padding / gap / radius |
197
+ |---|---|---|---|
198
+ | `button.default` | action14/20/500 | 精细指针40;触控/混合44 | 8 16 / 8 / pill |
199
+ | `button.compact` | action14/20/500 | 36,仅精细指针+hover的登记工具栏 | 6 12 / 8 / pill |
200
+ | `button.large` | action.large16/24/500 | 52;Hosted/主表单提交默认 | 12 24 / 8 / pill |
201
+ | `button.icon` | 保持原glyph比例 | 交互目标44×44 | 图形16/20/24;特殊可见底面由采用者具名登记;可见图形不因命中框增大,默认安静灰色且无常显深色轮廓 |
202
+ | `action.inline` | action14/20/500 | 独立控件同default目标;行内文本链接按A类例外评估 | 常态下划线或明确操作图标;不得只在hover才可辨 |
203
+ | `input.default` | input16/24/400 | 44 | 8 12 / label gap8 / 12 |
204
+ | `input.floating` | compact-label12/16+input16/24 | 60 | 8 16 / 0 / 12;持久标签,不以缩放到12以下实现 |
205
+ | `textarea` | input16/24/400 | 至少3行内容 | 12;可增长/滚动,标签与错误在外侧 |
206
+ | checkbox/radio | 标记20 | 实际目标44×44,含关联标签区域 | 标记与标签gap8;标签换行仍可操作 |
207
+ | switch | 原生track34×20、白色thumb16 | 实际目标44×44 | 原生checked `#00d66f`;on/off可辨,标签不随状态跳动 |
208
+ | badge | badge12/16/500 | 自然高度 | 4 8 / gap4 / pill;默认非操作控件 |
209
+
210
+ **C01 按钮角色、状态与宽度:** 同一决策区一个突出的主操作。primary使用黑色`action.primary.background/foreground`及对应hover/pressed;secondary使用浅灰`action.secondary.background/foreground`及对应hover/pressed,默认边框transparent;danger主操作使用暗红`action.danger.background/foreground`及对应hover/pressed;有背景的disabled共享`state.disabled`灰色配方。常规按钮为pill与14/20/500。角色不要求同色、同宽;宽度按文案和任务内容确定。text/link使用`action.link.foreground`及对应hover/pressed,hover加强下划线。文字已清晰可辨的按钮外围不因A02而一概补3:1边界;仍须逐项验证必要的可用控件/状态视觉。状态不能靠布局位移表达。所有variant均覆盖适用default/hover/focus-visible/pressed/selected/disabled/loading/invalid,而不是仅定义primary默认态。
211
+
212
+ **C01b Hosted 链接型操作:** Hosted 流程中实际承担按钮角色的 `a`,无论是否沿用既有导航语义,均须以连续的块级或 inline-block 承载面呈现其背景、圆角和命中区;不得让 inline 行盒切断背景。保留其 href、导航、target 与键盘语义。
213
+
214
+ **C02 禁用、只读与加载:** 有背景的disabled使用`state.disabled.foreground/background/border`,text/icon disabled可无底但需去掉常态下划线等可用线索并保持既有禁用语义;禁用后不得仍出现活动hover/pressed反馈。readonly不是disabled,值仍清楚且保留既有选择/复制。native disabled与aria-disabled的行为不同,样式修复不转换语义或添加拦截事件。loading保留操作位置、目标尺寸和现有反馈,不改变按钮是否可再次提交的业务条件。
215
+
216
+ **C03 表单:** 本节中性输入配方适用于常规文字/搜索等输入、textarea及select,不包含checkbox/radio/switch、range、color、file、hidden或button/submit/reset型input;选择控件查C04,其余保留原生呈现并单独验收。优先持久外置标签;现有浮动标签可以按floating配方保留。placeholder只作示例,不能作为唯一标签。必填、说明、错误与控件有明确归属;错误不只红色、不会把后续字段覆盖。Input/search/textarea/native select/custom select default使用`control.background/foreground/border`;hover使用既有可见边界,focus用V03输入配方,invalid使用`control.invalid.border`与`status.danger.foreground`错误正文,disabled用禁用配方;同时invalid+focus保留两种含义。不得新增校验时机/文案逻辑,也不改变状态语义标签。
217
+
218
+ 其他前端沿用“先任务提醒、后长列表;关键异常可直接扫读”的原则,须按各自任务验证。
219
+
220
+ **C03a 输入焦点:** 所有C03常规输入按V03执行;登录/Hosted入口不是专属例外。点击与键盘聚焦均须可辨;已有错误提示和校验行为保持,不能因焦点覆盖错误含义。
221
+
222
+ **实现检查:** C03排除的是`input[type="button"/"submit"/"reset"]`等原生非文字输入,不是自定义Select的`button`触发器。普通菜单与portal菜单共享容器配方(padding12、圆角12、浮层阴影)及菜单项配方;链选择等具名宽度变体保留自己的定位/宽度,但不取消共享阴影。分页Select禁用态也使用三项disabled token。不能靠页面祖先选择器分别定义字重/间距;最终按渲染样式验收。
223
+
224
+ **C04 选择控件:** checkbox/radio/switch未选中使用既有控件表面/边界;选中标记沿`control.selected.background/foreground`,原生switch例外为`#00d66f`,不改变其状态语义标签。hover保留含义,focus按V03,disabled沿C02,选中标记使用`state.disabled.foreground`与背景区分。Switch滑块的水平位移只能由`translate`或`transform`其中一种机制承担,不得叠加;在真实开发和交付构建中分别测量checked/unchecked、enabled/disabled的最终computed `translate`与`transform`及滑块/轨道几何,四态滑块必须完全位于轨道内。不得将C03的文字input底色、焦点或位移规则套用于switch。原生select保持平台可操作性;自定义select/combobox的搜索、选中、空结果、展开与滚动依既有行为审计。Menu item默认44高,compact36仅精细指针变体;内容padding8 12、字排14/20、圆角8;选中有标记,焦点不等同hover。
225
+
226
+ **C05 操作暗示:** 可进入行使用一致chevron/操作形状,纯信息行不得使用pointer和导航hover承诺。通知的“已读”与“可导航”分开审计,不能为移除视觉暗示删除原有mark-read事件。Tooltip只补充说明,不承载唯一关键内容,键盘/触控须有等价入口;缺少既有逻辑时登记超范围。
227
+
228
+ Sheet返回可见圆28的左边缘对齐正文左边,关闭可见圆28的右边缘对齐正文右边,44点击区向padding扩展;返回圆右侧到标题16。验收比较可见圆几何与正文边线,不只检查button的44尺寸。普通Dialog默认无FACTO kicker;调用方显式传入且有任务语义的 kicker 可以显示。Mock以已开放产品范围配置,不得因测试环境旗标开启Credit/Admin/隐藏入口并将其计入验收。
229
+
230
+ **C06 图标:** 常用16/20/24,chevron12只作辅助,描边默认1.5或2但同套一致。圆形底面默认28,可登记其他命名变体;44px是交互目标,不是44px可见圆形。默认安静灰色,不添加常显深色轮廓;仅keyboard focus按V03。测量实际渲染rect,不用SVG属性猜尺寸。点击框与图形分开;无文字控件有可理解名称,纯装饰不污染accessible name。图标替换不得改变业务状态含义。
231
+
232
+ <a id="overlays"></a>
233
+
234
+ ## 7. Dialog、Sheet、Drawer、Popover
235
+
236
+ | 配方 | 外框最大宽 | 内padding | 标题/区块间距 |
237
+ |---|---:|---:|---|
238
+ | 新产品紧凑起点 | 400 | 20 | 宽度变化需有内容理由与桌面/窄屏实测 |
239
+ | `drawer.detail` | 480 | 24;窄内容20 | 标题20/28;区块24/20 |
240
+ | `popover` | 默认320 | 12 | 文字14/20,分组gap8,radius12 |
241
+
242
+ **O00a 关闭与返回:** 保留原生button语义,不用可点击div替代。浮层关闭使用共享关闭图标(20×20画布、2px描边)及44px点击目标。Modal可见圆圈28,右边缘对齐内容右边缘,距壳体20;透明44点击区域不挤占视觉边线。具名Drawer变体可登记不同圆形底面,仍沿同一阅读轴。disabled/focus及关闭后焦点行为保留。
243
+
244
+ **O00 容器内边距:** 所有Modal/Dialog及任务Sheet的容器边框到header/body/footer四周统一20px;不因复杂度或断点切换为16/24。各区域共用阅读轴,不重复叠加壳体padding;底部safe-area按实际需要额外计入一次。Drawer与Popover按各自配方处理。
245
+
246
+ **O01 宽高与滚动:** 浮动弹窗外宽不超过可用viewport/宿主宽减左右各16和对应safe-area;该外侧留白不是容器padding。采用者登记每种浮层的内容宽度与适用条件;新产品从紧凑400起,任何宽度变化须说明内容理由并在桌面与窄屏实际复核。对齐于既有portal的可用区域。表中既有宽度指桌面浮动形态;现有移动Sheet可按原形态铺满。平板分屏依据实际可用宽度,不依据设备名称。桌面居中,现有Sheet可窄屏底对齐并保留贴边形态;改变组件或导航模式不属于纯样式默认授权。最大可视高扣除上下边距与安全区;内容过长在明确滚动区内可达。页脚允许进入滚动区,不能为了“始终固定”遮住内容或焦点。不得硬编码固定总高度,也不得用120px等人为最小可用高度使短窗口溢出真实可用空间。
247
+
248
+ **O02 标题与关闭:** 单行header布局基准32px(min-height),标题与可见关闭图形垂直居中;header到body保持20px。44px关闭/返回点击区上下各扩出6px而不撑高布局,可见圆圈仍28。扩展点击区不得被裁切或覆盖正文/相邻控件;不得用height:32锁死多行标题。超长词可在词内换行;极端长标题最大块高为`max(56px, calc(50dvh - 40px))`,标题自身可滚动,关闭/返回保持在外,正文保留正高度。仅当实际`scrollHeight > clientHeight`时标题才获得`tabIndex=0`,从而可用Tab、PageDown和方向键滚动;未溢出标题不得产生额外Tab stop。尺寸变化通过ResizeObserver、内容变化通过观察标题内容后重新判断。标题左对齐且允许增长,关闭/返回预留44目标;关键标题不单行省略。即使320窄屏、200%文字及长英文标题,仍可识别任务并找到关闭/返回。不能用减小字号补偿不合理宽度。
249
+
250
+ **O03 字段与操作:** 字段纵向gap16;两列最小单列内容宽160、列gap12,实际表单内容不足332时单列。数字仅为布局条件,不转换字段数据/顺序。footer普通单按钮按内容宽靠右;全宽操作作为具名变体登记。验收实际几何尺寸,不仅检查类名。多按钮空间不足时纵排,不把所有窄弹窗按钮一律拉满;新组合gap12,既有具名组合另验。保持有意义的DOM/Tab顺序,不用CSS反向排列制造视觉与键盘相反顺序。
251
+
252
+ **O04 Overlay语义:** 核验现有dialog名称、初始焦点、Tab范围、Escape/关闭和关闭后焦点返回;不可假定有scrim即为modal。关闭后即使发生 resize,也恢复到仍可见且可用的等价 opener;若没有这样的 opener,恢复到 main 或页面 heading。多层浮层的焦点/滚动/层级须逐条可操作。popover/menu属于其owner层,不能被modal遮掉或盖住无关高层提示;使用角色化层级表,不散布任意9999。缺失焦点管理等行为须遵守G06。
253
+
254
+ **O04b Toast 与 Modal 共存(2026-09-28修订):** Toast统一fixed右上,桌面top/right24、最大宽420;窄屏top16并兼顾safe-area,占满扣除页面gutter后的可用宽度,左右沿用--space-4(16px)并兼顾safe-area;内部横向padding16。Toast本身之外不增加背景或遮罩,不把root变为反馈布局行,不缩短页面画布。窄屏Modal改在完整scrim内顶部预留有限Toast空间。 已开Modal时,Toast 不得覆盖其 footer、唯一操作或当前焦点,也不得因预留空间缩短 scrim/backdrop,露出未遮罩的视口区域。短高视口优先保持Modal内部明确滚动区,使正文、footer和关闭均可到达;不以隐藏内容、挪走footer或改portal/focus逻辑解决。窄屏页面级 Toast 使用扣除页面左右gutter(--space-4 / 16px)后的全可用宽度,长错误在自身有限高度内滚动,不能收缩成遮挡操作的窄高柱。
255
+
256
+ **O04a 层级契约:** 每个app的`layer-map`登记role、owner、stacking context/portal或浏览器top layer、实际z-index/渲染顺序、嵌套规则与案例。标准约束相对关系,现有不同数字可由adapter映射,不要求为对齐数字改portal或焦点逻辑。
257
+
258
+ | 层级角色 | 同一owner中的相对关系 | 嵌套/验收约束 |
259
+ |---|---|---|
260
+ | `layer.content` | 基础内容 | 不越过其owner |
261
+ | `layer.sticky-navigation` | 在content之上 | 不遮挡当前焦点/锚点;保留内容滚动空间 |
262
+ | `layer.owner-popover` | 在所属content/sticky之上 | 页面popover在后开的modal scrim之下;modal内popover在该modal内容之上 |
263
+ | `layer.modal-scrim` / `layer.modal-content` | 当前被阻断owner全部内容 < scrim < modal-content | 每个嵌套modal建立新的owner;新scrim覆盖前一个modal及其popover,新modal在自己scrim之上 |
264
+ | `layer.owner-feedback` | 在当前活动owner内容之上且不遮唯一操作/焦点 | 交互toast必须属于可操作的活动owner,不能让inert背景控件仅凭高z-index浮出;关键持久反馈不依赖toast |
265
+
266
+ 每个owner的popover/feedback在其后打开的modal scrim之下;没有modal时按页面owner解析。浏览器top layer优先于普通stacking context,不能仅用更大z-index比较;须实测打开顺序与owner。工具菜单、下拉、toast和嵌套modal至少覆盖一组共存案例。原组件的portal/owner不满足契约而需改行为时按G06登记,不在UI-only中重建管理器。
267
+
268
+ **O05 高风险内容:** QR、恢复码、长地址、验证码、危险操作与交易确认独立验收。二维码不得为适配任意缩小到无法扫码,实际可扫码性需用测试数据核验;恢复码/地址可读与既有复制能力保留。软键盘、横屏短高、safe-area单独测试。
269
+
270
+ <a id="families"></a>
271
+
272
+ ## 8. 数据、导航、反馈与其他组件
273
+
274
+ | 组件族 | 规范配方与验收重点 |
275
+ |---|---|
276
+ | Table / dense list | 表头12/16/500,单元值14/20/400;default行min48、上下padding12/左右16。compact行min40/padding8仅fine+hover,comfortable行min56/padding16;触控内嵌操作仍≥44。多行自然增长;数字右对齐、文本左对齐、表头与列对应。横向滚动限必要二维区域且可发现,保留列名/单位/状态关系 |
277
+ | Toolbar / filter / pagination | 按钮/输入沿第6节;组间gap16、组内8。空间不足换行,筛选条件与结果/分页归属明确;不隐藏已生效条件;查询与分页行为由场景契约定义,公共控件仅展示受控状态。现有批量操作与选择计数保持可见 |
278
+ | Tabs / segmented / navigation | 文字14/20/500;默认目标44,精细指针compact36需登记。选中用形状/指示条+文字或语义,不只色差;active/current/focus不同。长导航可按现有机制局部滚动;导航项不因响应式双挂载 |
279
+ | Page header / breadcrumb | 按shell/page标题角色;标题、返回、面包屑、工具栏优先级清楚。内容窄时换行而非重叠;已有返回/菜单路径可达,当前位置可识别 |
280
+ | KPI / financial card | 卡片配方+amount角色;标签/金额/币种/趋势有主次,正负/状态不只颜色。窄卡先降列再允许换行,关键金额不缩成meta |
281
+ | Description / detail / timeline | 标签和值不混淆;大屏两列须保留对应关系,窄屏按项上下排,gap4/项间16。时间与事件关联,长ID有既有完整查看/复制入口 |
282
+ | Empty / error / loading / partial | 现有状态分别有清楚含义,使用现有恢复动作;标题16/24/600,说明14/20/400,内容gap8、操作gap16。无数据不伪装为0,失败不伪装为空;样式不能改状态判断 |
283
+ | Banner / alert / toast | 对应status配方,padding12 16、gap8、radius12;正文14/20,标题14/20/500。关闭44;长文可换行。Toast不遮唯一操作/焦点,时长与live反馈维持现有逻辑;关键持久信息不只依赖短暂toast |
284
+ | Skeleton / progress | 骨架接近实际内容结构,避免整页跳动;颜色`skeleton.base/highlight`,reduce-motion时静态。进度有文字或可访问等价,动画不改变完成条件 |
285
+ | Chart / graph / pipeline | 图例、轴、节点/连线、单位/状态可辨;重要线/标记按A类对比,颜色之外有形状/标签。允许必要局部二维操作,但存在完整信息入口;已有pan/zoom/selection交互不改 |
286
+ | Avatar / logo / brand card | 大小24/32/40命名变体;名字/角色不能仅靠头像区分。加载/缺失资产用现有fallback,不能新增身份逻辑;品牌色上文字单独测量 |
287
+ | Code / logs / documentation | code角色,padding16、radius12,局部滚动与copy目标清楚;阅读正文16/28,标题沿层级。不以代码截图承载可选择内容;遮掩策略/日志数据处理不改 |
288
+ | Third-party / embedded control | 标记可控边界,容器、标签、加载、错误和宿主对比由Facto负责;跨域字段内部不能由外部截图推定合格。第三方未测仍列未验证或外部依赖 |
289
+
290
+ **D01 运营表格:** 列显隐、排序、筛选、分页、粘性表头/首列、选择、批量操作与导出按实际已有变体列案例。固定列不得遮住滚动列或焦点;当前选择/生效筛选/总数关系可见,加载或部分失败不伪装为完整结果。只能调呈现,不能改变列权限、排序算法、选择集合与导出数据。
291
+
292
+ **D02 图表与画布:** 可交互画布须有图例/单位、当前选择及缩放状态的可辨表达,核验鼠标、触摸与键盘已有入口、画布内外滚动所有权。适用时检查无需拖拽的单指针替代([WCAG 2.5.7](https://www.w3.org/WAI/WCAG22/Understanding/dragging-movements.html),按必要性或由user agent决定且作者未修改的例外判断;未接管的浏览器原生滚动不作为作者拖拽交互缺陷)及非视觉完整信息入口;缺失时登记缺陷,需新增事件/数据入口的按G06处理,不能用图表静态截图宣称交互通过。
293
+
294
+ **D03 文档与开发者内容:** 搜索/空结果、目录、锚点定位、代码语言/主题切换、复制、终端、OpenAPI参数表与外链单独登记。锚点目标不被sticky页头盖住;复制目标44,长命令局部横滚,不把可执行命令截成不可理解片段。代码主题的注释/语法/选中/焦点均验对比;URL、地址、ID在已支持RTL或双向文本中保持正确方向与相邻标签关系,不能更改实际字符串。
295
+
296
+ **D04 实时与高风险状态:** SSE/轮询/队列、连接中/断线/滞后/重试/过期、乐观反馈、钱包或Hosted确认,按产品实际存在者登记。等待、成功、失败和最终确认的视觉不能混淆;状态变化后的布局、焦点和既有announcement验收。不得新增产品未支持状态、自动重试、超时、确认或交易逻辑。
297
+
298
+ **D05 现有主题与第三方:** 各前端按实际支持的主题/品牌映射登记,不能因规范预留扩展而假设它们都支持切换;只有存在主题切换时,才验收切换后的overlay、图表、代码块及既有持久性/系统偏好不变。第三方逐项列owner/库版本/可控部分/测试入口/限制;无法控制但影响关键路径的内容也不能直接N/A或PASS。
299
+
300
+ 新组件族必须先有文字/空间/颜色/状态/响应式/输入/验收配方,再加入本版登记。禁止用“其他组件同理”代替它自己的可操作性验证。
301
+
302
+ <a id="shared-patterns"></a>
303
+
304
+ ## 8a. 公共展示契约
305
+
306
+ 本节可供SDK采用;Dashboard专属默认值须通过具名profile配置,不推导业务状态。
307
+
308
+ **D09 骨架与反馈:** 每个骨架对应真实页面的shell、标题、分组、列表/卡面、详情区和操作区,不用通用大矩形替代。固定同一viewport、fixture及字体分别截取加载与完成态,记录区域边界、阅读轴、列数、行高及操作位置;测量锚点为页头下缘、内容左边缘、首个列表/卡面外框及保留的操作容器外框;对每个锚点记录loading/loaded的x、y、width、height。预先声明哪些区域固定、哪些由未知内容决定;固定区域应沿用同一布局token和容器,差异逐项解释,未解释的跳动判FAIL。不得在测量后把失败区域改称动态区域。未知内容区不要求像素同高,但不得推走正在操作的控件、改变焦点或造成整页横溢。追加分页使用尾部加载,不重置整页骨架;失败不能无限保留骨架,真实空态不能伪装加载。用aria-busy等提供等价状态,装饰骨架不产生重复读屏内容;reduce-motion静态。不设置缺乏组件依据的全局4px容差;如某组件需要容差,在case中预先注明原因及取值。上述检查不代替运行时布局偏移测量。
309
+
310
+ **D10 Toast与下拉菜单:** Toast沿用右上配方;普通短成功消息可以自动消失,时长由采用者登记;需用户处理的错误或关键信息同时保留在页面中,不能依赖短暂toast。成功、失败、复制、重发反馈语义一致,不重复播报。自定义Select的hover/selected背景覆盖整个可点击选项,容器允许统一内边距,禁止只有文字小块高亮或视觉项与点击区域不一致;长标签、勾选图标、滚动与键盘焦点均在同一行契约内验收。
311
+
312
+ <a id="responsive"></a>
313
+
314
+ ## 9. 全端响应式契约
315
+
316
+ **R01 四维分离:** 容器可用宽决定列数与换行,输入能力决定目标与hover策略,可用高度决定滚动/固定区,内容压力决定增长与信息优先级。断点不是PC/手机/iPad标签。实际media/container query从实现提取,按b−1/b/b+1覆盖,包含嵌套容器与query交叠/空档。
317
+
318
+ **R02 布局过程:** 320–2560 CSS px连续检查,自动采样步长不超过32,异常区再细化。只测起终点不算通过;页面`scrollWidth`正常也不能证明子节点未截字。支持超宽工作台另加3440样本。普通正文不产生页面级横向长页;必要表格/图形二维区按A规则登记。
319
+
320
+ **R03 输入:** 每个可操作组件必须有keyboard;有触摸能力时采用touch/mixed目标,不依赖hover。只有确认无触控路径的fine+hover profile可以compact;仅`pointer:fine`不够,混合设备可同时存在coarse指针,见[any-pointer](https://developer.mozilla.org/en-US/docs/Web/CSS/Reference/At-rules/@media/any-pointer)。CSS无法可靠确认时保留44舒适目标。
321
+
322
+ **R04 高度与滚动:** 手机/平板横屏、短窗口、地址栏伸缩、safe-area与软键盘均检查。不得无必要性地锁定方向;对应条款适用性登记。固定区只有一个安全区留白owner;使用dvh/svh等不自动证明正确。页面、侧栏、详情、浮层的滚动所有权明确,wheel/touch/PageDown与Tab末项均可达。
323
+
324
+ **R04a 短高浮层回归:** 在短高窗口及软键盘前后,同时打开Toast与Modal时,记录内部滚动、footer、关闭、backdrop 覆盖范围与焦点可达性;只确认页面无横向溢出不构成通过。
325
+
326
+ **R05 过程中适配:** 打开modal/menu、聚焦输入、滚动中resize/旋转/平板分屏,不能出现残留scrim、双导航、输入丢失、重复请求、滚动锁死。侧栏折叠等既有行为保持,不能为CSS方便改路由或组件挂载。
327
+
328
+ **R06 动效:** 颜色反馈默认120ms、控件过渡160ms、浮层视觉200ms;按现有交互配方使用。reduce-motion去除非必要位移/缩放和循环装饰,保留状态反馈;UI-only迁移不可更改业务计时或既有toast生命周期或靠动画完成事件推进任务。不得用动效遮掩加载/错误。
329
+
330
+ **R06a 可选Sheet入场变体:** 采用者可配置底部滑入(建议320ms、cubic-bezier(.22,1,.36,1))及遮罩淡入(建议200ms);这是公共可选能力,不自动应用于全部Dialog。按面板自身高度移动,步骤更新不重播,结束后不留下额外定位上下文;减弱动效时关闭非必要位移。适用断点由采用者登记,触发与关闭不改变业务计时。验收中间帧、重复打开、中途关闭、焦点、内部滚动和减弱动效。
331
+
332
+ <a id="accessibility"></a>
333
+
334
+ ## 10. 可访问性要求与判定边界(A类)
335
+
336
+ 这些是高频验收项,不是完整WCAG符合性清单。每个前端须另登记所有适用的WCAG 2.2 A/AA条款,包括名称/角色/状态、结构、键盘、错误识别、状态消息,以及金融确认/认证场景相关要求;不能只跑下表便宣称WCAG合规。需要逻辑变更的缺陷仍保持G06未关闭。
337
+
338
+ | 规则 | 通过条件与边界 |
339
+ |---|---|
340
+ | A01 文字对比 | 普通文字≥4.5:1;WCAG定义大字≥3:1。大字为至少18pt常规或14pt粗体(约24px或18.67px粗体),不能把所有18px/600直接算大字。例外按条款适用性判断。[文字对比](https://www.w3.org/WAI/WCAG22/Understanding/contrast-minimum.html) |
341
+ | A02 非文字对比 | 识别可用控件/状态所需视觉与必要图形相邻颜色≥3:1;不是要求所有装饰分割线达3:1。按实际使用面及例外判断。[非文字对比](https://www.w3.org/WAI/WCAG22/Understanding/non-text-contrast.html) |
342
+ | A03 目标尺寸 | WCAG AA目标24×24 CSS px及条款例外独立核验;圆/圆角等实际点击形状、相邻目标中心与间距须检查,bounding box达24不是唯一证据。Facto触控44是项目更高目标,不冒称AA硬门槛。[目标尺寸](https://www.w3.org/WAI/WCAG22/Understanding/target-size-minimum.html) |
343
+ | A04 文字放大 | 用户能放大文字至200%且不丢内容/功能,按条款例外处理。记录真实浏览器缩放机制;额外Firefox text-only检查,不用截图整体放大代替。[Resize Text](https://www.w3.org/WAI/WCAG22/Understanding/resize-text.html) |
344
+ | A05 Reflow | 横排内容以等效320 CSS px宽检查纵向阅读;256 CSS px高适用于以横向滚动为阅读方向的内容,不是普通手机横屏门槛。必要二维内容的例外局限于其区域。[Reflow](https://www.w3.org/WAI/WCAG22/Understanding/reflow.html) |
345
+ | A06 文本间距 | 同时施加行高1.5倍、段后2em、字距.12em、词距.16em仍不丢内容/功能;段后间距作用于段落,不能给每个div/button都注入margin。语言不适用项按条款记录。压力值不是默认设计值。[Text Spacing](https://www.w3.org/WAI/WCAG22/Understanding/text-spacing.html) |
346
+ | A07 键盘与焦点 | 逐条核验可用键盘路径、无陷阱、顺序有意义、焦点可见且不被作者内容完全遮挡;Facto进一步要求焦点/当前操作清楚可辨。2px轮廓不是AA自动结论,需看实际对比/遮挡 |
347
+ | A08 内容与输入 | 持久标签/结构与可访问名称正确;颜色不是唯一信息;hover/focus附加内容在适用场景可关闭、可到达且保持。使用Tab/Shift+Tab、Enter/Space及相应组件模式按键,overlay再测Escape;不改变现有语义来规避缺陷 |
348
+
349
+ 适用条款原文以[WCAG 2.2](https://www.w3.org/TR/WCAG22/)为准,Understanding页面是解释;[ARIA APG Dialog](https://www.w3.org/WAI/ARIA/apg/patterns/dialog-modal/)辅助核查模式,不等于正式符合性证明。disabled/装饰例外逐项登记,不可把“次要文字”当低对比例外。
350
+
351
+ <a id="acceptance"></a>
352
+
353
+ ## 11. Mock与验收执行协议
354
+
355
+ 记录完成率、错误及卡住点、任务耗时和观察条件;未做真实用户测试只能声明专家评审/模拟验收。性能另记录加载、交互响应与布局偏移的测量环境和基线,禁止以固定动画时长代表性能通过。新增规范不能自动补齐历史验收证据。
356
+
357
+ **E00 任务与体验:** 除工程与几何检查,按采用者实际任务验证状态能否理解、下一步能否发现、错误能否恢复。记录任务完成情况、错误、卡住点、耗时和观察条件;未做真实用户测试只声明专家评审或模拟验证。性能记录加载、交互及布局偏移的环境、基线和结果,动画时长不能代替性能指标。
358
+
359
+ ### 11.1 执行前登记与覆盖分母
360
+
361
+ 先从源码与实际运行对账路由、组件族、变体、现有状态、模式/flag、第三方边界、断点与容器。每个app/profile单独统计,页面承载与隔离primitive分开;不能把截图数、TSX文件数或组织family数当成已覆盖变体数。
362
+
363
+ **E01 覆盖输入冻结:** 对账结果必须保存为版本化inventory,记录revision/hash并随run保存。每条含`inventory_id / object-type / app-profile / route-or-mount / component-variant / reachable-states-flags / third-party-owner-boundary / risk / core-task-reason / in-or-out-scope-reason`。case引用对应inventory_id;别名/重定向与组件重复引用去重,新增发现追加版本并使受影响case重新规划。每个条目必须映射case或有明确排除理由;未找到、不可达、缺fixture的在范围内条目保留未验证,不能静默删除。
364
+
365
+ **E02 核心任务不是自由抽样:** 至少包含在范围内的身份/会话入口(若有)、每类资金操作/安全或权限变更/创建修改提交确认/管理批量操作的高风险任务及其失败恢复路径,关键金融或权限只读页;Hosted支付/认证不能因外部依赖排除。纯阅读/门户至少包含导航、搜索/服务发现、代码与复制等已有主要任务。按实现列出任务起点、步骤、终点和涉及的inventory_id,不存在者注明不适用理由。每个高风险任务必须纳入核心集合;普通重复任务可采用有理由的代表样本,但不得移出inventory。
366
+
367
+ 报告分别公布inventory条目数、已映射/未映射/排除数及各理由,再按风险/状态/app公布case的planned/executed/disposition。未完成inventory对账或存在未处理的在范围内漏项,不得宣称“声明范围产品通过”或“全端通过”。
368
+
369
+ 每个组件变体至少建立 normal 的宽/中/窄三条planned case,再加入风险/状态矩阵。固定容器组件记录视口及实际容器宽;无normal或不适用某档需写理由。缺fixture/浏览器/设备的case先保留 `UNVERIFIED`,不能等可运行了才加入分母。
370
+
371
+ 稳定ID格式:`app/variant/route-or-mount/fixture/state/environment_id`;各段规范化并转义分隔符。`environment_id`为下方environment对象的canonical JSON(递归按key排序、统一单位)完整SHA-256,环境清单与hash一起保存,不能只保存一个不可解释hash。theme、系统模式、目标设备或宿主容器变化分别生成case;同环境重跑用独立run_id,case计数仍为1,报告显式选择匹配当前基线的有效run,历史失败不删除。同条件下多条断言可归为一个case,不重复计数。
372
+
373
+ 以下字段不可省略,未知填null和原因(planned保留UNVERIFIED);environment的容器字段是预设宿主约束,实际几何另存run证据,不用候选布局产生的浮点噪声重新生成case:
374
+
375
+ ```yaml
376
+ case_id: "app/variant/route/fixture/state/environment_id"
377
+ standard_version: "1.2"
378
+ inventory_ids_and_hash: "对应条目ID列表与冻结inventory hash"
379
+ app_profile: "dashboard | workbench | hosted | reading"
380
+ variant_id: "来自本app登记的稳定组件变体ID"
381
+ route_or_mount: "页面路径+模式 或 隔离挂载符号"
382
+ fixture_id_and_hash: "固定数据、时钟、状态与hash"
383
+ environment:
384
+ viewport: "宽、高,CSS px"
385
+ container: "稳定宿主ID、目标可用宽/高约束、侧栏/嵌入/分屏布局上下文"
386
+ input_profile: "keyboard | touch | fine-hover | mixed"
387
+ target_platform_device: "模拟/真机、设备型号、OS与版本"
388
+ browser_engine_version: "浏览器、引擎、准确版本"
389
+ dpr: "设备像素比"
390
+ locale_direction_timezone: "语言、LTR/RTL、时区"
391
+ theme_brand: "已支持的主题与品牌变体"
392
+ system_mode: "forced-colors、reduce-motion、contrast-preference、系统文字倍率"
393
+ text_test_mode: "浏览器page zoom/text-only zoom、文本倍率、text-spacing配置hash"
394
+ rules_risk_mandatory: "适用规则、风险及强制/抽样"
395
+ actions_expected: "可重放步骤、样式/可读性与既有行为断言"
396
+ locator: "稳定testid/role+name/源码符号;必要时注明备用定位"
397
+ run_id_and_evidence: "唯一运行ID与截图/computed/trace等路径"
398
+ readiness: "ready | blocked,并说明原因"
399
+ disposition: "PASS | FAIL-OPEN | OUT-OF-SCOPE-OPEN | EXCEPTION-APPROVED | N/A | UNVERIFIED"
400
+ ```
401
+
402
+ ### 11.2 最低矩阵与抽样方法
403
+
404
+ | 层级 | 强制覆盖 |
405
+ |---|---|
406
+ | 每个在范围内变体 | 1440×900、834×1194、390×844的基础样本;实际host太窄时以容器宽归档而非假称wide。每个可聚焦控件至少一个keyboard路径,每个现有状态至少一个适用宽度 |
407
+ | 每个app的shell与核心任务 | 320×568、360×800、430×932、507×800、600×800、768×1024、1024×768、1194×834、1280×720、1920×1080、2560×1440;另667×375、844×390短高横屏,连续宽度检查。支持超宽时3440×1440 |
408
+ | 高风险变体 | 表单/浮层/导航/主从详情/金融标识/图表网络:320与834长内容,实际query边界b−1/b/b+1,短高、相关错误/禁用/加载态;200%文字、320 Reflow、text-spacing分别执行,不能互相替代 |
409
+ | 输入能力 | 同一834或其他已登记中宽分别keyboard、fine+hover、touch/mixed;小屏touch与大屏keyboard,hover不作为唯一可用入口 |
410
+ | 引擎与显示 | Chromium/WebKit/Firefox准确版本;每个引擎至少shell、表单/select、浮层、滚动和长内容核心任务。DPR1/2,3在移动高风险样本;forced-colors、reduce-motion及已支持主题分别记录 |
411
+ | 真机 | iPhone Safari、iPad Safari竖/横/分屏、Android Chrome;桌面Safari、Chrome及Edge。记录设备/OS/浏览器/可见viewport;核心表单在键盘出现前/出现后/滚至主操作/收起四阶段,iPad另测可用的外接键盘路径 |
412
+ | 辅助访问 | 桌面屏幕阅读器+浏览器与移动VoiceOver/TalkBack的核心导航/表单/状态路径,记录实际组合;系统文字放大、浏览器文字放大分开 |
413
+
414
+ 非高风险的其余组合用确定性pairwise:维度为现有state×宽度档×输入×已支持主题×locale;单一浅色应用的theme维度只有light,不生成dark/system产品主题样本。按字典序生成候选与可行成对组合,每次选覆盖未覆盖pair最多的case,平局按case_id字典序,直至所有适用pair覆盖。记录算法版本、输入维度、被排除组合的理由与生成清单;至少保留上述强制case。若改用risk-based抽样,必须登记同样明确的选择规则、最低样本和未覆盖项,不能用“随机抽几张”替代。
415
+
416
+ English长文/CJK回退、空值/0/大数/负数/长币种或地址/同名卡/多行错误必须覆盖其适用高风险变体。只测原型当前账户或短名字不足以验收。
417
+
418
+ ### 11.3 Mock安全与真实组件
419
+
420
+ - 使用产品真实组件与路由,fixture经已有API/store接口在隔离测试环境注入;静态重画页面或DOM改字截图不证明产品通过。fixture必须符合原schema、稳定ID、状态与真实内容约束,不能改数据含义掩盖UI缺陷。
421
+ - 运行前拒绝生产后端/生产钱包/真实会话;请求拦截必须覆盖HTTP、RPC、WebSocket/SSE与第三方写出路径,并记录实际请求。测试隔离不能侵入生产代码或打包产物。
422
+ - **E03 默认关闭外发:** 应用启动前建立覆盖HTTP/RPC/WebSocket/SSE/导航与第三方请求的精确allowlist;除精确mock及具名登记的本地测试origin/静态资产外一律在网络分派前abort/fail。记录channel、脱敏请求指纹、可取得的initiator与case_id;未知请求记mock-gap,case为UNVERIFIED,不允许记录后继续转发,也不能宽泛返回空数据。无法在分派前控制的渠道使case blocked+UNVERIFIED。
423
+ - 写请求默认拒绝外发;需要进入成功/错误后续状态时,在隔离环境**精确mock该写请求及其响应**,记录请求与本地存储副作用,绝不放行真实写出。需真实第三方测试会话的验证另列受控集成case与范围,不能混入纯mock的通过计数;未知请求仍不放行。
424
+ - 订阅、重连、取消、延时与重试有明确fixture生命周期;后台轮询/时钟固定。外部身份、hosted token和第三方组件使用专门测试会话;拿不到则blocked+UNVERIFIED,不偷偷跳过。
425
+ - 选择器未找到、超时、mock缺口、浏览器缺失首先是harness/环境问题;不能冒充产品缺陷或通过。可复现产品缺陷需另外证据支持。
426
+
427
+ ### 11.4 来源、断言与非回归
428
+
429
+ 每次run记录:baseline revision、candidate revision或patch hash、dirty状态、lockfile/hash、build来源/hash(适用时)、非秘密模式、fixture/hash、字体资产/实际字体、browser/OS/tool版本、viewport/container/DPR/input、locale/timezone、timestamp、**完整可重跑命令及工作目录**。不把固定历史SHA写成所有未来app基线;每个任务先冻结自己的最新来源,来源变化则重验受影响case。
430
+
431
+ 视觉证据至少截图+相关computed style/geometry;交互依规则增加focus/accessibility/scroll记录,副作用增加network/RPC/subscription/storage trace。截图在字体加载和状态稳定后采集。阈值必须针对可判定预期:例如关键标题完整、末四位未裁切、对比达标、focus投射可见;“截图存在”“class匹配”或“axe零告警”均不够。
432
+
433
+ UI候选与baseline使用相同fixture、初始快照、时钟和动作脚本,对比值/校验/状态结果和请求/订阅/存储行为。允许的时间噪声或动态ID预先登记,不能事后忽略异常。只改CSS也要检查被影响的键盘/触控/resize路径;行为敏感布局按G04扩大trace。对于共享变更,所有受影响消费者进入矩阵。
434
+
435
+ 纯文档制定不需要伪跑产品构建。进入产品实施后,命令映射必须来自该repo实际脚本:受影响app的typecheck/lint/build、现有相关测试、strict mock case、视觉/键盘回归及diff边界审查。缺命令/环境记录未验证,不编造通用脚本已通过。
436
+
437
+ ### 11.5 状态与计数
438
+
439
+ `planned`为冻结case总数,含N/A与blocked;`applicable=planned−N/A`;`executable`为适用且先决条件具备的case;`executed`为实际完成动作与预期检查且有完整来源的case(通过或失败均可)。执行中断不计完整executed,保留日志和UNVERIFIED。disposition六种互斥,数量之和必须等于planned。readiness与是否执行是独立属性,不是第七种结论。
440
+
441
+ - `PASS`:适用规则断言全部通过,证据/来源/fixture完整;UI候选还须通过G01与相关非回归。
442
+ - `FAIL-OPEN`:有足够证据确认产品视觉/可访问性偏差。
443
+ - `OUT-OF-SCOPE-OPEN`:缺陷已确认,修复需超出授权范围;不算PASS。
444
+ - `EXCEPTION-APPROVED`:B/C设计偏离已完成登记审批;单独统计,不能当原规则PASS。
445
+ - `N/A`:确实不适用且有理由;缺设备/fixture不是N/A。
446
+ - `UNVERIFIED`:证据不足、未运行、harness失败或外部依赖缺失;始终留在planned。
447
+
448
+ <a id="governance"></a>
449
+
450
+ ## 12. 审计判定、变更治理与采用门禁
451
+
452
+ ### 12.1 三个互不替代的结论
453
+
454
+ 1. **规范文档就绪:** 规则有明确范围、默认值/变体、证据要求、验收方法与边界;独立审查无未关闭的实质缺口/矛盾。仅此结论允许说“标准文档已通过复核,可供采用”。
455
+ 2. **UI-only安全通过:** 候选diff严格符合G01–G06,相关非回归证据完整。安全通过不代表视觉已合格。
456
+ 3. **产品在声明范围通过:** 所有必测适用case完成且无FAIL/OUT-OF-SCOPE/UNVERIFIED,B/C偏离若有批准例外须在结论明列;C类设计复核通过。任何必测真机/浏览器缺证据不得声称“全端通过”。
457
+
458
+ 全面产品结论还要列出非强制抽样未测集合;抽样通过不能表述为所有状态×设备全组合已实测。无例外的完全符合与带已批准设计例外的受限采用分别表述。A类真实缺陷与G01越界不能用设计例外豁免成通过。
459
+
460
+ ### 12.2 问题单与设计复核
461
+
462
+ 每项finding记录 `id / app-route-component-state / rule-A-B-C / baseline / viewport-input / actual / expected / evidence / severity / scope / fix-direction / acceptance-case`。优先级P1为关键内容/操作/金融标识不可用或重大可读性风险,P2为显著一致性/密度/状态辨识问题,P3为不影响任务的局部光学偏差;优先级与规则依据分开,不能把P2自动当可忽略。
463
+
464
+ C类至少由主审与一名独立审查者在真实宽/中/窄样本对照,检查:信息主次是否清楚、相同角色是否统一、阅读轴/间距关系是否稳定、交互线索是否可靠、品牌是否克制、内容压力下是否仍完整。结论须指向具体截图区域和用户任务影响。分歧回到证据修订,不以多数票或“行业都这样”关闭。
465
+
466
+ ### 12.3 例外与版本
467
+
468
+ 例外记录具体规则/组件/状态/主题/宽度、理由、替代方案、风险、证据、批准角色及实际批准人、到期日与复验触发器。提出者不能代填批准;待批准保留FAIL-OPEN或UNVERIFIED(依是否已确认缺陷),不是EXCEPTION-APPROVED。例外只能用于B/C,不豁免G01或已确认A缺陷。
469
+
470
+ 后续维护由Facto指定的UI标准负责人负责版本与角色表;评审至少含设计与前端/验收两种视角。新角色、默认值或适用范围变化须更新版本、迁移影响与案例;纠正文案/链接等不改语义的修订可patch。采用记录固定版本,不能让在线文档静默改变已验收基线。
471
+
472
+ 开始一次迁移前须具备:明确范围/基线、采用清单、组件/状态inventory、case矩阵、strict mock与命令映射、允许的展示文件和共享消费者列表。没有这些可以先完成调查,不能宣称实施与验收全部就绪。标准发布不等于所有应用已经迁移。
473
+
474
+ <a id="reuse"></a>
475
+
476
+ ## 12a. 公共UI复用与采用边界
477
+
478
+ 共享库负责token、字体资源、组件外观、通用交互及可访问性契约;业务应用负责路由、认证、权限、支付状态及请求。公共组件不得硬编码Dashboard页面名、provider或业务枚举。组件变体应通过公开属性表达,不要求调用方复制页面选择器。
479
+
480
+ 每个采用者记录标准修订、准确包版本、公开组件/API映射、资源完整性、实际解析版本及验收证据。源码、本地安装和npm发布版本分别记录,不能互相推定。发布时同步随包skill/reference,独立安装后验证桌面/触控/键盘/减弱动效路径。Dashboard的验证不能替代SDK或其他消费者验证;具体能力以所安装包的声明和采用元数据为准。
481
+
482
+ <a id="sources"></a>
483
+
484
+ ## 13. 公开参考与证据边界
485
+
486
+ 本文数值是Facto设计选择,不代表第三方认证或其他产品的完整测量结果。
487
+
488
+ - [WCAG 2.2](https://www.w3.org/TR/WCAG22/):可访问性要求。
489
+ - [ARIA APG](https://www.w3.org/WAI/ARIA/apg/):交互模式参考。
490
+ - [Atlassian Typography](https://atlassian.design/foundations/typography/)与[Spacing](https://atlassian.design/foundations/spacing/):角色与尺度方法参考,不是Facto数值认证。
491
+
492
+ ## 14. 公开材料边界
493
+
494
+ 验收原始截图、trace、网络载荷、会话状态、人员身份、工作目录和内部架构保存在采用者私有环境,不进入公共文档或npm包。公开报告仅使用脱敏摘要和合成示例;不得输出凭据、真实客户数据或内部文档链接。规范要求保存证据,不等于授权公开证据。
495
+
496
+
497
+
498
+ 本版维护规则:此公开规范与SDK组件采用状态分别版本化;消费者按安装包元数据判断实际支持范围。