Design Workflow Best Practices

​

Starting Your Workflow

​

Initial Setup

1. Join a channel using join_channel before any other operations
2. Get document overview with get_document_info to understand the structure
3. Check current selection using get_selection or read_my_design before modifications

// Example workflow start
await join_channel({ channelName: "design-session" });
const docInfo = await get_document_info();
const selection = await get_selection();

​

Document Structure and Hierarchy

​

Planning Layout Hierarchy

• Start with main container frames for each screen or section
• Create parent frames first, then add child elements
• Use parentId parameter to maintain proper hierarchy

​

Naming Conventions

• Use descriptive, semantic names (e.g., “Login Screen”, “Logo Container”, “Email Input”)
• Follow a consistent pattern across your design system
• Group related elements with meaningful names

​

Element Creation

​

Choosing the Right Tool

• create_frame - For containers, auto-layout groups, and input field backgrounds
• create_rectangle - For basic shapes and visual elements
• create_text - For labels, button text, and content

​

Common Design Patterns

​

Form/Login Screen Structure

// Recommended hierarchy
- Login Screen (main frame)
  - Logo Container (frame)
    - Logo (text/component)
  - Welcome Text (text)
  - Input Container (frame)
    - Email Input (frame)
      - Email Label (text)
      - Email Field (frame)
    - Password Input (frame)
      - Password Label (text)
      - Password Field (frame)
  - Login Button (frame)
    - Button Text (text)
  - Helper Links (frame)
    - Forgot Password (text)
    - Signup Link (text)

​

Input Fields Pattern

• Create a container frame for each input field
• Include a label text above or inside the input
• Group related inputs together (e.g., username/password)

​

Styling Best Practices

​

Color Management

// Setting fill color
await set_fill_color({
  nodeId: "node-id",
  r: 0.2,  // 51 in 0-255 range
  g: 0.4,  // 102 in 0-255 range
  b: 0.6,  // 153 in 0-255 range
  a: 1.0
});

​

Visual Hierarchy

• Position: Arrange elements in logical reading order (top to bottom)
• Spacing: Use consistent spacing between elements
• Typography: Apply appropriate font sizes for different text types
  • Larger for headings/welcome text
  • Medium for input labels
  • Standard for button text
  • Smaller for helper text/links

​

Verification and Error Handling

​

Verify Changes

// Create element
const result = await create_frame({
  x: 100, y: 100,
  width: 300, height: 400,
  name: "Container"
});

// Verify creation
const nodeInfo = await get_node_info({ nodeId: result.id });

​

Error Handling

• Handle WebSocket disconnections gracefully
• Verify node existence before operations
• Use batch operations to minimize error points

​

Component Usage

​

Working with Components

• Use get_local_components to discover available components
• Create instances with create_component_instance for consistency
• Leverage component instances instead of duplicating designs

// Get available components
const components = await get_local_components();

// Create instance
await create_component_instance({
  componentKey: components[0].key,
  x: 100,
  y: 100
});

​

Instance Overrides

1. Use get_instance_overrides to extract customizations
2. Apply overrides with set_instance_overrides for batch updates
3. Preserve component relationships rather than breaking instances

​

Performance Optimization

​

Use Batch Operations

• set_multiple_text_contents instead of multiple set_text_content calls
• delete_multiple_nodes instead of individual delete_node calls
• set_multiple_annotations instead of repeated set_annotation calls

​

Large Design Considerations

• Use chunking parameters in scan_text_nodes
• Monitor progress through WebSocket updates
• Process in logical groups to avoid timeouts (default 30s)

// Scan with chunking for large designs
await scan_text_nodes({
  nodeId: "large-frame-id",
  useChunking: true,
  chunkSize: 10
});

​

Auto Layout Best Practices

​

Setting Up Auto Layout

1. Set layoutMode (HORIZONTAL, VERTICAL, or NONE)
2. Configure padding with set_padding
3. Set alignment with set_axis_align
4. Configure sizing with set_layout_sizing
5. Set spacing with set_item_spacing

​

Layout Modes

• HORIZONTAL - For rows, navigation bars, button groups
• VERTICAL - For columns, form fields, card stacks
• NONE - For free-form positioning

​

Selection and Focus

​

Managing Selection

• Use set_focus to select and scroll to a specific node
• Use set_selections to select multiple nodes at once
• Always verify selection before batch operations

// Focus on specific element
await set_focus({ nodeId: "important-node-id" });

// Select multiple nodes
await set_selections({ nodeIds: ["id1", "id2", "id3"] });

​

Workflow Checklist

• Join channel before operations
• Get document info for context
• Check current selection
• Plan hierarchy before creating elements
• Use descriptive, consistent names
• Choose appropriate creation tools
• Verify changes with get_node_info
• Use batch operations when possible
• Implement error handling
• Leverage components for consistency