figma-to-code-agent 0.3.0

package/CHANGELOG.md

@@ -0,0 +1,55 @@
+# Changelog
+
+## [0.3.0] - 2026-02-12
+
+### Added
+- `--preview` flag: generate and instantly preview in browser via built-in Vite test app
+- `--node` parameter: convert specific Figma node/layer instead of entire file
+- Responsive scaling: root container auto-fits viewport width, no horizontal scrollbar
+- Figma mask support: filter `isMask` nodes, containers inherit parent background
+- Invisible fill filtering: skip `opacity: 0` fills (transparent placeholders)
+- Hidden layer filtering: `visible: false` nodes excluded from output
+- Vector icon detection: pure vector containers auto-exported as PNG images
+- Image local cache fallback: skip API calls when images already exist on disk
+- High-res image export: `scale: 2` for retina displays
+- Full typography CSS: font-family, font-size, font-weight, line-height, letter-spacing, text-align, color
+- `white-space: nowrap` for single-line text nodes
+- Google Fonts and CSS reset in test-app HTML templates
+- Non-ASCII filename sanitization (Chinese characters stripped from output filenames)
+- 4 example projects with original vs generated screenshots
+
+### Changed
+- Default TypeScript output changed to `false` (use `--typescript` to enable)
+- Root container uses `transform: scale()` with JS resize listener instead of fixed `max-width`
+- `overflow: hidden` containers now get `background-color: inherit` to match Figma compositing
+- Replaced `SimplifyTransformer`/`FlattenTransformer` with `FigmaStructureOptimizer`
+- `ComponentExtractor` preserves Text/Image/Shape types (no longer converts to Component)
+- Image imports only generated for local paths (avoids broken imports from failed downloads)
+- CSS class names truncated for long text nodes
+
+### Fixed
+- Duplicate method definitions in generators
+- Button text centering with flex layout for single-text containers
+- Image rendering with ES module imports (`import img from './assets/...'`)
+- Rate limit handling with automatic retry and backoff
+
+## [0.2.0] - 2026-02-11
+
+### Added
+- LLM integration: AWS Bedrock, OpenAI, and Anthropic providers
+- AI semantic naming, component splitting, and code optimization
+- CLI options: `--llm-provider`, `--llm-model`, `--ai-naming`, `--ai-splitting`, `--ai-optimization`
+
+### Changed
+- `TransformationPipeline` supports async transformers
+- `FigmaToCodeAgent` conditionally registers AI transformers
+
+## [0.1.0] - 2026-02-11
+
+### Initial Release
+- Figma API and MCP protocol integration
+- AST parsing and transformation pipeline
+- React and Vue code generation
+- CSS Modules, Tailwind, and plain CSS support
+- TypeScript support
+- 129 tests

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 lewiscutey
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/QUICKSTART.md

