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. 仅在用户确认服务器未安装时，才继续执行设置说明。

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

# 克隆并安装
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. 在插件 UI 中点击 “连接到 MCP 服务器”

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 已打开并显示“已连接”
“WebSocket 连接失败”	检查防火墙是否允许端口 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. 首先检查设计系统：询问用户是否有现有的令牌/规范，或从当前 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"，flex 子元素数组顺序是反转的
• 在 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 基准）

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

排版比例

级别	大小	字重	用途
展示	48-64px	粗体	主标题
H1	32-40px	粗体	页面标题
H2	24-28px	半粗体	部分标题
H3	20-22px	半粗体	子部分
正文	16px	常规	主要内容
小号	14px	常规	次要文本
说明	12px	常规	标签、提示

颜色用法

用途	建议
主要	主品牌色，行动号召按钮
次要	辅助操作
成功	#22C55E 范围（确认）
警告	#F59E0B 范围（谨慎）
错误	#EF4444 范围（错误）
中性	用于文本/边框的灰色

常见布局

移动屏幕（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：

检查项	方法
元素超出边界	penpotUtils.analyzeDescendants() 配合 isContainedIn()
文本太小（<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. 提供反馈：每个操作都需要响应