【入門編】PenpotとGraphQL APIの活用：デザインデータからカスタムレポートを自動生成する開発者向けレシピ – UI/UX・デザインツール活用バイブル

こんにちは！デザインシステムとエンジニアリングの境界線を溶かすような開発、ワクワクしますよね。

普段、私たちはFigmaやPenpotといったデザインツールを使ってUIを作っていますが、「今、チーム全体でいくつのコンポーネントが使われているんだろう？」「デザインの進捗率を、JiraやGitHubのタスクみたいに自動で可視化できないかな？」と思ったことはありませんか？

デザインデータを「ただの絵」として扱う時代はもう終わりです。オープンソースのデザインツール「Penpot」の強力な武器であるGraphQL APIを使えば、デザインの構造そのものをコードとして抽出し、自分たちの思い通りのカスタムレポートやダッシュボードを自動生成できるようになります。

今回は、PenpotのGraphQL APIを叩いてデザインメトリクス（コンポーネントの使用数やページの進捗）を自動集計し、社内ダッシュボードに出力するまでのレシピを、優しく丁寧に紐解いていきます。これをマスターすれば、デザイナーとエンジニアの連携が劇的にスムーズになりますよ。一緒に手を動かしていきましょう！

—

1. PenpotのバックエンドAPI（GraphQL）のエンドポイント構造を解析する

まずは、Penpotが持つAPIの心臓部を覗いてみましょう。
Penpotはモダンなアーキテクチャで作られており、フロントエンドとバックエンドの通信にはGraphQLが採用されています。つまり、公式のWebUIでできることは、基本的にAPI経由ですべてプログラムから操作・取得できるということです。

エンドポイントの確認

自前でホストしているPenpot（セルフホスト環境）であれ、公式クラウドであれ、GraphQLのエンドポイントは基本的に以下の構造になっています。

https:///api/graphql

なぜRESTではなくGraphQLなのか？

従来のREST APIだと、「プロジェクト情報を取って、次に各ページの情報を取って、さらにその中のコンポーネントを……」と何回もリクエストを投げる必要があり（N+1問題の地獄）、ネットワークが無駄に重くなります。
しかしGraphQLなら、「このプロジェクトの中にある、全ページの名前と、配置されているコンポーネントのインスタンス数をまとめてくれ！」という複雑な要求を、たった1回のリクエスト（Query）で正確に取得できます。これが最高に気持ちいいポイントです。

—

2. チーム内のデザイン進捗や使用コンポーネント数を自動集計するスクリプトの実装

それでは、実際にNode.js（またはお好みの言語）を使って、PenpotのAPIからデータを引っこ抜き、コンポーネント数を集計するスクリプトを書いてみましょう。

今回は、最も基本となる「Hello World!」的なステップとして、API認証を行い、指定したプロジェクトのデザインファイルから情報を取得するスクリプトを作成します。

事前準備：アクセストークンの取得

PenpotのAPIを叩くには認証が必要です。Penpotのユーザー設定画面（あるいはアカウント設定）から、APIアクセストークン（またはCookieベースのセッション）を発行しておいてください。

集計スクリプトの実装 (`penpot-metrics.js`)

/

  • Penpot デザインメトリクス自動集計スクリプト
  • 役割: PenpotのGraphQL APIにアクセスし、指定したファイルの
  • コンポーネント使用数やページ数を集計してコンソールに出力します。

/

const fetch = require(‘node-fetch’); // または標準のfetch (Node.js 18+)

// 1. 環境設定
const PENPOT_API_URL = process.env.PENPOT_API_URL || ‘https://design.penpot.app/api/graphql’;
const API_TOKEN = process.env.PENPOT_API_TOKEN; // 発行したアクセストークン
const FILE_ID = process.env.PENPOT_FILE_ID; // 対象のデザインファイルID

