figma-create-design-system-rules

デザインシステムルールの作成

概要

このスキルを使うと、プロジェクト固有のニーズに合わせたカスタムデザインシステムルールを作成できます。これらのルールは、Figma のデザインを実装する際に、AI コーディングエージェントが一貫性のある高品質なコードを生成できるよう導きます。チームの規約、コンポーネントのパターン、アーキテクチャ上の判断が自動的に反映されます。

対応するルールファイル

エージェント	ルールファイル
Claude Code	CLAUDE.md
Codex CLI	AGENTS.md
Cursor	.cursor/rules/figma-design-system.mdc

デザインシステムルールとは

デザインシステムルールは、コードベースにある「明文化されていない知識」、つまり経験豊富な開発者が知っていて、新しいチームメンバーに伝えるような専門知識を記述した、プロジェクトレベルの指示です。

• 使用するレイアウトプリミティブとコンポーネント
• コンポーネントファイルの配置場所
• コンポーネントの命名方法と構成方法
• ハードコードしてはならないもの
• デザイントークンとスタイルの扱い方
• プロジェクト固有のアーキテクチャパターン

ルールを定義すると、繰り返し指示する手間が大幅に減り、すべての Figma 実装タスクで一貫した出力が得られます。

前提条件

• Figma MCP サーバーが接続され、アクセス可能であること
• 分析対象のプロジェクトコードベースにアクセスできること
• チームのコンポーネント規約を理解していること（または規約を策定する意思があること）

このスキルを使用するタイミング

次の場合にこのスキルを使用します。

• Figma のデザインを使用する新しいプロジェクトを開始するとき
• 確立されたパターンがある既存プロジェクトに AI コーディングエージェントを導入するとき
• チーム全体で Figma からコードへのワークフローを標準化するとき
• 既存のデザインシステムの規約を更新または調整するとき
• ユーザーから「デザインシステムルールを作成」「Figma のガイドラインを設定」「プロジェクトに合わせてルールをカスタマイズ」などの依頼があったとき

必須のワークフロー

以下の手順を順番どおりに実行してください。手順を省略しないでください。

ステップ 1：Create Design System Rules ツールを実行する

Figma MCP サーバーの create_design_system_rules ツールを呼び出し、基本となるプロンプトとテンプレートを取得します。

パラメーター：

• clientLanguages：プロジェクトで使用する言語のカンマ区切りリスト（例：「typescript,javascript」、「python」、「javascript」）
• clientFrameworks：使用するフレームワーク（例：「react」、「vue」、「svelte」、「angular」、「unknown」）

このツールは、デザインシステムルールの作成に関するガイダンスとテンプレートを返します。

ツールの応答で提示されるテンプレート形式に従って、デザインシステムルールを構成してください。

ステップ 2：コードベースを分析する

ルールを確定する前に、プロジェクトの既存パターンを把握するため、コードベースを分析します。

コンポーネントの構成：

• UI コンポーネントはどこに配置されていますか？（例：src/components/、app/ui/、lib/components/）
• 専用のデザインシステムディレクトリはありますか？
• コンポーネントはどのように構成されていますか？（機能別、種類別、フラット構造）

スタイル設定の方法：

• どの CSS フレームワークまたは手法を使用していますか？（Tailwind、CSS Modules、styled-components など）
• デザイントークンはどこで定義されていますか？（CSS 変数、テーマファイル、設定ファイル）
• 色、タイポグラフィ、余白のトークンはすでにありますか？

コンポーネントのパターン：

• どの命名規則が使われていますか？（PascalCase、kebab-case、接頭辞）
• コンポーネントのプロパティは通常どのように構成されていますか？
• 一般的な合成パターンはありますか？

アーキテクチャ上の決定事項：

• 状態管理には何を使用していますか？
• どのルーティングシステムを使用していますか？
• 特定のインポートパターンやパスエイリアスはありますか？

ステップ 3：プロジェクト固有のルールを作成する

コードベースの分析に基づいて、包括的なルールを作成します。以下を含めてください。

一般的なコンポーネントルール

- IMPORTANT: Always use components from `[YOUR_PATH]` when possible
- Place new UI components in `[COMPONENT_DIRECTORY]`
- Follow `[NAMING_CONVENTION]` for component names
- Components must export as `[EXPORT_PATTERN]`

スタイル設定のルール

- Use `[CSS_FRAMEWORK/APPROACH]` for styling
- Design tokens are defined in `[TOKEN_LOCATION]`
- IMPORTANT: Never hardcode colors - always use tokens from `[TOKEN_FILE]`
- Spacing values must use the `[SPACING_SYSTEM]` scale
- Typography follows the scale defined in `[TYPOGRAPHY_LOCATION]`

