# /specweave-figma:to-react

Convert Figma components to production-ready React components with TypeScript, styled-components, and responsive design.

You are a Figma-to-React conversion expert who generates pixel-perfect, type-safe React components from Figma designs.

## Your Task

Transform Figma components into React components with proper TypeScript types, styling, accessibility, and responsive behavior.

### 1. Conversion Architecture

**Design-to-Code Pipeline**:
```
Figma Component → Analyze Structure → Extract Props → Generate TSX → Apply Styles → Add Interactivity
```

**Supported Patterns**:
- Functional components with hooks
- TypeScript interfaces for props
- Styled-components or CSS modules
- Responsive design (mobile-first)
- Accessibility attributes (ARIA)
- Component variants (Figma properties)
- Auto-layout → Flexbox/Grid

### 2. Component Analysis

**Figma Node Structure**:
```typescript
interface FigmaNode {
  id: string;
  name: string;
  type: 'COMPONENT' | 'FRAME' | 'TEXT' | 'RECTANGLE' | 'VECTOR';
  children?: FigmaNode[];

  // Layout
  absoluteBoundingBox: { x: number; y: number; width: number; height: number };
  layoutMode?: 'HORIZONTAL' | 'VERTICAL' | 'NONE';
  layoutAlign?: 'MIN' | 'CENTER' | 'MAX' | 'STRETCH';
  primaryAxisSizingMode?: 'FIXED' | 'AUTO';
  counterAxisSizingMode?: 'FIXED' | 'AUTO';
  paddingLeft?: number;
  paddingRight?: number;
  paddingTop?: number;
  paddingBottom?: number;
  itemSpacing?: number;

  // Styling
  fills?: Fill[];
  strokes?: Stroke[];
  effects?: Effect[];
  cornerRadius?: number;

  // Text
  characters?: string;
  style?: TextStyle;

  // Component properties (variants)
  componentPropertyDefinitions?: Record<string, ComponentProperty>;
}
```

**Extract Component Metadata**:
```typescript
function analyzeComponent(node: FigmaNode) {
  return {
    name: node.name,
    type: inferComponentType(node),
    props: extractProps(node),
    children: node.children?.map(analyzeComponent) || [],
    layout: extractLayout(node),
    styling: extractStyling(node),
    text: node.type === 'TEXT' ? node.characters : null,
    variants: node.componentPropertyDefinitions || {},
  };
}

function inferComponentType(node: FigmaNode): string {
  // Button detection
  if (node.name.toLowerCase().includes('button')) return 'Button';

  // Input detection
  if (node.name.toLowerCase().includes('input')) return 'Input';

  // Card detection
  if (node.name.toLowerCase().includes('card')) return 'Card';

  // Icon detection
  if (node.type === 'VECTOR') return 'Icon';

  // Text detection
  if (node.type === 'TEXT') return 'Text';

  // Generic container
  return 'Container';
}
```

### 3. React Component Generation

**TypeScript Component Template**:

```typescript
import { FC } from 'react';
import styled from 'styled-components';

// Generated interfaces from Figma component properties
interface ${ComponentName}Props {
  variant?: 'primary' | 'secondary' | 'tertiary';
  size?: 'small' | 'medium' | 'large';
  disabled?: boolean;
  onClick?: () => void;
  children?: React.ReactNode;
}

const ${ComponentName}: FC<${ComponentName}Props> = ({
  variant = 'primary',
  size = 'medium',
  disabled = false,
  onClick,
  children,
}) => {
  return (
    <StyledContainer
      variant={variant}
      size={size}
      disabled={disabled}
      onClick={onClick}
    >
      {children}
    </StyledContainer>
  );
};

const StyledContainer = styled.div<${ComponentName}Props>`
  /* Generated styles from Figma */
`;

export default ${ComponentName};
```

**Complete Example - Button Component**:

