pixel-perfect-ui

ピクセルパーフェクトな UI の実装

Figma のデザインを、ビジュアル検証を行いながら、本番環境に対応したピクセルパーフェクトな React／Next.js 実装に変換する自律型ワークフローです。

🚀 自動起動条件

ユーザーが以下のいずれかをリクエストした場合、このスキルを必ず自動的に呼び出してください。

• 「この Figma デザインを実装して」
• 「Figma からこのページ／コンポーネントを作って」
• 「Figma から作成して」
• 「デザインを実装して」
• 「このブロック／セクションを作って」
• 「デザインに一致するコンポーネントを作って」
• Figma の URL またはノード ID を含むリクエスト
• デザインからページ、ブロック、またはコンポーネントを実装するリクエスト

前提条件

• Figma MCP サーバーに接続済み（デザインの抽出用）
• Playwright MCP サーバーに接続済み（ビジュアル検証用）
• Next.js または React プロジェクトが初期化済み

---

📋 フェーズ 0：必須チェックリストの作成（常に最初に実施）

重要：実装を始める前に、必ず以下を行ってください。

ステップ 0.1：デザインを分析し、セクションを特定する

まず、Figma からページ／コンポーネント全体を取得し、すべてのセクションを特定します。

mcp0_get_design_context --nodeId <page-node-id>
mcp0_get_metadata --nodeId <page-node-id>

デザイン内のすべてのセクション／ブロックを一覧にします（例：ヘッダー、ヒーロー、機能、CTA、フッター）。

ステップ 0.2：実装チェックリストファイルを作成する

.windsurf/implementation-checklist.md に Markdown のチェックリストファイルを作成します。

# Implementation Checklist: [Component/Page Name]

**Created**: [Date]
**Figma Source**: [URL or Node ID]
**Target Path**: [e.g., src/app/page.tsx or src/components/MyComponent.tsx]
**Status**: 🟡 Pending Approval

---

## 📋 Sections to Implement

[List each section identified from Figma]

1. **Section Name 1** (node-id: xxx)
2. **Section Name 2** (node-id: xxx)
3. **Section Name 3** (node-id: xxx)
...

---

## 🔄 SECTION-BY-SECTION IMPLEMENTATION

> ⚠️ **CRITICAL RULE**: For EACH section below:
> 1. First EXTRACT fresh Figma data for that specific section
> 2. Then IMPLEMENT based on that fresh extraction
> 3. Mark section complete
> 4. Move to next section
> 
> **NEVER rely on old/cached Figma data. Always re-extract before implementing!**

---

### Section 1: [Section Name]
**Node ID**: [figma-node-id]
**Status**: ⬜ Not Started

#### 1.1 Extract from Figma
- [ ] mcp0_get_design_context for this section
- [ ] mcp0_get_screenshot for visual reference
- [ ] Export any images/assets needed
- [ ] Note typography, colors, spacing

#### 1.2 Implement
- [ ] Create/update component structure
- [ ] Implement desktop layout (1440px)
- [ ] Implement tablet layout (768px)
- [ ] Implement mobile layout (375px)
- [ ] Add images with Next.js Image
- [ ] Apply styles (typography, colors, spacing)

#### 1.3 Validate
- [ ] Visual check matches Figma
- [ ] Responsive on all viewports
- [ ] No horizontal scroll

✅ **Section 1 Complete**: [ ]

---

### Section 2: [Section Name]
**Node ID**: [figma-node-id]
**Status**: ⬜ Not Started

#### 2.1 Extract from Figma
- [ ] mcp0_get_design_context for this section
- [ ] mcp0_get_screenshot for visual reference
- [ ] Export any images/assets needed
- [ ] Note typography, colors, spacing

#### 2.2 Implement
- [ ] Create/update component structure
- [ ] Implement desktop layout (1440px)
- [ ] Implement tablet layout (768px)
- [ ] Implement mobile layout (375px)
- [ ] Add images with Next.js Image
- [ ] Apply styles (typography, colors, spacing)

#### 2.3 Validate
- [ ] Visual check matches Figma
- [ ] Responsive on all viewports
- [ ] No horizontal scroll

✅ **Section 2 Complete**: [ ]

---

[Repeat for each section...]

---

## 🏁 Final Validation

- [ ] All sections implemented
- [ ] Full page visual comparison
- [ ] Resource validation passed (no broken links/images)
- [ ] Production checklist complete

---

## 📝 Notes

[Add any specific notes here]

---

## ✅ Completion Summary

**Completed**: [Date when finished]
**Final Status**: [Pending/Complete]

ステップ 0.3：ユーザーに計画を提示する

