penpot-uiux-design

Penpot UI/UX 设计指南

使用 penpot/penpot-mcp MCP 服务，结合成熟的 UI/UX 原则，在 Penpot 中创建专业且以用户为中心的设计。

可用的 MCP 工具

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

MCP 服务设置

Penpot MCP 工具需要本地运行 penpot/penpot-mcp 服务。有关详细的安装和故障排除，请参阅 setup-troubleshooting.md。

设置之前：检查是否已在运行

在尝试设置之前，始终检查 MCP 服务是否已可用：

1. 先尝试调用工具：尝试调用 mcp__penpot__penpot_api_info —— 如果成功，说明服务正在运行且已连接。无需设置。

2. 如果工具调用失败，请询问用户：

   "Penpot MCP 服务似乎未连接。该服务是否已安装并正在运行？如果是，我可以帮助排除故障。如果不是，我可以引导你完成设置。"

3. 仅在用户确认该服务尚未安装时，才继续执行设置说明。

快速开始（仅在未安装时）

# Clone and install
git clone https://github.com/penpot/penpot-mcp.git
cd penpot-mcp
npm install

# Build and start servers
npm run bootstrap

然后在 Penpot 中：

1. 打开一个设计文件
2. 转到 Plugins → Load plugin from URL
3. 输入：http://localhost:4400/manifest.json
4. 在插件 UI 中点击 "Connect to MCP server"

VS Code 配置

添加到 settings.json：

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

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

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

快速参考

任务	参考文件
MCP 服务安装与故障排除	setup-troubleshooting.md
组件规格（按钮、表单、导航）	component-patterns.md
无障碍性（对比度、触摸目标）	accessibility.md
屏幕尺寸与平台规格	platform-guidelines.md

核心设计原则

黄金法则

1. 清晰胜于巧妙：每个元素都必须有明确用途
2. 一致性建立信任：复用模式、颜色和组件
3. 用户目标优先：为任务而设计，而非为功能而设计
4. 无障碍性不是可选项：为所有人而设计
5. 与真实用户一起测试：尽早验证假设

视觉层次（优先级顺序）

1. 大小：越大 = 越重要
2. 颜色/对比度：高对比度吸引注意力
3. 位置：左上角（LTR）最先被看到
4. 留白：孤立强调重要性
5. 字体粗细：加粗更突出

设计工作流

1. 首先检查设计系统：询问用户是否有现有的 token/规格，或从当前 Penpot 文件中发现
2. 了解页面：调用 mcp__penpot__execute_code 并使用 penpotUtils.shapeStructure() 查看层次结构
3. 查找元素：使用 penpotUtils.findShapes() 按类型或名称定位元素
4. 创建/修改：使用 penpot.createBoard()、penpot.createRectangle()、penpot.createText() 等
5. 应用布局：使用 addFlexLayout() 创建响应式容器
6. 验证：调用 mcp__penpot__export_shape 以视觉方式检查你的工作

设计系统处理

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

1. 询问用户："你有要遵循的设计系统或品牌指南吗？"
2. 从 Penpot 中探查：检查现有组件、颜色和模式

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

如果用户有设计系统：

• 使用其指定的颜色、间距、字体排版
• 匹配其现有组件模式
• 遵循其命名约定

如果用户没有设计系统：

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

Penpot API 关键陷阱

• width/height 是只读的 → 使用 shape.resize(w, h)
• parentX/parentY 是只读的 → 使用 penpotUtils.setParentXY(shape, x, y)
• 使用 insertChild(index, shape) 控制 z 轴顺序（而不是 appendChild）
• 当 dir="column" 或 dir="row" 时，Flex 子元素数组的顺序是相反的
• 在 text.resize() 之后，将 growType 重置为 "auto-width" 或 "auto-height"

定位新画板

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

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

画板间距指南：

• 相关屏幕（同一流程）之间使用 100px 间距
• 不同区块/流程之间使用 200px+ 间距
• 将画板垂直对齐（相同的 y）以便于视觉组织
• 按用户流程顺序将相关屏幕水平分组

默认设计 Token

仅在用户没有设计系统时使用这些默认值。如果用户有可用 token，始终优先使用用户的 token。

间距刻度（8px 基准）

Token	值	用途
spacing-xs	4px	紧凑的行内元素
spacing-sm	8px	相关元素
spacing-md	16px	默认内边距
spacing-lg	24px	区块间距
spacing-xl	32px	主要区块
spacing-2xl	48px	页面级间距

字体排版刻度

层级	字号	字重	用途
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	标签、提示

颜色使用

用途	建议
Primary	主品牌色、CTA
Secondary	辅助操作
Success	#22C55E 范围（确认）
Warning	#F59E0B 范围（警示）
Error	#EF4444 范围（错误）
Neutral	用于文本/边框的灰色阶

常见布局

移动端屏幕（375×812）

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

桌面端仪表盘（1440×900）

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

组件检查清单

按钮

• 清晰、面向操作的标签（2-3 个词）
• 最小触控目标：44×44px
• 视觉状态：默认、悬停、激活、禁用、加载中
• 足够对比度（相对于背景 3:1）
• 整个应用保持一致边框圆角

表单

• 标签位于输入框上方（不只是占位符）
• 必填字段标识
• 错误消息紧邻字段
• 合理的 Tab 键顺序
• 输入类型与内容匹配（email、tel 等）

导航

• 当前位置清晰指示
• 各屏幕位置一致
• 顶层项最多 7±2 个
• 移动端触控友好（48px 目标）

无障碍快速检查

1. 颜色对比度：文本 4.5:1，大号文本 3:1
2. 触控目标：最小 44×44px
3. 焦点状态：可见的键盘焦点指示器
4. 替代文本：为图片提供有意义的描述
5. 层级：正确的标题层级（H1→H2→H3）
6. 不依赖颜色：绝不只依赖颜色

设计评审检查清单

在最终确定任何设计之前：

• 视觉层级清晰
• 间距和对齐一致
• 排版可读（正文文字 16px+）
• 颜色对比度符合 WCAG AA
• 交互元素显而易见
• 适合移动端的触控目标
• 已考虑加载/空/错误状态
• 与设计系统保持一致

验证设计

通过 mcp__penpot__execute_code 使用这些验证方法：

检查	方法
元素超出边界	使用带 isContainedIn() 的 penpotUtils.analyzeDescendants()
文字过小（<12px）	使用 penpotUtils.findShapes() 按 fontSize 筛选
对比度缺失	调用 mcp__penpot__export_shape 并进行目视检查
层级结构	使用 penpotUtils.shapeStructure() 检查嵌套情况

导出 CSS

通过 mcp__penpot__execute_code 使用 penpot.generateStyle(selection, { type: 'css', includeChildren: true }) 从设计中提取 CSS。

打造出色设计的技巧

1. 从内容开始：真实内容会揭示布局需求
2. 移动优先设计：约束孕育创造力
3. 使用网格：8px 基础网格让一切保持对齐
4. 限制颜色：1 种主色 + 1 种辅助色 + 中性色
5. 限制字体：最多 1-2 种字体
6. 拥抱留白：呼吸空间有助于理解
7. 保持一致：相同的操作 = 处处相同的外观
8. 提供反馈：每个操作都需要一个响应