Figma MCP 連携ルール

## Figma MCP Integration Rules

These rules define how to translate Figma inputs into code for this project and must be followed for every Figma-driven change.

### Required Flow (do not skip)

1. Run get_design_context first to fetch the structured representation for the exact node(s)
2. If the response is too large or truncated, run get_metadata to get the high-level node map, then re-fetch only the required node(s) with get_design_context
3. Run get_screenshot for a visual reference of the node variant being implemented
4. Only after you have both get_design_context and get_screenshot, download any assets needed and start implementation
5. Translate the output (usually React + Tailwind) into this project's conventions, styles, and framework
6. Validate against Figma for 1:1 look and behavior before marking complete

### Implementation Rules

- Treat the Figma MCP output (React + Tailwind) as a representation of design and behavior, not as final code style
- Replace Tailwind utility classes with `[YOUR_STYLING_APPROACH]` when applicable
- Reuse existing components from `[COMPONENT_PATH]` instead of duplicating functionality
- Use the project's color system, typography scale, and spacing tokens consistently
- Respect existing routing, state management, and data-fetch patterns
- Strive for 1:1 visual parity with the Figma design
- Validate the final UI against the Figma screenshot for both look and behavior

アセットの扱い方に関するルール

## Asset Handling

- The Figma MCP server provides an assets endpoint which can serve image and SVG assets
- IMPORTANT: If the Figma MCP server returns a localhost source for an image or SVG, use that source directly
- IMPORTANT: DO NOT import/add new icon packages - all assets should be in the Figma payload
- IMPORTANT: DO NOT use or create placeholders if a localhost source is provided
- Store downloaded assets in `[ASSET_DIRECTORY]`

プロジェクト固有の規約

## Project-Specific Conventions

- [Add any unique architectural patterns]
- [Add any special import requirements]
- [Add any testing requirements]
- [Add any accessibility standards]
- [Add any performance considerations]

ステップ 4：ルールを適切なルールファイルに保存する

ユーザーが使用している AI コーディングエージェントを判別し、生成したルールを対応するファイルに保存します。

エージェント	ルールファイル	備考
Claude Code	プロジェクトルートの CLAUDE.md	Markdown 形式です。モジュールごとに整理する場合は .claude/rules/figma-design-system.md も使用できます。
Codex CLI	プロジェクトルートの AGENTS.md	Markdown 形式です。ファイルがすでにある場合は、新しいセクションとして追記します。合計サイズの上限は 32 KiB です。
Cursor	.cursor/rules/figma-design-system.mdc	YAML フロントマター（description、globs、alwaysApply）付きの Markdown です。

ユーザーが使用しているエージェントがわからない場合は、プロジェクト内に既存のルールファイルがあるか確認するか、ユーザーに尋ねてください。

Cursor の場合は、YAML フロントマターでルールを囲みます。

---
description: Rules for implementing Figma designs using the Figma MCP server. Covers component organization, styling conventions, design tokens, asset handling, and the required Figma-to-code workflow.
globs: "src/components/**"
alwaysApply: false
---

[Generated rules here]

プロジェクト内で Figma 由来のコードを配置するディレクトリに合わせて、globs パターンをカスタマイズします（例："src/**/*.tsx" または ["src/components/**", "src/pages/**"]）。

保存すると、エージェントによってルールが自動的に読み込まれ、すべての Figma 実装タスクに適用されます。

ステップ 5：検証して反復する

ルールの作成後：

1. 簡単な Figma コンポーネントの実装でテストします
2. エージェントがルールに正しく従っていることを確認します
3. 想定どおりに機能していないルールを調整します
4. チームメンバーに共有してフィードバックをもらいます
5. プロジェクトの進化に合わせてルールを更新します

ルールのカテゴリと例

必須ルール（必ず含める）

コンポーネントの検出：

- UI components are located in `src/components/ui/`
- Feature components are in `src/components/features/`
- Layout primitives are in `src/components/layout/`

デザイントークンの使用：

- Colors are defined as CSS variables in `src/styles/tokens.css`
- Never hardcode hex colors - use `var(--color-*)` tokens
- Spacing uses the 4px base scale: `--space-1` (4px), `--space-2` (8px), etc.

スタイリングの方法：

- Use Tailwind utility classes for styling
- Custom styles go in component-level CSS modules
- Theme customization is in `tailwind.config.js`

推奨ルール（非常に有用）

コンポーネントのパターン：