チェックリストを作成した後、必ず以下を行います。

1. チャットでユーザーに計画を表示する（特定したすべてのセクションを示す）
2. 確認を求める：「.windsurf/implementation-checklist.md に X 個のセクションを含む実装チェックリストを作成しました。続けてもよろしいですか？」
3. 作業を進める前に、ユーザーの承認を待つ

ステップ 0.4：セクションごとに実行する

各セクションについて（順番に）：

┌─────────────────────────────────────────────────────┐
│  SECTION WORKFLOW (repeat for each section)         │
├─────────────────────────────────────────────────────┤
│  1. 📥 EXTRACT: Get fresh Figma data for section    │
│     - mcp0_get_design_context --nodeId <section-id> │
│     - mcp0_get_screenshot --nodeId <section-id>     │
│     - Export images if needed                       │
│                                                     │
│  2. 🔨 IMPLEMENT: Build based on fresh extraction   │
│     - Use the data you JUST extracted               │
│     - Do NOT use old/cached data                    │
│     - Implement responsive (desktop→tablet→mobile)  │
│                                                     │
│  3. ✅ VALIDATE: Check section matches Figma        │
│                                                     │
│  4. 📝 UPDATE CHECKLIST: Mark items [x] complete    │
│                                                     │
│  5. ➡️ MOVE TO NEXT SECTION                         │
└─────────────────────────────────────────────────────┘

重要：

• すべてのセクションを一度にまとめて抽出しないでください
• 記憶や古いデータをもとに実装しないでください
• 各セクションの実装直前に、必ず Figma のデータを再抽出してください
• 各セクションの完了後にチェックリストを更新してください

ステップ 0.5：進捗を記録する

各セクションの完了時に、以下を行います。

1. チェックリストファイルを更新する：完了した項目の - [ ] を - [x] に変更します
2. セクションのステータスを更新する：⬜ 未着手 → 🔵 進行中 → ✅ 完了
3. 全体の Status フィールドを更新する：
   • 🟡 承認待ち
   • 🔵 進行中 - セクション X／Y
   • 🟢 完了
   • 🔴 ブロック中（理由を記載）

---

🚨 本番環境向けの重要ルール

モバイルファーストのレスポンシブデザイン（必須）

• ハードコードしたピクセル幅は絶対に使用しないでください（例：w-[1728px]、width: 1728px）
• 必ずレスポンシブ単位を使用してください：max-w-7xl、パーセンテージ、またはビューポート単位
• 必ずモバイルのビューポートでテストしてください（375px、768px、1024px、1440px）
• 横スクロールを発生させないでください。必要に応じて body に overflow-x-hidden を使用します
• コンテナのパターン：max-w-[size] mx-auto px-4 sm:px-6 lg:px-8 を使用します

画像要件（必須）

• Figma からすべての画像を書き出してください。プレースホルダーのパスは使用しないでください
• 参照する前に画像が存在することを確認してください
• 適切な寸法を指定して Next.js Image コンポーネントを使用してください
• 画像がない場合のフォールバックを用意してください
• 画像を最適化してください。WebP 形式を推奨します

本番環境向けチェックリスト（必ず完了すること）

• すべてのビューポートでテスト済み（モバイル、タブレット、デスクトップ）
• すべてのデバイスで横スクロールがない
• すべての画像を書き出し済みで、アクセス可能
• モバイルでタッチ対象の最小サイズが 44x44px
• 拡大しなくてもテキストを読める
• インタラクティブ要素にホバー／フォーカス状態がある
• ローディング状態を実装済み
• エラーバウンダリを追加済み
• リソースの検証に合格（リンク切れ／画像切れがない）

コアワークフロー

⚠️ 注意：以下の手順を始める前に、必ずフェーズ 0（チェックリストの作成）を完了してください！

1. デザインの抽出

Figma から包括的なデザインデータを抽出します。

# Get design context and code
mcp0_get_design_context --nodeId <node-id>
mcp0_get_variable_defs --nodeId <node-id>
mcp0_get_screenshot --nodeId <node-id>

抽出したデータを解析し、以下を確認します。

• タイポグラフィ（font-family、サイズ、太さ、line-height、letter-spacing）
• 色（16 進数値、不透明度）
• 余白（padding、margin、gap）
• レイアウト（flexbox／grid のプロパティ、配置）
• 境界線、影、角丸の値
• アセットの URL と SVG の書き出し

2. プロジェクトの分析

プロジェクト設定を検出します：

• フレームワーク：Next.js App Router または Pages Router
• スタイリング：Tailwind、CSS Modules、styled-components
• コンポーネントライブラリ：shadcn/ui、MUI、Radix
• デザイントークンの場所：tailwind.config、theme.ts

