Back to Details

vapor-ui

Compare original and translation side by side

🇺🇸

Original

English
🇨🇳

Translation

Chinese

Vapor UI Design Skill

Vapor UI设计技能

Instructions

说明

Step 1: Identify User Intent & Detect Version

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

Run these checks in parallel:
  1. Determine user intent:
    • Component lookup: User wants to know available components or specific component details
    • Usage guidance: User needs props, variants, or example code
    • Mockup generation: User wants to create a UI prototype
    • Figma conversion: User wants to convert Figma design to code
  2. Determine Vapor UI version (in order of priority):
    1. User-provided version: If user specifies a version, use it directly
    2. Auto-detect from codebase:
      bash
      node scripts/detect-version.mjs [start-path]
      Output: 
      CORE: x.x.x
      and 
      ICONS: x.x.x
    Use 
    CORE
    version for component scripts, 
    ICONS
    version for icon scripts.
并行执行以下检查：
  1. 确定用户意图：
    • 组件查询：用户想了解可用组件或特定组件的详细信息
    • 使用指导：用户需要属性、变体或示例代码
    • 原型生成：用户想要创建UI原型
    • Figma转换：用户想要将Figma设计转换为代码
  2. 确定Vapor UI版本（优先级顺序）：
    1. 用户指定版本：如果用户明确版本，直接使用该版本
    2. 从代码库自动检测：
      bash
      node scripts/detect-version.mjs [start-path]
      输出：
      CORE: x.x.x
      和 
      ICONS: x.x.x
    组件脚本使用
    CORE
    版本，图标脚本使用
    ICONS
    版本。

Step 2: Component Information

步骤2：组件信息

Get component list:
bash
node scripts/get-component-list.mjs <VERSION>
Example: 
node scripts/get-component-list.mjs 1.0.0-beta.12
Get component details (props, description):
bash
node scripts/get-component-info.mjs <VERSION> <COMPONENT> [PART]
Example: 
node scripts/get-component-info.mjs 1.0.0-beta.12 avatar
For detailed component structure, refer to 
references/component-structure.md
.
获取组件列表：
bash
node scripts/get-component-list.mjs <VERSION>
示例：
node scripts/get-component-list.mjs 1.0.0-beta.12
获取组件详情（属性、描述）：
bash
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
。

Step 3: Component Examples

步骤3：组件示例

Get example code:
bash
node scripts/get-component-examples.mjs <VERSION> <COMPONENT> [EXAMPLE_NAME]
Example: 
node scripts/get-component-examples.mjs 1.0.0-beta.12 avatar default-avatar
获取示例代码：
bash
node scripts/get-component-examples.mjs <VERSION> <COMPONENT> [EXAMPLE_NAME]
示例：
node scripts/get-component-examples.mjs 1.0.0-beta.12 avatar default-avatar

Step 3.5: Icon Lookup

步骤3.5：图标查询

Get icon list:
bash
node scripts/get-icon-list.mjs <ICONS_VERSION> [search-keyword]
Examples:
  • node scripts/get-icon-list.mjs 1.0.0-beta.12
    - List all icons
  • node scripts/get-icon-list.mjs 1.0.0-beta.12 arrow
    - Search icons containing "arrow"
  • node scripts/get-icon-list.mjs 1.0.0-beta.12 --outline
    - List only outline icons
  • node scripts/get-icon-list.mjs 1.0.0-beta.12 --filled
    - List only filled icons
Note: Use 
ICONS
version from 
detect-version.mjs
output for icon queries.
获取图标列表：
bash
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
版本。

Step 4: Mockup Generation

步骤4：原型生成

For mockup requests:
  1. Run 
    get-component-list.mjs
    to identify available components
  2. Run 
    get-component-info.mjs
    for each needed component's props
  3. Run 
    get-component-examples.mjs
    for usage patterns
  4. Generate code using Vapor UI components only
  5. Provide complete, copy-paste ready code
对于原型生成请求：
  1. 运行
    get-component-list.mjs
    确认可用组件
  2. 为每个所需组件运行
    get-component-info.mjs
    获取属性信息
  3. 运行
    get-component-examples.mjs
    获取使用模式
  4. 仅使用Vapor UI组件生成代码
  5. 提供可直接复制粘贴的完整代码

Step 5: Figma Design Conversion

步骤5：Figma设计转换

