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

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

// 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 };

If user HAS a design system:

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

If user has NO design system:

• 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

Always check existing boards before creating new ones to avoid overlap:

// 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);

Board spacing guidelines:

• 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

Use these defaults only when user has no design system. Always prefer user's tokens if available.

Spacing Scale (8px base)

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

Before finalizing any design:

• [ ] 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

Use these validation approaches with mcp__penpot__execute_code:

Export CSS

Use penpot.generateStyle(selection, { type: 'css', includeChildren: true }) via mcp__penpot__execute_code to extract CSS from designs.

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

Accessibility Guidelines Reference (WCAG)

Quick Compliance Checklist

Level AA Requirements (Minimum Standard)

• [ ] Color contrast 4.5:1 for normal text
• [ ] Color contrast 3:1 for large text (18px+ or 14px bold)
• [ ] Touch targets minimum 44×44px
• [ ] All functionality available via keyboard
• [ ] Visible focus indicators
• [ ] No content flashes more than 3 times/second
• [ ] Page has descriptive title
• [ ] Link purpose clear from text
• [ ] Form inputs have labels
• [ ] Error messages are descriptive

---

Color and Contrast

Contrast Ratios

Color Independence

Never use color as the only means of conveying information:

✗ Error fields shown only in red
✓ Error fields with red border + error icon + text message

✗ Required fields marked only with red asterisk
✓ Required fields labeled "(required)" or with icon + tooltip

✗ Status shown only by color dots
✓ Status with color + icon + label text

Accessible Color Combinations

Safe text colors on backgrounds:

Colors to avoid for text:

• Yellow on white (insufficient contrast)
• Light gray on white
• Orange on white (marginal at best)

---

Keyboard Navigation

Requirements

1. All interactive elements must be reachable via Tab key 2. Logical tab order following visual layout 3. No keyboard traps (user can always Tab away) 4. Focus visible at all times during keyboard navigation 5. Skip links to bypass repetitive navigation

Focus Indicators

/* Example focus styles */
:focus {
  outline: 2px solid #2563EB;
  outline-offset: 2px;
}

:focus:not(:focus-visible) {
  outline: none; /* Hide for mouse users */
}

:focus-visible {
  outline: 2px solid #2563EB;
  outline-offset: 2px;
}

Keyboard Shortcuts

---

Screen Reader Support

Semantic HTML Elements

Use appropriate elements for their purpose:

Heading Hierarchy

h1 - Page Title (one per page)
  h2 - Major Section
    h3 - Subsection
      h4 - Sub-subsection
    h3 - Another Subsection
  h2 - Another Major Section

Never skip levels (h1 → h3 without h2)

Image Alt Text

Decorative: alt="" (empty, not omitted)
Informative: alt="Description of what image shows"
Functional: alt="Action the image performs"
Complex: alt="Brief description" + detailed description nearby

Alt text examples:

✓ alt="Bar chart showing sales growth from $10M to $15M in Q4"
✓ alt="Company logo"
✓ alt="" (for decorative background pattern)

✗ alt="image" or alt="photo"
✗ alt="img_12345.jpg"
✗ Missing alt attribute entirely

---

Touch and Pointer

Touch Target Sizes

Touch Target Spacing

• Minimum 8px between adjacent targets
• Prefer 16px+ for comfort
• Larger targets for primary actions

Pointer Gestures

• Complex gestures must have single-pointer alternatives
• Drag operations need equivalent click actions
• Avoid hover-only functionality on touch devices

---

Forms Accessibility

Labels

Every input must have an associated label:

<label for="email">Email Address</label>
<input type="email" id="email" name="email">

Required Fields

<!-- Announce to screen readers -->
<label for="name">
  Name <span aria-label="required">*</span>
</label>
<input type="text" id="name" required aria-required="true">

Error Handling

<label for="email">Email</label>
<input type="email" id="email" aria-invalid="true" aria-describedby="email-error">
<span id="email-error" role="alert">
  Please enter a valid email address
</span>

Form Instructions

• Provide format hints before input
• Show password requirements before errors
• Group related fields with fieldset/legend

---

Dynamic Content

Live Regions

