デザイン～フロントエンドの開発でAIエージェントを導入する前に知っておきたい知識をまとめています。

この記事の対象読者

AIがコードを書いてくれる時代になっても、「デザインを正確にコードへ落とし込む」部分だけはなかなかうまくいかない、と感じたことがある人向けの記事です。

ロジックや機能の実装はAIに任せられるようになった一方で、デザインの再現度はまだAI任せにしづらい領域です。ここはデザイナーとエンジニアの境界にあり、両方の知見が無いと踏み込みにくい領域です。デザイン×AIエージェントの情報は個別には増えていますが、「デザイントークンの管理」「AGENTS.mdによる複数ツール共通のルール設計」「実際に動かして検証する」までを一貫してまとめた情報はまだ少ないと感じて書きました。

Figma / Penpotなどのデザインツールと、Claude Code / Cursor / Codexなどのコーディングエージェントを両方使っている（または使おうとしている）
複数のAIエージェントに、同じルールやデザインシステムを一貫して守らせたい
デザイン→コード変換の精度を上げたい

このあたりに当てはまる人を想定しています。

準備

npmのインストール

必要なnpmのインストールをします。

# Viteのインストール
npm create vite@latest
# プロジェクト名の指定、React/Typescript/ESLint or Oxlint

cd プロジェクト名
npm install

# storybookのインストール
npm create storybook@latest
# 公式の@storybook/addon-mcpは使わないので入れない

# tokens.jsonを使わないなら不要
# style dictionary
npm i style-dictionary

# Penpotを使わないなら不要
# penpot mcp
npm i -D @penpot/mcp

# Tokens Studio for Figma、Penpotからtokens.jsonのエクスポートをしないなら不要
# @tokens-studio/sd-transforms(Tokens Studio for FigmaやPenpotがエクスポートするtokens.jsonを標準規格に変換する)
npm i -D @tokens-studio/sd-transforms

npm Scriptの追加

package.json

{
  "scripts": {
    "build-tokens": "style-dictionary clean --config style-dictionary.config.js && style-dictionary build --config style-dictionary.config.js",
    "clean-tokens": "style-dictionary clean --config style-dictionary.config.js",
    "typecheck": "tsc --noEmit",
    "storybook": "storybook dev -p 6006",
    "build-storybook": "storybook build",
    "test": "vitest run",
    "test:watch": "vitest",
    "penpot-mcp": "penpot-mcp"
  }
}

AIに働いてもらうために使うファイルを知る

ファイル	役割
AGENTS.md	プロジェクト全体のSSOT（共通アーキテクチャ、コーディング規約、全体方針）
DESIGN.md	UI/UX設計・デザインシステムのSSOT（デザインルール、コンポーネント設計原則、UIガイドライン）
SKILL.md	特定タスク実行手順のSSOT（専門知識のカプセル化・再利用可能なワークフロー手順）
tokens.json	デザイントークンのSSOT（色・タイポグラフィ・Spacing等の具体的な数値データ）

なぜ複数のファイルに分けるのか

AIエージェントは、AGENTS.mdを毎回のセッション開始時に必ず読み込みます。一方でDESIGN.mdやSKILL.mdは、該当する作業が発生した時だけオンデマンドで読み込まれます。

もし全部を1つのファイルに詰め込むと、ボタンの色を1つ直すだけの作業でも、関係の無いアクセシビリティ規定やモーション設計の長文がAIのコンテキストに毎回混ざり込み、コンテキストを圧迫したり指示が埋もれて無視されたりする原因になります。

役割ごとにファイルを分けてポインタ化しておくことで、AIは今のタスクに必要な文脈だけをピンポイントで読み込めるようになります。この考え方は、後述のSKILL.mdの「ファイルの肥大化防止」でも同じ理由で出てきます。

AGENTS.md

AGENTS.mdの記述例

AGENTS.mdの中でDESIGN.md、.agents/skills/、tokens.jsonへの参照を記述します。

AGENTS.md

# Global Agent Rules

- **基本方針**: 対話・コードコメント・コミットメッセージはすべて【日本語】で行うこと。
- **UI / デザインシステム**: [DESIGN.md](./DESIGN.md) を参照し、厳密に従うこと。
- **デザイントークン**:
  - カラー、タイポグラフィ、Spacing 等のスタイルの正解データ(Single Source of Truth)は `./tokens.json` です。
  - `DESIGN.md` は原則と使い分け(Why / How)のみを扱い、具体値は持ちません。
    値の記述が両者で食い違った場合は、常に `tokens.json` を優先してください。
  - コンポーネント実装時は値を直書き(ハードコード)せず、`tokens.json`(または生成された CSS変数 / TS定数)を参照してください。
  - `tokens.json` を変更・追加した場合は、必ず `npm run build-tokens` を実行して反映してください。
- **専門タスク・スキル**: 特定の作業手順やワークフローについては [.agents/skills/](./.agents/skills/) 内の各 `SKILL.md` を参照すること。
- **実装リファレンス**: 既存コンポーネントの実装パターンや構造は `src/components/` 配下を参照すること。

## Frequently Used Commands
- トークンビルド: `npm run build-tokens`
- Storybook起動: `npm run storybook`
- テスト実行: `npm run test`
- 型チェック: `npm run typecheck`
- Penpot MCP サーバ起動: `npm run penpot-mcp`

Agent Skills

