设计系统

本站动效的真实现状：零动效 token，时长散落在三个不同的声明面上，共 33 个声明点。 --text-scale 已经把字号收成单一真值了，动效这块还没有对应的东西。

三个面必须一起数，只 grep ms 会漏掉一半：

声明面	写法	处数
CSS / 内联字面量	200ms 带后缀	19 处（分布在 13 行）
JS 数值常量	const ENTER_MS = 400 无后缀	2 处（400 入场 / 320 退场）
Tailwind 工具类	duration-200 ease-out 无后缀	12 处（200×7、300×3、150×2；ease-out×4）

去重后，转场类实际只用了 8 个不同时长：120 / 150 / 200 / 250 / 260 / 300 / 320 / 400。 曲线则是 3 条自定义 cubic-bezier（11 处）+ 1 条内置 ease-out（4 处）。

写这份标准前必须先解决一件事：那 13 个数值里有 4 个压根不是动效时长。 不加分类就去"收敛到 4 档"，会把积分步长和防抖延迟也收敛掉。

0. 先分类，再谈数值

类别	定义	本站实例	受 300ms 约束？
转场 transition	用户动作引起的状态变化，可打断	8 个值：120 / 150 / 200 / 250 / 260 / 300 / 320 / 400ms	是
循环 loop	无人值守的持续环境动	islandEq 900ms ease-in-out infinite（global.css:549 区段）	否，另立 --loop-*
停留 dwell	计时器，不是动画	toast 自动消失 3500ms（notes.md:22）	否，另立 --dwell-*
序列 sequence	一次性展示型编排	dockBounce 780ms、text-decode 默认 900ms	否，属"罕见/首次"档，允许更长
非动效数值	被写成 ms 但不是时长	spring 积分步长钳 dt ≤ 32ms；解码速率 15~20ms/字符；折射滤镜防抖 120ms	必须排除在时长体系外

这一分类是本标准的第一条硬约束：任何新的 ms 值落地前，先声明它属于哪一类。 类别名进变量命名（--dur-press / --loop-eq / --dwell-toast），不允许再出现裸值。

---

1. 该不该动

标准（animate 频率表 + HIG Motion 的节制原则）：每天 100+ 次的键盘动作永远不动； 几十次的高频面（hover、列表导航）只做几乎察觉不到的微动；偶发（模态、抽屉、通知）用标准动效； 罕见/首次才允许花哨。合法目的只有五种：反馈、空间一致性、状态指示、防止突兀跳变、解释。

实测：⚠️ 两处与频率表冲突。

• 工作台切组件的内容切换用 .anim-fade-up（fadeUp 200ms）——这是每天几十次的高频操作，属"微动或不动"档，勉强合规
• 侧栏行 hover（.glass-hover:hover 改 4 个属性 200ms）同样在高频面上

动作：保留但降档——hover 的 transform 分量去掉，只留颜色与阴影变化。 检查项：新增动效时必须能一句话说出它属于五种目的里的哪一种；说不出就不加。

2. 时长档位

标准（转场类，Emil 四档 + M3 阶梯交叉验证）：

语义 token	值	覆盖	依据
--dur-press	120ms	按压反馈	Emil 100–160ms；我们已是 120ms ✓
--dur-fast	200ms	hover、颜色、小浮层、内容切换	Emil 125–200ms；M3 short4 = 200ms
--dur-base	250ms	下拉、分段切换、开关平移	Emil 150–250ms；M3 medium1 = 250ms
--dur-exit	180ms	退场：浮层卸载计时、路由旧页让位	退场取入场的 ~0.6×（300→180）：离开不该让人等；M3 的退场同样短于入场
--dur-slow	300ms	模态、抽屉入场	Emil 上限 300ms；M3 medium2 = 300ms
--dur-enter	400ms	仅页面级入场与退场编排	M3 medium4 = 400ms；⚠️ 超出 Emil 的 300ms 上限，须逐例说明

M3 还有 450–1000ms 的 Long/ExtraLong 六档，本站不采纳：那六档服务的是一级导航与全屏形变，我们没有这类面。

实测：8 个转场值里有 6 个能干净落进五档，两处需要判断，一个暴露了档位设计的真问题：

值	处数	归属	判定
200ms	CSS 11 + Tailwind 7 = 18	--dur-fast	主力档，无异议
300ms	CSS 2 + Tailwind 3 = 5	--dur-slow	无异议
250ms	1（Segmented.tsx:82 内联）	--dur-base	无异议
120ms	1（.press-feedback）	--dur-press	落在 Emil 100–160 带内 ✓
260ms	1（segmentedStretch）	并进 --dur-base	距 250 仅 10ms，属随手取值
320ms	1（EXIT_MS）	并进 --dur-slow	距 300 仅 20ms，同上
150ms	2（Dock.tsx:143、ComponentList.tsx:136）	卡在 press(120) 与 fast(200) 之间	需要决定：加第 6 档，或并进 --dur-fast 接受 +50ms。建议后者——tooltip / chip 淡入 200ms 仍在 Emil 合法带内，而多一档会让"该用哪档"重新变成判断题
400ms	CSS 1（stagger-in）+ ENTER_MS	--dur-enter	超出 300ms 上限，须逐例说明（页面级入场 / 通知堆叠时序）

动作：立五个 --dur-* 替换 31 个转场声明点；两处 JS 常量改成读取 CSS token 或直接命名为 --dur-slow 的引用； --dur-enter 的每次使用必须在 notes 里写明为什么不能是 300ms。

检查项（必须三个面一起扫，只 grep ms 会漏掉 12 处）：

# 三个声明面的残留裸值
grep -rn "[0-9]\+ms" --include="*.css" --include="*.tsx" src/ | grep -v "var(--dur\|--loop\|--dwell\|--seq"
grep -rn "duration-\[[0-9]\|duration-1\|duration-2\|duration-3" --include="*.tsx" src/
grep -rn "_MS = [0-9]" --include="*.tsx" src/

机器口径：npm run check:motion（scripts/check-motion.mjs）把上面三条变成可执行检查，按行扫、不跨行匹配， 覆盖面比上面三条 grep 更宽——.astro 里的 duration-*（DemoChrome / page-home / pages ×2 共 4 处）与 WINDOW_MS = 3000（弹簧测量视窗，按本文口径不进时长体系）都被计入。 本文的 33 个声明点是 tsx/css 口径，脚本口径是 38（CSS/内联 19 + Tailwind duration 16 + JS 常量 3）， 另有 4 处内置 ease-* 工具类单列。以脚本输出为准，本文数字在脚本落地后按基线更新。

3. 曲线族

标准：内置 ease-out 太弱，故意的动效用强曲线；ease-in 禁止出现在 UI 上。 两条流派本站都出现过——Emil 系 cubic-bezier(0.23,1,0.32,1)，Material 系 standard = (0.2,0,0,1)。

实测——我们只有三条，且其中一条正是 Material 的 standard：

曲线	处数	族属（已核实出处）	语义命名
cubic-bezier(0.16, 1, 0.3, 1)	5	强减速族。与 Emil 的 --ease-out 同族且更极端，也与 M3 emphasized-decelerate (.05,.7,.1,1) 同族	--ease-out
cubic-bezier(0.2, 0, 0, 1)	4	M3 motionEasingStandardInterpolator 逐字相同	--ease-standard
cubic-bezier(0.3, 0, 0.4, 1)	2	轻缓收尾，用在 dockBounce 与 segmented stretch 两处物理感场景	--ease-settle

还有第四条曲线我们一直在用而不自知：Tailwind ease-out 4 处，它是内置的 cubic-bezier(0, 0, 0.2, 1)。 其中一处是 Switch.tsx 的旋钮平移与轨道配色——按 Emil 的规则，"故意的动效"不该停在内置曲线上。

所以问题从来不是"要不要换成标准曲线"——(0.2,0,0,1) 已经是 Material 的 standard。真正的问题是三条： 这三条没有名字；(0.16,1,0.3,1) 这条比两家都更极端的选择是有意还是偶然； 以及内置与自定义混用——同一个"平移"动作，Segmented 用自定义、Switch 用内置。