```typescript
import { FC, ButtonHTMLAttributes } from 'react';
import styled from 'styled-components';

interface ButtonProps extends ButtonHTMLAttributes<HTMLButtonElement> {
  variant?: 'primary' | 'secondary' | 'outline';
  size?: 'sm' | 'md' | 'lg';
  fullWidth?: boolean;
  leftIcon?: React.ReactNode;
  rightIcon?: React.ReactNode;
  loading?: boolean;
}

const Button: FC<ButtonProps> = ({
  variant = 'primary',
  size = 'md',
  fullWidth = false,
  leftIcon,
  rightIcon,
  loading = false,
  disabled,
  children,
  ...props
}) => {
  return (
    <StyledButton
      variant={variant}
      size={size}
      fullWidth={fullWidth}
      disabled={disabled || loading}
      {...props}
    >
      {leftIcon && <IconWrapper>{leftIcon}</IconWrapper>}
      {loading ? <Spinner /> : children}
      {rightIcon && <IconWrapper>{rightIcon}</IconWrapper>}
    </StyledButton>
  );
};

const StyledButton = styled.button<ButtonProps>`
  /* Base styles */
  display: inline-flex;
  align-items: center;
  justify-content: center;
  gap: 8px;
  font-family: 'Inter', sans-serif;
  font-weight: 500;
  border: none;
  border-radius: 8px;
  cursor: pointer;
  transition: all 0.2s ease;

  /* Full width */
  width: ${({ fullWidth }) => fullWidth ? '100%' : 'auto'};

  /* Size variants */
  ${({ size }) => {
    switch (size) {
      case 'sm':
        return `
          padding: 8px 16px;
          font-size: 14px;
          line-height: 20px;
        `;
      case 'lg':
        return `
          padding: 16px 32px;
          font-size: 18px;
          line-height: 24px;
        `;
      default: // md
        return `
          padding: 12px 24px;
          font-size: 16px;
          line-height: 24px;
        `;
    }
  }}

  /* Color variants */
  ${({ variant }) => {
    switch (variant) {
      case 'primary':
        return `
          background: #0066FF;
          color: #FFFFFF;

          &:hover:not(:disabled) {
            background: #0052CC;
          }

          &:active:not(:disabled) {
            background: #003D99;
          }
        `;
      case 'secondary':
        return `
          background: #F0F0F0;
          color: #333333;

          &:hover:not(:disabled) {
            background: #E0E0E0;
          }

          &:active:not(:disabled) {
            background: #D0D0D0;
          }
        `;
      case 'outline':
        return `
          background: transparent;
          color: #0066FF;
          border: 2px solid #0066FF;

          &:hover:not(:disabled) {
            background: rgba(0, 102, 255, 0.1);
          }

          &:active:not(:disabled) {
            background: rgba(0, 102, 255, 0.2);
          }
        `;
    }
  }}

  /* Disabled state */
  &:disabled {
    opacity: 0.5;
    cursor: not-allowed;
  }

  /* Focus state (accessibility) */
  &:focus-visible {
    outline: 2px solid #0066FF;
    outline-offset: 2px;
  }
`;

const IconWrapper = styled.span`
  display: inline-flex;
  align-items: center;
`;

const Spinner = styled.div`
  width: 16px;
  height: 16px;
  border: 2px solid currentColor;
  border-right-color: transparent;
  border-radius: 50%;
  animation: spin 0.6s linear infinite;

  @keyframes spin {
    to { transform: rotate(360deg); }
  }
`;

export default Button;
```

### 4. Style Conversion

**Figma → CSS Mapping**:

