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 を実行)
ブラウザがローカルホストをブロック	ローカルネットワークアクセスプロンプトを許可するか、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 は READ-ONLY → shape.resize(w, h) を使用
• parentX/parentY は READ-ONLY → penpotUtils.setParentXY(shape, x, y) を使用
• z オーダーには insertChild(index, shape) を使用 (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	ページレベルの間隔

タイポグラフィスケール

レベル	サイズ	ウェイト	用途
Display	48-64px	Bold	ヒーロー見出し
H1	32-40px	Bold	ページタイトル
H2	24-28px	Semibold	セクションヘッダー
H3	20-22px	Semibold	サブセクション
Body	16px	Regular	メインコンテンツ
Small	14px	Regular	セカンダリテキスト
Caption	12px	Regular	ラベル、ヒント

色の使用

目的	推奨
Primary	メインブランドカラー、CTA
Secondary	サポート操作
Success	#22C55E 範囲 (確認)
Warning	#F59E0B 範囲 (注意)
Error	#EF4444 範囲 (エラー)
Neutral	テキスト/ボーダーのグレースケール

一般的なレイアウト

モバイル画面 (375×812)

┌─────────────────────────────┐
│ ステータスバー (44px)           │
├─────────────────────────────┤
│ ヘッダー/ナビ (56px)           │
├─────────────────────────────┤
│                             │
│ コンテンツエリア                │
│ (スクロール可能)                 │
│ パディング: 水平方向 16px    │
│                             │
├─────────────────────────────┤
│ ボトムナビ/CTA (84px)       │
└─────────────────────────────┘

デスクトップダッシュボード (1440×900)

┌──────┬──────────────────────────────────┐
│      │ ヘッダー (64px)                    │
│ サイド │──────────────────────────────────│
│ バー  │ ページタイトル + アクション             │
│      │──────────────────────────────────│
│ 240  │ コンテンツグリッド                     │
│ px   │ ┌─────┐ ┌─────┐ ┌─────┐ ┌─────┐ │
│      │ │カード │ │カード │ │カード │ │カード │ │
│      │ └─────┘ └─────┘ └─────┘ └─────┘ │
│      │                                  │
└──────┴──────────────────────────────────┘

コンポーネントチェックリスト

ボタン

• 明確で、アクション指向のラベル (2-3 語)
• 最小タッチターゲット: 44×44px
• ビジュアル状態: デフォルト、ホバー、アクティブ、無効、読み込み中
• 十分なコントラスト (背景に対して 3:1)
• アプリ全体で一貫した角の丸さ

フォーム

• ラベルは入力の上 (プレースホルダーだけではない)
• 必須フィールド指標
• フィールドに隣接するエラーメッセージ
• 論理的なタブ順序
• 入力タイプはコンテンツに一致 (メール、電話など)

ナビゲーション

• 現在地が明確に示されている
• スクリーン全体で一貫した位置
• 最大 7±2 のトップレベルアイテム
• モバイルでタッチしやすい (48px ターゲット)

アクセシビリティのクイックチェック

1. 色コントラスト: テキスト 4.5:1、大きなテキスト 3:1
2. タッチターゲット: 最小 44×44px
3. フォーカス状態: 目に見えるキーボードフォーカスインジケーター
4. Alt テキスト: 画像の意味のある説明
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. フィードバックを提供: すべてのアクションには応答が必要