open_design_format.md

open_design_format.md

Open design format API Documentation

Open design format is a declarative design system that uses JSX-like syntax to create responsive layouts and UI components, specifically designed for Figma integration. Based on the Figma Widget API, it provides a comprehensive set of components for building sophisticated user interfaces with automatic layout management, styling, and effects.

Overview

Open design format enables designers and developers to create UI components using a JSON-based JSX format that maps directly to Figma's widget system. It supports real-time design collaboration through a WebSocket-based communication layer between AI agents and Figma via the Model Context Protocol (MCP).

Architecture

AI Agent <-> MCP <-> Local WebSocket Server <-> Figma Plugin

Core Components

JSX Structure Format

All Open design format components follow a consistent JSON structure:

{
  "jsx": {
    "type": "ComponentType",
    "props": {
      "property1": "value1",
      "property2": "value2"
    },
    "children": "content or array of child components"
  }
}

Text Components

Text

Renders styled text content with comprehensive typography controls.

Properties:

• fontSize - Font size in pixels (minimum: 1)
• fontFamily - Font family name (supports Google Fonts)
• fontWeight - Font weight (100-900 or 'normal', 'bold', 'medium', etc.)
• fill - Text color (hex code, Color object, or Paint array)
• letterSpacing - Character spacing
• lineHeight - Line spacing ('auto', number, or string)
• textAlign - Horizontal alignment ('left', 'center', 'right', 'justified')
• verticalAlignText - Vertical alignment ('top', 'center', 'bottom')
• textDecoration - Text decoration ('none', 'underline', 'strikethrough')
• textCase - Text transformation ('upper', 'lower', 'title', 'original', 'small-caps')
• italic - Boolean for italic text
• truncate - Text truncation (boolean or number of lines)

Example:

{
  "jsx": {
    "type": "Text",
    "props": {
      "fontSize": 32,
      "fontFamily": "Inter",
      "fontWeight": "700",
      "fill": "#1E1E1E"
    },
    "children": "Welcome to Open design format"
  }
}

Layout Components

AutoLayout

A frame with auto layout automatically applied, providing flexible container management with automatic sizing and positioning.

Properties:

• direction - Layout direction ('horizontal', 'vertical')
• spacing - Distance between children (number, 'auto', or LayoutGap object)
• padding - Padding inside the frame (number or Padding object)
• horizontalAlignItems - Horizontal alignment ('start', 'center', 'end')
• verticalAlignItems - Vertical alignment ('start', 'center', 'end', 'baseline')
• wrap - Allow wrapping when direction is horizontal (boolean)
• width - Component width ('hug-contents', 'fill-parent', or number)
• height - Component height ('hug-contents', 'fill-parent', or number)

Example:

{
  "jsx": {
    "type": "AutoLayout",
    "props": {
      "direction": "vertical",
      "padding": 24,
      "spacing": 16,
      "fill": "#FFFFFF",
      "cornerRadius": 12,
      "stroke": "#E0E0E0"
    },
    "children": [
      {
        "type": "Text",
        "props": {
          "fontSize": 20,
          "fontWeight": "600",
          "fill": "#000000"
        },
        "children": "Card Title"
      }
    ]
  }
}

Frame

A non-auto-layout Frame where children are positioned using x and y coordinates.

Properties:

• width - Frame width (required)
• height - Frame height (required)
• x - X position
• y - Y position
• overflow - Overflow behavior ('visible', 'hidden', 'scroll')

Shape Components

Rectangle

Creates rectangular shapes with customizable appearance.

Properties:

• width - Rectangle width (required)
• height - Rectangle height (required)
• fill - Fill color or paint array
• stroke - Stroke color or paint array
• strokeWidth - Stroke thickness in pixels
• cornerRadius - Corner radius (number or array for individual corners)

Example:

{
  "jsx": {
    "type": "Rectangle",
    "props": {
      "width": 120,
      "height": 120,
      "fill": "#FF6B6B",
      "cornerRadius": 8
    }
  }
}

Ellipse

Renders circular and elliptical shapes.

Properties:

• width - Ellipse width
• height - Ellipse height
• fill - Fill color or paint
• stroke - Stroke color
• strokeWidth - Stroke thickness
• arcData - Arc properties for partial ellipses

Line

Creates line elements for borders, dividers, and graphic elements.

Properties:

• length - Line length
• stroke - Line color
• strokeWidth - Line thickness
• strokeCap - Line endpoint decoration ('none', 'round', 'square')
• rotation - Rotation in degrees (-180 to 180)

SVG

Renders SVG content directly within components.

Properties:

• src - SVG string content
• width - SVG width
• height - SVG height

Example:

{
  "jsx": {
    "type": "SVG",
    "props": {
      "src": "<svg width='32' height='32' viewBox='0 0 32 32'><circle cx='16' cy='16' r='15.5'/></svg>",
      "width": 32,
      "height": 32
    }
  }
}

Image Component

Image

Displays images from various sources with responsive behavior.

Properties:

• src - Image source (URL string or ImagePaint object)
• width - Image width (required)
• height - Image height (required)
• cornerRadius - Rounded corners

Supported Sources:

• Web URLs: https://example.com/image.jpg
• Base64 data URIs: data:image/png;base64,...
• Local file paths (when supported)

Example:

{
  "jsx": {
    "type": "Image",
    "props": {
      "src": "https://picsum.photos/200/150",
      "width": 200,
      "height": 150,
      "cornerRadius": 8
    }
  }
}

Effects and Styling

Effects

Open design format supports various visual effects that can be applied to any component:

Blur Effect:

{
  "effect": {
    "type": "blur",
    "radius": 4
  }
}

Drop Shadow:

{
  "effect": {
    "type": "dropShadow",
    "x": 2,
    "y": 2,
    "blur": 4,
    "color": "#000000",
    "opacity": 0.25
  }
}

Paint and Color System

Solid Colors:

{
  "fill": "#FF0000"
}

Gradient Paints:

{
  "fill": {
    "type": "gradientPaint",
    "gradientType": "linear",
    "gradientStops": [
      {"position": 0, "color": "#FF6B6B"},
      {"position": 1, "color": "#4ECDC4"}
    ]
  }
}

Common Properties

BaseProps

Properties shared across all components:

• name - Component name for debugging
• hidden - Visibility toggle
• key - Component key for React-like reconciliation
• tooltip - Hover tooltip text
• positioning - Layout positioning ('auto', 'absolute')

BlendProps

Visual blending properties:

• blendMode - Blend mode for compositing
• opacity - Component opacity (0-1)

ConstraintProps

Positioning constraints:

• x - Horizontal position
• y - Vertical position

Advanced Layout Features

Responsive Behavior

Components support responsive sizing:

• 'hug-contents' - Size to fit content
• 'fill-parent' - Expand to fill available space
• Fixed pixel values

Auto Spacing

AutoLayout supports automatic spacing distribution:

{
  "spacing": "auto"  // Equivalent to CSS justify-content: space-between
}

Integration Examples

Button Component

{
  "jsx": {
    "type": "AutoLayout",
    "props": {
      "direction": "horizontal",
      "padding": {"top": 8, "right": 16, "bottom": 8, "left": 16},
      "fill": "#007AFF",
      "cornerRadius": 6
    },
    "children": [
      {
        "type": "Text",
        "props": {
          "fontSize": 14,
          "fill": "#FFFFFF",
          "fontWeight": "500"
        },
        "children": "Click Me"
      }
    ]
  }
}

Card Layout

{
  "jsx": {
    "type": "AutoLayout",
    "props": {
      "direction": "vertical",
      "spacing": 16,
      "padding": 24,
      "fill": "#FFFFFF",
      "cornerRadius": 12,
      "stroke": "#E0E0E0"
    },
    "children": [
      {
        "type": "Text",
        "props": {"fontSize": 20, "fontWeight": "600"},
        "children": "Card Title"
      },
      {
        "type": "Text",
        "props": {"fontSize": 14, "fill": "#666666"},
        "children": "Card description content"
      }
    ]
  }
}

Usage with External AI Systems

The Open design format format is designed to work seamlessly with various AI systems through its standardized JSON format. The consistent API structure allows different AI models to generate compatible design specifications that can be interpreted and rendered by the Figma plugin.

Workflow Integration

1. AI generates Open design format JSON specification
2. Specification is sent via WebSocket to Figma plugin
3. Plugin interprets JSON and creates corresponding Figma elements
4. Real-time collaboration and iteration through the MCP interface

This documentation provides a comprehensive foundation for implementing Open design format in various design automation and AI-assisted design workflows. The API's flexibility and alignment with established design patterns makes it suitable for both simple prototyping and complex design system implementation.