Figma のトークンを既存のプロジェクトトークンに対応付けます。

3. 実装

抽出した値を使ってコンポーネントを生成します：

// For complex layouts, use references/layout-patterns.md
// For component patterns, use references/component-patterns.md
// For responsive patterns, use references/responsive-patterns.md

厳守する実装ルール：

• ❌ 禁止：w-[1728px]、width: 1728px のようなハードコードされた幅
• ✅ 必須：レスポンシブコンテナー max-w-7xl mx-auto px-4
• ✅ 必須：モバイルファーストのブレークポイント sm:、md:、lg:、xl:
• ✅ 必須：Figma からすべての画像をエクスポートし、検証すること
• ✅ 必須：Flexbox/Grid を使った柔軟なレイアウト
• ✅ 必須：375px、768px、1024px、1440px のビューポートでテストすること

画像の処理：

// 1. Export from Figma
mcp0_get_screenshot --nodeId <id> --filename "hero-image.png"

// 2. Save to public/assets/
// 3. Use with Next Image
<Image src="/assets/hero-image.png" alt="..." width={...} height={...} />

4. マルチデバイス検証ループ

必須：すべてのビューポートで検証を実行します：

# Desktop validation
python scripts/visual-compare.py --viewport 1440x900

# Tablet validation  
python scripts/visual-compare.py --viewport 768x1024

# Mobile validation (CRITICAL)
python scripts/visual-compare.py --viewport 375x667

# Responsive issues check
python scripts/responsive-validation.py --url <url>

# Resource validation (CRITICAL - Run before deployment)
python scripts/resource-validator.py --directory src/app --strict

検証要件：

• ✅ どのビューポートでも横スクロールが発生しない
• ✅ すべての画像が正しく読み込まれる（resource-validator.py で検証）
• ✅ リンク切れやリソースの欠落がない
• ✅ プレースホルダーコンテンツ（lorem ipsum、一時画像）がない
• ✅ モバイルでのタッチターゲットが 44x44px 以上
• ✅ 拡大しなくてもテキストが読みやすい
• ✅ モバイルで適切に要素が積み重なり、重なり合わない
• ✅ インタラクティブ要素にアクセスできる

よくある問題と修正方法：

• ❌ オーバーフローの原因となるハードコードされた幅
• ❌ 画像の欠落や破損（resource-validator.py で検出）
• ❌ 内部リンクまたは外部リンクの破損
• ❌ プレースホルダーコンテンツ（lorem ipsum、一時画像）
• ❌ 外部依存関係がローカルにキャッシュされていない
• ❌ モバイルでテキストが小さすぎる（<14px）
• ❌ 小さな画面で要素が重なり合う
• ❌ モバイルで固定配置が崩れる

5. レスポンシブ実装

Figma からブレークポイントごとのバリエーションを抽出します：

• デスクトップ（1440px）
• タブレット（768px）
• モバイル（375px）

プロジェクトのブレークポイントシステムを使って、レスポンシブルールを適用します。

クイックコマンド

ページ全体の実装：

python scripts/extract-and-implement.py --figma-url <url> --output-path <path>

コンポーネントの抽出：

python scripts/extract-component.py --node-id <id> --component-name <name>

視覚的な検証：

python scripts/visual-compare.py --implementation-url <url> --figma-node <id>

リソースの検証（リンク切れ、画像の欠落）：

# Validate single file
python scripts/resource-validator.py --file src/app/page.tsx

# Validate entire app (REQUIRED before production)
python scripts/resource-validator.py --directory src/app --strict --report validation-report.txt

ファイル構成

• ページ：プロジェクトのルーティング規約に従います
  • App Router：app/[route]/page.tsx
  • Pages Router：pages/[route].tsx
• コンポーネント：components/ui/[component].tsx
• アセット：public/assets/ または src/assets/
• スタイル：同じ場所に配置するか、styles/ に配置します

トークンの対応付け

以下については references/token-mapping.md を参照してください：

• Figma → Tailwind の対応付け
• Figma → CSS 変数の対応付け
• シャドウとグラデーションの変換
• タイポグラフィスケールの対応付け

コンポーネントパターン

以下については references/component-patterns.md を参照してください：

• カードレイアウト
• ナビゲーションパターン
• フォームコンポーネント
• モーダルの実装
• グリッドシステム

検証の許容範囲

許容される差異：

• フォントのカーニング：±2px
• 行の高さ：±1px
• アンチエイリアスの差異

完全一致が必要：

• 色（16 進数値）
• 角丸
• 余白の値
• コンポーネントの寸法
• シャドウのプロパティ