vapor-ui

Vapor UI 设计技能

说明

步骤 1：识别用户意图并检测版本

并行运行以下检查：

1. 确定用户意图：

   • 组件查询：用户想了解可用组件或特定组件的详情
   • 使用指南：用户需要了解 props、变体或示例代码
   • 模型生成：用户想创建 UI 原型
   • Figma 转换：用户想将 Figma 设计转换为代码

2. 确定 Vapor UI 版本（按优先级排序）：

   1. 用户提供的版本：如果用户指定了版本，直接使用
   2. 从代码库自动检测：

      node scripts/detect-version.mjs [start-path]
      

      输出：CORE: x.x.x 和 ICONS: x.x.x

   组件脚本使用 CORE 版本，图标脚本使用 ICONS 版本。

步骤 2：组件信息

获取组件列表：

node scripts/get-component-list.mjs <VERSION>

示例：node scripts/get-component-list.mjs 1.0.0-beta.12

获取组件详情（props、描述）：

node scripts/get-component-info.mjs <VERSION> <COMPONENT> [PART]

示例：node scripts/get-component-info.mjs 1.0.0-beta.12 avatar

有关组件结构的详细信息，请参阅 references/component-structure.md。

步骤 3：组件示例

获取示例代码：

node scripts/get-component-examples.mjs <VERSION> <COMPONENT> [EXAMPLE_NAME]

示例：node scripts/get-component-examples.mjs 1.0.0-beta.12 avatar default-avatar

步骤 3.5：图标查询

获取图标列表：

node scripts/get-icon-list.mjs <ICONS_VERSION> [search-keyword]

示例：

• node scripts/get-icon-list.mjs 1.0.0-beta.12 - 列出所有图标
• node scripts/get-icon-list.mjs 1.0.0-beta.12 arrow - 搜索包含“arrow”的图标
• node scripts/get-icon-list.mjs 1.0.0-beta.12 --outline - 仅列出轮廓图标
• node scripts/get-icon-list.mjs 1.0.0-beta.12 --filled - 仅列出填充图标

注意：查询图标时，使用 detect-version.mjs 输出中的 ICONS 版本。

步骤 4：模型生成

对于模型生成请求：

1. 运行 get-component-list.mjs，确定可用组件
2. 为每个所需组件运行 get-component-info.mjs，获取其 props
3. 运行 get-component-examples.mjs，了解使用方式
4. 仅使用 Vapor UI 组件生成代码
5. 提供完整且可直接复制粘贴的代码

步骤 5：Figma 设计转换

对于 Figma 转换请求：

1. 解析 Figma URL，提取 file_key 和 node_id：

   https://www.figma.com/design/{file_key}/...?node-id={node_id}
   

2. 使用 MCP 获取设计上下文：

   mcp__figma-dev-mode-mcp-server__get_design_context
     - file_key: 从 URL 中提取
     - node_id: 从 URL 中提取（格式为 "X-Y" 或 "X:Y"）
     - depth: 5（复杂设计可设为更高值）
   

3. 分析节点树：

   • 以 💙 开头的节点：设计系统组件（参见 references/design-system-recognition.md）
   • 自动布局框架：转换为 VStack/HStack/Box/Grid（参见 references/figma-layout-mapping.md）
   • TEXT 节点：提取文本内容

4. 转换布局属性：

   • layoutMode: VERTICAL → VStack
   • layoutMode: HORIZONTAL → HStack
   • itemSpacing → gap 令牌
   • padding* → padding 令牌
   • 完整映射请参见 references/token-mapping.md

5. 识别设计系统组件：

   • 以 💙 开头的节点是 vapor-ui 组件
   • 提取 componentProperties，将变体映射为 props
   • 示例：💙Button，其中 Size: md, ColorPalette: primary → <Button size="md" colorPalette="primary">
   • 重要：布局 props（gap、padding、margin、backgroundColor 等）必须放在 $css prop 内

6. 生成代码：

   • 根据节点树自底向上构建 JSX
   • 使用设计令牌应用样式工具 props
   • 输出可用于生产环境的代码

---

示例

示例 1：组件用法查询

用户：“如何使用 Button 组件？”

操作：

1. 运行 node scripts/get-component-info.mjs 1.0.0-beta.12 button
2. 运行 node scripts/get-component-examples.mjs 1.0.0-beta.12 button
3. 提供属性、变体和示例代码

结果：包含代码示例的完整 Button 用法指南

---

示例 2：生成模型图

用户：“创建一个登录页面模型图”

操作：

1. 运行 get-component-list.mjs，查看可用组件
2. 运行 get-component-info.mjs，查询 text-input、button、card、form
3. 运行 get-component-examples.mjs，查看表单模式
4. 使用 Vapor UI 生成响应式布局

结果：可用于生产环境的登录页面代码

---

示例 3：发现组件

用户：“有哪些表单组件可用？”

操作：

1. 运行 node scripts/get-component-list.mjs 1.0.0-beta.12
2. 筛选输出结果，查找与表单相关的组件（text-input、textarea、checkbox、radio、select 等）

结果：分类列出的表单相关组件

---

Figma 转换示例请参阅 references/conversion-examples.md。

---

故障排查

错误	原因	解决方案
未找到组件	名称不匹配或版本错误	运行 get-component-list.mjs，确认版本
脚本获取错误	版本无效或网络问题	重新运行 detect-version.mjs，检查网络
无法识别 Figma 节点	没有 💙 前缀	将其视为自定义布局（Box/VStack/HStack/Grid）
间距不匹配	值不符合标准	四舍五入到最接近的令牌（参见 token-mapping.md）

---

参考资料

组件文档

• references/url-patterns.md：用于获取组件数据的 GitHub URL 模式
• references/component-structure.md：组件文件结构和 JSON 架构

Figma 转换

• references/figma-layout-mapping.md：自动布局到组件的映射
• references/design-system-recognition.md：💙 前缀组件识别
• references/token-mapping.md：Figma 值到 vapor-ui 令牌的映射
• references/conversion-examples.md：Figma 到代码的转换示例

脚本

脚本	用途
detect-version.mjs	从 package.json 检测 @vapor-ui/core 和 @vapor-ui/icons 版本
get-component-list.mjs	列出所有可用组件
get-component-info.mjs	获取组件属性和文档
get-component-examples.mjs	获取组件示例代码
get-icon-list.mjs	列出并搜索图标（支持 --outline、--filled 和关键字搜索）

MCP 工具

工具	用途
mcp__figma-dev-mode-mcp-server__get_design_context	获取 Figma 设计节点树
mcp__figma-dev-mode-mcp-server__get_screenshot	获取视觉参考图像
mcp__figma-dev-mode-mcp-server__get_metadata	获取 Figma 文件元数据