For content that updates dynamically:

aria-live="polite" - Announce when convenient
aria-live="assertive" - Announce immediately (interrupts)
role="alert" - Urgent messages (like assertive)
role="status" - Status updates (like polite)

Loading States

<button aria-busy="true" aria-live="polite">
  <span class="spinner"></span>
  Loading...
</button>

Modal Dialogs

• Focus moves into modal when opened
• Focus trapped within modal
• Escape key closes modal
• Focus returns to trigger element when closed

---

Testing Accessibility

Manual Testing Checklist

1. Keyboard only: Navigate entire page with Tab/Enter 2. Screen reader: Test with VoiceOver (Mac) or NVDA (Windows) 3. Zoom 200%: Content remains readable and usable 4. High contrast: Test with system high contrast mode 5. No mouse: Complete all tasks without pointing device

Automated Tools

• axe DevTools (browser extension)
• WAVE (WebAIM browser extension)
• Lighthouse (Chrome DevTools)
• Color contrast checkers (WebAIM, Contrast Ratio)

Common Issues to Check

• [ ] Missing or empty alt text
• [ ] Empty links or buttons
• [ ] Missing form labels
• [ ] Insufficient color contrast
• [ ] Missing language attribute
• [ ] Incorrect heading structure
• [ ] Missing skip navigation link
• [ ] Inaccessible custom widgets

---

ARIA Quick Reference

Roles

Properties

Golden Rule

First rule of ARIA: Don't use ARIA if native HTML works.

✗ <div role="button" tabindex="0">Click</div>
✓ <button>Click</button>

UI Component Patterns Reference

Buttons

Button Types

Button States

Default    → Resting state, clearly interactive
Hover      → Cursor over (desktop): darken 10%, subtle shadow
Active     → Being pressed: darken 20%, slight scale down
Focus      → Keyboard selected: visible outline ring
Disabled   → Not available: 50% opacity, cursor: not-allowed
Loading    → Processing: spinner replaces or accompanies label

Button Specifications

• Minimum size: 44×44px (touch target)
• Padding: 12-16px horizontal, 8-12px vertical
• Border radius: 4-8px (consistent across app)
• Font weight: Medium or Semibold (600-700)
• Text: Sentence case, 2-4 words max

Button Label Patterns

✓ Save Changes        ✗ Submit
✓ Add to Cart         ✗ Click Here
✓ Create Account      ✗ OK
✓ Download PDF        ✗ Go
✓ Start Free Trial    ✗ Continue

---

Forms

Form Layout Guidelines

• Single column preferred: Reduces cognitive load
• Top-aligned labels: Fastest completion times
• Logical grouping: Related fields together
• Smart defaults: Pre-fill when possible

Input Field Anatomy

┌─ Label (required) ─────────────────────────┐
│                                            │
│  ┌────────────────────────────────────┐   │
│  │ Placeholder text...                 │   │
│  └────────────────────────────────────┘   │
│  Helper text or error message              │
└────────────────────────────────────────────┘

Input States

Validation Timing

• On blur: Validate when user leaves field
• On change (after error): Clear error as user types correct input
• On submit: Final validation before processing
• Never on focus: Don't show errors before user types

Error Message Guidelines

✓ "Email address is required"
✓ "Password must be at least 8 characters"
✓ "Please enter a valid phone number (e.g., 555-123-4567)"

✗ "Invalid input"
✗ "Error"
✗ "This field is required" (generic)

Form Best Practices

