penpot-uiux-design

Compare original and translation side by side

🇺🇸

Original

English

🇨🇳

Translation

Chinese

Penpot UI/UX Design Guide

Penpot UI/UX 设计指南

Create professional, user-centered designs in Penpot using the

penpot/penpot-mcp

MCP server and proven UI/UX principles.

借助

penpot/penpot-mcp

MCP服务器和经过验证的UI/UX原则，在Penpot中创建专业的、以用户为中心的设计。

Available MCP Tools

可用的MCP工具

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

工具	用途
`mcp__penpot__execute_code`	在Penpot插件环境中运行JavaScript以创建/修改设计
`mcp__penpot__export_shape`	将图形导出为PNG/SVG格式以便视觉检查
`mcp__penpot__import_image`	将图片（图标、照片、Logo）导入设计中
`mcp__penpot__penpot_api_info`	获取Penpot API文档

MCP Server Setup

MCP服务器设置

The Penpot MCP tools require the

penpot/penpot-mcp

server running locally. For detailed installation and troubleshooting, see setup-troubleshooting.md.

Penpot MCP工具需要本地运行

penpot/penpot-mcp

服务器。有关详细的安装和故障排除说明，请参阅setup-troubleshooting.md。

Before Setup: Check If Already Running

设置前：检查服务器是否已运行

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.

在尝试设置前，请务必先检查MCP服务器是否已可用：

先尝试调用工具：调用
```
mcp__penpot__penpot_api_info
```
——如果调用成功，说明服务器已运行并连接，无需进行设置。
如果工具调用失败，请询问用户：

"Penpot MCP服务器似乎未连接。服务器是否已安装并运行？如果已安装，我可以协助排查故障；如果未安装，我可以引导您完成设置流程。"
仅当用户确认服务器未安装时，才继续执行设置说明。

Quick Start (Only If Not Installed)

快速开始（仅适用于未安装服务器的情况）

bash

undefined

bash

undefined

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

npm run bootstrap


然后在Penpot中执行以下操作：
1. 打开一个设计文件
2. 前往**插件** → **从URL加载插件**
3. 输入：`http://localhost:4400/manifest.json`
4. 在插件界面中点击**"连接到MCP服务器"**

VS Code Configuration

VS Code配置

Add to

settings.json

json

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

在

settings.json

中添加以下内容：

json

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

Troubleshooting (If Server Is Installed But Not Working)

故障排除（服务器已安装但无法正常工作时）

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

问题	解决方案
插件无法连接	检查服务器是否在运行（在penpot-mcp目录中执行 `npm run start:all` ）
浏览器阻止localhost连接	允许本地网络访问提示，或关闭Brave Shield，或尝试使用Firefox浏览器
工具未在客户端中显示	修改配置后完全重启VS Code/Claude
工具执行失败/超时	确保Penpot插件界面已打开并显示"已连接"状态
"WebSocket连接失败"	检查防火墙是否允许4400、4401、4402端口通行

Quick Reference

快速参考

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服务器安装与故障排除	setup-troubleshooting.md
组件规范（按钮、表单、导航）	component-patterns.md
无障碍设计（对比度、触摸目标）	accessibility.md
屏幕尺寸与平台规范	platform-guidelines.md

Core Design Principles

核心设计原则

The Golden Rules

黄金法则

Clarity over cleverness: Every element must have a purpose
Consistency builds trust: Reuse patterns, colors, and components
User goals first: Design for tasks, not features
Accessibility is not optional: Design for everyone
Test with real users: Validate assumptions early

清晰优先于花哨：每个元素都必须有明确的用途
一致性建立信任：复用设计模式、颜色和组件
用户目标至上：围绕任务而非功能进行设计
无障碍设计并非可选：为所有用户设计
与真实用户测试：尽早验证假设

Visual Hierarchy (Priority Order)

视觉层级（优先级顺序）

Size: Larger = more important
Color/Contrast: High contrast draws attention
Position: Top-left (LTR) gets seen first
Whitespace: Isolation emphasizes importance
Typography weight: Bold stands out

