figma-design-handoff

Figma のデザイン引き継ぎ

2026年現在、デザインツールの分野では Figma が圧倒的なシェアを誇り、大半のプロダクトチームが主要なデザインツールとして使用しています。構造化された引き継ぎワークフローによって、デザイナーが作成したものと開発者が実装するものの差であるデザインの乖離を解消できます。このスキルでは、Figma Variables からのデザイントークン生成、コンポーネント仕様の抽出、Dev Mode での確認、Auto Layout から CSS へのマッピング、ビジュアルリグレッションテストまで、一連のパイプラインを網羅します。

クイックリファレンス

ルール	ファイル	影響度	使用する場面
Figma Variables とトークン	rules/figma-variables-tokens.md	CRITICAL	Figma Variables を W3C デザイントークン JSON に変換する
コンポーネント仕様	rules/figma-component-specs.md	HIGH	Figma からコンポーネントの props、バリアント、状態を抽出する
Dev Mode での確認	rules/figma-dev-mode.md	HIGH	寸法、間隔、タイポグラフィ、アセットのエクスポート
Auto Layout → CSS	rules/figma-auto-layout.md	HIGH	Auto Layout を Flexbox/Grid にマッピングする
ビジュアルリグレッション	rules/figma-visual-regression.md	MEDIUM	本番 UI と Figma デザインを比較する

合計：1 カテゴリに 5 つのルール

Figma Dev Mode MCP Server（2026年の標準的な方法）

Figma Dev Mode MCP Server を使うと、手動で行う REST と Dev Mode の確認の大部分を置き換えられます。一度設定すれば、Figma にアクセスできる Claude Code セッションからデザインのコンテキスト、トークン、コードのマッピングを直接取得できます。

主なツール（16 個をドキュメント化 — developers.figma.com/docs/figma-mcp-server/tools-and-prompts）：

ツール	戻り値	用途
get_design_context	コンポーネントツリー + レイアウト + タイポグラフィ + 間隔	Figma ノードで最初に呼び出し、以降のすべてのツールの基盤にする
get_variable_defs	トークンコレクション（変数 + モード + エイリアス）	W3C DTCG JSON にそのままエクスポートする — REST パイプラインを省略
get_code_connect_map	Figma ノード → コードベースのコンポーネントマッピング	生成したコードを既存のリポジトリコンポーネントに紐付ける
get_screenshot	ノードまたはフレームの PNG	ビジュアル差分用のスクリーンショットを取得／チャットに埋め込む
search_design_system	ライブラリ全体からトークン／コンポーネントを検索	新しいものを生成する前に既存のトークンを探す
use_figma (ベータ版)	Figma キャンバスへの書き戻し	コードとデザインの双方向変換（キャンバスへの書き込み）
generate_figma_design (ベータ版)	プロンプトからデザインフレームを作成	引き継ぎ用の AI 生成デザインのひな型

インストール：Figma デスクトップアプリで Preferences → Dev Mode MCP Server を有効にするか、リモート MCP エンドポイントを使用します（読み取りツールにはデスクトップアプリは不要です）。Code Connect UI（2026年に GA）と組み合わせると、手動で JSON を設定せずに Figma ノード ID をコードベースのコンポーネントにマッピングできます。

// .claude/mcp-servers/figma.json — sample config
{
  "figma": {
    "command": "figma-mcp",
    "args": ["--mode=dev"],
    "env": { "FIGMA_ACCESS_TOKEN": "${FIGMA_TOKEN}" }
  }
}

クイックスタート

# 1. Export Figma Variables (Figma REST API)
curl -s -H "X-Figma-Token: $FIGMA_TOKEN" \
  "https://api.figma.com/v1/files/$FILE_KEY/variables/local" \
  > tokens/figma-local.json

# 2. Convert that response to W3C Design Tokens. This skill does NOT ship a
#    converter — the mapping (variables, modes, aliases, and the $value/$type
#    shape) is specified in rules/figma-variables-tokens.md, and the right
#    implementation depends on which collections and modes your file uses.
#    Earlier revisions of this Quick Start piped into a
#    `scripts/figma-to-w3c-tokens.js` that has never existed in this skill.
#    Result: tokens/figma-raw.json

# 3. Transform with Style Dictionary
npx style-dictionary build --config sd.config.js

# 4. Output: CSS custom properties + Tailwind theme
# tokens/
#   figma-raw.json        ← W3C Design Tokens format
#   css/variables.css     ← --color-primary: oklch(0.65 0.15 250);
#   tailwind/theme.js     ← module.exports = { colors: { primary: ... } }

// W3C Design Tokens Format (DTCG)
{
  "color": {
    "primary": {
      "$type": "color",
      "$value": "{color.blue.600}",
      "$description": "Primary brand color"
    },
    "surface": {
      "$type": "color",
      "$value": "{color.neutral.50}",
      "$extensions": {
        "mode": {
          "dark": "{color.neutral.900}"
        }
      }
    }
  }
}

// Style Dictionary config for Figma Variables
import StyleDictionary from 'style-dictionary';

export default {
  source: ['tokens/figma-raw.json'],
  platforms: {
    css: {
      transformGroup: 'css',
      buildPath: 'tokens/css/',
      files: [{ destination: 'variables.css', format: 'css/variables' }],
    },
    tailwind: {
      transformGroup: 'js',
      buildPath: 'tokens/tailwind/',
      files: [{ destination: 'theme.js', format: 'javascript/module' }],
    },
  },
};

