デザインとコードの「乖離」を撲滅せよ：Penpot × GitHub Actions で実現する真のCI/CD自動化
デザインツールが「絵を描く場所」だと思っているなら、今すぐその認識を捨てろ。デザインは、プロダクトのソースコードそのものだ。
Penpotを採用する最大の強みは、そのオープンなアーキテクチャにある。SVGベースのファイルフォーマット、そしてREST API。これらを活用せず、手動で「デザインの変更を確認しました」とSlackに投稿しているようなチームは、すでに開発プロセスの敗北者だ。
本稿では、デザインの変更をトリガーに、GitHub Actionsを駆動させ、差分を自動検出し、プロダクトの健全性を担保する「デザイン・オブ・コード（Design as Code）」の極致を解説する。
—
1. アーキテクチャの設計思想：Webhookはただの「信号」ではない
PenpotのWebhookは、単なる通知機能ではない。これはデザインシステムにおける「イベント・ソーシング」の起点だ。
今回の設計は以下の通り。
1. Penpot Webhook: デザイン変更を検知し、GitHub APIを叩く。
2. GitHub Actions: 受け取ったイベントを解析し、独自のCLIツールを起動。
3. Design Diff Engine: Penpot API経由で現在のSVGデータを抽出し、レポジトリ内のトークンデータや前回のスナップショットと比較する。
—
2. 構築：Penpot Webhook と GitHub Actions の接続
PenpotからWebhookを飛ばす際、セキュリティは妥協してはならない。GitHub `repository_dispatch` イベントを活用し、ペイロードを検証する。
Penpot Webhookの設定
Penpotのプロジェクト設定からWebhookを追加する。
- URL: `https://api.github.com/repos/{owner}/{repo}/dispatches`
- Headers: `Authorization: token ${{ SECRETS.GITHUB_TOKEN }}`
- Content-Type: `application/json`
GitHub Actions: `design-sync.yml`
まずは、Webhookを受け取り、パイプラインを起動させる最小構成だ。
name: Design Sync Pipeline
on:
repository_dispatch:
types: [penpot-update]
jobs:
sync:
runs-on: ubuntu-latest
steps:
- uses: actions/checkout@v4
- name: Setup Node.js
uses: actions/setup-node@v4
with:
node-version: ’20’
- name: Trigger Design Diff Process
run: |
# 独自CLIを呼び出し、Penpot APIから最新データをフェッチ
npx @my-org/design-cli sync –project-id ${{ github.event.client_payload.project_id }}
env:
PENPOT_API_TOKEN: ${{ secrets.PENPOT_API_TOKEN }}
—
3. 真のキモ：デザイン差分自動検出エンジン
ここからが本題だ。単に「更新されました」と通知するだけでは足りない。「何が変わったのか」をコードレベルで特定する必要がある。
PenpotのAPIはSVG構造を返す。これをそのまま比較しても無駄な差分が大量に出る。我々がやるべきは、「トークンレベルの正規化」だ。
独自CLIのロジック（概念コード）
// design-cli/sync.js
async function detectDesignDrift(penpotData) {
// 1. Penpotから取得したSVG/JSONデータを正規化
const normalized = normalizeDesignTokens(penpotData);
// 2. 現在のレポジトリ内のトークンJSONとの差分を計算
const diff = deepDiff(currentTokens, normalized);
if (diff.length > 0) {
// 3. 変更があればGitHub Issueとして自動チケット作成
await createIssue(‘デザイン差分を検出しました’, diff);
// 4. もしくは、CIをFAILさせて破壊的変更をブロックする
process.exit(1);
}
}
—
4. 上級者向けハック：パフォーマンスと最適化
数千のレイヤーを持つ巨大なプロジェクトを扱う場合、APIレスポンスのメモリ消費は無視できない。以下の最適化を必ず実装せよ。
- バイナリ解析（Protocol Buffersの利用）: JSONのパースは重い。もし可能なら、PenpotのExport機能でSVGをストリーム処理し、必要なノード（例えば`data-token-name`属性を持つものだけ）をSAXパーサーで抽出する。これにより、メモリ使用量を1/10以下に抑えられる。
- 差分ビルド: Penpotの「ページ」や「コンポーネント」単位でAPIを叩き、更新されたJSONのみをキャッシュする。GitHub Actionsの `actions/cache` を活用し、前回のスナップショットを再利用せよ。
- GitHub APIのレートリミット対策: 大規模な変更が発生した際、立て続けにWebhookが飛ぶとAPI制限に引っかかる。キューイングシステム（Redis等）を挟むか、GitHub Actionsの `concurrency` グループを設定して順序を制御すること。
—
結びに代えて：デザインは「語る」な、「実行」せよ
デザイナーが「ここを修正した」と口頭で伝え、エンジニアがそれを「解釈」してコードに落とし込む。この非効率な伝言ゲームは、今すぐ終了させるべきだ。
PenpotとGitHubを接続し、デザインの変更が直接ビルドパイプラインを揺さぶる。CIが「色のコントラストが不十分です」と警告を出し、デザインシステムが自動的に更新される。これこそが、現代のプロダクト開発における唯一の正解だ。
君たちが今日書くこのパイプラインが、数ヶ月後のエンジニアの苦悩をどれだけ救うか。コードに魂を込めよ。自動化は、愛である。