更新日志

移动端的变更记录，构建时从仓库根 CHANGELOG.md 提取（标题含「Mobile / 移动端」的段落），按时间倒序 —— 不手抄，避免站点与仓库两处说法不一致。完整历史（含 PC 侧）在仓库的 CHANGELOG.md。

移动端相关变更

图标系统（PC 5 端 + 移动端 6 端 + 全量图标库 + 预览页）

起因：用户要求「图标组件参考 TDesign / Element 等主流组件库，看他们的 icon 是怎么专门设计的、

设计内容有哪些，覆盖他们全部拥有的 icon 图标和功能」。

落地：2576 个图标（TDesign 线性 1334 + 面性 1020 + Element Plus 293，均 MIT），

11 个端实现全部接通，新增 5 个构建/门禁工具与 1 个图标预览页。

冻结规格：.design_library/kole-ui/icons/ICON-SPEC.md。

#### 新增：图标数据管线（离线可复现，上游校验和钉死）

tools/fetch-icon-sources.mjs — 拉取并归一化上游 SVG → sources.json。

逐包校验 sha256（防「某天图标悄悄变了」）；纯函数可单独 import（无副作用）。

tools/build-icons.mjs — 编译出 manifest.json（清单）/ registry.json（渲染数据）/

viewbox.js（viewBox 例外表）/ core.js（内联运行时）/ ATTRIBUTION.md（MIT 归属，分发必带）。

tools/build-icon-aliases.mjs — 别名层，让 Element UI 全部 282 个历史图标名与

移动端既有 9 个字形名都能落到真实图标（旧调用点零破坏）。

tools/inject-icon-table.mjs — 把 core 表注入 11 个端实现的标记块，杜绝「11 份手抄表必然漂移」。
tools/verify-icons.mjs — 11 条静态断言（产物一致 / 无 view-box 残留 / 描边全 1.5 /

core 可渲染 / 别名不遮蔽 / 各端都能查到名 / 分组覆盖率 / 路径数字与源逐值一致）。

#### 修正：两个上游缺陷在构建期抹平（此处是本仓库的增量，不是照抄）

1. view-box 拼写错误：TDesign 全部 2356 个 SVG 把属性写成 view-box（无效属性，

浏览器忽略 → 图标按默认视口缩放）。构建期两种拼写都读，产物统一写回规范的 viewBox。

2. 描边宽度 2 → 1.5：上游为 stroke-width="2"（24 网格），本仓库规范

（组件1.txt「图标规范：线性图标，描边1.5px，尺寸16/20/24px」）要求 1.5，构建期归一。

另丢弃 fill="transparent" 命中区路径（那是热区不是视觉内容）。

#### 修正：自测发现的数据损坏缺陷（构建期把坐标改错）

现象：归一化把路径数字四舍五入到 2 位小数，看似无害；但 SVG path 允许「隐式分隔」——

q-13.005.48-22.5 是三个数（-13.005、.48、-22.5，靠 - 和 . 当分隔符）。

把 -13.005 舍成 -13 后，后面的 .48 粘成 -13.48 —— 那是另一个坐标，

图形画错且不报任何错。实测踩到 Element Plus 的 quartz-watch（靠浏览器控制台才发现）。

修法：原本有小数位的数字，输出至少保留 1 位小数（-13.005 → -13.0），

隐式相连的 .48 不可能再被吸收；并在 optimizePath 内复核数字序列，不一致就原样返回。

防复发：新增门禁断言 V8「路径数字与源逐值一致」，比对全部 2576 个图标。

已做变异测试：把该 bug 重新注入 → V8 当场 FAIL（数字个数 461 ≠ 源 462），判据有区分力。

代价：registry.json 707KB（修前 677KB，+30KB 换正确性）。

#### 修正：非 <path> 图形被静默丢弃（覆盖率审计发现）

现象：解析器只认 <path d>，而上游有 36 个文件用 <circle cx cy r> / <ellipse>

表达图形（TDesign 的 circle / round / brightness / image 等）。这些图形被静默丢掉 ——

图标页面上"渲染成功"却是空的，构建与回归都不报错。TDesign 的 circle 与 round 两个图标

因此整个消失，是覆盖率审计（对三个参考库逐名比对）才暴露的。

修法：解析器同时处理 <path> / <circle> / <ellipse>，把圆与椭圆等价换算成

path 的两段 arc（M cx cy-r A r r 0 1 1 cx cy+r A r r 0 1 1 cx cy-r Z）。

结果：图标数 2574 → 2576；对三家参考库的覆盖率现为

TDesign 2356/2356、Element Plus 293/293（各 100%）、Element UI 280/282（余 2 个是解析碎片名）。

校验：两个恢复的图标在浏览器实测有真实几何（path 长度 63 / 44，分别对应 r=10 与 r=7 的圆）。

#### 分层与体积（按实测决定，不是拍脑袋）

core 151 个内联（core.js 35KB），standard 1989 / extended 434 按需加载。
为何不全内联：全量 670KB，内联等于给每一页都加 670KB，直接违背 ROADMAP 的性能预算精神。

#### 组件 API（PC 5 端 + 移动端 6 端，语义统一）

props：name / size（关键字 small|default|large|xlarge 或任意 CSS 长度，对齐 TDesign 双模式）/

向后兼容：PC 既有 icon prop（字形字符，默认 '★'）与移动端既有 9 名字形表全部保留，name 优先。
无障碍：label 有值 → role="img" + aria-label，无值 → aria-hidden；

spin 在 prefers-reduced-motion: reduce 下停转；语义色对比度 ≥ 3:1（实测 5.10–5.87:1）。

viewBox 按「路径串 → 网格」反查而非按名：别名指向的 1024 网格图标若按名查会取错网格

（实测影响 160 个名字，会导致图标拉伸变形）。

#### 新增：图标预览页 site/icon-preview.html

规范 组件5.txt「图标预览 IconPreview：展示系统所有图标 / 网格布局，支持搜索 /

点击图标复制名称或代码 / 可调整图标大小」声明已久但从未实现。本次补齐：

2576 图标网格、搜索、点击复制名称、Shift+点击复制内联 SVG、四档尺寸切换、仅线性过滤；

分两段加载（索引 51KB 先出骨架，路径数据按需）；

入口挂在图标组件页代码条 footer，i18n 双语（图标预览 / Icon gallery）。

#### 已知未覆盖 / 遗留

移动端 uni-app 端用 CSS mask（data-URI SVG） 承载字形（小程序无 DOM、无内联 SVG）。

H5 目标已实测；mp-weixin / app-plus 的遮罩渲染未在真机验证，已登记进契约 unknowns。

verify-emits-parse.mjs 的文件数期望值陈旧（158，应为 103×2=206）—— 本次之前就存在

（git show HEAD: 确认），已登记为 ROADMAP S8-P1。

verify-cross-platform.mjs 把注入的图标数据表误判为组件类名（540 条里 533 条是噪声）——

已登记为 ROADMAP S8-P2（判据不放宽，让门禁学会跳过数据块）。

组件5.txt 声明的 47 个工具/模板组件里 46 个仍未实现（本次只补了 IconPreview）——

已登记为 ROADMAP S8-P3，含「走 frameworks/ 正式组件还是 site/ 工具页」的决策点。

Mobile · 顶栏对齐 PC + 平台入口去重（移动端站导航栏改造）

起因：用户要求「移动端组件的导航栏参考 PC 端组件导航栏优化（上面跳转 PC 和移动的下拉框也重复了）」。

实测确认两条问题，逐项修掉。

