H2oslabs Synnovatorzero UI Spec Generator

UI Spec Generator

Generate structured page-component-function hierarchy from design resources and test cases.

Prerequisites

MCP Servers Required

• Pencil MCP: Read .pen design files via mcp__pencil__* tools
• Figma MCP: Read Figma designs (configured in .claude/mcp.json)

Input Resources

Workflow

Step 1: Gather Design Context

1. Read specs/design/style.pen to understand design tokens (colors, fonts, spacing)
2. Read specs/design/pages.md to get page list and Figma URLs
3. Use Figma MCP to fetch component structure from Figma links
4. Read existing .pen files in specs/design/components/ to catalog current components

Step 2: Analyze Test Cases

1. Read all files in specs/testcases/*.md
2. Extract implicit UI requirements from test case descriptions:
   • What data needs to be displayed?
   • What user actions are described?
   • What state changes occur?
3. Map requirements to pages and components

Step 3: Gap Analysis

Compare test case requirements against existing components:

• Covered: Test case UI needs are met by existing components
• Extendable: Existing component can be modified (see component-reuse-criteria.md)
• Missing: New component needed

Step 4: Design Missing Components

For gaps identified:

1. Reference the corresponding screenshot in specs/design/assets/images/
2. Use Figma MCP to get detailed component structure if Figma link exists
3. Follow existing design patterns from style.pen
4. Prefer extending existing components over creating new ones

Step 5: Generate pages.yaml

Output to specs/design/pages.yaml following the format in output-format.md.

Structure:

pages:
  - id: page-id
    name: 页面名称
    route: /path
    sections:
      - id: section-id
        name: 区块名称
        components:
          - id: component-id
            name: 组件名称
            type: card|list-item|button|...
            data_source: post|category|user|...
            fields: [field1, field2]
            actions: [action1, action2]

Using Figma MCP

Extract Figma file key and node ID from URLs in pages.md:

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

Use Figma MCP tools to:

1. Get file structure and component hierarchy
2. Identify grouped elements (frames, groups)
3. Extract component names and relationships

Component Reuse Decision

Before creating new components, check references/component-reuse-criteria.md:

1. Visual similarity with existing components
2. Functional compatibility
3. Non-breaking extension possibility

Data Type References

When specifying data_source, use types from specs/data/types.md:

• category - 活动/赛事
• post - 帖子/提案
• user - 用户
• group - 团队
• resource - 资源文件
• rule - 规则
• interaction - 互动

Output Validation

After generating pages.yaml:

1. Verify all pages from pages.md are included
2. Verify test case UI requirements are addressed
3. Confirm component reuse is maximized
4. Check YAML syntax validity

Converted and distributed by TomeVault — claim your Tome and manage your conversions.