aurora-admin/.design_library/kole-ui-mobile/spec/parts/_SUBTASK-CONTRACT.md

移动端组件 · 子任务共享约定（S7-P23 批次 A 起）

给子 agent 的硬约束。开工前逐条读完，任何一条不满足即视为未完成。 本文件与 .design_library/kole-ui-mobile/spec/移动端规格.md（冻结规格）、 .design_library/kole-ui-mobile/components/<slug>.json（既有 18 份契约）一起构成工作依据。 权威文档：仓库根 PLATFORMS.md（平台 × 端两轴 + 隔离规则）。

---

一 · 你要产出什么（6 个文件 + 1 段规格 + 1 份契约）

工作目录：C:\Users\12914\Desktop\组件规范第一套

#	路径	说明
1	frameworks-mobile/<Prefix>.css	样式。只引用 --kole-* 或 --kole-m-* 令牌，不得出现硬编码 hex；类名只能是 kole-m-<name> 或状态类 is-<state>
2	frameworks-mobile/<Prefix>.html	演示页。必须含 .demo 容器；每个演示块包成 <section class="demo-block" data-demo="<id>">；文件末尾必须带 ?demo=<id> 单块过滤脚本（照抄既有演示页的写法）
3	frameworks-mobile/<Prefix>.jsx	React 端。export default function X({...})，形参即 props
4	frameworks-mobile/<Prefix>.vue3.vue	Vue 3 端，<script setup> + defineProps({...}) + defineEmits([...])，样式 <style src="./<Prefix>.css"></style>
5	frameworks-mobile/<Prefix>.vue2.vue	Vue 2 端，props: {...} + $emit，name: 'KoleM<Prefix>'
6	frameworks-mobile/<Prefix>.uniapp.vue	uni-app 端。只能用 uni 基础组件（view/text/input/scroll-view/image…）+ @tap / @touch*；禁止 document / window / PointerEvent / addEventListener('pointer…')；尺寸用 rpx（750rpx = 视口宽度，88rpx = 44px @375pt）；样式里必须出现 --kole-m- 令牌覆盖
7	.design_library/kole-ui-mobile/spec/parts/<slug>.md	规格片段（见第二节格式）。只写你这几个组件的节，不要动 移动端规格.md
8	.design_library/kole-ui-mobile/components/<slug>.json	契约（见第三节字段表）。文件名用 你被分配的 slug，一字不改

