coderio 0.1.0-alpha.9 → 1.0.0

package/README.md

@@ -6,6 +6,8 @@ AI-Powered Design-to-Code Tool with High-Fidelity UI Restoration
 
 [![License](https://img.shields.io/badge/license-Apache%202.0-blue.svg)](LICENSE) [![Node Version](https://img.shields.io/badge/node-%3E%3D18.0.0%20%3C23.0.0-brightgreen)](https://nodejs.org/) [![npm version](https://img.shields.io/npm/v/coderio.svg)](https://www.npmjs.com/package/coderio) [![Contributors](https://img.shields.io/github/contributors/MigoXLab/coderio)](https://github.com/MigoXLab/coderio/graphs/contributors)
 
+💬 Contact: <a href="https://aicarrier.feishu.cn/docx/KTZCddG2VoarFExTqBEcS55QnRd" target="_blank">WeChat Group</a> | <a href="mailto:coderio&#64;pjlab&#46;org&#46;cn">Email</a>
+
 [English](README.md) | [简体中文](README_zh-CN.md)
 
 </div>
@@ -28,7 +30,9 @@ AI-Powered Design-to-Code Tool with High-Fidelity UI Restoration
 
 ## What is CodeRio?
 
-CodeRio is an intelligent **Figma-to-Code** automation tool that transforms designs into production-ready React code. Unlike traditional converters, CodeRio employs a multi-agent system that validates visual accuracy and iteratively refines misalignments, pursuing high-fidelity UI restoration.
+CodeRio is an intelligent **Figma-to-Code** automation tool that transforms designs into production-ready React code. Unlike traditional converters, CodeRio employs a multi-agent system that validates visual accuracy and iteratively refines misalignments, pursuing high-fidelity UI restoration and **production-ready code structure tailored for developers**.
+
+https://github.com/user-attachments/assets/a0bc1b1c-6aaa-4fbb-a2d8-18aeba70759b
 
 **Perfect for:**
 
@@ -38,15 +42,32 @@ CodeRio is an intelligent **Figma-to-Code** automation tool that transforms desi
 
 ## ✨ Examples
 
+### Case: CLI with --mode full
+
+After installing CodeRio, you can execute commands directly in the CLI. CodeRio excels at restoring complex landing page styles, handling intricate layouts, identifying and downloading diverse image resources, and encapsulating component structures. By selecting "FULL" mode, a visual fidelity evaluation report is generated upon completion. This report displays deviations between the design and the webpage using both annotation and overlay modes, providing effective guidance for further development by engineers. This example demonstrates a landing page converted from Figma ([Design Link](https://www.figma.com/design/c0UBII8lURfxZIY8W6tSDR/Top-16-Websites-of-2024---Awwwards--Community-?node-id=1-1482&t=FB3Hohq2nsH7ZFts-4)).
+
+https://github.com/user-attachments/assets/bd0c3f18-e98a-4050-bf22-46b198fadac2
+
+<a href="https://static.openxlab.org.cn/coderio/report.html" target="_blank">📊 View Interactive Validation Report</a>
+
+### Case: Development with Cursor Skill
+
+CodeRio can be seamlessly integrated into Cursor as a Skill. Simply input a prompt like **"Create a React project and restore this design with high fidelity,"** along with your output directory, Figma URL([Design Link](https://www.figma.com/design/c0UBII8lURfxZIY8W6tSDR/Top-16-Websites-of-2024---Awwwards--Community-?node-id=30-8264&t=FB3Hohq2nsH7ZFts-4)), and Token. The Agent will guide you step-by-step through the page generation process. For Landing Pages, it achieves **high-fidelity restoration**, accurately reproducing images and styles. It also automatically encapsulates reusable components (such as cards) and strictly adheres to **frontend development best practices**.
+
+https://github.com/user-attachments/assets/a66dc680-f68d-4121-b416-aa6b778bd895
+
 ## 🚀 Quick Start
 
-### 1. Prerequisites
+### Option 1: CLI (Recommended 👍🏻)
+Best for one-click generation.
+
+#### 1. Prerequisites
 
-- Node.js >= 18.0.0 (< 23.0.0)
+- Node.js >= 18.0.0 (< 25.0.0)
 - [Figma Personal Access Token](https://www.figma.com/developers/api#access-tokens)
 - LLM API Key ([Anthropic](https://console.anthropic.com/) | [OpenAI](https://platform.openai.com/) | [Google](https://aistudio.google.com/))
 
-### 2. Installation
+#### 2. Installation
 
 ```bash
 # Install globally (recommended)
@@ -62,9 +83,11 @@ pnpm add -g coderio
 > pnpm approve-builds
 > ```
 >
-> This allows native dependencies (better-sqlite3, sharp) to compile properly.
+> This allows native dependencies (better-sqlite3) to compile properly.
+>
+> **Note**: `playwright` and `sharp` are required only for validation features. They will be automatically installed when you first run a command that needs them (like `d2c --mode full`).
 
-### 3. Configuration
+#### 3. Configuration
 
 Create `~/.coderio/config.yaml`:
 
@@ -72,8 +95,8 @@ Create `~/.coderio/config.yaml`:
 mkdir -p ~/.coderio
 cat > ~/.coderio/config.yaml << 'EOF'
 model:
-  provider: anthropic          # anthropic | openai | google
-  model: claude-3-5-sonnet-20241022
+  provider: openai          # anthropic | openai | google
+  model: gemini-3-pro-preview
   baseUrl: https://api.anthropic.com
   apiKey: your-api-key-here
 
@@ -85,22 +108,17 @@ debug:
 EOF
 ```
 
-### 4. Usage
+#### 4. Usage
 
 ```bash
-# Convert Figma design to validated code
+# Convert Figma design to code (default mode: code only)
 coderio d2c -s 'https://www.figma.com/design/your-file-id/...'
-```
-
-CodeRio will:
 
-1. ✅ Fetch Figma design and generate protocol
-2. ✅ Create React + TypeScript + Tailwind CSS code
-3. ✅ Launch dev server and capture screenshots
-4. ✅ Validate visual accuracy and refine misalignments
-5. ✅ Generate interactive validation report
+# Full mode: Generate code + visual validation + auto-refinement
+coderio d2c -s 'https://www.figma.com/design/your-file-id/...' -m full
+```
 
-### 5. Run Your Project
+#### 5. Run Your Project
 
 ```bash
 # Navigate to generated project
@@ -115,14 +133,14 @@ pnpm dev
 # 🎉 Open http://localhost:5173
 ```
 
-### 6. View Validation Report
+#### 6. View Validation Report
 
 ```bash
 # Open validation report in browser
-open coderio/<design-name_node-id>/validation/index.html
+open coderio/<design-name_node-id>/process/validation/index.html
 ```
 
-## 📖 All Commands
+#### 📖 All Commands
 
 | Command           | Alias | Description                                         |
 | ----------------- | ----- | --------------------------------------------------- |
@@ -132,20 +150,24 @@ open coderio/<design-name_node-id>/validation/index.html
 | `validate`        | `val` | Run validation on generated code                    |
 | `images`          | -     | Download and process Figma assets                   |
 
-### Step-by-Step Workflow
-
-For more control, run each step individually:
+### Option 2: Skill (Portable Embedded Workflow)
+Best for control and precision using AI Agents.
 
+**Prerequisites**:
+Copy the Skill file to your Cursor configuration directory:
 ```bash
-# Step 1: Extract design protocol
-coderio d2p -s 'https://www.figma.com/design/.../...'
+mkdir -p ~/.cursor/skills/design-to-code
+cp docs/skills/SKILL.md ~/.cursor/skills/design-to-code/SKILL.md
+```
 
-# Step 2: Generate code from protocol
-coderio p2c -p './coderio/<design-name_node-id>/process/protocol.json'
+**Using in Cursor**:
+1. Open Cursor Chat (`Cmd` + `L`).
+2. Type: **"Use design-to-code skill to convert this design: [Your Figma URL]"**
+3. The Agent will guide you step-by-step through protocol extraction and code generation.
 
-# Step 3: Run validation (coming soon)
-# coderio val -p './coderio/<design-name_node-id>/my-app'
-```
+**Using in Claude Code**:
+1. Start Claude Code.
+2. Type: **"Read docs/skills/SKILL.md and perform design conversion: [Your Figma URL]"**
 
 ## 💎 Key Features
 
@@ -196,24 +218,14 @@ Built-in interruption recovery system:
 - **Resume from Anywhere**: Pick up exactly where you left off
 - **Crash Recovery**: Handles network failures, API timeouts, process interruptions
 
-## 🛠️ How It Works
-
-CodeRio uses a sophisticated multi-agent pipeline:
+### 4. Production-Ready Code Structure
 
-```
-Figma Design → Protocol → Code → Launch → Validate → Refine → Report
-     ↓           ↓         ↓       ↓        ↓          ↓        ↓
-  Fetch API  Structure  Initial  Launch   Judge    Refiner  Visualize
-             Style      Agent    Agent    Agent    Agent
-             Hierarchy
-```
+Beyond visual fidelity, the generated code is built for long-term maintenance:
 
-1. **Protocol Generation**: Extracts structure, styles, and assets from Figma
-2. **Code Generation**: Creates React components with Tailwind CSS
-3. **Launch**: Installs dependencies and starts dev server
-4. **Validation**: Captures screenshots and compares with design
-5. **Refinement**: Automatically fixes misalignments
-6. **Reporting**: Generates interactive visual report
+- **Component-Based Architecture**: Automatically decomposes semantic components (Header, Footer, Hero, etc.), avoiding spaghetti code.
+- **Scientific Styling**: Prefers Flexbox/Grid layouts over rigid absolute positioning, ensuring responsiveness across different screen sizes.
+- **Modern Tech Stack**: Defaults to React + TypeScript + Tailwind CSS for type safety and scalability.
+- **Clean File Structure**: Automatically organizes `components/`, `assets/`, `utils/` directories following industry best practices.
 
 ## 🗺️ Roadmap