去重：平台切换从顶栏移除。移动端站顶栏原有一个 [PC 端] [移动端] 分段胶囊，与同一页左栏的

「平台」组指向同一跳转（实测 DOM：a.mp-item 与 a.m-side-link.m-side-platform 的 href 均为

../index.html）—— 同一件事两处入口。PC 站顶栏从来没有这个控件（只有左栏一处），

故删顶栏那份，两端现在都是左栏唯一入口。改动同时断言「删的是重复的那个，不是删光」：

verify-mobile-docs 的 E7 从「断言顶栏有平台切换」改为「断言左栏有平台入口」。

顶栏逐项对齐 PC（此前只有结构同名，控件实现不同源）：
高度 56px → 60px；内容加 1180px 居中容器（.m-top-inner，与 .m-body 同宽，

logo 与左栏左边缘对齐；此前内容铺满视口、与下方内容左边缘错位）。

激活项补 2px 底部品牌指示条（.m-nav a.active::after，PC .topnav a.active::after 同款）；

此前只有文字变色。

版本角标 → 可点版本下拉：<span class="m-ver"> 换成 #m-ver-trigger + #m-ver-menu，

清单从部署根 versions.json / site/versions.json 两份按序取（不并行 —— 快照页那份必然 404，

并行会把 404 记进控制台，而站点门禁的零控制台错误是硬断言）；拿不到清单时

data-single="1" 退回不可点角标（与 PC 同一语义）。路径校验只放行 ".." 与 x.y.z，防清单把人带去外站。

主题触发器补 三态图标（月亮 / 太阳 / 显示器，PC .theme-icon 同款）：显式选择时按时态给图标，

自动模式恒为显示器图标；此前只有文字标签。

零运行时依赖不变：新增的版本/主题逻辑是构建期内联脚本（COPY_SCRIPT），不引包。
顺手修掉一处过期硬编码：移动端站文案里的 PC 组件数写死为「79」，

而 S6-P21 组件族参数化后 PC 索引已是 103（实测 components/index.json）。改为构建期从 PC 索引实测读取

（模板占位符由 build-mobile.mjs 灌入），拿不到索引时退回中性表述而非编造数字。

涉及：总览页、FAQ、平台与端页的正文与覆盖矩阵、以及 dist/mobile/README.md 与 manifest 的 isolatedFrom。

验收（原样）：

node tools/verify-mobile-docs.mjs        → [OK] 12 条断言 · 53 页（E7 判据已同步去重）
REG_BASE=http://127.0.0.1:3457 node tools/verify-mobile-site.mjs → [OK] 263 条断言 · 50 页 · 控制台错误 0 · 演示帧 281/281
REG_BASE=http://127.0.0.1:3457 node tools/run-mobile-regression.mjs → passRate 100% | pages 47 (all-pass 47) | assertions 804/804 | N/A 10
REG_BASE=http://127.0.0.1:3457 node tools/run-regression.mjs        → passRate 100% | pages 103 (all-pass 103) | assertions 1405/1405 | N/A 50
PC 与移动端回归各连跑 8 次，结果逐次一致（40/40 全绿）

浏览器实测（Playwright，1440px）：顶栏 60px / 内容容器实测 1180px / 激活项 ::after 实测

2px rgb(47, 84, 235) / 顶栏内 .m-platform 计数 0 / 版本下拉实测 1 个选项且 data-single="0" /

切夜间后图标 m-icon-sun:block 且 html.kole-dark 生效；320–768px 四档无横向溢出、零控制台错误。

四道移动端门禁全绿：隔离 31 条 / uni-app 9 条 × 50 SFC / 文档 12 条 · 53 页 / 站点 263 条 · 50 页。

Mobile · 批次 E/F：移动端组件 36 → 47（两批子 agent 并行 + 新增「磁盘↔索引」双向门禁）

继续 /son 派活推进 TDesign 清单覆盖。批次 E（typography / segmented / sticky / overlay / popover / message）

与批次 F（picker / cascader / colorpicker / upload / table）并行产出 11 个组件 × 8 文件 = 88 文件，

规格 §37–§47。索引 36 → 47，实现 216 → 282，移动端回归 597 → 804 条断言。

给每个组件预分配规格编号（§37–§47）：上一轮两个子 agent 并存时存在编号撞号风险（撞号会被合并脚本按幂等规则整节跳过），

本轮在派单里逐组件指定编号，合并时零冲突、规格 §1–47 连续。

新增反向门禁 B1b（两个子 agent 独立报的同一条缺口）：verify-mobile-isolation.mjs 原先只查

「索引里的组件有没有实现文件」，不查「磁盘上的实现文件有没有进索引」——于是子 agent 产出的组件在合并前

完全不被任何门禁覆盖（不在索引里 = 不被检查），属静默缺口。现补反向断言：磁盘前缀集合必须等于索引前缀集合，

不一致直接报「未登记：X, Y（跑 node tools/merge-mobile-batch.mjs 合并）」。断言数 30 → 31。

修掉两处探针误判（都是工具侧，不是内容缺陷）：
verify-mobile-site.mjs 的总览页在 47 个卡片时只渲染 43 个 —— 预览帧 loading="lazy"，

一次 scrollTo 到底会跳过中间帧。改为逐段滚动（每 800px 一次）后再判定，实测 281/281。

同一脚本把收集器的 net::ERR_ABORTED 记为控制台错误 —— 那是 _collect.html 在帧装载完成后

主动 removeAttribute('src') 释放帧造成的在途请求中断，是设计行为。判据改为忽略 ERR_ABORTED，

其余（404 / ERR_INVALID_URL 等）仍然计错。

子 agent 自修的真实缺陷（都带证据）：Sticky 的 is-stuck 判定在默认偏移下滚动 0 就已贴合（改为与容器 padding box + 偏移量比较，含 1px 边框补偿）；

Message.jsx 把 onClose 写进 useEffect 依赖 → 宿主传内联箭头函数时计时器永远不到点（回调移到 useRef）；

Sticky/Message 演示页缺实际执行的监听器致 data-behavior 静默失效；

Table 可点行不可聚焦（真实引擎报 matrix:keyboard-reachable）→ 补 tabindex/role/aria-selected/Enter 键路径；

ColorPicker 的色板 hex 写在行内 style 被 no-hardcode-hex 判据扫到 → 改走行内自定义属性（CSS 零 hex，色值只存数据层）。

规划偏差（子 agent 主动对齐既有约定）：disabled 从变体维度降为状态类 —— 全仓 47 份契约无一把它当变体，

同意；picker/cascader/segmented 的初判分类经我核对后修正为 input/navigation（PC 同源六分类口径）。

验收（原样）：

node tools/verify-mobile-isolation.mjs   → [OK] 31 条断言（含新增 B1b 反向断言）
node tools/verify-uniapp.mjs             → [OK] 9 条断言 · 50 个 SFC
node tools/verify-mobile-docs.mjs        → [OK] 12 条断言 · 53 页
REG_BASE=… verify-mobile-site.mjs        → [OK] 263 条断言 · 50 页（0 控制台错误、演示帧 281/281）
node tools/run-mobile-regression.mjs     → 100% | 804/804 | 47/47 页 | N/A 10 | 0 超时
node tools/run-regression.mjs            → 100% | 1405/1405 | 103/103 页（PC 侧未被污染）
node tools/pack-deploy.mjs --tar         → OK（282 实现 / 47 文档页 / 47 测试页）

部署：暂存树哈希与本地一致（936742e98d061a30）→ 替换重建 → 五项验收全过、11 个新增组件页全 200、容器 0 error；

