NumberSwipe_New/docs/design.md

UI 设计规范 · design.md

版本 1.5 · 2026-09-16 · 参考实现：玩法一「数字一笔」（modes/01-number-stroke）。设计师看图请打开同目录的 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 的对比），其余令牌直接复用本文。
• 玩法二「连连气球」：独立的天蓝 / 气球体系（#83B4EB 系），不套用本文色板；动效时长与缓动可以对齐四档。
• 壳（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 池化后复核字阶。