persagy-vant 0.0.35 → 0.0.37

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "persagy-vant",
-  "version": "0.0.35",
+  "version": "0.0.37",
   "description": "Lightweight Mobile UI Components built on Vue",
   "main": "lib/vant.cjs.js",
   "module": "es/index.mjs",

package/skills/use-persagy-vant/SKILL.md

@@ -13,9 +13,10 @@ description: 使用 Persagy Vant 为 Vue 3 移动端业务页面规划、实现
 2. 阅读 `references/design-interaction-baseline.md`，将其中适用的设计、状态和反馈规则落实到页面；如与产品需求冲突，以明确的产品需求为准并说明差异。
 3. 阅读 `references/business-component-catalog.md`，按用户任务先确定业务组件；再从 `references/component-catalog.md` 补齐基础组件。
 4. 按 `references/component-documentation.md` 的查阅流程读取每个被选中组件的 README 和 demo：在组件库仓库中使用 `packages/persagy-mobile/src/<component>/README.zh-CN.md`，在业务项目中使用 `node_modules/persagy-vant/es/<component>/README.zh-CN.md`。涉及视觉、插槽或类型扩展时，同时查阅 `var.less`、类型定义和 demo；API、事件、插槽和导入方式均以这些资料为准。
-5. 按 `references/page-recipes.md` 组合页面，补齐加载、空数据、错误、禁用和提交中状态。用户要求“审查并优化当前页面”或语义等同的 UI 优化时，默认按 `references/reuse-policy.md` 的非侵入式优化规则执行：不得改变已有接口、请求/响应数据、字段映射、数据内容或业务事件。
-6. 无论是单个页面审查/优化，还是从 0 到 1 的页面规划与实现，页面组件覆盖率均必须不低于 `90%`。将组件复用清单中的组件职责视为页面覆盖基线：优先保持组件原样；页面差异先使用公开 Props、事件、插槽、Less 变量或其他已有组件组合实现，不得复制组件内部 DOM、样式或私有逻辑，也不得自行覆盖组件样式。
-7. 输出或提交前，按 `references/reuse-policy.md` 和 `references/design-interaction-baseline.md` 完成自查，并附上“组件复用清单”“规范落实项”“业务与数据兼容核查”和“组件覆盖率”。组件复用清单必须按 `references/component-documentation.md` 使用官网中文名称和可点击的组件展示链接；未达到 `90%` 时，必须记录覆盖率缺口并反馈给产品经理，说明需要优化的组件变量或建议新增的组件，供其反馈组件库维护方；未经产品经理明确确认例外，不得作为合规页面交付。
+5. 阅读 `references/component-variant-selection.md`，针对每个可见或可交互 UI 单元，从该组件模拟器/README 的示例中选定最贴近当前页面的具体样式与变量组合；不得仅按组件名称套用基础示例。
+6. 按 `references/page-recipes.md` 组合页面，补齐加载、空数据、错误、禁用和提交中状态。用户要求“审查并优化当前页面”或语义等同的 UI 优化时，默认按 `references/reuse-policy.md` 的非侵入式优化规则执行：不得改变已有接口、请求/响应数据、字段映射、数据内容或业务事件。
+7. 无论是单个页面审查/优化，还是从 0 到 1 的页面规划与实现，页面组件覆盖率均必须不低于 `90%`。将组件复用清单中的组件职责视为页面覆盖基线：默认保持模拟器示例与组件原样，只使用其既有 Props、事件、插槽和样式变体完成搭建；未经产品经理明确提出具体样式调整，不得改动 Less/CSS 变量、覆盖组件视觉或自行定制组件样式。
+8. 输出或提交前，按 `references/reuse-policy.md`、`references/design-interaction-baseline.md` 和 `references/component-variant-selection.md` 完成自查，并附上“组件复用清单”“组件变体选型”“规范落实项”“业务与数据兼容核查”和“组件覆盖率”。组件复用清单必须按 `references/component-documentation.md` 使用官网中文名称和可点击的组件展示链接；未达到 `90%` 时，必须记录覆盖率缺口并反馈给产品经理，说明需要优化的组件变量或建议新增的组件，供其反馈组件库维护方；未经产品经理明确确认例外，不得作为合规页面交付。
 
 ## 组件缺口
 

package/skills/use-persagy-vant/references/component-documentation.md

@@ -5,8 +5,8 @@
 ## 页面实现时的查阅流程
 
 1. 从 `business-component-catalog.md` 和 `component-catalog.md` 确定候选组件。
