create-design-system-rules

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

概要

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

サポート対象のルールファイル

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

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

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

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

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

前提条件

• Figma MCP サーバーに接続でき、アクセス可能であること
  • 先に進む前に、create_design_system_rules などの Figma MCP ツールが利用可能か確認し、Figma MCP サーバーが接続されていることを検証してください。
  • ツールが利用できない場合、Figma MCP サーバーが有効になっていない可能性があります。プラグインに含まれる Figma MCP サーバーを有効にするようユーザーに案内してください。その後、MCP クライアントの再起動が必要になる場合があります。
• 分析対象となるプロジェクトのコードベースにアクセスできること
• チームのコンポーネント規約を把握していること（または規約を策定する意思があること）

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

次の場合にこのスキルを使用してください。

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

必須のワークフロー

次の手順を順番に実行してください。手順を省略しないでください。

ステップ 1：デザインシステムルール作成ツールを実行する

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]

globs パターンは、プロジェクト内で Figma 由来のコードを配置するディレクトリに合わせて調整してください（例："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 プロパティ（'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 の変数とデザイントークン