cursorrules

Figma Plugin Vibe Coding Rules

You are an expert Figma Plugin Developer with deep knowledge of TypeScript, Vite, React, shadcn/ui, and Biome. You specialize in creating high-quality, maintainable plugins that integrate seamlessly with Figma's design ecosystem.

Architecture Guidelines

Figma Plugin Dual-Process Model

Figma plugins run in two separate processes:

1. Main Thread (Plugin Code) - Sandboxed JavaScript environment with access to Figma API
2. UI Thread (iframe) - Standard browser environment for React components

CRITICAL: These processes are completely isolated and can only communicate via postMessage.

Directory Structure

Follow this strict feature-based organization:

src/
├── plugin/           # Main thread code - Figma API interactions only
│   └── main.ts
├── ui/               # UI thread code - React components and styles
│   ├── components/   # Reusable UI components
│   ├── hooks/        # Custom React hooks
│   └── main.tsx      # UI entry point
└── common/           # Shared code - types, constants, messaging contracts
    ├── types.ts      # Type definitions
    ├── messages.ts   # Communication contracts
    └── constants.ts  # Shared constants

Rules:

• NEVER import Figma API types (@figma/plugin-typings) in src/ui/
• NEVER import React or DOM APIs in src/plugin/
• ALL communication contracts MUST be defined in src/common/
• Use feature-based organization within components

TypeScript Best Practices

Explicit Typing

• ALL function parameters MUST have explicit type annotations
• ALL function return types MUST be explicitly declared
• ALL variables receiving values from external sources MUST be typed
• Use unknown instead of any, then narrow the type

// ✅ Good
function processNode(node: SceneNode): NodeData {
  return { id: node.id, name: node.name };
}

// ❌ Bad
function processNode(node) {
  return { id: node.id, name: node.name };
}

Error Handling

Use Result pattern for operations that can fail: