Files
CloudLab 880fde8641
CloudLab CI/CD / 门禁 doctor (push) Failing after 30s
CloudLab CI/CD / 单元测试 (push) Skipped
CloudLab CI/CD / 归档完整性 (push) Skipped
CloudLab CI/CD / 构建站点与归档 (push) Skipped
CloudLab CI/CD / 部署到 lab.hdtime.space(rsync) (push) Skipped
CloudLab CI/CD / 构建镜像并推送 Gitea 容器仓库 (push) Skipped
CloudLab CI/CD / 容器部署到 lab.hdtime.space (push) Skipped
CloudLab CI/CD / 发布版本(Tag) (push) Skipped
docs(ui): record Sprint 10 narrow-screen header and overlay fix
- Add UI-SPRINT10-PLAN and UI-VERIFICATION section 17 with the 480px
  two-row room header, 390/320 breadcrumb measurements and the
  compare workbench sticky-bar fix.
- Record local and repo 438-check runs, 39-load local/live smoke,
  16/16 live room headers and overlay positions at 390/480/760/761/900.
- Update UI-DELIVERY, UI-SYSTEM, UX-AUDIT, BRAND-GUIDE and Sprint 9
  notes; the Sprint 9 breadcrumb limitation is now marked as solved.
- Add before/after screenshots, live screenshots, header/overlay probe
  JSON and live URL/SHA evidence under docs/evidence/sprint10.
2026-11-20 23:50:46 +00:00

42 KiB
Raw Permalink Blame History

CloudLab 设计系统(UI-SYSTEM)

文档状态(与 2026-11-20 源码同步):令牌值、组件规则、状态样式均从 app/app.css 与页面级 CSS 实测抽取;"v2.1 段"指 app.css 第 976 行起的附加规则(2026-11-18)。 适用范围:app/ 下 13 个页面的界面实现与后续增量开发。后端接口不在本文范围,见 API-CONTRACT.md;页面级问题见 UX-AUDIT.md;品牌资产见 BRAND-GUIDE.md。 最后核对命令:见文末第 10 节。


0. 系统分层(先看这张图)

app/app.css         全局::root 令牌 + 深色覆盖 + 基础元素 + 通用组件 + v2.1 可访问性/状态段
  ├─ home.css       首页:--hp-* 命名空间 + .hp-* 组件(映射 --cl-*,保留品牌差异)
  ├─ room.css       实验室外壳:--rm-* 主题变量(4 个 room)+ .rm-* 组件
  │    └─ compare.css      九宫格全屏工作台:.cmp-overlay 内自成暗色 --cmp-*
  │         ├─ compare-bio.css   生物九宫格页面级补充
  │         └─ compare-data.css  数据九宫格页面级补充
  ├─ bio-databases.css  资料库页:.bd-*,无独立令牌
  └─ ide.css        IDE:独立令牌镜像(--bg/--panel/--ink/--accent/--lime/--focus),不加载 app.css

四条硬规则:

  1. 全局令牌只定义一次:--cl-* 只在 app.css :root 与其 html[data-theme="dark"] 覆盖中定义;页面级 CSS 只读,不重定义。
  2. 页面命名空间隔离:首页 --hp-*/.hp-*、实验室 --rm-*/.rm-*、对比 --cmp-*/.cmp-*、资料库 --bd-*/.bd-*;新页面必须建命名空间,禁止复用 .rm-* 到非实验室页。
  3. ide.css 是例外且必须镜像:ide.html 不加载 app.css/shell.js,ide.css:1-27 自建同值令牌。修改品牌色/圆角/焦点色时必须同步两处,否则 IDE 与站点漂移。
  4. 颜色与字号优先用令牌:新增代码不得写 #hex(--cl-* 定义处除外);字号优先用 --cl-text-* 或既有组件类。IDE 现有字面量 px 保留(静态棘轮按字面量扫描),但全站 <10px 基线已为 0,不得新增。

1. 颜色令牌

1.1 浅色(:root,app.css:1-26)

令牌 值 语义/用途
--cl-bg #f4f7f4 页面底色(冷白)
--cl-bg-2 #eaf0ea 次级底色/分区
--cl-surface #ffffff 卡片/面板
--cl-surface-2 #f8faf7 卡片内嵌/表头
--cl-surface-3 #eef4ef 控件底色/hover
--cl-ink #0d1f1c 主文字
--cl-ink-2 #2c423e 次主文字
--cl-sub #526863 辅助文字(正文级)
--cl-mut #5f736e 弱化文字(非正文)
--cl-line #dfe8e1 主边框
--cl-line-2 #edf3ee 弱边框/分隔
--cl-brand #0f766e 主品牌色/主按钮
--cl-brand-2 #0d9488 品牌亮色/hover/焦点环
--cl-brand-ink #064e46 品牌底上的深色文字
--cl-brand-soft #e6f7f1 品牌浅底(选中/提示)
--cl-accent #d9f06b 强调色(柠檬黄,少量)
--cl-accent-ink #263700 强调底上的文字
--cl-blue #2563eb 信息/数据
--cl-cyan #0891b2 信息辅助
--cl-green #15803d 成功
--cl-amber #b45309 警告
--cl-red #b91c1c 错误/危险
--cl-violet #6d28d9 分类辅助

结构令牌:--cl-r:16px、--cl-r-sm:10px、--cl-r-lg:26px、--cl-header:64px、--cl-max:1240px、--cl-shadow、--cl-shadow-sm、--cl-font、--cl-display、--cl-mono、color-scheme:light。

1.2 深色(html[data-theme="dark"],app.css:27-49)

令牌 深色值 备注
--cl-bg #08110f 近黑绿
--cl-bg-2 #0c1714
--cl-surface #0e1b18
--cl-surface-2 #0b1613
--cl-surface-3 #13231f
--cl-ink #e8f2ec
--cl-ink-2 #c9dad3
--cl-sub #9fb5ae
--cl-mut #789089
--cl-line #20332d
--cl-line-2 #172722
--cl-brand #2dd4bf 深色下品牌色变亮,保证对比
--cl-brand-2 #5eead4
--cl-brand-ink #082f2b
--cl-brand-soft #0d2b25
--cl-accent #d9f06b 不变
--cl-accent-ink #263700 不变
--cl-blue #60a5fa
--cl-cyan #22d3ee
--cl-green #4ade80
--cl-amber #fbbf24
--cl-red #f87171
--cl-violet #a78bfa

