figma-component-sync

name: figma-component-sync description: Check a React component against its Figma design source and identify differences. Use when reviewing component implementations, syncing designs, auditing visual accuracy, or updating components to match new Figma designs.

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

Output Files Structure

.temp/component-updates/{component-name}/
├── figma-context.md          # Raw Figma MCP output
├── dependencies.md           # Internal dependency analysis & property mapping
├── technical-comparison.md   # Side-by-side property comparison
├── decisions.md              # Grouped changes with decision checkboxes
└── implementation-plan.md    # Generated after review (if changes needed)

README.md Format for Accepted Differences

Components should document accepted differences in their README:

# ComponentName

Description...

## Figma Source

https://www.figma.com/design/...

## Accepted Design Differences

| Category | Figma | Implementation | File | Reason |
|----------|-------|----------------|------|--------|
| Width | Fixed 200px | `w-full` | EditableText.tsx | Container flexibility |
| Gap | 0px | `gap-1` (4px) | BaseEditable.tsx | Visual breathing room |
| Shadow | `shadow-lg` | `shadow-sm` | EditControls.tsx | Subtler appearance |

Dependency Detection Rules

When tracing dependencies, include a component if:

1. It's imported from a relative path within the same component family

   • ✅ import { BaseEditable } from '../BaseEditable'
   • ✅ import { EditControls } from '../EditControls'
   • ❌ import { Button } from '@/components/ui/button' (external UI lib)
   • ❌ import { cn } from '@/lib/utils' (utility, not component)

2. It renders visual elements (not just hooks or utilities)

3. It implements styling that corresponds to Figma properties:

   • Layout (flex, gap, padding, margin)
   • Colors (background, text, border)
   • Typography (font size, weight, line-height)
   • Effects (shadow, border-radius)

Property-to-File Mapping Guidelines

When determining which file "owns" a Figma property:

Example Usage

Check a single component:

Check the EditableText component against its Figma design

Check all inline-edit components:

Check all components in packages/client/src/components/inline-edit/ against their Figma designs

Apply decisions after review:

Apply the figma sync decisions for EditableText

Prompts for Follow-up Actions

After generating comparison.md, provide these follow-up prompts:

To apply changes:

@workspace Read .temp/component-updates/{component-name}/comparison.md and implement all changes marked as IMPLEMENT

To update README with accepted deviations:

@workspace Read .temp/component-updates/{component-name}/comparison.md and add all ACCEPT decisions to the component's README.md

Common Figma Properties to Check

Troubleshooting

"No Figma link found"

• Ensure README.md exists in the component folder
• Check the link format matches expected pattern

"MCP authentication failed"

• Verify Figma MCP is configured
• Run mcp_figma_whoami to check auth status

"Component not found at path"

• Verify the component path is correct
• Check for typos in component name