figma-code-agent 1.0.0

package/package.json

@@ -0,0 +1,31 @@
+{
+  "name": "figma-code-agent",
+  "version": "1.0.0",
+  "description": "Figma developer expert tool for Claude Code — 19 knowledge modules and 10 invokable skills for building plugins, codegen plugins, importers, token pipelines, and design-to-code workflows.",
+  "bin": {
+    "figma-code-agent": "bin/install.js"
+  },
+  "files": [
+    "bin",
+    "skills",
+    "knowledge"
+  ],
+  "keywords": [
+    "figma",
+    "claude-code",
+    "design-to-code",
+    "figma-plugin",
+    "codegen",
+    "importer",
+    "react",
+    "css",
+    "design-tokens",
+    "payloadcms"
+  ],
+  "author": "aolea",
+  "license": "MIT",
+  "repository": {
+    "type": "git",
+    "url": "https://github.com/aolea/figma-code-agent"
+  }
+}

package/skills/README.md

@@ -0,0 +1,103 @@
+# Figma Agent Skills
+
+Claude Code invokable skills for Figma development workflows.
+
+## Plugin Format
+
+This agent uses the Claude Code plugin format (`.claude-plugin/plugin.json`). Skills live in `skills/{name}/SKILL.md`.
+
+## Available Skills
+
+### Tier 1: Developer Workflow (Assess → Recommend → Implement → Validate)
+
+| Skill | Command | Description | Knowledge Modules |
+|-------|---------|-------------|-------------------|
+| Build Plugin | `/fca:build-plugin` | Build a Figma plugin from scratch or enhance an existing one | plugin-architecture, plugin-best-practices, figma-api-plugin |
+| Build Codegen Plugin | `/fca:build-codegen-plugin` | Build a Dev Mode codegen plugin that generates code from designs | plugin-codegen, figma-api-devmode, plugin-best-practices, figma-api-plugin |
+| Build Importer | `/fca:build-importer` | Build a service that fetches Figma designs into a CMS or React app | figma-api-rest, figma-api-variables, all design-to-code, css-strategy, design-tokens, payload-figma-mapping, payload-blocks |
+| Build Token Pipeline | `/fca:build-token-pipeline` | Build a pipeline that syncs Figma design tokens to code | figma-api-variables, design-tokens, design-tokens-variables, figma-api-webhooks, css-strategy |
+
+### Tier 2: Reference / Validation (Step-by-step process)
+
+| Skill | Command | Description | Knowledge Modules |
+|-------|---------|-------------|-------------------|
+| Ref: Layout | `/fca:ref-layout` | Interpret Figma Auto Layout → CSS Flexbox with correct sizing modes | layout |
+| Ref: React | `/fca:ref-react` | Generate production-grade React/TSX component from Figma node data | layout, visual, typography, assets, semantic, css-strategy |
+| Ref: HTML | `/fca:ref-html` | Generate semantic HTML + layered CSS from Figma node data | layout, visual, typography, assets, semantic, css-strategy, design-tokens |
+| Ref: Tokens | `/fca:ref-tokens` | Extract design tokens → CSS custom properties + Tailwind config | design-tokens, design-tokens-variables, figma-api-variables, css-strategy |
+| Ref: PayloadCMS Block | `/fca:ref-payload-block` | Map Figma component → PayloadCMS block config + renderer + types | payload-blocks, payload-figma-mapping, payload-visual-builder, css-strategy |
+
+### Tier 3: Audit
+
+| Skill | Command | Description | Knowledge Modules |
+|-------|---------|-------------|-------------------|
+| Audit Plugin | `/fca:audit-plugin` | Audit Figma plugin code against production best practices | plugin-architecture, plugin-codegen, plugin-best-practices, figma-api-plugin |
+
+## Installation
+
+```bash
+# Recommended: install via npx
+npx figma-code-agent
+
+# Alternative: load as Claude Code plugin (for development)
+claude --plugin-dir /path/to/figma-code-agent
+
+# Manual: symlinks (requires clone)
+./install.sh
+```
+
+## Skill Structure
+
+Skills use two process patterns:
+
+### Tier 1 Pattern: 4-Phase Process
+
+1. **YAML frontmatter** -- `name` and `description` for Claude Code registration
+2. **@references** -- Knowledge modules the skill depends on
+3. **Objective** -- What the skill accomplishes
+4. **Input** -- What the user provides (requirements, existing project path, description)
+5. **Process** -- 4 phases: Assess → Recommend → Implement → Validate
+6. **Output** -- What gets generated (project files, modifications, validation report)
+
+### Tier 2/3 Pattern: Step-by-Step Process
+
+1. **YAML frontmatter** -- `name` and `description` for Claude Code registration
+2. **@references** -- Knowledge modules the skill depends on
+3. **Objective** -- What the skill accomplishes
+4. **Input** -- What the user provides (Figma node data, file URL, etc.)
+5. **Process** -- Numbered step-by-step instructions for Claude
+6. **Output** -- What gets generated (React component, CSS, token config, etc.)
+
+## Invocation Examples
+
+```
+# Build a Figma plugin
+/fca:build-plugin I want to build a plugin that exports frames as React components
+
+# Build a codegen plugin for Dev Mode
+/fca:build-codegen-plugin Generate Tailwind + React code in the inspect panel
+
+# Build a Figma importer
+/fca:build-importer Import Figma page designs into PayloadCMS blocks
+
+# Build a token sync pipeline
+/fca:build-token-pipeline Sync Figma Variables to CSS and Tailwind on library publish
+
+# Interpret a Figma Auto Layout frame
+/fca:ref-layout <paste Figma Auto Layout JSON node data>
+
+# Generate a React component from Figma design
+/fca:ref-react <paste Figma node data or describe the component>
+
+# Generate vanilla HTML + CSS from Figma design
+/fca:ref-html <paste Figma node data>
+
+# Extract design tokens from Figma Variables
+/fca:ref-tokens <paste Figma Variables API response or style data>
+
+# Map a Figma component to a PayloadCMS block
+/fca:ref-payload-block <paste Figma component data>
+
+# Audit a Figma plugin codebase
+/fca:audit-plugin <path to Figma plugin project>
+```

