figma-to-code-agent 0.6.0 → 0.7.0

package/CHANGELOG.md

@@ -1,5 +1,37 @@
 # Changelog
 
+## [0.7.0] - 2026-02-27
+
+### Added
+- MCP (Model Context Protocol) server implementation for integration with Claude Desktop and Kiro IDE
+- Kiro Skill interface for seamless design-to-code workflow in Kiro IDE
+- Design consistency checker for analyzing design token consistency
+- Interactive prototype generator with state management
+- Custom template system for code generation
+- Comprehensive property-based tests for agent components (ConversationContext, DecisionEngine, ExecutionOrchestrator, IntentUnderstandingEngine)
+- Property-based tests for ToolRegistry
+- End-to-end agent workflow tests
+- Cross-delivery consistency integration tests
+- Agent architecture with conversation context, intent understanding, decision engine, and execution orchestrator
+
+### Changed
+- Updated README with bilingual support (English and Chinese)
+- Refined documentation structure and removed redundant content
+- Fixed broken documentation links
+- Improved CLI guide with comprehensive examples and troubleshooting
+
+### Documentation
+- Added MCP Service Configuration Guide (docs/MCP_GUIDE.md)
+- Added Kiro Skill Usage Guide (docs/KIRO_SKILL_GUIDE.md)
+- Added CLI Usage Guide (docs/CLI_GUIDE.md)
+- Created README.zh-CN.md for Chinese documentation
+- Updated QUICKSTART.md with clearer instructions
+
+### Tests
+- Total test count: 222 tests (all passing)
+- Added 7 new test files for agent components and integrations
+- Updated jest.config.js to handle uuid module transformation
+
 ## [0.6.0] - 2026-02-13
 
 ### Added

package/README.md

@@ -3,10 +3,33 @@
 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.
+> 
+> English | [中文](README.zh-CN.md)
+
+## Usage
+
+### 1. CLI Tool
+For local development and CI/CD integration.
+
+```bash
+npx figma-to-code-agent --token YOUR_TOKEN --file FILE_KEY --framework react --output ./output
+```
+
+[Full CLI Guide →](docs/CLI_GUIDE.md)
+
+### 2. MCP Service
+Integrate with Claude Desktop or Kiro IDE, generate code through AI conversations.
+
+[MCP Configuration Guide →](docs/MCP_GUIDE.md)
+
+### 3. Kiro Skill
+Use as a Skill in Kiro IDE for seamless design-to-code workflow.
+
+[Kiro Skill Guide →](docs/KIRO_SKILL_GUIDE.md)
 
 ## Examples
 
-### Example 1 — MIUI12 官网 (全局导航)
+### Example 1 — MIUI12 Website (Global Navigation)
 
 | Original Design | React | Vue |
 |:-:|:-:|:-:|
@@ -34,32 +57,33 @@ Convert Figma designs to production-ready React/Vue components. Supports CSS Mod
 
 - 🎨 Extract designs from Figma API with caching and rate-limit handling
 - ⚛️ Generate React (.jsx/.tsx) and Vue (.vue) components
-- 🎭 CSS Modules, Tailwind CSS (arbitrary values), or plain CSS with separate stylesheet
-- 📐 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)
+- 🎭 Support CSS Modules, Tailwind CSS, and plain CSS
+- 📐 Responsive layout with viewport adaptation
+- 🖼️ 2x resolution image export, auto-detect vector icons
 - 🎯 Design token extraction (CSS variables, SCSS, JSON, JS)
-- 🧩 Component splitting (auto-split large designs >50 nodes, max depth 4)
-- 📁 File organizer (PascalCase/kebab-case naming, directory structure, Props interface)
-- 🖼️ Asset management (image dedup, SVG-first, semantic naming, import generation)
-- 🔍 Visual validation (Puppeteer rendering, pixel comparison, similarity scoring)
-- ♿ Accessibility enhancement (ARIA roles, alt text, landmark detection)
-- ⚡ Performance optimization (lazy loading, code splitting hints, redundant wrapper removal)
-- 🎨 Style deduplication (merge identical CSS rules across components)
-- 📱 Responsive code generation (media queries from breakpoint metadata)
+- ♿ Accessibility enhancements (ARIA roles, alt text)
+- ⚡ Performance optimization (lazy loading, code splitting, style deduplication)
 - 🤖 Optional AI enhancements (semantic naming, component splitting, code optimization)
+- 🔌 MCP server (integrate with Claude Desktop / Kiro IDE)
+- 🎯 Kiro Skill (use as a skill in Kiro IDE)
+- 📊 Design consistency checker
+- 🎮 Interactive prototype generator
 
 ## Install
 