• Mark optional fields, not required (fewer asterisks)
• Show password requirements before errors occur
• Use input masks for formatted data (phone, date)
• Preserve data on errors (don't clear the form)
• Provide clear success confirmation

---

Navigation

Navigation Patterns

Top Navigation Bar

┌─────────────────────────────────────────────────────┐
│ Logo    Nav Item  Nav Item  Nav Item    [Search] [User] │
└─────────────────────────────────────────────────────┘

• Best for: Marketing sites, simple apps
• Max items: 5-7 top-level links
• Mobile: Collapse to hamburger menu

Sidebar Navigation

┌────────┬────────────────────────────────┐
│ Logo   │ Content Area                   │
├────────┤                                │
│ Nav 1  │                                │
│ Nav 2  │                                │
│ Nav 3  │                                │
│        │                                │
│ ────── │                                │
│ Nav 4  │                                │
│ Nav 5  │                                │
└────────┴────────────────────────────────┘

• Best for: Dashboards, complex apps
• Width: 200-280px expanded, 64px collapsed
• Mobile: Overlay drawer

Bottom Navigation (Mobile)

┌─────────────────────────────────────┐
│           Content Area              │
│                                     │
├─────────────────────────────────────┤
│  🏠    🔍    ➕    💬    👤        │
│ Home  Search Add  Chat  Profile     │
└─────────────────────────────────────┘

• Max items: 3-5 destinations
• Best for: Primary app sections
• Always visible: Persistent navigation

Breadcrumbs

Home > Products > Electronics > Headphones

• Use for: Deep hierarchies (3+ levels)
• Current page: Not clickable, different style
• Separator: > or / or chevron icon

Tab Navigation

┌─────────┬─────────┬─────────┬─────────┐
│ Tab 1   │ Tab 2   │ Tab 3   │ Tab 4   │
└─────────┴─────────┴─────────┴─────────┘
│                                       │
│        Tab Content Area               │
│                                       │
└───────────────────────────────────────┘

• Max tabs: 3-5 for clarity
• Active indicator: Underline or background
• Use for: Related content within same page

---

Cards

Card Anatomy

┌─────────────────────────────────┐
│ ░░░░░░░ Image/Media ░░░░░░░░░░ │
├─────────────────────────────────┤
│ Category Label                  │
│ Card Title                      │
│ Description text that may       │
│ span multiple lines...          │
│                                 │
│ [Action Button]  [Secondary]    │
└─────────────────────────────────┘

Card Guidelines

• Consistent sizing: Use grid, equal heights
• Content hierarchy: Image → Title → Description → Actions
• Padding: 16-24px internal spacing
• Border radius: 8-12px (matching buttons)
• Shadow: Subtle elevation (0 2px 4px rgba(0,0,0,0.1))

---

Modals and Dialogs

Modal Structure

┌─────────────────────────────────────┐
│ Modal Title                    [×]  │
├─────────────────────────────────────┤
│                                     │
│ Modal content goes here.            │
│ Keep it focused on one task.        │
│                                     │
├─────────────────────────────────────┤
│           [Cancel]  [Confirm]       │
└─────────────────────────────────────┘

Modal Guidelines

• Size: 400-600px width (desktop), full-width minus margins (mobile)
• Overlay: Semi-transparent dark background (rgba(0,0,0,0.5))
• Close options: X button, overlay click, Escape key
• Focus trap: Keep keyboard focus within modal
• Primary action: Right-aligned, visually prominent

---

Dashboards

Dashboard Layout Principles

1. Most important metrics at top: KPIs, summary cards 2. Progressive detail: Overview → Drill-down capability 3. Consistent card sizes: Use grid system 4. Minimal chartjunk: Only data-serving visuals 5. Actionable insights: Highlight anomalies

Data Visualization Selection

Dashboard Best Practices

• Limit to 5-9 widgets per view
• Align to grid: Consistent gutters and sizing
• Filter controls: Top or sidebar, always visible
• Date range selector: Common need, make prominent
• Export options: PDF, CSV for data tables
• Responsive: Stack cards on smaller screens

---

Empty States

Empty State Components

┌─────────────────────────────────────┐
│                                     │
│         [Illustration/Icon]         │
│                                     │
│      No projects yet                │
│                                     │
│   Create your first project to      │
│   start organizing your work.       │
│                                     │
│       [Create Project]              │
│                                     │
└─────────────────────────────────────┘

Empty State Guidelines

• Friendly illustration: Not just "No data"
• Explain value: Why create something?
• Clear CTA: Primary action to fix empty state
• Keep it brief: 1-2 sentences max

---

Loading States

Loading Patterns

Skeleton Screen

┌─────────────────────────────────────┐
│ ░░░░░░░░░░░░ ░░░░░░░░░░           │
├─────────────────────────────────────┤
│ ░░░░░░░░░░░░░░░░░░░░░░░░░         │
│ ░░░░░░░░░░░░░░░░░░░               │
│ ░░░░░░░░░░░░░░░░░░░░░░░           │
└─────────────────────────────────────┘

• Match layout of loaded content
• Use subtle animation (shimmer/pulse)
• Show actual content structure

Platform Design Guidelines Reference

Mobile Design Fundamentals

Screen Sizes

Safe Areas

┌─────────────────────────────────┐
│ ▓▓▓▓▓▓▓ Status Bar ▓▓▓▓▓▓▓▓▓▓ │ 44-47px
├─────────────────────────────────┤
│                                 │
│      Safe Content Area          │
│                                 │
│                                 │
├─────────────────────────────────┤
│ ▓▓▓▓▓▓ Home Indicator ▓▓▓▓▓▓▓ │ 34px
└─────────────────────────────────┘

Touch Targets

• Minimum: 44×44pt (iOS) / 48×48dp (Android)
• Recommended: 48×48px for all platforms
• Spacing: Minimum 8px between targets

---

iOS Human Interface Guidelines (HIG)

Design Philosophy

• Clarity: Text is legible, icons precise, adornments subtle
• Deference: UI helps people understand content, never competes
• Depth: Distinct visual layers convey hierarchy

Navigation Patterns

Tab Bar Specifications

┌─────────────────────────────────┐
│  🏠    🔍    ➕    💬    👤    │
│ Home  Search Add  Chat  Profile │ 49pt height
└─────────────────────────────────┘

• Max 5 tabs
• Icons 25×25pt with 10pt labels
• Active tab uses fill/tint color
• Inactive tabs use gray

Navigation Bar

┌─────────────────────────────────┐
│ ‹ Back    Page Title    Action │ 44pt minimum
└─────────────────────────────────┘

• Left: Back button or cancel
• Center: Title
• Right: Primary action (text or icon)

Typography (SF Pro)

iOS Colors (System)

iOS-Specific Patterns

• Swipe gestures: Delete, archive, actions
• Pull to refresh: Standard list refresh
• Long press: Context menus
• Haptic feedback: Confirm actions
• Edge swipe: Back navigation

---

Android Material Design

Android Design Philosophy

• Material as metaphor: Physical properties, elevation
• Bold, graphic, intentional: Deliberate color, typography, space
• Motion provides meaning: Feedback and continuity

Android Navigation Patterns

Bottom Navigation

┌─────────────────────────────────┐
│  🏠    🔍    📷    💬    👤    │
│ Home  Search Camera Chat Account│ 80dp height
└─────────────────────────────────┘

• 3-5 destinations
• Icons 24dp with 12sp labels
• Active: filled icon + primary color
• Inactive: outlined icon + on-surface

App Bar

┌─────────────────────────────────┐
│ ≡  App Title                🔍 │ 64dp height
└─────────────────────────────────┘

• Left: Navigation icon (menu or back)
• Center: Title (can be left-aligned)
• Right: Action icons (max 3)

Floating Action Button (FAB)

• Size: 56dp standard, 40dp mini
• Position: Bottom right, 16dp from edges
• Purpose: Primary action only
• Behavior: Can hide on scroll

Typography (Roboto)

Material Colors

Elevation (Shadows)

Android-Specific Patterns

• Snackbar: Brief feedback at bottom
• Bottom sheet: Additional content/actions
• Chips: Filter, input, choice, action
• Speed dial FAB: Multiple related actions

---

Responsive Web Design

Breakpoints

Grid System

• Columns: 12-column grid standard
• Gutters: 16-24px between columns
• Margins: 16px (mobile) to 64px (desktop)
• Max content width: 1200-1440px

Responsive Typography

Mobile (base):
  Body: 16px
  H1: 28-32px
  H2: 22-24px
  
Tablet:
  Body: 16px
  H1: 32-40px
  H2: 24-28px
  
Desktop:
  Body: 16-18px
  H1: 40-56px
  H2: 28-36px

Mobile-First Approach

1. Design for smallest screen first 2. Add complexity for larger screens 3. Content priority: What's essential? 4. Performance: Minimize for mobile 5. Touch-first interactions

Responsive Patterns

---

Desktop Applications

Window Chrome

┌─────────────────────────────────────────┐
│ ● ● ●   App Title              ─ □ ×  │ Title bar
├────────┬────────────────────────────────┤
│ Sidebar│ Content Area                   │
│        │                                │
│        │                                │
│        │                                │
│        ├────────────────────────────────┤
│        │ Status Bar                     │
└────────┴────────────────────────────────┘

Keyboard-First Design

• All actions accessible via keyboard
• Visible keyboard shortcuts
• Focus management for tab order
• Search/command palette (Cmd/Ctrl+K)

Hover States

Desktop has hover (mobile doesn't):

• Show additional info on hover
• Preview actions before click
• Tooltips for icon-only buttons
• Dropdown menus on hover

Dense Information

Desktop allows for:

• Smaller touch targets (32px min)
• More visible information
• Complex tables and data grids
• Multi-column layouts
• Side-by-side comparisons

---

Cross-Platform Considerations

Shared Principles

• Consistent brand identity
• Same core user flows
• Synchronized data/state
• Familiar information architecture

Platform-Specific Adaptations

Design Tokens Across Platforms

Create platform-agnostic tokens:

// Spacing
spacing-sm: 8
spacing-md: 16
spacing-lg: 24

// These map to platform units
iOS: points (pt)
Android: density-independent pixels (dp)
Web: pixels (px) or rem

Penpot MCP Server Setup & Troubleshooting

Complete guide for installing, configuring, and troubleshooting the Penpot MCP Server.

Architecture Overview

The Penpot MCP integration requires three components working together:

┌─────────────────┐     ┌─────────────────┐     ┌─────────────────┐
│   MCP Client    │────▶│   MCP Server    │◀───▶│  Penpot Plugin  │
│ (VS Code/Claude)│     │  (port 4401)    │     │ (in browser)    │
└─────────────────┘     └────────┬────────┘     └────────┬────────┘
                                 │                       │
                                 │    WebSocket          │
                                 │    (port 4402)        │
                                 └───────────────────────┘

1. MCP Server - Exposes tools to your AI client (HTTP on port 4401) 2. Plugin Server - Serves the Penpot plugin files (HTTP on port 4400) 3. Penpot MCP Plugin - Runs inside Penpot browser, executes design commands

Prerequisites

• Node.js v22+ - Download
• Git - For cloning the repository
• Modern browser - Chrome, Firefox, or Chromium-based browser

Verify Node.js installation:

node --version  # Should be v22.x or higher
npm --version
npx --version

Installation

Step 1: Clone and Install

# Clone the repository
git clone https://github.com/penpot/penpot-mcp.git
cd penpot-mcp

# Install dependencies
npm install

Step 2: Build and Start Servers

# Build all components and start servers
npm run bootstrap

This command:

• Installs dependencies for all components
• Builds the MCP server and plugin
• Starts both servers (MCP on 4401, Plugin on 4400)

Expected output:

MCP Server listening on http://localhost:4401
Plugin server listening on http://localhost:4400
WebSocket server listening on port 4402

Step 3: Load Plugin in Penpot

1. Open Penpot in your browser 2. Open or create a design file 3. Go to Plugins menu (or press the plugins icon) 4. Click Load plugin from URL 5. Enter: http://localhost:4400/manifest.json 6. The plugin UI will appear - click "Connect to MCP server" 7. Status should change to "Connected to MCP server"

Important: Keep the plugin UI open while using MCP tools. Closing it disconnects the server.

Step 4: Configure Your MCP Client

VS Code with GitHub Copilot

Add to your VS Code settings.json:

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

Or use the HTTP endpoint:

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

Claude Desktop

Claude Desktop requires the mcp-remote proxy (stdio-only transport):

1. Install the proxy:

   npm install -g mcp-remote

2. Edit Claude Desktop config:

• macOS: ~/Library/Application Support/Claude/claude_desktop_config.json
• Windows: %APPDATA%/Claude/claude_desktop_config.json
• Linux: ~/.config/Claude/claude_desktop_config.json

3. Add the Penpot server:

   {
     "mcpServers": {
       "penpot": {
         "command": "npx",
         "args": ["-y", "mcp-remote", "http://localhost:4401/sse", "--allow-http"]
       }
     }
   }

4. Fully quit Claude Desktop (File → Quit, not just close window) and restart

Claude Code (CLI)

claude mcp add penpot -t http http://localhost:4401/mcp

Troubleshooting

Connection Issues

"Plugin cannot connect to MCP server"

Symptoms: Plugin shows "Not connected" even after clicking Connect

Solutions:

1. Verify servers are running:

   # Check if ports are in use
   lsof -i :4401  # MCP server
   lsof -i :4402  # WebSocket
   lsof -i :4400  # Plugin server

2. Restart the servers:

   # In the penpot-mcp directory
   npm run start:all

3. Check browser console (F12) for WebSocket errors

Browser Blocks Local Connection

Symptoms: Browser refuses to connect to localhost from Penpot

Cause: Chromium 142+ enforces Private Network Access (PNA) restrictions

Solutions:

1. Chrome/Chromium: When prompted, allow access to local network 2. Brave: Disable Shield for the Penpot website:

• Click the Brave Shield icon in address bar
• Toggle Shield off for this site

3. Try Firefox: Firefox doesn't enforce these restrictions as strictly

"WebSocket connection failed"

Solutions:

1. Check firewall settings - allow ports 4400, 4401, 4402 2. Disable VPN if active 3. Check for conflicting applications using the same ports

MCP Client Issues

Tools Not Appearing in VS Code/Claude

1. Verify endpoint:

   # Test the SSE endpoint
   curl http://localhost:4401/sse
   
   # Test the MCP endpoint
   curl http://localhost:4401/mcp

2. Check configuration syntax - JSON must be valid 3. Restart the MCP client completely 4. Check MCP server logs:

   # Logs are in mcp-server/logs/
   tail -f mcp-server/logs/mcp-server.log

"Tool execution timed out"

Cause: Plugin disconnected or operation took too long

Solutions:

1. Ensure plugin UI is still open in Penpot 2. Verify plugin shows "Connected" status 3. Try reconnecting: click Disconnect then Connect in plugin

Plugin Issues

"Plugin failed to load"

1. Verify plugin server is running on port 4400 2. Try accessing http://localhost:4400/manifest.json directly in browser 3. Clear browser cache and reload Penpot 4. Remove and re-add the plugin

"Cannot find penpot object"

Cause: Plugin not properly initialized or design file not open

Solutions:

1. Make sure you have a design file open (not just the dashboard) 2. Wait a few seconds after opening file before connecting 3. Refresh Penpot and reload the plugin

Server Issues

Port Already in Use

# Find process using the port
lsof -i :4401

# Kill the process if needed
kill -9 <PID>

Or configure different ports via environment variables:

PENPOT_MCP_SERVER_PORT=4501 npm run start:all

Server Crashes on Startup

1. Check Node.js version (must be v22+) 2. Delete node_modules and reinstall:

   rm -rf node_modules
   npm install
   npm run bootstrap

Configuration Reference

Environment Variables

Example: Custom Configuration

# Run on different ports with debug logging
PENPOT_MCP_SERVER_PORT=5000 \
PENPOT_MCP_WEBSOCKET_PORT=5001 \
PENPOT_MCP_LOG_LEVEL=debug \
npm run start:all

Verifying the Setup

Run this checklist to confirm everything works:

1. Servers Running:

   curl -s http://localhost:4401/sse | head -1
   # Should return SSE stream headers

2. Plugin Connected: Plugin UI shows "Connected to MCP server"

3. Tools Available: In your MCP client, verify these tools appear:

• mcp__penpot__execute_code
• mcp__penpot__export_shape
• mcp__penpot__import_image
• mcp__penpot__penpot_api_info

4. Test Execution: Ask your AI assistant to run a simple command:

"Use Penpot to get the current page name"

Getting Help

• GitHub Issues: penpot/penpot-mcp/issues
• GitHub Discussions: penpot/penpot-mcp/discussions
• Penpot Community: community.penpot.app