Guides UI/UX design in Penpot using MCP tools to build layouts, design systems, dashboards, forms; applies accessibility and platform guidelines.
From awesome-copilotnpx claudepluginhub ctr26/dotfiles --plugin awesome-copilotThis skill uses the workspace's default tool permissions.
references/accessibility.mdreferences/component-patterns.mdreferences/platform-guidelines.mdreferences/setup-troubleshooting.mdFetches up-to-date documentation from Context7 for libraries and frameworks like React, Next.js, Prisma. Use for setup questions, API references, and code examples.
Fetches up-to-date documentation from Context7 for libraries and frameworks like React, Next.js, Prisma. Use for setup questions, API references, and code examples.
Uses ctx7 CLI to fetch current library docs, manage AI coding skills (install/search/generate), and configure Context7 MCP for AI editors.
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.
# 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:
http://localhost:4400/manifest.jsonAdd to settings.json:
{
"mcp": {
"servers": {
"penpot": {
"url": "http://localhost:4401/sse"
}
}
}
}
| 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:
// 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:
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:
// 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 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 |
┌─────────────────────────────┐
│ 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 │ │
│ │ └─────┘ └─────┘ └─────┘ └─────┘ │
│ │ │
└──────┴──────────────────────────────────┘
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.