+### Global Installation
 ```bash
 npm install -g figma-to-code-agent
 ```
 
-Or use directly with npx (no install needed):
+### Local Installation
+```bash
+npm install figma-to-code-agent
+```
 
+### Use with npx (no installation required)
 ```bash
-npx figma-to-code-agent --token YOUR_FIGMA_TOKEN --file FILE_KEY --node NODE_ID --output ./output
+npx figma-to-code-agent --token YOUR_TOKEN --file FILE_KEY --output ./output
 ```
 
 ## Quick Start
@@ -73,91 +97,60 @@ npx figma-to-code-agent \
   --framework react \
   --output ./output
 
-# Generate and preview in browser
+# Generate and preview
 npx figma-to-code-agent \
   --token YOUR_FIGMA_TOKEN \
   --file FILE_KEY \
-  --node NODE_ID \
   --framework react \
   --output ./output \
   --preview
 ```
 
+For more usage options, see the [Quick Start Guide](docs/QUICKSTART.md).
+
 ## 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. Applies transformation pipeline (flatten, extract components, optimize layout, semantic naming, style merging, accessibility, performance)
-5. Detects vector-only containers and exports them as PNG icons
-6. Downloads images at 2x resolution
-7. Generates framework-specific components with chosen style mode
-8. Deduplicates identical CSS rules and generates responsive media queries
-9. Wraps output in a responsive scale container (no horizontal scrollbar)
+1. **Extract**: Fetch design data via Figma API (with caching)
+2. **Parse**: Parse design tree into intermediate AST
+3. **Transform**: Apply transformation pipeline (flatten, extract components, optimize, semantic naming)
+4. **Generate**: Generate framework-specific component code
+5. **Optimize**: Style deduplication, responsive handling, accessibility enhancements
+
+For detailed architecture, see [Architecture Documentation](spec/ARCHITECTURE.md).
 
 ## CLI Options
 
 | Option | Description | Default |
 |--------|-------------|---------|
-| `--token <token>` | Figma API token (or `FIGMA_TOKEN` env) | — |
+| `--token <token>` | Figma API token | — |
 | `--file <key>` | Figma file key | — |
-| `--node <id>` | Target node ID (e.g. `1502-102`) | root |
+| `--node <id>` | Target node ID | root |
 | `--framework` | `react` or `vue` | `react` |
 | `--style` | `css-modules`, `tailwind`, or `css` | `css-modules` |
-| `--typescript` | Enable TypeScript output | `false` |
+| `--typescript` | Enable TypeScript | `false` |
 | `--output <dir>` | Output directory | `./output` |
-| `--extract-tokens <fmt>` | Extract design tokens: `css`, `scss`, `json`, `js` | — |
 | `--preview` | Preview in browser after generation | — |
+| `--mcp` | Start MCP server mode | — |
 
-### AI Options (optional)
+### AI Options
 
 | Option | Description |
 |--------|-------------|
 | `--llm-provider` | `bedrock`, `openai`, or `anthropic` |
 | `--llm-model` | Model name |
-| `--llm-region` | AWS region for Bedrock (default: `us-east-1`) |
-| `--llm-api-key` | API key for OpenAI/Anthropic (or `LLM_API_KEY` env) |
-| `--ai-naming` | AI-powered semantic component naming |
-| `--ai-splitting` | AI-powered component splitting |
+| `--ai-naming` | AI-powered semantic naming |
 | `--ai-optimization` | AI-powered code optimization |
-| `--ai-layout` | AI-powered layout analysis |
-
-## Programmatic API
 
-```typescript
-import { FigmaToCodeAgent } from 'figma-to-code-agent'
+For complete options, see [CLI Usage Guide](docs/CLI_GUIDE.md).
 
-const agent = new FigmaToCodeAgent({
-  figmaToken: 'your-token',
-  fileKey: 'your-file-key',
-  framework: 'react',
-  styleMode: 'css-modules',
-  typescript: false,
-  outputDir: './output',
-  extractTokens: 'css', // optional: 'css' | 'scss' | 'json' | 'js'
-})
+## Documentation
 