尺寸：越大越重要
颜色/对比度：高对比度吸引注意力
位置：左上区域（从左到右阅读习惯）最先被注意到
留白：隔离元素可突出其重要性
字体粗细：粗体更显眼

Design Workflow

设计工作流

Check for design system first: Ask user if they have existing tokens/specs, or discover from current Penpot file

Understand the page: Call

mcp__penpot__execute_code

with

penpotUtils.shapeStructure()

to see hierarchy

Find elements: Use
```
penpotUtils.findShapes()
```
to locate elements by type or name

Create/modify: Use

penpot.createBoard()

penpot.createRectangle()

penpot.createText()

etc.

Apply layout: Use
```
addFlexLayout()
```
for responsive containers
Validate: Call
```
mcp__penpot__export_shape
```
to visually check your work

先检查是否有设计系统：询问用户是否有现有的设计令牌/规范，或从当前Penpot文件中识别
了解页面结构：调用
```
mcp__penpot__execute_code
```
并传入
```
penpotUtils.shapeStructure()
```
以查看层级结构
查找元素：使用
```
penpotUtils.findShapes()
```
按类型或名称定位元素

创建/修改：使用

penpot.createBoard()

、

penpot.createRectangle()

、

penpot.createText()

等方法

应用布局：使用
```
addFlexLayout()
```
创建响应式容器
验证：调用
```
mcp__penpot__export_shape
```
以视觉检查工作成果

Design System Handling

设计系统处理

Before creating designs, determine if the user has an existing design system:

Ask the user: "Do you have a design system or brand guidelines to follow?"
Discover from Penpot: Check for existing components, colors, and patterns

javascript

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

在创建设计前，先确定用户是否有现有的设计系统：

询问用户："您是否有需要遵循的设计系统或品牌规范？"
从Penpot中识别：检查是否有现有组件、颜色和设计模式

javascript

// 识别当前文件中的现有设计模式
const allShapes = penpotUtils.findShapes(() => true, penpot.root);

// 查找已使用的颜色
const colors = new Set();
allShapes.forEach(s => {
  if (s.fills) s.fills.forEach(f => colors.add(f.fillColor));
});

// 查找现有文本样式（字体大小、粗细）
const textStyles = allShapes
  .filter(s => s.type === 'text')
  .map(s => ({ fontSize: s.fontSize, fontWeight: s.fontWeight }));

// 查找现有组件
const components = penpot.library.local.components;

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

如果用户已有设计系统：

使用用户指定的颜色、间距和排版
匹配现有组件模式
遵循命名规范

如果用户没有设计系统：

使用以下默认设计令牌作为起点
主动提出帮助建立一致的设计模式
参考component-patterns.md中的规范

Key Penpot API Gotchas

Penpot API关键注意事项