-2. 阅读所选组件的 `README.zh-CN.md`：先确认适用场景和演示，再确认实现所需的 Props、事件与插槽。
-3. 需要视觉适配时，先保持组件默认样式；仅在需求确有差异时读取该组件 `var.less` 中的公开变量，再检查 Props、插槽或其他已有组件组合。不得通过页面 CSS 覆盖组件内部样式。需要复杂数据、双向绑定或事件时，读取类型定义；需要组合方式时，读取 demo。新增的 `content-panel`、`title-bar`、`material-action-bar`、`material-detail`、`material-display-bar` 必须在使用前完整执行此步骤。
+2. 阅读所选组件的 `README.zh-CN.md`：先确认适用场景和全部代码演示标题，再确认实现所需的 Props、事件与插槽；模拟器中的每个示例都视为可选变体，而不是只看“基础用法”。
+3. 按 `component-variant-selection.md` 从示例中选择最贴近当前页面语义和视觉结构的一种变体，并记录示例标题与实际使用的公开能力。默认保持该变体的原始样式，不读取或修改 `var.less` 以进行视觉适配；只有产品经理明确提出具体样式调整后，才读取该组件 `var.less` 中与该调整直接相关的公开变量。不得通过页面 CSS 覆盖组件内部样式。需要复杂数据、双向绑定或事件时，读取类型定义；需要组合方式时，读取 demo。新增的 `content-panel`、`title-bar`、`material-action-bar`、`material-detail`、`material-display-bar` 必须在使用前完整执行此步骤。
 4. 仅使用已文档化的公开能力。README 未列出的能力不得假定存在；无法满足时按 `component-gap-template.md` 输出缺口说明。
 
 ## 需求到资料的映射
@@ -15,7 +15,7 @@
 | --- | --- |
 | 选择合适组件 | 组件目录、业务组件目录、对应 README 的介绍和 demo |
 | 配置交互、按钮、校验或回调 | README 的 Props、Events、Slots、类型定义 |
-| 调整间距、色彩、尺寸或层级 | README 的样式变量和 `var.less` |
+| 产品经理明确提出组件样式调整 | README 的样式变量和 `var.less`；仅查阅和修改与该明确要求直接相关的公开变量 |
 | 组合多个组件完成页面 | 页面配方、各组件 demo |
 | 评估是否需要新组件 | 组件目录、README、组件缺口模板 |
 
@@ -24,7 +24,7 @@
 在需求中写明业务目标和涉及组件，并要求先读组件说明。例如：
 
 ```md
-使用 $use-persagy-vant 实现工单详情页。先读取 `info-card`、`label`、`bottom-action-bar` 的组件说明和 demo；按其公开 Props、事件、插槽与样式变量实现需求，不新增同类组件。
+使用 $use-persagy-vant 实现工单详情页。先读取 `info-card`、`label`、`bottom-action-bar` 的组件说明和 demo；按其已有公开 Props、事件、插槽与模拟器示例实现需求，不新增同类组件，也不调整组件样式。
 ```
 
 无需指定组件时，也可以要求 AI 先完成选型：

package/skills/use-persagy-vant/references/component-variant-selection.md

