# UI 设计规范 · design.md 版本 1.5 · 2026-09-16 · 参考实现:玩法一「数字一笔」(`modes/01-number-stroke`)。设计师看图请打开同目录的 [`design.html`](design.html)(可离线双击,含色板、字阶、组件样张与可回放的动效)。 本文是产品级的视觉与动效规范。规则、关卡、交互语义仍以各玩法的 GDD 为准;本文只管「长什么样、怎么动」。 ## 0. 怎么用这份文档 三处必须一致,改任何一处都要同步另外两处: | 位置 | 内容 | 谁在用 | |---|---|---| | `docs/design.md` + `docs/design.html` | 规范与样张 | 设计师、接手人 | | `modes/01-number-stroke/web/style.css` 的 `:root` | CSS 令牌 | DOM 壳(选关、顶栏、底栏、toast) | | `modes/01-number-stroke/src/theme.ts` | `THEME` / `BOARD_TYPE` / `MOTION` | Canvas 盘面(Web 与 Cocos 共用) | `tests/theme.test.ts` 会校验 `style.css` 与 `theme.ts` 的颜色、动效时长、字体栈一致,改了一边没改另一边 `npm run check` 会红。 **改设计的流程**:先改本文对应表格 → 改 `style.css` / `theme.ts` → 改 `design.html` 样张 → 在 §12 变更记录追加一行。 ## 1. 设计原则 1. **板要干净。** 逻辑 puzzle 的盘面只回答三个问题:我走到哪了、哪错了、过没过。任何装饰都不能和这三件事抢注意力。 2. **一个主色。** 蓝紫 `#6558F5` 只表示「已走 / 当前 / 可继续」。红只表示冲突,琥珀只表示提示。不要每关换主题色。 3. **数字优先。** 盘面上的数字是内容本身。数字用系统圆体、800 字重、等宽数字;其余文字都比数字轻。 4. **动效四档。** 所有动效只用 120 / 200 / 320 / 500 ms 四档时长和四条缓动曲线。新动效先归档,再写代码。 5. **反馈紧贴手指。** 落子、踩对、冲突、死路的反馈都发生在手指所在的格子上,不弹窗、不撒纸片。 6. **信息随手可见。** 关号、包名、本包进度、剩余格数常驻顶栏,一眼看清「我在哪、还差多少」。 ## 2. 色彩 浅色单主题。所有颜色取自下表,DOM 用 CSS 变量,Canvas 用 `THEME`。 ### 2.1 令牌 | 令牌 | 值 | 用途 | CSS | theme.ts | |---|---|---|---|---| | 背景 | `#FFFFFF` | 页面与盘面背景 | `--bg` | `bg` | | 桌面底 | `#F2F2F6` | 桌面浏览器上手机框外的底色 | `--bg-app` | – | | 二级表面 | `#F3F3F7` | 按钮、胶囊、chip、锁定关卡格 | `--surface-2` | – | | 未走格 | `#E6E7EC` | 盘面未走格、选关未过关格、进度条底 | `--cell` | `cell` | | 分隔线 | `#E1E2EA` | 细线(预留) | `--line` | – | | 墨 | `#23243A` | 标题、正文、未走线索数字、冲突角标底 | `--ink` | `clueInk` | | 墨 2 | `#6B6D80` | 副文案、字幕、胶囊文字、图标 | `--ink-2` | – | | 墨 3 | `#A3A5B5` | 弱文案、进度数字、锁图标 | `--ink-3` | – | | 主色 | `#6558F5` | 已走格、桥、当前关、主按钮、进度 | `--primary` | `visited` | | 主色·亮 | `#7D72FF` | 过关后全盘提亮 | `--primary-bright` | `visitedBright` | | 主色·淡 | `#ECEAFE` | 当前关格底、开启态 chip、完成态胶囊 | `--primary-soft` | – | | 主色上的字 | `#FFFFFF` | 已走格数字、主按钮文字 | `--on-primary` | `visitedInk` | | 冲突 | `#E5484D` | 冲突格、重置进度 | `--danger` | `conflict` | | 冲突·淡 | `#FDECEC` | 预留(高对比模式) | `--danger-soft` | – | | 提示 | `#F5A524` | 提示描边、提示按钮脉冲 | `--hint` | `hint` | | 提示·淡 | `#FEF3DD` | 预留 | `--hint-soft` | – | | 线索描边 | `#23243A` | 未走线索 / 奇偶格的描边(= 墨,与线索数字同色) | `--clue-ring` | `clueRing` | | 已走线索描边 | `#DFE1EC` | 起点与已走线索格外圈的灰白描边 | – | `activeClueRing` | | 闪色 | `#FFFFFF` | 踩对线索闪白、过关扫光 | – | `flash` | | 遮罩 | `rgba(35,36,58,.92)` | toast 底 | `--overlay` | – | 阴影:主按钮 `0 6px 18px rgba(101,88,245,.28)`,按下时 `0 3px 10px rgba(101,88,245,.22)`;桌面手机框 `0 20px 60px rgba(20,20,40,.14)`。盘面无阴影。 ### 2.2 语义规则 - 紫 = 路径。已走格、桥、起点 `1`、当前关、主按钮、进度条都是同一个紫。 - 红只出现在冲突格。错误发生时该格轻晃 280ms,进出连线保持紫色;步号占用别处固定数字时不显示「×」。本格数字 / 奇偶要求不符时仍保留原要求角标。 - 琥珀只出现在提示描边和提示按钮脉冲,不用于任何常驻元素。 - 灰阶承担一切非路径信息:未走格 `cell`、文字三档墨。未走线索 / 奇偶格的描边与线索数字同用墨色,像印在盘上的一圈,不引入第二种彩色。 - 过关后全盘从 `primary` 切到 `primary-bright`,这是唯一允许的「换色」。 ### 2.3 对比度 | 组合 | 对比度 | 用途 | |---|---|---| | `#FFFFFF` on `#6558F5` | 5.2 : 1 | 已走格数字、主按钮 | | `#23243A` on `#E6E7EC` | 12.6 : 1 | 未走线索数字 | | `#FFFFFF` on `#E5484D` | 4.5 : 1 | 冲突格数字(角标另有墨底白字) | | `#6B6D80` on `#FFFFFF` | 5.1 : 1 | 副文案 | | `#23243A` on `#E6E7EC` | 12.6 : 1 | 未走线索描边(与数字同色) | | `#A3A5B5` on `#FFFFFF` | 2.5 : 1 | 仅用于非关键弱文案 | ## 3. 字体与字阶 ### 3.1 字体栈 ``` ui-rounded, "SF Pro Rounded", "PingFang SC", "Hiragino Sans GB", "Noto Sans SC", system-ui, -apple-system, "Segoe UI", sans-serif ``` `ui-rounded` 让 iOS / macOS 直接拿到系统圆体(数字圆润、与圆角格子同气质);Android 回落到 Noto Sans SC;Windows 回落到 Segoe UI。DOM 与 Canvas 用同一串(`--font` 与 `BOARD_FONT_FAMILY`)。 全局 `font-variant-numeric: tabular-nums`,所有数字等宽,计数变化时不跳动。 ### 3.2 UI 字阶 | 名称 | 字号 / 字重 | 用途 | CSS | |---|---|---|---| | display | 34 / 800 | 选关页标题 | `--fs-display` | | title | 22 / 800 | 顶栏关号 `1-7` | `--fs-title` | | heading | 17 / 700 | 包标题、主按钮 | `--fs-heading` | | body | 15 / 500 | 副标题、字幕 | `--fs-body` | | label | 14 / 600–700 | 剩余格胶囊、包进度、toast | `--fs-label` | | caption | 13 / 600 | chip、总进度数字 | `--fs-caption` | | micro | 12 / 600 | 顶栏副标题「入门 · 第 7 关」(字距 0.04em) | `--fs-micro` | 选关关卡格数字 20 / 700;底栏按钮 15 / 700。 ### 3.3 盘面字阶(相对单位格边长 u) | 用途 | 比例 | 字重 | theme.ts | |---|---|---|---| | 起点 `1`(未按下的提示态与已走第 1 步) | 0.60 u | 800 | `BOARD_TYPE.start` | | 单位数步号 / 线索 | 0.52 u | 800 | `single` | | 两位数步号 / 线索 | 0.46 u | 800 | `double` | | 未走奇偶格「奇 / 偶」 | 0.44 u | 700 | `parity` | | 已走奇偶格下方小字「奇 / 偶」 | 0.19 u | 700 | `paritySub` | | 冲突角标半径 / 角标字号 | 0.15 u / 半径 × 1.25 | 800 | `badge` / `badgeText` | | 线索描边线宽 | 0.05 u(≥ 2px) | – | `ring` | | 提示描边线宽 | 0.08 u(≥ 3px) | – | `hintRing` | 数字一律 800,汉字 700,文字基线下沉 4% 字号做视觉居中。大格 / 异形格的数字放在锚点单位(形心最近的单位格)中心。 ## 4. 间距、圆角、尺寸 - **间距**:4pt 网格。`--sp-1..7` = 4 / 8 / 12 / 16 / 20 / 24 / 28。页面左右内边距 20,顶部 12 + 安全区,底部 16 + 安全区。 - **圆角**:`--r-sm` 10(预留)、`--r-md` 14(关卡格、toast)、`--r-lg` 18(主按钮、底栏按钮)、`--r-xl` 24(预留)、`--r-pill` 胶囊。桌面手机框 28。 - **盘面**:格圆角 0.18 u,格间缝 0.10 u,桥厚 0.46 u。 - **点击区**:所有可点元素 ≥ 44 × 44(`--tap`)。返回按钮 44,chip 34 高但左右各留 16 内边距。 - **桌面**:≥ 520px 宽时以 480px 手机框居中,四周 24 留白,圆角 28 + 框阴影。 ## 5. 盘面(Canvas) ### 5.1 布局 - `fitBoard`:按短边缩放,四周留 10px,单位格封顶 96px(≤ 6 格的教学盘)或 110px。 - 整盘垂直居中后**上提容器高度的 3%**:视觉中心略高于几何中心,小盘不显得下坠。 - 命中测试:触屏每格四周 8% 死区,鼠标 14%。点按或滑到任意历史格可直接回退;触点进入历史格时优先处理回退。 ### 5.2 格的状态 | 状态 | 底 | 描边 | 数字 | 备注 | |---|---|---|---|---| | 未走 | `cell` | 无 | 无 | – | | 未走线索 | `cell` | `clue-ring`(墨)0.05 u | `ink` 0.52 / 0.46 u | 描边用「外层剪影 + 内层填充」画,矩形与异形同一画法 | | 未走奇偶 | `cell` | `clue-ring`(墨)0.05 u | 「奇 / 偶」`ink` 0.44 u | – | | 起点 `1`(未按下) | `primary` | `activeClueRing` | `on-primary` 0.60 u | 只是视觉提示,按下才计入路径 | | 已走 | `primary` | 无 | 步号 `on-primary` | 与相邻已走格之间画桥 | | 已走线索 / 起点 | `primary` | `activeClueRing` | 步号 | 描边保留,说明它曾是线索 | | 已走奇偶 | `primary` | `activeClueRing` | 步号上移 0.09 u,下方 0.19 u 小字「奇 / 偶」 | – | | 冲突 | `danger` | 线索有描边则 `activeClueRing` | 步号 `on-primary` | 单格轻晃 280ms,连接线仍紫色;步号错位无叉号。本格要求不符时保留数字 / 奇偶角标,半径 0.15 u | | 补数字 | 同普通线索 | 先叠加琥珀外圈 2.4s,之后恢复普通线索描边 | 新数字使用普通数字字阶;奇偶格保留下方小字 | 本局重开仍保留数字 | | 提示目标 | 不变 | 外圈 `hint` 描边 0.08 u,向外扩一线宽 | 不变 | 2.4s 脉冲后消失 | | 退回压暗 | 覆 `bg` 45% | – | – | 提示「已偏离」时,分叉点之后的段压暗 | | 过关 | `primary-bright` | – | – | 按步序扫白光 | 大格(2×2、3×3、1×2…)是一个圆角矩形;异形格由单位矩形 + 接缝矩形同色拼成一整块,凸角圆、凹角直。 ### 5.3 桥 两个相邻已走格之间的连接:沿共享边居中,厚 0.46 u,跨缝方向盖满缝再多 1px。始终使用路径色;任一侧冲突也不变红、不随格子晃动。**生长动画只长厚度**,跨缝方向从第一帧起就盖满,不露白缝。 ## 6. 组件 ### 6.1 顶栏(对局) ``` [←] 1-7 [▢ 6] 入门 · 第 7 关 ▬▬ ▬▬ ▬▬ ▬▬ ▬▬ ▬▬ ▬▬ ▬▬ ▬▬ ▬▬ ← 本包进度条 ``` - 三列网格 `1fr auto 1fr`,中间永远居中。高 52。 - 返回:44 圆形点击区,墨 2 色 26px 箭头,按下时底 `surface-2`。 - 关号:title 22 / 800;副标题 micro 12 / 600 墨 3,内容 `{包名} · 第 {n} 关`。 - 剩余格胶囊:高 32,`surface-2` 底,墨 2 字 14 / 700,左侧 16px 圆角方框图标(墨 3)。数字变化时 `bump`(200ms spring 缩放 1 → 1.14 → 1)。过关后切到 `done`:底 `primary-soft`、字与图标 `primary`、图标换勾、文字「完成」。 - 本包进度条:每关一段,高 4,段间 3,圆角 2。灰 = 未到,紫 40% = 已过,紫 100% = 当前。 ### 6.2 字幕 顶栏下方 36 高一行,body 15 / 500 墨 2 居中。只有教学关有内容,空时 200ms 淡出。 ### 6.3 底栏 三个等宽按钮「重开 / 补数字 / 指路」(最大 170),高 56,圆角 18,`surface-2` 底,15 / 700 墨色,图标 22px 墨 2,图标与文字间距 4px。按下底色变 `cell` + 缩放 0.97。禁用 40% 透明。「指路」发现起手错时,重开按钮 `pulse`:0.9s 琥珀外圈呼吸。 底栏上方是常驻手势说明「按住滑动连线 · 点已走格回退」,caption 13px 墨 2,顶部间距 8px,居中。 ### 6.4 Toast 距页面底边 128px + 底部安全区居中,避开手势说明。圆角 14,`overlay` 底白字 14 / 600,最大宽度为页面宽减 40px,长句自动换行;进出 200ms(透明 + 上移 8px),停留 1.8s。 ### 6.5 选关页 - 标题 display 34 / 800,副标题 body 墨 2;下方**总进度**:6px 胶囊条(`cell` 底、`primary` 填充,320ms 过渡)+ 右侧 `16 / 26` caption 墨 3。 - 包标题 heading 17 / 700,右侧 `x / n` label 墨 3;整包完成时变 `primary`。 - 关卡格:5 列,间距 12,正方形,圆角 14,数字 20 / 700。 - 未过关:`cell` 底墨字。 - 已过关:`primary` 底白字,右上角 CSS 画的小勾。 - 当前:`primary-soft` 底 + 3px 内描边 `primary` + 紫字,2.4s 呼吸外圈。 - 锁定:`surface-2` 底,墨 3 锁图标,无数字;点击 320ms 抖动。 - 按下缩放 0.94。 - 列表可滚,顶部 12px、底部 20px 渐隐遮罩,不被按钮切断。 - 继续按钮:高 54,圆角 18,`primary` 底白字 17 / 700,紫色投影;文案 `继续 · 2-1`。 - 设置 chip:高 34 胶囊,`surface-2` 底墨 2 字 13 / 600;开启态 `primary-soft` 底紫字;「重置进度」红字。 ## 7. 页面 ### 7.1 对局页(自上而下) | 区块 | 高度 | |---|---| | 安全区 + 12 | – | | 顶栏 | 52 | | 本包进度条 | 8 上边距 + 4 | | 字幕 | 8 上边距 + 36 | | 盘面 | 剩余全部(flex: 1) | | 手势说明 | 8 上边距 + caption 行高 | | 底栏 | 12 上边距 + 56 | | 16 + 安全区 | – | ### 7.2 状态流 ``` 选关 ──点关卡 / 继续──▶ 对局(整屏淡入 200ms,盘面错落进场) 对局 ──过关──▶ 扫光 320ms → 停留 500ms → 盘面淡出 160ms → 下一关盘面进场(顶栏就地更新) 对局 ──最后一关过关──▶ 选关(toast「已通关全部 26 关」) 对局 ──返回──▶ 选关(整屏淡入) ``` ## 8. 动效 ### 8.1 时长与缓动 | 档 | 时长 | 用途 | CSS | theme.ts | |---|---|---|---|---| | fast | 120ms | 按下反馈、步号淡入、桥生长 | `--t-fast` | `MOTION.fast` | | base | 200ms | 整屏切换、toast、胶囊 bump、进场单格 | `--t-base` | `MOTION.base` | | slow | 320ms | 闪白衰减、过关扫光、抖动、进度条 | `--t-slow` | `MOTION.slow` | | hold | 500ms | 过关停留 | `--t-hold` | `MOTION.hold` | | 缓动 | 曲线 | 用途 | |---|---|---| | ease-out | `cubic-bezier(.22, 1, .36, 1)` | 进场、淡入、桥生长(Canvas 用 quart ease-out) | | ease-in | `cubic-bezier(.4, 0, 1, 1)` | 退场 | | ease-in-out | `cubic-bezier(.65, 0, .35, 1)` | 呼吸、脉冲 | | spring | `cubic-bezier(.34, 1.56, .64, 1)` | bump;Canvas 弹簧 k=260、c=18、初速 2.4 | ### 8.2 事件 → 动效 | 事件 | 对象 | 动效 | 时长 | 音效 | 振动 | |---|---|---|---|---|---| | 开局 / 切关 | 每个格 | 缩放 0.92 → 1 + 淡入,按阅读顺序每格延迟 14ms,延迟封顶 200ms | base | – | – | | 追加一步 | 当前格 | 弹簧放大回 1(初速 2.4) | ≈ 200 | step(音高随步号) | 8ms | | 追加一步 | 步号 | 淡入 | fast | – | – | | 追加一步 | 桥 | 厚度 0 → 1(ease-out),跨缝方向始终盖满 | fast | – | – | | 踩对线索 | 该格描边 | 闪白 1 → 0 线性衰减 | slow | step | 18ms | | 冲突 | 该格 | 立即红底 + 横向轻晃,幅度 0.06 u 递减;进出连线保持紫色 | 280ms | conflict(闷音) | 40ms | | 撤销 | 该格 / 桥 | 立即褪回,无动画 | 0 | – | – | | 多步回退 | 目标格 | 后缀立即撤回,目标格轻弹;toast 说明回到第几步 | ≈ 200 | – | 12ms | | 补数字 | 目标格 | 数字成为固定线索,目标轻弹并显示琥珀外圈 | 2.4s | – | 18ms | | 死路 | 当前格 | 横向抖动,6 个来回,幅度 0.06 u 递减 | 280ms | – | 10-30-10 | | 非法起手 | 线索 `1` 格 | 同上抖动 | 280ms | reject | 15ms | | 剩余格变化 | 顶栏胶囊 | bump 1 → 1.14 → 1(spring) | base | – | – | | 提示 | 目标格 | 琥珀外描边,≈ 1.1Hz 正弦脉冲,最后 0.4s 淡出 | 2.4s | – | – | | 提示·已偏离 | 分叉后的段 | 覆白 45% 随脉冲 | 2.4s | – | – | | 提示·起手错 | 重开按钮 | 琥珀外圈脉冲 | 0.9s 循环 | – | – | | 过关 | 全盘 | 底色切 `primary-bright`;按步序扫白光,每格 250ms 正弦,整盘 320ms 内起完 | slow | cleared(和弦) | 20-40-30 | | 过关 | 胶囊 | 切 `done`(完成 + 勾) | base | – | – | | 过关后 | 全盘 | 停留 500ms → 淡出 160ms → 下一关进场 | hold + 160 | – | – | | 切屏 | 整屏 | 淡入 + 上移 8px | base | – | – | | Toast | toast | 淡入 + 上移 8px,停 1.8s | base | – | – | | 按钮按下 | 按钮 | 缩放 0.97(关卡格 0.94、主按钮 0.98) | fast | – | – | | 锁定关卡被点 | 关卡格 | 横向抖动 ±5px | slow | – | – | | 当前关 | 关卡格 | 外圈呼吸 0 → 6px 紫 16% | 2.4s 循环 | – | – | ### 8.3 过关时间线 ``` 0ms cleared 事件:全盘切亮色,和弦起,胶囊变「完成」,按钮禁用 0–320ms 按步序扫光(每格 250ms 正弦,起点先亮) 320–820 停留 820–980 整盘淡出(160ms) 980 下一关:顶栏 / 进度条就地更新,新盘面错落进场(≤ 400ms) ``` ### 8.4 减弱动态 系统开启「减弱动态效果」时:CSS 全部动画与过渡关闭;Canvas 去掉进场错落、弹簧、扫光与淡出,只保留状态切换与提示描边(静态显示),错误格变红但不晃动。`BoardView` 通过 `reducedMotion` 选项接收。 ### 8.5 性能约束 `BoardView.update()` 返回 `isAnimating`,宿主只在有动画时重绘;静止时 0 帧。所有动效都是无状态插值(`dt` 封顶 50ms),掉帧不会漏掉状态。 ## 9. 声音与振动 | 事件 | 音效 | 振动 | |---|---|---| | 落子 | 90ms 正弦短音,C5 起每步升半音,12 步循环 | 8ms(踩对线索 18ms) | | 冲突 | 160ms 方波 130Hz 闷音 | 40ms | | 非法起手 | 60ms 三角波 220Hz | 15ms | | 死路 | – | 10-30-10 | | 过关 | C-E-G-C 三角波和弦,每音 220ms 间隔 70ms | 20-40-30 | 均可在选关页 chip 关闭。Cocos 侧换 4 段短音,接口同 `Sfx`。 ## 10. 可访问性 - 关键文字对比度 ≥ 4.5 : 1(§2.3)。 - 冲突发生时单格晃动;本格要求不符时有角标。过关胶囊有勾和文字,已过关卡格有勾,锁定有锁图标。 - 所有可点元素 ≥ 44px;键盘焦点有 3px 紫描边。 - 剩余格胶囊 `aria-live="polite"`;装饰性 SVG `aria-hidden`。 - 遵守 `prefers-reduced-motion`(§8.4)。 ## 11. 与其他玩法的关系 - **玩法三「六边一笔」**:结构与本规范一致(同一套壳、同一套四档动效),但 `theme.ts` 目前是靛蓝 `#4F5BD5` + 黄黑墙。待办:把 `--primary` 统一到 `#6558F5`(需先确认与墙黄 `#FFC826` 的对比),其余令牌直接复用本文。 - **壳(`shared/`)**:首页选玩法、设置、通用按钮皮肤按本文 §4 / §6 的按钮、chip、toast 规格实现。 ## 12. 变更记录 | 日期 | 变更 | |---|---| | 2026-09-16 | v1.5:去掉步号错位的 ×,错误格单独变红并晃动 280ms,进出连接线保持紫色;撤销 / 重开立即停止晃动。独立试玩版全部关卡直接可选。 | | 2026-09-16 | v1.4:第 n 步走到预定数字 n 以外的位置立即标红,角标显示「×」;本格要求不符仍显示原要求。补数字的约束同步生效。 | | 2026-09-16 | v1.3:触屏命中死区缩至 8%,任意历史格可直接回退;增加补数字提示,保留指路;底栏改为三个 15px 按钮,加常驻手势说明,toast 上移并支持换行。颜色、盘面字阶与动效令牌保持 v1.2。 | | 2026-09-16 | v1.2:未走线索 / 奇偶格描边改为墨色 `#23243A`(与线索数字同色),线宽 0.05 u。试玩反馈:主色描边跳脱、不简洁。 | | 2026-09-16 | v1.1:未走线索 / 奇偶格描边由灰 `#B4B8CC` 改为主色 `#6558F5`,线宽 0.05 u → 0.06 u(试玩反馈:灰描边不显眼)。已被 v1.2 替代。 | | 2026-09-15 | v1.0:建立令牌体系(色彩 / 字阶 / 间距 / 圆角 / 动效四档),CSS 与 `theme.ts` 由测试守门;字体栈加 `ui-rounded`;线索描边加深到 `#B4B8CC`;顶栏加副标题「包名 · 第 n 关」、本包进度条、剩余格胶囊(bump / 完成态);选关页加总进度条、已过关勾、当前关呼吸、列表渐隐;盘面加错落进场与过关后淡出;桥生长改为只长厚度;支持减弱动态。 | 待办:高对比模式(冲突改红底 + 斜纹)、暗色主题、玩法三令牌统一、Cocos 侧 Label 池化后复核字阶。