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. ユーザーがサーバーをインストールしていないと確認した場合にのみ、セットアップ手順を進めてください。

クイックスタート（インストールされていない場合のみ）

# Clone and install
git clone https://github.com/penpot/penpot-mcp.git
cd penpot-mcp
npm install

# Build and start servers
npm run bootstrap

次に Penpot で:

1. デザインファイルを開きます
2. Plugins → Load plugin from URL に移動します
3. 入力します: http://localhost:4400/manifest.json
4. プラグイン UI で 「Connect to MCP server」 をクリックします

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 が開いていて「Connected」と表示されていることを確認してください
「WebSocket connection failed」	ファイアウォールがポート 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 から検出する: 既存のコンポーネント、カラー、パターンを確認する

// Discover existing design patterns in current file
const allShapes = penpotUtils.findShapes(() => true, penpot.root);

// Find existing colors in use
const colors = new Set();
allShapes.forEach(s => {
  if (s.fills) s.fills.forEach(f => colors.add(f.fillColor));
});

// Find existing text styles (font sizes, weights)
const textStyles = allShapes
  .filter(s => s.type === 'text')
  .map(s => ({ fontSize: s.fontSize, fontWeight: s.fontWeight }));

// Find existing components
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) を使用する
• z 順序の制御には insertChild(index, shape) を使用する(appendChild ではない)
• dir="column" または dir="row" の場合、Flex の子要素の配列順序は逆になる
• text.resize() の後、growType を "auto-width" または "auto-height" にリセットする

新しいボードの配置

新しいボードを作成する前に、必ず既存のボードを確認してください。重なりを避けるためです:

// Find all existing boards and calculate next position
const boards = penpotUtils.findShapes(s => s.type === 'board', penpot.root);
let nextX = 0;
const gap = 100; // Space between boards

if (boards.length > 0) {
  // Find rightmost board edge
  boards.forEach(b => {
    const rightEdge = b.x + b.width;
    if (rightEdge + gap > nextX) {
      nextX = rightEdge + gap;
    }
  });
}

// Create new board at calculated position
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)

┌─────────────────────────────┐
│ Status Bar (44px)           │
├─────────────────────────────┤
│ Header/Nav (56px)           │
├─────────────────────────────┤
│                             │
│ Content Area                │
│ (Scrollable)                │
│ Padding: 16px horizontal    │
│                             │
├─────────────────────────────┤
│ Bottom Nav/CTA (84px)       │
└─────────────────────────────┘

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

┌──────┬──────────────────────────────────┐
│      │ Header (64px)                    │
│ Side │──────────────────────────────────│
│ bar  │ Page Title + Actions             │
│      │──────────────────────────────────│
│ 240  │ Content Grid                     │
│ px   │ ┌─────┐ ┌─────┐ ┌─────┐ ┌─────┐ │
│      │ │Card │ │Card │ │Card │ │Card │ │
│      │ └─────┘ └─────┘ └─────┘ └─────┘ │
│      │                                  │
└──────┴──────────────────────────────────┘

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

ボタン

• 明確でアクション指向のラベル(2〜3 語)
• 最小タッチターゲット: 44×44px
• 視覚的状態: デフォルト、ホバー、アクティブ、無効、ローディング
• 十分なコントラスト(背景に対して 3:1)
• アプリ全体で一貫したボーダー半径

フォーム

• 入力欄の上にラベルを配置する(プレースホルダーだけにしない)
• 必須フィールドのインジケーター
• フィールドの近くにエラーメッセージを表示する
• 論理的なタブ順序
• 入力タイプがコンテンツに一致する(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)	fontSize でフィルタリングする penpotUtils.findShapes()
コントラストの不足	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. フィードバックを提供する: すべてのアクションには応答が必要です