【実務・中級編】Figmaの「Component Description」とドキュメンテーション駆動デザイン！脱属人化のチーム運用ルール – UI/UX・デザインツール活用バイブル

Figmaの「Component Description」とドキュメンテーション駆動デザイン：属人性を破壊する最強のチーム運用プラクティス

1. なぜあなたのデザインシステムは「腐敗」するのか？

大規模なプロダクト開発において、デザインシステムを構築した直後は誰もが興奮します。「これで UI の共通化が進み、開発速度は2倍になる」と。

しかし、半年後に何が起きているでしょうか？

  • Notion や Confluence の仕様書は更新が止まり、完全に化石化している
  • 「このボタンの Disabled 状態のホバーってどういう挙動？」と、Slack で毎回同じ質問が飛ぶ
  • デザイナーとエンジニアでコンポーネントの Variant 名や Props の解釈がズレ、コード側で独自実装が乱立する

この悲劇の原因は明確です。「デザインツール（Figma）」と「仕様ドキュメント（外部ツール）」が地理的・文脈的に分断されているからです。

どれほど綺麗な UI を描いても、そのコンポーネントが「いつ・どのように使われるべきか」「どんな制約を持つか」という文脈が欠落していれば、それはただの「色のついた四角形」に過ぎません。外部の仕様書リンクを開く数秒の認知コストすら、開発の現場では致命的なオーバーヘッドとなります。

本稿では、Figma の 「Component Description（コンポーネントの説明）」 欄を真の Single Source of Truth（一次情報源）として位置づけ、コードとの完全な同期を実現する「ドキュメンテーション駆動デザイン（DDD: Documentation-Driven Design）」の真髄を解説します。

—

2. Component Descriptionを「仕様書のインライン化」へ昇華させるテクニック

Figma のコンポーネント定義パネルにある「Description」欄。多くのチームがここを「ボタンコンポーネントです」といった無意味な一行メモで放置しています。これは極めて勿体ない運用です。

Dev Mode（開発モード）において、エンジニアがコンポーネントを選択した際、最初に目に入る最高の一等地がこの Description 領域です。ここに構造化された仕様（Structured Specs）を注入します。

2.1 現場で即採用すべき「Description 記述標準フォーマット」

テキストの散文ではなく、エンジニアがパースしやすい Markdown ライクな構造で記述します。以下のフォーマットをコンポーネントの運用ルールとして厳格に適用してください。

[概要]
主要なアクション（フォーム送信、決定等）を誘導するプライマリボタン。1画面につき原則1つ。

[使用上の注意 / Do & Don’t]

  • DO: ダイアログ内の肯定的な最終操作に配置する。
  • DON’T: 破壊的アクション（削除等）には使用しない（Danger Variant を使用すること）。

[インタラクション / 状態遷移]

  • Hover: opacity 0.8 / cursor: pointer
  • Focused: border 2px var(–color-focus-ring)
  • Disabled: Pointer events none. フォームの必須項目未入力時に適用。

[アクセシビリティ (a11y)]

  • Role: button
  • Keyboard: Space / Enter で実行可能
  • Contrast Ratio: 4.5:1 以上確保済み (vs White Background)

