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:
  markdown

  ## 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

Step 1: Initialize Check

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

1. •

   Create output directory:

   code

   .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:

   markdown

   # 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