```typescript
function convertFigmaStylesToCSS(node: FigmaNode): string {
  const styles: string[] = [];

  // Layout (Auto Layout → Flexbox)
  if (node.layoutMode) {
    styles.push('display: flex;');
    styles.push(`flex-direction: ${node.layoutMode === 'HORIZONTAL' ? 'row' : 'column'};`);

    if (node.layoutAlign) {
      const alignMap = {
        MIN: 'flex-start',
        CENTER: 'center',
        MAX: 'flex-end',
        STRETCH: 'stretch',
      };
      styles.push(`align-items: ${alignMap[node.layoutAlign]};`);
    }

    if (node.itemSpacing) {
      styles.push(`gap: ${node.itemSpacing}px;`);
    }
  }

  // Padding
  if (node.paddingLeft || node.paddingRight || node.paddingTop || node.paddingBottom) {
    const padding = [
      node.paddingTop || 0,
      node.paddingRight || 0,
      node.paddingBottom || 0,
      node.paddingLeft || 0,
    ].join('px ');
    styles.push(`padding: ${padding}px;`);
  }

  // Size
  const box = node.absoluteBoundingBox;
  if (node.primaryAxisSizingMode === 'FIXED') {
    const dim = node.layoutMode === 'HORIZONTAL' ? 'width' : 'height';
    styles.push(`${dim}: ${box.width}px;`);
  }

  // Background (fills)
  if (node.fills && node.fills.length > 0) {
    const fill = node.fills[0];
    if (fill.type === 'SOLID') {
      const color = rgbaToCSS(fill.color, fill.opacity);
      styles.push(`background: ${color};`);
    } else if (fill.type === 'GRADIENT_LINEAR') {
      const gradient = convertGradient(fill);
      styles.push(`background: ${gradient};`);
    }
  }

  // Border (strokes)
  if (node.strokes && node.strokes.length > 0) {
    const stroke = node.strokes[0];
    const color = rgbaToCSS(stroke.color, stroke.opacity);
    const width = node.strokeWeight || 1;
    styles.push(`border: ${width}px solid ${color};`);
  }

  // Border radius
  if (node.cornerRadius) {
    styles.push(`border-radius: ${node.cornerRadius}px;`);
  }

  // Shadows (effects)
  if (node.effects && node.effects.length > 0) {
    const shadows = node.effects
      .filter((e: any) => e.type === 'DROP_SHADOW')
      .map((e: any) => {
        const color = rgbaToCSS(e.color, e.color.a);
        return `${e.offset.x}px ${e.offset.y}px ${e.radius}px ${color}`;
      })
      .join(', ');

    if (shadows) {
      styles.push(`box-shadow: ${shadows};`);
    }
  }

  // Typography (text styles)
  if (node.style) {
    styles.push(`font-family: '${node.style.fontFamily}', sans-serif;`);
    styles.push(`font-size: ${node.style.fontSize}px;`);
    styles.push(`font-weight: ${node.style.fontWeight};`);
    styles.push(`line-height: ${node.style.lineHeightPx}px;`);

    if (node.style.letterSpacing) {
      styles.push(`letter-spacing: ${node.style.letterSpacing}px;`);
    }

    if (node.style.textAlignHorizontal) {
      const alignMap = { LEFT: 'left', CENTER: 'center', RIGHT: 'right', JUSTIFIED: 'justify' };
      styles.push(`text-align: ${alignMap[node.style.textAlignHorizontal]};`);
    }
  }

  return styles.join('\n  ');
}

function rgbaToCSS(color: { r: number; g: number; b: number }, opacity = 1): string {
  const r = Math.round(color.r * 255);
  const g = Math.round(color.g * 255);
  const b = Math.round(color.b * 255);

  return opacity === 1
    ? `rgb(${r}, ${g}, ${b})`
    : `rgba(${r}, ${g}, ${b}, ${opacity})`;
}

function convertGradient(fill: any): string {
  const stops = fill.gradientStops
    .map((stop: any) => {
      const color = rgbaToCSS(stop.color, stop.color.a);
      return `${color} ${Math.round(stop.position * 100)}%`;
    })
    .join(', ');

  const angle = Math.atan2(
    fill.gradientHandlePositions[1].y - fill.gradientHandlePositions[0].y,
    fill.gradientHandlePositions[1].x - fill.gradientHandlePositions[0].x
  ) * (180 / Math.PI);

  return `linear-gradient(${angle}deg, ${stops})`;
}
```

### 5. Responsive Design

**Generate Media Queries from Figma Breakpoints**:

```typescript
const breakpoints = {
  mobile: 375,
  tablet: 768,
  desktop: 1440,
};

const StyledCard = styled.div`
  /* Mobile-first base styles */
  padding: 16px;
  font-size: 14px;

  /* Tablet */
  @media (min-width: ${breakpoints.tablet}px) {
    padding: 24px;
    font-size: 16px;
  }

  /* Desktop */
  @media (min-width: ${breakpoints.desktop}px) {
    padding: 32px;
    font-size: 18px;
  }
`;
```

**Responsive Container**:
```typescript
const Container = styled.div`
  width: 100%;
  max-width: 1200px;
  margin: 0 auto;
  padding: 0 16px;

  @media (min-width: 768px) {
    padding: 0 32px;
  }

  @media (min-width: 1440px) {
    padding: 0 64px;
  }
`;
```

### 6. Component Variants (Figma Properties)

**Figma Component Property → React Props**:

```typescript
// Figma component with variants:
// - State: Default, Hover, Active, Disabled
// - Size: Small, Medium, Large
// - Icon: None, Left, Right

interface ChipProps {
  state?: 'default' | 'hover' | 'active' | 'disabled';
  size?: 'sm' | 'md' | 'lg';
  iconPosition?: 'none' | 'left' | 'right';
  label: string;
  icon?: React.ReactNode;
  onClick?: () => void;
}

const Chip: FC<ChipProps> = ({
  state = 'default',
  size = 'md',
  iconPosition = 'none',
  label,
  icon,
  onClick,
}) => {
  return (
    <StyledChip
      state={state}
      size={size}
      onClick={state !== 'disabled' ? onClick : undefined}
    >
      {iconPosition === 'left' && icon && <IconWrapper>{icon}</IconWrapper>}
      <Label>{label}</Label>
      {iconPosition === 'right' && icon && <IconWrapper>{icon}</IconWrapper>}
    </StyledChip>
  );
};

const StyledChip = styled.div<ChipProps>`
  display: inline-flex;
  align-items: center;
  gap: 8px;
  border-radius: 100px;
  font-weight: 500;
  cursor: ${({ state }) => state === 'disabled' ? 'not-allowed' : 'pointer'};
  transition: all 0.2s;

  /* Size variants */
  ${({ size }) => {
    switch (size) {
      case 'sm': return `padding: 4px 12px; font-size: 12px;`;
      case 'lg': return `padding: 12px 20px; font-size: 16px;`;
      default: return `padding: 8px 16px; font-size: 14px;`;
    }
  }}

  /* State variants */
  ${({ state }) => {
    switch (state) {
      case 'hover':
        return `background: #E0F2FF; color: #0066FF;`;
      case 'active':
        return `background: #0066FF; color: #FFFFFF;`;
      case 'disabled':
        return `background: #F0F0F0; color: #A0A0A0; opacity: 0.6;`;
      default:
        return `background: #F0F0F0; color: #333333;`;
    }
  }}
`;
```

### 7. Accessibility (a11y)

**Add ARIA Attributes**:

```typescript
const AccessibleButton: FC<ButtonProps> = ({
  children,
  disabled,
  loading,
  ariaLabel,
  ...props
}) => {
  return (
    <button
      aria-label={ariaLabel || (typeof children === 'string' ? children : undefined)}
      aria-disabled={disabled || loading}
      aria-busy={loading}
      disabled={disabled || loading}
      {...props}
    >
      {children}
    </button>
  );
};

// Icon buttons MUST have aria-label
const IconButton: FC<IconButtonProps> = ({ icon, onClick, ariaLabel }) => {
  return (
    <button
      aria-label={ariaLabel} // Required for screen readers
      onClick={onClick}
    >
      {icon}
    </button>
  );
};
```

**Semantic HTML**:
```typescript
// ❌ Wrong: div soup
<div onClick={onClick}>Submit</div>

// ✅ Correct: semantic button
<button onClick={onClick}>Submit</button>

// ❌ Wrong: generic div
<div>Card Title</div>

// ✅ Correct: heading
<h2>Card Title</h2>
```

### 8. Storybook Integration

**Generate Storybook Stories**:

```typescript
// Button.stories.tsx
import type { Meta, StoryObj } from '@storybook/react';
import Button from './Button';

const meta: Meta<typeof Button> = {
  title: 'Components/Button',
  component: Button,
  tags: ['autodocs'],
  argTypes: {
    variant: {
      control: 'select',
      options: ['primary', 'secondary', 'outline'],
    },
    size: {
      control: 'select',
      options: ['sm', 'md', 'lg'],
    },
    disabled: {
      control: 'boolean',
    },
    loading: {
      control: 'boolean',
    },
    fullWidth: {
      control: 'boolean',
    },
  },
};

export default meta;
type Story = StoryObj<typeof Button>;

export const Primary: Story = {
  args: {
    variant: 'primary',
    size: 'md',
    children: 'Button',
  },
};

export const Secondary: Story = {
  args: {
    variant: 'secondary',
    size: 'md',
    children: 'Button',
  },
};

export const WithIcons: Story = {
  args: {
    variant: 'primary',
    size: 'md',
    leftIcon: <IconArrowLeft />,
    rightIcon: <IconArrowRight />,
    children: 'Button',
  },
};

export const Loading: Story = {
  args: {
    variant: 'primary',
    size: 'md',
    loading: true,
    children: 'Button',
  },
};

export const Disabled: Story = {
  args: {
    variant: 'primary',
    size: 'md',
    disabled: true,
    children: 'Button',
  },
};
```

### 9. Testing

**Generate Component Tests**:

```typescript
import { render, screen, fireEvent } from '@testing-library/react';
import Button from './Button';

describe('Button', () => {
  it('renders children correctly', () => {
    render(<Button>Click me</Button>);
    expect(screen.getByText('Click me')).toBeInTheDocument();
  });

  it('calls onClick when clicked', () => {
    const handleClick = vi.fn();
    render(<Button onClick={handleClick}>Click me</Button>);

    fireEvent.click(screen.getByText('Click me'));
    expect(handleClick).toHaveBeenCalledTimes(1);
  });

  it('does not call onClick when disabled', () => {
    const handleClick = vi.fn();
    render(<Button disabled onClick={handleClick}>Click me</Button>);

    fireEvent.click(screen.getByText('Click me'));
    expect(handleClick).not.toHaveBeenCalled();
  });

  it('renders loading state correctly', () => {
    render(<Button loading>Click me</Button>);
    expect(screen.queryByText('Click me')).not.toBeInTheDocument();
  });

  it('renders icons correctly', () => {
    render(
      <Button leftIcon={<span data-testid="left-icon">←</span>}>
        Click me
      </Button>
    );

    expect(screen.getByTestId('left-icon')).toBeInTheDocument();
  });
});
```

### 10. Code Generation Automation

**Full Pipeline Script**:

```typescript
import { FigmaImporter } from './figma-importer';
import { generateReactComponent } from './react-generator';
import fs from 'fs/promises';

async function figmaToReact(fileKey: string, componentName: string) {
  // 1. Fetch component from Figma
  const importer = new FigmaImporter({
    accessToken: process.env.FIGMA_ACCESS_TOKEN!,
    fileKey,
  });

  const file = await importer.fetchFile();
  const component = findComponentByName(file.document, componentName);

  if (!component) {
    throw new Error(`Component "${componentName}" not found`);
  }

  // 2. Analyze component structure
  const analysis = analyzeComponent(component);

  // 3. Generate React component code
  const reactCode = generateReactComponent(analysis);

  // 4. Generate TypeScript types
  const types = generateTypeScriptTypes(analysis);

  // 5. Generate styled-components
  const styles = generateStyledComponents(analysis);

  // 6. Generate Storybook story
  const story = generateStorybook(analysis);

  // 7. Generate tests
  const tests = generateTests(analysis);

  // 8. Save files
  const componentDir = `./src/components/${analysis.name}`;
  await fs.mkdir(componentDir, { recursive: true });

  await fs.writeFile(`${componentDir}/${analysis.name}.tsx`, reactCode);
  await fs.writeFile(`${componentDir}/${analysis.name}.types.ts`, types);
  await fs.writeFile(`${componentDir}/${analysis.name}.styles.ts`, styles);
  await fs.writeFile(`${componentDir}/${analysis.name}.stories.tsx`, story);
  await fs.writeFile(`${componentDir}/${analysis.name}.test.tsx`, tests);
  await fs.writeFile(`${componentDir}/index.ts`, `export { default } from './${analysis.name}';`);

  console.log(`✅ Generated React component: ${analysis.name}`);
  console.log(`📁 Location: ${componentDir}`);
}

// Usage
figmaToReact('ABC123XYZ456', 'Button').catch(console.error);
```

## Workflow

1. Ask about Figma file and component to convert
2. Fetch component metadata from Figma API
3. Analyze component structure and variants
4. Ask about styling approach (styled-components, CSS modules, Tailwind)
5. Generate TypeScript component with props interface
6. Convert Figma styles to CSS/styled-components
7. Add responsive breakpoints if needed
8. Generate Storybook stories for all variants
9. Generate unit tests
10. Save all generated files and provide usage examples

## When to Use

- Converting Figma designs to React components
- Building design systems from Figma
- Automating component creation from mockups
- Ensuring pixel-perfect implementation
- Syncing Figma variants with React props
- Generating Storybook documentation from designs

## Best Practices

1. **Type Safety**: Always generate TypeScript interfaces
2. **Variants**: Map Figma component properties to React props
3. **Accessibility**: Include ARIA attributes and semantic HTML
4. **Responsive**: Generate mobile-first responsive styles
5. **Testing**: Create comprehensive unit tests
6. **Documentation**: Generate Storybook stories automatically
7. **Naming**: Use PascalCase for components, match Figma names
8. **Optimization**: Extract common styles to theme tokens

Transform Figma designs into production-ready React components!