# Figma MCP to React + Tailwind v4 Code Generator

A demonstration of AI-powered Figma-to-code workflow using Figma MCP tools with Claude Code.

⚠️ **Important**: This is a ~20-minute starting point showcasing capabilities, NOT production-ready code.

## What This Project Demonstrates

1. **Figma MCP Workflow**: Two-phase extraction and implementation process
2. **Design Token Strategy**: Intentional duplication with user-controlled consolidation
3. **Pure UI Components**: Props-based components without business logic
4. **Parallel Generation**: Multiple components generated simultaneously with unique names

## Quick Links

- 📄 [Single URL Template](./templates/figma-mcp-single-template.md) - For unified Figma designs
- 📄 [Dual URL Template](./templates/figma-mcp-dual-template.md) - For separate desktop/mobile files

## Example Components (Capability Demonstrations)

**Design Source**: This project uses the [E-commerce UI - Figma Ecommerce UI Kit (Demo Version)](https://www.figma.com/community/file/1102233251923362930/e-commerce-ui-figma-ecommerce-ui-kit-demo-version) from the Figma community, licensed under [CC BY 4.0](https://creativecommons.org/licenses/by/4.0/). A huge thank you to the creators for this amazing open-source Figma resource with 475+ UI components and 70+ web pages.

**Modifications**: The components in this project are derivative works—React code generated from the original Figma designs, adapted with Tailwind v4 styling and custom implementations.

This project includes 8 generated ecommerce components from this Figma design system:

- **navbar-style-1/** - Responsive navbar with top bar and navigation menu
- **carousel-1/** - Hero carousel with overlay content
- **carousel-2/** - Secondary carousel component
- **product-cards/** - Product grid with card variants
- **editors-pick/** - Editorial layout grid with featured items
- **blog-3/** - Blog post cards layout
- **footer-6/** - Footer with subscribe form and social links
- **container-fluid/** - Responsive container component

**Note on naming**: Component names (e.g., "navbar-style-1", "carousel-2") are kept from the original Figma file for demonstration purposes. In real projects, use more semantic names that match your domain.

**🎯 Purpose**: These components demonstrate the workflow's capabilities and stress-test the system. They are **NOT** examples of best-practice component architecture or composition patterns.

**View them**: Run `npm run dev` - all components render on the homepage with demos.

## Getting Started with Figma MCP Workflow

### Prerequisites

- Node.js 18+ and npm
- Figma file URL with design to convert
- Claude Code or similar AI assistant with Figma MCP tools

### Step-by-Step

1. **Prepare your Figma file**:
   - Get the Figma URL with `node-id` parameter
   - Format: `https://figma.com/design/{fileKey}/{fileName}?node-id=1234-5678`
   - Ensure you have view access to the file

2. **Choose your template**:
   - **Single URL**: One Figma file with responsive frames → Use [figma-mcp-single-template.md](./templates/figma-mcp-single-template.md)
   - **Dual URL**: Separate desktop and mobile Figma files → Use [figma-mcp-dual-template.md](./templates/figma-mcp-dual-template.md)

3. **Copy the template** from `/templates/` directory

4. **Fill in your paths** (replace placeholders):
   - **Component folder path**: Where to create the component (e.g., `./app/components/my-component/`)
   - **Root CSS file path**: Path to your main CSS file (e.g., `./app/app.css`) - **MUST exist**
   - **Meta-framework**: Optional (e.g., `nextjs`, `remix`, `vite`)
   - **UI library path**: Optional (e.g., `./app/components/ui/`)

5. **Paste into Claude Code** and follow the two-phase workflow:
   - Phase 1: Extraction (assistant will save raw files)
   - Review checkpoint
   - Phase 2: Implementation (assistant will generate component)

6. **Review and refine**: Validate the generated code, test responsive behavior, add business logic

## Understanding the Generated Code

### 1. Design Token Duplication is INTENTIONAL ✨

Each component has its own namespaced design tokens in [app/app.css](app/app.css):

```css
@theme {
  /* Blog-3 Component Design Tokens */
  --color-blog-primary: #23a6f0;
  --font-size-blog-h3: 24px;

  /* Footer-6 Component Design Tokens */
  --color-footer-primary: #23a6f0;
  --font-size-footer-h3: 24px;
}
```

**Why duplicate?** The workflow doesn't assume which design tokens are truly shared across your system. **You** decide what to consolidate based on your design requirements.

**What to do next**: Review `app/app.css` and merge duplicates into a unified design system when you understand your patterns. For example, both components above use `#23a6f0` - you might consolidate this into a single `--color-brand-primary` token.

### 2. Components are Pure UI (No Business Logic) 🎨

All generated components accept props and render UI only:

```tsx
export interface NavbarStyle1Props {
  brandName?: string
  cartCount?: number
  // ... props only, no data fetching or state management
}
```

**What to add**: Connect components to your backend, add business logic, implement actual features, and integrate with your app's state management.

### 3. Parallel Generation Capability ⚡

Components with unique names can be generated simultaneously using the workflow. This dramatically speeds up the initial scaffolding phase.

**How it works**: Each component gets its own namespaced design tokens (e.g., `--color-navbar-primary`, `--color-footer-primary`), preventing conflicts when generating multiple components in parallel.

**Requirement**: Ensure each component has a unique name before starting parallel generation.

## The Workflow

### Phase 1: Extraction (Read-Only) 📥

