Skip to content

Commit c9d70db

Browse files
aaronpowellaaronpowell
authored
Merge pull request #621 from Jcardif/add-penpot-uiux-design
Add penpot-uiux-design skill
2 parents b12dc28 + a6ac908 commit c9d70db

6 files changed

Lines changed: 1706 additions & 0 deletions

File tree

‎docs/README.skills.md‎

Lines changed: 1 addition & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -43,6 +43,7 @@ Skills differ from other primitives by supporting bundled assets (scripts, code
4343
| [microsoft-code-reference](../skills/microsoft-code-reference/SKILL.md) | Look up Microsoft API references, find working code samples, and verify SDK code is correct. Use when working with Azure SDKs, .NET libraries, or Microsoft APIs—to find the right method, check parameters, get working examples, or troubleshoot errors. Catches hallucinated methods, wrong signatures, and deprecated patterns by querying official docs. | None |
4444
| [microsoft-docs](../skills/microsoft-docs/SKILL.md) | Query official Microsoft documentation to understand concepts, find tutorials, and learn how services work. Use for Azure, .NET, Microsoft 365, Windows, Power Platform, and all Microsoft technologies. Get accurate, current information from learn.microsoft.com and other official Microsoft websites—architecture overviews, quickstarts, configuration guides, limits, and best practices. | None |
4545
| [nuget-manager](../skills/nuget-manager/SKILL.md) | Manage NuGet packages in .NET projects/solutions. Use this skill when adding, removing, or updating NuGet package versions. It enforces using `dotnet` CLI for package management and provides strict procedures for direct file edits only when updating versions. | None |
46+
| [penpot-uiux-design](../skills/penpot-uiux-design/SKILL.md) | 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". | `references/accessibility.md`<br />`references/component-patterns.md`<br />`references/platform-guidelines.md`<br />`references/setup-troubleshooting.md` |
4647
| [plantuml-ascii](../skills/plantuml-ascii/SKILL.md) | Generate ASCII art diagrams using PlantUML text mode. Use when user asks to create ASCII diagrams, text-based diagrams, terminal-friendly diagrams, or mentions plantuml ascii, text diagram, ascii art diagram. Supports: Converting PlantUML diagrams to ASCII art, Creating sequence diagrams, class diagrams, flowcharts in ASCII format, Generating Unicode-enhanced ASCII art with -utxt flag | None |
4748
| [prd](../skills/prd/SKILL.md) | Generate high-quality Product Requirements Documents (PRDs) for software systems and AI-powered features. Includes executive summaries, user stories, technical specifications, and risk analysis. | None |
4849
| [refactor](../skills/refactor/SKILL.md) | Surgical code refactoring to improve maintainability without changing behavior. Covers extracting functions, renaming variables, breaking down god functions, improving type safety, eliminating code smells, and applying design patterns. Less drastic than repo-rebuilder; use for gradual improvements. | None |

‎skills/penpot-uiux-design/SKILL.md‎

Lines changed: 342 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,342 @@
1+
---
2+
name: penpot-uiux-design
3+
description: '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".'
4+
---
5+
6+
# Penpot UI/UX Design Guide
7+
8+
Create professional, user-centered designs in Penpot using the `penpot/penpot-mcp` MCP server and proven UI/UX principles.
9+
10+
## Available MCP Tools
11+
12+
| Tool | Purpose |
13+
| ---- | ------- |
14+
| `mcp__penpot__execute_code` | Run JavaScript in Penpot plugin context to create/modify designs |
15+
| `mcp__penpot__export_shape` | Export shapes as PNG/SVG for visual inspection |
16+
| `mcp__penpot__import_image` | Import images (icons, photos, logos) into designs |
17+
| `mcp__penpot__penpot_api_info` | Retrieve Penpot API documentation |
18+
19+
## MCP Server Setup
20+
21+
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).
22+
23+
### Before Setup: Check If Already Running
24+
25+
**Always check if the MCP server is already available before attempting setup:**
26+
27+
1. **Try calling a tool first**: Attempt `mcp__penpot__penpot_api_info` - if it succeeds, the server is running and connected. No setup needed.
28+
29+
2. **If the tool fails**, ask the user:
30+
> "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."
31+
32+
3. **Only proceed with setup instructions if the user confirms the server is not installed.**
33+
34+
### Quick Start (Only If Not Installed)
35+
36+
```bash
37+
# Clone and install
38+
git clone https://github.com/penpot/penpot-mcp.git
39+
cd penpot-mcp
40+
npm install
41+
42+
# Build and start servers
43+
npm run bootstrap
44+
```
45+
46+
Then in Penpot:
47+
1. Open a design file
48+
2. Go to **Plugins** → **Load plugin from URL**
49+
3. Enter: `http://localhost:4400/manifest.json`
50+
4. Click **"Connect to MCP server"** in the plugin UI
51+
52+
### VS Code Configuration
53+
54+
Add to `settings.json`:
55+
```json
56+
{
57+
"mcp": {
58+
"servers": {
59+
"penpot": {
60+
"url": "http://localhost:4401/sse"
61+
}
62+
}
63+
}
64+
}
65+
```
66+
67+
### Troubleshooting (If Server Is Installed But Not Working)
68+
69+
| Issue | Solution |
70+
| ----- | -------- |
71+
| Plugin won't connect | Check servers are running (`npm run start:all` in penpot-mcp dir) |
72+
| Browser blocks localhost | Allow local network access prompt, or disable Brave Shield, or try Firefox |
73+
| Tools not appearing in client | Restart VS Code/Claude completely after config changes |
74+
| Tool execution fails/times out | Ensure Penpot plugin UI is open and shows "Connected" |
75+
| "WebSocket connection failed" | Check firewall allows ports 4400, 4401, 4402 |
76+
77+
## Quick Reference
78+
79+
| Task | Reference File |
80+
| ---- | -------------- |
81+
| MCP server installation & troubleshooting | [setup-troubleshooting.md](references/setup-troubleshooting.md) |
82+
| Component specs (buttons, forms, nav) | [component-patterns.md](references/component-patterns.md) |
83+
| Accessibility (contrast, touch targets) | [accessibility.md](references/accessibility.md) |
84+
| Screen sizes & platform specs | [platform-guidelines.md](references/platform-guidelines.md) |
85+
86+
## Core Design Principles
87+
88+
### The Golden Rules
89+
90+
1. **Clarity over cleverness**: Every element must have a purpose
91+
2. **Consistency builds trust**: Reuse patterns, colors, and components
92+
3. **User goals first**: Design for tasks, not features
93+
4. **Accessibility is not optional**: Design for everyone
94+
5. **Test with real users**: Validate assumptions early
95+
96+
### Visual Hierarchy (Priority Order)
97+
98+
1. **Size**: Larger = more important
99+
2. **Color/Contrast**: High contrast draws attention
100+
3. **Position**: Top-left (LTR) gets seen first
101+
4. **Whitespace**: Isolation emphasizes importance
102+
5. **Typography weight**: Bold stands out
103+
104+
## Design Workflow
105+
106+
1. **Check for design system first**: Ask user if they have existing tokens/specs, or discover from current Penpot file
107+
2. **Understand the page**: Call `mcp__penpot__execute_code` with `penpotUtils.shapeStructure()` to see hierarchy
108+
3. **Find elements**: Use `penpotUtils.findShapes()` to locate elements by type or name
109+
4. **Create/modify**: Use `penpot.createBoard()`, `penpot.createRectangle()`, `penpot.createText()` etc.
110+
5. **Apply layout**: Use `addFlexLayout()` for responsive containers
111+
6. **Validate**: Call `mcp__penpot__export_shape` to visually check your work
112+
113+
## Design System Handling
114+
115+
**Before creating designs, determine if the user has an existing design system:**
116+
117+
1. **Ask the user**: "Do you have a design system or brand guidelines to follow?"
118+
2. **Discover from Penpot**: Check for existing components, colors, and patterns
119+
120+
```javascript
121+
// Discover existing design patterns in current file
122+
const allShapes = penpotUtils.findShapes(() => true, penpot.root);
123+
124+
// Find existing colors in use
125+
const colors = new Set();
126+
allShapes.forEach(s => {
127+
if (s.fills) s.fills.forEach(f => colors.add(f.fillColor));
128+
});
129+
130+
// Find existing text styles (font sizes, weights)
131+
const textStyles = allShapes
132+
.filter(s => s.type === 'text')
133+
.map(s => ({ fontSize: s.fontSize, fontWeight: s.fontWeight }));
134+
135+
// Find existing components
136+
const components = penpot.library.local.components;
137+
138+
return { colors: [...colors], textStyles, componentCount: components.length };
139+
```
140+
141+
**If user HAS a design system:**
142+
143+
- Use their specified colors, spacing, typography
144+
- Match their existing component patterns
145+
- Follow their naming conventions
146+
147+
**If user has NO design system:**
148+
149+
- Use the default tokens below as a starting point
150+
- Offer to help establish consistent patterns
151+
- Reference specs in [component-patterns.md](references/component-patterns.md)
152+
153+
## Key Penpot API Gotchas
154+
155+
- `width`/`height` are READ-ONLY → use `shape.resize(w, h)`
156+
- `parentX`/`parentY` are READ-ONLY → use `penpotUtils.setParentXY(shape, x, y)`
157+
- Use `insertChild(index, shape)` for z-ordering (not `appendChild`)
158+
- Flex children array order is REVERSED for `dir="column"` or `dir="row"`
159+
- After `text.resize()`, reset `growType` to `"auto-width"` or `"auto-height"`
160+
161+
## Positioning New Boards
162+
163+
**Always check existing boards before creating new ones** to avoid overlap:
164+
165+
```javascript
166+
// Find all existing boards and calculate next position
167+
const boards = penpotUtils.findShapes(s => s.type === 'board', penpot.root);
168+
let nextX = 0;
169+
const gap = 100; // Space between boards
170+
171+
if (boards.length > 0) {
172+
// Find rightmost board edge
173+
boards.forEach(b => {
174+
const rightEdge = b.x + b.width;
175+
if (rightEdge + gap > nextX) {
176+
nextX = rightEdge + gap;
177+
}
178+
});
179+
}
180+
181+
// Create new board at calculated position
182+
const newBoard = penpot.createBoard();
183+
newBoard.x = nextX;
184+
newBoard.y = 0;
185+
newBoard.resize(375, 812);
186+
```
187+
188+
**Board spacing guidelines:**
189+
190+
- Use 100px gap between related screens (same flow)
191+
- Use 200px+ gap between different sections/flows
192+
- Align boards vertically (same y) for visual organization
193+
- Group related screens horizontally in user flow order
194+
195+
## Default Design Tokens
196+
197+
**Use these defaults only when user has no design system. Always prefer user's tokens if available.**
198+
199+
### Spacing Scale (8px base)
200+
201+
| Token | Value | Usage |
202+
| ----- | ----- | ----- |
203+
| `spacing-xs` | 4px | Tight inline elements |
204+
| `spacing-sm` | 8px | Related elements |
205+
| `spacing-md` | 16px | Default padding |
206+
| `spacing-lg` | 24px | Section spacing |
207+
| `spacing-xl` | 32px | Major sections |
208+
| `spacing-2xl` | 48px | Page-level spacing |
209+
210+
### Typography Scale
211+
212+
| Level | Size | Weight | Usage |
213+
| ----- | ---- | ------ | ----- |
214+
| Display | 48-64px | Bold | Hero headlines |
215+
| H1 | 32-40px | Bold | Page titles |
216+
| H2 | 24-28px | Semibold | Section headers |
217+
| H3 | 20-22px | Semibold | Subsections |
218+
| Body | 16px | Regular | Main content |
219+
| Small | 14px | Regular | Secondary text |
220+
| Caption | 12px | Regular | Labels, hints |
221+
222+
### Color Usage
223+
224+
| Purpose | Recommendation |
225+
| ------- | -------------- |
226+
| Primary | Main brand color, CTAs |
227+
| Secondary | Supporting actions |
228+
| Success | #22C55E range (confirmations) |
229+
| Warning | #F59E0B range (caution) |
230+
| Error | #EF4444 range (errors) |
231+
| Neutral | Gray scale for text/borders |
232+
233+
## Common Layouts
234+
235+
### Mobile Screen (375×812)
236+
237+
```text
238+
┌─────────────────────────────┐
239+
│ Status Bar (44px) │
240+
├─────────────────────────────┤
241+
│ Header/Nav (56px) │
242+
├─────────────────────────────┤
243+
│ │
244+
│ Content Area │
245+
│ (Scrollable) │
246+
│ Padding: 16px horizontal │
247+
│ │
248+
├─────────────────────────────┤
249+
│ Bottom Nav/CTA (84px) │
250+
└─────────────────────────────┘
251+
252+
```
253+
254+
### Desktop Dashboard (1440×900)
255+
256+
```text
257+
┌──────┬──────────────────────────────────┐
258+
│ │ Header (64px) │
259+
│ Side │──────────────────────────────────│
260+
│ bar │ Page Title + Actions │
261+
│ │──────────────────────────────────│
262+
│ 240 │ Content Grid │
263+
│ px │ ┌─────┐ ┌─────┐ ┌─────┐ ┌─────┐ │
264+
│ │ │Card │ │Card │ │Card │ │Card │ │
265+
│ │ └─────┘ └─────┘ └─────┘ └─────┘ │
266+
│ │ │
267+
└──────┴──────────────────────────────────┘
268+
269+
```
270+
271+
## Component Checklist
272+
273+
### Buttons
274+
275+
- [ ] Clear, action-oriented label (2-3 words)
276+
- [ ] Minimum touch target: 44×44px
277+
- [ ] Visual states: default, hover, active, disabled, loading
278+
- [ ] Sufficient contrast (3:1 against background)
279+
- [ ] Consistent border radius across app
280+
281+
### Forms
282+
283+
- [ ] Labels above inputs (not just placeholders)
284+
- [ ] Required field indicators
285+
- [ ] Error messages adjacent to fields
286+
- [ ] Logical tab order
287+
- [ ] Input types match content (email, tel, etc.)
288+
289+
### Navigation
290+
291+
- [ ] Current location clearly indicated
292+
- [ ] Consistent position across screens
293+
- [ ] Maximum 7±2 top-level items
294+
- [ ] Touch-friendly on mobile (48px targets)
295+
296+
## Accessibility Quick Checks
297+
298+
1. **Color contrast**: Text 4.5:1, Large text 3:1
299+
2. **Touch targets**: Minimum 44×44px
300+
3. **Focus states**: Visible keyboard focus indicators
301+
4. **Alt text**: Meaningful descriptions for images
302+
5. **Hierarchy**: Proper heading levels (H1→H2→H3)
303+
6. **Color independence**: Never rely solely on color
304+
305+
## Design Review Checklist
306+
307+
Before finalizing any design:
308+
309+
- [ ] Visual hierarchy is clear
310+
- [ ] Consistent spacing and alignment
311+
- [ ] Typography is readable (16px+ body text)
312+
- [ ] Color contrast meets WCAG AA
313+
- [ ] Interactive elements are obvious
314+
- [ ] Mobile-friendly touch targets
315+
- [ ] Loading/empty/error states considered
316+
- [ ] Consistent with design system
317+
318+
## Validating Designs
319+
320+
Use these validation approaches with `mcp__penpot__execute_code`:
321+
322+
| Check | Method |
323+
| ----- | ------ |
324+
| Elements outside bounds | `penpotUtils.analyzeDescendants()` with `isContainedIn()` |
325+
| Text too small (<12px) | `penpotUtils.findShapes()` filtering by `fontSize` |
326+
| Missing contrast | Call `mcp__penpot__export_shape` and visually inspect |
327+
| Hierarchy structure | `penpotUtils.shapeStructure()` to review nesting |
328+
329+
### Export CSS
330+
331+
Use `penpot.generateStyle(selection, { type: 'css', includeChildren: true })` via `mcp__penpot__execute_code` to extract CSS from designs.
332+
333+
## Tips for Great Designs
334+
335+
1. **Start with content**: Real content reveals layout needs
336+
2. **Design mobile-first**: Constraints breed creativity
337+
3. **Use a grid**: 8px base grid keeps things aligned
338+
4. **Limit colors**: 1 primary + 1 secondary + neutrals
339+
5. **Limit fonts**: 1-2 typefaces maximum
340+
6. **Embrace whitespace**: Breathing room improves comprehension
341+
7. **Be consistent**: Same action = same appearance everywhere
342+
8. **Provide feedback**: Every action needs a response

0 commit comments

Comments
 (0)