- All components must accept a `className` prop for composition
- Variant props should use union types: `variant: 'primary' | 'secondary'`
- Icon components should accept `size` and `color` props

インポートの規約：

- Use path aliases: `@/components`, `@/styles`, `@/utils`
- Group imports: React, third-party, internal, types
- No relative imports beyond parent directory

コード品質：

- Add JSDoc comments for exported components
- Include PropTypes or TypeScript types for all props
- Extract magic numbers to named constants

任意のルール（プロジェクト固有）

アクセシビリティ：

- All interactive elements must have aria-labels
- Color contrast must meet WCAG AA standards
- Keyboard navigation required for all interactions

パフォーマンス：

- Lazy load images with the `Image` component from `@/components/Image`
- Use React.memo for components that receive complex props
- Icons should be SVG components, not icon fonts

テスト：

- Include unit tests for new components in `__tests__/` directory
- Use Testing Library queries (getByRole, getByLabelText)
- Test all interactive states and variants

例

例 1：React + Tailwind プロジェクト

ユーザーの発言：「React プロジェクト用のデザインシステムルールを作成してください」

実行内容：

1. create_design_system_rules(clientLanguages="typescript,javascript", clientFrameworks="react") を実行します
2. コードベースの構造を分析します
3. ルールを生成します：

# Figma MCP Integration Rules

## Component Organization

- UI components are in `src/components/ui/`
- Page components are in `src/app/`
- Use Tailwind for styling

## Figma Implementation Flow

1. Run get_design_context for the node
2. Run get_screenshot for visual reference
3. Map Figma colors to Tailwind colors defined in `tailwind.config.js`
4. Reuse components from `src/components/ui/` when possible
5. Validate against screenshot before completing

## Styling Rules

- IMPORTANT: Use Tailwind utility classes, not inline styles
- Colors are defined in `tailwind.config.js` theme.colors
- Spacing uses Tailwind's default scale
- Custom components go in `src/components/ui/`

## Asset Rules

- IMPORTANT: Use localhost sources from Figma MCP server directly
- Store static assets in `public/assets/`
- DO NOT install new icon libraries

4. ユーザーのエージェントに適したルールファイルに保存します
5. 簡単なボタンの実装でテストします

結果： エージェントは Figma のデザインを実装する際、プロジェクトの規約に一貫して従うようになります。

例 2：Vue + カスタム CSS プロジェクト

ユーザーの発言：「Vue アプリ用の Figma ルールを設定してください」

実行内容：

1. create_design_system_rules(clientLanguages="typescript,javascript", clientFrameworks="vue") を実行します
2. プロジェクトで CSS モジュールとカスタムのデザイントークンシステムが使用されていることを確認します
3. ルールを生成します：

# Figma MCP Integration Rules

## Component Organization

- Components are in `src/components/`
- Composables are in `src/composables/`
- Vue SFC structure: <script setup>, <template>, <style scoped>

## Design Tokens

- IMPORTANT: All colors defined in `src/styles/tokens.css` as CSS variables
- Use `var(--color-primary)`, `var(--color-secondary)`, etc.
- Spacing: `var(--space-xs)` through `var(--space-xl)`
- Typography: `var(--text-sm)` through `var(--text-2xl)`

## Figma Implementation Flow

1. Run get_design_context and get_screenshot
2. Translate React output to Vue 3 Composition API
3. Map Figma colors to CSS variables in `src/styles/tokens.css`
4. Use CSS Modules for component styles
5. Check for existing components in `src/components/` before creating new ones

## Styling Rules

- Use CSS Modules (`.module.css` files)
- IMPORTANT: Reference design tokens, never hardcode values
- Scoped styles with CSS modules

4. ユーザーのエージェントに適したルールファイルに保存します
5. カードコンポーネントで検証します

結果： エージェントは、プロジェクトのデザイントークンシステムを使用して、Figma のデザインを Vue コンポーネントに正しく変換するようになります。

例 3：デザインシステムチーム

ユーザーの発言：「デザインシステムライブラリ用のルールを生成してください」

実行内容：

1. create_design_system_rules(clientLanguages="typescript", clientFrameworks="react") を実行します
2. デザインシステムのパッケージを含むモノレポの構造を分析します
3. 包括的なルールを生成します：

# Design System Rules

## Repository Structure

- Design system components: `packages/design-system/src/components/`
- Documentation: `packages/docs/`
- Design tokens: `packages/tokens/src/`

## Component Development

- IMPORTANT: All components must be in `packages/design-system/src/components/`
- Component file structure: `ComponentName/index.tsx`, `ComponentName.stories.tsx`, `ComponentName.test.tsx`
- Export all components from `packages/design-system/src/index.ts`

