pencil-ui-design

name	pencil-ui-design
description	使用 Pencil MCP 创建工业级 UI 设计的完整工作流和组件库

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"

图片使用注意事项

1. 没有 image 节点类型 - 图片只能作为 frame/rectangle 的填充
2. 先创建容器 - 必须先用 I() 创建 frame，再用 G() 应用图片
3. 设置正确尺寸 - frame 的 width/height 决定显示尺寸
4. 圆角裁剪 - 设置 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"
})

---

设计工作流

第一步：设置设计系统

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

第二步：创建页面结构

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

第三步：使用组件构建 UI

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

第四步：验证设计

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

第五步：迭代优化

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

---

批量更新样式

使用 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 网格