公网 data.mobile.json 报 47 个组件。

剩余 23 个（已写进 ROADMAP S7-P23）：config-provider / Fab / BackTop / Drawer / Indexes / SideBar / Tabs /

Calendar / DateTimePicker / TreeSelect / CountDown / Empty / Footer / Image / ImageViewer / QRCode / Result /

Skeleton / Swiper / Watermark / DropdownMenu / Guide / PullDownRefresh。

Mobile · 批次推进：移动端组件 5 → 36（三批子 agent + 合并脚本 + 修行为断言静默缺口）

起因：用户要求「参考 TDesign 移动端组件清单，按批次补全缺的组件」，随后 /son（派子 agent）、/agi（全自主）。

参考清单 67 个组件，本仓库已覆盖 36 个（含此前的 18 个）；流程按 PLATFORMS.md §四「六步」固化。

三批子 agent 产出 18 个组件（每个 = 6 端实现 + 规格片段 + 契约 = 8 文件，共 144 文件）：
批次 A：mobile-icon / mobile-layout / mobile-link / mobile-loading
批次 B：mobile-avatar / mobile-list / mobile-collapse / mobile-progress
批次 C：mobile-input / mobile-search / mobile-switch / mobile-stepper / mobile-textarea
批次 D：mobile-form / mobile-radio / mobile-checkbox / mobile-slider / mobile-rate

规格从 §19 连续到 §36（共 36 节）；索引 18 → 36 个组件，实现文件 108 → 216。

新增可复用的合并脚本 tools/merge-mobile-batch.mjs：子 agent 一律不写 index.json（避免并发写同一文件），

