canvas-design-decomposition

Canvas 设计拆解

强制触发条件（先加载此技能）

在提出组件库的组件结构、编写实现计划或实现组件之前，必须先加载并遵循此技能；如果你正在规划 UI 应如何拆分为 Canvas 组件（组件库、区块或完整页面），即使用户只要求提供计划或拆解，也同样适用。在你即将构建、添加或脚手架搭建组件时也适用（见下文）。以下任一情况都视为触发条件：

• 构建或添加 Canvas 组件：在 src/components/ 下创建新文件夹，编写 component.yml 和入口文件（React 项目中的 index.jsx/.tsx；无头项目中使用框架对应的文件），根据工单或规格搭建组件脚手架，根据设计编写区块，或实现命名区块（hero、footer、card 等）。除非任务只是对现有稳定 API 进行简单的一行调整，否则请先完成拆解，再编写 schema 或实现代码，确保命名、插槽、变体和复用保持一致。
• **设计或演进 Canvas 组件库：**确定区域命名、复用方式、props/插槽和粒度，无论依据的是文件、网站还是对话。
• 消息中包含 Figma URL（figma.com/design、figma.com/make 或分支 URL），或明确提及与 Figma 相关的 node-id / 画框。
• 真实来源是用于指导布局或组件的现有网站、截图、抓取页面或参考 URL（需要抓取实时 URL 时，配合使用 nebula-scrape-url）。
• 来源是纯文本或生成式内容：书面简报、Markdown 规格，或 AI 生成/提示词生成的设计（布局描述、文字版线框图、聊天中生成的组件列表）。即使没有像素图，仍须执行阶段 A——对输入进行分类并列出未知项。
• 用户要求根据任何素材或描述实现、构建、匹配、重现或规划实现某个设计、画框、屏幕或页面。

不要跳过（常见失败模式）

