Pencil MCP 工业级 UI 设计 Skills

本 Skills 提供了一套工业级标准的 UI 设计规范，用于 Pencil MCP 设计工作。

快速开始

1. 初始化设计系统变量

在开始设计前，先设置设计系统变量：

mcp_pencil_set_variables({
  filePath: "<your-file.pen>",
  variables: {
    // 参考 design-tokens.json 中的完整变量定义
  }
})

2. 创建可复用组件

使用 reusable: true 创建组件，通过 ref 复用：

// 创建组件
buttonPrimary=I(document, {type: "frame", reusable: true, name: "Button/Primary", ...})

// 使用组件
btn1=I(someParent, {type: "ref", ref: "buttonPrimary"})

设计系统规范

颜色系统 (Color Tokens)

| 变量名 | Light Mode | Dark Mode | 用途 | |--------|------------|-----------|------| | --background | #FAFAFA | #09090B | 页面背景 | | --foreground | #18181B | #FAFAFA | 主文本 | | --card | #FFFFFF | #18181B | 卡片背景 | | --card-foreground | #18181B | #FAFAFA | 卡片文本 | | --muted | #F4F4F5 | #27272A | 次要背景 | | --muted-foreground | #71717A | #A1A1AA | 次要文本 | | --border | #E4E4E7 | #27272A | 边框 | | --primary | #18181B | #FAFAFA | 主按钮 | | --primary-foreground | #FAFAFA | #18181B | 主按钮文本 | | --secondary | #F4F4F5 | #27272A | 次按钮 | | --accent | #FCD34D | #FCD34D | 强调色 | | --destructive | #EF4444 | #EF4444 | 危险操作 | | --ring | #18181B | #D4D4D8 | Focus ring |

字体层级 (Typography Scale)

| 层级 | 大小 | 字重 | 行高 | 用途 | |------|------|------|------|------| | Display | 36px | 700 | 1.2 | 大标题 | | H1 | 24px | 600 | 1.3 | 页面标题 | | H2 | 20px | 600 | 1.4 | 区块标题 | | H3 | 18px | 600 | 1.4 | 卡片标题 | | Body | 14px | 400 | 1.5 | 正文 | | Small | 12px | 400 | 1.4 | 辅助文本 | | Caption | 10px | 500 | 1.3 | 标签 |

推荐字体: Inter (英文), Noto Sans SC (中文)

间距系统 (Spacing)

基于 4px 网格：

xs: 4px
sm: 8px
md: 12px
lg: 16px
xl: 24px
2xl: 32px
3xl: 48px

圆角规范 (Border Radius)

| 变量 | 值 | 用途 | |------|-----|------| | radius-sm | 6px | 小元素 (Badge, Chip) | | radius-md | 8px | 按钮、输入框 | | radius-lg | 12px | 卡片、弹窗 | | radius-xl | 16px | 大卡片 | | radius-full | 9999px | 圆形头像 |

阴影系统 (Shadows)

{
  "shadow-sm": {
    "type": "shadow",
    "shadowType": "outer",
    "color": "#0000000D",
    "blur": 2,
    "offset": {"x": 0, "y": 1}
  },
  "shadow-md": {
    "type": "shadow",
    "shadowType": "outer",
    "color": "#0000000A",
    "blur": 6,
    "offset": {"x": 0, "y": 4}
  },
  "shadow-lg": {
    "type": "shadow",
    "shadowType": "outer",
    "color": "#00000014",
    "blur": 15,
    "offset": {"x": 0, "y": 8}
  }
}

组件规范

Button 按钮

Primary Button

{
  "type": "frame",
  "name": "Button/Primary",
  "reusable": true,
  "height": 40,
  "layout": "horizontal",
  "padding": [16, 10],
  "gap": 8,
  "alignItems": "center",
  "justifyContent": "center",
  "fill": "#18181B",
  "cornerRadius": 8,
  "effect": {
    "type": "shadow",
    "shadowType": "outer",
    "color": "#0000001A",
    "blur": 2,
    "offset": {"x": 0, "y": 1}
  }
}
// 文本: fill="#FFFFFF", fontFamily="Inter", fontSize=14, fontWeight=500