特定のアクションやワークフローを AI エージェントに正確に実行させるための「手順書・拡張能力定義パッケージ」です。プロジェクト全体の基本ルール（AGENTS.md）とは分離し、特定タスクに必要な専門手順・制約・スクリプトをカプセル化して管理します。

特徴・強み

特徴	内容
決定性の担保	フォルダ内に `scripts/`（Linterや自動テスト等）で内包しているツールを実行させてその場で検証・テストが可能
コンテキストの節約	常時読み込まれる `AGENTS.md` と異なり、該当タスクの実行時（オンデマンド）のみ読み込まれる

my-project/
 └── .agents/
      └── skills/
           ├── <skill-name-1>/
           │    ├── SKILL.md            # 【必須】スキルの手順・制約(500行以内)
           │    ├── references/         # 【任意】補助ドキュメント(500行超の参照資料)
           │    │    └── api-spec.md
           │    └── scripts/            # 【任意】確定的な自動化スクリプト
           │         └── sync-tokens.js
           │
           └── <skill-name-2>/
                └── SKILL.md

スキルの具体例

分類	詳細
専門ワークフロー・生成	新規コンポーネント作成手順 UI/UXデザイン作成手順 i18n(多言語)辞書ファイルの自動生成
デザインシステム・アクセシビリティ検証	カラーシステムに基づく配色ルールチェックアクセシビリティ(WCAG 2.2 AA)の自動検証スクリプト実行 & 修正方針の提案共通デザインシステムの自動バリデーション
ナレッジ・コンポーネント利用規約	デザインシステムコンポーネントの使用例(ベストプラクティス)

読込みタイミング

オンデマンド（該当するタスクが発生した必要な時のみ自動/手動で読み込まれる）

ファイルの肥大化防止

500行以内（公式仕様で「500行未満」が明記）。必要な時だけ読み込まれるため、常に読み込まれるAGENTS.mdより長めに書けます。500行を超える詳細資料やAPI仕様は references/ ディレクトリへ追い出し、相対パスで参照させます（漸進的開示）。

ディレクトリ構成イメージ

.agents/skills/figma-sync/
  ├── SKILL.md                        # 【本文】以下のサンプルコード
  ├── references/
  │   └── component-mapping.md        # よくあるFigmaレイヤー名→既存コンポーネントの対応表
  └── scripts/
      └── check-token-usage.ts        # Hex/px直書きを検出する自動検証スクリプト

SKILL.md のサンプルコード

SKILL.md

---
name: figma-sync
description: FigmaのデザインをMCP経由で取得し、既存コンポーネントを再利用しながら正確にコード化するスキル。Figmaのフレーム/コンポーネントをコード化する際に使用。
---

# Figma Sync Skill

FigmaのMCPツールで取得したデザイン情報をもとに、プロジェクトの規約（DESIGN.md / tokens.json）に準拠したコンポーネントを作成・更新します。

## 前提条件・絶対制約
- 値の直書き禁止。`tokens.json`由来のCSS変数（`var(--color-brand-primary)`等）のみを使用すること。
- 新規要素を作る前に `src/components/` 配下を確認し、既存コンポーネントを再利用すること。
- 全体的なデザイン原則についてはルートの [DESIGN.md](../../../DESIGN.md) を参照すること。

## 実行ワークフロー

Figmaのデザインをコード化するよう指示された場合は、以下の手順に厳密に従ってください。

### Step 1: デザイン情報の取得
FigmaのMCPツール（`get_design_context`）で、対象フレームの構造・スタイル・テキストを取得する。

### Step 2: トークンとの照合
取得した色・spacing・フォント等の値を `tokens.json` と照合する。一致するトークンがあれば必ずCSS変数を使用し、一致するものが無ければ直書きせず一度立ち止まってユーザーに確認する。

### Step 3: 既存コンポーネントとの照合
`src/components/` 配下を確認し、レイヤー名やスタイルが類似する既存コンポーネントが無いか確認する。あれば新規作成せず再利用する。
判断に迷う場合は `./references/component-mapping.md` の対応表を確認する。

### Step 4: 自動検証スクリプトの実行
生成したコードにHex/pxの直書きが無いか、検証スクリプトで確認する。

`npx ts-node .agents/skills/figma-sync/scripts/check-token-usage.ts src/components/<ComponentName>/<ComponentName>.tsx`

- エラーが検出された場合は直ちに修正し、パスするまで再実行してください。

### Step 5: トークンビルド
`tokens.json` を変更・追加した場合は `npm run build-tokens` を実行して反映する。

## Do's and Don'ts
- **Do**: Figmaのレイヤー名をコンポーネント名の参考にする。
- **Do**: バリエーション（Hover/Disabled等）はPropsとして表現する。
- **Don't**: `tokens.json`に無い値をHexやpx直書きで実装しない。
- **Don't**: 既存コンポーネントがあるのに似たものを新規で作らない。

記述のポイント

項目	内容
descriptionの明確化	「何をするスキルか」を簡潔かつ具体的に記述
確定的なコマンドの記述	Step4のように実行させるコマンドを明記することで、AI が迷わず `scripts/` 内の検証ツールや Linter を実行できる
段階的開示のパス提示	Step 3のように、詳細な対応表は別ドキュメント(`references/` 配下)に分離し相対パスで指定することで、SKILL.md 本文の 500 行制限を守りつつ高精度な指示が出せる
実際に実行可能な関数名・コマンド名を指定	抽象的な「Figmaと連携する」ではなく、`get_design_context` や `npm run build-tokens` のように

DESIGN.md