@@ -0,0 +1,198 @@
+# Quick Start
+
+## 1. Install & Build
+
+```bash
+git clone https://github.com/lewiscutey/figma-to-code-agent.git
+cd figma-to-code-agent
+npm install
+npm run build
+```
+
+## 2. Get Your Figma Token
+
+1. Go to [Figma API Settings](https://www.figma.com/developers/api#access-tokens)
+2. Click "Get personal access token"
+3. Copy the token
+
+## 3. Get File Key & Node ID
+
+From your Figma URL:
+
+```
+https://www.figma.com/design/ABC123DEF456/My-Design?node-id=100-200
+                              ^^^^^^^^^^^^^^                 ^^^^^^^
+                              File Key                       Node ID
+```
+
+Node ID format: `100-200` (use hyphen, not colon)
+
+## 4. Generate Code
+
+```bash
+# React component
+node dist/cli.js \
+  --token YOUR_FIGMA_TOKEN \
+  --file ABC123DEF456 \
+  --node 100-200 \
+  --framework react \
+  --output ./output
+
+# Vue component
+node dist/cli.js \
+  --token YOUR_FIGMA_TOKEN \
+  --file ABC123DEF456 \
+  --node 100-200 \
+  --framework vue \
+  --output ./output
+```
+
+Or use environment variable:
+
+```bash
+export FIGMA_TOKEN="your-token"
+node dist/cli.js --file ABC123DEF456 --node 100-200 --output ./output
+```
+
+## 5. Preview in Browser
+
+Add `--preview` to instantly open the result in your browser:
+
+```bash
+node dist/cli.js \
+  --token YOUR_FIGMA_TOKEN \
+  --file ABC123DEF456 \
+  --node 100-200 \
+  --framework react \
+  --output ./output \
+  --preview
+```
+
+This copies the generated files to the built-in test app, starts a Vite dev server, and opens your browser. Press `Ctrl+C` to stop — temporary files are cleaned up automatically.
+
+## 6. TypeScript Output (Optional)
+
+By default, generates `.jsx` / `.vue`. Add `--typescript` for `.tsx` output:
+
+```bash
+node dist/cli.js \
+  --token YOUR_FIGMA_TOKEN \
+  --file ABC123DEF456 \
+  --node 100-200 \
+  --framework react \
+  --typescript \
+  --output ./output
+```
+
+## Generated Output
+
+For a React component, you'll get:
+
+```
+output/
+├── Component.jsx          # React component
+├── Component.module.css   # CSS Module styles
+└── assets/                # Downloaded images
+    ├── hero-image.png
+    └── icon-close.png
+```
+
+For Vue, a single `.vue` file with `<template>`, `<script setup>`, and `<style scoped>`.
+
+## What Gets Generated
+
+- Pixel-accurate layout using absolute positioning
+- Responsive scaling — auto-fits viewport width, no horizontal scrollbar
+- Full typography (font family, size, weight, line-height, letter-spacing, color)
+- Images exported at 2x resolution for retina displays
+- Vector icons auto-detected and exported as PNG
+- Hidden layers and mask shapes filtered out
+- CSS Modules with scoped class names
+
+## CLI Reference
+
+| Option | Description | Default |
+|--------|-------------|---------|
+| `--token <token>` | Figma API token (or `FIGMA_TOKEN` env) | — |
+| `--file <key>` | Figma file key | — |
+| `--node <id>` | Target node ID | root |
+| `--framework` | `react` or `vue` | `react` |
+| `--style` | `css-modules`, `tailwind`, or `css` | `css-modules` |
+| `--typescript` | Enable TypeScript output | `false` |
+| `--output <dir>` | Output directory | `./output` |
+| `--preview` | Preview in browser after generation | — |
+
+## AI Enhancements (Optional)
+
+For smarter component naming and code optimization, add an LLM provider:
+
+```bash
+# AWS Bedrock
+node dist/cli.js \
+  --token YOUR_FIGMA_TOKEN \
+  --file ABC123DEF456 \
+  --framework react \
+  --llm-provider bedrock \
+  --llm-model anthropic.claude-3-5-sonnet-20241022-v2:0 \
+  --ai-naming \
+  --output ./output
+
+# OpenAI
+LLM_API_KEY="sk-..." node dist/cli.js \
+  --token YOUR_FIGMA_TOKEN \
+  --file ABC123DEF456 \
+  --framework react \
+  --llm-provider openai \
+  --llm-model gpt-4o \
+  --ai-naming \
+  --output ./output
+```
+
+| AI Option | What It Does |
+|-----------|-------------|
+| `--ai-naming` | Renames `Frame123` → `UserProfileCard` |
+| `--ai-splitting` | Splits large designs into sub-components |
+| `--ai-optimization` | Improves code quality and accessibility |
+
+## Troubleshooting
+
+**"Figma token is required"**
+Set `--token` or `export FIGMA_TOKEN="your-token"`
+
+**"Rate limited" / 429 errors**
+The tool auto-retries with backoff. If persistent, wait a minute and try again. Downloaded images are cached locally to avoid repeated API calls.
+
+**Images not showing**
+Check that the `assets/` folder was generated alongside your component. Image paths are relative imports.
+
+**Preview not working**
+Make sure `test-app/test-react/node_modules` (or `test-vue`) exists. Run `npm install` inside the test-app directory first:
+```bash
+cd test-app/test-react && npm install
+```
+
+## Try the Pre-built Examples
+
+The `test-app/` directory contains pre-generated components from the 4 examples shown in the README. You can preview them directly without a Figma token:
+
+```bash
+# React examples
+cd test-app/test-react
+npm install
+npx vite --open
+
+# Vue examples
+cd test-app/test-vue
+npm install
+npx vite --open
+```
+
+Edit `src/main.jsx` (or `src/main.js` for Vue) to switch between components:
+
+```jsx
+// Try different pages:
+import { Component } from './Component.jsx'     // MIUI12
+import { Homepage } from './Homepage.jsx'        // World Peas Homepage
+import { ShoppingCart } from './ShoppingCart.jsx' // Shopping Cart
+import { ProductPage } from './ProductPage.jsx'  // Product Page
+```

package/README.md

@@ -0,0 +1,149 @@
+# Figma-to-Code Agent
+
+Convert Figma designs to production-ready React/Vue components. Supports CSS Modules, Tailwind, and plain CSS.
+
+> 📖 New here? Check the [Quick Start Guide](QUICKSTART.md) for step-by-step setup.
+>
+> 🖥️ Want to see it in action? Run the examples in [test-app/](test-app/) — pre-generated React and Vue components ready to preview.
+
+## Examples
+
+### Example 1 — MIUI12 官网 (全局导航)
+
+| Original Design | React | Vue |
+|:-:|:-:|:-:|
+| ![Original](assets/example1/全局导航-黑.png) | ![React](assets/example1/generate/Figma%20to%20Code%20-%20React%20Test%20-%20%5Blocalhost%5D.png) | ![Vue](assets/example1/generate/Figma%20to%20Code%20-%20Vue%20Test%20-%20%5Blocalhost%5D.png) |
+
+### Example 2 — Homepage (World Peas)
+
+| Original Design | React | Vue |
+|:-:|:-:|:-:|
+| ![Original](assets/example2/20260211-185255.png) | ![React](assets/example2/generate/Figma%20to%20Code%20-%20React%20Test%20-%20%5Blocalhost%5D.png) | ![Vue](assets/example2/generate/Figma%20to%20Code%20-%20Vue%20Test%20-%20%5Blocalhost%5D.png) |
+
+### Example 3 — Shopping Cart
+
+| Original Design | React | Vue |
+|:-:|:-:|:-:|
+| ![Original](assets/example3/20260212-095453.png) | ![React](assets/example3/generate/Figma%20to%20Code%20-%20React%20Test%20-%20%5Blocalhost%5D.png) | ![Vue](assets/example3/generate/Figma%20to%20Code%20-%20Vue%20Test%20-%20%5Blocalhost%5D.png) |
+
+### Example 4 — Product Page
+
+| Original Design | React | Vue |
+|:-:|:-:|:-:|
+| ![Original](assets/example4/20260212-095459.png) | ![React](assets/example4/generate/Figma%20to%20Code%20-%20React%20Test%20-%20%5Blocalhost%5D.png) | ![Vue](assets/example4/generate/Figma%20to%20Code%20-%20Vue%20Test%20-%20%5Blocalhost%5D.png) |
+
+## Features
+
+- 🎨 Extract designs from Figma API with caching and rate-limit handling
+- ⚛️ Generate React (.jsx/.tsx) and Vue (.vue) components
+- 🎭 CSS Modules, Tailwind, or plain CSS
+- 📐 Absolute positioning with responsive scaling (auto-fits viewport)
+- 🖼️ Image export at 2x resolution, vector icon auto-detection and PNG export
+- 🔤 Full typography support (font family, size, weight, line-height, letter-spacing, color)
+- 👁️ Figma layer filtering (hidden layers, mask shapes)
+- 🤖 Optional AI enhancements (semantic naming, component splitting, code optimization)
+
+## Quick Start
+
+```bash
+npm install
+npm run build
+
+# Generate React component
+node dist/cli.js \
+  --token YOUR_FIGMA_TOKEN \
+  --file FILE_KEY \
+  --node NODE_ID \
+  --framework react \
+  --output ./output
+
+# Generate and preview in browser
+node dist/cli.js \
+  --token YOUR_FIGMA_TOKEN \
+  --file FILE_KEY \
+  --node NODE_ID \
+  --framework react \
+  --output ./output \
+  --preview
+```
+
+## How It Works
+
+1. Fetches the Figma file data via API (with local caching)
+2. Parses the design tree into an intermediate AST
+3. Filters invisible layers, mask shapes, and transparent fills
+4. Detects vector-only containers and exports them as PNG icons
+5. Downloads images at 2x resolution
+6. Generates framework-specific components with CSS Modules
+7. Wraps output in a responsive scale container (no horizontal scrollbar)
+
+## CLI Options
+
+| Option | Description | Default |
+|--------|-------------|---------|
+| `--token <token>` | Figma API token (or `FIGMA_TOKEN` env) | — |
+| `--file <key>` | Figma file key | — |
+| `--node <id>` | Target node ID (e.g. `1502-102`) | root |
+| `--framework` | `react` or `vue` | `react` |
+| `--style` | `css-modules`, `tailwind`, or `css` | `css-modules` |
+| `--typescript` | Enable TypeScript output | `false` |
+| `--output <dir>` | Output directory | `./output` |
+| `--preview` | Preview in browser after generation | — |
+
+### AI Options (optional)
+
+| Option | Description |
+|--------|-------------|
+| `--llm-provider` | `bedrock`, `openai`, or `anthropic` |
+| `--llm-model` | Model name |
+| `--ai-naming` | AI-powered semantic component naming |
+| `--ai-splitting` | AI-powered component splitting |
+| `--ai-optimization` | AI-powered code optimization |
+
+## Programmatic API
+
+```typescript
+import { FigmaToCodeAgent } from 'figma-to-code-agent'
+
+const agent = new FigmaToCodeAgent({
+  figmaToken: 'your-token',
+  fileKey: 'your-file-key',
+  framework: 'react',
+  styleMode: 'css-modules',
+  typescript: false,
+  outputDir: './output',
+})
+
+const files = await agent.convert()
+```
+
+## Project Structure
+
+```
+src/
+├── extraction/          # Figma API client, MCP protocol, caching
+├── transformation/      # AST parsing, layout optimization, transformers
+│   └── transformers/    # Component extraction, semantic naming, etc.
+├── generation/          # React and Vue code generators
+├── llm/                 # LLM providers (Bedrock, OpenAI)
+├── validation/          # Visual validation
+└── cli.ts               # CLI entry point
+```
+
+## Development
+
+```bash
+npm run build        # Compile TypeScript
+npm test             # Run all tests (129 tests)
+npm run lint         # ESLint
+npm run format       # Prettier
+```
+
+## Requirements
+
+- Node.js 18+
+- npm
+
+## License
+
+MIT

package/dist/FigmaToCodeAgent.d.ts

@@ -0,0 +1,55 @@
+import type { GeneratedFile } from './generation/types';
+export interface AgentConfig {
+    figmaToken: string;
+    fileKey: string;
+    nodeIds?: string[];
+    framework: 'react' | 'vue';
+    styleMode: 'css-modules' | 'tailwind' | 'css';
+    typescript: boolean;
+    outputDir: string;
+    llm?: {
+        provider: 'bedrock' | 'openai' | 'anthropic';
+        model: string;
+        region?: string;
+        apiKey?: string;
+        enableAINaming?: boolean;
+        enableAISplitting?: boolean;
+        enableAIOptimization?: boolean;
+        enableAILayout?: boolean;
+    };
+}
+export declare class FigmaToCodeAgent {
+    private config;
+    private figmaClient;
+    private parser;
+    private pipeline;
+    private llm?;
+    private aiOptimizer?;
+    constructor(config: AgentConfig);
+    convert(): Promise<GeneratedFile[]>;
+    /**
+     * Download images for all Image nodes in the AST
+     */
+    private downloadImages;
+    private collectImageNodes;
+    /**
+     * Find containers whose children are all Shape/Vector nodes (icons).
+     * These should be exported as images since CSS can't render SVG paths.
+     */
+    /**
+     * Find containers whose children are all Shape/Vector nodes (icons).
+     * These should be exported as images since CSS can't render SVG paths.
+     * Only matches small containers (< 200px) to avoid exporting large sections.
+     */
+    /**
+     * Find containers whose descendants are all Shape/Vector nodes.
+     * These should be exported as images since CSS can't render SVG paths.
+     * Skips containers that also have Text or Image children (mixed content).
+     */
+    private collectIconNodes;
+    private hasShapeDescendant;
+    private hasTextOrImageDescendant;
+    private sanitizeFileName;
+    private findNodeById;
+}
+//# sourceMappingURL=FigmaToCodeAgent.d.ts.map

package/dist/FigmaToCodeAgent.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"FigmaToCodeAgent.d.ts","sourceRoot":"","sources":["../src/FigmaToCodeAgent.ts"],"names":[],"mappings":"AAUA,OAAO,KAAK,EAAmB,aAAa,EAAE,MAAM,oBAAoB,CAAC;AAMzE,MAAM,WAAW,WAAW;IAC1B,UAAU,EAAE,MAAM,CAAC;IACnB,OAAO,EAAE,MAAM,CAAC;IAChB,OAAO,CAAC,EAAE,MAAM,EAAE,CAAC;IACnB,SAAS,EAAE,OAAO,GAAG,KAAK,CAAC;IAC3B,SAAS,EAAE,aAAa,GAAG,UAAU,GAAG,KAAK,CAAC;IAC9C,UAAU,EAAE,OAAO,CAAC;IACpB,SAAS,EAAE,MAAM,CAAC;IAClB,GAAG,CAAC,EAAE;QACJ,QAAQ,EAAE,SAAS,GAAG,QAAQ,GAAG,WAAW,CAAC;QAC7C,KAAK,EAAE,MAAM,CAAC;QACd,MAAM,CAAC,EAAE,MAAM,CAAC;QAChB,MAAM,CAAC,EAAE,MAAM,CAAC;QAChB,cAAc,CAAC,EAAE,OAAO,CAAC;QACzB,iBAAiB,CAAC,EAAE,OAAO,CAAC;QAC5B,oBAAoB,CAAC,EAAE,OAAO,CAAC;QAC/B,cAAc,CAAC,EAAE,OAAO,CAAC;KAC1B,CAAC;CACH;AAED,qBAAa,gBAAgB;IAOf,OAAO,CAAC,MAAM;IAN1B,OAAO,CAAC,WAAW,CAAiB;IACpC,OAAO,CAAC,MAAM,CAAY;IAC1B,OAAO,CAAC,QAAQ,CAAyB;IACzC,OAAO,CAAC,GAAG,CAAC,CAAc;IAC1B,OAAO,CAAC,WAAW,CAAC,CAAkB;gBAElB,MAAM,EAAE,WAAW;IAwCjC,OAAO,IAAI,OAAO,CAAC,aAAa,EAAE,CAAC;IA8CzC;;OAEG;YACW,cAAc;IAiE5B,OAAO,CAAC,iBAAiB;IAUzB;;;OAGG;IACH;;;;OAIG;IACH;;;;OAIG;IACH,OAAO,CAAC,gBAAgB;IAexB,OAAO,CAAC,kBAAkB;IAK1B,OAAO,CAAC,wBAAwB;IAKhC,OAAO,CAAC,gBAAgB;IAYxB,OAAO,CAAC,YAAY;CAUrB"}