@@ -0,0 +1,53 @@
+# 组件变体与模拟器示例选型
+
+组件选型不止确定“使用哪个组件”，还必须确定“使用该组件的哪个模拟器示例、哪些公开 Props/插槽/变量”。目标是用最贴近页面现状与产品意图的原生示例完成界面，避免把所有场景都退化为基础样式或用自定义 CSS 模拟示例变体。
+
+## 必经流程
+
+对每个可见或可交互 UI 单元执行以下流程：
+
+1. **识别页面意图**：记录该单元是信息展示、进入下一层、单选/多选、状态回显、带头像的人员/对象、带标签的分类、紧凑操作入口，还是其他明确目的；同时识别已有页面的内容层级、行数、左右信息、选中态和分组关系。
+2. **浏览完整示例集**：读取目标组件 README 的所有“代码演示”标题，并查看对应 demo。模拟器展示的变体、变量和样式示例均是候选方案；不得只查看基础用法后立即实现。
+3. **比较候选变体**：从同一组件中至少比较语义接近的示例；按“业务语义优先、信息层级其次、现有视觉结构再次、最少公开扩展最后”的顺序选择。不得为了视觉相似而选择错误的交互语义，例如把可多选项实现成单击跳转项。
+4. **使用公开能力落地**：先原样复用所选示例的 Props、事件、插槽和预置样式。未经产品经理明确提出具体样式调整，不得修改 Less/CSS 变量或组件视觉；不要复刻模拟器 DOM、私有 class 或自行拼出近似控件。
+5. **记录决策**：每种实际使用的组件变体都写入交付中的“组件变体选型”，使产品经理能从组件官网/模拟器复查效果。
+
+## 选择准则
+
+- 有交互含义的变量优先于纯视觉变量：例如选择状态、导航箭头、输入/回显、禁用与加载必须与业务行为一致。
+- 信息密度与行数必须匹配：单行信息不用三行样式；标题、编号、位置等稳定三层信息才用三行样式。
+- 内容归属决定元素位置：影响当前项选择的控件使用前置/后置选择；对象身份使用头像；分类或状态集合使用标签组；辅助说明用 `label`、`note` 或 `description`，不要滥用标题插槽。
+- 页面层级优先通过已有容器变体表达：例如卡片内容、分组标题、灰色承载区、圆角卡片，先检查容器组件的示例和变量，再考虑页面级布局。
+- 多个示例都可用时，选择无需改动组件视觉、公开能力最少且后续维护最清晰的一种；在清单中说明取舍。
+
+## 单元格的示例匹配
+
+【单元格】的模拟器拥有大量变体。按下列业务意图选用对应 README 示例，而不是固定使用基础单元格：
+
+| 页面意图 | 优先模拟器示例 | 典型公开能力 | 不适用时机 |
+| --- | --- | --- | --- |
+| 普通标题与回显值 | 基础用法 | `title`、`value`、`label` | 有明确选择状态或三层稳定信息时 |
+| 点击进入详情、选择面板或下一层 | 展示箭头 / 扩展元素「右图标」 | `is-link` 或 `right-icon="arrow"`、`click`、`value`/`note` | 仅展示不可操作信息时 |
+| 多选、单选列表项 | 扩展元素「前置选择」或「后置选择」 | `left-select` / `right-select`，并连接真实选择状态 | 点击仅为路由跳转或字段录入时 |
+| 人员、设备等有识别图片的对象 | 扩展元素「头像」 | `avatar` 或 `right-avatar` | 图片不承担对象识别、仅为装饰时 |
+| 强调关键条目或分组内重点字段 | 标题加粗 / 前置小蓝标 | `title-bold` / `blue-mark` | 普通内容项；不能替代页面一级标题组件 |
+| 标题旁呈现多个分类/状态 | 扩展元素「标签组」 | `tags` | 单一状态可用右侧值或状态组件时 |
+| 标题 + 一条辅助信息 | 双行图标单元格 / 基础用法带 `label` | `label`、`icon`/`right-icon`、`center` | 需要固定三层业务信息时 |
+| 标题、编号/位置、描述三层信息 | 三行样式 | `three-line`、`title`、`label`、`description`、可选 `value`/`right-icon` | 内容只有一到两层时 |
+| 辅助信息在右侧且可独立操作 | 加粗与可点击备注 | `note`、`note-bold`、`note-clickable`、`click-note` | 整行都应作为唯一触发器时 |
+| 成组的列表或录入入口 | 分组标题 / 卡片风格 | `cell-group` 的 `title`、`inset`、`gray-card` | 页面规范要求使用【背景】或其他业务卡片承载时，优先服从该规范 |
+
+“前置选择”与“后置选择”由选择动作的视觉归属决定：选择控件与标题同属一项、需要先看到状态时使用前置；文本信息为主、选择控件作为结果或批量操作时使用后置。若现有页面无法明确判断，先保留原有交互位置并在选型记录中说明。
+
+## 交付格式
+
+在“组件复用清单”后增加以下内容；同一变体可合并为一项，不必按每一行重复：
+
+```md
+## 组件变体选型
+- [单元格](https://persagy-vant-ai.netlify.app/#/zh-CN/cell)：模拟器示例「后置选择」；用于工单批量选择，使用 `right-select` 绑定原有选中状态。未采用「展示箭头」，因为该行不是跳转入口。
+- [单元格](https://persagy-vant-ai.netlify.app/#/zh-CN/cell)：模拟器示例「三行样式」；用于设备条目，使用 `three-line`、`title`、`label`、`description` 和 `right-icon="arrow"` 呈现名称、编号、位置与详情入口。
+- <官网中文组件名>：模拟器示例「<README 中的准确示例标题>」；<页面意图>，使用 `<实际 Props/插槽/变量>`；<未选其他示例的关键原因>。
+```
+
+若 README/demo 没有能语义匹配的示例或公开能力，不创建相似自定义结构，也不得自行调整组件样式以强行匹配；在组件缺口记录中说明已评估的示例、不能满足的原因和建议新增的变体/API。仅当产品经理明确提出具体样式调整时，才可在其确认范围内使用 README 已文档化的公开样式变量。