仕様・設計思想ガイドライン: https://github.com/google-labs-code/design.md

「なぜそのデザインなのか(設計意図/RationaleやDo's/Don'ts)」という自然言語の文脈(Context)までAIに伝えるためのデザインディレクション仕様を書きます。

役割と導入効果

項目	内容
DESIGN.md なし	配色や余白がバラバラな、汎用的で統一感のない"それっぽいUI"が出力されがち
DESIGN.md あり	自社のデザインシステム、アクセシビリティ基準、ブランドルールに準拠した高品質なアウトプットを自動生成

記述内容(書くこと)

分類	例
設計思想・意図 (Rationale)	なぜこの色なのかターゲットユーザー(例: 高齢者向けに視認性重視等)
デザインシステムの制約	Hexカラーの直書き禁止(CSS変数利用) ボタンの余白ルール
コンポーネント固有ルール & Do's / Don'ts	破壊的アクション以外で赤色禁止

配置場所と基本構造

項目	内容
配置場所	リポジトリルート(`./DESIGN.md`)
ファイル構造	冒頭の `YAML Frontmatter`(機械読取用) + 本文 `Markdown`(自然言語の意図・ガイドライン)

DESIGN.md

# Design Principles & Guidelines

> **値の正解データ(Single Source of Truth)は [`tokens.json`](./tokens.json)です。**
> このドキュメントは「なぜ・どう使い分けるか」の原則のみを扱い、具体値は持ちません。

## 1. Concept & Rationale
- 複雑なデータを扱うツールのため、「高い視認性」「シンプルな情報階層」「誤操作を防ぐフィードバック」を最優先とする。

## 2. Color System & Usage
- `color.brand.primary`(`var(--color-brand-primary)`): テキスト、主要アイコン、強調枠線に使用。背景への広範な使用は禁止。
- `color.brand.accent`(`var(--color-brand-accent)`): 主なCTA(コンバージョンボタン)および重要な通知バッジのみに使用。

## 3. Component Rules
### Buttons
- 角丸(border-radius)は全コンポーネントで `border.radius.default` に統一する(`var(--border-radius-default)`)。
- **Zero Hex Policy**: コード内(JSX/CSS)への Hex 値直書きは禁止。必ず `var(--color-brand-primary)` 等の CSS 変数を使用すること。

## 4. Do's & Don'ts
- **Do:** 余白は常に `spacing.base` の倍数で配置する(`calc(var(--spacing-base) * n)`)。
- **Don't:** ドロップシャドウを多用しない(カード要素のみ subtle-shadow を許容)。

ファイルの肥大化防止

項目	内容
適正行数	200〜500行（オンデマンドで読み込まれるためAGENTS.mdより長めに記述可能）
分割方針	500行を超える場合やカテゴリが多岐にわたる場合は、DESIGN.mdをインデックス（親）とし、詳細は`docs/design/`へ切り出す

すべての基盤ルールやA11y規定をDESIGN.md 1つに詰め込むと、AIがちょっとしたボタンの修正を行う際にも関係のないMotionやA11yの長文テキストがプロンプトに入り込み、指示を無視する原因になります。情報カテゴリごとにファイルを分けてポインタ化しておくことで、AIはタスクに必要な文脈だけをピンポイントでコンテキストに組み込めるようになります。

ディレクトリ構造例

my-project/
 ├── DESIGN.md                    # 【親】全体原則・最重要制約・インデックス(50〜100行)
 └── docs/
      └── design/
           ├── foundations.md     # カラー・タイポグラフィ・8pxグリッド等の基礎トークン
           ├── accessibility.md   # A11y(コントラスト比・ARIA属性・キーボード操作)
           ├── motion.md          # アニメーションイージング・duration規約
           ├── i18n-typography.md # 多言語・日本語固有のフォント/行高ルール
           └── components/        # 各コンポーネントの詳細仕様
                ├── button.md
                └── modal.md

分割時のDESIGN.md記述例

DESIGN.md

# DESIGN.md

## 絶対遵守事項(常に強制)
- **Zero Hex Policy**: UIコンポーネントへのHexカラーの直書きは禁止。`src/tokens/variables.css` のCSS変数を使用すること。
- **8pxグリッド**: margin/paddingはすべて8pxの倍数を使用すること(`var(--spacing-2)` 等)。

## 詳細仕様(必要な時に読む)
関連するタスクに取り組む際は、以下の各ガイドを参照してください。

- **トークン・基礎原則**: [docs/design/foundations.md](./docs/design/foundations.md)
- **アクセシビリティ(A11y)**: [docs/design/accessibility.md](./docs/design/accessibility.md)
- **モーション・アニメーション**: [docs/design/motion.md](./docs/design/motion.md)
- **コンポーネント仕様**: [docs/design/components/](./docs/design/components/)

tokens.json

Figmaなどのデザインツールからエクスポートされ、Style Dictionaryなどのビルドツールや AI エージェントが参照する機械可読なデザイントークンの正本データです。

	内容
tokens.json	「数値データ(変数)」 ➔ 自動変換してCSS / TS型定義のソースになる
DESIGN.md	「設計意図・文脈(文章)」 ➔ AIにトークンの使い方や理由を指示する

主な定義内容

色、余白、タイポグラフィ、シャドウ、角丸など

tokens.jsonの作成

DTCG形式で作成します。仕様に従って手動で作成したり、AIエージェントに作成させることもできますが、UIデザインツールからエクスポートすることもできます。

