feat(品牌标识): 几何 K 图标(favicon/顶栏标记/theme-color) + 并行会话成果入库

## 品牌标识（本次会话）起因：品牌此前没有任何图形标识 —— 唯一 favicon 是内联 data-URI 里的字母「A」，那是 v2.0.0「Aurora Admin → Kole UI」改名漏掉的一处（PC 顶栏也是「A」，移动端站已是「K」；移动端文档站则完全没有 favicon）。 - 几何：24 网格三个互不接触的笔画（竖 + 两斜），圆头描边；描边 2.25 → 16px 标签页尺寸下正好 1.5px = 规范原文「描边1.5px」 - 取色分两套（刻意）：favicon 硬编码品牌蓝/白（渲染在浏览器标签栏，不继承 kole-dark）；顶栏标记走 currentColor（实测暗色下自动转 rgb(20,22,28)） - 新增 theme-color 双条（light #FFFFFF / dark #1C1F26，取 --kole-color-card-bg） - 修 site/app.js hero 标语 KOLE ADMIN → KOLE UI（改名变形残留） - 移动端 7 个模板补 favicon（此前计数 0）验收：门禁 9 条全 OK（site-routing/site-routes/mobile-docs/mobile-site/isolation/ theme/nav/i18n/icons）；PC 回归 1464/1464 · 移动端 807/807，各连跑 8 次一致；两端 favicon 405 字节逐字节一致；PC 站控制台错误 1→0。 ## 并行会话成果（本次一并入库） - 图标系统：2576 图标（TDesign/Element Plus，MIT）+ 11 端注入 + 5 个构建门禁工具 + IconPreview 预览页 + ICON-SPEC.md 冻结规格 - 移动端平台：47 组件 × 6 端 + 文档站 53 页 + 隔离门禁 - PC 组件：103 个大后台组件 / 组件11 批次 - uni-app：PC 端试点 + 移动端端实现 + 真实编译验证 ## 工程 - .gitignore 补 .scratch/ 与 .zcode-preexisting-*.txt（会话中间产物，实测 9.1MB，不入库） - CHANGELOG 补品牌标识条目 - ROADMAP 登 S8-P4（品牌标识任务包 + og:image/apple-touch-icon 未做部分）
2026-09-21 10:05:48 +08:00
parent eb25feedaf
commit f1fbfc2ddb
2541 changed files with 270385 additions and 25873 deletions
@@ -0,0 +1,278 @@
+{
+  "schemaVersion": 1,
+  "sourceKind": "authored-spec",
+  "provenance": "authored-in-repo",
+  "specFile": "spec/移动端规格.md",
+  "specSection": "44 · 级联选择器 Cascader",
+  "confidence": "high",
+  "slug": "mobile-cascader",
+  "name": "级联选择器 Cascader",
+  "semanticTypeCandidates": [
+    "cascader",
+    "tree-select",
+    "region-picker"
+  ],
+  "variantDimensions": [
+    {
+      "name": "mode",
+      "values": [
+        "panel",
+        "popup"
+      ]
+    },
+    {
+      "name": "showPath",
+      "values": [
+        "true",
+        "false"
+      ]
+    },
+    {
+      "name": "round",
+      "values": [
+        "false",
+        "true"
+      ]
+    }
+  ],
+  "representativeVariants": [
+    {
+      "mode": "panel",
+      "showPath": "true",
+      "round": "false",
+      "label": "内嵌面板（页面内逐级选择）"
+    },
+    {
+      "mode": "popup",
+      "showPath": "true",
+      "round": "true",
+      "label": "底部浮层（带遮罩与确定取消）"
+    },
+    {
+      "mode": "panel",
+      "showPath": "false",
+      "round": "false",
+      "label": "不显示路径条（层级少时省一行高度）"
+    }
+  ],
+  "anatomy": {
+    "cascader": "根元素，mode=panel 时内嵌在页面里，mode=popup 时是底部浮层",
+    "mask": "遮罩（仅 mode=popup），点击关闭",
+    "cascader__header": "取消 / 标题 / 确定三格（仅 mode=popup）",
+    "cascader__path": "路径条，按已选深度渲染；除末位外都可点，点了回退到该级",
+    "cascader__panel": "选项区，role=listbox + aria-label 说明当前在选第几级",
+    "cascader__option": "单个选项，role=option + aria-selected；有下级显示箭头，叶子显示勾号"
+  },
+  "structurePatterns": {
+    "mode": "panel（内嵌在页面里）/ popup（底部浮层，自带遮罩与确定取消）",
+    "showPath": "true（显示路径条，可回退）/ false（不显示，层级少的场景省一行高度）",
+    "round": "false（直角）/ true（浮层靠内容一侧切圆角）"
+  },
+  "usageHints": [
+    "在有层级关系的选项里逐级选到末级（省 → 市 → 区、品类 → 子品类 → SKU）",
+    "移动端一次只展示当前一层，已选路径收进上方路径条，靠路径条回退而不是靠「上一级」按钮",
+    "点某一级后下一级选项随之变化：面板始终只渲染当前一层，选择即下钻",
+    "点路径条里的上级可回退：回退到该级并重新展示它的下一级；末位是「你在这里」的锚点，不可点",
+    "级数不写死：路径条按已选深度渲染，两级与四级用同一份实现",
+    "选项行高与路径条各项热区均不小于 44px"
+  ],
+  "doNotInvent": [
+    "层级数据源（由宿主传入 options 树，本组件不发明省市区库）",
+    "搜索定位某级选项（那需要把整棵树拍平，是独立的检索组件）",
+    "异步逐级加载的占位与重试流程",
+    "多选（一次选多条路径）"
+  ],
+  "unknowns": [
+    "路径很长时路径条是折行还是横向滚动（当前折行，四级以上会占两行）",
+    "叶子被选中后是否要自动收起浮层（当前不自动收，等宿主决定）",
+    "是否要保留「上一级」按钮作为路径条之外的第二种回退入口"
+  ],
+  "interaction": [
+    "点某一级后下一级选项随之变化：面板始终只渲染当前一层，选择即下钻",
+    "点路径条里的上级可回退：回退到该级并重新展示它的下一级；末位是「你在这里」的锚点，不可点",
+    "级数不写死：路径条按已选深度渲染，两级与四级用同一份实现",
+    "点到叶子结点后再点同级另一项，会截断更深的层级（改选不会留下旧的深层残留）",
+    "选项行高与路径条各项热区均不小于 44px；选项区滚动容器 -webkit-overflow-scrolling: touch"
+  ],
+  "accessibility": [
+    "mode=panel 根元素 role=\"group\" + aria-label；mode=popup 根元素 role=\"dialog\" + aria-modal=\"true\"",
+    "选项区 role=\"listbox\"，aria-label 随层级变化（如「级联选项 · 城市」），读屏能播报当前在第几级",
+    "选项 role=\"option\" + aria-selected；禁用项写 aria-disabled=\"true\"",
+    "路径条末位写 aria-current=\"true\"，读屏播报「当前项」",
+    "路径条每一项是原生 button（键盘可达），末位用 disabled 让键盘跳过"
+  ],
+  "api": {
+    "source": "implementation",
+    "note": "props / events / slots 为 6 端实现的公共接口（说明文字取自规格对应小节）。字段名与各端源码逐名核对：node tools/verify-mobile-docs.mjs",
+    "requiredNote": "「必传」按严格定义：实现里**没有默认值**时才为 Y（本门禁逐条核对 props 与各端源码的默认值，防止契约与实现脱节）。",
+    "props": [
+      {
+        "name": "mode",
+        "type": "'panel' | 'popup'",
+        "default": "'panel'",
+        "desc": "变体 mode：panel 内嵌在页面里，popup 是底部浮层（规格 §44.3）",
+        "required": false
+      },
+      {
+        "name": "round",
+        "type": "boolean",
+        "default": "false",
+        "desc": "变体 round：浮层靠内容一侧是否切圆角（规格 §44.3）",
+        "required": false
+      },
+      {
+        "name": "showPath",
+        "type": "boolean",
+        "default": "true",
+        "desc": "变体 showPath：是否显示路径条（规格 §44.3）",
+        "required": false
+      },
+      {
+        "name": "open",
+        "type": "boolean",
+        "default": "false",
+        "desc": "状态 open：mode=popup 时浮层是否展开（规格 §44.4）",
+        "required": false
+      },
+      {
+        "name": "closeOnMask",
+        "type": "boolean",
+        "default": "true",
+        "desc": "遮罩点击是否关闭（规格 §44.5）",
+        "required": false
+      },
+      {
+        "name": "value",
+        "type": "Array<string>",
+        "default": "[]",
+        "desc": "当前选中路径，从根到当前级的 value 序列（规格 §44.6）",
+        "required": false
+      },
+      {
+        "name": "options",
+        "type": "Array<string | { label: string, value: string, disabled?: boolean, children?: Array }>",
+        "default": "[]",
+        "desc": "层级数据树（宿主提供，本组件不发明省市区库）（规格 §44.7）",
+        "required": false
+      },
+      {
+        "name": "disabled",
+        "type": "boolean",
+        "default": "false",
+        "desc": "状态 disabled：整块置灰且不响应（规格 §44.4）",
+        "required": false
+      },
+      {
+        "name": "title",
+        "type": "string",
+        "default": "''",
+        "desc": "浮层标题（空串时用默认「选择地区」）（规格 §44.2 cascader__header）",
+        "required": false
+      },
+      {
+        "name": "label",
+        "type": "string",
+        "default": "'级联选项'",
+        "desc": "选项区 aria-label 的前缀，读屏靠它知道这组在选什么（规格 §44.6）",
+        "required": false
+      }
+    ],
+    "events": [
+      {
+        "name": "change",
+        "params": "value: Array<string>",
+        "desc": "路径变化时触发（下钻或回退），回传从根到当前级的 value 序列（规格 §44.5）"
+      },
+      {
+        "name": "confirm",
+        "params": "value: Array<string>",
+        "desc": "mode=popup 时点击确定触发（规格 §44.5）"
+      },
+      {
+        "name": "close",
+        "params": "—",
+        "desc": "mode=popup 时点击取消或遮罩（closeOnMask=true）触发（规格 §44.5）"
+      }
+    ],
+    "slots": [
+      {
+        "name": "default",
+        "desc": "自定义内容（追加在面板之前，常见用法是放触发器）"
+      }
+    ]
+  },
+  "variantClasses": {
+    "mode": {
+      "panel": [
+        ".kole-m-cascader--panel"
+      ],
+      "popup": [
+        ".kole-m-cascader--popup"
+      ]
+    },
+    "showPath": {
+      "true": [],
+      "false": [
+        ".kole-m-cascader--no-path"
+      ]
+    },
+    "round": {
+      "false": [],
+      "true": [
+        ".kole-m-cascader--round"
+      ]
+    }
+  },
+  "demos": [
+    {
+      "id": "levels",
+      "group": "01 组件类型",
+      "title": "逐级下钻",
+      "desc": "点省份后下一级换成城市：面板只渲染当前一层，避免 375px 下横向挤压。",
+      "variant": "mode=panel"
+    },
+    {
+      "id": "popup",
+      "group": "01 组件类型",
+      "title": "底部浮层",
+      "desc": "mode=popup：自带遮罩与确定取消，遮罩点击关闭。",
+      "variant": "mode=popup"
+    },
+    {
+      "id": "back",
+      "group": "02 组件状态",
+      "title": "回退上一级",
+      "desc": "点路径条里的上级即退回该级，重新展示它的下一级；末位是「你在这里」的锚点。",
+      "variant": "状态 selected（路径条回退）"
+    },
+    {
+      "id": "states",
+      "group": "02 组件状态",
+      "title": "禁用项与空态",
+      "desc": "禁用结点置灰并写 aria-disabled；当前级无子项时显示占位文案。",
+      "variant": "状态 disabled | empty"
+    }
+  ],
+  "related": [
+    {
+      "slug": "mobile-picker",
+      "why": "选项之间没有层级关系（城市平铺）时用选择器，不要用级联去拼一棵假树"
+    },
+    {
+      "slug": "mobile-popup",
+      "why": "通用弹出层；mode=popup 本身就是底部浮层，不要在弹出层里再套一层"
+    },
+    {
+      "slug": "cell",
+      "why": "「已选地区」的展示入口用单元格，点开才拉起级联"
+    },
+    {
+      "slug": "mobile-list",
+      "why": "只需要展示一层可选项且不需要回退路径时，列表更轻"
+    },
+    {
+      "slug": "actionsheet",
+      "why": "动作面板面向「点一下即执行」，级联面向「逐级缩小范围再确认」"
+    }
+  ]
+}