async function fetchPenpotData() {
// 2. 取得したいデータを定義するGraphQLクエリ
// ここがGraphQLの真骨頂。欲しいデータ構造をそのまま記述します。
const query = `
query GetFileDetails($fileId: ID!) {
file(id: $fileId) {
id
name
pages {
id
name
# ページ内にあるボードや要素の構造を取得
boards {
id
name
}
}
}
}
`;

const variables = { fileId: FILE_ID };

try {
console.log(‘🚀 Penpot APIへリクエストを送信中…’);

const response = await fetch(PENPOT_API_URL, {
method: ‘POST’,
headers: {
‘Content-Type’: ‘application/json’,
‘Authorization’: `Bearer ${API_TOKEN}` // 認証ヘッダー
},
body: JSON.stringify({ query, variables })
});

const result = await response.json();

if (result.errors) {
console.error(‘❌ GraphQLのエラーが発生しました:’, result.errors);
return;
}

// 3. データの集計処理
const fileData = result.data.file;
const pageCount = fileData.pages.length;

let totalBoards = 0;
fileData.pages.forEach(page => {
totalBoards += page.boards.length;
});

// 4. 結果の出力（HelloWorld的な動作確認）
console.log(‘\n📊 — Penpot デザインメトリクスレポート —‘);
printMetric(‘ファイル名’, fileData.name);
printMetric(‘ページ総数’, pageCount);
printMetric(‘フレーム（ボード）総数’, totalBoards);
console.log(‘——————————————–\n’);
console.log(‘✨ おめでとうございます！デザインデータの抽出に成功しました。’);

} catch (error) {
console.error(‘⚠️ 通信エラーが発生しました:’, error);
}
}

// 綺麗に見せるためのヘルパー関数
function printMetric(label, value) {
console.log(` – ${label.padEnd(25, ‘ ‘)}: ${value}`);
}

// 実行
fetchPenpotData();

このスクリプトを動かすことで、「デザインデータがただの視覚情報ではなく、プログラムで集計可能な『生きたデータ』である」ということを強烈に実感できるはずです。

—

3. 社内ダッシュボードへデザインメトリクスをリアルタイム出力する方法

さて、データを取得できるようになったら、次はそれを「チームの資産」に昇華させましょう。この集計スクリプトをCron（定期実行）やGitHub ActionsなどのCI/CDパイプラインに組み込み、社内ダッシュボード（Grafana, Datadog, あるいは社内製のSlack通知botなど）へリアルタイムに出力します。

応用アーキテクチャのイメージ

1. 自動化（Cron / GitHub Actions）

  • 毎日朝9時に、先ほどのスクリプトが自動で走るように設定します。

2. メトリクスの送信（Webhook）

  • スクリプト内で集計した数値を、SlackのIncoming Webhookや、社内ダッシュボードのAPIへJSON形式でPOSTします。

3. チームへの還元

  • 「今週はデザインファイル内でコンポーネントが〇〇個増えました」「未着手のページが〇個あります」といったレポートが、自動的にSlackの `#design-system` チャンネルに飛ぶようになります。

// Slackへレポートを飛ばす処理のイメージ
async function sendToSlack(metrics) {
const webhookUrl = process.env.SLACK_WEBHOOK_URL;
const message = {
text: `🎨 本日のPenpotデザイン進捗レポート\n- ページ数: ${metrics.pages}\n- ボード数: ${metrics.boards}`
};

await fetch(webhookUrl, {
method: ‘POST’,
body: JSON.stringify(message),
headers: { ‘Content-Type’: ‘application/json’ }
});
}

このアプローチがもたらす開発者とデザイナーの未来

デザインツールの中身をAPIで監視できるようになると、デザインの「負債（デット）」をコードと同じように検知できるようになります。
例えば、「同じような見た目なのにコンポーネント化されていない要素が急増している」「命名規則が守られていないページがある」といった異常値いち早く察知し、デザインシステムの崩壊を未然に防ぐことができるのです。

—

まとめ

今回は、PenpotのGraphQL APIを入り口にして、デザインデータをプログラムからハックし、カスタムレポートの土台を作る方法をご紹介しました。

  • Penpotは強力なGraphQL APIを持っており、デザイン構造を1回のリクエストで取得できる。
  • Node.jsなどを使って、ページ数やコンポーネント数をプログラムで自動集計できる。
  • それを定期実行し、Slackや社内ダッシュボードに流すことで、デザインのメトリクス化が実現できる。

「デザインはデザイナーのもの、コードはエンジニアのもの」という壁を取り払い、データを軸にシームレスに連携できるチームは、これからの時代に圧倒的なスピードを生み出します。

これをマスターすれば、毎日のチーム開発やデザイン管理のストレスが劇的に楽になりますよ。ぜひあなたのプロジェクトでも試してみてくださいね！

スポンサーリンク
タイトルとURLをコピーしました