• 从零开始的工作也不例外。从头实现一个新页面或 Figma 画框仍须遵循此技能——在确定实现细节之前，先将设计映射为连贯的组件树、props 和插槽。
• 仓库中的草稿文件不能替代此流程。现有的 pages/*.json、src/components/ 下的不完整组件或抓取到的资源，或许可以作为有用的起点，但不能替代阅读此技能，也不能替代针对当前素材完成阶段 A–G。请根据拆解核对草稿代码；不要假定之前已完成拆解。
• 计划也算。如果用户只要求提供实现计划，仍须加载此技能，并在处理像素或走工具捷径之前，概述区域 → 组件 → 放置位置。

自动化工具输出（例如 Figma MCP 参考 JSX、HTML 导出或生成的代码）是此工作流的输入，不能替代完成阶段 A–G。

将设计素材转化为稳定的组件模型：区域、组件树、prop 与插槽的取舍，以及粒度检查。如果没有为每个节点草拟 props 和插槽，拆解就不完整——Canvas 作者通过此 API 与组件树交互，因此应在规划结构时一并规划，而不是等到实现后再做。

规划时，不要局限于单个画框或工单：思考每个部分还可能出现在什么地方，以及哪些内容会有所不同（文案、子项、variant）。优先使用可复用的 machineName、用于可变区域的插槽，以及通过 variant 实现的预设，而不是一次性名称或将某个活动内容写死的 props。

在此工作流中不要实现像素或编写 component.yml——先完成结构以及 props/插槽草案，再交接。

技能顺序

1. 本技能 — 工作流、树结构和交接。
2. canvas-component-composability — 共享 props/slots 规则、可重复内容和粒度检查。
3. canvas-component-metadata — 精确的 component.yml 架构。
4. canvas-component-definition — 文件夹约定、模拟数据和命名规范。
5. implement-design — 像素级还原 适用于源文件为 Figma 的情况，并且必须在树结构锁定后进行（使用时需要 Figma MCP）。对于非 Figma 来源，根据已锁定的树结构和设计令牌进行实现，无需此步骤；除非用户指定参考 Figma 文件。

关于 Canvas 中的可重复列表/网格，请参阅 canvas-component-composability/references/repeatable-content.md。

输入

在阶段 A 中对来源进行分类。常见类别：

类型	示例
设计工具	Figma 文件、画框导出、FigJam
在线参考	现有生产或预发布网站、竞品 URL
已捕获媒体	截图、PDF、品牌资料
结构化抓取内容	通过工具获取的 HTML/CSS 快照
提示词 / 文本	用户简报、AI 生成的布局说明、Markdown 线框图

可选辅助工具：

• URL 抓取：nebula-scrape-url（不适用于 Figma 或文档）。
• Figma 还原度检查（分解后）： implement-design。

工作流（必需）

按顺序完成阶段 A → G。每个阶段都有一个退出标准。如果 阶段 F 未通过，修正树结构，并仅针对受影响的节点重新运行阶段 E。

阶段 A — 收集输入并确定范围

• 识别输入类型：设计文件（例如 Figma）、在线网站 / 抓取内容、截图， 或纯文本 / 由提示词生成的规格说明。
• 列出未知项：断点、空状态、文案最大长度、媒体宽高比、悬停/焦点/激活状态、无障碍要求。
• 为每项未知内容标注风险：低 / 中 / 高（可能导致结构反复修改）。

退出标准： 已说明输入类型；已列出带风险标注的未知项（即使部分问题尚无答案，也继续工作流）。

阶段 B — 区域图

• 将设计划分为区域（例如页眉、主视觉区、内容区块、侧边栏、 页脚、模态框框架）。
• 为每个区域提供：标签、用途（一句话）、类别 — chrome （外壳）、navigation（导航）或 content（内容）。

退出标准： 按顺序列出区域，并为每个区域标明用途和类别。

阶段 C — 候选组件清单

• 将区域映射到候选 machineName 值（根据 canvas-component-definition 使用 kebab-case 文件夹名称）。
• 优先使用可复用的基础名称；通过 props/组合实现变体，而不是新增组件名称，除非确实只会使用一次。
• 当相同模式出现两次或更多时，标注复用次数。
• 泛化： 对每个候选组件，注明其他可能的使用场景（其他页面、更短的文案、不同的子元素）。如果它只适用于当前屏幕，请重命名或拆分，直到范围可复用。

退出标准： 表格包含候选 machineName、职责、复用次数和父级区域。

阶段 D — 组件树

• 构建父子关系：布局外壳与内容叶节点。
• **布局归属：**多列网格、页面级堆叠和区块包装器应放在面向布局的组件中；除非布局对每个实例都保持不变，否则避免将无关网格写入内容组件。
• 将组件树表示为嵌套大纲或 Mermaid 图（Mermaid 节点 ID：不得包含空格；使用驼峰命名或下划线）。

**退出条件：**组件树涵盖清单中的每一行；明确区分布局与内容角色。

阶段 E — Props 与插槽（逐节点）

必需：每次拆解都必须包含此阶段。Props 和插槽不是事后添加的内容——它们决定编辑者如何使用组件树。对于树中的每个节点，规划：

• **Props：**编辑者应直接设置的配置和简单值（变体、布尔值、短字符串、URL、枚举）。注明用途和大致类型类别（string、boolean、enum、图像/引用）——无需编写最终 YAML。实际的 props 与插槽判定标准、变体与细粒度配置指南，以及 prop 排序，请遵循 canvas-component-composability。此阶段记录决策，不重新定义这些判定标准。
• 插槽：作者可在其中组合子组件或任意区块的区域。注明插槽名称、允许的内容，并说明其为空时的行为（折叠、占位符、最小高度）。
• **实现方式：**在交接文档中记录采用 variants（默认）还是 granular props，并用一句话说明理由。阶段 E 的文档编写规范请参阅 references/props-vs-slots-rubric.md。

**退出条件：**每个节点都有 props/插槽规划，已注明实现方式，并且不会将可重复的富内容子项建模为 props 中的对象数组。

阶段 F — 粒度审查

按照 canvas-component-composability 中的共享粒度检查清单执行。本阶段需依据该共享规则集审查候选组件树并记录结果；不要在此处另建一套拆分/合并判定标准。阶段 F 的审查说明请参阅 references/granularity.md。

• 为每个节点标记通过/不通过，并简要说明理由。
• 如果有节点未通过，请合并、拆分或提取，然后仅对变更的节点重复阶段 E。
• 明确记录有意保留的例外。

**退出条件：**所有节点均通过；或者已明确记录未通过项的理由。

阶段 G — 交接

使用下方模板提交一份 Markdown 文档。将后续步骤指向：

• Schema：canvas-component-metadata
• 组合边缘情况： canvas-component-composability
• 契约和模拟： canvas-component-definition
• Figma 视觉保真度：implement-design （如适用）

**退出条件：**填写完成的模板，可直接粘贴到 issue 或 MR 中。

**此处不涉及：**页面 JSON (canvas-page-definition)、验证运行 (nebula-component-validation)。

输出模板

复制并填写：

## Summary

- **Design source:** (e.g. Figma URL | live URL | screenshots | prompt/spec
  text)
- **Scope:** (single component | section | full page)
- **Version / date:**

## Assumptions and open questions

- ...

## Region map

| Region | Purpose | Class |
| ------ | ------- | ----- |
| ...    | ...     | ...   |

## Component inventory

| machineName (candidate) | Responsibility | Reuse | Parent region | Notes |
| ----------------------- | -------------- | ----- | ------------- | ----- |
| ...                     | ...            | ...   | ...           | ...   |

## Component tree

(Nested list or Mermaid)

## API sketch (per component)

### `machine-name`

**Implementation style:** variants (default) | granular props — one-line
rationale

**Props** (table rows in editor order: **variant first** when there is a single
primary variation enum; **content first** otherwise—then configuration)

| Name (camelCase intent) | Purpose | Required? | Kind (string / bool / enum / …) |
| ----------------------- | ------- | --------- | ------------------------------- |
| ...                     | ...     | ...       | ...                             |

**Slots**

| Slot key | Purpose | Empty behavior |
| -------- | ------- | -------------- |
| ...      | ...     | ...            |

## Granularity audit

| Component / node | Pass/Fail | Notes / fix |
| ---------------- | --------- | ----------- |
| ...              | ...       | ...         |

## Next steps

- [ ] `canvas-component-composability` — edge cases for props/slots,
      repeatability, or granularity
- [ ] `canvas-component-metadata` — draft `component.yml`
- [ ] `canvas-component-definition` — folder, entry file, mocks
- [ ] `implement-design` — Figma fidelity pass (only when matching a Figma file)

延伸阅读

• canvas-component-composability
• references/granularity.md
• references/props-vs-slots-rubric.md
• references/worked-example.md

避免重复

• 不要重述完整的 component.yml 语法——请使用 canvas-component-metadata。
• 不要在此处重述可复用的 props/插槽或粒度规则手册——请链接至 canvas-component-composability。