Figma Component Sync

Skill: Figma Component Sync

This skill checks a component's implementation against its Figma design source and helps you decide which differences to accept, ignore, or implement.

When to Use

• Reviewing if a component matches its Figma design
• Auditing visual accuracy of existing components
• Updating components after Figma design changes
• Documenting known/accepted design deviations

Prerequisites

• Component must have a README.md with a Figma link in the format:

  ## Figma Source
  https://www.figma.com/design/{fileKey}/{fileName}?node-id={nodeId}&m=dev

• Figma MCP must be configured and authenticated

Workflow Overview

┌─────────────────────────────────────────────────────────────────┐
│ 1. FETCH - Get Figma design context and current component code  │
├─────────────────────────────────────────────────────────────────┤
│ 2. TRACE DEPENDENCIES - Identify internal components used       │
├─────────────────────────────────────────────────────────────────┤
│ 3. ANALYZE - Compare design vs implementation (all files)       │
├─────────────────────────────────────────────────────────────────┤
│ 4. REVIEW - User decides: implement, ignore, or accept each     │
├─────────────────────────────────────────────────────────────────┤
│ 5. APPLY - Implement approved changes                           │
├─────────────────────────────────────────────────────────────────┤
│ 6. TEST - Verify implementation matches Figma                   │
└─────────────────────────────────────────────────────────────────┘

Step-by-Step Instructions

Before starting any work, call manage_todo_list with the following items and mark each one in-progress before starting it and completed immediately after finishing:

1. Fetch Figma design context and read component source
2. Trace internal dependencies and map property ownership
3. Generate comparison report (comparison.md)
4. Present findings and prompt user for decisions
5. Apply approved changes to source files
6. Verify implementation against Figma

Step 1: Initialize Check

Given a component path (e.g., packages/client/src/components/inline-edit/EditableText):

1. Create output directory:

   .temp/component-updates/{component-name}/

2. Find and read the component's README.md to extract Figma link

3. Check parent folder for additional README.md with relevant Figma context

4. Fetch Figma design context using mcp_figma_get_design_context:

   • Extract fileKey and nodeId from the Figma URL
   • Call the MCP tool with those parameters
   • Save output to .temp/component-updates/{component-name}/figma-context.md

5. Read current component implementation:

   • Main component file (.tsx)
   • Styles if separate
   • Save analysis to .temp/component-updates/{component-name}/current-implementation.md

Step 2: Trace Dependencies

Identify internal components that may implement Figma-specified styles:

1. Parse imports from the main component file:

   • Look for imports from relative paths (e.g., ../BaseEditable, ../EditControls)
   • Ignore external packages (react, lucide-react, @/components/ui/*)

2. For each internal dependency:

   • Read the component's source code
   • Check if it has its own README.md with Figma source
   • If yes, fetch that Figma context too

3. Map Figma properties to responsible files:

   • For each Figma property (spacing, colors, shadows, etc.)
   • Determine which file's code actually implements it
   • Create a property-to-file mapping

4. Save dependency analysis to .temp/component-updates/{component-name}/dependencies.md:

   # Dependency Analysis: {ComponentName}
   
   ## Internal Dependencies
   | Component | Path | Has Figma Source? |
   |-----------|------|-------------------|
   | BaseEditable | ../BaseEditable | Yes (node 1252-9022) |
   | EditControls | ../EditControls | No |
   
   ## Property Ownership Map
   | Figma Property | Responsible File | Current Value |
   |----------------|------------------|---------------|
   | Label-Content Gap | BaseEditable.tsx | gap-1 (4px) |
   | Content Padding | BaseEditable.tsx | py-0.5 (2px) |
   | Button Shadow | EditControls.tsx | shadow-sm |
   | Input Border | EditableText.tsx | border-input |

Step 3: Generate Comparison

Create .temp/component-updates/{component-name}/comparison.md:

IMPORTANT: Only include differences and decisions. Do NOT include:

• Figma Design Summary sections
• Current Implementation Summary sections
• "Previously Matching" or "No Changes Needed" sections

# Component Comparison: {ComponentName}

> Figma: https://www.figma.com/design/...?node-id=...

## Differences

### 📁 {ComponentName}.tsx

#### 1. Border color
- **Figma:** `border-gray-300`
- **Code:** `border-input`
- **Impact:** Low

**Decision:**
- [ ] 🔧 IMPLEMENT
- [ ] ✅ ACCEPT - Reason: 
- [ ] ⏭️ SKIP

---

### 📁 BaseEditable.tsx (dependency)

#### 1. Label-Content Gap
- **Figma:** `0px` (no gap)
- **Code:** `gap-1` (4px)
- **Impact:** Medium

**Decision:**
- [ ] 🔧 IMPLEMENT
- [ ] ✅ ACCEPT - Reason: 
- [ ] ⏭️ SKIP

#### 2. Content Padding
- **Figma:** `py-2` (8px)
- **Code:** `py-0.5` (2px)
- **Impact:** Medium

**Decision:**
- [ ] 🔧 IMPLEMENT
- [ ] ✅ ACCEPT - Reason: 
- [ ] ⏭️ SKIP

---

## Previously Accepted

| Category | Figma | Code | File | Reason |
|----------|-------|------|------|--------|
| Width | fixed | `w-full` | {ComponentName}.tsx | Container flexibility |

Step 4: User Review

Prompt the user to:

1. Open the comparison.md file
2. Review each difference (grouped by file)
3. Mark decisions inline
4. Save the file

Use this prompt format:

📋 Component sync analysis complete!

Found differences in {N} files:
- {ComponentName}.tsx: {n} differences
- BaseEditable.tsx (dependency): {n} differences
- EditControls.tsx (dependency): {n} differences

Please review and make decisions:
1. Open: `.temp/component-updates/{component-name}/comparison.md`
2. For each difference, choose: IMPLEMENT, ACCEPT, or SKIP
3. Save the file
4. Tell me to apply the decisions

Step 5: Apply Decisions

After user completes review:

1. Parse the comparison.md for decisions (grouped by file)
2. For IMPLEMENT decisions:
   • Generate a technical plan per file
   • Apply code changes to each file
   • Run tests to verify
3. For ACCEPT decisions:
   • Add to the target component's README.md under "## Accepted Design Differences"
   • Include which file the deviation is in
4. For SKIP decisions:
   • Leave as-is for future review

Important: When changing dependency files (like BaseEditable), consider:

• These changes affect ALL components using that dependency
• Document the change scope in the implementation plan
• Run broader test coverage if needed