For Figma conversion requests:
  1. Parse Figma URL to extract 
    file_key
    and 
    node_id
    :
    https://www.figma.com/design/{file_key}/...?node-id={node_id}
  2. Get design context using MCP:
    mcp__figma-dev-mode-mcp-server__get_design_context
  - file_key: extracted from URL
  - node_id: extracted from URL (format: "X-Y" or "X:Y")
  - depth: 5 (or higher for complex designs)
  3. Analyze node tree:
    • 💙 prefix nodes: Design system components (see 
      references/design-system-recognition.md
      )
    • Auto-layout frames: Convert to VStack/HStack/Box/Grid (see 
      references/figma-layout-mapping.md
      )
    • TEXT nodes: Extract text content
  4. Convert layout properties:
    • layoutMode: VERTICAL
      → VStack
    • layoutMode: HORIZONTAL
      → HStack
    • itemSpacing
      → gap token
    • padding*
      → padding tokens
    • See 
      references/token-mapping.md
      for full mapping
  5. Recognize design system components:
    • Nodes starting with 💙 are vapor-ui components
    • Extract 
      componentProperties
      for variant → props mapping
    • Example: 
      💙Button
      with 
      Size: md, ColorPalette: primary
      → 
      <Button size="md" colorPalette="primary">
    • Important: Layout props (
      gap
      , 
      padding
      , 
      margin
      , 
      backgroundColor
      , etc.) must be inside 
      $css
      prop
  6. Generate code:
    • Build JSX from node tree (bottom-up)
    • Apply style utility props using design tokens
    • Output production-ready code
对于Figma转换请求：
  1. 解析Figma链接提取
    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: 从链接中提取
  - node_id: 从链接中提取（格式："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
      用于变体到属性的映射
    • 示例：
      💙Button
      带有 
      Size: md, ColorPalette: primary
      → 
      <Button size="md" colorPalette="primary">
    • 重要提示：布局属性（
      gap
      、
      padding
      、
      margin
      、
      backgroundColor
      等）必须放在
      $css
      属性内
  6. 生成代码：
    • 从下到上构建JSX
    • 使用设计令牌应用样式工具属性
    • 输出可用于生产环境的代码

Examples

示例

Example 1: Component Usage Query
User: "How do I use the Button component?"
Action:
  1. Run 
    node scripts/get-component-info.mjs 1.0.0-beta.12 button
  2. Run 
    node scripts/get-component-examples.mjs 1.0.0-beta.12 button
  3. Provide props, variants, and example code
Result: Complete Button usage guide with code examples
Example 2: Mockup Generation
User: "Create a login page mockup"
Action:
  1. Run 
    get-component-list.mjs
    to check available components
  2. Run 
    get-component-info.mjs
    for text-input, button, card, form
  3. Run 
    get-component-examples.mjs
    for form patterns
  4. Generate responsive layout using Vapor UI
Result: Production-ready login page code
Example 3: Component Discovery
User: "What form components are available?"
Action:
  1. Run 
    node scripts/get-component-list.mjs 1.0.0-beta.12
  2. Filter output for form-related components (text-input, textarea, checkbox, radio, select, etc.)
Result: Categorized list of form-related components
For Figma conversion examples, see 
references/conversion-examples.md
.
示例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. 为text-input、button、card、form组件运行
    get-component-info.mjs
  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
。

Troubleshooting

故障排除

ErrorCauseSolution
Component not foundName mismatch or version errorRun 
get-component-list.mjs
, verify version
Script fetch errorInvalid version or network issueRe-run 
detect-version.mjs
, check network
Figma node not recognizedNo 💙 prefixTreat as custom layout (Box/VStack/HStack/Grid)
Spacing mismatchNon-standard valuesRound to nearest token (see 
token-mapping.md
)
错误原因解决方案
组件未找到名称不匹配或版本错误运行
get-component-list.mjs
，验证版本
脚本获取错误版本无效或网络问题重新运行
detect-version.mjs
，检查网络
Figma节点未被识别无💙前缀视为自定义布局（Box/VStack/HStack/Grid）
间距不匹配使用非标准值四舍五入到最近的令牌值（详见
token-mapping.md
）

References

参考资料

Component Documentation

组件文档

  • references/url-patterns.md
    : GitHub URL patterns for fetching component data
  • references/component-structure.md
    : Component file structure and JSON schema
  • references/url-patterns.md
    ：用于获取组件数据的GitHub URL模式
  • references/component-structure.md
    ：组件文件结构及JSON schema

Figma Conversion

Figma转换

  • references/figma-layout-mapping.md
    : Auto-layout to component mapping
  • references/design-system-recognition.md
    : 💙 prefix component recognition
  • references/token-mapping.md
    : Figma values to vapor-ui tokens
  • references/conversion-examples.md
    : Figma to code conversion examples
  • references/figma-layout-mapping.md
    ：自动布局到组件的映射
  • references/design-system-recognition.md
    ：💙前缀组件识别规则
  • references/token-mapping.md
    ：Figma值到vapor-ui令牌的映射
  • references/conversion-examples.md
    ：Figma转代码的示例

Scripts

脚本

ScriptPurpose
detect-version.mjs
Detect @vapor-ui/core and @vapor-ui/icons versions from package.json
get-component-list.mjs
List all available components
get-component-info.mjs
Get component props and documentation
get-component-examples.mjs
Get component example code
get-icon-list.mjs
List and search icons (supports --outline, --filled, keyword search)
脚本用途
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 Tools

MCP工具

ToolPurpose
mcp__figma-dev-mode-mcp-server__get_design_context
Fetch Figma design node tree
mcp__figma-dev-mode-mcp-server__get_screenshot
Get visual reference image
mcp__figma-dev-mode-mcp-server__get_metadata
Get Figma file metadata
工具用途
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文件元数据