90 lines
3.5 KiB
Markdown
90 lines
3.5 KiB
Markdown
|
# 交互走查（UI v2）
|
|||
|
|
|
|||
|
|
## 1. 动效参数（Motion Tokens）
|
|||
|
|
- Easing
|
|||
|
|
- `--ease-default`: `cubic-bezier(0.4, 0, 0.2, 1)`
|
|||
|
|
- Duration
|
|||
|
|
- `--duration-fast`: `140ms`（hover/press/focus 的轻量过渡）
|
|||
|
|
- `--duration-normal`: `180ms`（弹窗/抽屉等容器级过渡）
|
|||
|
|
- `--duration-slow`: `260ms`（页面级淡入、复杂布局切换）
|
|||
|
|
- Reduced Motion
|
|||
|
|
- 当 `prefers-reduced-motion: reduce`：所有 transition/animation 时长强制为 `1ms`，并关闭平滑滚动。
|
|||
|
|
|
|||
|
|
## 2. 微交互规范（Micro-interactions）
|
|||
|
|
- Button
|
|||
|
|
- Hover：轻微提升（如 `translateY(-1px)`）+ 阴影增强
|
|||
|
|
- Active：回落（`translateY(0)`）+ 阴影减弱
|
|||
|
|
- Focus-visible：3px 可见焦点环（UI v2 使用 indigo 系）
|
|||
|
|
- Input / Select
|
|||
|
|
- Focus：边框高亮 + 3px 焦点环
|
|||
|
|
- Invalid：`aria-invalid="true"` 时显示错误态（颜色 + 文案）
|
|||
|
|
- Loading
|
|||
|
|
- 页面级：使用非阻塞 Loading（避免焦点丢失/Tab 被截断）
|
|||
|
|
- 按钮级：loading 状态应禁用重复提交并提示“处理中”
|
|||
|
|
|
|||
|
|
## 3. 键盘与焦点顺序（Tab Order）
|
|||
|
|
### 3.1 全局
|
|||
|
|
- 焦点顺序必须与视觉顺序一致（从左到右、从上到下）。
|
|||
|
|
- 页面切换（路由变化）后：
|
|||
|
|
- 默认把焦点设置到页面标题 `h1`（若可实现）或第一个可交互元素。
|
|||
|
|
|
|||
|
|
### 3.2 组件级
|
|||
|
|
- 导航链接（`a`）
|
|||
|
|
- `Tab` 聚焦
|
|||
|
|
- `Enter` 触发导航
|
|||
|
|
- Button（`button`）
|
|||
|
|
- `Tab` 聚焦
|
|||
|
|
- `Enter/Space` 触发
|
|||
|
|
- 输入框（`input`/`textarea`）
|
|||
|
|
- `Tab` 聚焦
|
|||
|
|
- `Esc` 不应清空内容（除非明确说明）
|
|||
|
|
- Select（`select`）
|
|||
|
|
- `Tab` 聚焦
|
|||
|
|
- `Arrow` 在打开态变更选项
|
|||
|
|
|
|||
|
|
### 3.3 模态框（Modal）
|
|||
|
|
- 打开时：
|
|||
|
|
- 焦点移动到第一个可交互控件（或标题 + 关闭按钮）。
|
|||
|
|
- 关闭时：
|
|||
|
|
- 焦点回到触发打开的按钮。
|
|||
|
|
- `Esc`：关闭（如果业务允许）。
|
|||
|
|
|
|||
|
|
## 4. 无障碍标签与语义（WCAG 2.1 AA 关键点）
|
|||
|
|
### 4.1 颜色对比
|
|||
|
|
- 正文、按钮文字、表单占位与边框需满足 AA 对比度要求。
|
|||
|
|
- 通过令牌层保证：`--text-primary/secondary/tertiary` 与 `--bg-*` 配对达标。
|
|||
|
|
|
|||
|
|
### 4.2 表单
|
|||
|
|
- 每个输入控件必须有可见 `label`。
|
|||
|
|
- 错误提示与输入框绑定：
|
|||
|
|
- 输入框：`aria-invalid="true"`
|
|||
|
|
- 错误文本：为其生成 `id` 并用 `aria-describedby` 关联
|
|||
|
|
- 提交失败：聚焦到第一个错误字段并播报错误（可通过 `aria-live`）。
|
|||
|
|
|
|||
|
|
### 4.3 图标按钮
|
|||
|
|
- 若按钮仅图标，必须提供可读名称：
|
|||
|
|
- `aria-label="关闭"` / `title="关闭"`
|
|||
|
|
|
|||
|
|
### 4.4 通知（Toast/Alert）
|
|||
|
|
- 错误类：建议 `role="alert"`（立即播报）
|
|||
|
|
- 信息类：建议 `role="status"`（非打断播报）
|
|||
|
|
|
|||
|
|
## 5. 像素级验收建议（与工程联动）
|
|||
|
|
- 验收基线：
|
|||
|
|
- 每个关键页面至少 1 张桌面端基线截图（含主要状态：默认/空态/加载/错误）。
|
|||
|
|
- 容差：
|
|||
|
|
- 像素级对比误差 ≤ 1px（文本抗锯齿允许极小差异，建议在工具中配置阈值）。
|
|||
|
|
- 关键路径：
|
|||
|
|
- 登录 → 进入首页 → 打开核心模块 → 创建/编辑/删除关键实体（若业务允许）。
|
|||
|
|
|
|||
|
|
## 6. 灰度与回滚交互（前端开关）
|
|||
|
|
- UI 版本
|
|||
|
|
- `document.documentElement.dataset.ui`：`v1` / `v2`
|
|||
|
|
- 本地覆盖：`localStorage.gemold_ui_version`
|
|||
|
|
- 灰度比例：`localStorage.gemold_ui_rollout_percent`（0–100）
|
|||
|
|
- 主题
|
|||
|
|
- `document.documentElement.dataset.theme`：`light` / `dark`
|
|||
|
|
- 本地覆盖：`localStorage.gemold_theme`
|
|||
|
|
- 内部控制台
|
|||
|
|
- `/_release`：提供切换 v1/v2、设置灰度比例与“一键回滚”
|