【実務・中級編】FigmaのスクリプトとREST API連携で実現するデザインアセットの自動バックアップとメトリクス計測 – UI/UX・デザインツール活用バイブル

Figmaを「デザインの黒箱」から解放せよ：REST APIとCI/CDで構築するデザインアセット自動バックアップ＆メトリクス計測基盤

デザインシステムが巨大化するにつれ、プロダクト開発の現場ではひとつの共通の課題に直面する。
「誰が、どのコンポーネントを、どれだけ使っているのか？」「過去の破壊的変更の履歴を、正確にどう追跡するか？」

FigmaはUI/UXデザインのデファクトスタンダードだが、その実態はブラウザ上のブラックボックスになりがちだ。デザインデータが個人のローカルキャッシュや単一のクラウドに依存している状態では、真のエンジニアリングとは言えない。コードであればGitで管理され、CI/CDでメトリクスが計測されるものが、デザイン領域では「お祈り運ｍ」で行われている。

この記事では、Figma REST APIとTypeScript、そしてGitHub Actionsを巧みに組み込み、デザインファイルの自動バックアップとコンポーネント使用率のメトリクス計測を完全自動化するパイプラインの構築手法を、テックリードの視点から余すところなく解説する。

—

1. 現場の生産性を極限まで高める：Figmaショートカットと神プラグイン

自動化パイプラインの話に入る前に、日々のデザイン・エンジニアリングの境界線を溶かす「プロの道具使い」を確認しておこう。手数を減らすことこそが、自動化の土台となる。

開発スピードを劇的に高める隠れたキーボードショートカット

  • `Shift` + `1`: ドキュメント全体を俯瞰（ファーストビュー最適化）
  • `Shift` + `2`: 選択したレイアウトフレームにズーム（コンポーネント検証の基本）
  • `⌥` (Option) + Drag: レイヤーのインスタンスを爆速で複製しつつ、自動レイアウトの数値を視覚的に確認
  • `⌘` + `Shift` + `L`: アウトラインモードの切り替え（ベクターパスの歪みを一瞬で検知）

絶対に入れるべき神プラグイン（エンジニア視点）

1. Tokens Studio for Figma (旧Figma Tokens): デザインとコードの単一情報源（SSOT）を維持するためのマストツール。JSONとしてトークンを書き出し、GitHub経由でリポジトリに同期させる。
2. Dev Mode Inspector: 開発者モードを拡張し、生成されるCSS/Tailwind/Swiftのコード品質を担保する。
3. Component Patrol: 未承認のコンポーネントや、デタッチされたままの危険なインスタンスをスキャンし、チームのガバナンスを保つ。

—

2. アーキテクチャ概要：デザインを「コード」と同等に扱う

今回のアーキテクチャの全体像はこうだ。

[Figma Cloud]
│
▼ (Webhook / Cron)
[GitHub Actions (CI/CD)]
│
├─► 1. Figma REST API経由でJSONツリー構造を取得 ──► [GitHub Repository (JSON Backup)]
│
└─► 2. コンポーネント使用率をパース・集計 ────────► [Metrics Dashboard / Slack Notification]

デザインファイルを定期的にJSONとしてリポジトリにスナップショット保存することで、「デザインのGit diff（差分管理）」が可能になる。

—

3. 実装：Figma REST APIをたたくTypeScriptスクリプト

まずは、Figma APIからファイル構造を取得し、主要なコンポーネントの利用状況（インスタンスの数）を算出するNode.jsスクリプトを実装する。

必要なパッケージのインストール：

npm install axios dotenv
npm install -D typescript @types/node ts-node

設定ファイル・スクリプト：`scripts/figma-metrics.ts`

import axios from ‘axios’;
import as fs from ‘fs’;
import as path from ‘path’;
import dotenv from ‘dotenv’;

dotenv.config();

const FIGMA_ACCESS_TOKEN = process.env.FIGMA_ACCESS_TOKEN;
const FIGMA_FILE_KEY = process.env.FIGMA_FILE_KEY;

if (!FIGMA_ACCESS_TOKEN || !FIGMA_FILE_KEY) {
console.error(‘Error: FIGMA_ACCESS_TOKEN and FIGMA_FILE_KEY must be set.’);
process.exit(1);
}

const figmaApi = axios.create({
baseURL: ‘https://api.figma.com/v1’,
headers: {
‘X-Figma-Token’: FIGMA_ACCESS_TOKEN,
},
});

interface ComponentMetric {
name: string;
key: string;
usageCount: number;
}

// 再帰的にノードを走査し、インスタンス（コンポーネントの使用）をカウントする
function traverseNode(node: any, componentMap: Map) {
if (!node) return;

// タイプの判定: INSTANCE はコンポーネントが配置されている状態を指す
if (node.type === ‘INSTANCE’) {
const componentKey = node.componentKey;
const existing = componentMap.get(componentKey);
if (existing) {
existing.count += 1;
} else {
componentMap.set(componentKey, { name: node.name, count: 1 });
}
}

// 子ノードが存在する場合は再帰的に走査
if (node.children && Array.isArray(node.children)) {
for (const child of node.children) {
traverseNode(child, componentMap);
}
}
}