Figma

Figmaのネイティブインポート機能には型のサポート範囲に大きな制限があるのでプラグインをつかいます。

Tokens Studio for Figma

プラグイン呼び出し	インポート/エクスポート	エクスポートの設定

プラグインから「Tokens Studio for Figma」を検索	Importはそのままtokens.json選択	exportは「single file」タブでall tokens setsにチェックして「Export」ボタンを押す

Penpot

左メニューの「TOKENS」タブ	TOOLS	EXPORT

TOKENSタブに切り替え	Importはそのままtokens.json選択	EXPORTは「MULTIPLE FILES」としてエクスポートして、ダウンロードしたzipの中のtokens.jsonのみ使う

※Tokens Studio for FigmaやPenpotからエクスポートしたtokens.jsonは完全にはDTCG形式準拠ではないので@tokens-studio/sd-transformsを使って修正します。

@tokens-studio/sd-transforms：fontFamilies→fontFamilyのような変換を自動でやるTokens Studio公式npmパッケージ

tokens.json

{
  "color": {
    "brand": {
      "primary": {
        "$value": "#0F1419",
        "$type": "color",
        "$description": "メインのブランドカラー。主要なテキストや強調表示に使用。"
      },
      "accent": {
        "$value": "#B8411F",
        "$type": "color",
        "$description": "CTAボタンや重要通知のみに使用するアクセントカラー。"
      }
    },
    "semantic": {
      "bg": {
        "default": {
          "$value": "#FFFFFF",
          "$type": "color"
        }
      }
    }
  },
  "spacing": {
    "base": {
      "$value": "4px",
      "$type": "dimension"
    },
    "md": {
      "$value": "16px",
      "$type": "dimension",
      "$description": "8pxグリッド標準パディング(base * 4)"
    }
  },
  "border": {
    "radius": {
      "default": {
        "$value": "8px",
        "$type": "dimension"
      }
    }
  },
  "font": {
    "family": {
      "base": {
        "$value": [
          "Inter",
          "Noto Sans JP",
          "sans-serif"
        ],
        "$type": "fontFamily",
        "$description": "全体の基準フォント。日本語は Noto Sans JP にフォールバックする。"
      }
    },
    "size": {
      "base": {
        "$value": "16px",
        "$type": "fontSize",
        "$description": "本文の基準サイズ。"
      }
    },
    "weight": {
      "regular": {
        "$value": 400,
        "$type": "fontWeight",
        "$description": "本文の標準ウェイト。"
      },
      "semibold": {
        "$value": 600,
        "$type": "fontWeight",
        "$description": "ボタンラベル等、操作要素の強調に使用。"
      }
    },
    "lineHeight": {
      "normal": {
        "$value": 1.5,
        "$type": "number",
        "$description": "本文および操作要素の標準行高。"
      }
    }
  }
}

作成したtokens.jsonをvariables.cssとtokens.tsに変換できます。

style-dictionary.config.js

/**
 * Design Tokens ビルド設定。
 *
 * 正解データ(Single Source of Truth)は `tokens.json`(DTCG 形式)。
 * ここから CSS 変数と TypeScript 定数を生成し、コンポーネント側は
 * 生成物のみを参照する(AGENTS.md / DESIGN.md §3 Zero Hex Policy)。
 *
 * 生成物は `src/styles/generated/` 配下にのみ出力する。
 * 同ディレクトリは全ファイルが生成物であり、手で編集しないこと。
 * 手書きのスタイルは `src/styles/` 直下に置く(例: global.css)。
 */
import StyleDictionary from 'style-dictionary';
import { register } from '@tokens-studio/sd-transforms';

// Penpot(Tokens Studio 系)のエクスポートは fontFamilies/fontSizes/fontWeights
// のように複数形の $type を使うため、DTCG 仕様準拠の単数形(fontFamily 等)に
// 変換するプリプロセッサを登録する。tokens.json(手書き)はもともと単数形なので
// このプリプロセッサは実質的に無害(変換対象が無ければ何もしない)。
register(StyleDictionary);

export default {
  // tokens.json は $value / $type を使う DTCG 形式のため必須。
  usesDtcg: true,
  preprocessors: ['tokens-studio'],
  source: ['tokens.json'],
  platforms: {
    css: {
      transformGroup: 'css',
      buildPath: 'src/styles/generated/',
      files: [
        {
          destination: 'variables.css',
          format: 'css/variables',
          // :root に出すことで全コンポーネントから var() 参照できる。
          options: { selector: ':root', outputReferences: true },
        },
      ],
    },
    ts: {
      // transformGroup 'js' には fontFamily/css が含まれず、fontFamily 型が
      // 配列のまま出力されてしまうため、transforms を明示して追加する。
      transforms: ['attribute/cti', 'name/pascal', 'size/rem', 'color/hex', 'fontFamily/css'],
      buildPath: 'src/styles/generated/',
      files: [
        {
          // 名前付き const を出力する(例: export const ColorBrandAccent = '#b8411f';)。
          // .ts として出力するため別途 .d.ts は不要。
          destination: 'tokens.ts',
          format: 'javascript/es6',
        },
      ],
    },
  },
};

変換実行

npm run build-tokens

実行すると2つのファイルが作成されます。

ファイル	用途
`src/styles/generated/tokens.ts`	`.tsx`, `.stories.tsx`, 設定ファイルからインポート
`src/styles/generated/variables.css`	アプリのグローバルCSSエントリポイント(`main.tsx` / `index.css`等)から読み込む。Storybookで同じ見た目を再現したい場合は `.storybook/preview.ts` でも同様にインポートする

