UX/Wireframe Planning 是一个面向实现计划与技术需求的线框规划技能，用于判断项目是否涉及 UI/Web 应用工作，并在需要时生成线框规范与可视化线框。
用途 该技能从实现计划和技术需求中检测 React/Web 应用改动。当发现 UI 相关工作时，生成结构化的线框规范以及可视化线框；对于没有前端改动的项目，则在生成一份带有 has_ui_changes: false 的最小规范后自动跳过线框生成步骤。
前置条件 使用前需要以下文件：
- implementation/milestones.yaml 和 implementation/tasks/milestone-m*.tasks.yaml
- requirements/technical-requirements.yaml
- requirements/business-requirements.yaml（用于需求引用）
使用方式 命令：/ux-wireframe-planning [base-directory] 如果未提供基础目录，技能会通过查找 implementation/milestones.yaml 自动检测。
处理流程 Phase 1：检测 读取技术需求，检查前端技术（React、Next.js、Vue、Angular、Svelte、Remix、Astro，以及技术栈中任何 frontend 或 ui 部分）；扫描实现计划任务文件，查找创建/修改 .tsx、.jsx、.vue、.svelte 文件的任务，提及 component、page、route、layout、navigation、modal、form、table 的任务，以及带有 ui_component: true 标签的任务；检查业务需求中涉及用户交互的用例和作为最终用户的角色。
Phase 2：决策 如果所有信号均未检测到 UI 改动：生成 ux/wireframe-spec.yaml，其中 has_ui_changes: false，输出检测摘要，步骤完成并自动跳过线框生成。如果检测到 UI 改动：进入 Phase 3。
Phase 3：线框规范生成 从检测到的 UI 任务和需求中提取页面与组件：从任务中提到的路由识别不同页面/屏幕；为每个页面识别组件（表单、表格、导航等）；为每个组件记录状态和交互；映射页面之间的用户流程；写入 ux/wireframe-spec.yaml。输出格式参见 references/example.yaml。
Phase 4：线框文件创建（组件 + 页面） 所有线框内容——变量、可复用组件和页面框架——都放在单个自包含的 .pen 文件 ux/wireframes.pen 中。重要：Pencil 不支持跨文件组件引用，每个 .pen 文件必须内联包含自己的组件定义；尝试导入库文件并通过 ref 引用其组件会产生 broken_ref 节点。因此所有组件和页面都放在一个文件中。线框文件包含三个部分：变量（设计令牌，颜色、间距、排版、尺寸，全部以 wf- 为前缀）；可复用组件（线框原语，如 page-shell、header、sidebar、card、form-field、button、table 等，作为顶层子节点并设置 reusable: true）；页面线框（顶层 ref 节点，实例化文件内组件）。完整变量目录、组件定义和插槽映射参见 references/pencil-wireframe-kit.md。通过 MCP 工具创建文件时，先使用 pencil_set_variables 设置所有设计令牌，再使用 pencil_batch_design 创建可复用组件作为顶层子节点。
Phase 5：逐页线框生成 为线框规范中的每个页面，向同一个 .pen 文件添加页面框架。一致性规则（强制）：单文件——所有组件和页面线框放在一个 ux/wireframes.pen 文件中（无跨文件引用）；无硬编码颜色——所有填充/描边/文本使用 $wf-* 变量；已知组件不使用原始形状——使用引用文件内组件的组件实例（type: "ref"）；使用组件结构——用 wf-page-shell 组合页面并填充其子插槽；尺寸一致——页面宽度使用字面量 1440、高度使用 900（Pencil 会静默丢弃 width/height 属性上的 $wf-* 变量引用）；为所有内容加标签——用实际内容名称覆盖所有后代标签；状态注释——在定义组件状态处添加 wf-state-badge。生成模式使用 pencil_batch_design 向同一文件添加页面线框，并使用 pencil_export_nodes 导出该页面的 PNG 预览。
Phase 6：更新线框规范 生成所有线框后，更新 ux/wireframe-spec.yaml：为每个线框条目设置 pen_file: "ux/wireframes.pen"（所有页面同一文件）；为每个导出的 PNG 设置 preview_png 路径；设置 status: generated。
Phase 7：校验 运行：sherpy validate -t wireframe-spec -f ux/wireframe-spec.yaml --strict
Phase 8：一致性检查清单 完成前验证：ux/wireframes.pen 包含所有已定义变量；目录中所有组件作为顶层可复用节点存在；所有页面线框引用文件内组件（无跨文件引用）；无硬编码颜色值（全部使用 $wf-* 变量）；每个页面使用 wf-page-shell 作为根组件；每个组件实例都有覆盖的标签；在规范定义状态处存在状态徽章；为所有线框导出 PNG 预览。
输出文件 ux/ 目录下包含：wireframe-spec.yaml（结构化规范）、wireframes.pen（所有组件 + 页面线框，自包含）、PAGE-001.png、PAGE-002.png 等导出的预览。
自审 完成后输出线框规划摘要，包括：是否检测到 UI 改动、检测摘要、页面数、组件数、生成的线框数，以及按页面列出的组件数量和线框状态（✓/pending）。下一步为继续到实现计划审查。
适用场景 适用于需要从实现计划和技术需求中自动识别 UI 工作并生成线框规范与可视化线框的项目，尤其是使用 React 等前端技术的 Web 应用开发流程。
限制 该技能依赖特定的前置文件结构；Pencil 不支持跨文件组件引用，所有组件必须内联在单个 .pen 文件中；Pencil 会静默丢弃 width/height 属性上的 $wf-* 变量引用，因此页面尺寸需使用字面量 1440 和 900；未提供基础目录时依赖自动检测 implementation/milestones.yaml。