-const files = await agent.convert()
-```
-
-## Project Structure
-
-```
-src/
-├── extraction/          # Figma API client, MCP protocol, caching
-├── transformation/      # AST parsing, layout optimization, transformers
-│   └── transformers/    # Flatten, component extraction, semantic naming,
-│                        # style merger, responsive merger, accessibility,
-│                        # performance optimizer, AI-powered transformers
-├── generation/          # React and Vue code generators, file organizer
-├── tokens/              # Design token extraction and export
-├── assets/              # Asset management (image extraction, dedup)
-├── validation/          # Visual validation (Puppeteer, pixel comparison)
-├── config/              # Configuration management
-├── errors/              # Error handling and recovery
-├── llm/                 # LLM providers (Bedrock, OpenAI)
-└── cli.ts               # CLI entry point
-```
+- 📖 [Quick Start](QUICKSTART.md) - Get started in 5 minutes
+- 🖥️ [CLI Guide](docs/CLI_GUIDE.md) - Complete CLI reference
+- 🔌 [MCP Guide](docs/MCP_GUIDE.md) - Integrate with Claude/Kiro
+- 🎯 [Kiro Skill Guide](docs/KIRO_SKILL_GUIDE.md) - Use in Kiro IDE
+- 🏗️ [Architecture](spec/ARCHITECTURE.md) - System architecture
+- 🎨 [Examples](assets/) - Real conversion examples
 
 ## Development
 
@@ -166,16 +159,15 @@ git clone https://github.com/lewiscutey/figma-to-code-agent.git
 cd figma-to-code-agent
 npm install
 npm run build        # Compile TypeScript
-npm test             # Run all tests (222 tests)
-npm run lint         # ESLint
-npm run format       # Prettier
+npm test             # Run tests (222 tests)
+npm run lint         # Lint code
 ```
 
 ## Requirements
 
 - Node.js 18+
