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 伺服器是否已可用：

先嘗試呼叫工具：執行 mcp__penpot__penpot_api_info——如果成功，表示伺服器正在執行且已連線。無需設定。
如果工具失敗，請詢問使用者：

「Penpot MCP 伺服器似乎未連線。伺服器是否已安裝並執行中？如果是，我可以協助疑難排解。如果沒有，我可以引導您完成設定。」
僅在使用者確認伺服器未安裝時，才繼續提供設定說明。

快速開始（僅限未安裝時）

# 複製並安裝
git clone https://github.com/penpot/penpot-mcp.git
cd penpot-mcp
npm install

# 建置並啟動伺服器
npm run bootstrap

然後在 Penpot 中：

開啟一個設計檔案
前往 外掛程式 → 從 URL 載入外掛程式
輸入：http://localhost:4400/manifest.json
在外掛程式 UI 中點選 「連線到 MCP 伺服器」

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 已開啟並顯示「已連線」
「WebSocket 連線失敗」	檢查防火牆是否允許連接埠 4400、4401、4402

快速參考

任務	參考檔案
MCP 伺服器安裝與疑難排解	setup-troubleshooting.md
元件規格（按鈕、表單、導覽）	component-patterns.md
無障礙（對比、觸控目標）	accessibility.md
螢幕尺寸與平台規格	platform-guidelines.md

核心設計原則

黃金法則

清晰勝於花俏：每個元素都必須有目的
一致性建立信任：重複使用模式、顏色和元件
使用者目標優先：為任務而設計，而非功能
無障礙不是選項：為每個人設計
與真實使用者測試：及早驗證假設

視覺層級（優先順序）

大小：越大 = 越重要
顏色/對比：高對比吸引注意力
位置：左上角（LTR）最先被看到
留白：隔離凸顯重要性
字體粗細：粗體更突出

設計工作流程

先檢查設計系統：詢問使用者是否有現有的代碼/規格，或從目前的 Penpot 檔案中探索
了解頁面：使用 mcp__penpot__execute_code 搭配 penpotUtils.shapeStructure() 查看層級結構
尋找元素：使用 penpotUtils.findShapes() 依類型或名稱定位元素
建立/修改：使用 penpot.createBoard()、penpot.createRectangle()、penpot.createText() 等
套用版面：使用 addFlexLayout() 建立響應式容器
驗證：呼叫 mcp__penpot__export_shape 以視覺方式檢查成果

設計系統處理

在建立設計之前，先確認使用者是否有現有的設計系統：

詢問使用者：「您是否有要遵循的設計系統或品牌指南？」
從 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 是唯讀的 → 使用 shape.resize(w, h)
parentX/parentY 是唯讀的 → 使用 penpotUtils.setParentXY(shape, x, y)
使用 insertChild(index, shape) 來控制 z 順序（不要用 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	粗體	主視覺標題
H1	32-40px	粗體	頁面標題
H2	24-28px	半粗體	區段標題
H3	20-22px	半粗體	子區段
Body	16px	一般	主要內容
Small	14px	一般	次要文字
Caption	12px	一般	標籤、提示

顏色用途

用途	建議
主要	主要品牌色、行動呼籲按鈕
次要	輔助操作
成功	#22C55E 範圍（確認）
警告	#F59E0B 範圍（警示）
錯誤	#EF4444 範圍（錯誤）
中性	灰階用於文字/邊框

常見版面

行動螢幕（375×812）

┌─────────────────────────────┐
│ 狀態列（44px）               │
├─────────────────────────────┤
│ 頁首/導覽（56px）            │
├─────────────────────────────┤
│                             │
│ 內容區域                    │
│ （可捲動）                   │
│ 內距：水平 16px             │
│                             │
├─────────────────────────────┤
│ 底部導覽/行動呼籲（84px）    │
└─────────────────────────────┘

桌面儀表板（1440×900）