配置

AGENTS.mdを起点にする

各ツールから、事実上の標準となっているAGENTS.mdを読み込ませ、そこからDESIGN.md、tokens.json、Agent Skillsを参照するようにしていきます。

my-project/
 ├── AGENTS.md                                # 全AI共通の開発ルール・リポジトリ構造
 ├── DESIGN.md                                # 【デザイン設計書】UI/UXポリシー・Do's & Don'ts
 ├── tokens.json                              # 【データの源泉】W3C 規格のデザイントークン原本
 │
 ├─【設定ファイル & エントリーポイント】
 │   ├── CLAUDE.md                            # Claude Code 向け参照
 │   ├── .claude/settings.json                # Claude Code 実行権限設定
 │   ├── .mcp.json                            # ClaudeのMCP
 │   │
 │   ├── .codex
 │   │    ├──config.toml                      # Codex CLIのMCP
 │   │    └──rules/default.rules              # Codex CLI 実行権限設定
 │   │
 │   ├── .cursor/
 │   │    ├── permissions.json                # Cursor auto-run許可リスト
 │   │    └── mcp.json                        # Cursor のMCP
 │   │
 │   ├── .devin/
 │   │    ├── mcp_config.json                 # Devin CLI・Devin DesktopのMCP(共通)
 │   │    └── config.local.json               # Devin CLI 実行権限設定(gitignore対象)
 │   │
 │   └── .vscode/
 │         ├── settings.json                  # GitHub Copilot(VS Code拡張) 実行権限設定
 │         └── mcp.json                       # GitHub Copilot(VS Code拡張) のMCP
 │
 └── .agents/                                 # 【共通スキル】
       ├── skills/                            # Agent Skills 仕様に基づく再利用可能手順
       │    ├── skill-name-1/SKILL.md
       │    └── skill-name-2/SKILL.md
       └── mcp_config.json                    # Antigravity CLIのMCP

Antigravity CLI・Devin Desktopの実行権限設定ファイルはプロジェクト外

ツール	OS	パス
Antigravity CLI	Windows	`C:\Users\ユーザー名\.gemini\antigravity-cli\settings.json`
Antigravity CLI	macOS	`/Users/ユーザー名/.gemini/antigravity-cli/settings.json`
Devin Desktop	Windows	`C:\Users\ユーザー名\AppData\Roaming\devin\config.json`
Devin Desktop	macOS/Linux	`~/.config/devin/config.json`

各ツールからAGENTS.mdを読むようにする

CLAUDE.mdは@AGENTS.mdのインポートのみにしていて、基本変更しないのでこの1行のままにしています。

※Codex CLI、Cursor、GitHub Copilot、Antigravity CLI、Devin、Devin DesktopはプロジェクトルートのAGENTS.mdを読み込むので不要

Claude Code固有の設定

CLAUDE.md

Claude CodeはAGENTS.mdをネイティブには読まないため、CLAUDE.mdの@path/to/import構文でAGENTS.mdをインポートします(Anthropic公式ドキュメントで推奨されている方法です)。Windowsでのシンボリックリンク（ln -s AGENTS.md CLAUDE.md）は管理者権限や開発者モードが必要になるため、こちらのインポート構文の方が環境を選ばず確実です。

CLAUDE.md

@AGENTS.md

Claude Codeに.agents/skills/配下にあるSkillsをプラグインとして認識させる

Claude Codeは.claude/skills/配下しか自動でスキャンしないので、.agents/skills/に置く場合はSYMLINKの設定が必要になります。（.claude/skills/配下に置いていればこの手順は不要。CursorでClaudeを使う場合などは設定不要）

プラグインとして認識させないと下記のメリットが失われるので、Claudeしか使わない場合は.claude/skills/に配置するのがよいです。

AIが迷わずにスクリプトを実行できる
コンテキスト消費が抑えられる
トリガーワードでの自動発火や、/figma-syncのような呼び出しができるようになる

Mac / Linux / Git Bash / WSL

# 1. 親ディレクトリの存在を保証 (-p で存在すればスキップ)
mkdir -p .claude/skills

# 2. シンボリックリンクの作成
# Claude Code: スキルごとに個別 symlink
ln -sfn ../../.agents/skills/skill-name-1 .claude/skills/skill-name-1
ln -sfn ../../.agents/skills/skill-name-2 .claude/skills/skill-name-2

# 3. 動作確認
ls -la .claude/skills/

# ==========================================
# 解除用コマンド(必要に応じて使用)
# ==========================================
# rm .claude/skills/skill-name-1
# rm .claude/skills/skill-name-2

Windows (PowerShell) ※要管理者権限または開発者モード

# 1. 親ディレクトリの存在を保証
New-Item -ItemType Directory -Force -Path .claude\skills | Out-Null

# 2. シンボリックリンクの作成(既存パスがあれば削除してから再作成)
# Claude Code: スキルごとに個別 symlink
$links = @{
    ".claude\skills\skill-name-1"    = "..\..\.agents\skills\skill-name-1"
    ".claude\skills\skill-name-2" = "..\..\.agents\skills\skill-name-2"
}
foreach ($pair in $links.GetEnumerator()) {
    if (Test-Path $pair.Key) { Remove-Item $pair.Key -Force }
    New-Item -ItemType SymbolicLink -Path $pair.Key -Target $pair.Value | Out-Null
}