不要改 index.json（索引由主 agent 统一合并）、不要改 site/m/**、tests/mobile/**（生成物，由 node tools/build-mobile.mjs 产出）、不要改其它组件的任何文件。

---

二 · 规格片段格式（逐字照此结构，一节一个组件）

## <编号> · <中文名> <English>

### <编号>.1 用途
<一句话：这个组件解决什么问题；移动端场景下与桌面端的差别>

### <编号>.2 结构（anatomy）
- `字段名`：说明
（4~6 条，字段名用反引号，是后面契约 anatomy 的来源）

### <编号>.3 变体维度
- `维度名`：`取值1` / `取值2` / `取值3`
（2~3 个维度，取值必须与实现里的类名一一对应）

### <编号>.4 状态
- default：常态
- <其它状态>：说明

### <编号>.5 交互与触控
- <点击/滑动手势、热区尺寸、动效时值等，逐条可验证>

### <编号>.6 无障碍
- <语义角色、aria-*、键盘/读屏行为>

### <编号>.7 doNotInvent
- <明确不许发明的部分，2~4 条>

### <编号>.8 unknowns
- <规格未定项，2~3 条>

编号从 19 开始连续（现有规格到 §18），主 agent 会把你的片段按编号拼进 移动端规格.md。

---

三 · 契约字段（缺一个字段，门禁就红）

{
  "schemaVersion": 1,
  "sourceKind": "authored-spec",
  "provenance": "authored-in-repo",
  "specFile": "spec/移动端规格.md",
  "specSection": "<编号> · <中文名> <English>",
  "confidence": "high",
  "slug": "<分配的 slug>",
  "name": "<中文名> <English>",
  "semanticTypeCandidates": ["…", "…"],
  "variantDimensions": [{ "name": "…", "values": ["…"] }],
  "representativeVariants": [{ "<维度名>": "<取值>", "label": "<中文标签>" }],
  "anatomy": { "字段名": "说明" },
  "structurePatterns": { "维度名": "取值说明" },
  "usageHints": ["…（逐字取自规格 §x.1~§x.5，5 条左右）"],
  "doNotInvent": ["…"],
  "unknowns": ["…"],
  "interaction": ["…（逐字取自规格 §x.5）"],
  "accessibility": ["…（逐字取自规格 §x.6）"],
  "api": {
    "source": "implementation",
    "note": "props / events / slots 为 6 端实现的公共接口（说明文字取自规格对应小节）。字段名与各端源码逐名核对：node tools/verify-mobile-docs.mjs",
    "requiredNote": "「必传」按严格定义：实现里**没有默认值**时才为 Y（本门禁逐条核对 props 与各端源码的默认值，防止契约与实现脱节）。",
    "props": [{ "name": "…", "type": "…", "default": "…", "desc": "…（规格 §x.y）", "required": false }],
    "events": [{ "name": "…", "params": "…", "desc": "…" }],
    "slots": [{ "name": "default", "desc": "…" }]
  },
  "variantClasses": { "<维度名>": { "<取值>": [".kole-m-xxx--yyy"] } },
  "demos": [{ "id": "…", "group": "01 组件类型", "title": "…", "desc": "…", "variant": "…" }],
  "related": [{ "slug": "<真实存在的 slug>", "why": "<何时用它而不是本组件>" }]
}

会被门禁逐条核对的四件事（写错必红）：

1. variantClasses 里数组中的每个 .kole-m-xxx 类名、每个 --kole-m-xxx 变量，必须在你写的 <Prefix>.css 里真实出现（类名按 .name 精确匹配；变量要写成 --name: 定义）。
2. api.props 的每个 name 必须在你写的 jsx / vue3 / vue2 / uniapp 四端源码里都能提取到；反过来，源码里多出来的形参也必须在契约里登记。
   • React 端：events 按 onXxx 形式出现在形参里（如事件 click → 形参 onClick）；slots.default → children；具名插槽 → 同名形参（如 actions）。
   • required: true 的 prop 必须在四端实现里都没有默认值；required: false 的必须都有默认值。拿不准就一律 required: false 并给默认值。
3. demos[].id 必须与演示页里的 data-demo="<id>" 双向一致（契约有的演示页要有，演示页有的契约要登记），且每个演示的代码块非空。
4. related[].slug 必须是真实存在的组件：现有 18 个 slug 是 navbar tabbar actionsheet pullrefresh swipecell mobile-button cell mobile-divider mobile-badge mobile-tag mobile-popup mobile-toast mobile-dialog mobile-grid mobile-steps mobile-noticebar mobile-numberkeyboard mobile-datepicker； 你可以引用同批次其它组件的 slug（见你的派单）。

演示页可分块预览：每个 data-demo 块在文档站会被单独渲染成 375 宽的预览帧，所以每块要能独立成立（不要依赖前一块的 DOM 或上一个演示留下的状态）。

---

四 · 提交前必须自己跑（把输出原样贴进报告）

cd "C:/Users/12914/Desktop/组件规范第一套"
# 1) 语法：脚本与三端 SFC
node --check tools/build-mobile.mjs
node -e "for (const f of ['<Prefix>.jsx','<Prefix>.vue2.vue','<Prefix>.vue3.vue','<Prefix>.uniapp.vue']) { const s=require('fs').readFileSync('frameworks-mobile/'+f,'utf8'); const m=s.match(/<script[^>]*>([\s\S]*?)<\/script>/); if(!m) { console.log(f+': 无 script 段'); continue; } require('fs').writeFileSync('/tmp/_x.mjs', m[1]); require('child_process').execFileSync(process.execPath,['--check','/tmp/_x.mjs']); console.log(f+': script OK'); }"

# 2) uni-app 静态门禁（会检查你那一端：SFC 三段 / 禁 DOM / 手势必须 touch / rpx / 前缀）
node tools/verify-uniapp.mjs

# 3) 演示页结构自检（section 配平 + data-demo 与契约一致 + 过滤脚本在）
node -e "
const fs=require('fs');
const ct=JSON.parse(fs.readFileSync('.design_library/kole-ui-mobile/components/<slug>.json','utf8'));
const h=fs.readFileSync('frameworks-mobile/<Prefix>.html','utf8');
const ids=[...h.matchAll(/data-demo=\"([a-z0-9-]+)\"/g)].map(m=>m[1]);
console.log('演示页 data-demo:', ids.join(','));
console.log('契约 demos:', ct.demos.map(d=>d.id).join(','));
console.log('过滤脚本:', h.includes('demo-single') ? 'OK' : '缺');
"

注意：verify-mobile-docs.mjs（契约 API ↔ 源码逐名一致）与 build-mobile.mjs 由主 agent在合并索引后统一跑；你只要保证上面三步通过，并把 api.props 与四端源码逐名对齐。

---

五 · 报告格式（三分型，不要模糊表述）

DONE | PARTIAL | BLOCKED
- 产出文件（逐条列绝对路径 + 行数）
- 上表 4 条硬约束的**自检输出原样粘贴**
- 未做 / 未验证的部分（写明原因）
- 发现的仓库问题（不要在任务里顺手修，报给我）

禁止：写 已完成 而不给自检输出；把「没跑」说成「应该没问题」；改本约定文件或 index.json。