由主 agent 用该脚本统一合并 —— 它做三件事且幂等：① 按编号把 spec/parts/*.md 拼进规格原文（同编号则只归档不拼接）；

② 把 frameworks-mobile/ 里未登记的组件（校验 6 端文件齐全 + 契约存在）写进索引；③ 已拼接的片段归档到 parts/_merged/。

修掉一个静默缺口（子 agent 复核时发现，价值最高的一条）：tests/mobile/_behaviors.js 的 PILOTS 是硬编码白名单

（只有最初 5 个组件），于是批次新增组件即使在演示页写了 data-behavior，引擎也直接 return [] ——

行为断言静默不跑，断言总数悄悄少一截。修法：作用范围改为「演示页里真的写了 [data-behavior] 的组件」

∪ 兜底名单，由 build-mobile.mjs 在生成测试页时把派生结果注入 window.__koleBehaviorSlugs。

实测：行为断言覆盖 5 → 31 个组件，断言条数 8 → 34 条（全部 pass）。

修掉一处判据过窄（上一轮遗留）：pack-deploy.mjs 的「frameworks-mobile 实现文件数」按索引动态算，

但打包时批次文件已在磁盘而尚未合并进索引 → 断言误报。现在按「索引组件数 × 端数」与磁盘实际双向核对，

不一致时直接指出差额（本次实测：156 vs 186，正是未合并的批次 C）。

修掉一处探针误判：verify-mobile-site.mjs 统计总览页演示帧时只看到 20/26 ——

预览帧是 loading="lazy"，视口外的帧不会加载（浏览器行为，不是缺陷）。判据改为先滚到底再判定，

实测 26/26、现在 36/36 全部正常渲染。

子 agent 自修的真实缺陷（都在报告里给了证据）：<button> 嵌在 <label> 里（非法嵌套）；

Stepper 根 overflow:hidden 裁掉小尺寸档的热区外扩（命中测试证实）；同一状态块挂两条 data-behavior 互相污染；

Textarea 计数示例是死数据；Slider 根元素 cursor:pointer 让数值文案被判「鼠标专用交互」（真实引擎报的 matrix:keyboard-reachable）。

验收（原样）：

node tools/verify-mobile-isolation.mjs   → [OK] 30 条断言
node tools/verify-uniapp.mjs             → [OK] 9 条断言 · 39 个 SFC
node tools/verify-mobile-docs.mjs        → [OK] 12 条断言 · 42 页（站内链接全可解析）
REG_BASE=… verify-mobile-site.mjs        → [OK] 208 条断言 · 39 页（0 控制台错误、演示帧 220/220、320–768px 无溢出）
node tools/run-mobile-regression.mjs     → 100% | 597/597 | 36/36 页 | N/A 10 | 0 超时
node tools/run-regression.mjs            → 100% | 1405/1405 | 103/103 页（PC 侧未被污染）
node tools/pack-deploy.mjs --tar         → OK（2349 文件 / 36 组件 × 6 端 = 216 实现 / 文档页 36 / 测试页 36）

部署：暂存树哈希与本地一致（719d66f2fce6875a）→ 替换重建 → 服务器端五项验收全过、容器 0 error；

公网 data.mobile.json 报 36 个组件，抽查 8 个新增组件页全 200。

Mobile · 移动端组件第二批收尾（弹出层系 + 展示系 + 输入系）：Toast / Dialog / Grid / Steps / NoticeBar / NumberKeyboard / DatePicker（索引 11 → 18）

起因：按批次继续开工，把 ROADMAP S7-P23 的剩余 7 个组件做完 —— 规格 §12~§18 本轮新写

（契约的唯一授权来源必须先于实现），再按 PLATFORMS.md §四六步流程落地为 6 端实现。

索引 11 → 18，frameworks-mobile/ 66 → 108 个文件（18 × 6 端）。

七个新组件（规格小节 → slug / 前缀）：
轻提示 Toast（§12 → mobile-toast）：tone 五语气 + position 三位置 + mask；

容器 role="status" + aria-live="polite"（结果朗读一次不反复打断）；tone=loading 时图标旋转并标 aria-busy。

对话框 Dialog（§13 → mobile-dialog）：variant = confirm（两按钮等宽）/ alert（单按钮铺满）+ tone = danger + round；

closeOnMask 可关；role="dialog" + aria-modal + aria-labelledby；按钮热区 ≥44px。

宫格 Grid（§14 → mobile-grid）：columns 2/3/4 + border + square；可点格子是原生 button（整块热区 + 键盘可达），

static 格子是 div 且不绑点击 —— 直接规避「鼠标专用交互」这类无障碍缺口；按下反馈一律 :active（触屏没有悬停）。

步骤条 Steps（§15 → mobile-steps）：direction 横/纵 + status 四态；role="list" / role="listitem" + aria-current="step"；

状态不只靠颜色（进行中加粗、已完成用勾选字符、失败用感叹号）。

通知栏 NoticeBar（§16 → mobile-noticebar）：四种语气 + scrollable 跑马灯 + closable；

无障碍硬要求落地：prefers-reduced-motion: reduce 下停止滚动并改为换行显示；滚动内容不用 aria-live（反复朗读会干扰）。

数字键盘 NumberKeyboard（§17 → mobile-numberkeyboard）：type = number/digit + showDelete + showConfirm + confirmDisabled；

键盘不持有输入值 —— 只 emit 按键事件（数字键回传该字符 / 删除键回传 'delete' / 确认键回传 'confirm'），写入哪个输入框由宿主决定。

日期选择器 DatePicker（§18 → mobile-datepicker）：mode = date/month + round + closeOnMask；三列 role="listbox" / role="option" + aria-selected；

年份范围由宿主传入（years / months / days），不发明可用年份区间（契约 unknowns 已登记）。

配色零发明（全部既有令牌，脚本实测亮/暗两态）：Toast 深底 + 反色文字 15.78:1 / 15.00:1；

Dialog 卡片底 + 正文色 15.13:1 / 10.34:1；Grid / Steps / NoticeBar 沿用既有语义对（浅底 + 同族深字，均 ≥4.5:1）。

判据有效性用变异探针验证（5/5 当场捕获，不是「跑了绿灯」就算数）：

① 向 CSS 注入 #FF0000 → B3 报出文件与色值；② 契约加一个源码没有的 prop → E4 逐端报「源码里没有」；

③ 把有默认值的 prop 标成必传 → E4b 逐端报「应相反」；④ uni-app 端注入 document.querySelectorAll → U5 报出两条规则；

⑤ uni-app 端去掉全部 rpx → U9 报「未使用 rpx」。每个探针都当场还原并复跑确认绿灯。

过程中发现并修掉三处真问题：

① 契约 related 里写了裸名（toast / noticebar）而非真实 slug → E6c 逐条报「不存在」，已补 mobile- 前缀（5 处）；

② tools/pack-deploy.mjs 输出文案与 site/m/_design_template.html 里写死了组件数（前一批 8 个组件落地时漏改）

→ 分别改为读索引与构建期占位符注入；

③ Dialog 初版的圆角写在基础类上（round 变体于是无意义）→ 改为由 --round 类控制，契约 variantClasses 与 CSS 双向对上。

验收（原样）：

node tools/build-mobile.mjs              → 18 组件 × 6 端（data.mobile.json 412 KB）· 18 测试页 · 18 文档页 · dist/mobile 全端
node tools/verify-mobile-isolation.mjs   → [OK] 隔离门禁全部通过（30 条断言）— B1 18 × 6 端 108 文件 / B8 报告 18 = 索引 18
node tools/verify-uniapp.mjs             → [OK] uni-app 门禁全部通过（9 条断言 · 21 个 SFC）
node tools/verify-mobile-docs.mjs        → [OK] 文档完整性门禁全部通过（12 条断言 · 24 页）
REG_BASE=… verify-mobile-site.mjs        → [OK] 移动端站点全部通过（118 条断言 · 21 页；演示帧 101/101 正常，0 控制台错误）
REG_BASE=… node tools/run-mobile-regression.mjs → passRate 100% | pages 18 (all-pass 18) | assertions 270/270 | N/A 6
node tools/run-regression.mjs            → passRate 100% | pages 103 (all-pass 103) | assertions 1405/1405 | N/A 50（PC 零污染）
node tools/pack-deploy.mjs               → OK — mobile 108 个实现文件（18 组件 × 6 端）/ 文档页 18 / 测试页 18

未执行：部署（只改工作区，未走 AGENTS §九发布流程）；uni-app 真实编译（既有状况 S7-P25，需 @dcloudio 依赖）。

Mobile · 移动端组件第二批（弹出层基座 + 展示系）：Badge / Tag / Popup（索引 8 → 11）

起因：批次推进。移动端规格已写到 §9 / §10 / §11（上一轮写好但未实现），本轮按 PLATFORMS.md §四

的六步流程把三节规格落地为 6 端实现 —— 组件数 8 → 11，frameworks-mobile/ 48 → 66 个文件。

三个新组件（规格小节 → slug / 前缀）：
徽标 Badge（§9 → mobile-badge）：shape = dot / number / text + standalone；

状态 overflow（超过 max 显示 99+）与 hidden（值为 0 且未开 showZero 时不渲染）。

角标绝对定位、不改变被包裹元素的布局尺寸；红点 aria-hidden，数字角标带 aria-label。

标签 Tag（§10 → mobile-tag）：tone 五语气（default / primary / success / warning / danger）

+ size（default / small）+ closable。关闭按钮是原生 button、24×24 热区（小尺寸标签内用负外边距扩展），

aria-label 带上标签文字（否则一串「✕」读屏无法区分）；disabled 时置灰且不响应。

弹出层 Popup（§11 → mobile-popup）：placement 五方向（center / bottom / top / left / right）+ round

（贴边方向在靠内容一侧切圆角，用逻辑属性，RTL 安全）；closeOnMask 可关；内容超长时 body 内部滚动、

遮罩不滚；滑入 240ms cubic-bezier(.32,.72,0,1)；浮层 role="dialog" + aria-modal，遮罩 aria-hidden。

配色零发明（全部既有令牌，脚本实测两态）：实心底 + --kole-color-text-inverse

亮色 5.57–5.87:1 / 暗色 5.64–8.24:1；Tag 的浅底 + 同族字色亮色 4.68–5.38:1 / 暗色 4.92–6.91:1。

未新增任何色值，因此不需要碰 PC 令牌文件。

过程发现并修掉两处陈旧计数（都是前一批 8 个组件落地时漏改的）：

① tools/pack-deploy.mjs 的输出文案写死「5 组件 × 6 端」（数字本身是算出来的，只有说明文字陈旧）→ 改为读索引；

② site/m/_design_template.html 的「移动端 5 个组件」写死在 HTML 里 → 改为构建期占位符（由 build-mobile.mjs 注入实际组件数）。

注：本条初版把占位符原文写进了日志正文，而 changelog.html 是从本文件正文提取渲染的，

于是页面里出现了未替换的占位符 —— 被 verify-mobile-docs.mjs 的 E7（无残留占位符）当场拦下。

同一条纪律：日志正文里不要出现占位符形状的字面量。

修掉一处误报 skip：Badge 的「数值为 0（hidden）」演示块把 data-assert 放在被隐藏的角标上，

断言引擎按「默认隐藏（交互后可见）」记为 skip —— 但该块本身就是「隐藏态+可见对照」的设计。

已把断言移到可见的容器上，skip 3 → 且该页断言 16 条全 pass（skip 只剩两条静态组件固有的 N/A）。

顺带修正 ROADMAP S7-P23 的失败判据：其中写的 PC 断言总数是 1017，实际当前为 1405（103 组件 × 5 端后未更新）。

验收（原样）：

node tools/build-mobile.mjs              → 11 组件 × 6 端（data.mobile.json 238 KB）· 11 测试页 · 11 文档页 · dist/mobile 全端
node tools/verify-mobile-isolation.mjs   → [OK] 隔离门禁全部通过（30 条断言）— B1 11 × 6 端 66 文件 / B8 报告 11 = 索引 11
node tools/verify-uniapp.mjs             → [OK] uni-app 门禁全部通过（9 条断言 · 14 个 SFC）
node tools/verify-mobile-docs.mjs        → [OK] 文档完整性门禁全部通过（12 条断言 · 17 页；E8 站内链接 657 条）
REG_BASE=… verify-mobile-site.mjs        → [OK] 移动端站点全部通过（83 条断言 · 14 页；演示帧 64/64 正常，0 控制台错误）
REG_BASE=… node tools/run-mobile-regression.mjs → passRate 100% | pages 11 (all-pass 11) | assertions 172/172 | N/A 4
node tools/run-regression.mjs            → passRate 100% | pages 103 (all-pass 103) | assertions 1405/1405 | N/A 50（PC 零污染）
node tools/pack-deploy.mjs               → OK — mobile 66 个实现文件（11 组件 × 6 端）/ 文档页 11 / 测试页 11
浏览器实测（1280×1000）                  → 三页各 14 个小节 / 演示块 6·5·6 / 预览帧全部有内容（0 空帧）/ 0 控制台错误
  几何：Badge 角标 absolute + translate(50%,-50%)（不占位）；Tag 24px 高；Popup fixed 被展示框 transform 包含块约束（关闭态位移 143.6px）

Mobile · 组件批次推进：18 个组件 × 6 端（108 实现文件）+ 文档站 24 页，全部门禁与回归通过

起因：用户要求「参考 TDesign 移动端的组件清单，按批次补全当前组件库缺的组件」。

参考页给出 72 个组件的清单，本仓库按「规格 → 契约 → 6 端实现 → 文档页 → 门禁」的既有流水线分批推进。

组件从 5 扩到 18（frameworks-mobile/ 108 个文件 = 18 × 6 端），规格 19 节、契约 18 份：

按 PC 同源分类：导航 4 · 反馈 7 · 通用 2 · 数据展示 3 · 数据录入 2。完整清单见 site/m/index.html 的覆盖矩阵与侧栏。

本会话直接产出的一批（A）：mobile-button（三档高度 44/36/28、loading 阻止重复触发、aria-busy）、

cell（整行热区 ≥56px、按行分隔线、可点用原生 button / 纯展示用 div）、mobile-divider（水平/垂直/虚线/

三种文字对齐，纯装饰 role=separator + aria-hidden）。三者的 6 端实现、契约（含演示分组、相似组件、

必传列、CSS 变量）与规格 §6–§8 均由本会话写入；其余批次与并发会话合并完成。

合并时修掉两处判据问题（都是「判据太窄」而不是放宽）：
slug 允许与 PC 同名：build-mobile.mjs 与 verify-mobile-isolation.mjs 原先要求「移动端 slug 不得与

PC 撞名」，实际两个平台各自有「按钮」「分割线」是正常的 —— 真正要证明的是「同名也各自独立」。

改为：报告同名清单，并断言同名组件的实现文件不在 frameworks/ 下。

dist/mobile/manifest.json 的判据从「无 PC slug」改为「slug 集合与索引完全一致」——

后者能同时抓到漏项与串入，比原来更严。

移动端令牌层补一条全局焦点环：:focus-visible 落在移动端令牌层（不能只依赖 PC 令牌文件里那条 ——

断言引擎读的是直接 link 的样式表的 cssRules，@import 进来的规则不在其中）。

这既是让静态组件过 focus-visible-defined 断言，也是真实的 a11y 改进。

门禁全绿：隔离 30 条 · uni-app 9 条（21 个 SFC）· 文档完整性 12 条（24 页，站内链接 1121 条全可解析）·

移动端站点 118 条（21 页浏览器实测：0 控制台错误、演示帧 101/101 正常渲染、320–768px 无溢出）。

回归：移动端 100%（270 通过 / N/A 6 / 18 页） · PC 100%（1405 通过 / N/A 50 / 103 页）。

部署（AGENTS §九）：pack-deploy --tar（2187 文件 / 1.65 MB gzip）→ 暂存树哈希与本地一致

（a962d7c4caa853b2）→ 替换重建 → 服务器端 specs 404 / 根 302 / sitemap 200 / healthz / SPA 深链全过、

容器 0 error；公网抽查 5 个页面全 200，site/m/index.html、site/m/component/mobile-button.html、

site/m/data.mobile.json 逐字节与本地一致。

Mobile docs · 顶栏与左栏对齐 PC（平台 / 开发指南 / 组件 N + 主题三态跨站生效）+ 补常见问题与更新日志页

起因：用户指出「导航栏需要和 PC 一致，左侧栏也是」。移动端文档站此前是自成一体的简版顶栏

（品牌 + 平台分段 + 3 个链接）与自创分组的左栏（开发指南 5 项自定名 + 手势/反馈分类），

与 PC 文档站的信息架构不一致。

顶栏与 PC 同结构：logo（标记块 + Kole UI + 副标题） + 版本角标 v1.0.0（读 data.mobile.json 的

meta.version）+ 平台切换 + 主导航 5 项（组件总览 / 快速开始 / 设计规范 / 常见问题 / 更新日志，

与 PC 同名同序，组件页高亮「组件总览」= PC 在组件页高亮「组件」的同一口径）+ 主题模式三态。

PC 特有的三件没有搬，原因写明在 site/m/style.css 注释里：搜索框（PC 79 个组件才需要）、

技术栈选择器（PC 5 端各自成页；移动端 6 端同页展示）、语言选择器（移动端无 i18n 字典）。

主题三态与 PC 完全同一约定：localStorage['kole-mode'] ∈ light|dark|auto、auto 跟随系统、

反色靠 html.kole-dark（令牌两端共用）。实测跨站生效：在移动端站选夜间 → FAQ 页仍是夜间 →

PC 站同一键也是夜间；<head> 里有同步 bootstrap，避免首帧先白后黑（PC 的 S2-P5 同款处理）。

左侧栏三段式与 PC 侧栏一致：「平台」组（PC 端组件 / 移动端组件【当前】，各带副标题）→

「开发指南」组（与 PC 同名同序的 5 项；移动端特有的「平台与端 / 测试与回归」置后并标「移动端」）→

「组件 N」按 PC 的六分类分组与计数（通用 / 导航 / 数据录入 / 数据展示 / 反馈 / 工具与系统）。

组件重新归类：navbar、tabbar → 导航；actionsheet、pullrefresh、swipecell → 反馈；

分类口径写进移动端索引的 categories 块（真源），构建脚本与文档站都读它。

补两页：
faq.html 常见问题：6 组 20 条（接入 / 令牌 / 触控 / uni-app / 排障 / 口径），每条对应仓库里可复现的

实测或门禁断言；含「uni-app 端真的编译过吗 → 没有」这类如实回答。

changelog.html 更新日志：构建时从仓库根 CHANGELOG.md 提取标题含「Mobile / 移动端」的段落

（自带一个极小的 Markdown 渲染：标题 / 列表 / 引用 / 代码块 / 行内 code 与 strong），不手抄 ——

站点与仓库两处说法不一致是这类页面的典型失败模式。

改名对齐：设计令牌 → 设计规范（tokens.html → design.html），与 PC 的「设计规范」同名。
门禁 11 → 12 条：E3 从「侧栏列全组件」扩为「顶栏与左栏与 PC 同结构」（平台组与「当前」角标、

开发指南 5 项同名同序、顶栏 7 个必需元素、主导航 5 项）；新增 E8 站内文件链接全部可解析（332 条）。

E8 当场抓到两个真问题（已修）：① 改名后 _index_template.html 与 _guide_template.html 还指向

tokens.html（快速开始卡片与页脚）；② changelog.html 的测试链接少退一级（../tests/… 应为 ../../tests/…）。

E8 已双向验证（临时改坏一处链接 → FAIL）。

修：更新日志页在窄屏横向溢出（375px 溢出 88px、414px 溢出 49px）—— 提取的正文含 64 位哈希、

长路径这类不可断词的串；给正文/列表/行内 code 补 overflow-wrap: anywhere（表格此前已有同类规则）。

修后 7 页 × 4 宽度（320/375/414/768）0 溢出。

验收（原样）：

node tools/verify-mobile-docs.mjs        → [OK] 12 条断言 · 11 页
node tools/verify-mobile-isolation.mjs   → [OK] 29 条断言    node tools/verify-uniapp.mjs → [OK] 9 条（8 SFC）
REG_BASE=… verify-mobile-site.mjs        → [OK] 53 条断言（8 页 + 窄屏）   npm run verify:i18n → OK（16 checks）
浏览器实测：顶栏 = Kole UI 移动端 / v1.0.0 / [PC 端][移动端] / 组件总览·快速开始·设计规范·常见问题·更新日志 / 自动模式
            左栏 = 平台（PC 端组件、移动端组件【当前】）/ 开发指南 5 项 + 2 项移动端特有 / 组件 5（导航 2 · 反馈 3）
            主题：选夜间 → html.kole-dark + localStorage[kole-mode]=dark；跳 FAQ 仍夜间；PC 站同键亦夜间；0 控制台错误
node tools/run-mobile-regression.mjs     → 100% | 77/77 | 5/5 页
node tools/run-regression.mjs            → 100% | 1026/1026 | N/A 34 | 79/79 页
node tools/pack-deploy.mjs --tar         → OK（39 条必需项，含 6 张移动端根页；组件数改为从索引读取）

Deploy · 移动端组件页（TDesign 范式）已上线

按 AGENTS §九发布：pack-deploy --tar → 上传 → 暂存归一化树哈希与本地一致（f00d3c4ac2e50861，1531 文件）→ 替换 → docker compose build && up -d。

验收：specs 404 / 根 302→/site/ / sitemap 200 / healthz 有 content-type / SPA 深链 200 / 缺快照 404 / 容器日志 0 error；

公网 https://kole-ui.mymoyu.top 抽查 6 个文件（site/app.js、组件薄壳、site/data.json、移动端文档页与演示页）逐字节与本地一致。

并发提示：本轮期间另一会话把 package.json 版本重置为 1.0.0 并重建站点（data.json 的 generated=2026-09-20 07:36、

versions.json 单版本）。线上现已与该状态一致 —— 版本号本身不是本次改动；如需回到 2.0.0，请改 package.json

后重跑 npm run build:site 并再发布一次。

另：本轮第一次发布（07:26 打包）后实测到线上落后工作区 906 个文件（并发会话 07:36 重建了薄壳与 app.js），

已按 §九的约定「等稳定后重发」补发一次，现线上与工作区逐字节一致。

Mobile docs · 组件页对齐 TDesign 范式（演示分组 / 独立预览 + 原文代码 / 必传 / CSS 变量 / 相似组件）

起因：用户给了参考页 <https://tdesign.tencent.com/mobile-vue/components/link>。用浏览器渲染后提取其结构：

演示按 01 组件类型 / 02 组件状态 分组；每个演示独立成块（标题 + 预览 + 代码）；

API 分 Props（名称 / 类型 / 默认值 / 描述 / 必传）、Events、CSS Variables（名称 / 默认值 / 描述）；

另有「何时使用 / 组件搭配使用 / 推荐慎用示例 / 相似组件」。按这套范式重排了移动端组件页。

演示改为「分组 + 独立块」：契约新增 demos（id / group / title / desc / variant），5 个组件共 20 个演示块

（navbar 3、tabbar 4、actionsheet 4、pullrefresh 4、swipecell 4），按 01 组件类型 / 02 组件状态 分组。

每块含：标题 + 变体标记 + 说明 + 375 宽单演示预览帧 + 「查看代码」（演示页原文，行数标注，可复制）。

演示页支持 ?demo=<id> 单块模式：5 个演示页的每个演示包成

<section class="demo-block" data-demo="…">，并加过滤脚本（只显示该块、隐藏帧内标题行、取消 min-height:100vh）。

无参数路径完全不变 —— 测试页与回归走无参数，实测移动端回归仍 100%（77/77）。

预览帧高度自适应：按 body.scrollHeight 收紧到 140–360px。

踩坑：先用 max(body.scrollHeight, documentElement.scrollHeight) 量，结果四个演示都锁在 308px ——

documentElement.scrollHeight 等于帧视口高度（html 撑满视口），于是「帧高 → 视口高 → 量到的高度」

形成反馈环，永远收敛在初始值。只量 body 后：swipecell 140 / navbar 140–166 / tabbar 222 / pullrefresh 242 /

actionsheet 262，0 个演示被裁。

API 补两列/一表：Props 增「必传」列（严格定义：实现里没有默认值时才为 Y，门禁逐条核对 4 个框架端）；

新增「CSS 变量」表（从组件样式表扫描组件级变量：--kole-m-swipecell-offset /

--kole-m-swipecell-action-width / --kole-m-pullrefresh-threshold / --kole-m-pullrefresh-offset）。

新增「相似组件」表（契约 related：组件 + 「何时用它而不是本组件」的区分说明，共 10 条），

并把「用法要点」按参考页改名为「何时使用」。

组件页新顺序：演示 → API（Props / 事件 / 插槽 / CSS 变量）→ 何时使用 → 交互与触控 → 无障碍 →

相似组件 → 规格未定 → 结构 → 变体类名映射 → 代表变体 → 令牌 → 6 端源码 → 测试与回归 → 契约。

另在 hero 下加「引入」代码块（令牌 + 本组件样式）。

门禁从 8 条扩到 11 条：新增 E4b（必传 ⇔ 实现默认值）、E6b（CSS 变量表 ↔ 组件 CSS 双向）、

E6c（相似组件 slug 真实存在 + 说明非空）；E5 扩为「每个演示块 ↔ 演示页 data-demo 双向一致 +

预览帧带 ?demo= + 代码区含转义后的演示页原文 + 每个演示代码块非空」。

验收（原样）：

node tools/verify-mobile-docs.mjs        → [OK] 11 条断言 · 9 页
node tools/verify-mobile-isolation.mjs   → [OK] 29 条断言     node tools/verify-uniapp.mjs → [OK] 9 条（8 SFC）
REG_BASE=… verify-mobile-site.mjs        → [OK] 53 条断言（8 页 + 窄屏）
npm run verify:i18n                      → OK（16 checks）
浏览器实测（1280×1000）：分组 01/02 ✓ · 20 个演示块 ✓ · 每块预览帧只显示对应演示（4/4）✓ ·
  每块有代码折叠 ✓ · 帧高自适应 0 裁剪 ✓ · 0 控制台错误
node tools/run-mobile-regression.mjs     → 100% | 77/77 | 5/5 页（演示页改动后复跑）
node tools/run-regression.mjs ×2         → 100% | 1026/1026 | N/A 34 | 79/79 页

Deploy · 公网站更新到当前构建（移动端文档站四页 + 逐组件页 + PC 顶栏改动）

按 AGENTS §九流程发布：SITE_URL_BASE=https://kole-ui.mymoyu.top/ npm run build:site → build-mobile + build-uniapp

→ pack-deploy --tar（1531 文件 / 5.8 MB，1.0 MB gzip）→ 上传 → 备份（目录 /opt/aurora-admin.prev-20260920-0712

+ 镜像 kole-ui-showcase:pre-20260920-0710）→ 暂存目录逐文件哈希对账 0 差异（1531/1531） → 替换 → docker compose build && up -d。

验收（服务器 127.0.0.1:3311）：specs 目录 404 ✓ / 根 302→/site/ ✓ / sitemap 200 ✓ / healthz 有 content-type ✓ /

SPA 深层路由 /site/component/button/h5 200 ✓；移动端与 uni-app 路径 8 条全 200（含此前 404 的

site/m/guide.html、platform.html、tokens.html）；安全响应头 3 条在位。

公网 https://kole-ui.mymoyu.top：/site/、/site/m/、/site/m/guide.html、

/site/m/component/actionsheet.html、/versions.json、/sitemap.xml 全 200；

data.json → lib=kole-ui / version=2.0.0 / generated=2026-09-20 07:09（= 本次构建）；

抽查 site/m/guide.html 与 site/m/component/actionsheet.html 的公网字节哈希与本地包逐字节一致。

过程发现并修掉一个会让构建直接失败的仓库状态问题：本地 Dockerfile 曾带 COPY 1.4.1 /usr/share/nginx/html/1.4.1

行，而仓库根已无 1.4.1/ 快照目录（并发改动期间快照被清理）——docker compose build 报

failed to calculate checksum of ref …: "/1.4.1": not found。该行与其后注释块（"以后归档后在补一行"）

的自洽性由 tools/verify-versions.mjs 双向卡住（磁盘快照 ↔ COPY 行），现已通过（33 checks）。

注：本轮第一次发布正是卡在这条（打包与 Dockerfile 之间差了几十秒的并发改动），已重新打包发布成功。

修掉发布过程中暴露的 500：快照被移除后 /1.4.1/site/ 由「归档站」变成 500（容器日志：

rewrite or internal redirection cycle while internally redirecting to "/1.4.1/site/index.html"）——

nginx.conf 里版本段的 try_files 回落目标又匹配回同一 location，形成内部重定向环；

且深链 /1.4.1/site/component/button/h5 同样 500。修法：末位补 =404，前三个参数退化为文件存在性检查

（快照在 → 发它自己的壳；不在 → 干净 404）。并给这条失败模式加了门禁：tools/verify-versions.mjs

新增「versioned fallback terminates with =404」，双向验证过（改动后 34 checks 全过；把 =404 去掉立刻 FAIL）。

实测：/1.4.1/site/ 404、/1.4.1/ 302（再 404）、其余验收全绿、容器日志 0 条 error。

归档的 1.4.1 快照内容本身没有被删除——它仍在服务器上的 /opt/aurora-admin.prev-20260920-0712/1.4.1/

与 kole-ui-showcase:pre-20260920-0710 镜像里；仓库当前按「不归档任何历史版本」的状态（versions.json

只列 2.0.0）发布，这是并发会话清理快照后的既定状态。

Mobile docs · 补全左侧栏与页面内容（API / 6 端源码 / 令牌 / 回归状态）

起因：用户指出「移动端的左侧栏内容不完整，页面内容也不够完整」。移动端文档站此前只有顶部导航

与 6 个小节的组件页，没有左侧导航，也没有 API、源码、令牌、回归状态这些"读文档的人真正要用的东西"。

左侧栏：所有页面共用一份 IA —— 「开发指南」5 项（移动端总览 / 快速开始 / 平台与端 / 设计令牌 /

测试与回归）+「组件 5」按分类分组（导航 / 手势 / 反馈）与计数，当前页/当前组件高亮并带 aria-current。

桌面恒定展开；≤1000px 自动收起为可折叠面板（点标题展开）。

踩坑记录：左栏用 <details> 承载时，不能用"去掉 open + CSS 强制展开"的写法 ——

不带 open 的 <details> 高度按关闭态算成 0，overflow:auto 会把里面的 nav 整块裁掉

（DOM 里有 10 条链接、屏幕上一片空白，实测截图抓到）。改为 open 默认展开 + 断点脚本切换。

新增三页：
guide.html 快速开始：三步接入、按端引入路径表（6 端）、6 端最小示例（React / Vue 3 / Vue 2 / uni-app

可拷贝代码）、与 PC 端的边界、5 条常见问题（样式不生效 / --kole-m-* 取不到值 / 安全区 / 手势不触发 / 多 fixed 叠层）。

platform.html 平台与端：两轴覆盖矩阵、uni-app 两列对照、12 行目录与命名映射、6 条隔离规则、

6 条门禁命令（各自检查什么）、新增组件的六步流程。

tokens.html 设计令牌：15 个 --kole-m-* 表（名 / 值 / 用途）+ 组件实际引用到的继承令牌表（构建时扫描）、

单位与安全区与明暗模式三条约定、"改令牌的正确姿势"示例。

组件页 6 节 → 14 节：新增 API（props / 事件 / 插槽三张表）、6 端源码（每端一个折叠块 + 复制按钮）、

用到的令牌（构建时从该组件 CSS 扫描，区分自有 / 继承 / 组件级变量）、交互与触控、无障碍、

变体维度 × 类名映射、测试与回归（逐组件断言数，取自回归报告的 pageResults）、设计契约（内嵌原始 JSON）、

Docs site · 平台入口打通（PC ↔ 移动端）+ 技术栈选择器美化 + 本地访问方式

起因：用户要求「做一个合理的访问方式」与「当前的组件框架选择的样式需要美化一下」。

前者指：移动端文档站上线后没有入口，且本地起服务时端口被旧实例占用会静默失败（实测 403）；

后者指顶栏那个裸 <select>（系统原生下拉、无悬停/展开态，与旁边的语言/主题选择器不同源）。

技术栈选择器改为「胶囊触发器 + 卡片菜单」（site/index.html + site/style.css + site/app.js）：

图标（层次符号）+ 当前值 + 箭头；菜单沿用语言选择器的卡片样式（标题分隔线、每项带端文件名角标

html / jsx / vue2 / vue3、选中项对勾、头部右侧显示当前端文件名）。键盘全路径：↓/↑ 移动、

Home/End 首尾、Enter/Space 选中、Esc 关闭并回焦、Tab 关闭不抢焦点、点击外部关闭；

展开态旋转箭头 + 品牌色焦点环；暗色与 prefers-reduced-motion 均适配。

原生 <select> 保留为状态真源（.fw-native：1px 视觉隐藏，不进 Tab 序列）：

选中项写回它的 value 并派发 change，既有的「状态更新 / localStorage / 路由跳转」管道

与既有验证脚本（run-site-smoke 读 inputValue() + selectOption()）一行未改。

侧栏新增「平台」分组：PC 端组件（带「当前」角标与副标题）/ 移动端组件（副标题写清

5 组件 × 6 端含 uni-app）。移动端入口是整页跳转（指向站点根下的 m/index.html）——

SPA 的路由拦截器只接管无扩展名的地址，带 .html 的链接交回浏览器，两个站各自独立加载。

移动端文档站顶栏加平台切换 [PC 端] [移动端]（当前侧实心品牌底），与 PC 侧形成双向入口。
本地访问方式（site/dev-server.js）：端口被占用时自动向上找空闲端口（最多 10 档）并说明，

不再 EADDRINUSE 直接退出；KOLE_PORT 显式指定时不回退（CI/脚本依赖固定端口）。

启动即打印 6 个入口：PC 文档站 / 移动端文档站 / 组件总览 / PC 测试总览 / 移动端测试总览 /

两个回归收集器，并给出 REG_BASE= 提示。

实测踩到过：3311 上挂着改动前启动的实例时，新目录一律 403，日志里只有一句 EADDRINUSE，

极易误判成「构建没产出」。

修：移动端文档站在小屏上横向溢出（实测 375px 溢出 128px、414px 溢出 89px）—— 一个讲移动端的

文档站自己在手机上横向滚动说不过去。元凶两处：表格里不可断行的长路径

（.design_library/kole-ui-mobile/components/ 把表格最小宽度顶到 462px）与组件页固定 375px 的设备帧。

修法：单元格与 <code> 允许长 token 断行、设备帧取 min(375px, 100%)、顶栏 ≤720px 换行并把副导航移到第二行。

修后实测 320 / 375 / 414 / 768 / 1280 全部 0 溢出、0 控制台错误。

新增窄屏门禁：tools/verify-mobile-site.mjs 加「窄屏无横向溢出」一节（3 类页面 × 4 个宽度 + 控制台错误），

断言数 38 → 53。只靠"在桌面宽度看一眼"发现不了这类问题。

修：移动端文档站与规格文件里对 MOBILE.md 的失效引用 → PLATFORMS.md（4 处源码，

生成物已重跑）。该文档在交付时最终命名为 PLATFORMS.md。

验证脚本同步：verify-nav-responsive.mjs 的字体容忍度元素清单随 UI 更新

（.fw-label/#fw-select → .fw-cur/.fw-menu .fw-opt）—— 清单不跟着改会把余量报得偏乐观。

实测余量 5.8%（英文 · 1367px）。

验收（原样）：

浏览器功能断言（Chromium 1440×900）        25/25 PASS，全程 0 控制台错误
  ├ 触发器/菜单/4 选项/端文件名角标/选中态/aria-expanded
  ├ 选择 Vue 3 → 触发器文案 + #fw-select value + localStorage + 路由 /component/button/vue3 同步
  ├ 键盘：Esc 关闭、↓ 打开并聚焦当前项、↓ 环形移动、Enter 生效
  ├ 侧栏平台入口 2 项、href=/site/m/index.html、整页跳转到移动端站、移动端站回链 ../index.html
  └ 暗色模式菜单底色 rgb(28,31,38)（跟随主题）
node tools/verify-mobile-isolation.mjs     → [OK] 29 条断言
node tools/verify-uniapp.mjs               → [OK] 9 条断言（8 个 SFC）
REG_BASE=… node tools/verify-mobile-site.mjs → [OK] 53 条断言（8 页 + 3 页窄屏 × 4 宽度）
npm run smoke:site                          → OK — all checks passed
npm run verify:nav                          → OK — all checks passed（余量 5.8%）
npm run verify:playground                   → OK — all checks passed
node tools/run-regression.mjs ×3            → 100% | 1026/1026 | N/A 34 | 79/79 页 | 0 超时
node tools/run-mobile-regression.mjs        → 100% | 77/77 | 5/5 页 | 0 超时

Mobile · 移动端平台上线：与 PC 端物理隔离（平台 × 端两轴，含 uni-app 端）

起因：用户要求「在组件库额外添加移动端组件，移动端和 PC 端隔离」，并明确「PC 和移动是两个大分类，

移动端后面是 H5 移动端、Vue 移动端，而且 uni-app 也会经常用到（uni-app 移动端 / uni-app PC 端）」。

据此把组件库组织成两个正交轴：平台 pc | mobile × 端 css | html | jsx | vue2 | vue3 | uniapp。

新增 PLATFORMS.md（两轴定义、目录与命名映射、隔离规则、新增组件六步流程）。

移动端 5 个组件 × 6 端 = 30 个实现文件（frameworks-mobile/）：navbar（顶部导航栏）、

tabbar（底部标签栏）、actionsheet（动作面板）、pullrefresh（下拉刷新）、swipecell（滑动单元格）。

每组件六端：CSS / H5 演示页 / React / Vue 2 / Vue 3 / uni-app。类名前缀 kole-m-，导出名 KoleM*。

移动端规格原文（本仓库自撰）：.design_library/kole-ui-mobile/spec/移动端规格.md。

PC 端规格来自外部交付的 组件1~10.txt；移动端没有外部规范，故契约 sourceKind: authored-spec、

provenance: authored-in-repo——不冒认外部来源；契约的 doNotInvent / unknowns 逐条对应规格条目。

规格共 5 节（另有 §〇隔离总则），5 份契约全覆盖。

令牌层：.design_library/kole-ui-mobile/colors_and_type.css = @import PC 令牌（颜色/字体/圆角/阴影同源）

+ 15 个 --kole-m-*（触控 44px 最小热区、@supports (env()) 安全区、移动端字号、手势动效时值）。

PC 令牌文件零改动，改一处令牌两端同时生效。

隔离边界（每一条都有断言，见下）：实现目录（frameworks-mobile/ vs frameworks/）、契约目录、

类名前缀、令牌前缀、测试页（tests/mobile/ vs tests/）、回归报告（tests/mobile-report.json vs

tests/report.json）、文档站（site/m/ 静态站 vs site/ SPA，移动端不进 PC 路由表）、

分发产物（dist/mobile/* vs dist/*）。

uni-app 端两处：移动端 × uni-app（5 个，目标 app-plus / mp-weixin / h5，用 uni 基础组件 +

rpx + touch 事件——小程序与 App 端无 PointerEvent）；PC × uni-app 试点 3 个

（frameworks-uniapp-pc/{Button,Input,Card}.uniapp.vue，类名与 PC 的 frameworks/*.css 逐字一致、

--kole-* 令牌、px 尺寸、目标 H5/PC 容器），覆盖率 3 / 79 并登记为 ROADMAP S7-P26。

构建（Node，跨平台，不碰 Windows-only 的 PS 链）：tools/build-mobile.mjs（导出 site/m/data.mobile.json

自包含 102 KB = 5 组件 × 6 端源码、site/m/index.html 总览、site/m/component/<slug>.html 逐组件页、

tests/mobile/、dist/mobile/）与 tools/build-uniapp.mjs（dist/uniapp-pc/**）。

两个脚本都带写入守卫：越界路径直接抛错（移动端脚本只允许写 site/m/ tests/mobile/ dist/mobile/）。

测试：移动端测试页以 375×640 设备帧 iframe 载真实演示页；断言引擎与 PC 共用 tests/_runtime.js；

行为库为移动端专属 tests/mobile/_behaviors.js，新增 3 个触控动词 swipe-sets-class / swipe-sets-attr /

pull-triggers（合成 pointerdown → pointermove → pointerup 手势，断言类/属性真实变化）。

两端行为库互不加载，PC 侧 6 试点组件不受影响。

门禁与 CI：tools/verify-mobile-isolation.mjs（28 断言：PC 零污染 / 移动端自洽 / 分发隔离）、

tools/verify-uniapp.mjs（9 断言：SFC 三段 / node --check 语法 / 标签配平 / 禁 DOM API /

手势必须 touch / 只用 uni 基础组件 / 前缀隔离 / 单位策略）、tools/run-mobile-regression.mjs。

regression.yml 新增：构建分发产物 → 移动端生成物可复现性断言（git diff --quiet 卡"改了索引忘重跑构建"）

→ 两条门禁 → 移动端回归 → 报告上传与摘要（PC 与移动端两段）。

部署：tools/pack-deploy.mjs 的 CONTENT_DIRS 增 frameworks-mobile、frameworks-uniapp-pc，

新增 6 条硬断言（移动端 30 实现 / 5 文档页 / 5 测试页 / 3 试点）；Dockerfile 增两条 COPY；

.dockerignore 显式排除 .design_library/kole-ui-mobile/spec（移动端规格原文与 PC 规格同策略不进镜像）；

site/dev-server.js 白名单增两个顶层目录。

验收（原样）：

node tools/verify-mobile-isolation.mjs   → [OK] 隔离门禁全部通过（28 条断言）
node tools/verify-uniapp.mjs             → [OK] uni-app 门禁全部通过（9 条断言 · 8 个 SFC）
node tools/run-mobile-regression.mjs     → passRate 100% | pages 5 (all-pass 5) | assertions 77/77
node tools/run-regression.mjs ×8         → run 1..8 全为 100% | pass 1017 | fail 0 | na 34 | pages 79/79 | timedOut 0
node tools/pack-deploy.mjs               → OK：components 79 薄壳/395 实现 · mobile 30 实现/5 文档页/5 测试页 · uniapp-pc 3 试点

未执行（写明并给复现命令，见 ROADMAP S7-P25）：uni-app 真实编译（H5 / 微信小程序 / App）——

需 @dcloudio/vite-plugin-uni，与零运行时依赖不冲突但会污染主回归 job 的依赖，故本次只做静态门禁；

复现命令写在 tools/verify-uniapp.mjs 头部。