Penpot UI/UX Design Guide

penpot/penpot-mcp

Available MCP Tools

mcp__penpot__execute_code

mcp__penpot__export_shape

mcp__penpot__import_image

mcp__penpot__penpot_api_info

MCP Server Setup

penpot/penpot-mcp

Before Setup: Check If Already Running

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

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

settings.json

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

Troubleshooting (If Server Is Installed But Not Working)

npm run start:all

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

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

// Discover existing design patterns in current file
const allShapes = penpotUtils.findShapes(() => true, penpot.root);

// Find existing colors in use
const colors = new Set();
allShapes.forEach(s => {
  if (s.fills) s.fills.forEach(f => colors.add(f.fillColor));
});

// Find existing text styles (font sizes, weights)
const textStyles = allShapes
  .filter(s => s.type === 'text')
  .map(s => ({ fontSize: s.fontSize, fontWeight: s.fontWeight }));

// Find existing components
const components = penpot.library.local.components;

return { colors: [...colors], textStyles, componentCount: components.length };

• Use their specified colors, spacing, typography
• Match their existing component patterns
• Follow their naming conventions

• Use the default tokens below as a starting point
• Offer to help establish consistent patterns
• Reference specs in component-patterns.md

Key Penpot API Gotchas

• width

  /

  height

  are READ-ONLY → use

  shape.resize(w, h)

• parentX

  /

  parentY

  are READ-ONLY → use

  penpotUtils.setParentXY(shape, x, y)

• Use

  insertChild(index, shape)

  for z-ordering (not

  appendChild

  )
• Flex children array order is REVERSED for

  dir="column"

  or

  dir="row"

• After

  text.resize()

  , reset

  growType

  to

  "auto-width"

  or

  "auto-height"

Positioning New Boards

// Find all existing boards and calculate next position
const boards = penpotUtils.findShapes(s => s.type === 'board', penpot.root);
let nextX = 0;
const gap = 100; // Space between boards

if (boards.length > 0) {
  // Find rightmost board edge
  boards.forEach(b => {
    const rightEdge = b.x + b.width;
    if (rightEdge + gap > nextX) {
      nextX = rightEdge + gap;
    }
  });
}

// Create new board at calculated position
const newBoard = penpot.createBoard();
newBoard.x = nextX;
newBoard.y = 0;
newBoard.resize(375, 812);

• Use 100px gap between related screens (same flow)
• Use 200px+ gap between different sections/flows
• Align boards vertically (same y) for visual organization
• Group related screens horizontally in user flow order

Default Design Tokens

Spacing Scale (8px base)

spacing-xs

spacing-sm

spacing-md

spacing-lg

spacing-xl

spacing-2xl

Typography Scale

Color Usage

Common Layouts

Mobile Screen (375×812)

┌─────────────────────────────┐
│ Status Bar (44px)           │
├─────────────────────────────┤
│ Header/Nav (56px)           │
├─────────────────────────────┤
│                             │
│ Content Area                │
│ (Scrollable)                │
│ Padding: 16px horizontal    │
│                             │
├─────────────────────────────┤
│ Bottom Nav/CTA (84px)       │
└─────────────────────────────┘

Desktop Dashboard (1440×900)

┌──────┬──────────────────────────────────┐
│      │ Header (64px)                    │
│ Side │──────────────────────────────────│
│ bar  │ Page Title + Actions             │
│      │──────────────────────────────────│
│ 240  │ Content Grid                     │
│ px   │ ┌─────┐ ┌─────┐ ┌─────┐ ┌─────┐ │
│      │ │Card │ │Card │ │Card │ │Card │ │
│      │ └─────┘ └─────┘ └─────┘ └─────┘ │
│      │                                  │
└──────┴──────────────────────────────────┘

Component Checklist

Buttons

• Clear, action-oriented label (2-3 words)
• Minimum touch target: 44×44px
• Visual states: default, hover, active, disabled, loading
• Sufficient contrast (3:1 against background)
• Consistent border radius across app

Forms

• Labels above inputs (not just placeholders)
• Required field indicators
• Error messages adjacent to fields
• Logical tab order
• Input types match content (email, tel, etc.)

Navigation

• Current location clearly indicated
• Consistent position across screens
• Maximum 7±2 top-level items
• Touch-friendly on mobile (48px targets)

Accessibility Quick Checks

1. Color contrast: Text 4.5:1, Large text 3:1
2. Touch targets: Minimum 44×44px
3. Focus states: Visible keyboard focus indicators
4. Alt text: Meaningful descriptions for images
5. Hierarchy: Proper heading levels (H1→H2→H3)
6. Color independence: Never rely solely on color

Design Review Checklist

• Visual hierarchy is clear
• Consistent spacing and alignment
• Typography is readable (16px+ body text)
• Color contrast meets WCAG AA
• Interactive elements are obvious
• Mobile-friendly touch targets
• Loading/empty/error states considered
• Consistent with design system

Validating Designs

mcp__penpot__execute_code

penpotUtils.analyzeDescendants()

isContainedIn()

penpotUtils.findShapes()

fontSize

mcp__penpot__export_shape

penpotUtils.shapeStructure()

Export CSS

penpot.generateStyle(selection, { type: 'css', includeChildren: true })

mcp__penpot__execute_code

Tips for Great Designs

1. Start with content: Real content reveals layout needs
2. Design mobile-first: Constraints breed creativity
3. Use a grid: 8px base grid keeps things aligned
4. Limit colors: 1 primary + 1 secondary + neutrals
5. Limit fonts: 1-2 typefaces maximum
6. Embrace whitespace: Breathing room improves comprehension
7. Be consistent: Same action = same appearance everywhere
8. Provide feedback: Every action needs a response