Penpot 可以畫 hi-fi 嗎？本地架設、MCP 串 Claude/Codex 與 UI 落地流程

相信大家在開展一個新專案的 UI 設計時，通常第一個想到的就是 Figma。但如果團隊有敏感資料不能上雲、或是想要百分之百掌握自託管（Self-host）主導權，這時候開源界的 Figma——Penpot，就會出現在你的架構評估名單中。然而，很多人對開源設計工具的第一印象，還停留在「只能拿來畫 Wireframe 的 Pencil」，甚至懷疑它到底能不能勝任高保真（Hi-Fi）設計圖與 UI 落地。

如果你平常只拿 Pencil 這類工具畫草圖，Penpot 會顯得重一點。可是一旦需求往 hi-fi、design system、團隊協作、self-host、設計交付走，Penpot 的位置就很清楚。

Penpot 專案官網：GitHub 倉庫 | 官方 MCP 整合文件

高保真（Hi-Fi）實力：為什麼 Penpot 能勝任複雜設計？

Figma 之所以強大，在於它的 Auto Layout、Component System 與 Tokens。而開源的 Penpot 其實在這幾點上踩得非常硬：

Browser-first：打開瀏覽器就能直接設計，不需要安裝任何厚重的 Electron 桌面應用程式。
Auto Layout（基於 CSS Grid/Flexbox）：這點甚至比 Figma 還要貼近前端工程，設計師排出來的版面，在結構上與 CSS 規格完全一致，前端開發者在 Inspect 時能少掉很多轉譯的痛苦。
Design Tokens 與變體（Variants）：支持全域的顏色、字級與間距變數，方便在頁面變多時進行一鍵維護與覆用。
Inspect Mode：可以直接將選取元件轉譯為 clean 的 SVG、CSS 與 HTML 供工程師複製。

環境布署：快速體驗雲端 vs. Docker 本地自架

如果你只是想先看看 Penpot 的 UI 介面與操作手感，官方有提供免費的雲端服務：

官方託管版本：直接瀏覽 design.penpot.app 註冊即可開始。

然而，對於需要結合 AI Agent 做 automation、或者注重數據安全的專案，官方提供了極為完善的自架方案：

官方支持 Docker Compose、Kubernetes (Helm Chart)、Elestio 與 TrueNAS 部署。

對於本地開發者，Docker Compose 是最快且排錯最容易的起點。你只需要去官網抓他們的 docker-compose.yaml 到本地，並下 docker compose up -d 即可拉起整套 Penpot 服務。

自架架設與 AI 串接重點

在部署完成後，如果你希望引入像 Claude Code 這類的 AI 助理幫你進行設計稿分析或自動化生成，你需要完成以下 Pipeline 的對接：

確保本地的 Penpot Container 正常運行。
建立設計專案並產生一組 MCP User Token。
啟動 Penpot 的 MCP Server，將設計檔資料轉換為 AI 可讀的 Tool 格式。

實戰 MCP：串接 Claude Code 與 OpenCode 助理

Penpot 原生提供了 MCP (Model Context Protocol) 支援，可以讓 AI 直接讀取、分析甚至寫入你的設計檔。這在處理設計代碼化（Design-to-code）或風格同步時非常強大。

MCP Server 支援 Remote（遠端託管）與 Local（本機自架）兩種連線方式。

Remote MCP 的 JSON 設定檔：

{
  "mcpServers": {
    "penpot": {
      "url": "https://<your-penpot-domain>/mcp/stream?userToken=YOUR_MCP_KEY",
      "type": "http"
    }
  }
}

這是 MCP 客戶端的 JSON 設定檔片段，用於註冊 Penpot 的 Remote MCP 服務。填入你自架的 Penpot 網域與專屬 Token 後，外部的 AI 助理（如 Claude Code）就能透過 HTTP 協議與設計檔建立安全連線。

Local MCP 的 JSON 設定檔：

