Sync Design System Components

Name

Synopsis

Description

Implementation

Your Task

1. Inventory Figma Components:
   • Use Figma MCP tools to list all components in the file
   • Group components by category (buttons, inputs, cards, etc.)
   • Identify component variants and properties
   • Note component descriptions and documentation
2. Inventory Code Components:
   • Scan the codebase for existing component library
   • Identify component files and their exports
   • Check for existing Code Connect configurations
   • Map components to Figma equivalents
3. Analyze Gaps:
   • Identify Figma components without code implementations
   • Identify code components without Figma designs
   • Note variant mismatches (Figma has variants code doesn't)
   • Find naming inconsistencies
4. Create Sync Plan:
   • Prioritize which components to sync first
   • Determine if generating new code or updating existing
   • Plan Code Connect mapping creation/updates
   • Identify breaking changes that need migration
5. Execute Sync: Based on user preference, either:
   • Generate missing components: Create code for Figma-only components
   • Update existing components: Align code with Figma changes
   • Create Code Connect mappings: Link existing code to Figma
   • Document discrepancies: Report on mismatches without changing code

Code Connect Integration

// Button.figma.tsx
import figma from '@figma/code-connect';
import { Button } from './Button';

figma.connect(
  Button,
  'https://www.figma.com/file/abc123?node-id=1:234',
  {
    props: {
      variant: figma.enum('Variant', {
        Primary: 'primary',
        Secondary: 'secondary',
      }),
      size: figma.enum('Size', {
        Small: 'sm',
        Medium: 'md',
        Large: 'lg',
      }),
      disabled: figma.boolean('Disabled'),
      children: figma.string('Label'),
    },
    example: ({ variant, size, disabled, children }) => (
      <Button variant={variant} size={size} disabled={disabled}>
        {children}
      </Button>
    ),
  }
);

Sync Report Format

# Design System Sync Report

Generated: [date]
Figma File: [file name and URL]
Code Location: [path to component library]

## Summary

- Total Figma Components: 45
- Total Code Components: 38
- Synced Components: 35
- Needs Generation: 10
- Needs Update: 3
- Needs Code Connect: 7

## Components Needing Action

### Generate (Figma → Code)

1. **AlertDialog**
   - Variants: Info, Warning, Error, Success
   - Props: title, message, onClose, onConfirm
   - Figma: [URL]

2. **Tooltip**
   - Variants: Top, Right, Bottom, Left
   - Props: content, trigger, delay
   - Figma: [URL]

### Update (Align Code with Figma)

1. **Button**
   - Missing variant: Ghost
   - New prop: iconPosition (left/right)
   - Action: Add variant and prop to code

### Create Code Connect

1. **Card**
   - Code exists at: src/components/Card/Card.tsx
   - Figma: [URL]
   - Action: Create Card.figma.tsx mapping

## Recommendations

1. Consolidate Button and IconButton components
2. Standardize size prop values across all components
3. Add missing documentation to Input component
4. Consider deprecating old Badge variants

Best Practices

1. Component Naming:
   • Keep names consistent between Figma and code
   • Use PascalCase for component names
   • Match variant names exactly (case-sensitive)
2. Variant Mapping:
   • Map Figma variant properties to code props
   • Handle boolean variants properly
   • Support all variant combinations
   • Provide sensible defaults
3. Documentation:
   • Sync component descriptions from Figma
   • Document prop types and accepted values
   • Include usage examples
   • Note any differences between Figma and code
4. Validation:
   • Test all generated components compile
   • Verify variants render correctly
   • Check accessibility compliance
   • Validate against design system guidelines

Workflow Options

1. Full Sync: Generate all missing components, update existing ones, create all Code Connect mappings
2. Partial Sync: Only sync specified components or categories
3. Report Only: Generate sync report without making changes
4. Code Connect Only: Only create/update Code Connect mappings for existing components

Additional Deliverables

1. Migration Guide:
   • If updating existing components, document breaking changes
   • Provide codemod scripts if possible
   • List all components affected
2. Testing Plan:
   • Visual regression test suggestions
   • Component test updates needed
   • Storybook story generation
3. Documentation Updates:
   • Updated component documentation
   • Design system guidelines
   • Usage examples

Notes

• Preserve existing component behavior unless explicitly changing
• Maintain backwards compatibility when possible
• Use design tokens from Figma variables
• Consider responsive behavior and breakpoints
• Test dark mode if supported
• Validate accessibility (WCAG AA minimum)