深色同时设 color-scheme:dark。shell.js applyTheme() 负责写 data-theme 并同步 meta[name=theme-color]:深色 #08110f、浅色 #0b2520。

1.3 首页品牌差异(--hp-*,home.css)

首页有意保留比主站更深/更暖的底色,其余尽量映射:

首页令牌 深色 浅色 说明
--hp-bg #05110d #f4f2ea 比 --cl-bg 更深/更暖,保留
--hp-hi var(--cl-accent) 同 强调色映射
--hp-mint var(--cl-brand-2) var(--cl-brand) 强调辅助色,深浅各取更亮/更深
--hp-on-accent #082016 同 强调底文字,注释标 13.5:1
--hp-sans/mono/r/r-sm/max var(--cl-*) 同 全部映射

完整值与用途见 BRAND-GUIDE.md §5。

1.4 实验室与对比

  • room.css:7-10 按 data-room 提供四套:bio #0f766e/#e8f7f1/#064e46、chem #a16207/#fdf5e6/#713f12、data #1d4ed8/#eaf0fe/#1e3a8a、human #9d174d/#fceef4/#831843(依次 accent/soft/ink)。
  • compare.css:139 的 .cmp-overlay 内定义暗色工作台:--cmp-bg:#050d0b、--cmp-panel:#0a1512、--cmp-ink:#e7f3ec、--cmp-accent:#d9f06b、--cmp-teal:#5eead4、--cmp-amber:#fbbf24。这是"工作台永远是暗色"的产品决策,不再跟随全站主题。

1.5 对比度实测(WCAG 相对亮度,2026-11-18)

前景 / 背景 比值 AA 正文(4.5) AA 大字(3.0)
#0f766e / #f4f7f4 5.07 通过 通过
#0f766e / #ffffff 5.47 通过 通过
#ffffff / #0f766e 5.47 通过 通过
#0d1f1c / #f4f7f4 15.82 通过 通过
#526863 / #f4f7f4 5.53 通过 通过
#5f736e / #ffffff 5.04 通过 通过
#5f736e / #f4f7f4 4.67 通过(余量仅 0.17) 通过
#d9f06b / #0b2520 12.79 通过 通过
#263700 / #d9f06b 10.21 通过 通过
#e8f2ec / #08110f 16.72 通过 通过
#9fb5ae / #08110f 8.83 通过 通过
#7b938c / #08110f 5.83 通过 通过
#7b938c / #0d2b25 4.60 通过 通过
#0d9488 / #ffffff 3.74 不用于正文 通过(404 大字)
#5f736e / #fefefe 5.00 通过 通过
#064e46 / #ffffff 9.61 通过 通过
#5eead4 / #08110f 12.94 通过 通过
#2dd4bf / #08110f 10.28 通过 通过
#d9f06b / #08110f 15.15 通过 通过

未测色对(disabled、chip、深色表格斑马纹、.cmp-* 内部)标注为待测,改动这些组合时必须补测。规则:正文不用 --cl-mut;--cl-mut 只用于 ≥12px 的非关键辅助信息,且不得再降低透明度。2026-11-18 S3-2 已将深色 --cl-mut 由 #789089 调为 #7b938c(brand-soft 上 4.43→4.60),并修复浅色 hover 两处 3.74:1(详见 2.6)。


2. 字号比例与文本工具类

2.1 新令牌(app.css:983-990,v2.1 新增,不改旧值)

令牌 值 用途
--cl-text-2xs 11px 最小辅助(时间、计数、脚注)
--cl-text-xs 12px 控件/标签/表格
--cl-text-sm 13px 正文下限/卡片描述
--cl-text-md 14.5px 默认正文(与 body 一致)
--cl-text-lg 17px 小标题/引导句
--cl-text-xl 20px 区块标题

2.2 工具类

类 等价 说明
.cl-text-2xs 11px/1.5 元信息
.cl-text-xs 12px/1.55 控件/表格
.cl-text-sm 13px/1.6 紧凑正文
.cl-text-md 14.5px/1.65 默认
.cl-text-lg 17px/1.45 小标题
.cl-text-xl 20px/1.35 区块标题
.cl-text-aux 11px + --cl-mut 辅助行
.cl-text-body 13px/1.65 正文段落

2.3 规则

  1. 正文与可交互控件目标 ≥12px;辅助信息 ≥11px;装饰性字标(如 home.css 7.5px)是例外,必须带 aria-hidden 或不承载信息。
  2. 历史组件不批量替换 font-size(v2.1 注释明确"历史组件不做批量替换");新组件与迁移中的组件优先用工具类。
  3. 表格正文 ≥12px;S2-2 已将共享组件(含 .cl-table 12.5px、th 11.5px、.cl-btn.sm 12px)提升到下限,明细见 2.4;页面级 CSS 的迁移由各 owner 按 S2-3/S2-4/S2-5 推进。
  4. 行高:正文 ≥1.6,控件 1.4-1.5,标题 1.3-1.45。

2.4 共享组件字号修订(S2-2,2026-11-18)

只提升既有选择器的字号:未删除规则,未改颜色、间距或布局结构;行号为修改后的 app/app.css 行号。桌面端可点击文本满足 ≥12px,密集元信息 ≥10.5px。

选择器 行 原值 新值 场景
.cl-kbd 131 10px 11px 快捷键徽标
.cl-btn.sm 158 11.8px 12px 小按钮
.cl-chip 164 11.5px 12px 状态/分类 chip
.cl-hint 207 11px 12px 表单/页脚提示
.foot-note 346 10.8px 11.5px 页脚说明
.cl-cats button 383 10.3px 12px 可点击分类筛选
.cl-browse-head p 551 12.7px 13px 浏览页副标题
.cl-file-row .fn span 580 10px 11px 文件行副标题
.cl-file-row .fs 581 10.5px 11px 文件大小
.cl-file-row .fe 582 9.5px 10.5px 文件类型徽标
.cl-table 643 11.5px 12.5px 表格正文
.cl-table th 644 10.5px 11.5px 表头
.cl-table .num 647 10.5px 11.5px 数值列
.cl-tree summary .n 923 9px 10.5px 树节点计数
.cl-tree .cl-item 926 11.3px 12px 树列表项
.cl-file-row.head 929 9.5px 10.5px 文件列表表头
.cl-file-row.head .fs 932 9.5px 10.5px 文件列表表头大小
移动端 .cl-file-row .fs 853 9.5px 10.5px ≤720px 大小
移动端 .cl-cats button 884 9.8px 11.5px ≤720px 分类

