🎨 CodeRio

高保真还原设计稿的前端工程生成智能体

💬 联系方式：微信群｜邮箱

📑 目录

CodeRio 是什么？
示例展示
快速开始
核心特性
工作原理
路线图
贡献
许可证

CodeRio 是什么？

CodeRio 是一款智能的Figma 转代码自动化工具，能够将设计稿转换为生产级 React 代码。与传统转换工具不同，CodeRio 采用多智能体系统，能够验证视觉准确度并迭代优化偏差，追求高保真的UI还原和贴合工程师开发规范的代码结构。

framework-hd.mp4

适用场景：

🎯 追求精确还原设计的前端开发者
🚀 希望加速开发流程的团队
💎 期望设计精准实现的设计师

✨ 示例展示

案例：使用 CLI，--mode full

安装 CodeRio 后可以直接在 CLI 中执行命令使用。CodeRio 对复杂样式的落地页具有出色的还原能力，能够处理复杂的布局、识别并下载多样化的图片资源，以及自动封装组件结构。选择 “FULL” 模式，在生成结束后会自动生成还原度可视化评估报告，以标注和拓印两种模式展示设计稿与网页的偏差，为工程师的进一步开发提供有效指导。本示例展示了一个从 Figma (设计稿链接) 转换而来的落地页。

report.mp4

📊 View Interactive Validation Report

案例：在 Cursor 中使用 Skill 开发

CodeRio 支持作为 Skill 集成到 Cursor 中使用。您只需在对话框中输入 “请帮我创建一个 React 工程，高保真还原设计稿”，并提供输出目录、设计稿链接(设计稿链接)及 Figma Token，Agent 即可引导您逐步完成网页生成。对于落地页（Landing Page）类页面，CodeRio 能达到 高保真还原 标准，精确还原图片与样式，并自动对卡片等组件进行 复用封装，生成的代码完全符合 前端开发规范。

coderio-skill-demo.mp4

🚀 快速开始

方式 1：命令行 CLI（推荐 👍🏻）

适用于一键快速生成。

1. 前置要求

Node.js >= 18.0.0 (< 25.0.0)
Figma 个人访问令牌
Figma 链接：在 Figma 中选中 Frame 或 Component，右键选择 Copy link to selection (参考图片)。
LLM API 密钥（Anthropic | OpenAI | Google）

2. 安装

# 全局安装（推荐）
npm install -g coderio

# 或使用 pnpm
pnpm add -g coderio

pnpm v9+ 用户注意：如果看到 "Ignored build scripts" 警告，请运行：pnpm approve-builds，允许原生依赖（better-sqlite3）正确编译。

注意：验证功能（如 d2c --mode full）依赖可选依赖 playwright 和 sharp。为了保持安装轻量，coderio 默认不内置它们。建议您提前全局安装，以确保运行更加顺畅：
npm install -g playwright sharp
npx playwright install chromium

3. 配置

重要提示：本工具需要模型具备 多模态（视觉）能力（推荐 gemini-3-pro-preview）。

创建配置文件 ~/.coderio/config.yaml（Windows：%USERPROFILE%\.coderio\config.yaml）：

model:
    provider: openai # anthropic | openai | google
    model: gemini-3-pro-preview
    baseUrl: https://api.anthropic.com
    apiKey: your-api-key-here

figma:
    token: your-figma-token-here

debug:
    enabled: false # 如果需要保留请求和模型回复，可以设置为 true

4. 使用

# 将 Figma 设计转换为代码（默认模式：仅代码）
coderio d2c -s 'https://www.figma.com/design/your-file-id/...'

# 完整模式：生成代码 + 视觉验证 + 自动优化
coderio d2c -s 'https://www.figma.com/design/your-file-id/...' -m full

5. 运行项目

# 进入生成的项目目录
cd coderio/<设计文件名-页面节点编号>/my-app

# 安装依赖
pnpm install

# 启动开发服务器
pnpm dev

# 🎉 打开 http://localhost:5173

6. 查看验证报告

验证报告目录：coderio/<设计文件名-页面节点编号>/process/validation/index.html

📖 全部命令

命令	别名	描述
`design2code`	`d2c`	完整流程：Figma → 协议 → 代码 → 验证
`design2protocol`	`d2p`	仅提取设计协议
`protocol2code`	`p2c`	从现有协议生成代码
`validate`	`val`	对生成的代码运行验证
`images`	-	下载和处理 Figma 资源

方式 2：Docker

基于 Docker 提供了完整运行时环境，适用于未安装 Node.js 的场景。

1. 前置要求

Windows 用户指南： 以下命令使用了 bash 语法（heredoc、${PWD}、--network=host 等），无法在 CMD 或 PowerShell 中直接运行。请通过 WSL2 执行：

安装 WSL2 和 Linux 发行版（如 Ubuntu）

安装 Docker Desktop，并在 Settings → Resources → WSL Integration 中开启 WSL2 集成

打开 WSL2 终端（在 CMD/PowerShell 中运行 wsl，或从开始菜单打开 Ubuntu）

在 WSL2 终端中执行以下所有命令

2. 安装

docker pull crpi-p4hwwrt00km3axuk.cn-shanghai.personal.cr.aliyuncs.com/coderio/coderio

3. 配置

创建工作目录和 config.yaml 配置文件：

mkdir -p ./coderio-app && cd ./coderio-app
cat > config.yaml << 'EOF'
model:
  provider: openai          # anthropic | openai | google
  model: gemini-3-pro-preview
  baseUrl: https://api.anthropic.com
  apiKey: your-api-key-here

figma:
  token: your-figma-token-here

debug:
  enabled: false
EOF

4. 使用