# 3. 動作確認
Get-ChildItem .claude\skills\

# ==========================================
# 解除用コマンド(必要に応じて使用)
# ==========================================
# Remove-Item .claude\skills\skill-name-1
# Remove-Item .claude\skills\skill-name-2

Windows (Command Prompt / cmd.exe) ※要 /D オプション

:: 1. 親ディレクトリの存在を保証
mkdir .claude\skills 2>nul

:: 2. シンボリックリンクの作成(※ディレクトリリンクのため /D オプションを使用)
:: Claude Code: スキルごとに個別 symlink
mklink /D ".claude\skills\skill-name-1" "..\..\.agents\skills\skill-name-1"
mklink /D ".claude\skills\skill-name-2" "..\..\.agents\skills\skill-name-2"

:: 3. 動作確認
dir .claude\skills\

:: ==========================================
:: 解除用コマンド(ディレクトリリンク解除のため del ではなく rmdir を使用)
:: ==========================================
:: rmdir ".claude\skills\skill-name-1"
:: rmdir ".claude\skills\skill-name-2"

各ツール専用のファイルの配置

Claude

.claude/settings.json

{
  "permissions": {
    "allow": [
      "Bash(npm run build-tokens)",
      "Bash(npm run storybook)",
      "Bash(npx @playwright/mcp@latest)"
    ]
  }
}

.mcp.json

{
  "mcpServers": {
    "figma": {
      "type": "http",
      "url": "https://mcp.figma.com/mcp"
    },
    "penpot": {
      "type": "http",
      "url": "${PENPOT_MCP_URL:-http://localhost:4401/mcp}"
    },
    "storybook": {
      "type": "stdio",
      "command": "npx",
      "args": ["-y", "storybook-mcp-server"],
      "env": {
        "STORYBOOK_URL": "${STORYBOOK_URL:-http://localhost:6006}"
      }
    },
    "playwright": {
      "type": "stdio",
      "command": "npx",
      "args": ["-y", "@playwright/mcp@latest"]
    }
  }
}

Cursor

.cursor/permissions.json

{
  "terminalAllowlist": [
    "npm run build-tokens",
    "npm run storybook",
    "npx @playwright/mcp@latest"
  ]
}

.cursor/mcp.json

{
  "mcpServers": {
    "figma": {
      "type": "http",
      "url": "https://mcp.figma.com/mcp"
    },
    "penpot": {
      "type": "http",
      "url": "http://localhost:4401/mcp"
    },
    "storybook": {
      "type": "stdio",
      "command": "npx",
      "args": ["-y", "storybook-mcp-server"],
      "env": {
        "STORYBOOK_URL": "http://localhost:6006"
      }
    },
    "playwright": {
      "type": "stdio",
      "command": "npx",
      "args": ["-y", "@playwright/mcp@latest"]
    }
  }
}

Codex CLI

.codex/rules/default.rules

prefix_rule(
    pattern = ["npm", "run", "build-tokens"],
    decision = "allow",
    justification = "Build tokens script is safe to execute",
)

prefix_rule(
    pattern = ["npm", "run", "storybook"],
    decision = "allow",
    justification = "Local Storybook dev server is safe to execute",
)

prefix_rule(
    pattern = ["npx", "@playwright/mcp@latest"],
    decision = "allow",
    justification = "Playwright MCP tool is safe to execute",
)

.codex/config.toml

[mcp_servers.figma]
url = "https://mcp.figma.com/mcp"

[mcp_servers.penpot]
url = "http://localhost:4401/mcp"

[mcp_servers.storybook]
command = "npx"
args = ["-y", "storybook-mcp-server"]

[mcp_servers.storybook.env]
STORYBOOK_URL = "http://localhost:6006"

[mcp_servers.playwright]
command = "npx"
args = ["-y", "@playwright/mcp@latest"]

GitHub Copilot(VS Code拡張)

.vscode/settings.json

{
  "chat.tools.terminal.enableAutoApprove": true,
  "chat.tools.terminal.autoApprove": {
    "/^npm run build-tokens$/": true,
    "/^npm run storybook$/": true
  }
}

.vscode/mcp.json

{
  "servers": {
    "figma": {
      "type": "http",
      "url": "https://mcp.figma.com/mcp"
    },
    "penpot": {
      "type": "http",
      "url": "http://localhost:4401/mcp"
    },
    "storybook": {
      "type": "stdio",
      "command": "npx",
      "args": ["-y", "storybook-mcp-server"],
      "env": {
        "STORYBOOK_URL": "http://localhost:6006"
      }
    },
    "playwright": {
      "type": "stdio",
      "command": "npx",
      "args": ["-y", "@playwright/mcp@latest"]
    }
  }
}

Antigravity CLI

%USERPROFILE%.gemini\antigravity-cli\settings.json

{
  "permissions": {
    "allow": [
      "command(npm run build-tokens)",
      "command(npm run storybook)",
      "command(npx @playwright/mcp@latest)"
    ]
  }
}

.agents/mcp_config.json

{
  "mcpServers": {
    "figma": {
      "serverUrl": "https://mcp.figma.com/mcp"
    },
    "penpot": {
      "serverUrl": "http://localhost:4401/mcp"
    },
    "storybook": {
      "command": "npx",
      "args": ["-y", "storybook-mcp-server"],
      "env": {
        "STORYBOOK_URL": "http://localhost:6006"
      }
    },
    "playwright": {
      "command": "npx",
      "args": ["-y", "@playwright/mcp@latest"]
    }
  }
}