package/skills/audit-plugin/SKILL.md

@@ -0,0 +1,244 @@
+---
+name: audit-plugin
+description: Audit Figma plugin code against production best practices. Use this skill when the user has a Figma plugin codebase and wants a quality review covering error handling, performance, memory management, caching, async patterns, testing, and distribution readiness.
+---
+
+@knowledge/plugin-architecture.md
+@knowledge/plugin-codegen.md
+@knowledge/plugin-best-practices.md
+@knowledge/figma-api-plugin.md
+
+## Objective
+
+Audit a Figma plugin codebase against 7 production best practice categories, plus codegen-specific checks and architectural pattern verification. Read the actual source files, identify concrete issues with code references, rate each section (pass/warn/fail), and provide actionable recommendations with fix examples. This is NOT generic advice -- every finding must reference specific code in the plugin.
+
+## Input
+
+The user provides plugin source code as `$ARGUMENTS`. This may be:
+
+- **File paths** to plugin source files (manifest, main thread code, UI code, utilities)
+- **Directory path** to the plugin project root
+- **Description** of the plugin's purpose and architecture, with key file contents
+- **Specific concern** to focus the audit on (e.g., "check my async patterns" or "review error handling")
+
+If file paths are provided, read all relevant source files before starting the audit. At minimum, the audit needs:
+- Manifest or `package.json` with `figma-plugin` section
+- Main thread entry point (typically `src/main.ts`)
+- UI entry point if it exists (typically `src/ui.tsx`)
+
+If only a subset of files is available, audit what is provided and note which sections cannot be fully evaluated.
+
+## Process
+
+Read all provided source files first, then audit against each section in order. For each section, identify specific patterns (good and bad) in the code.
+
+### Section 1: Error Handling
+
+Consult `knowledge/plugin-best-practices.md` Section 1.
+
+**Check for:**
+
+- [ ] **Structured error types** -- Does the plugin define error codes (enum/const) with machine-readable codes, human-readable messages, and optional details? Or are errors thrown as raw strings?
+- [ ] **Try/catch in IPC handlers** -- Is each IPC event handler (`on<Handler>(EVENT, async () => {...})`) wrapped in a single top-level try/catch? Or are there unprotected async handlers?
+- [ ] **Centralized error emission** -- Is there a single `emitError()` helper that logs to console AND emits structured error data to the UI? Or are errors handled ad-hoc in each handler?
+- [ ] **User-facing error messages** -- Are error messages non-technical and actionable (e.g., "Select a frame or component")? Or do they leak stack traces or technical details to users?
+- [ ] **Graceful degradation** -- When processing a tree of nodes, does the plugin skip failed nodes and continue? Or does one failure abort the entire operation?
+- [ ] **UI error display** -- Does the UI handle error events with recovery hints and retry options? Or do errors silently fail or show raw error objects?
+- [ ] **figma.notify usage** -- Are `figma.notify()` calls used for quick user feedback (selection errors, completion messages)?
+
+**Rating criteria:**
+- **Pass**: Structured error types, centralized emission, try/catch on all handlers, graceful degradation
+- **Warn**: Try/catch present but inconsistent, no structured types, some unprotected handlers
+- **Fail**: No try/catch in handlers, raw error throwing, no error propagation to UI
+
+### Section 2: Performance
+
+Consult `knowledge/plugin-best-practices.md` Section 2.
+
+**Check for:**
+
+- [ ] **Progress reporting** -- For operations processing 100+ nodes, does the plugin report progress to the UI? Or does it appear frozen during long operations?
+- [ ] **Pipeline timing** -- Are extraction and generation phases instrumented with timing logs? Or is there no visibility into where time is spent?
+- [ ] **Depth limits** -- Is recursive tree traversal capped at a maximum depth (e.g., 30)? Or can deeply nested designs cause stack overflow?
+- [ ] **Batch operations** -- Are child extractions parallelized with `Promise.all`? Are heavy I/O operations (exportAsync) done sequentially? Or is there unbounded parallelism on expensive operations?
+- [ ] **Scoped traversal** -- Does the plugin scope searches to the selected subtree or current page? Or does it call `figma.root.findAll()` on the entire document?
+- [ ] **Bundle size** -- Is the UI built with Preact (not React)? Are heavy libraries lazy-loaded? Is `--minify` enabled in the build?
+- [ ] **Visible children filter** -- Does traversal filter out `visible: false` nodes early? Or are invisible nodes fully processed?
+
+**Rating criteria:**
+- **Pass**: Progress reporting, depth limits, pipeline timing, efficient traversal, optimized bundle
+- **Warn**: Missing progress for long operations, no depth limit but no crashes observed, minor inefficiencies
+- **Fail**: `figma.root.findAll()` without scoping, no depth limits, unbounded parallel exportAsync, React instead of Preact
+
+### Section 3: Memory Management
+
+Consult `knowledge/plugin-best-practices.md` Section 3.
+
+**Check for:**
+
+- [ ] **JSON-serializable intermediate format** -- Does the extraction phase produce a plain data structure (ExtractedNode-like)? Or does it try to pass Figma SceneNode objects across IPC?
+- [ ] **Selective property extraction** -- Are only needed properties extracted from each node? Or is every property read regardless of usage?
+- [ ] **Asset deduplication** -- Are images with the same `imageHash` exported only once? Or is the same image exported multiple times?
+- [ ] **Large file safeguards** -- Are there element count warnings, depth limits, and pre-flight checks before heavy operations?
+- [ ] **Cache cleanup** -- Are module-level caches cleared between extraction runs and on page changes? Or do caches grow unbounded?
+- [ ] **Reference nulling** -- Are large data structures nulled out when no longer needed?
+
+**Rating criteria:**
+- **Pass**: Serializable intermediate format, selective extraction, deduplication, cache cleanup
+- **Warn**: Serializable format but extracts unnecessary properties, no deduplication
+- **Fail**: Passing SceneNode objects across IPC, no cache cleanup, unbounded memory growth
+
+### Section 4: Caching
+
+Consult `knowledge/plugin-best-practices.md` Section 4.
+
+**Check for:**
+
+- [ ] **Variable cache** -- Are local variable IDs loaded once and cached for the extraction run? Or is `getLocalVariablesAsync()` called repeatedly?
+- [ ] **Font loading cache** -- Are already-loaded fonts tracked to avoid redundant `loadFontAsync` calls?
+- [ ] **Component reference cache** -- Are component names cached to avoid repeated `getMainComponentAsync()` calls?
+- [ ] **Cache invalidation** -- Are caches invalidated at appropriate times (extraction start, page change, selection change)?
+- [ ] **Persistent storage** -- Are user preferences stored in `figma.clientStorage`? Is node-level metadata stored via `pluginData` where appropriate?
+- [ ] **Session vs persistent separation** -- Are volatile caches (variable IDs, extracted data) kept in memory, while durable settings use clientStorage?
+
+**Rating criteria:**
+- **Pass**: Variable cache, font cache, proper invalidation, persistent settings
+- **Warn**: Some caching but missing variable or font cache, manual invalidation
+- **Fail**: No caching at all, repeated expensive API calls on every node
+
+### Section 5: Async Patterns
+
+Consult `knowledge/plugin-best-practices.md` Section 5.
+
+**Check for:**
+
+- [ ] **Async node access** -- Uses `getNodeByIdAsync` (not `getNodeById`)? Null-checks results?
+- [ ] **Font loading before text modification** -- Calls `loadFontAsync` before setting `characters` or font properties? Handles `figma.mixed` for multi-font text?
+- [ ] **exportAsync handling** -- Processes exports sequentially for heavy operations? Uses try/catch per export?
+- [ ] **Timeout handling** -- Are long-running operations wrapped with timeout logic? Is there a cancellation pattern for plugin close?
+- [ ] **Sequential vs parallel** -- Are read-only child extractions parallelized while I/O operations are sequential?
+- [ ] **Promise rejection handling** -- Are all async handlers wrapped in try/catch? No unhandled promise rejections?
+
+**Rating criteria:**
+- **Pass**: Async-first API usage, proper font loading, timeout handling, cancellation, correct parallel/sequential choices
+- **Warn**: Async APIs used but missing null checks, no timeout handling, minor parallel/sequential issues
+- **Fail**: Sync API usage (getNodeById), no font loading before text modification, unhandled rejections
+
+### Section 6: Testing
+
+Consult `knowledge/plugin-best-practices.md` Section 6.
+
+**Check for:**
+
+- [ ] **Testable architecture** -- Is generation logic separated from Figma API calls? Can generation functions be tested with plain data input?
+- [ ] **Mock data fixtures** -- Are there mock ExtractedNode fixtures for testing generation without the Figma runtime?
+- [ ] **Unit tests for generation** -- Are pure generation functions (layout CSS, visual CSS, HTML rendering) unit tested?
+- [ ] **Code validation** -- Does the plugin validate generated HTML/CSS output (tag matching, bracket matching, no JavaScript injection)?
+- [ ] **Edge case coverage** -- Are edge cases handled: empty selection, zero-size frames, SLICE nodes, detached instances, mixed fonts, deeply nested groups?
+- [ ] **Console logging strategy** -- Are logs prefixed by domain (`[Extraction]`, `[Generation]`, `[Export]`) with relevant data?
+
+**Rating criteria:**
+- **Pass**: Generation functions testable and tested, mock fixtures, validation, edge case handling, structured logging
+- **Warn**: Architecture supports testing but few/no tests written, some edge cases missed
+- **Fail**: Generation coupled to Figma API (untestable), no validation, crashes on common edge cases
+
+### Section 7: Distribution
+
+Consult `knowledge/plugin-best-practices.md` Section 7.
+
+**Check for:**
+
+- [ ] **Manifest correctness** -- Is `editorType` correct (["figma"] for standard, ["dev"] for codegen)? Is `documentAccess: "dynamic-page"` set?
+- [ ] **Permission minimization** -- Are only necessary permissions declared? Most plugins need zero permissions.
+- [ ] **Network access scoping** -- If `networkAccess` is declared, are domains specific (not wildcard `*`)? Is reasoning provided?
+- [ ] **Version management** -- Is the version in package.json following semver? Is the version reflected in the plugin name or manifest?
+- [ ] **Build configuration** -- Is `--typecheck` and `--minify` enabled in the build script?
+- [ ] **Publishing metadata** -- Are name, description, icon, and cover image prepared?
+
+**Rating criteria:**
+- **Pass**: Correct manifest, minimal permissions, scoped network, semver, optimized build
+- **Warn**: Correct manifest but missing optimization flags, overly broad permissions
+- **Fail**: Wrong editorType, missing dynamic-page, wildcard network access without justification
+
+### Section 8: Codegen-Specific Checks (If Applicable)
+
+Only audit this section if the plugin is a codegen plugin (`editorType: ["dev"]`, `capabilities: ["codegen"]`).
+
+Consult `knowledge/plugin-codegen.md`.
+
+**Check for:**
+
+- [ ] **3-second timeout compliance** -- Does the `generate` callback avoid network calls, heavy traversal, and unbounded operations? Is data pre-cached during `preferenceschange`?
+- [ ] **Progressive complexity** -- Does the generator handle simple nodes quickly and only do heavy processing for complex nodes?
+- [ ] **Language routing** -- Does the generate callback route to language-specific generators based on `event.language`?
+- [ ] **CodegenResult format** -- Are results returned as an array of `{title, code, language}` with correct language constants?
+- [ ] **Preferences system** -- Are user preferences (units, CSS strategy) exposed via codegen preferences?
+- [ ] **Pre-caching** -- Is expensive data (component mappings, variable resolution) cached during preference changes, not during generation?
+
+### Section 9: Architecture Checks
+
+Consult `knowledge/plugin-architecture.md`.
+
+**Check for:**
+
+- [ ] **3-stage data flow** -- Is the codebase organized into extraction (Figma API) -> generation (data transformation) -> export (output assembly)?
+- [ ] **IPC type safety** -- Are IPC events defined with TypeScript types? Are event names centralized as constants (not string literals)?
+- [ ] **Domain separation** -- Are extraction, generation, and export in separate directories/modules? Or is everything in one file?
+- [ ] **Event correlation** -- For request/response IPC patterns, are messages correlated (e.g., via IDs or specific event types)?
+
+## Output
+
+Generate an audit report with the following structure:
+
+### Audit Report Format
+
+```
+# Figma Plugin Audit Report
+Plugin: {plugin name}
+Date: {date}
+Files audited: {list of files}
+
+## Summary
+Overall: {PASS | WARN | FAIL}
+{1-2 sentence summary of the plugin's quality level}
+
+| Section | Rating | Key Finding |
+|---------|--------|-------------|
+| Error Handling | {PASS/WARN/FAIL} | {one-line summary} |
+| Performance | {PASS/WARN/FAIL} | {one-line summary} |
+| Memory Management | {PASS/WARN/FAIL} | {one-line summary} |
+| Caching | {PASS/WARN/FAIL} | {one-line summary} |
+| Async Patterns | {PASS/WARN/FAIL} | {one-line summary} |
+| Testing | {PASS/WARN/FAIL} | {one-line summary} |
+| Distribution | {PASS/WARN/FAIL} | {one-line summary} |
+| Codegen (if applicable) | {PASS/WARN/FAIL} | {one-line summary} |
+| Architecture | {PASS/WARN/FAIL} | {one-line summary} |
+
+## Detailed Findings
+
+### 1. Error Handling — {RATING}
+
+**Good:**
+- {specific finding with file:line reference}
+
+**Issues:**
+- {specific finding with file:line reference}
+  - **Fix:** {concrete code suggestion}
+
+### 2. Performance — {RATING}
+... (repeat for each section)
+
+## Priority Fixes
+1. {highest priority fix — what and why}
+2. {second priority fix}
+3. {third priority fix}
+```
+
+### Report Rules
+
+- **Every finding must reference a specific file and line/function** -- never say "you should add error handling" without pointing to where
+- **Provide fix code examples** for WARN and FAIL findings -- show the corrected pattern, not just what is wrong
+- **Acknowledge good patterns** -- call out what the plugin does well in each section
+- **Priority fixes** should be ordered by impact: crashes > data loss > poor UX > code quality
+- **Overall rating**: FAIL if any section is FAIL, WARN if any section is WARN and none are FAIL, PASS only if all sections pass
+- If files are insufficient to evaluate a section, mark it as "INCOMPLETE" with a note on what files are needed