补充:

  • .cl-cats button 桌面 12px、移动端 11.5px;390 宽实测 13 页均无横向页面滚动。
  • 移动端 .cl-file-row .fs 比桌面小 0.5px,符合 Sprint 2 计划 §3.2「移动端不得低于桌面 1px 以上」。
  • 本次未改任何 --cl-* 令牌与颜色值,也未替换 home/room/compare/ide 等页面级字号(分别由 S2-4/S2-3/S2-5 负责)。

2.5 全站字号门禁(S2 集成,2026-11-18)

在 S2-2/S2-3/S2-4/S2-5 各自修订后,Lead 在集成阶段做了一次全站收敛,目标是“有意义文本不低于 10px,<12px 进入总量预算”,而不是机械地把所有元信息都拉到 12px(会挤压抽屉、对比读数表和资料树)。

最终实测(tests/ui_invariants.py 313 项,1440/390):

指标 1440px 390px
有意义 <10px 文本 0 0
<12px 文本 966 946(预算 ≤1200)
横向溢出 0/13 页 0/13 页

Lead 收敛的选择器:

  • app.css:.cl-log-item .h 10.5、.cl-mobilebar button 10.5、移动 .cl-start-card span 10.5、移动 .cl-mobilebar .badge 10;S2 门禁将 .cl-item .m 提到 12、.cl-tree summary 与 summary .n 提到 12。
  • home.css:.hp-building-head 10、.hp-floor-main small 10、.hp-footer-cols div>span 10、移动 .hp-lab-tags i 10。
  • room.css:.rm-bench-grid-eyebrow 10.5、.rm-records-stats span 10.5;bio/data 的 room-meta 内联样式 10.5。
  • bio-databases.css:.bd-table th 10.5。
  • compare.css / compare-data.css:移动 .cmp-board-foot 10.5、移动 .data-cell-note 10.5。
  • ide.css:.ide-activity button em 10.5、.ide-panel-tabs b 10、.ide-status 10.5。

剩余 <12px 主要是 10.5–11.8px 的元信息(lab 抽屉分类、compare 读数表、browse 文件行、页脚链接),属于预算内保留项;后续若要进一步收紧,应先做布局回归再调整预算,禁止静默放宽。

2.6 S3-2 字号下限与对比度修复(2026-11-18)

字号(app.css,静态 <10px 归零)

行 选择器 原值 新值 备注
259 .preview-pane .k font:9.5px font:10.5px 示意面板标签
264 .preview-descriptors span 9.5px 10.5px 描述键
265 .preview-descriptors b 9px 10px 描述值
268 .preview-pills span 9px 10px 示意 pill
306 .mini-file .ft font:9px font:10px 文件类型
308 .mini-file .fs 9.5px 10.5px 文件大小
311 .mini-bench-head span font:9px font:10px 基准标题
318 .mini-kpis span 8.5px 10px KPI 标签(原最小)
379 .cl-drawer-tabs button span 9.5px 10.5px 抽屉页签计数
475 .cl-stat .box .l 9.5px 10.5px 统计标签
612 .cl-viewer-eyebrow 9.5px 10.5px 查看器眉标
690 .cl-search-foot kbd 9.5px 10.5px 搜索快捷键
851 .cl-viewer-path(≤720) 9px 10px 移动端路径
869 .hero-stats span(≤720) 9.5px 10.5px 移动端首页统计标签
928 .cl-tree .cl-item .m font:9px font:10px 树节点元信息

说明:验证器静态棘轮只统计 font-size: 声明(11 条);259/306/311/928 为 font: 简写,不在计数内但同样低于 10px,本次一并提升,避免“计数通过、视觉仍有小字”。未整体放大字号,也未改任何尺寸/间距。

对比度(2026-11-20 Sprint 5 验证:340 项 → 340 PASS / 0 FAIL / 0 SKIP)

行 位置 旧值 → 新值 背景 比值
565 .cl-crumbs .sep var(--cl-line) #dfe8e1 → var(--cl-mut) #5f736e #fefefe 1.24 → 5.00
965 .cl-404-code(大字) var(--cl-brand-soft) #e6f7f1 → var(--cl-brand-2) #0d9488 #ffffff 1.11 → 3.74(大字阈值 3.0)
— html .rm-crumbs .sep 临时覆盖已移除;room.css:23 改为 var(--cl-sub) #fefefe 1.24 → 5.00
50(深色) --cl-mut 令牌 #789089 → #7b938c --cl-brand-soft #0d2b25 4.43 → 4.60
1134 浅色 a:hover --cl-brand-2 → --cl-brand-ink #ffffff 3.74 → 9.61
1136 浅色 .cl-btn.primary:hover 背景 --cl-brand-2 → --cl-brand-ink #ffffff 文字 3.74 → 9.61

补充:

  • 验证器 340 项:340 PASS / 0 FAIL / 0 SKIP;Sprint 5 用像素采样补齐 index/bio-databases 的 4 个整页(183 处 0 违规),另有 818 处页面内部渐变/透明度跳过仍是未验证。
  • 额外自查(首页/bio/records/browse × 1440/390,8 组)初始可见文本 0 违规;浅色 hover 两处 3.74:1 低于正文阈值,按状态修复。
  • html .rm-crumbs .sep 的跨文件临时覆盖已清理:room.css:23 源规则改为 var(--cl-sub),app.css 覆盖已删除,避免双份真相。
  • 装饰性微字号白名单:app.css 已无 <10px 声明;仅保留 10px 的静态示意/元信息(.preview-、.mini-、.cl-crumbs/.cl-viewer-path 等),理由为“非交互、非正文、已从 8.5–9.5 提升到 10”,复核人 ui-designer,Sprint 4 复评后保留 10px(非正文、非交互),全站静态 <10px 已为 0。未新增任何主色硬编码;唯一新色值是 --cl-mut 令牌 #7b938c。