**Purpose**: Extract ALL design data from Figma and save raw outputs. Make **NO modifications** to system files.

1. Use Figma MCP tools to extract:
   - Design system variables (colors, typography, spacing)
   - Component metadata and measurements
   - Visual screenshots and descriptions
   - Generated code context
2. Save 6-11 raw files to `temp-outputs/` directory
3. NO system modifications at this stage
4. **STOP for review** - verify extraction before proceeding

### Phase 2: Implementation (After Review) 🛠️

**Purpose**: Use extracted raw data to update system files and generate pixel-perfect component.

1. Read from saved raw files (never re-extract)
2. Merge design systems and document strategy
3. Update `app/app.css` with design tokens using `@theme` directive
4. Extend `tailwind.config.ts` with semantic utility classes
5. Generate component with pixel-perfect implementation
6. Validate with TypeScript, linting, and visual comparison

**See detailed workflow**: [Single URL Guide](./docs/FIGMA-GENERIC-SINGLE.md) | [Dual URL Guide](./docs/FIGMA-GENERIC-DUAL.md)

## Tech Stack Foundation

We provides the infrastructure for Figma-to-code workflows:

- **[React Router v7](https://reactrouter.com/)** - Full-stack React framework
- **[TypeScript](https://www.typescriptlang.org/)** - Type-safe JavaScript
- **[Tailwind CSS v4](https://tailwindcss.com/)** - CSS-first configuration approach
- **[shadcn/ui](https://ui.shadcn.com/)** - Radix UI component primitives (vendored)
- **[TanStack Query](https://tanstack.com/query)** - Server state management (optional)
- **[Zustand](https://github.com/pmndrs/zustand)** - Client state management (optional)
- **[Vite](https://vitejs.dev/)** - Build tool and dev server
- **[Playwright](https://playwright.dev/)** - End-to-end testing

### Tailwind v4: CSS-First Configuration ⭐

We use Tailwind v4's revolutionary CSS-first approach (released January 22, 2025):

**No `tailwind.config.js` required** - All configuration happens directly in CSS using the `@theme` directive:

```css
@import 'tailwindcss';
@config '../tailwind.config.ts'; /* Optional, for DX only */

@theme {
  /* Design tokens → Utility classes */
  --color-brand-primary: #23a6f0;
  --font-montserrat: 'Montserrat', sans-serif;
  --navbar-height: 91px;
}

@theme inline {
  /* Reference existing CSS variables */
  --color-background: var(--background);
}
```

Then use semantic utilities in your components:

```tsx
<div className='bg-brand-primary h-navbar-height font-montserrat'>
  Hello World
</div>
```

**Why this matters for Figma workflows**: Design tokens extracted from Figma map directly to CSS variables without config file complexity. The `@theme` directive automatically generates utility classes, making the Figma-to-code translation seamless.

**Key Changes in Tailwind v4**:

- **`@theme` directive** - Define design tokens directly in CSS ([docs](https://tailwindcss.com/docs/theme))
- **`@theme inline`** - Reference CSS variables within theme ([docs](https://tailwindcss.com/docs/functions-and-directives))
- **Optional config file** - The included `tailwind.config.ts` is purely for DX (creates semantic aliases)

**Learn more**: [Tailwind v4 Announcement](https://tailwindcss.com/blog/tailwindcss-v4) | [shadcn/ui v4 Guide](https://ui.shadcn.com/docs/tailwind-v4)

## Development Commands

```bash
# Development
npm run dev              # Start dev server at http://localhost:5173
npm run start:server     # Start JSON server mock API on port 3001

# Code Quality
npm run typecheck        # TypeScript + React Router type generation
npm run lint             # ESLint (strict: max-warnings 0)
npm run lint:fix         # Auto-fix linting issues
npm run format           # Format with Prettier
npm run format:check     # Check formatting (CI-friendly)

# Production
npm run build            # Build for production
npm start                # Run production server

# Testing
npm test                 # Run Playwright tests headless
npm run test:ui          # Interactive test UI mode
npm run test:debug       # Debug tests with dev tools
```

## Learn More

### Figma MCP Workflow

- [Single URL Workflow Guide](./docs/FIGMA-GENERIC-SINGLE.md) - Complete process documentation
- [Dual URL Workflow Guide](./docs/FIGMA-GENERIC-DUAL.md) - For separate desktop/mobile files
- [Single URL Template](./templates/figma-mcp-single-template.md) - Copy-paste prompt
- [Dual URL Template](./templates/figma-mcp-dual-template.md) - Copy-paste prompt

### Technologies

- [Tailwind v4 CSS-First Config](https://tailwindcss.com/docs/theme) - Official documentation
- [Tailwind v4 Announcement](https://tailwindcss.com/blog/tailwindcss-v4) - What's new
- [React Router v7](https://reactrouter.com/start/framework/installation) - Framework documentation
- [shadcn/ui](https://ui.shadcn.com/) - Component library documentation
- [shadcn/ui Tailwind v4 Guide](https://ui.shadcn.com/docs/tailwind-v4) - Migration guide
- [TanStack Query](https://tanstack.com/query/latest) - Data synchronization
- [Playwright](https://playwright.dev/docs/intro) - Testing framework

## Contributing

This is a demonstration project. Feel free to:

- Fork and experiment with the workflow
- Adapt templates for your specific needs
- Share improvements to the workflow documentation
- Report issues with the generation process

## License

This project is private and not licensed for public use.