引き継ぎワークフロー

デザインからコードへのパイプラインは、次の 5 段階で構成されます。

1. Figma でデザインする — デザイナーが Variables、Auto Layout、適切な命名を使用してコンポーネントを作成する
2. 仕様を抽出する — Dev Mode で間隔、タイポグラフィ、色を確認し、アセットをエクスポートする
3. トークンをエクスポートする — REST API またはプラグインで Figma Variables を W3C トークン JSON に変換する
4. コンポーネントを構築する — Auto Layout を CSS Flexbox/Grid にマッピングし、トークンを適用してバリアントを実装する
5. ビジュアル QA — Applitools を使って本番環境のスクリーンショットと Figma フレームを比較する

┌─────────────┐     ┌──────────────┐     ┌───────────────┐
│  Figma File  │────▶│  Dev Mode    │────▶│  tokens.json  │
│  (Variables, │     │  (Inspect,   │     │  (W3C DTCG    │
│  Auto Layout)│     │   Export)    │     │   format)     │
└─────────────┘     └──────────────┘     └───────┬───────┘
                                                  │
                                                  ▼
┌─────────────┐     ┌──────────────┐     ┌───────────────┐
│  Visual QA  │◀────│  Components  │◀────│ Style         │
│  (Applitools,│     │  (React +   │     │ Dictionary    │
│   Chromatic) │     │  Tailwind)   │     │ (CSS/Tailwind)│
└─────────────┘     └──────────────┘     └───────────────┘

ルール

各ルールは rules/ ディレクトリからオンデマンドで読み込まれます。

Auto Layout から CSS へのマッピング

よく使われるマッピングのクイックリファレンス：

Figma Auto Layout	CSS 相当	Tailwind クラス
方向：水平	flex-direction: row	flex-row
方向：垂直	flex-direction: column	flex-col
間隔：16	gap: 16px	gap-4
パディング：16	padding: 16px	p-4
パディング：16、24	padding: 16px 24px	py-4 px-6
配置：中央	align-items: center	items-center
並び：両端揃え	justify-content: space-between	justify-between
コンテナーに合わせる	flex: 1 1 0%	flex-1
コンテンツに合わせる	width: fit-content	w-fit
固定幅：200	width: 200px	w-[200px]
最小幅：100	min-width: 100px	min-w-[100px]
最大幅：400	max-width: 400px	max-w-[400px]
折り返し	flex-wrap: wrap	flex-wrap
絶対位置	position: absolute	absolute

ビジュアル QA ループ

// Applitools Eyes + Figma Plugin — CI integration
import { Eyes, Target } from '@applitools/eyes-playwright';

const eyes = new Eyes();

await eyes.open(page, 'MyApp', 'Homepage — Figma Comparison');

// Capture full page
await eyes.check('Full Page', Target.window().fully());

// Capture specific component
await eyes.check(
  'Hero Section',
  Target.region('#hero').ignoreDisplacements()
);

await eyes.close();

Applitools Figma Plugin は、本番環境のスクリーンショットを Figma フレームに重ねて、次の問題を検出します：

• 色の不一致（トークンが適用されていない、またはモードが誤っている）
• 間隔のずれ（パディング／マージンの差異）
• タイポグラフィの不整合（フォントサイズ、ウェイト、行の高さ）
• 状態の欠落（ホバー、フォーカス、無効状態が実装されていない）

主な決定事項

決定事項	推奨事項
トークン形式	W3C Design Tokens Community Group（DTCG）JSON
トークンパイプライン	Figma REST API → Style Dictionary → CSS/Tailwind
色形式	知覚的に均一なテーマ設定に OKLCH を使用
レイアウトのマッピング	Auto Layout → CSS Flexbox（2D レイアウトには Grid）
ビジュアル QA ツール	デザインと開発の差分確認に Applitools Eyes + Figma Plugin
仕様形式	Figma コンポーネントのプロパティに対応する TypeScript インターフェース
モードの処理	Figma Variable のモード → CSS メディアクエリ／クラス切り替え

アンチパターン（禁止）

• ハードコードされた値：色、間隔、タイポグラフィをハードコードせず、必ずトークンを参照してください
• Dev Mode の省略：寸法を目測せず、正確な値には Dev Mode を使用してください
• 手動でのトークン同期：Figma から値を手動でコピーせず、REST API で自動化してください
• モードの無視：ライト／ダークモードを持つ変数は別ファイルではなく、テーマ切り替えに対応付けてください
• スクリーンショットだけの QA：構造化されたリグレッションテストを行わないビジュアル比較では、微妙なずれを見逃します
• フラットなトークン構造：フラットなキーと値の組み合わせではなく、ネストされた W3C DTCG 形式を使用してください

参考資料

リソース	説明
references/figma-to-code-workflow.md	エンドツーエンドのワークフロー、ツールチェーンの選択肢
references/design-dev-communication.md	PR テンプレート、コンポーネントのステータス管理
references/applitools-figma-plugin.md	セットアップ、CI 統合、比較設定

関連スキル

• ork:design-system-tokens — W3C トークンアーキテクチャと Style Dictionary の変換
• ork:ui-components — shadcn/ui と Radix のコンポーネントパターン
• ork:accessibility — Figma から抽出したコンポーネントの WCAG 準拠