2.7 S4:IDE 字号迁移与静态零基线(2026-11-20)

  • app/ide.css 的 189 条 <10px 声明全部迁移:原值 ≥9.5px → 10.5px(48 条),<9.5px → 10px(141 条);保持字面量 px,不引入 var() 间接层。
  • .mat-ico 原固定 width:22px 在 10px 等宽字体下装不下 4 字符(内部 scrollWidth 24 > clientWidth 20);改为 flex:none; width:auto; min-width:22px; height:22px; padding:0 3px。
  • 未改字号层级、间距、栅格、DOM 与交互;其他页面与共享 app.css/chrome.css 未动。
  • tests/ui_invariants.py 的 STATIC_FONT_BASELINE 全站改为 0:当前 961 条声明中 <10px 为 0,逐文件只降不升。
  • 实测 340 项 PASS 340 / FAIL 0 / SKIP 0;像素采样 183 处 0 违规;合成对比度 4,821 采样 0 违规;运行时有意义 <10px 1440/390 = 0/0,<12px = 966/946(预算 ≤1200)。
  • IDE 真实数据 8 视图(1440×1000、390×844):无横向溢出,标题栏 64/58,可见 <10px=0,0 JS 异常 / 0 console error / 0 HTTP ≥400。
  • 局限:未做跨浏览器/真机;index.html 与 bio-databases.html 的渐变对比度已由 Sprint 5 像素采样补齐(见 2.8);818 处页面内部渐变/透明度跳过仍为未验证;IDE 登录后线上未做同口径探针。

3. 跳过链接与焦点规范

结构(13 页一致,文案两版均可):

<a class="cl-skip-link" href="#main-content">跳到主内容</a>
...
<main id="main-content" tabindex="-1">

样式规则(app.css:1007-1023):

  • 默认 1px 视觉隐藏(clip-path:inset(50%)),不是 display:none。
  • :focus/:focus-visible 展开:min-height:44px、padding:12px 18px、outline:2px solid var(--cl-ink)、outline-offset:3px。
  • 深色下文字用 --cl-brand-ink,背景仍是 --cl-brand。
  • 首页覆盖:home.css:76 把 outline 改为 --hp-on-accent;IDE 覆盖:ide.css:54-58 用 translateY(-160%) 隐藏、focus 显示,白字。
  • 打印时隐藏(app.css:1125)。

验收:首 Tab 必须可见;Enter 后 #main-content 获得焦点(有 tabindex="-1");焦点环不被页头遮挡。

3.2 焦点环

:focus-visible{outline:2px solid var(--cl-brand-2);outline-offset:2px}
button:focus-visible,a:focus-visible,input:focus-visible,
select:focus-visible,textarea:focus-visible,summary:focus-visible,[tabindex]:focus-visible{
  outline:2px solid var(--cl-brand-2);outline-offset:2px;
}
html[data-theme="dark"] :focus-visible{outline-color:var(--cl-accent)}
.cl-table tr:focus-visible,.cl-tree summary:focus-visible{outline-offset:-2px}