async function main() {
try {
console.log(‘Fetching Figma file data…’);
const response = await figmaApi.get(`/files/${FIGMA_FILE_KEY}`);
const fileData = response.data;

// 1. バックアップとして生のJSONツリーを保存
const backupDir = path.resolve(__dirname, ‘../backups’);
if (!fs.existsSync(backupDir)) {
fs.mkdirSync(backupDir, { recursive: true });
}
const timestamp = new Date().toISOString().replace(/:/g, ‘-‘);
const backupPath = path.join(backupDir, `figma-backup-${timestamp}.json`);

// データ量削減のためメタデータや必要な部分に絞ることも可能だが、今回はフルバックアップ
fs.writeFileSync(backupPath, JSON.stringify(fileData, null, 2));
console.log(`[Success] Backup saved to ${backupPath}`);

// 2. コンポーネント使用率のメトリクス集計
const componentMap = new Map();
traverseNode(fileData.document, componentMap);

const metrics: ComponentMetric[] = Array.from(componentMap.entries()).map(([key, value]) => ({
key,
name: value.name,
usageCount: value.count,
}));

// 使用頻度順にソート
metrics.sort((a, b) => b.usageCount – a.usageCount);

const metricsPath = path.resolve(__dirname, ‘../backups/latest-metrics.json’);
fs.writeFileSync(metricsPath, JSON.stringify(metrics, null, 2));
console.log(`[Success] Metrics calculated and saved to ${metricsPath}`);

// TODO: ここでDatadogやSlack Webhookへメトリクスを送信する処理を追加可能

} catch (error: any) {
console.error(‘Failed to fetch Figma data:’, error.response?.data || error.message);
process.exit(1);
}
}

main();

—

4. GitHub ActionsによるCI/CDパイプラインの構築

手動でスクリプトを叩くようではエンジニアの名が廃る。GitHub Actionsを使い、毎日深夜、あるいはデザインシステムリポジトリへのプッシュをトリガーにして自動実行させよう。

設定ファイル：`.github/workflows/figma-backup-metrics.yml`

name: Figma Backup & Metrics Sync

on:
# 毎日深夜0時(UTC)に自動実行
schedule:

  • cron: ‘0 0 ‘

# 手動トリガー（workflow_dispatch）を有効化
workflow_dispatch:

jobs:
sync-figma:
runs-on: ubuntu-latest

steps:

  • name: Checkout Repository

uses: actions/checkout@v4

  • name: Set up Node.js

uses: actions/setup-node@v4
with:
node-version: ’20’
cache: ‘npm’

  • name: Install Dependencies

run: npm ci

  • name: Run Figma Backup & Metrics Script

env:
FIGMA_ACCESS_TOKEN: ${{ secrets.FIGMA_ACCESS_TOKEN }}
FIGMA_FILE_KEY: ${{ secrets.FIGMA_FILE_KEY }}
run: npx ts-node scripts/figma-metrics.ts

  • name: Commit and Push Changes if Backup/Metrics Updated

uses: stefanzweifel/git-auto-commit-action@v5
with:
commit_message: ‘chore(figma): automated backup and component metrics update [skip ci]’
branch: main
commit_user_name: ‘Figma Automation Bot’
commit_user_email: ‘bot@users.noreply.github.com’

> 💡 テックリードの知見:
> `git-auto-commit-action` を使うことで、生成されたJSONの変更を自動でGitにコミット＆プッシュできる。これにより、デザインファイルの「いつ、どのコンポーネントが大量に破棄されたか／採用されたか」のタイムラインがGitの履歴として完全に残るようになる。

—

5. チーム開発で役立つ設定の共有化ルール

自動化スクリプトやCI/CDをチームに導入するにあたり、以下のガバナンスルールを必ず策定してほしい。

1. Personal Access Token (PAT) の管理:
Figmaのアクセストークンは個人のアカウントではなく、チーム用のBotアカウント（または組織の管理者アカウント）を発行してGitHub Secretsに登録すること。個人に依存させると退職時にパイプラインが沈黙する。
2. デザインシステムの「キー（Component Key）」の固定:
コンポーネント名を変更しても、Figma内部の `componentKey` は変わらない。メトリクス計測はこのキーをベースに行うため、デザイナーがコンポーネントを「切断（Detach）」して新しく作り直す行為（アンチパターン）をチーム内で厳禁とするコードレビューの文化を作る。
3. 差分データの活用:
蓄積された `latest-metrics.json` の変化を毎週の定例ミーティングやSlack通知（Incoming Webhook）でチームに流す。「今週、最も使われたコンポーネント」「誰も使っていないゾンビコンポーネント」を可視化することで、デザインシステムの負債を早期に解消できる。

—

結び：デザインとコードの境界線をなくす

FigmaのREST APIとCI/CDを接続した瞬間から、デザインファイルは「ただの絵」から「バージョン管理されたシステムのアセット」へと生まれ変わる。

デザインシステムの運用に銀の弾丸はない。しかし、こうしたエンジニアリングの力による「観測と自動化」の仕組みこそが、デザイナーとエンジニアの共通言語を作り、プロダクトのスケールを支える最強の防壁となるのだ。

さあ、今すぐ `FIGMA_ACCESS_TOKEN` を発行し、あなたのチームのデザインをコードの領域へと引き上げよう。

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