[関連トークン / コード対応]

  • Component Code: `
  • Storybook: https://storybook.your-domain.com/?path=/docs/button

2.2 Dev Mode で極上の DX（Developer Experience）を提供する

Figma の Dev Mode を有効化すると、この Description はコードプロパティのすぐ上に配置されます。

エンジニアは外部ドキュメントへコンテキストスイッチすることなく、「UIを目で確認し」「仕様をその場で読み」「コードをコピーする」という一連の動作を1画面内でコンプリートできます。

—

3. 開発スピードを爆発させるショートカット＆神プラグイン

ドキュメンテーションとプロトタイピングの速度を殺さないためには、キーボード操作の完全自動化と、プラグインによるデータ構造化が不可欠です。

3.1 開発効率を劇的に高めるプロのキーボードショートカット

| ショートカット (Mac / Win) | 機能 | 現場での極限活用テクニック |
| :— | :— | :— |
| Shift + I | インスタンス/コンポーネント挿入 | キーボードのみでコンポーネント検索・配置。マウス操作を完全排除する。 |
| Option + 2 (Mac) / Alt + 2 (Win) | アセットパネル切り替え | デザイン層から即座にコンポーネントライブラリの検索へ遷移。 |
| Shift + R | ルーラー（定規）表示切り替え | ピクセルパーフェクトなアライメント確認と Padding 仕様の瞬時チェック。 |
| Cmd + Option + C / V | スタイルコピー＆ペースト | 自動レイアウトの Padding や Fill（色）、Effect を瞬時に別フレームへ転写。 |
| Shift + A | Auto Layout 追加 | すべてのコンポーネントを Flexbox 思考で構築する最速の鍵。 |

—

3.2 脱属人化を加速させる「神プラグイン」4選

1. EightShapes Spec Asset

コンポーネントの Spacing、Padding、Variant の一覧、そして Component Description を全自動でドキュメントフレームとして書き出すプラグイン。Figma キャンバス上に「印刷可能なレベルの仕様書」が一発で生成されます。

2. Tokens Studio for Figma (Figma Tokens)

デザインツール内のスタイルを JSON データとして一元管理する業界標準。Description 内に記述されたトークン名と実際の変数値をシームレスに結合します。

3. Component Governor

ライブラリ内の全コンポーネントの Description 記入率、Variant の命名ルール違反、アクセシビリティ定義の欠損をダッシュボード形式で分析・検知する監査ツール。

4. HTML to Design / Figma to Code

Figma 上のコンポーネント構造から、React/Tailwind/Vue などのクリーンなコードを生成。Description の仕様と照らし合わせながら実体コードの骨組みを最速で作成します。

—

4. 完全自動化パイプライン：Figma API → CI/CD → コード・Doc生成

ドキュメントの最新化を「人間の運用（手動）」に頼ると、デザインシステムは必ず壊れます。
「Figma API で Description を取得し、JSON 化して Storybook や Web サイトのドキュメントへ自動同期する」 のがテックリードとしての最適解です。

以下に、Figma API から Component Description およびメタデータを抽出・構造化するための設定ファイルと抽出スクリプトのプロトタイプを示します。

4.1 設定ファイル：`design-tokens.config.json`

Figma ファイルからどのコンポーネントをドキュメント化の対象とするかを制御する設定例です。

{
“figmaFileKey”: “d8Xk9J2LzMwQp1AaBbCcDd”,
“outputDir”: “./src/design-system/generated”,
“targetCanvas”: “❖ Core Components”,
“exportFormats”: [“json”, “yaml”],
“syncOptions”: {
“extractDescription”: true,
“parseMarkdownInDescription”: true,
“strictAccessibilityCheck”: true
}
}

4.2 Description抽出＆構造化スクリプト：`fetch-figma-docs.js`

Figma REST API から Component の Description を取得し、Markdown 構造を自動パースして開発用のメタデータ JSON に変換する Node.js スクリプトです。

/

  • Figma APIからComponent Descriptionを抽出し、
  • 構造化された仕様メタデータ(JSON)を生成する自動化スクリプト

/

const axios = require(‘axios’);
const fs = require(‘fs-extra’);
const path = require(‘path’);

const FIGMA_TOKEN = process.env.FIGMA_PERSONAL_ACCESS_TOKEN;
const FILE_KEY = “d8Xk9J2LzMwQp1AaBbCcDd”; // 対象のFigma File Key

async function fetchFigmaComponentDocs() {
try {
console.log(‘🚀 Figma API からコンポーネント定義を取得中…’);

// Figma API: コンポーネントメタデータの取得
const response = await axios.get(`https://api.figma.com/v1/files/${FILE_KEY}/components`, {
headers: { ‘X-Figma-Token’: FIGMA_TOKEN }
});

const components = response.data.meta.components;
const structuredDocs = {};

components.forEach(comp => {
// コンポーネント名とDescriptionを取得
const { name, description, key, containing_frame } = comp;

if (!description) {
console.warn(`⚠️ [WARN] コンポーネント “${name}” に Description が記載されていません。`);
return;
}

// Description (Markdown) の簡易パース処理
structuredDocs[name] = {
figmaKey: key,
category: containing_frame ? containing_frame.name : ‘Uncategorized’,
rawDescription: description,
parsedSpec: parseDescriptionMarkdown(description),
updatedAt: new Date().toISOString()
};
});

// 構造化データをJSONとして保存（Storybookやドキュメントサイトで読み込む）
const outputPath = path.resolve(__dirname, ‘./src/generated/component-specs.json’);
await fs.outputJson(outputPath, structuredDocs, { spaces: 2 });

console.log(`✅ ドキュメントデータの抽出が完了しました: ${outputPath}`);

} catch (error) {
console.error(‘❌ エラーが発生しました:’, error.message);
process.exit(1);
}
}

/

  • Component Description のテキストをパースし、オブジェクト化する

/
function parseDescriptionMarkdown(text) {
const sections = {};
const regex = /\[(.?)\]\s\n([\s\S]?)(?=\n\[|$)/g;
let match;

while ((match = regex.exec(text)) !== null) {
const title = match[1].trim().toLowerCase();
const content = match[2].trim();
sections[title] = content;
}

return sections;
}

fetchFigmaComponentDocs();

4.3 抽出・生成されるメタデータ成果物例：`component-specs.json`

この JSON をコードベースに取り込み、Storybook の `Docs` タブや社内ポータルに自動描写させることで、「Figma を更新すればドキュメントサイトも自動で最新化する」エコシステムが完成します。

{
“Button/Primary”: {
“figmaKey”: “c1a2b3c4d5e6”,
“category”: “Atoms/Buttons”,
“rawDescription”: “[概要]\n主要なアクションを誘導するプライマリボタン…\n[関連トークン / コード対応]\n- Component Code: `

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