动作：三条曲线起名为上表的 token；(0.16,1,0.3,1) 保留现值但标记为未经慢放复核的继承选择， 用 DevTools 把 fadeUp 拉到 5× 时长看一次收尾有没有急停；Switch.tsx 的两处 ease-out 换 --ease-standard， 与 Segmented 对齐。 检查项：出现 cubic-bezier( 字面量即报警（允许的字面量只在 token 定义处）； TSX 里出现 ease-out / ease-in-out 工具类即提示改用命名曲线。

4. 物理性

标准：不许 scale(0) 入场（真实世界没有从无到有），起点 scale(0.9–0.97) + opacity: 0； 锚定在触发元素上的浮层，transform-origin 要跟触发点，模态除外（它居中呈现）。

实测：scale(0) 与 scale(0.x) 小值入场 0 命中 ✓；transform-origin 相关：0 处（我们还没有锚定型浮层， modal 与 toast 都是居中/贴边，暂不适用）。

动作：无需改动，但这条要在 P3 补 dropdown / popover 组件时生效——现在写下来正是为了那时不忘记。 检查项：grep -rn "scale(0)\b" src/ 必须为空。

5. 可打断与退场

标准：可能被连续触发的元素（通知、开关、快速切换）用 transition 而非 keyframes—— transition 从当前值重新定向，keyframes 每次都从零重启。弹簧在被打断时保留速度，关键帧不保留。 退场要沿入场的路径原路返回。

实测：⚠️ 一处结构性冲突。

• .stagger-in 与 .anim-fade-up 是 keyframes（fadeUp ... both）。anim-fade-up 用在工作台切组件上—— 用户连点侧栏时会反复从零重启，且 both 会把动画状态钉住。这正是标准点名要避免的形态
• toast 走的是逐层 transition（400ms 时序、320ms 退场）✓ 符合；退场沿 translateY(120%) 原路返回 ✓

动作：.anim-fade-up 改为 transition + @starting-style 的入场写法，或至少去掉 both 的钉住。 检查项：role=status / 通知类组件内不得出现 animation: 关键字，一律 transition:。

6. 可动属性白名单

标准：只动 transform 与 opacity（跳过 layout 与 paint，走合成器）；clip-path 是受许可的第四项。 width/height/margin/padding/top/left 三阶段全触发。will-change 不许常挂。

实测：transition: all 0 命中 ✓；will-change 0 命中（既没乱用也没用，中性）。 两处违规（脚本 npm run check:motion 查出来的，本文初稿只抓到第一处）：

• global.css 的 .col-handle::before 写 transition: opacity 200ms ease, height 200ms ease，hover 时 height: 24px → 36px。 缓解因素是它绝对定位且是个 2px 宽伪元素，布局代价被限制住了——但等价写法是免费的。
• Dock.tsx:122 的 transition-[width,height] duration-300 ease-out：放大动画直接动宽高， 触发布局；且它同时用了内置 ease-out（见 §3）。

动作：前者改 transform: scaleY(1.5) + transform-origin: center，视觉结果相同、走合成器； 后者改成 transform: scale() 驱动（Dock 本来就有缩放态），或至少把宽高动画换成不触发布局的等价写法。 检查项：transition / animation 声明里出现 height|width|margin|padding|top|left 即报警， clip-path 与 opacity transform 豁免。

7. 降级与门控

标准：prefers-reduced-motion 和动效同批交付，不是后续补（animate 硬规则 4）。 降级是"更少更温和"而非清零：保留帮助理解的 opacity/颜色过渡，去掉位移与形变。 基于 hover 的位移动效须用 @media (hover: hover) and (pointer: fine) 门控——触屏会在点击后留下假悬停态。 条款依据：SC 2.2.2（自动运动 >5s 须可暂停）、SC 2.3.3（交互触发的动画须可禁用）。

实测：这是本站最大的一处成片缺口。

• prefers-reduced-motion 只出现在 2 个组件（spring-ios、text-decode），island-ios 作为动效组件没有降级
• global.css 里零条 reduced-motion 规则——而那里有 5 组 keyframes（fadeUp、dockBounce、islandEq、segmentedStretch、stagger-in），其中 islandEq 是 infinite 循环，正撞 SC 2.2.2
• hover 位移门控 0 处：.glass-hover:hover 带 transform、dock 放大、spotlight 光斑全部门控缺失

动作：global.css 加一段全局 reduce 闸门（关掉 infinite 循环与 transform 分量，保留 opacity）； island-ios 补 JS 侧 matchMedia 检测；hover 位移统一加 pointer 门控。 检查项：grep -c "prefers-reduced-motion" src/styles/global.css ≥ 1； 每个含 animation: 的文件都能对应到一处 reduce 分支；@media (hover: hover) 命中数 ≥ 位移型 hover 的数量。

8. 一致性与 stagger

标准：成组入场要 stagger，间隔 30–80ms，更长就显拖沓；stagger 是装饰，播放期间不得阻塞交互； 动效气质要贴组件性格（sonner 用 ease 而非 ease-out 显得慢而雅，是有意的不协调消除）。

实测：stagger-in 的用法注释写的是 animationDelay: i * 80ms——正好卡在上限， 但它是硬编码在使用侧而非 token 化，第二处 stagger 很可能飘到 100ms。 islandEq 循环的 900ms 与 dockBounce 的 780ms 分属两类，不需要一致，但需要各自有名。

动作：立 --stagger: 60ms（取区间中值而非上限）；使用侧改成 calc(var(--stagger) * var(--i))。 检查项：出现 animationDelay 字面量乘数即提示改用 token。

9. notes 里的数字要有代码保证

标准：53ac764 已经把"灵感来源"改成 notes 单一真值。那么 notes 里的关键参数同样成真值—— 后面的人会拿它当依据，而它现在没有任何东西保证与代码一致。

实测：抓到一处三重的硬矛盾。 switch/glass-apple/notes.md:8 写 "250ms cubic-bezier(0.2, 0, 0, 1) 平移，和分段控件同一条曲线"， 而实现是 Switch.tsx:46 与 Switch.tsx:59 的 duration-200 ease-out。 三处不实：值（250 → 200）、曲线（自定义 → 内置）、"和分段控件同一条曲线"为假 （Segmented 用 (0.2,0,0,1)，Switch 用内置 ease-out，两者不同）。 另有一处轻度漂移：dock notes 的"~750ms"对应实现 780ms。

动作：notes 的关键参数改成引用 token 名（--dur-base、--ease-standard），只在暂无 token 时写裸值； P2 落 token 后回头修这两处。分段控件与开关是同族控件，本就该共用一档时长一条曲线——顺便把真值对齐。

检查项：从 notes 抽取 ms 数字与 cubic-bezier 字面量，与同目录代码的声明集合比对，报不匹配项。 这条做不全自动化（散文表述难以解析），但**"notes 声明的值在代码里找不到同值来源"这一条可以精确报警**—— 上面两处矛盾都属于此类。

10. 路由切换（2026-10-31 落地，同日修订）

标准：顶栏是常驻 chrome，跨路由不重挂；内容交换不加入场动画。 导航是高频动作，换页必须跟手——实测内容交换 50–90ms（/design 约 260ms）， 再叠 300ms 入场，点击到看清内容要 350–560ms，判为慢。

编排（global.css 的 ::view-transition-*）：

• root 与 top-nav 的 group / old / new 六个伪元素统一 animation: none： Astro 仍走 startViewTransition（换页免整页刷新），但不再付伪元素动画的时长； UA 默认的根交叉淡入也显式关掉，否则它仍会跑 250ms。
• 顶栏 transition:persist 加 transition:name="top-nav"。只写 persist 不够： 没有名字它就留在根快照里，跟着内容一起对穿——中间帧实测图标与文字重影。 有了名字它单独成组，新旧几何相同 → 视觉上静止。
• 导航链接 data-astro-prefetch="hover"：悬停即取目标 HTML，点击只剩余交换。
• reduced-motion：Astro 自带闸门保留；本页已无动画，两者结论一致。

为什么不挂 100ms 的轻淡入：淡入从第一帧就压住内容，等于给每次点击加固定税。 换页本身已经够短，再藏起来那一下只会让"已经好了"看起来像"还在加载"。

实测（headless Chrome + CDP，1920×1080，生产构建，点击顶栏到 astro:after-swap）：

目标	点击 → 内容可见	备注
首页 / 页面	50–66ms	—
工作台	78–87ms	首访带 268KB JS
设计	约 260ms	195KB HTML + 3313 节点，快照开销

取 HTML 在 before-swap 前占 30–40ms，悬停预取可吸收。旧版 300ms 入场把总时延推到 350–560ms。

检查项：grep -n "transition:name" src/layouts/BaseLayout.astro 必须命中顶栏； global.css 的路由伪元素块只能出现 animation: none，不得有 keyframes 引用。

---

Never Ship（本站适用版）

逐条对当前代码跑过，右侧是实测状态：

禁止	本站实测（基线 982e282）
transition: all	✓ 0 命中
scale(0) 入场	✓ 0 命中
UI 上用 ease-in	✓ 0 命中
故意的动效用内置 ease-out	✓ 0 处——曲线进 --ease-* token，工具类也取本站曲线
键盘动作 / 100+ 次每天的动作加动效	⚠️ 高频面两处（见 §1），未动
无因由的 >300ms 转场	⚠️ --dur-enter 400ms 使用处须在 notes 写明理由
锚定浮层用 transform-origin: center	— 暂无此类组件
高频元素用 keyframes	✓ .anim-fade-up 改 transition + @starting-style（见 §5）
动 width/height/margin/padding/top/left	✓ 0 处——.col-handle::before 改 transform；Dock 的放大是逐帧改尺寸（macOS 式推开邻居），不是 CSS 过渡
未门控的 hover 位移	✓ 已加 @media (hover: hover) and (pointer: fine) 闸门
缺 prefers-reduced-motion	✓ global.css 有全局闸门，island-ios 与 Dock 在 JS 侧也降级
全体同时入场	✓ 间隔走 --stagger
notes 写死数值、与代码脱节	✗ 两处待修（见 §9，其中 Switch 是三重的）

六条 ✗ 的优先级：§7 的降级缺口是唯一会直接造成用户不适的——前庭障碍用户面对 infinite 循环无从关闭， 建议 P2 第一批改动落在那儿。其次是 §9 的 notes 失真，它会让后面的人按错值建判据。 §3 / §5 / §6 属手感与性能，可与 token 落地同批处理。

这份标准落成 token 的样子

不在本次改动范围（属 P2），但先给出形状，避免届时另起一套：

:root {
  /* --- 动效 token：类别即命名空间 --- */
  --dur-press:   120ms;   /* 按压反馈，Emil 100–160 */
  --dur-fast:    200ms;   /* hover / 颜色 / 小浮层 / 内容切换 */
  --dur-base:    250ms;   /* 下拉 / 分段切换 / 开关平移 */
  --dur-exit:    180ms;   /* 退场：比入场短，离开不该让人等 */
  --dur-slow:    300ms;   /* 模态与抽屉入场 */
  --dur-enter:   400ms;   /* 仅页面级入场与退场，使用须注明理由 */
  --loop-eq:     900ms;   /* 灵动岛均衡器循环 */
  --dwell-toast: 3500ms;  /* 通知停留计时器，非动画 */
  --seq-dock:    780ms;   /* Dock 启动弹跳 */
  --seq-decode:  900ms;   /* 标题解码序列 */
  --stagger:      60ms;   /* 组入场间隔，取区间中值 */
  --ease-out:      cubic-bezier(0.16, 1, 0.3, 1);    /* 待慢放复核 */
  --ease-standard: cubic-bezier(0.2, 0, 0, 1);       /* = M3 standard */
  --ease-settle:   cubic-bezier(0.3, 0, 0.4, 1);     /* 物理感收尾 */
}

另需注意：spring-ios 的 dt ≤ 32ms 与 dock 折射滤镜的 120ms 防抖不进这套 token—— 它们是数值积分步长与事件节流，套上 --dur- 前缀反而误导读者。

本文的自查（也要守"数值诚实"）

这份草稿的第一版数字是错的，错法值得记下来，因为它就是本站"裸值散落"造成的同类事故：

我最初 grep -ro "[0-9]\+ms" src/ 得到"13 种时长 / 35 处"，据此写下"把 27 处裸值替换掉"。三个错叠加：

1. 混算了散文与代码——35 处里有 22 处在 notes.md 的文字描述中，不是声明点
2. 漏了两个声明面——Tailwind duration-200 和 JS const ENTER_MS = 400 都不含 ms 后缀，grep 抓不到，漏掉 14 处
3. 基线已漂移——53ac764 把 global.css 从 598 行扩到 683 行并新增 --text-scale，我最初的测量发生在它之前

修正后的口径是三个声明面共 33 个声明点、8 个转场值（改造前）。§2 的检查项命令已改成三面分别扫描， 正是为了防止同一个盲区再犯——那 33 个声明点现在已全部 token 化，见下。

落地状态

本文的标准已落地（commit 982e282，2026-10-30）：

• 五个 --dur-*、三个 --ease-*、--loop-eq / --seq-dock / --seq-decode / --dwell-toast / --stagger 全部进 token
• 三个声明面的裸值清零：CSS/内联 0 处、Tailwind duration-* / ease-* 0 处、JS 常量只剩 WINDOW_MS（弹簧测量视窗，按口径不进时长体系）
• 降级闸门：global.css 的 prefers-reduced-motion 段 + island-ios / Dock 的 JS 侧降级 + hover 门控
• 检查脚本：npm run check:motion（scripts/check-motion.mjs），已转 --strict，不达标即拦住提交

本文的"实测"小节记录的是落地前的审计结果，作为改造依据留着； 判断现状看 npm run check:motion 的输出，不要拿这里的数字当现状。

---

搬到新项目要花多少代价

要搬的	在哪	量
动效 token 13 个 + 3 条曲线	global.css「动效 token」+ @theme 曲线	约 22 行
降级闸门 + hover 门控	global.css 的 prefers-reduced-motion 与 @media (hover: hover)	约 30 行
JS 侧读 token / 浮层进出	src/lib/motion.ts + src/lib/overlay.ts	58 行
裸值扫描	scripts/check-motion.mjs	107 行
路由切换（仅 Astro）	global.css 的 ::view-transition-* + 顶栏 persist	13 行

• 零依赖。
• 必须整块搬：token + 闸门 + 扫描脚本三件一起。只搬 token 没有闸门 = 无障碍欠账；只搬闸门没有 token = 每处还要自己编时长。
• 可以剥掉：§10 路由转场（依赖 Astro ClientRouter，React 项目换成自己 router 的钩子）；overlay.ts 只在 React 项目里需要。
• 工时：约 20 分钟（React / 原生）；Astro 转场另加 10 分钟。
• 搬完怎么验：node scripts/check-motion.mjs --strict 全达标；系统开"减少动效"后位移消失、透明度过渡保留；transition: all 与 will-change 各 0 命中。

1. 材质分级

标准：本站只有三种材质，各有明确职责，不许互相顶替。

级别	材质	用在哪	判据
悬浮层	玻璃（--glass-* + backdrop-blur）	顶栏、命令面板、齿轮菜单、弹层、坞站、tooltip	浮在别的内容之上、底下有东西要看
内容层	不透明白底（--color-surface + --shadow-sm/md）	卡片、表格、面板、表单	内容本身，要读要读要选
风格轴	新拟态（--neuro-*）	尚未实现（neumorphic 是 P3 的第三条轴）	独立配方，不是"玻璃的另一种写法"

为什么玻璃不能下沉到内容层：玻璃是增透的——它靠背后有东西才成立（--glass-bg 是 28% 的 surface 叠在模糊上）。 铺满一屏的玻璃卡片等于没有底，用户读不到"这块内容属于哪"，而且背景光斑会跟着文字一起抖。 这条 CHANGELOG 里改过三次才收敛，至今没有正式条文——就是本文。

实测（基线 982e282，2026-10-31 重测）：玻璃表面 token（--glass-bg / blur / highlight / inset）出现在 19 个文件里（18 个组件 + global.css 的定义处），全部是悬浮层或展示型组件： 顶栏、齿轮菜单、命令面板、字体面板、坞站、模态、输入框、按钮、下拉、勾选、导航、骨架、标签页、玻璃卡片、演示工具条、复用卡与工作台两侧面板。页面层 0 处——原先 showcase 首页的玻璃 CTA / 提示条与页面预览缩略图里的玻璃底已改回 --color-surface，缩略图现在与真实页面同材质。 --glass-border 另有 44 个文件用作通用发丝线——它只是描边，不构成玻璃表面，不算违反。 站内结构（页面骨架、列表页、dashboard、设置页）一律是 bg-[var(--color-surface)] 的白底面板 ✓ 符合。

动作：

• 新增浮层一律玻璃；新增内容容器一律白底。要混用时，先问"这块底下有没有东西"。
• card/glass-apple 是展示品（复现对象），它可以违反这条——但它不能成为站内页面的做法。

检查项：

# 内容层不该出现玻璃表面：页面与骨架文件里不应有 bg / blur / highlight / inset
grep -rnE "var\(--glass-(bg|blur|highlight|inset)\)" src/pages src/layouts src/components/PageShell.astro | wc -l   # 应为 0

# 玻璃表面只在组件层出现（浮层与展示品）
grep -rlE "var\(--glass-(bg|blur|highlight|inset)\)" src/components | wc -l

2. 阴影三档

标准：阴影只表达高度，不表达颜色。三档对应三种高度，用错就是噪声。

token	用途	判据
--shadow-sm	贴着表面的东西：卡片、按钮、输入框	元素不离开自己的位置
--shadow-md	浮起一层的面板：工作台中栏、模态、坞站	元素有明确的前后关系
--shadow-lg	压住全屏的东西：遮罩下的弹层、命令面板	元素是当前焦点

标准：

• 阴影色是冷紫灰（--base-shadow-tint: 56 50 120），不是纯黑——纯黑会让画面发脏。
• 一层里只用一个阴影档；需要两个就是两个元素，不要在一个元素上叠 shadow-sm + shadow-md。
• 玻璃面本身已有 --glass-inset（边缘光学），再叠大阴影会显脏——玻璃浮层用 --shadow-md 即可。

实测：--shadow-sm 14 处、--shadow-md 9 处、--shadow-lg 6 处，分布与上表一致 ✓； --glass-inset 与大阴影同层出现的地方只有玻璃浮层本身 ✓。

动作：新面板先问"它浮不浮"。贴着 = sm，浮一层 = md，压屏 = lg。

检查项：

# 同一个元素上不该同时出现两档阴影
grep -rn "shadow-\[var(--shadow-" src | grep -c "shadow-\[var(--shadow-md)\].*shadow-\[var(--shadow-sm)\]"

---

搬到新项目要花多少代价

要搬的	在哪	量
材质层约 22 个变量（玻璃 / 新拟态 / 阴影）	global.css「玻璃 / 新拟态」「阴影 token」	22 行
三条风格配方	global.css「风格轴配方」	40 行
玻璃实际生效的全局规则	global.css 的 [class*='backdrop-blur']	4 行

• 零依赖：backdrop-filter 是浏览器原生，不引任何模糊库。
• 必须整块搬：搬 token 时把分级判据一起搬——玻璃只给悬浮层、内容面板一律不透明白底。只搬 token 不搬这条，玻璃会从浮层蔓延到卡片，分级就没了。
• 可以剥掉：新拟态配方（除非真要那条轴）；--glass-inset 的边缘光学可先不搬（没有它玻璃也能看，只是薄一点）。
• 工时：约 15 分钟。
• 搬完怎么验：把 --glass-blur 改成 0 再改回 16px，看所有浮层是否同步变化（说明没有硬编码模糊）；悬浮层底下必须有内容，空底玻璃看不出厚度。

1. 阶梯

标准：本站只有一条字号阶梯（--text-*），外加一条全局缩放倍率 --text-scale（小 0.92 / 标准 1 / 大 1.12，由「字体与字号」面板控制）。

档	值	角色	实测用量
--text-2xs	10px	极小 label、图标角标	27
--text-xs	12px	副标、tag、时间戳	56
--text-sm	13px	元数据、表格、说明文字	57
--text-base	14px	正文	10
--text-md	16px	强调正文	0
--text-lg	20px	小标题	9
--text-xl	24px	大标题	7
--text-2xl	28px	特大标题	3
--text-3xl…7xl	30–72px	页面级标题（Tailwind 原生档，跟倍率走）	9

标准：

• 只用 Tailwind 工具类（text-sm、text-2xs），不写 text-[length:var(--text-sm)]。 两种写法指向同一个 token，但混用会让"这一档到底用在哪"查不出来——本站两种形式都出现过（任意值形式 24 处）。
• 档位按角色选，不按"我觉得小一点更好"：正文 13–14、说明 12、元数据 10–12。 相邻两档不要跳着选（比如 12 直接跳 16），阶梯的意义就是连续。
• 标题与正文的对比：至少两档。全站只有页头允许用大标题（text-2xl 起），组件内部标题不超过 text-lg。

实测（基线 982e282，2026-10-31 重测）：命名档位工具类 361 处，text-[length:...] 任意值 97 处——两套写法并存，这是本文要清掉的第一件事。 --text-md（16px 强调正文）定义了就没人用：要么补上用法，要么删掉这一档（阶梯里的空档也是噪声）。

动作：

1. 把 97 处任意值形式换成工具类形式（text-[length:var(--text-2xs)] → text-2xs）。
2. --text-md 二选一：删掉，或在"强调正文"处统一使用。

检查项：

# 不该再有任意值形式的字号
grep -rn "text-\[length:var(--text-" src | wc -l

2. 行长、行距与中英混排

标准（library.md 第四节，clreq §7.1 / Butterick）：

• 中文正文行距 = 字号的 1.5–2.0 倍（--text-base 14px → 行高 21–28px）。
• 正文行长：中文 17–40 字/行（硬上限 48），西文 45–90 字符。
• 中西文混排间距可固定 ¼ 字宽；line-break: strict 用于中文正文，短标签用 loose。
• 中文标点避头尾（GB/T 15834）——正文里不能出现行首句读符号。

实测（2026-10-31 更新）：行高已收成一条阶梯，覆写 Tailwind 的 --leading-*， 所以 20 处 leading-relaxed 都跟着一个数走：

档	值	用在哪
--leading-tight	1.15	页头 / 分区标题（leading-tight）
--leading-snug	1.375	单行说明、副标（leading-snug）
--leading-normal	1.5	默认（Tailwind 原值）
--leading-relaxed	1.65	正文（leading-relaxed，原 1.625；落在 clreq 1.5–2.0）
--leading-code	1.55	代码块（等宽字不需要正文那份呼吸）

例外：复现页（page-home / dashboard 等"海报"）保留 leading-[1.1] / leading-none 这类自己的行高—— 它们不是站内结构，按 layout.md 的 counter_example 同一口径处理；首页 Hero 是单行展示标题，直接用 leading-none。

行长也已落地：--measure: 40em（≈40 汉字 / 80 西文字符，同时落在 clreq 17–40 与 Butterick 45–90 内）， .prose-notes 的段落 / 列表 / 引文统一封顶。宽屏下有两种合法去处： 分栏（.prose-columns，≥1800px 起 columns: 34em——栏宽本身就是行长，栏内段落不再二次收窄）， 以及表格与代码块——它们不跟行长走，表格按内容宽度左对齐（拉满会把长文本列撑成 150 字一行， 见 layout.md §2），代码块用满容器宽。

动作：新增标题用 leading-tight、正文用 leading-relaxed，不写 leading-[1.x] 字面量； 新增正文容器一律走 .prose-notes，别再手写 max-w-[68ch] 一类的第二套行长。

检查项：

# 站内结构不该再有任意值行高（复现页除外）
grep -rn "leading-\[" src/pages src/components | grep -v "showcase/demo" | wc -l   # 应为 0
# 行长与行高各只有一处真值
grep -rn -- "--measure\|--leading-relaxed" src/styles/global.css

3. 字重

标准：只有四档字重，取自 OpenType wght 轴：--fw-normal 400 / --fw-medium 500 / --fw-semibold 600 / --fw-bold 700。 字重只用数字，不用 light / bold 关键字（CSS Fonts 4 + OpenType 注册轴）。 层级靠字号 + 颜色拉开，字重只在"强调"和"标题"两处用：--fw-semibold 给标题，--fw-medium 给选中态。

实测：--fw-bold 定义了没人用——同上，二选一（删掉，或在真正需要强调的地方用）。

---

搬到新项目要花多少代价

要搬的	在哪	量
字号阶梯 9 档 + --text-scale 两行	global.css「字号阶梯」	14 行
行高阶梯 4 档 + 代码块行高	global.css 的 @theme 与「行高」段	8 行
--measure 与正文规则	global.css 的 --measure + .prose-notes	4 行
正文字族 + 等宽字族	public/fonts/ + @font-face	6 个家族约 1.0MB；只带 2 个约 480KB
字体切换面板（可选）	src/components/workbench/FontSwitcher.tsx	264 行（含 EN / ZH / 字号 / 等宽四维）

• 零依赖：字体是静态文件；不想管文件就换 fontsource 的 npm 包。
• 必须整块搬：字号阶梯要整条搬（9 档齐全），东拼西凑会出现"14 和 15 都在用"；--measure 与正文规则一起搬，否则宽屏会把行拉到 90 字符以上。
• 可以剥掉：三家族等宽切换（省 3 个字体包与开关 UI）；中文字族只留一个。
• 工时：阶梯 + 两个字族约 15 分钟；连字体切换面板约 40 分钟。
• 搬完怎么验：grep -rn "text-\[length:var(--text-" src | wc -l 证明字号全走 token；量一段中文正文是否落在 40 字/行上下；站内结构里 leading-[ 任意值应为 0。

1. 状态色

标准：三个语义前景色 + 一套底色/描边，只表达事情的状态，不表达品牌。

token	值（浅色）	用在哪	实测对比度（白底 / 页底）
--color-success-fg	#1c815c	成功提示、涨跌正向	4.83 / 4.51
--color-warning-fg	#b65700	危险操作、待办、"计划中"	4.83 / 4.50
--color-info-fg	#2777ac	进行中、中性提示	4.86 / 4.53

标准：

• 前景色只当文字色或小圆点用，且必须过 SC 1.4.3 的 4.5:1（正文尺寸）。 底色与描边（--color-*-bg / --color-*-bd）从前景色 mix 出来，自动跟着前景色走。
• 大面积底色用 -bg（10% 混色），描边用 -bd（25% 混色）——不要自己再调 rgba。
• 状态不能只靠颜色表达：圆点旁边要有文字（"已复现 / 复现中 / 计划中"），色盲用户也要读得到。

实测：语义前景色在代码里用于 notes 链接、dashboard 涨跌、settings 删除按钮、列表页状态点 ✓。 对比度已按 SC 1.4.3 修正（修正前 warning-fg 在页底只有 2.97，连 3:1 都不够）。 --color-text-subtle 同步修正为 #717179（4.84 / 4.51）——它之前是 2.76，被当小字用着。

动作：新增状态一律从这三个 token 出，不要写新的色值。

检查项：

# 不该有裸写的状态色
grep -rnE "#(059669|d97706|0284c7|9b9ba3)" src | wc -l

2. 按压反馈

标准：所有可点元素都要有按压反馈，用缩放表达，不用颜色——颜色变化会和 hover 撞。

• 通用做法：给元素加 .press-feedback（transform: scale(0.97) + --dur-press 过渡）。
• 缩放量统一：全站一个值，不许这里 0.97 那里 0.95。
• 按压是瞬时的：--dur-press 120ms（Emil 100–160ms 带内）。长按不做长反馈。

实测（基线 982e282 之后）：原先有三套缩放值并存——.press-feedback 的 0.97、 玻璃按钮的 hover:scale-[1.02] active:scale-[0.98]、灵动岛按钮的 hover:scale-105 active:scale-95。 现已收敛成两处定义（在 global.css，不在组件里；Toast 入场另有 scale(0.92)，属动效入场，不在此列）：

class	行为	用在哪
.press-feedback	按压 → scale(0.97)	所有可点元素（chip、按钮、图标、开关、通知关闭）
.press-hover	悬停 → scale(1.02)，按压 → scale(0.97)	按钮型元素（CTA、玻璃按钮）

禁用态不缩放（.press-feedback:disabled:hover { transform: none }）——这条必须留在层外， 否则压不过 Tailwind 的 layered 工具类。

悬停位移要门控：触屏没有真悬停，group-hover:translate-x-* 会在点完后留下假悬停态。 位移型悬停一律用 .group-shift-right / .group-shift-down（包在 @media (hover: hover) and (pointer: fine) 里）。

检查项：

# 缩放值只应出现在 global.css 的两处定义里
grep -rn "scale-\[0\.9\|scale-\[1\.0" src | grep -v global.css | wc -l
# 位移型 hover 不该再用 Tailwind 的 group-hover:translate
grep -rn "group-hover:translate" src | wc -l

3. 焦点与目标尺寸

标准（这是可用性底线，不是修饰）：

• 焦点环必须可见：SC 2.4.13 要求等效周长 ≥2px，本站 *:focus-visible 用 2px 实线 + 2px 偏移。
• 指针目标 ≥ 24×24 CSS px（SC 2.5.8）。轨道、图标、关闭按钮都要够。 空间不够时可以靠间距补偿，但不要靠"看起来够大"。
• 键盘可达：Tab 能走到，Enter/Space 能触发；浮层打开时焦点进去、关闭后归还。
• 浮层不能压住下层的焦点（SC 2.4.11）。
• 输入框只能有一套焦点指示：用 focus:outline-none + 自己的环（拟态用 2px shadow 环， 玻璃 / 极简用描边提亮）替代全局环。全局规则放在 @layer base， 否则层外规则会压过工具类，出现「外环 + 内环」两层焦点。

实测（基线 982e282，修正后）：

• 焦点环 1.5px → 2px ✓（原值低于 SC 2.4.13）。
• Switch sm 轨道 20px → 24px ✓（md 26px 本来就合规）。
• Segmented 是完整的 APG radiogroup（方向键 / Home / End / roving tabindex）✓。
• Dropdown 是 APG Select-Only Combobox：aria-activedescendant 指向高亮项，焦点留在触发器； ↑↓ / Home / End 移动、Enter / 空格选中、Esc / Tab 收起、点外关闭，禁用项跳过 ✓。
• Combobox 是 APG list-filtering combobox：焦点同样留在输入框，↑↓ 在关闭时先打开、 Enter 选中并阻止表单提交、Esc 只收弹层、禁用项跳过，结果数用 aria-live 播报 ✓。 与 Dropdown 的分工是能不能自由输入：只能选一个已有值用 Dropdown，输入即过滤用 Combobox。
• Tabs 是 APG Tabs（automatic activation）：roving tabindex、方向键同时移动焦点与选中、 Home / End 到两端、禁用页签跳过，面板可聚焦 ✓。
• Choice 是 APG Checkbox + Radio Group：原生 input 保留空格切换与方向键单选， input sr-only 后焦点环用 peer-focus-visible 画在可视框上，组级与单项禁用都可见 ✓。
• Switch 是 role="switch" + aria-checked，底色 <button> 自带 Space/Enter ✓。
• Modal 补齐了焦点陷阱、关闭后焦点归还、aria-labelledby ✓。
• 缺口：Dock 的图标按钮尺寸随放大变化，静止时 52px ✓；但 topnav 的字号/图标类 chip 与 CommandPalette 的行高仍需逐个核对是否达到 24px。

动作：新增可点元素先量尺寸（DevTools 或 getBoundingClientRect），不够就加 padding。

检查项：

# 焦点环不能退回 1.5px
grep -rn "outline: 1.5px" src | wc -l

4. 拖拽与指针手势

标准：

• 双通道：指针能做的，键盘也必须能做——拾起 / 移动 / 放下 / 取消四步缺一不可。
• 指针拖拽用 Pointer Events + setPointerCapture，不用 HTML5 drag-and-drop（触屏与样式都不可控）。
• 只在把手上开始拖拽，行本身保留滚动；把手设 touch-action: none。
• 拖动中只表达"拿起了"与"会落到哪"，松手才提交新顺序；落点量布局位（offsetTop），不量被 translate 的 rect。
• 读屏要播报：拾起 / 移到第 n 项 / 放下 / 取消，写进 aria-live="polite"。
• 降级：prefers-reduced-motion 下可去掉过渡，但顺序改变与焦点位置不能丢。

两种手势，两种判据

同一个"拖"，动机不同，规则也不同。混着用就会把一种的正确做法搬到另一种上。

	跟手型	拉动型
例子	拖拽排序、滑动删除、滑块、抽屉	拽住往外拉、拉够远就触发（如"拉飞便签"）
位移关系	按住期间 1:1，不许打折	阻尼就是交互本身
提交时机	松手判定（滑块例外：连续提交）	越过触发线即提交，之后不可撤销
判错的样子	加了缓动或多乘一个系数 → 读成"卡顿 / 拖不动"	改成 1:1 → 失去"拉"的张力

跟手型手势的四段链

1:1 跟手  →  越界阻尼  →  阈值提交  →  吸附落位
 track        damp         commit       settle

• 跟手：按住期间位移必须与指针相等。任何缓动、任何系数都会读成延迟；拖拽期间不挂 transition，松手才挂。
• 越界：越过边界后仍跟手，但那部分只跟 30% 左右。硬停像 bug，无限位移像没有边界。
• 提交：速度与距离双条件，不看单一位移。「放在那里」和「甩过去」是两种意图；测速只取最后约 120ms 的位移，全程平均会被起手那一下拖偏。
• 吸附：落位用 token 时长；reduced-motion 下不画过程，直接到终态。

轴锁：横向 / 纵向意图不明时先看起手方向，纵向就让位给滚动（touch-action: pan-y），不要抢滚动手势。

本站实现：

• drag/sortable-list——跟手型，指针与键盘共用同一份 moveItem(items, from, boundary)；
• drag/swipe-to-dismiss——跟手型，四段齐全，速度线 0.5px/ms；键盘 Delete / Backspace 等价，结果进 aria-live；
• slider/*——跟手型但连续提交，不涉及阈值与吸附。

检查项：

# 拖拽组件必须捕获指针，并带播报
grep -rn "setPointerCapture" src/components | wc -l
grep -rn "aria-live" src/components/drag | wc -l

5. 指针与光标

标准：光标是操作提示，不是装饰。按三层处理，越往后越谨慎。

A 层 · 原生状态关键字（首选，零 JS）：状态用系统关键字表达，不用图片光标。

状态	关键字	用在哪
默认可交互	pointer	按钮、链接、可点卡片
文本编辑	text	输入框、可选文本
可拖拽 / 拖拽中	grab / grabbing	把手、可拖行
不可用	not-allowed	禁用控件
缩放 / 列宽 / 移动	zoom-in/zoom-out、col-resize、move	画布、表格、可拖动面板

• 光标图片（cursor: url(...)）只在必须时用：PNG 或带自然尺寸的静态 SVG， 建议 ≤32×32（Firefox / Chromium 默认上限 128×128，超限会被静默忽略）， 必须带末尾关键字兜底；热区 x y 相对图片左上角。
• 光标不参与状态色体系：状态不能只靠光标表达，颜色与文案仍是主信号。

C 层 · 自定义光标替身（仅 demo，不做站点级）：四条硬规则，缺一条就不做。

1. 不全局隐藏：禁止在 html / body 上写 cursor: none；原生光标始终保留。
2. 只精确指针：只在 (hover: hover) and (pointer: fine) 下启用，触屏与粗指针不加载。
3. 输入区让位：文本、输入框、可选中区域上不画替身，避免遮挡插入点与选区。
4. 动效降级：prefers-reduced-motion 下关闭跟随与拖尾，只留静态提示或直接不启用。

• 替身不能是唯一反馈：键盘、读屏、触屏用户必须仍能完成同一操作。
• mix-blend-mode 只做点缀，不保证任何背景下的对比度；它还会创建独立堆叠上下文。

B 层 · 元素响应指针（推荐）：光标不动，元素响应——磁吸、聚光、放大。

• 写 transform，不写 left/top 与宽高；指针移动期间不挂过渡，离开再补间回位。
• 同时门控 (hover: hover) and (pointer: fine) 与 prefers-reduced-motion；触屏不响应。
• 指针操作在 up-event 完成或可中止（SC 2.5.2）；指针目标 ≥24×24（SC 2.5.8）。

本站实现：cursor/magnetic（矩阵「其他」列）——元素朝指针偏移、离开回位，光标保持原生； cursor/contextual 作为 C 层的局部 demo——只在虚线框内跟随、按 data-cursor-state 换形、 输入区让位，原生光标不动；原生关键字已散落在各组件（pointer / grab / grabbing / not-allowed）。

检查项：

# 不做站点级光标隐藏；磁吸只给精确指针
grep -rn "cursor: none" src | wc -l            # 应为 0
grep -rn "pointer: fine" src | wc -l           # ≥1
grep -rn "prefersReducedMotion" src/components/cursor | wc -l  # ≥1

---

搬到新项目要花多少代价

要搬的	在哪	量
状态色（3 前景 + 3 对底/描边 + 分隔线）	global.css 语义层	14 行
全局焦点环	global.css 的 *:focus-visible	8 行
按压 / 悬停缩放（全站唯一定义）	.press-feedback / .press-hover + hover 门控	约 30 行
光标关键字对照与自定义光标四条硬规则	本文 §5	0 行代码，1 张表
对比度重算脚本（改色时才要）	scripts/pick-colors.mjs	138 行

• 零依赖。
• 必须整块搬：焦点环与 24×24 目标尺寸是可用性底线，不能只搬颜色；.press-feedback 全站只留一处定义，搬过去之后把目标项目里其它 scale(...) 全删掉。
• 可以剥掉：pick-colors.mjs（它依赖本站的 OKLCH 取色流程，只在你也要改色时才需要）。
• 工时：约 10 分钟（换色另算：用脚本把新色重算到 4.5:1 约 20 分钟）。
• 搬完怎么验：纯键盘 Tab 走一遍，焦点环可见且不被浮层遮住（SC 2.4.11）；按钮点击面积 ≥24×24（SC 2.5.8）；开"减少动效"后按压缩放消失、颜色变化保留。

1. 七态

标准：每个组件按七态验收，缺哪一态要说得出理由。

状态	判据	缺了会怎样
默认	静止时的样子	——
悬停	指针在目标上	用户不知道能不能点
按压	目标被按下	不知道点击是否生效
焦点	键盘可见焦点	键盘用户直接不可用（SC 2.4.7）
禁用	不可用但可见	用户不知道为什么不能操作
加载	数据在路上	不知道是卡住了还是没反应
错误	输入非法 / 操作失败	用户不知道自己错在哪
空	没有数据	页面看着像坏了

2. 哪些不许缺

标准（决策 8：APG 状态闸门——APG 有专条的，状态与键位不许缺）：

type	必缺即不合规	依据
switch	焦点、禁用、按下	APG Switch pattern
segmented（radio group）	焦点、禁用、方向键遍历	APG Radio Group pattern
modal（dialog）	焦点陷阱、Esc、焦点归还、关闭后焦点归还给触发元素	APG Dialog (Modal) pattern
dock（toolbar）	焦点、Home/End	APG Toolbar pattern
input	焦点、禁用、错误	WCAG 1.4.11 + 3.3.1
dropdown	焦点、禁用、按下、展开/收起	APG Combobox (Select-Only) + Listbox
tabs	焦点、禁用、按下、方向键 / Home / End	APG Tabs pattern
choice（checkbox / radio）	焦点、禁用、方向键（radio）	APG Checkbox + Radio Group
button	焦点、禁用、按下	WCAG 2.4.7 / 4.1.2

没专条的（card / nav / motion）自定，但焦点与禁用不许没有——那是所有可交互元素的底线。

Skeleton 是 loading 态的载体，不做七态：只验 role=status + aria-busy、 占位块 aria-hidden，以及版式是否与最终内容一致。

3. 怎么查

实测口径：demo 是状态矩阵的载体，所以"demo 里有没有这个状态"就是覆盖度。 npm run check:states 扫 demo 源码里的状态证据（disabled / aria-invalid / aria-busy / focus-visible / 空 / loading 等），对照上表出缺口——缺口就是 P4 的优先级，不靠新鲜感排。

动作：补状态时先补"必缺"那几类；demo 里要让状态看得见（不是只加一个 prop）， 否则它不算被演示。

demo 里的文字只有一类该留在舞台内：怎么操作这一屏（键位、触发方式），一行以内。 "为什么这样设计 / 材质怎么叠"这类解释写在 notes 与复用卡（右侧本来就有）， 舞台是看效果的地方，不是读说明的地方。

检查项：

npm run check:states

---

搬到新项目要花多少代价

要搬的	在哪	量
必缺状态表	src/data/state-requirements.json	24 行
覆盖率脚本	scripts/check-states.mjs	95 行
notes frontmatter 约定	AGENTS.md + 各组件的 notes.md	每组件一个字段块

• 零依赖，但依赖机制：矩阵能被执行的前提是"每个组件都有带 frontmatter 的 notes"。没有 registry / frontmatter 体系时，这一篇只能降级成一张人工对照表。
• 必须整块搬：表 + 脚本 + frontmatter 约定三件一起；只搬表就是抄了一份没人执行的清单。
• 可以剥掉：APG 专条判定（目标项目不要求无障碍达标时，可只留默认 / 悬停 / 按压 / 禁用四态）。
• 工时：已有 frontmatter 体系约 30 分钟；没有的话先建约定，约 2–3 小时。
• 搬完怎么验：node scripts/check-states.mjs --strict 全绿；故意删掉某个组件的 disabled 演示，脚本必须报出来。

1. 固定视口 + 内滚

标准（ROADMAP 决策 5）：站内页面不整体上下滚。

┌ TopNav（fixed，56px）──────────────────────────┐
├ PageShell（高度 = 100dvh - 顶栏高度）─────────┤
│  ┌ PageBar（不滚）标题 + 说明 + 工具栏 ─────┐  │
│  └─────────────────────────────────────────┘  │
│  ┌ PageScroll（overflow-y-auto）正文 ───────┐  │
│  └─────────────────────────────────────────┘  │
└────────────────────────────────────────────────┘

• 视口高度 = calc(100dvh - var(--nav-h))，--nav-h 由 body.has-topnav 给（56px），复现页为 0。
• 页头（.page-bar）不参与滚动，只靠一条发丝线（--color-divider）与正文划界。
• 正文滚在自己的容器里（.page-scroll），overscroll-behavior: contain——滚到底不带动文档。
• 只有整页场景（营销复现页）例外：它没有页头，内容从上到下铺开。

为什么：整页滚动时顶栏和页头会跟着走，用户每次要操作都得滚回去；固定视口让"页头是常驻的"这件事成立。

实测（基线 982e282，2026-10-31 重测）：src/components/PageShell.astro 已落地，9 个页面走它； 有页头的 7 页（使用概览 / 组件详情 / 整页场景 / 组件列表 / 设置 / 矩阵 / 页面总览）全部走 PageShell； 营销复现页（page-home）走 PageShell 但无页头；index 与 workbench 不走 PageShell——前者是落地页，后者是固定视口工作台 ✓。

动作：新增页面一律用 PageShell；不要自己写 min-h-screen + 文档滚动。

检查项：

# 页面里不该再有文档级滚动容器
grep -rn "min-h-screen\|min-h-\[calc(100vh" src/pages | wc -l

2. 屏宽基准

标准：同一个屏宽基准 → 同一套内边距 → 同一个容器。 全站的宽度只有一处真值，容器、内边距、贴边定位都从它算：

:root {
  --frame-max: clamp(1560px, calc(100vw - 440px), 3600px); /* 中间项 = 两侧留白固定 220 */
  --frame-gutter: 94vw;  /* 窄屏两侧留白 */
  --frame-pad: 16px;     /* 框内左右内边距（≥640px 时 32px） */
  --measure: 40em;       /* 行长上限：管读的东西，不管框 */
  --page-col: 96rem;     /* 分区页的内容列：框内的第二档，单页可用 colWidth 覆写 */
}

基准本身随屏宽增长（2026-10-31 两轮）：固定 1560 在 4K 上两侧各留 1140px，用户实测"留白很不舒服"。 现在的规则是留白固定 220px：2000px 以下与最早一致（1560），往上框按 1:1 吃掉额外宽度—— 2560 与 3840 两档实测两侧都是 220px，3600 封顶。增长只写在 token 定义里： 别处再写一个 calc(100vw - …) 就是第二套基准，check:frame 会拦。

宽度被列数吃掉，而不是被行长吃掉：框长了之后，段落有两种合法去处—— 分栏流动，或留在 --measure 内（40em ≈ 40 汉字 / 80 西文字符，见 typography.md §2）：

类	用途
.container-page	只定宽与居中（不带内边距）
.page-frame	居中框 + padding-inline: var(--frame-pad)——页面内容区与顶栏用它
.page-col	分区页（设置 / 详情 / 向导）的内容列：在框内再收一档到 --page-col 并居中，页头与正文同用一条列
.wb-frame	工作台三栏的框，与全站同一个基准
.doc-grid	文档墙：≥1800px 起 repeat(auto-fill, minmax(34rem, 1fr))，窄屏单列；展开的那篇 span 2
.prose-columns	正文分栏：≥1800px 起 columns: 34em，标题 / 表格 / 代码块 / 引用 column-span: all 整宽跨栏
.glossary-columns	条目墙：columns: 26rem，宽度换列数（字典页排法）
.glossary-columns-wide	行更宽的一档（组件清单/术语表）：≥2600px 才分列，常规屏保持单列表格

表格不拉满：≥1800px 时表格回到真实 table 盒（display: table; width: auto; max-width: 100%）， 按内容宽度左对齐、放不下就换行。拉满卡片会把"管什么"这种长文本列撑成 150 字一行—— 宁可让表格右侧留白，也不牺牲列内的行长。

为什么这条是硬规则：2026-10-31 之前的"分段感"几乎全是基准不统一造成的——顶栏 1560 居中、 工作台满宽、logo 绝对定位到屏幕边缘。于是 logo、导航、控制簇、三栏各用各的宽度， 在 3848px 屏上两端能差 3800px。改基准比改样式有效：统一之后，1920 与 3848 两档实测 logo 左边 212 / 1176、齿轮右边 1696 / 2660，两端始终落在框上。

实测（2026-10-31，headless Chrome 真像素 + CDP 量盒）： 1920 框 1560（两侧 180）、2560 框 2120（两侧 220）、3840 框 3400（两侧 220）； /design 文档墙 1920 两列 / 3840 四列，判断层术语 1920 三列 / 3840 六列， 资料库正文 2560 三栏、3840 五栏，表格按内容宽（3840 实测 2081px，最后一个字列 915px）； 工作台舞台在超宽下把 demo 卡垂直居中（my-auto），画布留白成为构图而不是空洞。

检查项：

npm run check:frame   # 写死宽度 + 容器后又写 px-，两处都拦

3. 间距

标准：间距只用 4px 网格（Refactoring UI：间距只用 4 的倍数）。本站间距 token：

token	值	用途
--space-1	4px	图标与文字之间
--space-2	8px	紧凑内边距
--space-3	12px	控件内边距
--space-4	16px	常规间距
--space-5	24px	区块内边距
--space-6	32px	区块之间
--space-7	48px	大块留白
--space-8	64px	页面级留白

实测：--space-* 定义了就没人用——全站的间距实际由 Tailwind 的 p-4 / gap-3 这类工具类承担， 而且这些工具类的值不是 4 的倍数（Tailwind 的 spacing 步长是 0.25rem = 4px ✓，但 gap-2.5/p-3.5 这类半档会破格）。

动作：二选一——① 把 Tailwind 的间距步长也纳入 token 契约（在 @theme 里定义 --spacing）； ② 承认间距由 Tailwind 负责，删掉本站的 --space-*（它们现在是"定义了没人用"的假契约）。 推荐 ①：既然字号已经用 --text-scale 管住了倍率，间距同理可以收口。

检查项：

# 半档间距会破 4px 网格
grep -rhoE "(p|m|gap|w|h|top|left|right|bottom)-[0-9]+\.5" src | sort | uniq -c

4. 圆角

标准：圆角是一条阶梯，值来自 @theme 的 --radius-*（Tailwind 的 rounded-* 工具类直接取用）：

档	值	用途
--radius-sm	4px	小标签
--radius-md	6px	输入框、chip
--radius-lg	8px	按钮、卡片
--radius-xl	12px	大卡片
--radius-2xl	16px	面板
--radius-3xl	24px	弹层、坞站托盘

阶梯 = 8px 基准的倍数（0.5 / 0.75 / 1 / 1.5 / 2 / 3）。值沿用原状—— 先把真值收进 token，改档位是 P3 配方表的事（换轴时半径应该跟着轴一起换）。

实测：101 处 rounded-* 工具类，全部自动取用 token ✓（收进 @theme 之前是散落的默认值， 而 Tailwind 的默认值恰好与本站阶梯一致，所以视觉没有变化）。

动作：新增容器从这六档里选；需要"随手一个圆角"时先想清楚它属于哪一档。

---

搬到新项目要花多少代价

要搬的	在哪	量
屏宽基准 4 个变量（含 --measure）	global.css「屏宽基准」	12 行
三个容器类	global.css「布局工具」	17 行
页面骨架	src/components/PageShell.astro	32 行
守门脚本	scripts/check-frame.mjs	86 行（改 SKELETON 路径即可）
文档墙 / 条目墙 / 正文分栏（按需）	global.css 的 .doc-grid / .glossary-* / .prose-columns	约 60 行

• 零依赖：纯 CSS + 一个原生 Node 脚本。
• 必须整块搬：token → 容器 → 页面骨架 → 守门脚本，四件按序。少了脚本，三个月后一定会冒出第二套宽度——那正是本站 2026-10-31 之前"分成好几截"的成因。
• 可以剥掉：.wb-*（工作台三栏）；多列容器（信息密度不够时单列更稳）。
• 工时：约 20 分钟——10 分钟拷，10 分钟把 --frame-max 的下限/封顶换成目标设计稿的宽度，再跑 1920 与 3840 两档。
• 搬完怎么验：两档宽度下量 logo、页头标题、内容左边缘是否落在同一条竖线上；node scripts/check-frame.mjs 报 0 违规。

1. 唯一来源

标准：通用 UI 图标一律来自 lucide-react，并通过 src/components/Icon.tsx 渲染。业务组件不直接手写 <svg> 表达箭头、勾选、关闭、面板、设置这类通用含义。

动作：

• 新增通用图标：先在 Lucide 里找，再通过 Icon 使用。
• 类型图标：只改 src/components/icons.ts 的 TYPE_ICON 映射，不在 TypeGlyph 里画路径。
• 品牌 Logo、滤镜图形、曲线图可以保留自绘 SVG，但不能顺手新增装饰性内联图标。

检查项：

grep -Rn "<svg" src --include="*.tsx" --include="*.astro"

2. 网格、尺寸与线宽

标准：

项	规则
网格	统一 viewBox="0 0 24 24"
渲染尺寸	14 / 16 / 18 / 20 / 24，不再出现 15、17、22 这类临时值
默认线宽	2
小尺寸勾选	14px 勾用 2.25，12px 勾用 3，避免缩下去后断线
端点	Lucide 默认 round cap / join，不混 square
激活态	只改颜色、底衬或尺寸，不改 strokeWidth

为什么：图标是否舒服，第一眼看的是光学重量，不是形状。线宽随激活状态变化会让图标“跳一下”；14 / 20 / 24 三种网格同时存在，会让一排图标看起来像从三个系统里借来的。

3. 类型图标

标准：16 个组件类型各有唯一图标，名称与语义来自 TYPE_ICON：

类型	Lucide 图标
button	MousePointerClick
card	SquareStack
input	TextCursorInput
dropdown	ChevronsUpDown
choice	SquareCheck
nav	Waypoints
tabs	LayoutPanelTop
modal	AppWindow
dock	Dock
segmented	SlidersHorizontal
switch	ToggleRight
drag	GripVertical
cursor	MousePointer2
motion	Activity
toast	BellRing
skeleton	Rows3

动作：新增类型时，TYPE_LABEL、TYPE_ORDER、TYPE_ICON 三处一起补；缺图标会落回 Circle，但这不应成为常态。

4. 无障碍

标准：

• 图标旁边有文字时，图标 aria-hidden="true"。
• 图标是按钮唯一内容时，按钮必须有 aria-label，图标仍保持装饰性。
• 颜色不能作为图标状态的唯一表达；禁用、激活、错误要同时有形状、文字或焦点态。

搬到新项目要花多少代价

要搬的文件：src/components/Icon.tsx（13 行）、src/components/icons.ts（44 行）、package.json 里的 lucide-react。

零耦合：Icon 只包 Lucide，不读 registry、不读站点 token。换项目时可以直接复制这两个文件。

可以剥掉的部分：TYPE_ICON 是本站组件类型专用的，新项目可以删掉映射，只保留 Icon 包装。

不能直接搬的情况：如果项目不允许外部依赖，就把用到的 Lucide SVG path 复制进 icons.ts；Lucide 是 ISC 许可，但复制后需要自己维护更新。

工时：接入约 10 分钟；把现有内联图标全部替换约 1 小时；补图标预览页约 1 小时。

搬完怎么验：

grep -Rn "strokeWidth=\"1.8\|strokeWidth=\"2.2\|viewBox=\"0 0 20 20\|viewBox=\"0 0 14 14" src

期望 0 处。

组件回答"这个零件长什么样"，页面模式回答"零件按什么顺序摆"。 下面每条都来自至少两家系统的同一结论；只有一家主张的，标了出处不作硬规则。

1. 页面头

标准：H1 是资源名或任务名；一句说明只补 H1 没说的；主操作只有一个，放在右上。

位置	放什么
左	返回 / 面包屑（二选一）→ H1 → 一句说明
右	主操作（动词 + 名词）→ 次要操作 → 溢出菜单
永不	第二个同权重的主操作；把主操作沉到内容底部

• 主操作是"创建 / 查看日志 / 提交"这类推进任务的动作；"矩阵视图 / 列表视图"是视图切换，走次要按钮。
• 单任务页例外（向导 / 认证 / 问卷）：主操作就是这条流程的提交，留在表单末尾； 页头不再放第二个提交，也不放"下一步"的副本。页头右上只留给跨页面的动作（退出向导、找帮助）。
• 错误分两层：页面级 banner 说后果与恢复方式，字段级 errorMessage 说这一格该填什么。两层各说一件事，不互相复述。
• 窄屏时操作区换到标题下一行，主操作仍排最后（视觉上靠右）。
• 没有创建能力就不放创建按钮，不摆一个禁用按钮占位。

本站落点：PageHeader 的 actions 槽。dashboard（筛选）、list（矩阵视图）已用； record 的三个操作原先沉在正文底部，与"页头承担页面级操作"不一致，已迁入页头。 分区页（PageShell col）的页头与正文共用 .page-col 这一条内容列——标题不会一个人留在框边上。 单任务页：create（48rem）与 auth（30rem）用 colWidth 收窄并在正文区垂直居中。

反例：page-home 没有页头——它是品牌页，主操作在 hero 里，跟着内容走。

2. 索引页

标准：工具栏紧贴数据上方；计数与结果同区；分页只在超过一页时出现。

• 搜索、筛选、排序放进同一个面板的顶部条，不要分两处；它们只影响下方列表。
• 计数写成结果范围 + 总数（1–12 条，共 89 条），放在列表页脚；不要只写总数，用户不知道当前看到哪一段。
• 筛选或搜索变化时回到第 1 页；只有一个分页时不渲染分页条。
• 行整行可点就整行是链接；不可用的行保持不可点，不假装可点。

本站落点：ComponentList。工具栏、计数、分页、回第 1 页都已按此实现。

3. 表格（只读也要语义）

标准：文本左对齐、数字右对齐，列头跟数据同向；数字用 tabular-nums；只读表格同样需要 caption 与 scope。

• 行高默认 40px 一档，比卡片行更紧；不为稀疏数据放大行高。
• 窄屏不要硬压列：优先减少次要列，其次横向滚动，最后才换卡片列表。
• 排序状态要能被看见（当前列 + 方向），不能只靠悬停提示。

本站落点：/showcase/matrix 已用 th scope；只读表已复现为 table 三材质，list 场景用 framed=false 嵌进面板（/showcase/demo/list 的「表格」视图）。排序 / 筛选 / 选择 / 固定列都还没做，逐项放行。

4. 设置页

标准：分组用 fieldset + legend；一行 = 标签 + 一句说明 + 控件；文本编辑显式保存，开关/滑块即时生效。

• 宽屏两列：左栏是分组导航（锚点），右栏是卡片列（Polaris 的 2fr / 5fr）。 导航出现时，卡片内同名的分组标题收成 sr-only——同一屏不画两遍分组名，语义仍在。
• 说明只写用户不知道的后果（"上次更新 3 个月前"），不重复标签。
• 文本字段有脏状态时给出保存 / 放弃，并说明"未保存"；保存后给一次 aria-live 确认。
• 不要每个卡片一套独立保存；同页只保留一套保存模型。
• 危险操作单独成组（账户删除、回滚），不与日常开关并排；是否需要二次确认按决策 17 的可撤销性判断。

本站落点：page-settings。开关与滑块即时；个人资料改为显式保存（保存 / 放弃 + 状态播报）； ≥1024px 起左栏分组导航 + 右栏卡片，窄屏退回单列并让卡片标题重新出现。

5. 详情页

标准：键值事实用 dl；行级操作必须带视觉隐藏上下文；所有行都去同一个地方时，用卡片级的一个操作。

• 状态徽标、负责人、时间放在身份区附近，不要散到正文各处。
• 主操作一个；次要操作与溢出菜单往后排。
• 缺失的可选值写"未填写"，不省略整行。

本站落点：record 用 Descriptions（dl）+ 面包屑；操作移到页头与第 1 条对齐； 宽屏两列（2fr / 1fr）——左=身份与变更摘要，右=版本 / 环境 / 提交 / 负责人 / 回滚点，窄屏按 身份 → 摘要 → 元数据 单列下来。

6. 流程页

标准：线性且 ≥3 步才用步骤条；可乱序、可跨会话的任务用任务清单，两者不混用（GOV task list / USWDS step indicator）。

• 校验在提交时发生；失败后顶部错误摘要放在 H1 之下、表单之上，并把焦点移过去。
• 摘要标题说明有几处问题；每条链接到出错字段，摘要文案与行内错误逐字一致。
• 不因为失败清空输入；返回上一步要保留已填内容。
• 核对页分组展示答案，能回到对应步骤修改；未填写的可选项显示"未填写"。

本站落点：create 三步步进器；本次补错误摘要、焦点与字段链接。宽屏时步骤条转到左侧成竖排导航，表单列仍按 colWidth 收到 48rem——表单不跟着框拉长。

7. 页面级状态

状态	规则	本站
加载	先给结构再给内容；骨架与最终版式同形	组件级 skeleton 已有；页面级载体未定
空	说清什么空了 + 一句下一步 + 一个主操作	empty-state 三材质已落地，list 已接
错误	说明影响与恢复方式，不用"出错了"兜底	banner 三材质已落地（warning 走 role="alert"，info / success 走 role="status"），auth 已接；页面级"服务不可用"载体仍未定
404 / 500	H1 直说问题；给一条回去的路；不显示技术细节	仍是框架默认页

8. 来源与不照抄的部分

规则	本地快照	官方
索引页主操作右上、工具栏紧贴列表	polaris/.../patterns/resource-index-layout/variants/default.mdx	Polaris（存档）
设置两列分组 + 保存栏	polaris/.../patterns/app-settings-layout/variants/default.mdx	Polaris（存档）
分页只在需要时出现、过滤回第 1 页	govuk/src/components/pagination/index.md	GOV.UK
数字右对齐、只读表格语义	govuk/src/components/table/index.md · uswds/_components/table/guidance/usability.md	GOV.UK · USWDS
摘要列表的行级操作要带隐藏上下文	govuk/src/components/summary-list/index.md	GOV.UK
错误摘要置顶、聚焦、逐条链接	govuk/src/components/error-summary/index.md · govuk/src/patterns/validation/index.md	GOV.UK
步骤条只用于线性多步	uswds/_components/step-indicator/guidance/when-to-use.md	USWDS
图表不靠悬停才能读、给数据表替代	uswds/_components/data-visualizations/data-visualizations.md	USWDS

不照抄：

• GOV 禁止"返回链接 + 面包屑"同时出现——本站 create 用返回、record 用面包屑，分场景成立。
• GOV 的绿/红系统色不直接搬；语义色走本站 token。
• Polaris 的 contextual save bar 已标 deprecated；本站不引那套组件，只借"脏状态才出现保存"的时机。
• 破坏性操作不一律二次确认（决策 17）；可撤销的用即时执行 + 恢复入口。
• Polaris 的两列分组只在宽屏成立；窄屏退回单列，此时卡片内的分组标题重新出现（左栏导航隐藏后它是唯一标题）。

---

搬到新项目要花多少代价

要搬的	在哪	量
页面头槽位	src/components/PageHeader.astro	40 行
索引页工具栏 + 计数 + 分页	ComponentList.tsx + pagination/*	约 1 个页面
错误摘要	CreateWizard.tsx 内的局部实现	约 40 行
只读表格语义	matrix.astro 的 table 写法	1 个示例

• 零依赖：全部是结构规则，不带库。
• 必须整块搬：页面头槽位 + 索引页计数/分页 + 错误摘要，三件一起才形成一致的任务路径。
• 可以剥掉：Polaris 两列设置、Gov 任务清单——站点没有对应场景就不搬。
• 搬完怎么验：四个场景各走一遍"进入 → 主操作 → 失败 → 恢复"；错误摘要能用键盘逐条跳到字段。