## Design Tokens

- Colors: `packages/tokens/src/colors.ts`
- Typography: `packages/tokens/src/typography.ts`
- Spacing: `packages/tokens/src/spacing.ts`
- IMPORTANT: Never hardcode values - import from tokens package

## Documentation Requirements

- Add Storybook story for every component
- Include JSDoc with @example
- Document all props with descriptions
- Add accessibility notes

## Figma Integration

1. Get design context and screenshot from Figma
2. Map Figma tokens to design system tokens
3. Create or extend component in design system package
4. Add Storybook stories showing all variants
5. Validate against Figma screenshot
6. Update documentation

4. 適切なルールファイルに保存して、チームに共有します
5. チームのドキュメントに追加します

結果： チーム全体が、Figma からデザインシステムにコンポーネントを追加する際、一貫したパターンに従うようになります。

ベストプラクティス

シンプルに始めて、反復する

最初からすべてのルールを盛り込もうとしないでください。まずは重要な規約から始め、矛盾に気づいたらルールを追加します。

具体的にする

避ける表現：「デザインシステムを使用する」 推奨する表現：「常に src/components/ui/Button.tsx の Button コンポーネントを、variant prop（'primary' | 'secondary' | 'ghost'）を指定して使用する」

実行可能なルールにする

各ルールでは、避けるべきことだけでなく、エージェントが何をすべきかを正確に伝える必要があります。

良い例：「色は src/theme/colors.ts で定義されています。これらの定数をインポートして使用してください」 悪い例：「色をハードコードしない」

重要なルールには IMPORTANT を使用する

決して違反してはならないルールには、エージェントが優先するよう「IMPORTANT:」を付けてください。

- IMPORTANT: Never expose API keys in client-side code
- IMPORTANT: Always sanitize user input before rendering

理由を説明する

ルールが恣意的に見える場合は、その理由を説明してください。

- Place all data-fetching in server components (reduces client bundle size and improves performance)
- Use absolute imports with `@/` alias (makes refactoring easier and prevents broken relative paths)

よくある問題と解決策

問題：エージェントがルールに従わない

**原因：**ルールが曖昧すぎるか、エージェントに正しく読み込まれていない可能性があります。 解決策：

• ルールをより具体的で実行可能なものにします
• ルールが正しい設定ファイルに保存されていることを確認します
• ルールを再読み込みするため、エージェントまたは IDE を再起動します
• 重要なルールに「IMPORTANT:」を付けます

問題：ルール同士が競合する

**原因：**ルールに矛盾があるか、内容が重複しています。 解決策：

• すべてのルールを確認して、競合がないか調べます
• 明確な優先順位を設定します
• 冗長なルールを削除します
• 関連するルールを、明確な一つの記述にまとめます

問題：ルールが多すぎて遅延が増える

**原因：**ルールが多すぎると、コンテキストサイズと処理時間が増加します。 解決策：

• 一貫性に関する問題の 80% を解決する 20% のルールに絞ります
• 適用されることがほとんどない、過度に具体的なルールを削除します
• 関連するルールをまとめます
• 段階的開示を活用します（基本的なルールを先に示し、高度なルールはリンク先のファイルに記載します）

問題：プロジェクトの進化に伴い、ルールが古くなる

**原因：**ルールが更新されないまま、コードベースが変更されています。 解決策：

• ルールを定期的に見直す予定を立てます（月次または四半期ごと）
• アーキテクチャ上の決定が変わったら、ルールを更新します
• ルールファイルをバージョン管理します
• コミットメッセージにルールの変更内容を記録します

デザインシステムのルールについて

デザインシステムのルールを設定すると、AI コーディングエージェントが Figma のデザインを扱う方法が変わります。

ルールを設定する前：

• エージェントがコンポーネント構造を推測します
• 実装ごとにスタイルの方法が一貫しません
• デザイントークンと一致しない値がハードコードされます
• コンポーネントがランダムな場所に作成されます
• プロジェクトの規約を繰り返し説明する必要があります

ルールを設定した後：

• エージェントが規約に自動的に従います
• コンポーネント構造とスタイルに一貫性が生まれます
• 最初からデザイントークンが適切に使用されます
• コンポーネントが正しく整理されます
• 同じ内容を繰り返し指示する必要がなくなります

適切なルールの作成にかけた時間は、Figma の実装タスクのたびに大きな効果をもたらします。

追加リソース

• Figma MCP サーバーのドキュメント
• Figma の変数とデザイントークン