```
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

"auto-width"

"auto-height"

```
width
```
/
```
height
```
为只读属性 → 使用
```
shape.resize(w, h)
```
方法

parentX

parentY

为只读属性 → 使用

penpotUtils.setParentXY(shape, x, y)

方法

使用
```
insertChild(index, shape)
```
控制层级顺序（而非
```
appendChild
```
）
当
```
dir="column"
```
或
```
dir="row"
```
时，Flex子元素数组顺序是反向的

执行

text.resize()

后，需将

growType

重置为

"auto-width"

或

"auto-height"

Positioning New Boards

新画板定位

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

javascript

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

创建新画板前务必检查现有画板，避免重叠：

javascript

// 查找所有现有画板并计算下一个位置
const boards = penpotUtils.findShapes(s => s.type === 'board', penpot.root);
let nextX = 0;
const gap = 100; // 画板之间的间距

if (boards.length > 0) {
  // 找到最右侧的画板边缘
  boards.forEach(b => {
    const rightEdge = b.x + b.width;
    if (rightEdge + gap > nextX) {
      nextX = rightEdge + gap;
    }
  });
}

// 在计算出的位置创建新画板
const newBoard = penpot.createBoard();
newBoard.x = nextX;
newBoard.y = 0;
newBoard.resize(375, 812);

画板间距规范：

相关屏幕（同一流程）之间使用100px间距
不同章节/流程之间使用200px以上间距
垂直对齐画板（相同y坐标）以保持视觉整洁
按用户流程顺序水平分组相关屏幕

Default Design Tokens

默认设计令牌

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

仅当用户没有设计系统时使用这些默认值。如果用户有自己的令牌，请优先使用。

Spacing Scale (8px base)

间距比例（以8px为基准）

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

令牌	值	用途
`spacing-xs`	4px	紧凑的内联元素
`spacing-sm`	8px	关联元素之间
`spacing-md`	16px	默认内边距
`spacing-lg`	24px	章节间距
`spacing-xl`	32px	主要章节间距
`spacing-2xl`	48px	页面级间距

Typography Scale

排版比例

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

层级	字号	字重	用途
Display	48-64px	Bold	英雄标题
H1	32-40px	Bold	页面标题
H2	24-28px	Semibold	章节标题
H3	20-22px	Semibold	子章节标题
Body	16px	Regular	主要内容
Small	14px	Regular	次要文本
Caption	12px	Regular	标签、提示文本

Color Usage

颜色使用规范

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

用途	建议
Primary	主品牌色，用于主要操作按钮（CTA）
Secondary	辅助操作按钮
Success	#22C55E色系（确认提示）
Warning	#F59E0B色系（警告提示）
Error	#EF4444色系（错误提示）
Neutral	灰度色系，用于文本/边框

Common Layouts

常见布局

Mobile Screen (375×812)

移动端屏幕（375×812）

text

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

text

┌─────────────────────────────┐
│ 状态栏（44px）              │
├─────────────────────────────┤
│ 头部导航栏（56px）          │
├─────────────────────────────┤
│                             │
│ 内容区域                    │
│ （可滚动）                  │
│ 水平内边距：16px            │
│                             │
├─────────────────────────────┤
│ 底部导航/操作栏（84px）      │
└─────────────────────────────┘

Desktop Dashboard (1440×900)

桌面端仪表板（1440×900）

text

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

text

┌──────┬──────────────────────────────────┐
│      │ 头部栏（64px）                    │
│ 侧边 │──────────────────────────────────│
│ 栏   │ 页面标题 + 操作按钮              │
│      │──────────────────────────────────│
│ 240  │ 内容网格                        │
│ px   │ ┌─────┐ ┌─────┐ ┌─────┐ ┌─────┐ │
│      │ │卡片 │ │卡片 │ │卡片 │ │卡片 │ │
│      │ └─────┘ └─────┘ └─────┘ └─────┘ │
│      │                                  │
└──────┴──────────────────────────────────┘

Component Checklist

组件检查清单

Buttons

按钮

Forms

表单

Navigation

Accessibility Quick Checks

无障碍设计快速检查

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

颜色对比度：普通文本4.5:1，大文本3:1
触摸目标：最小44×44px
焦点状态：可见的键盘焦点指示器
替代文本：图片的有意义描述
层级结构：正确的标题层级（H1→H2→H3）
颜色独立性：绝不单独依赖颜色传递信息

Design Review Checklist

设计评审检查清单

Validating Designs

设计验证

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

结合

mcp__penpot__execute_code

使用以下验证方法：

检查项	方法
元素超出边界	使用 `penpotUtils.analyzeDescendants()` 结合 `isContainedIn()`
文本过小（<12px）	使用 `penpotUtils.findShapes()` 按 `fontSize` 过滤
对比度不足	调用 `mcp__penpot__export_shape` 并进行视觉检查
层级结构	使用 `penpotUtils.shapeStructure()` 查看嵌套关系

Export CSS

导出CSS

Use

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

via

mcp__penpot__execute_code

to extract CSS from designs.

通过

mcp__penpot__execute_code

调用

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

从设计中提取CSS代码。

Tips for Great Designs

优秀设计技巧

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

从内容开始：真实内容能揭示布局需求
移动端优先设计：约束激发创意
使用网格：以8px为基准的网格确保对齐一致
限制颜色数量：1种主色 + 1种辅助色 + 中性色
限制字体数量：最多1-2种字体
善用留白：呼吸空间提升内容可读性
保持一致性：相同操作对应相同外观
提供反馈：每个操作都应有响应