Penpot UI/UX 设计指南

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

可用的 MCP 工具

MCP 服务器设置

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

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

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

1. 首先尝试调用工具：尝试调用 mcp__penpot__penpot_api_info – 如果成功，则服务器正在运行且已连接。无需设置。
2. 如果工具调用失败，询问用户：
   

   “Penpot MCP 服务器似乎未连接。服务器是否已安装并正在运行？如果是，我可以帮助进行故障排除。如果不是，我可以指导您完成设置。”

3. 只有在用户确认服务器未安装时，才继续进行设置说明。

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

# 克隆并安装
git clone https://github.com/penpot/penpot-mcp.git
cd penpot-mcp
npm install

# 构建并启动服务器
npm run bootstrap

然后在 Penpot 中：

1. 打开一个设计文件
2. 转到 插件 → 从 URL 加载插件
3. 输入：http://localhost:4400/manifest.json
4. 在插件界面中点击 “连接到 MCP 服务器”

VS Code 配置

添加到 settings.json：

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

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

快速参考

核心设计原则

黄金法则

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

视觉层次（优先级顺序）

1. 大小：越大 = 越重要
2. 颜色/对比度：高对比度吸引注意力
3. 位置：顶部左侧（LTR）最先被看到
4. 空白：隔离强调重要性
5. 字体粗细：粗体突出

设计工作流

1. 首先检查设计系统：询问用户是否有现有的标记/规范，或从当前 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 中发现：检查现有的组件、颜色和模式

// 发现当前文件中的现有设计模式
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 中的规范

关键 Penpot API 注意事项

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

新面板定位

在创建新面板之前，始终检查现有面板以避免重叠：

// 查找所有现有面板并计算下一个位置
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 坐标）以实现视觉组织
• 按用户流程顺序水平分组相关屏幕

默认设计标记

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

间距比例（8px 基准）

排版比例

颜色用途

常见布局

移动屏幕 (375×812)

┌─────────────────────────────┐
│ 状态栏 (44px)                │
├─────────────────────────────┤
│ 头部/导航 (56px)              │
├─────────────────────────────┤
│                             │
│ 内容区域                     │
│ (可滚动)                     │
│ 内边距: 水平 16px             │
│                             │
├─────────────────────────────┤
│ 底部导航/行动号召按钮 (84px)    │
└─────────────────────────────┘

桌面仪表板 (1440×900)

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

组件检查清单

按钮

• 清晰、面向操作的标签（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 使用以下验证方法：

导出 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. 提供反馈：每个操作都需要一个响应