┌──────┬──────────────────────────────────┐
│      │ 頁首（64px）                      │
│ 側   │──────────────────────────────────│
│ 邊   │ 頁面標題 + 操作                  │
│ 欄   │──────────────────────────────────│
│ 240  │ 內容網格                         │
│ px   │ ┌─────┐ ┌─────┐ ┌─────┐ ┌─────┐ │
│      │ │卡片 │ │卡片 │ │卡片 │ │卡片 │ │
│      │ └─────┘ └─────┘ └─────┘ └─────┘ │
│      │                                  │
└──────┴──────────────────────────────────┘

元件檢查清單

按鈕

[ ] 清晰、行動導向的標籤（2-3 個字）
[ ] 最小觸控目標：44×44px
[ ] 視覺狀態：預設、懸停、啟用、停用、載入中
[ ] 足夠的對比度（與背景 3:1）
[ ] 整個應用程式中圓角半徑一致

表單

[ ] 標籤位於輸入框上方（不只是佔位文字）
[ ] 必填欄位標示
[ ] 錯誤訊息緊鄰欄位
[ ] 邏輯的 Tab 順序
[ ] 輸入類型與內容相符（email、tel 等）

導覽

[ ] 清楚標示目前位置
[ ] 跨畫面位置一致
[ ] 頂層項目最多 7±2 個
[ ] 行動裝置友善（48px 目標）

無障礙快速檢查

顏色對比：文字 4.5:1，大字型 3:1
觸控目標：最小 44×44px
焦點狀態：可見的鍵盤焦點指示器
替代文字：為圖片提供有意義的描述
層級結構：正確的標題層級（H1→H2→H3）
顏色獨立性：絕不單獨依賴顏色

設計審查檢查清單

在最終確定任何設計之前：

[ ] 視覺層級清晰
[ ] 間距和對齊一致
[ ] 字體可讀（主文字 16px 以上）
[ ] 顏色對比符合 WCAG AA
[ ] 互動元素明顯
[ ] 行動裝置友善的觸控目標
[ ] 已考慮載入中/空白/錯誤狀態
[ ] 與設計系統一致

驗證設計

使用以下驗證方法搭配 mcp__penpot__execute_code：

檢查項目	方法
元素超出邊界	使用 `isContainedIn()` 搭配 `penpotUtils.analyzeDescendants()`
文字太小（<12px）	使用 `penpotUtils.findShapes()` 並以 `fontSize` 篩選
缺少對比	呼叫 `mcp__penpot__export_shape` 並目視檢查
層級結構	使用 `penpotUtils.shapeStructure()` 檢視巢狀結構

匯出 CSS

透過 mcp__penpot__execute_code 使用 penpot.generateStyle(selection, { type: 'css', includeChildren: true }) 從設計中提取 CSS。

優秀設計的秘訣

從內容開始：真實內容會揭示版面需求
行動優先設計：限制激發創意
使用網格：8px 基底網格保持對齊
限制顏色：1 主色 + 1 輔助色 + 中性色
限制字型：最多 1-2 種字體
擁抱留白：呼吸空間提升理解力
保持一致：相同動作 = 各處相同外觀
提供回饋：每個動作都需要回應

您可能也喜歡

algorithmic-art

153Kdesign-ui

使用 p5.js 建立演算法藝術，搭配種子亂數與互動式參數探索。當使用者要求使用程式碼創作藝術、生成式藝術、演算法藝術、流場或粒子系統時使用。創作原創的演算法藝術，而非複製現有藝術家的作品，以避免侵犯著作權。

anthropics

獲取

frontend-ui-engineering

77Kdesign-ui

建立生產級品質、無障礙、響應式的使用者介面。在建立或修改介面與頁面、建立元件、實作版面配置、滿足 WCAG 無障礙需求、管理狀態，或當輸出需要看起來像生產級品質而非 AI 生成時使用。

addyosmani

獲取

hyperframes-keyframes

34Kdesign-ui

當 HyperFrames 合成需要可搜尋的 2D/3D 關鍵影格、GSAP 時間軸、CSS 關鍵影格、Anime.js、WAAPI、FLIP、路徑、遮罩、SVG 變形/繪製、文字軌跡、3D 深度或 `hyperframes keyframes` 診斷時使用。請勿用於廣泛場景策略、品牌設計、媒體來源、字幕或一般影片規劃。

heygen-com

獲取

繼續探索

瀏覽 design-ui 熱門 Skills 最近更新