-- npm
+- Figma access token ([Get token](https://www.figma.com/developers/api#access-tokens))
 
 ## License
 
-MIT
+MIT License - See [LICENSE](LICENSE) file for details

package/README.zh-CN.md

@@ -0,0 +1,173 @@
+# Figma-to-Code Agent
+
+将 Figma 设计转换为生产就绪的 React/Vue 组件。支持 CSS Modules、Tailwind 和纯 CSS。
+
+> 📖 新手入门？查看 [快速入门指南](QUICKSTART.md) 获取详细步骤。
+> 
+> [English](README.md) | 中文
+
+## 使用方式
+
+### 1. 命令行工具（CLI）
+适合本地开发和 CI/CD 集成。
+
+```bash
+npx figma-to-code-agent --token YOUR_TOKEN --file FILE_KEY --framework react --output ./output
+```
+
+[完整 CLI 指南 →](docs/CLI_GUIDE.md)
+
+### 2. MCP 服务
+集成到 Claude Desktop 或 Kiro IDE，通过 AI 对话生成代码。
+
+[MCP 配置指南 →](docs/MCP_GUIDE.md)
+
+### 3. Kiro Skill
+在 Kiro IDE 中作为 Skill 使用，提供无缝的设计到代码工作流。
+
+[Kiro Skill 指南 →](docs/KIRO_SKILL_GUIDE.md)
+
+## 示例展示
+
+### 示例 1 — MIUI12 官网（全局导航）
+
+| 原始设计 | 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) |
+
+### 示例 2 — 主页（World Peas）
+
+| 原始设计 | 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) |
+
+### 示例 3 — 购物车
+
+| 原始设计 | 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) |
+
+### 示例 4 — 产品页面
+
+| 原始设计 | 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) |
+
+## 功能特性
+
+- 🎨 从 Figma API 提取设计，支持缓存和速率限制处理
+- ⚛️ 生成 React (.jsx/.tsx) 和 Vue (.vue) 组件
+- 🎭 支持 CSS Modules、Tailwind CSS 和纯 CSS
+- 📐 响应式布局，自适应视口
+- 🖼️ 2x 分辨率图片导出，自动检测矢量图标
+- 🎯 设计令牌提取（CSS 变量、SCSS、JSON、JS）
+- ♿ 无障碍增强（ARIA 角色、alt 文本）
+- ⚡ 性能优化（懒加载、代码分割、样式去重）
+- 🤖 可选 AI 增强（语义命名、组件拆分、代码优化）
+- 🔌 MCP 服务器（集成到 Claude Desktop / Kiro IDE）
+- 🎯 Kiro Skill（在 Kiro IDE 中作为技能使用）
+- 📊 设计一致性检查器
+- 🎮 交互原型生成器
+
+## 安装
+
+### 全局安装
+```bash
+npm install -g figma-to-code-agent
+```
+
+### 本地安装
+```bash
+npm install figma-to-code-agent
+```
+
+### 使用 npx（无需安装）
+```bash
+npx figma-to-code-agent --token YOUR_TOKEN --file FILE_KEY --output ./output
+```
+
+## 快速开始
+
+```bash
+# 生成 React 组件
+npx figma-to-code-agent \
+  --token YOUR_FIGMA_TOKEN \
+  --file FILE_KEY \
+  --node NODE_ID \
+  --framework react \
+  --output ./output
+
+# 生成并预览
+npx figma-to-code-agent \
+  --token YOUR_FIGMA_TOKEN \
+  --file FILE_KEY \
+  --framework react \
+  --output ./output \
+  --preview
+```
+
+更多使用方式请查看 [快速入门指南](QUICKSTART.md)。
+
+## 工作原理
+
+1. **提取**：通过 Figma API 获取设计数据（支持缓存）
+2. **解析**：将设计树解析为中间 AST
+3. **转换**：应用转换管道（扁平化、组件提取、优化、语义命名）
+4. **生成**：生成框架特定的组件代码
+5. **优化**：样式去重、响应式处理、无障碍增强
+
+详细架构请参考 [系统架构文档](spec/ARCHITECTURE.md)。
+
+## CLI 选项
+
+| 选项 | 描述 | 默认值 |
+|--------|-------------|---------|
+| `--token <token>` | Figma API 令牌 | — |
+| `--file <key>` | Figma 文件 Key | — |
+| `--node <id>` | 目标节点 ID | root |
+| `--framework` | `react` 或 `vue` | `react` |
+| `--style` | `css-modules`、`tailwind` 或 `css` | `css-modules` |
+| `--typescript` | 启用 TypeScript | `false` |
+| `--output <dir>` | 输出目录 | `./output` |
+| `--preview` | 生成后在浏览器中预览 | — |
+| `--mcp` | 启动 MCP 服务器模式 | — |
+
+### AI 选项
+
+| 选项 | 描述 |
+|--------|-------------|
+| `--llm-provider` | `bedrock`、`openai` 或 `anthropic` |
+| `--llm-model` | 模型名称 |
+| `--ai-naming` | AI 驱动的语义命名 |
+| `--ai-optimization` | AI 驱动的代码优化 |
+
+完整选项请参考 [CLI 使用指南](docs/CLI_GUIDE.md)。
+
+## 文档
+
+- 📖 [快速入门](docs/QUICKSTART.md) - 5 分钟快速上手
+- 🖥️ [CLI 指南](docs/CLI_GUIDE.md) - 命令行完整参考
+- 🔌 [MCP 指南](docs/MCP_GUIDE.md) - 集成到 Claude/Kiro
+- 🎯 [Kiro Skill 指南](docs/KIRO_SKILL_GUIDE.md) - Kiro IDE 使用
+- 🏗️ [系统架构](spec/ARCHITECTURE.md) - 架构设计
+- 🎨 [示例项目](assets/) - 真实转换示例
+
+## 开发
+
+```bash
+git clone https://github.com/lewiscutey/figma-to-code-agent.git
+cd figma-to-code-agent
+npm install
+npm run build        # 编译 TypeScript
+npm test             # 运行测试（222 个测试）
+npm run lint         # 代码检查
+```
+
+## 系统要求
+
+- Node.js 18+
+- Figma 访问令牌（[获取令牌](https://www.figma.com/developers/api#access-tokens)）
+
+## 许可证
+
+MIT License - 详见 [LICENSE](LICENSE) 文件

package/dist/agent/ConversationContext.d.ts

@@ -0,0 +1,91 @@
+import type { ConversationContext as IConversationContext, Message, Intent, TaskState, UserPreferences, Artifact } from './types';
+/**
+ * 对话上下文管理器
+ * 维护用户意图、历史交互和任务状态
+ */
+export declare class ConversationContextManager {
+    private context;
+    private persistencePath?;
+    constructor(sessionId?: string, persistencePath?: string);
+    /**
+     * 创建新的对话上下文
+     */
+    private createNewContext;
+    /**
+     * 获取当前上下文
+     */
+    getContext(): IConversationContext;
+    /**
+     * 添加消息到历史记录
+     */
+    addMessage(role: Message['role'], content: string, metadata?: Record<string, any>): void;
+    /**
+     * 设置用户意图
+     */
+    setIntent(intent: Intent): void;
+    /**
+     * 获取用户意图
+     */
+    getIntent(): Intent | null;
+    /**
+     * 更新任务状态
+     */
+    updateTaskState(updates: Partial<TaskState>): void;
+    /**
+     * 获取任务状态
+     */
+    getTaskState(): TaskState;
+    /**
+     * 创建检查点
+     */
+    createCheckpoint(data: any): string;
+    /**
+     * 从检查点恢复
+     */
+    restoreFromCheckpoint(checkpointId: string): boolean;
+    /**
+     * 更新用户偏好
+     */
+    updateUserPreferences(preferences: Partial<UserPreferences>): void;
+    /**
+     * 获取用户偏好
+     */
+    getUserPreferences(): UserPreferences;
+    /**
+     * 添加生成的产物
+     */
+    addArtifact(artifact: Omit<Artifact, 'id' | 'timestamp'>): string;
+    /**
+     * 获取所有产物
+     */
+    getArtifacts(): Artifact[];
+    /**
+     * 获取特定版本的产物
+     */
+    getArtifactsByVersion(version: number): Artifact[];
+    /**
+     * 获取历史消息
+     */
+    getHistory(): Message[];
+    /**
+     * 清空历史记录（保留用户偏好）
+     */
+    clearHistory(): void;
+    /**
+     * 持久化上下文到文件
+     */
+    private persist;
+    /**
+     * 从文件加载上下文
+     */
+    private loadFromFile;
+    /**
+     * 导出上下文为 JSON
+     */
+    export(): string;
+    /**
+     * 从 JSON 导入上下文
+     */
+    import(json: string): boolean;
+}
+//# sourceMappingURL=ConversationContext.d.ts.map

package/dist/agent/ConversationContext.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"ConversationContext.d.ts","sourceRoot":"","sources":["../../src/agent/ConversationContext.ts"],"names":[],"mappings":"AAGA,OAAO,KAAK,EACV,mBAAmB,IAAI,oBAAoB,EAC3C,OAAO,EACP,MAAM,EACN,SAAS,EACT,eAAe,EACf,QAAQ,EAET,MAAM,SAAS,CAAC;AAEjB;;;GAGG;AACH,qBAAa,0BAA0B;IACrC,OAAO,CAAC,OAAO,CAAuB;IACtC,OAAO,CAAC,eAAe,CAAC,CAAS;gBAErB,SAAS,CAAC,EAAE,MAAM,EAAE,eAAe,CAAC,EAAE,MAAM;IAYxD;;OAEG;IACH,OAAO,CAAC,gBAAgB;IAoBxB;;OAEG;IACH,UAAU,IAAI,oBAAoB;IAIlC;;OAEG;IACH,UAAU,CAAC,IAAI,EAAE,OAAO,CAAC,MAAM,CAAC,EAAE,OAAO,EAAE,MAAM,EAAE,QAAQ,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,GAAG,CAAC,GAAG,IAAI;IAWxF;;OAEG;IACH,SAAS,CAAC,MAAM,EAAE,MAAM,GAAG,IAAI;IAK/B;;OAEG;IACH,SAAS,IAAI,MAAM,GAAG,IAAI;IAI1B;;OAEG;IACH,eAAe,CAAC,OAAO,EAAE,OAAO,CAAC,SAAS,CAAC,GAAG,IAAI;IAQlD;;OAEG;IACH,YAAY,IAAI,SAAS;IAIzB;;OAEG;IACH,gBAAgB,CAAC,IAAI,EAAE,GAAG,GAAG,MAAM;IAYnC;;OAEG;IACH,qBAAqB,CAAC,YAAY,EAAE,MAAM,GAAG,OAAO;IAiBpD;;OAEG;IACH,qBAAqB,CAAC,WAAW,EAAE,OAAO,CAAC,eAAe,CAAC,GAAG,IAAI;IAQlE;;OAEG;IACH,kBAAkB,IAAI,eAAe;IAIrC;;OAEG;IACH,WAAW,CAAC,QAAQ,EAAE,IAAI,CAAC,QAAQ,EAAE,IAAI,GAAG,WAAW,CAAC,GAAG,MAAM;IAWjE;;OAEG;IACH,YAAY,IAAI,QAAQ,EAAE;IAI1B;;OAEG;IACH,qBAAqB,CAAC,OAAO,EAAE,MAAM,GAAG,QAAQ,EAAE;IAIlD;;OAEG;IACH,UAAU,IAAI,OAAO,EAAE;IAIvB;;OAEG;IACH,YAAY,IAAI,IAAI;IAYpB;;OAEG;IACH,OAAO,CAAC,OAAO;IAgBf;;OAEG;IACH,OAAO,CAAC,YAAY;IAUpB;;OAEG;IACH,MAAM,IAAI,MAAM;IAIhB;;OAEG;IACH,MAAM,CAAC,IAAI,EAAE,MAAM,GAAG,OAAO;CAW9B"}