规则:

  • 只用 :focus-visible,不要给鼠标点击加环;键盘必须可见。
  • 禁止在页面级 CSS 写 outline:none 而不提供替代环;当前 room.css:162、compare.css:276/292、compare-bio.css:90 是反例,迁移时删除。
  • 焦点色:浅色 --cl-brand-2(#0d9488),深色 --cl-accent(#d9f06b);IDE 用 --focus(浅 #0f766e / 深 #5eead4)。
  • 焦点环在滚动容器内用负 offset,避免被裁切。

4. 组件规范

4.1 按钮 .cl-btn

<button class="cl-btn primary" type="button">提交运行</button>
<button class="cl-btn" type="button">取消</button>
<a class="cl-btn ghost" href="/app/browse.html">查看资料</a>
<button class="cl-btn sm" type="button" aria-pressed="true">全部</button>
<button class="cl-btn primary" type="button" aria-busy="true" disabled>
  <span class="cl-spinner" aria-hidden="true"></span>提交中…
</button>
  • 基础:min-height:36px、padding:7px 13px、圆角 10px、12.8px/600、1px 边框、轻阴影、.16s 过渡。
  • 变体:.primary(品牌底白字,深色下文字 #042f2b)、.ghost(透明底)、.accent(柠檬黄底深字);尺寸 .sm(30px/12px)、.lg(46px/14px)。
  • 状态::hover 上移 1px;:active 归位;[disabled] 透明度 .45;[aria-disabled="true"] 同 disabled;[aria-busy="true"] cursor:progress 且 spinner 14px;[aria-pressed="true"] 品牌浅底。
  • 图标:<svg class="i" aria-hidden="true"><use href="/app/sprite.svg#i-xxx"></use></svg>,禁止写死颜色。

4.2 表单

<div class="cl-field">
  <label for="run-name">运行名称</label>
  <input class="cl-input" id="run-name" name="run-name" aria-describedby="run-name-hint">
  <span class="val">必填</span>
</div>

<label class="cl-check"><input type="checkbox" class="cl-check"> 保留中间文件</label>

<select class="cl-select" aria-label="实验类型">
  <option>全部</option>
</select>
<p class="cl-hint" id="run-name-hint">仅用于列表展示,不影响实验参数。</p>
  • .cl-field 为 3 列网格 112px minmax(0,1fr) 58px,用于"标签-控件-值"。
  • .cl-input 高 34px、.cl-select 高 36px、字号 12-12.5px、圆角 8-9px。
  • hover 边框向品牌色混合;:focus-visible 2px 环;disabled 降透明度、底色 --cl-surface-2。
  • aria-invalid="true":红边 + 3px 红晕,focus 环也变红;必须同时提供文字错误说明(.cl-error 或 .cl-hint)。
  • 复选框/单选框 .cl-check/.cl-radio:18px、accent-color:var(--cl-brand)。
  • 占位符用 --cl-mut,不得再降透明度。

4.3 表格

<div class="cl-table-wrap">
  <table class="cl-table">
    <caption>最近运行(最多 100 条)</caption>
    <thead><tr><th scope="col">实验</th><th scope="col">状态</th><th scope="col" class="num">耗时</th></tr></thead>
    <tbody>
      <tr tabindex="0"><td>PCR 扩增</td><td>succeeded</td><td class="num">12s</td></tr>
    </tbody>
  </table>
</div>
  • 外层 .cl-table-wrap 负责滚动、边框、max-height:58vh;表头 sticky。
  • 行可聚焦时加 tabindex="0",用 :focus-within 提供整行底色;:focus-visible offset -2px。
  • caption 左对齐、11px,供读屏与视觉共用。

4.4 状态:空 / 错误 / 加载 / 骨架

<!-- 空态 -->
<div class="cl-empty">
  <svg class="i" aria-hidden="true"><use href="/app/sprite.svg#i-grid"></use></svg>
  <b>这个目录下没有可显示的内容</b>
  <p>换一个目录,或清空筛选条件。</p>
  <div class="cl-empty-actions">
    <button class="cl-btn sm" type="button" data-retry>重新加载</button>
    <a class="cl-btn sm ghost" href="/app/browse.html">回到资料浏览</a>
  </div>
</div>

<!-- 错误(可重试) -->
<div class="cl-error" role="alert">
  <span class="i" aria-hidden="true">!</span>
  <div>
    <b>数据库目录加载失败</b>
    <p>检查网络后重试;若持续失败,请稍后再来。</p>
    <div class="cl-error-actions">
      <button class="cl-btn sm" type="button" data-retry>重试</button>
    </div>
  </div>
</div>

<!-- 加载 -->
<div class="cl-loading" role="status" aria-live="polite">
  <span class="cl-spinner" aria-hidden="true"></span>正在加载资料清单…
</div>

<!-- 骨架 -->
<div class="cl-skeleton block" aria-hidden="true"></div>
<div class="cl-skeleton text" aria-hidden="true"></div>

规则:

  • 加载中容器加 aria-busy="true",结束后改回 "false";文本用 role="status" 或放到已有 live region,避免重复朗读。
  • 错误必须有 role="alert"(即时)或 aria-live="assertive"(容器级),并给可执行动作(重试/返回),不能只报错。
  • 空态 .cl-empty 最小高 140px、虚线边;主文案 <b> 13.5px,说明 12.8px。
  • 骨架只做视觉占位,aria-hidden="true",不要朗读。
  • 动效:spinner clSpin .7s linear infinite;skeleton clShimmer 1.25s;reduced-motion 下均停止。

4.5 Toast 与播报

<div class="cl-toast-box" id="toast-box" aria-live="polite" aria-atomic="true"></div>
<div class="cl-visually-hidden" id="status-live" role="status" aria-live="polite"></div>
  • .cl-toast-box 固定在底部居中(bottom:80px),.cl-toast 深墨底浅字,.ok 品牌绿、.err 红;3.2s 后移除(IDE 用 3.2s)。
  • 容器或 toast 必须带 role="status"/aria-live="polite";不要给每条 toast 都加 assertive。
  • 需要朗读但视觉隐藏的计数/结果,用 .cl-visually-hidden 的 live region(records.js 的做法)。
  • 记录页 #rec-undo 用 role="status" 呈现"已删除,撤回"。

4.6 徽标/标签/卡片

  • .cl-chip:24px 高、12px、圆角 999px;.ok/.warn/.err 三态;深色有专门覆盖。
  • .cl-tag:6px 圆角,用于分类/关键词。
  • .cl-card:表面色 + 1px 边 + --cl-r 圆角 + 20px 内边距 + 轻阴影。
  • .cl-note:左 3px 品牌竖线的提示块;.cl-ok:品牌浅底成功块。

4.7 表格/树/滚动容器中的焦点

  • .cl-table tr:focus-visible 与 .cl-tree summary:focus-visible 使用 outline-offset:-2px。
  • 滚动容器不要设 overflow:hidden 裁掉焦点环;必要时给内边距。

5. 状态语义与 ARIA 映射

状态 视觉 ARIA/属性 使用位置
加载中 spinner/骨架/文案 容器 aria-busy="true";文本 role="status" browse、bio-databases、IDE 应用加载
空 .cl-empty 无强制 role;说明文字可读 目录空、记录空、列表空
错误 .cl-error role="alert" 或 live region 加载失败、提交失败
可重试 按钮/链接 按钮文本"重试/重新加载" browse、bio-databases、IDE
选中/切换 品牌浅底 aria-pressed="true/false" 记录筛选、browse 视图 tab、分类 chip
当前项 颜色/下划线 aria-current="page"/"true"/"location" 面包屑、导航、目录末级
校验失败 红边红晕 aria-invalid="true" + 文字说明 表单
忙碌按钮 spinner + 文案 aria-busy="true"、必要时 disabled 登录、提交
禁用 降透明 disabled 或 aria-disabled="true" 按钮、输入
弹层 遮罩+面板 role="dialog" aria-modal="true" aria-labelledby 欢迎、对比工作台、查看器、搜索
瞬态提示 toast role="status" aria-live="polite" 保存/复制/提交结果

硬性要求:任何"加载/错误/保存结果"都必须有非视觉通道;任何切换按钮必须有 aria-pressed;任何弹层必须能 Esc 关闭且焦点可还原。


6. 动效与打印

6.1 reduced-motion

旧块 app.css:894-896(*{animation-duration:.01ms;transition-duration:.01ms})+ v2.1 块 1116-1123(更细):

@media (prefers-reduced-motion:reduce){
  html{scroll-behavior:auto!important}
  .cl-panel{animation:none!important}
  .cl-skeleton::after{display:none!important;animation:none!important}
  .cl-spinner{animation:none!important;border-color:...;border-top-color:var(--cl-brand)}
  .cl-btn:hover,.cl-start-card:hover,...{transition:none!important;transform:none!important}
}

规则:新增动画必须同时提供 reduced-motion 分支;不要用 !important 覆盖用户偏好之外的东西;加载指示在 reduced-motion 下改为静态颜色环或文案。

6.2 print

旧块 app.css:897-905 隐藏 .cl-top/.cl-side/.cl-drawer/.cl-dock/.cl-worktabs/.cl-mobilebar/.cl-viewer-foot 等;v2.1 追加 .cl-skip-link{display:none!important}(1125)。

打印验收:records/browse 打印时无导航/按钮噪声,表格不横向溢出,链接 URL 可见(可选)。


7. 命名与作用域规则

范围 前缀/文件 规则
全局 --cl-*、.cl-* 只在 app.css 定义;组件优先复用
首页 --hp-*、.hp-*(home.css) 只服务 index;颜色尽量映射 --cl-*
实验室 --rm-*、.rm-*(room.css) 需 .rm-body[data-room] 上下文;4 套 accent
对比 --cmp-*、.cmp-*(compare*.css) .cmp-overlay 内暗色;页面级补充用 compare-bio.css/compare-data.css
资料库 .bd-*(bio-databases.css) 无独立令牌,复用 --cl-*
IDE 无前缀(ide.css) 独立令牌镜像;不得被其他页面引用

补充:

  • 新页面必须加 data-page 或页面级 class(如 .hp-page、.rm-body)作为作用域根,禁止裸标签选择器污染全局。
  • 组件类用"块-元素"式命名(.cl-btn、.cl-btn.sm),状态用属性选择器([aria-pressed])而不是新类。
  • 版本参数:改 CSS/JS 必须提升 html 引用里的 ?v=N(如 ide.css?v=20、compare.css?v=2),避免缓存混用。
  • 禁止在 HTML 里写内联颜色/字号(现存 404.html、records.html 的内联样式应逐步迁移)。

8. 组件使用示例(整页最小骨架)

<!doctype html>
<html lang="zh-CN" data-theme="light">
<head>
  <meta charset="utf-8">
  <meta name="viewport" content="width=device-width, initial-scale=1">
  <title>示例页 · CloudLab 云实验室</title>
  <link rel="stylesheet" href="/app/app.css">
  <link rel="stylesheet" href="/app/room.css">
</head>
<body class="rm-body" data-room="bio">
  <a class="cl-skip-link" href="#main-content">跳到主内容</a>
  <header class="rm-top">...</header>
  <main id="main-content" tabindex="-1">
    <div class="cl-toolbar">
      <button class="cl-btn sm" type="button" aria-pressed="true">全部</button>
      <button class="cl-btn sm" type="button" aria-pressed="false">只看失败</button>
    </div>
    <div class="cl-empty">
      <b>还没有记录</b>
      <p>运行一次实验后,记录会出现在这里。</p>
    </div>
  </main>
  <div class="cl-toast-box" aria-live="polite" aria-atomic="true"></div>
  <script src="/app/shell.js" defer></script>
</body>
</html>

9. 变更流程与验收

9.1 变更流程

  1. 提案:说明是"新增令牌/组件"还是"迁移旧组件";迁移必须列出影响页面。
  2. 令牌:只允许在 app.css :root 增加;深色必须同时给覆盖值;命名 --cl-<语义>,不复用颜色名(不要 --cl-teal-2)。
  3. 组件:优先加到 v2.1 附加段(app.css:976 之后),不修改既有规则;页面专属放页面 CSS。
  4. 版本:改文件即 bump ?v=;改 app.css 需评估 13 页(ide 除外)。
  5. 验收:跑 python3 tests/ui_invariants.py;人工做浅/深色、1440/390、键盘、reduced-motion 四项检查。
  6. 记录:更新本文与 UX-AUDIT.md 的对应条目;品牌色/字体变更走 BRAND-GUIDE.md 审批。

9.2 验收清单(每个 PR 自检)

  • 没有新增 #hex(令牌定义除外)。
  • 没有新增 <12px 的正文字号;辅助字号 ≥10.5px,且全站有意义 <10px 为 0。
  • 所有交互元素键盘可达,:focus-visible 可见。
  • 加载/空/错误三态齐全,错误可重试。
  • 切换类控件有 aria-pressed,当前项有 aria-current。
  • 弹层有 dialog 语义、Esc、焦点还原。
  • reduced-motion 下动画停止/降级。
  • 浅色/深色、1440/390 无溢出、无对比失败。
  • 更新了 ?v= 与相关文档。

10. 最后核对命令

cd /root/dsh_workspace/cloudlab-app

# 令牌与深色覆盖
sed -n '1,60p' app/app.css

# v2.1 段(字号/焦点/skip/状态组件/动效/打印)
sed -n '976,1129p' app/app.css

# v2.2 对比度状态修复
sed -n '1131,1136p' app/app.css

# 组件定义
grep -n '^\.cl-btn\|^\.cl-field\|^\.cl-input\|^\.cl-table\|^\.cl-toast\|^\.cl-empty\|^\.cl-error\|^\.cl-loading\|^\.cl-skeleton' app/app.css

# 页面级令牌与作用域
grep -n '^:root\|--hp-\|--rm-\|--cmp-' app/home.css app/room.css app/compare.css

# 焦点覆盖缺口
for f in app/app.css app/room.css app/compare.css app/compare-data.css app/compare-bio.css app/home.css app/bio-databases.css app/ide.css; do
  printf '%-28s fv=%s outline_none=%s\n' "$f" "$(grep -c ':focus-visible' $f)" "$(grep -c 'outline:none' $f)"
done

# 13 页 skip/主题
grep -c 'cl-skip-link' app/*.html
grep -n 'data-theme=' app/*.html | head -20

# 像素采样(9 页 × 1440/390)
node tests/contrast_gradient.mjs --base http://127.0.0.1:8099 --json /tmp/gradient.json

# 静态验收
python3 tests/ui_invariants.py --skip-browser

2.8 S5:渐变页对比度像素采样与资料库文字修复(2026-11-20)

  • 新增 tests/contrast_gradient.mjs(纯 Node + CDP + 无头 Chromium):隐藏文字后整页截图,对每个 Range 文本矩形逐像素合成,取最差 WCAG 比值;正文 4.5:1、大文本 3:1。
  • tests/ui_invariants.py 在合成采样 checked<=0 时优先使用像素结果:0 违规 PASS、有违规 FAIL、无结果保持 SKIP;Node 缺失时不伪造通过。
  • 结果:340 项 PASS 340 / FAIL 0 / SKIP 0;本地 4 个整页 checked 183 处、0 违规;线上真实目录 checked 940 处、0 违规;正文最低 4.58(index)/4.57(本地 bio-databases)/4.47(线上 bio-databases 390),大文本最低 4.47(阈值 3)。
  • .bd-empty 文字 var(--cl-mut) → var(--cl-sub):390 空态 4.03:1 → 4.76:1,1440 4.55 → 5.39。
  • 线上首采发现真实目录 11 处违规(8 个表格文件名 4.03:1、3 个链接 4.37:1):.bd-table .mono → var(--cl-sub),.bd-table a、.bd-file、.bd-card-foot a → var(--cl-brand-ink),hover 保持同色只加下划线;复采为 0。
  • 缓存版本 bio-databases.css?v=7;未改渐变/主色/字体/布局。
  • 仍为未验证:818 处页面内部渐变/透明度跳过、跨浏览器/真机、多 DPR、hover/focus/登录后界面。

2.9 S6:全站渐变像素覆盖与四处文字色修复(2026-11-20)

  • 像素采样器 tests/contrast_gradient.mjs 的默认页面从 2 页扩到 9 页(index、lab、bio、chem、data、bio-databases、compare、compare-bio、compare-data),1440/390 共 18 个页面/宽度;采样算法不变。
  • tests/ui_invariants.py 的 _check_runtime_contrast 改为合成与像素同时判定:合成 checked>0 时像素违规也 FAIL;采样超时 120 → 300 秒。340 项总数不变。
  • 四处文字色:.cmp-board-foot #5f7f74 → #86a99c;.bio-mini-empty var(--cl-mut) → var(--cl-ink-2);.data-table td 增加 var(--cl-ink-2);.cl-3d-hint var(--cl-mut) → var(--cl-ink-2)。
  • 缓存版本:app.css?v=5、compare.css?v=6、compare-bio.css?v=5、compare-data.css?v=7;chrome.css?v=3、ide.css?v=22 未改。
  • 结果:340 项 PASS 340 / FAIL 0 / SKIP 0;像素 18 个页面/宽度、checked 642、0 违规、skipped 162;正文最低 4.57、大文本最低 4.47;静态 <10px 仍为 0。
  • 线上复核(2026-11-20T18:35Z):14/14 URL 200;线上真实目录像素 checked 1,398、0 违规、211 skipped;线上 smoke 26 次 0 错误/0 溢出。
  • 仍未验证:818 处合成 skip、hover/focus/折叠/登录后、跨浏览器/真机/多 DPR、canvas/伪元素/Shadow DOM。详见 UI-SPRINT6-PLAN.md 与 UI-VERIFICATION.md 第 13 节。

2.10 S7:运行时键盘焦点可见性(2026-11-20)

  • 新增 tests/focus_keyboard.mjs:Node + 无头 Chromium CDP,对 13 页 × 1440/390 按 Tab 采样 activeElement,检查自身 outline/box-shadow 与显式搜索容器 focus-within 环;退出码 0/1/2,JSON 不含机器绝对路径。
  • 修复两个真实缺陷:records 的 #rec-search 与 bio-databases 的 #bd-q 自身 outline:none 且容器无焦点环。只在 app/room.css 与 app/bio-databases.css 末尾新增 2px var(--cl-brand-2) 焦点环;room.css?v=6(9 页)、bio-databases.css?v=8。
  • tests/ui_invariants.py 新增 _run_focus_probe/_focus_payload/_check_focus_keyboard,检查项 340 → 341;Node 缺失 SKIP、基础设施失败 WARN、有不可见焦点 FAIL。
  • 结果:341 项 PASS 341 / FAIL 0 / WARN 0 / SKIP 0;键盘 26 次加载、599 个停留点(repo 598、线上 652,均 0 不可见);对比度与静态字号口径不变。
  • 未验证:跨浏览器/真机/多 DPR、焦点顺序语义、焦点陷阱完整性、登录后深层视图。详见 UI-SPRINT7-PLAN.md 与 UI-VERIFICATION.md 第 14 节。

2.11 S8:全站元信息统一(2026-11-20)

  • 13 个页面的可索引元信息齐全:description 13/13(index 原有,12 个页面新增);canonical 12/13(404 为 noindex,不声明);Open Graph 12/13(每页 6 项);Twitter Card 12/13(每页 3 项)。
  • canonical 统一为 https://lab.hdtime.space/app/ 与 /app/<page>.html;og:url 与 canonical 一致,og:title/twitter:title 与 title 一致,og:description/twitter:description 使用页面 description。
  • tests/ui_invariants.py 新增 check_metadata(),每页 1 条“元信息完整性”检查;341 → 354 项。404 例外:只要求 description + robots=noindex,禁止 canonical/OG/Twitter。
  • 不新增 og:image/twitter:image,不添加 hreflang,不改 CSS/DOM/JS/API/品牌资产;只检查源码,不验证社交平台抓取或搜索引擎收录。
  • 像素采样加固:contrast_gradient.mjs 首轮违规时单次重拍(800ms),ui_invariants.py 汇总 capture_retries;重拍后仍违规照常 FAIL,避免把首帧漏绘误报为样式缺陷;本轮未改页面 CSS。
  • 焦点采样加固:focus_keyboard.mjs 对 focus-visible 但无指示器的目标等待 220ms 复测一次;仍无指示器才判失败,避免把 .cl-btn 的 transition 过渡途中误报为焦点环缺失;本轮未改页面 CSS。
  • 结果:2026-11-20T20:31:53Z 354 项 PASS 354 / FAIL 0 / WARN 0 / SKIP 0;元信息 13/13 PASS;既有检查无回退;像素采样 capture_retries 为空;键盘焦点 599 停留点 0 不可见;线上 14/14 URL 200、14/14 HTML SHA 一致、smoke 26 次 0 错误、线上焦点 655 停留点 0 不可见。详见 UI-SPRINT8-PLAN.md 与 UI-VERIFICATION.md 第 15 节。

2.12 S9:320px reflow 与提示条/表头对比度(2026-11-20)

  • 布局门禁从 1440/390 扩到 1440/390/320:13 页 × 3 宽度 = 39 次测量,0 横向溢出;320 页头高度 58px、品牌标记 30px、动作控件 ≥34px。
  • 极窄屏规则只加在 app/chrome.css:@media (max-width:360px) 下 body .rm-brand > span:last-child 隐藏,保留 30×30 标记、链接与 aria-label;390 及以上完全不变。
  • app/app.css 的 .cl-3d-hint 改为白底 --cl-surface、1px --cl-line-2、999px 圆角、10.5px、--cl-ink-2 的提示条;.cl-viewer3d > .cl-3d-hint 绝对定位右下、z-index 3、pointer-events:none。实测 2.02 → 10.74。
  • app/bio-databases.css 的 .bd-table th 用 --cl-sub,320 品牌渐变上 4.03 → 4.76。
  • tests/ui_invariants.py 与 tests/contrast_gradient.mjs 采集前隐藏首次访问 onboarding 弹层(只改测试 DOM,不改页面 CSS),避免半透明遮罩被误当文字背景。
  • 结果:2026-11-20T21:25:06Z 本地 422 项 PASS 422 / FAIL 0 / WARN 0 / SKIP 0;仓库副本 2026-11-20T22:03:42Z 同为 422 项 0 FAIL;渐变 27 组 863 处 0 违规;键盘焦点本地 599、仓库副本 600 停留点,均 0 不可见;静态 <10px 0。详见 UI-SPRINT9-PLAN.md 与 UI-VERIFICATION.md 第 16 节。
  • 线上复核(2026-11-20T22:05:34Z 部署):14/14 URL 200、16/16 关键资源 SHA 一致、smoke 26 次 0 错误/0 溢出、键盘焦点 657 停留点 0 不可见、渐变 938 处 0 违规、320 data documentElement 320/320。
  • Sprint 10 已把 ≤480 的 8 个 room 页改为两行 76px,320/390 面包屑完整(292/292、362/362);onboarding 弹层自身仍未纳入对比度检查。

2.13 S10:≤480px 两行 room 页头与对比工作台吸顶(2026-11-20)

  • 断点:@media (max-width:480px) 时 bio/chem/data/records/browse/compare/compare-bio/compare-data 八个 room 页页头改为两行,内容高 75px + 1px 底边 = 76px;481px 起恢复单行 58px。
  • 第一行:品牌与 5 个动作控件;第二行:.rm-crumbs 独占整行,宽 100%、高 20px、字号 11.5px,末级 b 允许收缩。品牌字标只在 ≤380px 隐藏,保留 30×30 标记、首页链接与 aria-label。
  • 吸顶偏移:.rm-stations 在窄屏为 76px;对比工作台 .cmp-mobile-bar 在 ≤760px 为 top:0、761–900px 为 top:64px。
  • 缓存版本:13 个 HTML 的 chrome.css?v=5;compare 三页 compare.css?v=7。
  • 验证器:320/390 的 8 个 room 页期望 76px,新增 16 条面包屑完整可见检查,422 → 438 项;smoke 增加 320×844 视口,26 → 39 次加载。
  • 结果:本地 2026-11-20T23:01:13Z 438 项 PASS 438 / 0 FAIL / 0 SKIP;仓库副本 23:20:39Z 438 项 0 FAIL;线上 390/320 页头 16/16 PASS,crumb 362/362 与 292/292,14/14 URL 200、15/15 SHA 一致、smoke 39 次 0 错误。
  • 未验证:481px 边界只在本地探针;320 不进入键盘焦点门禁;仅 Chromium 单 DPR。详见 UI-SPRINT10-PLAN.md、UI-VERIFICATION.md 第 17 节。

11. 已知例外与待办

  1. IDE 自建令牌与 app.css 重复,必须双改(app/ide.css:1-27、app/app.css)。
  2. 对比工作台固定暗色,不跟随 data-theme;这是有意设计,但需要保证任意入口进入时视觉一致。
  3. 首页 --hp-bg 与主站 --cl-bg 不同是品牌决策,不要"顺手统一"。
  4. 共享组件与页面级字号已完成 S2 集成收敛(见 2.4/2.5):有意义文本 <10px 为 0,<12px 总量 966/946(预算 ≤1200);剩余为 10.5–11.8px 元信息,预算内保留。
    1. 对比度已由验证器覆盖(S3-1 / S5 / S6 / S9 / S10):438 项中 438 PASS / 0 FAIL / 0 SKIP;像素采样已扩到 9 页 × 1440/390/320(本地 27 组 863 处 0 违规、336 skip,正文最低 4.56、大文本 4.47;线上实测 938 处 0 违规(52 skip)、焦点 657 停留点 0 不可见),合成对比度仍有 1,214 处页面内部跳过未验证;app.css 历史失败已修(404 大字、面包屑分隔符)。room.css:23 的 .rm-crumbs .sep 已改为 var(--cl-sub),app.css 临时覆盖已删除。Sprint 7 新增键盘焦点检查(26 次加载、599 个 Tab 停留点;线上真实数据 652;均 0 不可见)。 Sprint 8 新增 13 条元信息完整性检查(description 13/13,canonical/OG/Twitter 12/13,404 为 noindex 例外)。 Sprint 9 将布局与渐变采样扩到 320,422 项全 PASS;Sprint 10 起 ≤480 的 8 个 room 页改为两行 76px,320/390 面包屑完整,验证器 438 项。
  1. 静态检查器不覆盖焦点顺序/交互/视觉回归;Sprint 7 新增真实 Tab 焦点可见性运行时探针(Chromium 单 DPR、初始可见态),仍不覆盖焦点顺序语义、焦点陷阱完整性与跨浏览器;UI 变更仍需人工走查。
  2. IDE skip link 由 ide.css:54-59 单独实现,与 app.css 的 .cl-skip-link 行为一致但重复;Sprint 4 未改,Sprint 5 仍未改;IDE 登录页的 #auth 特例由 ide.js 处理。
  3. 全站静态 <10px 声明为 0(Sprint 4 清零 IDE 189 条);10px 仅限 2.6 白名单中的静态示意/元信息。
  4. 元信息检查只验证 HTML 源码字段与取值一致性,不验证社交平台抓取、og:image、搜索引擎收录或 sitemap;og:image/twitter:image 仍需品牌提供正式 1200×630 资产。