Devin CLI

MCPサーバー設定は.devin/mcp_config.json(プロジェクト、Devin Desktopと共通)に書きます。

.devin/mcp_config.json

{
  "mcpServers": {
    "figma": {
      "url": "https://mcp.figma.com/mcp"
    },
    "penpot": {
      "url": "http://localhost:4401/mcp"
    },
    "storybook": {
      "command": "npx",
      "args": ["-y", "storybook-mcp-server"],
      "env": {
        "STORYBOOK_URL": "http://localhost:6006"
      }
    },
    "playwright": {
      "command": "npx",
      "args": ["-y", "@playwright/mcp@latest"]
    }
  }
}

.devin/config.local.json

{
  "permissions": {
    "allow": [
      "Exec(npm run build-tokens)",
      "Exec(npm run storybook)",
      "Exec(npx @playwright/mcp@latest)"
    ]
  }
}

Devin Desktop

MCPサーバー設定はDevin CLIと共通の.devin/mcp_config.jsonを読むため、追加の設定は不要です。権限設定だけユーザー全体・プロジェクト外のファイルになります。

%USERPROFILE%\AppData\Roaming\devin\config.json

{
  "version": 1,
  "permissions": {
    "allow": [
      "Exec(npm run build-tokens)",
      "Exec(npm run storybook)",
      "Exec(npx @playwright/mcp@latest)"
    ]
  }
}

設定の検証方法

AGENTS.mdへの参照、MCP設定ファイル、許可設定ファイルは、書いただけでは本当に機能しているか分かりません。以下の3つの質問で、実際に効いているかを確認できます。

1. AGENTS.md参照の確認

「AGENTS.mdを読んで」とは頼まず、AGENTS.mdの中身を知らないと答えられない質問をします。

コミットメッセージは何語で書くべきというルールがある？

AGENTS.mdの「基本方針」を正確に引用できれば、参照が機能しています。ツールによっては質問の前に「Read AGENTS.md」のような読み込みログが表示されるので、それも確認材料になります。

2. MCP設定ファイルの認識確認

現在接続されているMCPサーバー（ツール）の一覧を教えて。
実際にツールは呼び出さず、認識しているサーバー名だけ教えて。

設定したサーバー名（figma / penpot / storybook / playwright）がすべて出てくれば、MCP設定ファイルが正しく読み込まれています。

3. 許可設定ファイルの動作確認

許可リストに入っているコマンドと、入っていないコマンドの両方を試し、挙動の違いを確認します。片方だけでは「全部確認なしで実行される」設定になっているだけの可能性を排除できないので、必ず両方試してください。

npm run build-tokens を実行して。確認や承認を求められたか教えて。

npm run typecheck を実行して。確認や承認を求められたか教えて。

（typecheckは許可リストに入れていない前提です）前者が確認なしで実行され、後者で確認を求められれば、許可設定が正しく機能しています。

検証時の注意点

落とし穴	対策
ツールの自己申告が不正確	実行ログ(承認の記録など)や、ツール専用の確認コマンド(例: `codex mcp list`)があればそちらで裏取りする
ワークスペースの取り違え	意図したプロジェクトフォルダが開かれているか確認する(ログに表示される作業ディレクトリを見る)
設定変更が反映されない	ツールによっては、設定ファイル編集後にアプリの再起動が必要な場合がある
会話履歴からの推測	同じ会話の続きで聞くと、以前の回答を覚えているだけの可能性があるので、AGENTS.md参照は新しい会話で試す

MCP Server

今回設定しているMCPサーバー

