常见问题
按「接入 → 令牌 → 触控 → uni-app → 排障 → 口径」六组整理。每条都对应仓库里可复现的实测或门禁断言，不是凭印象写的经验。
接入
| 问题 | 回答 |
|---|
| 组件渲染出来了，但没有样式 | 没引令牌或组件样式。最小集合是 kole-ui/mobile/tokens.css + kole-ui/mobile/components/index.css（按需则引单个组件 CSS）。 |
| 能直接拷走一个文件用吗 | 能。frameworks-mobile/<Prefix>.html 是零依赖演示页（样式内联 + 原生脚本），拷进工程即可跑；.css 是独立的样式表。 |
| 为什么没有 PC 的那些组件 | 移动端与 PC 是两套清单、物理隔离（见 平台与端）。移动端只做触屏优先的组件，B 端中后台的那 103 个在 PC 文档站。 |
类名为什么带 -m- | kole-m- 是移动端命名空间（PC 是 kole-）。两端样式表各引各的，交叉引用会拿到未定义的样式（门禁 verify:isolation 会拦这类混用）。 |
令牌
| 问题 | 回答 |
|---|
--kole-m-* 取不到值 | 令牌层没加载。它在 PC 令牌文件之上加了一层，不要只引 PC 的 colors_and_type.css；引移动端的 tokens.css（已 @import PC 令牌）或直接引移动端令牌层。 |
| 改了颜色，移动端为什么跟着变 | 这是设计如此：颜色 / 字体 / 圆角 / 阴影令牌两端同源，移动端只加 --kole-m-*（触控尺寸、安全区、字号、动效）。改 PC 令牌文件，两端同时生效。 |
| 暗色模式要单独写一套样式吗 | 不用。给根元素加 html.kole-dark 即可（令牌文件里已写好该组）；本站在顶栏「主题模式」里切换，约定与 PC 完全一致 —— 三态存 localStorage['kole-mode']，auto 跟随系统。 |
触控
| 问题 | 回答 |
|---|
| 安全区没生效（刘海 / 底部横条） | 页面需要 viewport-fit=cover（演示页都带）。令牌层用 @supports (padding-top: env(safe-area-inset-top)) 探测后再取 env()，不支持时为 0px。 |
| 滑动 / 下拉在真机上不触发 | 浏览器端组件用 Pointer Events；uni-app 端用 touch 事件。若你的容器截了事件（如自带手势库），需要放行；另外纵向位移更大时组件会主动让位给页面滚动。 |
同一页多个 position: fixed 组件叠在一起 | 这是浏览器行为（都相对视口定位）。做演示或预览时给容器加 transform: translateZ(0) 建立包含块，组件 CSS 不必改 —— 本站的 TabBar / ActionSheet 演示就是这么做。 |
| 点击热区多大才合规 | 44×44（WCAG 2.5.5 / Apple HIG），令牌是 --kole-m-touch-target: 44px；uni-app 端为 88rpx（750rpx = 视口宽度）。 |
uni-app
| 问题 | 回答 |
|---|
为什么 uni-app 端没有 document / PointerEvent | 小程序与 App 端没有 DOM，也没有 PointerEvent。所以该端只用 uni 基础组件（view / text）+ @touch* 事件；verify:uniapp 会静态拦住 DOM API 与 pointer 事件。 |
uni-app 端为什么用 rpx | rpx 是移动端语义（750rpx = 视口宽度），该端在组件内用同名令牌覆盖成 rpx 值；PC × uni-app 端反过来保持 px。 |
| uni-app 端真的编译过吗 | 没有。本仓库只做静态门禁（9 条：SFC 结构 / node --check 语法 / 禁 DOM / 手势必须 touch / 前缀隔离 / 单位策略），真实编译需要 @dcloudio 依赖，复现命令在 tools/verify-uniapp.mjs 头部（ROADMAP S7-P25）。 |
排障
| 现象 | 怎么办 |
|---|
| 改了索引但页面没变 | 本站是生成物：跑 npm run build:mobile 重建（CI 里有 git diff --quiet -- site/m tests/mobile 断言，防止「改了索引忘了重建」）。 |
| 本地打开是 403 / 404 | dev-server 白名单没有该顶层目录（要加 PUBLIC_ROOTS 与 isPublicPath() 两处）；或 3311 上还挂着改动前启动的实例 —— 现在会自动回退端口并打印实际入口。 |
| 演示帧里样式全丢 | 相对路径层数不对（深层页要用三级 ../../../ 回到仓库根）。这是实测踩过的坑，已由 verify:mobile-site（浏览器实测）卡住。 |
口径
| 问题 | 回答 |
|---|
| 版本号以什么为准 | package.json 的 version，构建时写进 site/m/data.mobile.json 的 meta.version（顶栏角标读它）。 |
| 回归口径 | 移动端断言跑在真实 375×640 设备帧里（引擎与 PC 共用 tests/_runtime.js，触控动词在 tests/mobile/_behaviors.js）；报告 tests/mobile-report.json 含逐页结果。跑法：node tools/run-mobile-regression.mjs。 |
| 规格从哪来 | 移动端没有外部规范原文，规格由本仓库撰写：.design_library/kole-ui-mobile/spec/移动端规格.md。契约 JSON 的 sourceKind 是 authored-spec、provenance 是 authored-in-repo。 |