# 交互走查（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、设置灰度比例与“一键回滚”