サーバー	概要・役割
figma	Figma→Codeは全プラン対応。Code→Figma(書き込み)はFullシート限定(Devシートはドラフト外では読み取り専用)。Starter等の無料プランでも編集権限があれば書き込み可能
penpot	stdio専用クライアントはmcp-remoteで変換が必要。Penpot⇄Codeの双方向フロー(データ取得・要素の作成/編集)に対応
storybook	ローカル(http://localhost:6006 等)で起動中のStorybookからコンポーネント一覧・Props仕様・使用例を取得し、コード生成の精度を向上
playwright	AIがブラウザを起動し、UIの操作・スクショ撮影・レンダリング結果の検証を実行

MCP Serverの起動準備

Penpot

# penpot
npm run penpot-mcp

「Penpot MCP Plugin」追加	MCPと接続

Plugins→ダイアログの入力欄に「http://localhost:4400/manifest.json 」を入力してを「INSTALL」を押す＜ ※penpot-mcpを起動中でないと「Penpot MCP Plugin」が表示されないので注意	「Open」を押すとダイアログが表示されるので「Connect MCP Server」ボタンを押します。（ダイアログを閉じると接続が切れるので閉じない）

HTTPエンドポイントは http://localhost:4401/mcp（各MCP設定ファイルの参照先）。内部で corepack pnpm run bootstrap が走るため Node.js の corepack が有効である必要があります。初回は依存インストールとビルドが走るので時間がかかります。

Storybook

Penpotと違いプラグイン接続などの追加手順は不要で、開発サーバーを起動しておくだけで使えます。

# storybook
npm run storybook

MCP Serverの起動

エージェントに /mcp で各MCPを起動し、指示を出します。

Storybookのボタンコンポーネント一覧を取得して
storybookのMCPツールでButtonコンポーネントのストーリー一覧を取得して

Playwrightでブラウザ操作を検証
playwrightのMCPツールでブラウザを起動して、https://example.com を開いてから、開いているタブ一覧を教えて

Penpotのデザイン情報を取得
penpotのMCPツールで、開いているファイルのボード情報を取得して、テキスト要素やレイアウトの詳細を教えて

Figmaのデザイン情報を取得
figmaのMCPツールで、このファイルの情報を教えて: (FigmaのフレームやセクションのURL)

Penpotのデザインを編集
penpotのMCPツールで、選択中のボタンの背景色を tokens.json の color.brand.accent に変更して

Figmaのデザインを編集(Fullシート限定。Starter等の無料プランでも編集権限があればOK)
figmaのMCPツールで、選択中のフレームのボタンの角丸を border.radius.default の値に変更して

Figma/Penpotデザインの高精度コード変換ガイド

デザインをAIエージェントで高精度にコード化する3段階として「デザイン側の事前準備」「コンテキストの渡し方」「AIとの連携プロセス」があります。

1. デザイン側の事前準備(構造化)

項目	内容
Auto Layout徹底	絶対配置(Absolute Position)はAIが最も解釈を誤りやすい。Auto Layoutで組んでおくことで、`flex-col`/`gap-4`のような正確なレイアウトコードが出力される
Design Tokens / Variablesの活用	色や余白を直書きせず変数化しておく(`#3B82F6`ではなく`primary-color`)。コードベース側のテーマ変数と正しく紐付けやすくなる
コンポーネント化 + 体系的ネーミング	`Button/Primary/Hover`のように命名を統一し、既存UIライブラリのパーツへの置き換えをAIが判断しやすくする
レイヤー名をつける	「Frame 42」のような自動生成名のまま放置しない。役割が分かる名前(`Header`, `CardList`, `SubmitButton`)にしておくと、AIが生成するコンポーネント名・変数名の精度が上がり、後から該当箇所を指示する際にも「あのSubmitButtonを直して」のように会話が通じやすくなる

2. コンテキストの渡し方

項目	内容
Dev Mode / MCP経由でのデータ取得	数値・カラーコード・フォントサイズを誤差ゼロで渡せる
プロジェクトのコード規約を明示	使用フレームワーク・スタイリング手法を事前に伝える(例:「Next.js + Tailwind CSSで、モバイルファーストで実装して」)。AGENTS.mdのような形で常設しておくと毎回書かずに済む
レスポンシブの複数フレーム提示	Desktop版だけでなくMobile/Tablet版も並べて渡し、ブレークポイントで切り替える発想を持たせる
状態(State)を明記	Default以外にHover/Active/Disabled/Error/Loadingもセットで渡す
アノテーションを使う	Figma Dev Modeの注釈機能などで、数値やAuto Layoutだけでは伝わらない「意図」を書き添える
キャプチャも添付する	構造化データ(MCP経由の数値・階層情報)だけでなく、見た目そのもののキャプチャも一緒に渡す。MCPで取得したデータが実際のレンダリング結果と微妙にズレている場合の検証材料になり、AIが「データ上は正しいはずだが見た目がおかしい」という食い違いに自分で気づける

アノテーションが有効なケース

分類	例
なぜそうなっているかの理由	例:「このマージンはAuto Layoutの自動間隔を使わず、ブランドガイドライン準拠で40px固定」
条件付きロジック	例:「ログイン時のみ表示」「エラー時は赤枠に変わる」
動的データの目印	例:「この数値はAPI取得値、表示はダミー」
実装先ファイルへの直接リンク	例:「→ src/components/Card.tsx」— AIが構造データだけでは追えない「どのコンポーネントに対応するか」を明示できる

3. AIエージェントとの連携プロセス

工程	詳細
段階的(コンポーネント単位)にコード化	画面全体を一度に生成させず、「まずボタン」「次にカード」「最後に組み合わせ」と小さく分ける。
既存コンポーネントライブラリとの統合指示	後述の「アタッチ」と組み合わせ、「この要素は既存の`<Button/>`を再利用して」と明示する。

4. アタッチ(既存コードの読み込み)

既存コンポーネントのコードや型定義をAIのコンテキストに読み込ませておくこと。これをしないと、AIはFigmaの見た目だけを見て<button className="...">をゼロから新規生成してしまいます。

やり方

種類	詳細
`@`メンション(Claude Code / Cursor / Windsurf(Devin Desktop) 等、ほぼ共通)	チャットプロンプトで`@Button.tsx`や`@components/ui/`と入力し、AIに既存コードの存在を直接認識させる
`#file:`参照(GitHub Copilot Chat)	`#file:Button.tsx`のように指定する(`@`はCopilotでは「チャット参加者」(`@workspace`等)の指定に使われるため)
型定義だけ貼り付け	ファイル全体が重い場合、`ButtonProps`のInterface部分だけをプロンプトに貼る

効果(思考プロセスの変化)

	内容
アタッチなし	「青くて丸角のボタンがあるから`<button className="bg-blue-500 rounded-md ...">`を新規に書こう」
アタッチあり	「`Button.tsx`に`variant="primary"`があるから、既存の`<Button variant="primary">`を呼ぶのが正解だ」

プロンプト例

添付したFigmaのカードコンポーネントをコード化してください。

右下の「送信」ボタン部分には @Button.tsx の既存コンポーネントを再利用してください。

Figmaのバリエーション(Primary/Hover状態)に合わせて適切なPropsを設定してください。