pencil-ui-design

Pencil MCP の業界標準 UI デザインスキル

このスキルでは、Pencil MCP のデザイン作業に使用する、業界標準の UI デザイン規範を提供します。

クイックスタート

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"})

---

デザインシステムの規範

カラーシステム（カラー・トークン）

変数名	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	フォーカスリング

フォント階層（タイポグラフィスケール）

階層	サイズ	太さ	行の高さ	用途
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（中国語）

間隔システム（スペーシング）

4px グリッドに基づきます：

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

角丸の規範（ボーダー半径）

変数	値	用途
radius-sm	6px	小さな要素（Badge、Chip）
radius-md	8px	ボタン、入力欄
radius-lg	12px	カード、モーダル
radius-xl	16px	大きなカード
radius-full	9999px	円形アバター

影のシステム（シャドウ）

{
  "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 ボタン

プライマリボタン

{
  "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

セカンダリボタン

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

ゴーストボタン

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

破壊的ボタン

{
  "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 では、Lucide ではなく Material Symbols Rounded アイコンフォントを使用します！

基本的な使い方

{
  "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() 操作を使用でき、次の 2 つの方法に対応しています。

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")

ストック画像（実際の写真におすすめ）

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

プロンプト作成のコツ

種類	良いプロンプト	良くないプロンプト
アバター	"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 网格