Secondary Button

{
  "fill": "#F4F4F5",
  "stroke": "#E4E4E7",
  "strokeThickness": 1,
  "cornerRadius": 8
}
// 文本: fill="#18181B"

Ghost Button

{
  "fill": "transparent",
  "cornerRadius": 8
}
// Hover: fill="#F4F4F5"

Destructive Button

{
  "fill": "#EF4444",
  "cornerRadius": 8
}
// 文本: fill="#FFFFFF"

Card 卡片

{
  "type": "frame",
  "name": "Card",
  "reusable": true,
  "layout": "vertical",
  "padding": 16,
  "gap": 12,
  "fill": "#FFFFFF",
  "stroke": "#E4E4E7",
  "strokeThickness": 1,
  "cornerRadius": 12,
  "effect": {
    "type": "shadow",
    "shadowType": "outer",
    "color": "#0000000A",
    "blur": 4,
    "offset": {"x": 0, "y": 2}
  }
}

Input 输入框

{
  "type": "frame",
  "name": "Input",
  "reusable": true,
  "height": 40,
  "layout": "horizontal",
  "padding": [12, 10],
  "gap": 8,
  "alignItems": "center",
  "fill": "#FFFFFF",
  "stroke": "#E4E4E7",
  "strokeThickness": 1,
  "cornerRadius": 8
}
// Focus 状态: stroke="#18181B", strokeThickness=2

Avatar 头像

{
  "type": "frame",
  "name": "Avatar",
  "reusable": true,
  "width": 40,
  "height": 40,
  "cornerRadius": 9999,
  "fill": "#F4F4F5",
  "layout": "vertical",
  "alignItems": "center",
  "justifyContent": "center"
}

Badge 徽章

{
  "type": "frame",
  "name": "Badge",
  "reusable": true,
  "height": 22,
  "layout": "horizontal",
  "padding": [6, 8],
  "alignItems": "center",
  "justifyContent": "center",
  "fill": "#F4F4F5",
  "stroke": "#E4E4E7",
  "strokeThickness": 1,
  "cornerRadius": 6
}
// 文本: fontSize=10, fontWeight=500

图标规范

⚠️ 重要: Pencil MCP 使用 Material Symbols Rounded 图标字体，不是 Lucide！

基本用法

{
  "type": "icon_font",
  "iconFontFamily": "Material Symbols Rounded",
  "iconFontName": "home",
  "fontSize": 24,
  "width": 24,
  "height": 24,
  "fill": "#71717A"
}

注意: 必须同时设置 fontSize、width 和 height 属性，否则图标可能不显示！

常用图标速查表

| 类别 | 图标名称 | 用途 | |------|----------|------| | 导航 | home, menu, arrow_back, arrow_forward, close | 导航和菜单 | | 操作 | add, edit, delete, search, settings | 常用操作 | | 状态 | check_circle, error, warning, info | 状态提示 | | 媒体 | headphones, mic, volume_up, play_arrow, pause | 音频视频 | | 社交 | person, group, share, favorite, star | 社交功能 | | 文件 | folder, description, menu_book, article | 文件文档 | | 通信 | mail, chat, notifications, send | 消息通知 | | 游戏 | extension, sports_esports, military_tech | 游戏奖励 | | 学习 | school, lightbulb, timer, assignment | 教育学习 |

图标尺寸规范

| 尺寸 | 值 | 用途 | |------|-----|------| | XS | 16px | 辅助小图标、徽章内 | | SM | 20px | 按钮内图标、列表图标 | | MD | 24px | 标准图标、导航图标 | | LG | 32px | 大按钮、空状态图标 | | XL | 48px | 特殊强调、卡片主图标 |

完整示例

// 创建一个带图标的按钮
iconBtn=I(parent, {
  type: "frame",
  width: 48,
  height: 48,
  layout: "vertical",
  alignItems: "center",
  justifyContent: "center",
  fill: "#1E2A2F",
  cornerRadius: 9999
})
icon=I(iconBtn, {
  type: "icon_font",
  iconFontFamily: "Material Symbols Rounded",
  iconFontName: "add",
  fontSize: 24,
  width: 24,
  height: 24,
  fill: "#FFFFFF"
})