{
  "mcpServers": {
    "penpot": {
      "transport": {
        "type": "http"
      },
      "url": "http://localhost:4401/mcp"
    }
  }
}

這段 JSON 設定則是針對 Local MCP 模式，指定 AI 客戶端連向本地運行的 4401 port。這適合在本機端跑自動化腳本或需要極低延遲的設計檔重構場景。

如何在本地啟動 Local MCP Server？

如果你要在本地環境做 debug，你需要在終端機執行：

npx @penpot/mcp@stable

這行指令會透過 npm 直接下載並在本地啟動 Penpot 的 MCP 伺服器。啟動後它會在背景傾聽 API 請求，扮演橋接 Penpot 瀏覽器插件與 AI 助理之間的溝通橋樑。

啟動後，依序完成以下步驟：

不要關閉執行 npx 的 Terminal 視窗。
開啟你的 Penpot 專案頁面，從 Plugins -> Load from URL 載入 http://localhost:4400/manifest.json。
在 Plugin 的 UI 上點擊 Connect to MCP server 進行授權。
這時你的 Claude Code 便可透過本地的 http://localhost:4401/mcp 對設計檔進行修改。

AI 輔助設計：如何用 MCP 讓 Agent 產出 UI 稿？

當 Agent 成功連接上 Penpot 後，不要劈頭就叫它畫一個完整的 App 首頁，否則你只會得到一堆重疊的亂糟糟圖層。實務上我會採用以下小步快跑（Iterative）的策略：

1. 先讀取分析，不做任何寫入

叫 Agent 先去撈當前設計檔的 Tokens 命名、元件結構與頁面清單。

對話範例：「請分析我目前這個設計檔，列出所有的 color tokens 與 spacing scales，先不要修改任何內容。」

2. 給予參考元件，小範圍生成

在設計系統內，指定它用現有的 Button 與 Card 組裝出一個特定的 Card Variant，以此確認 Agent 對 CSS Grid 的掌握度。

對話範例：「請套用目前的 Design System 變數，在 Dashboard 頁面中新增一個帶有 hover 狀態的 Card 元件。」

交付與落地：從 Penpot 設計稿到前端代碼實作

設計稿畫得再好看，如果工程師接不上手也是徒勞。在從 Penpot 交付到前端開發時，建議遵循這套 Pipeline：

優先導出 Design Tokens：將 Penpot 中的色碼、字級、陰影，直接輸出成 CSS 變數（CSS Variables）或 Tailwind 的 Theme Config。
對應 Component Name：設計檔中的 Layer 結構與 Group 命名，必須與前端元件（如 <Button />、<Sidebar />）的架構對齊。
利用 Inspect Mode 避坑：Penpot 導出的 CSS Grid 程式碼相當乾淨，在排 Layout 時可以作為直接的實作參考，但阻礙的是還是要由人腦進行過濾與重構，避免直接照抄產生冗餘的 absolute positioning。

開源設計工具選型：Penpot vs. Pencil

這兩套雖然都是開源軟體，但選型邏輯完全不同：

Pencil 是一款輕量化、免安裝的桌面草圖工具，專門用來在會議中快速拉 wireframe 或畫流程圖（Flowchart）。
Penpot 則是團隊協作平台，它有完整的組件庫、Auto Layout 引擎、實體交付檢視，甚至有完整的 MCP 自動化整合，適合做高保真的 UI 實作。

結論與取捨

Figma 目前在生態系與社群資源上依舊處於領先，這是不可否認的事實；但 Penpot 作為開源的替代方案，其原生對網頁標準（Web Standards）的適配度極高，且能在私有雲中完全託管。

如果你要的是快速把想法畫出來，Pencil 夠用。它輕，打開就能畫，適合早期討論。但如果你在處理 Design System 落地、敏感資料去雲端化、或是想要讓 AI Agent 可以直接用程式碼插拔設計稿，那自架 Penpot 才是目前唯一的正解。