package/skills/build-codegen-plugin/SKILL.md

@@ -0,0 +1,279 @@
+---
+name: build-codegen-plugin
+description: Build a Figma Dev Mode codegen plugin that generates code from designs. Use this skill when the user wants to build a plugin that runs in Figma's Dev Mode inspect panel and generates code from selected nodes.
+---
+
+@knowledge/plugin-codegen.md
+@knowledge/figma-api-devmode.md
+@knowledge/plugin-best-practices.md
+@knowledge/figma-api-plugin.md
+
+## Objective
+
+Help the user build a Figma codegen plugin that runs in Dev Mode's inspect panel and generates code from selected design nodes. Codegen plugins have unique constraints — a strict 3-second timeout, no network calls during generation, a built-in preferences system, and a specific `CodegenResult[]` return format. This skill handles all of these constraints and produces a working codegen plugin with language routing, pre-caching, and timeout-safe generation.
+
+## Input
+
+The user provides their codegen requirements as `$ARGUMENTS`. This may be:
+
+- Target language(s) to generate (React/TSX, Vue, HTML+CSS, Tailwind, Swift, Kotlin, custom DSL)
+- A path to an existing codegen plugin to enhance
+- A description of the code generation approach (property extraction vs full component generation)
+- A specific codegen feature to add
+
+If the input is a path, read the project files before proceeding. If the input is a description, proceed directly to Phase 1.
+
+## Process
+
+### Phase 1 — Assess
+
+Determine the codegen plugin's scope and constraints.
+
+**Language targets:**
+- Which languages/frameworks should the plugin generate code for?
+- Each language becomes an entry in the manifest's `codegenLanguages` array
+- Each language gets a dedicated generator module
+
+**Complexity level:**
+- **Property extraction**: reads node properties and outputs simple declarations (e.g., CSS properties, style tokens)
+- **Component generation**: produces full component code with structure, styles, and props (more complex, higher timeout risk)
+
+**Plugin type:**
+- **Codegen-only** (`editorType: ["dev"]`): runs exclusively in Dev Mode inspect panel. No standard plugin UI.
+- **Hybrid** (`editorType: ["figma", "dev"]`): has both a standard plugin UI (for configuration, export) AND a codegen panel in Dev Mode. Use hybrid when the plugin needs operations beyond code inspection (e.g., batch export, settings UI, node manipulation).
+
+**Preferences needed:**
+- Unit system: px vs rem vs em
+- CSS strategy: Tailwind utilities vs CSS Modules vs inline styles vs vanilla CSS
+- Naming convention: camelCase vs kebab-case vs BEM
+- Component style: functional vs class-based
+- Other framework-specific options
+
+Report the assessment to the user before proceeding.
+
+### Phase 2 — Recommend
+
+Based on the assessment, recommend the architecture.
+
+**Manifest configuration:**
+```json
+{
+  "editorType": ["dev"],
+  "capabilities": ["codegen"],
+  "codegenLanguages": [
+    { "label": "React/TSX", "value": "react-tsx" },
+    { "label": "HTML + CSS", "value": "html-css" }
+  ]
+}
+```
+- `editorType: ["dev"]` for codegen-only; `["figma", "dev"]` for hybrid
+- `capabilities: ["codegen"]` is required
+- Each language in `codegenLanguages` appears as a tab in the inspect panel
+
+**3-second timeout strategy:**
+- The `generate` callback has a hard 3-second timeout — if exceeded, Figma kills the operation
+- **Pre-cache during `preferenceschange`**: load variables, resolve component references, build lookup tables. This event fires when the user opens the plugin or changes preferences — no timeout pressure.
+- **Keep `generate` lightweight**: only read the selected node's immediate properties, look up pre-cached data, assemble code string. No `getNodeByIdAsync`, no `exportAsync`, no network calls.
+- **Progressive complexity**: handle simple nodes quickly (single properties), only do heavier processing for complex component nodes if time budget allows
+
+**Preference system:**
+- Use Figma's built-in codegen preferences panel (NOT a custom iframe UI)
+- Preferences are defined in the manifest or via `figma.codegen.on('preferenceschange')`
+- Preference values are available in both the `generate` and `preferenceschange` callbacks via `event.preferences`
+
+**Language routing:**
+- The `generate` callback receives `event.language` indicating which language tab the user selected
+- Route to dedicated generator modules: `generateReact(node)`, `generateHTML(node)`, etc.
+- Each generator module is a pure function: node data in → `CodegenResult[]` out
+
+**Dev Resources linking (optional):**
+- Link generated code to external resources (GitHub files, Storybook URLs, documentation)
+- Use `figma.codegen.on('resultchange')` to update Dev Resources when code changes
+- Dev Resources appear in the inspect panel alongside generated code
+
+**Hybrid architecture (if applicable):**
+- Standard UI (`src/ui.tsx`) handles configuration, batch operations, settings
+- Codegen (`src/codegen.ts`) handles per-node code generation in Dev Mode
+- Shared modules for generation logic used by both
+- Separate entry points in manifest: `main` for standard, `codegen` for Dev Mode
+
+Present the recommendations to the user and confirm before implementing.
+
+### Phase 3 — Implement
+
+Generate the codegen plugin code.
+
+**1. Manifest / `package.json` `figma-plugin` section:**
+```json
+{
+  "name": "Plugin Name",
+  "id": "REPLACE_WITH_PLUGIN_ID",
+  "editorType": ["dev"],
+  "capabilities": ["codegen"],
+  "codegenLanguages": [
+    { "label": "React/TSX", "value": "react-tsx" }
+  ],
+  "codegenPreferences": [
+    {
+      "itemType": "select",
+      "propertyName": "unitSystem",
+      "label": "Unit System",
+      "options": [
+        { "label": "rem", "value": "rem", "isDefault": true },
+        { "label": "px", "value": "px" }
+      ]
+    }
+  ]
+}
+```
+
+**2. Main entry point (`src/main.ts`):**
+
+```typescript
+// Pre-cached data populated during preferenceschange
+let variableCache: Map<string, ResolvedVariable> = new Map();
+let componentCache: Map<string, string> = new Map();
+
+figma.codegen.on('preferenceschange', async (event) => {
+  // Heavy work happens here — no timeout pressure
+  try {
+    // Load and cache all local variables
+    const variables = await figma.variables.getLocalVariablesAsync();
+    variableCache.clear();
+    for (const variable of variables) {
+      variableCache.set(variable.id, resolveVariable(variable));
+    }
+
+    // Cache component names for instance detection
+    // ... additional pre-caching
+  } catch (error) {
+    console.error('[Codegen] Pre-cache failed:', error);
+  }
+});
+
+figma.codegen.on('generate', (event) => {
+  // Lightweight — must complete within 3 seconds
+  // No async operations, no network calls
+  try {
+    const { node, language } = event;
+
+    switch (language) {
+      case 'react-tsx':
+        return generateReact(node, event.preferences, variableCache);
+      case 'html-css':
+        return generateHTML(node, event.preferences, variableCache);
+      default:
+        return [{ title: 'Error', code: `Unknown language: ${language}`, language: 'PLAINTEXT' }];
+    }
+  } catch (error) {
+    return [{ title: 'Error', code: String(error), language: 'PLAINTEXT' }];
+  }
+});
+```
+
+**3. Language-specific generator modules:**
+
+Each generator is a pure function:
+```typescript
+// src/generators/react.ts
+export function generateReact(
+  node: SceneNode,
+  preferences: Record<string, string>,
+  variables: Map<string, ResolvedVariable>
+): CodegenResult[] {
+  // Read node properties (synchronous — no async API calls)
+  // Look up pre-cached variable bindings
+  // Assemble React/TSX code string
+  // Return CodegenResult array
+
+  return [
+    {
+      title: 'Component.tsx',
+      code: componentCode,
+      language: 'TYPESCRIPT',
+    },
+    {
+      title: 'Component.module.css',
+      code: cssCode,
+      language: 'CSS',
+    },
+  ];
+}
+```
+
+**4. Preference handling:**
+- Read preferences from `event.preferences` in both callbacks
+- Apply preference values to generation (unit conversion, naming convention, CSS strategy)
+- Provide sensible defaults for all preferences
+
+**5. Code quality patterns:**
+- Try/catch in both `generate` and `preferenceschange` callbacks
+- Graceful fallback: if generation fails for a node, return a helpful error message as a `CodegenResult` (not an exception)
+- Code validation: verify generated code has balanced brackets, valid syntax structure
+- Progressive detail: simple nodes get simple output, complex nodes get full component generation
+
+### Phase 4 — Validate
+
+Verify the codegen plugin meets Figma's constraints.
+
+**Timeout compliance:**
+- [ ] No `async` keyword or `await` in the `generate` callback
+- [ ] No `getNodeByIdAsync`, `loadFontAsync`, `exportAsync` in `generate`
+- [ ] No `fetch()` or network calls in `generate`
+- [ ] Heavy data loading happens in `preferenceschange` (pre-caching)
+- [ ] Node property reads in `generate` are synchronous and direct
+
+**Manifest correctness:**
+- [ ] `editorType` includes `"dev"`
+- [ ] `capabilities` includes `"codegen"`
+- [ ] `codegenLanguages` array is populated with at least one language
+- [ ] Each language has `label` (display name) and `value` (event identifier)
+- [ ] Preferences use valid `itemType` values (`select`, `input`, `separator`)
+
+**Output format:**
+- [ ] `generate` returns `CodegenResult[]` (array, not single object)
+- [ ] Each result has `title` (string), `code` (string), `language` (Figma language constant)
+- [ ] Language constants are valid: `CSS`, `HTML`, `JAVASCRIPT`, `TYPESCRIPT`, `JSON`, `PLAINTEXT`, etc.
+
+**Pre-caching:**
+- [ ] Variable resolution cached during `preferenceschange`
+- [ ] Component name lookups cached
+- [ ] Caches are refreshed on preference changes (not stale between sessions)
+
+**Error handling:**
+- [ ] Both `generate` and `preferenceschange` have try/catch
+- [ ] Generation errors produce a readable error CodegenResult (not a crash)
+- [ ] Pre-cache failures are logged but don't prevent generation from working with partial data
+
+## Output
+
+Generate the appropriate files:
+
+### Codegen-Only Plugin Output
+
+- **`package.json`** — with `figma-plugin` section including codegen config
+- **`src/main.ts`** — Entry point with `preferenceschange` (pre-caching) and `generate` (routing) handlers
+- **`src/generators/{language}.ts`** — One generator module per target language
+- **`src/types.ts`** — Shared types, resolved variable interfaces, preference types
+- **`tsconfig.json`** — TypeScript configuration
+
+### Hybrid Plugin Output (if applicable)
+
+All of the above, plus:
+- **`src/ui.tsx`** — Standard plugin UI for configuration/batch operations
+- Separate entry points in manifest for standard and codegen modes
+
+### Output Checklist
+
+Before returning the codegen plugin code, verify:
+
+- [ ] Manifest has `capabilities: ["codegen"]` and correct `editorType`
+- [ ] `codegenLanguages` array populated with all target languages
+- [ ] 3-second timeout budget respected — `generate` callback is synchronous and lightweight
+- [ ] No network calls, no async API calls inside `generate`
+- [ ] Heavy data loading pre-cached in `preferenceschange` handler
+- [ ] `CodegenResult[]` format correct with valid language constants
+- [ ] Preferences use Figma's built-in preference system (not custom UI)
+- [ ] Language routing dispatches to dedicated generator modules
+- [ ] Error handling produces readable error results (not crashes)
+- [ ] Pre-cached data is refreshed on preference changes