图片素材处理

使用 G() 操作生成图片

Pencil MCP 提供 G() 操作来生成或获取图片，支持两种方式：

AI 生成图片 (推荐用于插画、头像、图标)

// 先创建一个 frame 容器
avatar=I(parent, {type: "frame", width: 48, height: 48, cornerRadius: 9999})
// 使用 AI 生成图片填充
G(avatar, "ai", "cute cartoon boy avatar, friendly smile, warm colors, children illustration style")

Stock 图片 (推荐用于真实照片)

// 获取 Unsplash 图片
heroImg=I(parent, {type: "frame", width: 400, height: 300})
G(heroImg, "stock", "modern office workspace laptop natural light")

Prompt 编写技巧

| 类型 | 好的 Prompt | 不好的 Prompt | |------|-------------|---------------| | 头像 | "cute cartoon boy, round face, brown hair, warm yellow background, simple illustration" | "boy" | | 图标 | "isometric cloud server icon, soft gradients, minimalist" | "server" | | 背景 | "abstract gradient purple blue, soft blur, dreamy atmosphere" | "background" |

图片使用注意事项

没有 image 节点类型 - 图片只能作为 frame/rectangle 的填充
先创建容器 - 必须先用 I() 创建 frame，再用 G() 应用图片
设置正确尺寸 - frame 的 width/height 决定显示尺寸
圆角裁剪 - 设置 cornerRadius: 9999 可实现圆形图片

文本处理规范

防止文本溢出

当文本内容较长时，必须设置以下属性防止溢出：

{
  "type": "text",
  "content": "这是一段很长的文本内容...",
  "width": "fill_container",
  "textGrowth": "fixed-width",
  "lineHeight": 1.5
}

textGrowth 属性说明

| 值 | 说明 | 适用场景 | |----|------|----------| | "auto" | 文本根据内容自动调整宽度（默认） | 短文本、标签 | | "fixed-width" | 固定宽度，超出自动换行 | 段落、描述文本 | | "truncate" | 固定宽度，超出显示省略号 | 列表项标题 |

常见文本样式

// 段落文本 (自动换行)
paragraph=I(parent, {
  type: "text",
  content: "这是一段较长的描述文本，需要自动换行显示。",
  width: "fill_container",
  textGrowth: "fixed-width",
  fontSize: 14,
  lineHeight: 1.5,
  fill: "#71717A"
})

// 标题文本 (单行)
title=I(parent, {
  type: "text",
  content: "标题文本",
  fontSize: 18,
  fontWeight: 600,
  fill: "#1E2A2F"
})

设计工作流

第一步：设置设计系统

打开或创建 .pen 文件
使用 mcp_pencil_set_variables 设置颜色变量
创建可复用组件

第二步：创建页面结构

创建页面 Frame (390x844 for iPhone)
设置背景色 #FAFAFA
使用垂直布局 layout: "vertical"

第三步：使用组件构建 UI

通过 ref 引用可复用组件
使用 U() 覆盖特定属性
保持设计一致性

第四步：验证设计

使用 mcp_pencil_get_screenshot 截图检查
验证对齐、间距、颜色
检查字体和图标一致性

第五步：迭代优化

根据反馈调整细节
确保无视觉错误
输出最终设计稿

批量更新样式

使用 mcp_pencil_replace_all_matching_properties 批量替换属性：

mcp_pencil_replace_all_matching_properties({
  filePath: "design.pen",
  parents: ["pageId1", "pageId2"],
  properties: {
    "fillColor": {"#FFF9F2": "#FAFAFA"},
    "fontFamily": {"Fredoka": "Inter"},
    "cornerRadius": {24: 12}
  }
})

质量检查清单

[ ] 所有页面背景统一 (#FAFAFA)
[ ] 所有卡片有边框 (1px #E4E4E7)
[ ] 阴影效果一致 (blur 2-6px)
[ ] 按钮圆角统一 (8px)
[ ] 字体统一 (Inter)
[ ] 图标库统一 (Lucide)
[ ] 字体层级正确 (12/14/16/18/20/24px)
[ ] 间距遵循 4px 网格