Penpot UI/UX Design Guide

Create professional, user-centered designs in Penpot using the penpot/penpot-mcp MCP server and proven UI/UX principles.

Available MCP Tools

MCP Server Setup

The Penpot MCP tools require the penpot/penpot-mcp server running locally. For detailed installation and troubleshooting, see setup-troubleshooting.md.

Before Setup: Check If Already Running

Always check if the MCP server is already available before attempting setup:

1. Try calling a tool first: Attempt mcp__penpot__penpot_api_info - if it succeeds, the server is running and connected. No setup needed.

2. If the tool fails, ask the user:

   "The Penpot MCP server doesn't appear to be connected. Is the server already installed and running? If so, I can help troubleshoot. If not, I can guide you through the setup."

3. Only proceed with setup instructions if the user confirms the server is not installed.

Quick Start (Only If Not Installed)

# Clone and install
git clone https://github.com/penpot/penpot-mcp.git
cd penpot-mcp
npm install

# Build and start servers
npm run bootstrap

Then in Penpot:

1. Open a design file
2. Go to Plugins → Load plugin from URL
3. Enter: http://localhost:4400/manifest.json
4. Click "Connect to MCP server" in the plugin UI

VS Code Configuration

Add to settings.json:

{
  "mcp": {
    "servers": {
      "penpot": {
        "url": "http://localhost:4401/sse"
      }
    }
  }
}

Troubleshooting (If Server Is Installed But Not Working)

Quick Reference

Core Design Principles

The Golden Rules

1. Clarity over cleverness: Every element must have a purpose
2. Consistency builds trust: Reuse patterns, colors, and components
3. User goals first: Design for tasks, not features
4. Accessibility is not optional: Design for everyone
5. Test with real users: Validate assumptions early

Visual Hierarchy (Priority Order)

1. Size: Larger = more important
2. Color/Contrast: High contrast draws attention
3. Position: Top-left (LTR) gets seen first
4. Whitespace: Isolation emphasizes importance
5. Typography weight: Bold stands out

Design Workflow

1. Check for design system first: Ask user if they have existing tokens/specs, or discover from current Penpot file
2. Understand the page: Call mcp__penpot__execute_code with penpotUtils.shapeStructure() to see hierarchy
3. Find elements: Use penpotUtils.findShapes() to locate elements by type or name
4. Create/modify: Use penpot.createBoard(), penpot.createRectangle(), penpot.createText() etc.
5. Apply layout: Use addFlexLayout() for responsive containers
6. Validate: Call mcp__penpot__export_shape to visually check your work

Design System Handling

Before creating designs, determine if the user has an existing design system:

1. Ask the user: "Do you have a design system or brand guidelines to follow?"
2. Discover from Penpot: Check for existing components, colors, and patterns

…