Penpot-Uiux-Design

# 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

| Tool | Purpose |

| ---- | ------- |

| `mcp__penpot__execute_code` | Run JavaScript in Penpot plugin context to create/modify designs |

| `mcp__penpot__export_shape` | Export shapes as PNG/SVG for visual inspection |

| `mcp__penpot__import_image` | Import images (icons, photos, logos) into designs |

| `mcp__penpot__penpot_api_info` | Retrieve Penpot API documentation |

MCP Server Setup

The Penpot MCP tools require the `penpot/penpot-mcp` server running locally. For detailed installation and troubleshooting, see [setup-troubleshooting.md](references/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)

| Issue | Solution |

| ----- | -------- |

| Plugin won't connect | Check servers are running (`npm run start:all` in penpot-mcp dir) |

| Browser blocks localhost | Allow local network access prompt, or disable Brave Shield, or try Firefox |

| Tools not appearing in client | Restart VS Code/Claude completely after config changes |

| Tool execution fails/times out | Ensure Penpot plugin UI is open and shows "Connected" |

| "WebSocket connection failed" | Check firewall allows ports 4400, 4401, 4402 |

Quick Reference

| Task | Reference File |

| ---- | -------------- |

| MCP server installation & troubleshooting | [setup-troubleshooting.md](references/setup-troubleshooting.md) |

| Component specs (buttons, forms, nav) | [component-patterns.md](references/component-patterns.md) |

| Accessibility (contrast, touch targets) | [accessibility.md](references/accessibility.md) |

| Screen sizes & platform specs | [platform-guidelines.md](references/platform-guidelines.md) |

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.createRectang