npx skills add ...
npx skills add github/awesome-copilot --skill penpot-uiux-design
npx skills add github/awesome-copilot --skill penpot-uiux-design
Comprehensive guide for creating professional UI/UX designs in Penpot using MCP tools. Use this skill when: (1) Creating new UI/UX designs for web, mobile, or desktop applications, (2) Building design systems with components and tokens, (3) Designing dashboards, forms, navigation, or landing pages, (4) Applying accessibility standards and best practices, (5) Following platform guidelines (iOS, Android, Material Design), (6) Reviewing or improving existing Penpot designs for usability. Triggers: "design a UI", "create interface", "build layout", "design dashboard", "create form", "design landing page", "make it accessible", "design system", "component library".
Create professional, user-centered designs in Penpot using the penpot/penpot-mcp MCP server and proven UI/UX principles.
| 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 |
The Penpot MCP tools require the penpot/penpot-mcp server running locally. For detailed installation and troubleshooting, see setup-troubleshooting.md.
Always check if the MCP server is already available before attempting setup:
Try calling a tool first: Attempt mcp__penpot__penpot_api_info - if it succeeds, the server is running and connected. No setup needed.
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."
Only proceed with setup instructions if the user confirms the server is not installed.
Then in Penpot:
http://localhost:4400/manifest.jsonAdd to settings.json:
| 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 |
| Task | Reference File |
|---|---|
| MCP server installation & troubleshooting | setup-troubleshooting.md |
| Component specs (buttons, forms, nav) | component-patterns.md |
| Accessibility (contrast, touch targets) | accessibility.md |
| Screen sizes & platform specs | platform-guidelines.md |
mcp__penpot__execute_code with penpotUtils.shapeStructure() to see hierarchypenpotUtils.findShapes() to locate elements by type or namepenpot.createBoard(), penpot.createRectangle(), penpot.createText() etc.addFlexLayout() for responsive containersmcp__penpot__export_shape to visually check your workBefore creating designs, determine if the user has an existing design system:
If user HAS a design system:
If user has NO design system:
width/height are READ-ONLY → use shape.resize(w, h)parentX/parentY are READ-ONLY → use penpotUtils.setParentXY(shape, x, y)insertChild(index, shape) for z-ordering (not appendChild)dir="column" or dir="row"text.resize(), reset growType to "auto-width" or "auto-height"Always check existing boards before creating new ones to avoid overlap:
Board spacing guidelines:
Use these defaults only when user has no design system. Always prefer user's tokens if available.
| Token | Value | Usage |
|---|---|---|
spacing-xs | 4px | Tight inline elements |
spacing-sm | 8px | Related elements |
spacing-md | 16px | Default padding |
spacing-lg | 24px | Section spacing |
spacing-xl | 32px | Major sections |
spacing-2xl | 48px | Page-level spacing |
| Level | Size | Weight | Usage |
|---|---|---|---|
| Display | 48-64px | Bold | Hero headlines |
| H1 | 32-40px | Bold | Page titles |
| H2 | 24-28px | Semibold | Section headers |
| H3 | 20-22px | Semibold | Subsections |
| Body | 16px | Regular | Main content |
| Small | 14px | Regular | Secondary text |
| Caption | 12px | Regular | Labels, hints |
| Purpose | Recommendation |
|---|---|
| Primary | Main brand color, CTAs |
| Secondary | Supporting actions |
| Success | #22C55E range (confirmations) |
| Warning | #F59E0B range (caution) |
| Error | #EF4444 range (errors) |
| Neutral | Gray scale for text/borders |
Before finalizing any design:
Use these validation approaches with mcp__penpot__execute_code:
| Check | Method |
|---|---|
| Elements outside bounds | penpotUtils.analyzeDescendants() with isContainedIn() |
| Text too small (<12px) | penpotUtils.findShapes() filtering by fontSize |
| Missing contrast | Call mcp__penpot__export_shape and visually inspect |
| Hierarchy structure | penpotUtils.shapeStructure() to review nesting |
Use penpot.generateStyle(selection, { type: 'css', includeChildren: true }) via mcp__penpot__execute_code to extract CSS from designs.
// 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 };// 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);┌─────────────────────────────┐
│ Status Bar (44px) │
├─────────────────────────────┤
│ Header/Nav (56px) │
├─────────────────────────────┤
│ │
│ Content Area │
│ (Scrollable) │
│ Padding: 16px horizontal │
│ │
├─────────────────────────────┤
│ Bottom Nav/CTA (84px) │
└─────────────────────────────┘
┌──────┬──────────────────────────────────┐
│ │ Header (64px) │
│ Side │──────────────────────────────────│
│ bar │ Page Title + Actions │
│ │──────────────────────────────────│
│ 240 │ Content Grid │
│ px │ ┌─────┐ ┌─────┐ ┌─────┐ ┌─────┐ │
│ │ │Card │ │Card │ │Card │ │Card │ │
│ │ └─────┘ └─────┘ └─────┘ └─────┘ │
│ │ │
└──────┴──────────────────────────────────┘