docker run -ti --rm \
  --network=host \
  -v ${PWD}:/app \
  -v ./config.yaml:/root/.coderio/config.yaml \
  crpi-p4hwwrt00km3axuk.cn-shanghai.personal.cr.aliyuncs.com/coderio/coderio bash

进入容器后，使用 CodeRio 命令：

# 将 Figma 设计转换为代码（默认模式：仅代码）
coderio d2c -s 'https://www.figma.com/design/your-file-id/...'

# 完整模式：生成代码 + 视觉验证 + 自动优化
coderio d2c -s 'https://www.figma.com/design/your-file-id/...' -m full

5. 运行项目

# 进入生成的项目目录
cd coderio/<设计文件名-页面节点编号>/my-app

# 安装依赖
pnpm install

# 启动开发服务器
pnpm dev

# 🎉 打开 http://localhost:5173

6. 查看验证报告

生成的文件会挂载到宿主机。在浏览器中打开验证报告：

./coderio/<设计文件名-页面节点编号>/process/validation/index.html

方式 3：Skill（便携式嵌入工作流）

适用于需要 AI 辅助和更精准控制的场景。

前置准备：将 skills\design-to-code 文件夹拷贝到 ~\.cursor\skills(windows 为%USERPROFILE%\.cursor\skills) 目录下，

Cursor 中使用：

打开 Cursor Chat
输入："使用 design-to-code skill 帮我转换这个设计：[你的 Figma 链接]"
智能体将引导你分步完成协议提取和代码生成。

Claude Code 中使用：

启动 Claude Code。
输入："阅读 docs/skills/SKILL.md 并执行设计转换任务：[你的 Figma 链接]"

💎 核心特性

1. 智能设计协议生成

生成结合页面组件结构、CSS代码、静态资源的综合前端协议：

组件层级识别：自动识别组件结构和数据状态，形成贴合前端开发习惯的组件层次骨架
样式提取：将 Figma JSON 解译为CSS 属性，包括颜色、间距、阴影、动画等
资源优化：自动识别并处理图片节点

interface Protocol {
    id: string; // 组件标识符（如 "Header", "Hero"）
    data: {
        name: string; // 组件名称
        purpose: string; // 语义描述
        elements: FigmaFrameInfo[]; // 原始 Figma 节点数据
        layout?: LayoutInfo; // 位置、尺寸、间距、方向
        componentName?: string; // 可复用组件标识符
        props?: PropDefinition[]; // 组件 props 定义
        states?: StateData[]; // 组件状态变体
    };
    children?: Protocol[]; // 嵌套子组件
}

2. 视觉验证与校准

通过自动化视觉测试确保像素级精度：

位置校准：使用计算机视觉测量元素的精确定位
视觉差异报告：交互式 HTML 报告，包含热力图和并排对比
自动优化：迭代修复偏差直至达到准确度阈值
量化指标：MAE、视觉图片辅助

视觉报告功能：

标注偏差的截图
显示像素差异的热力图叠加层
组件级准确度分析

3. 断点续传

内置的中断恢复系统：

自动检查点：每个主要操作后自动保存状态
任意位置恢复：精确恢复到中断位置
崩溃恢复：处理网络故障、API 超时、进程中断

4. 生成的代码结构贴合前端开发规范

不仅仅是视觉还原，生成的代码更是为了长期维护而生：

组件化开发：自动拆分 Header、Footer、Hero 等语义化组件，拒绝面条式代码。
科学的样式定义：优先使用 Flexbox/Grid 布局，避免过度依赖绝对定位，确保不同屏幕尺寸下的响应性。
现代技术栈：默认使用 React + TypeScript + Tailwind CSS，类型安全且易于扩展。
清晰的文件结构：自动组织 components/、assets/、utils/ 等目录，符合行业最佳实践。

🗺️ 路线图

🤝 贡献

我们欢迎贡献！感谢所有贡献者！🎉

Provide feedback

Saved searches

Use saved searches to filter your results more quickly

🎨 CodeRio

📑 目录

CodeRio 是什么？

✨ 示例展示

案例：使用 CLI，--mode full

案例：在 Cursor 中使用 Skill 开发

🚀 快速开始

方式 1：命令行 CLI（推荐 👍🏻）

1. 前置要求

2. 安装

3. 配置

4. 使用

5. 运行项目

6. 查看验证报告

📖 全部命令

方式 2：Docker

1. 前置要求

2. 安装

3. 配置

4. 使用

5. 运行项目

6. 查看验证报告

方式 3：Skill（便携式嵌入工作流）

💎 核心特性

1. 智能设计协议生成

2. 视觉验证与校准

3. 断点续传

4. 生成的代码结构贴合前端开发规范

🗺️ 路线图

🤝 贡献

📄 许可证

FilesExpand file tree

README_zh-CN.md

Latest commit

History

README_zh-CN.md

File metadata and controls

🎨 CodeRio

📑 目录

CodeRio 是什么？

✨ 示例展示

案例：使用 CLI，--mode full

案例：在 Cursor 中使用 Skill 开发

🚀 快速开始

方式 1：命令行 CLI（推荐 👍🏻）

1. 前置要求

2. 安装

3. 配置

4. 使用

5. 运行项目

6. 查看验证报告

📖 全部命令

方式 2：Docker

1. 前置要求

2. 安装

3. 配置

4. 使用

5. 运行项目

6. 查看验证报告

方式 3：Skill（便携式嵌入工作流）

💎 核心特性

1. 智能设计协议生成

2. 视觉验证与校准

3. 断点续传

4. 生成的代码结构贴合前端开发规范

🗺️ 路线图

🤝 贡献

📄 许可证