package/skills/use-persagy-vant/references/reuse-policy.md

@@ -11,11 +11,13 @@
 
 凡调用本 Skill 的页面任务，不论是单个页面审查/优化、已有页面改造，还是从 0 到 1 的页面规划与实现，页面组件覆盖率均必须不低于 `90%`。覆盖率以“由 Persagy Vant 组件、业务组件或其公开插槽承载的可见/可交互 UI 单元 ÷ 页面全部可见/可交互 UI 单元”计算；纯页面根容器、数据循环和接口/状态适配不计为自定义 UI 单元。
 
-产品经理确认组件复用清单后，清单中的组件和职责进一步作为页面覆盖基线。保持组件默认视觉和交互，除非产品经理明确要求变更。
+组件库演进目标是让其既有组件、Props 与模拟器样式变体覆盖不少于 `90%` 的业务场景，使产品无需新建自定义组件或二次修改组件视觉。页面任务中无法以原生能力完成的内容必须作为组件缺口回流，不得以临时自定义组件或样式覆盖掩盖缺口。
 
-1. 先使用组件公开 Props、事件、插槽和 Less/CSS 变量；再组合其他已有组件。原页面中与组件不同的元素、字段或展示需求，优先通过这些公开能力实现，不自行编写同类结构或样式。
-2. 禁止通过页面 CSS 覆盖组件内部 DOM、私有 class 或默认视觉；禁止为匹配旧页面手写按钮、字段、上传、选择、标题、列表、面板等已有组件能力。仅允许为页面根布局、组件间间距和文档明确的公开扩展点编写最小样式。
-3. 如果采用组件默认样式、公开变量、插槽和已有组件组合仍无法覆盖需求，停止扩大页面自定义样式；按 `component-gap-template.md` 输出缺口，明确建议优化的组件变量或新增组件，并反馈给产品经理，由产品经理反馈组件库维护方。
+产品经理确认组件复用清单后，清单中的组件和职责进一步作为页面覆盖基线。保持组件默认视觉和交互；模拟器中的每个示例、样式变体和变量组合均为已校准方案。未经产品经理明确提出需要调整的具体样式与目标，不得修改组件默认视觉、Less/CSS 变量或组件内部样式。
+
+1. 先使用组件 README/demo 已展示的公开 Props、事件、插槽与样式变体，再组合其他已有组件。原页面中与组件不同的元素、字段或展示需求，优先通过这些已校准能力实现，不自行编写同类结构或样式；默认不改动 Less/CSS 变量。
+2. 禁止通过页面 CSS 覆盖组件内部 DOM、私有 class、默认视觉或公开样式变量；禁止为匹配旧页面手写按钮、字段、上传、选择、标题、列表、面板等已有组件能力。仅允许为页面根布局、组件间间距和文档明确的非组件视觉扩展点编写最小样式。
+3. 如果采用组件默认样式、模拟器既有变体、公开 Props/插槽和已有组件组合仍无法覆盖需求，停止扩大页面自定义样式；按 `component-gap-template.md` 输出缺口，明确建议优化的组件变量或新增组件，并反馈给产品经理，由产品经理反馈组件库维护方。仅在产品经理明确提出具体调整并确认后，才可使用已文档化的公开样式变量实现该调整。
 4. 交付前列出组件覆盖率、计算范围、使用的公开变量/插槽，以及保留的页面级样式；覆盖率低于 `90%` 时，必须在交付说明中附上“组件覆盖率缺口记录”并反馈给产品经理。只有产品经理明确确认例外后，才可交付当前页面；该记录作为后续优化变量或新增组件、使页面达到 `90%` 的输入。
 
 ## 当前页面审查与优化：非侵入式规则
@@ -35,6 +37,7 @@
 - 禁止拷贝组件源码、依赖组件私有 DOM/class，或用 CSS 覆盖内部结构以改变交互。
 - 禁止臆造组件 props、事件、插槽、类型或主题变量。
 - 禁止在产品经理确认组件复用清单后，自行修改组件默认样式或以页面 CSS 覆盖组件内部样式。
+- 禁止为了贴近旧页面、个人判断或视觉偏好，修改组件的 Less/CSS 变量、默认色彩、间距、圆角、字号、边框或状态视觉；产品经理未明确提出具体调整时，必须使用模拟器已提供的原始样式。
 
 ## 允许的页面代码