sloth-d2c-figma-plugin 2.0.3-beta48 → 2.0.3-beta51

package/README.md

@@ -1,108 +1,156 @@
-# Figma Plugin Sample React Hot Reload
+# Sloth D2C Figma 插件
 
-支持 React（部分）热更新的 Figma 插件 demo
+> 设计稿转代码工具 - Figma 插件
 
-## 功能介绍
+## 📖 简介
 
-这个 Demo 用于开发 Figma 插件，支持了如下的功能：
+Sloth D2C 设计稿转代码插件，面向前端开发与设计团队的智能化工具，支持设计稿快速转生产级HTML/React代码，及文本/图片+Prompt输入AI生成目标风格页面并转译至Figma节点。
 
-- [x] React
-- [x] Webpack
-- [x] WebpackDevServer
-- [x] React Hot Reload
-- [x] React Router
-- [x] React Hooks
-- [x] 便捷的消息通信机制
+### 核心能力
 
-更多关于此仓库的介绍，请移步到我的博客文章 [Figma 插件开发浅浅谈](https://banyudu.com/posts/figma-plugin-development-intro.f7472f?v=OKGW6q)。
+① 高保真还原，样式布局精准匹配设计稿，降低编码与走查成本；
 
-## 使用说明
+② 代码贴近人工编写，支持TailwindCSS、Flex自动布局、行列分组等技术特性；
 
-### 安装依赖
+③ 支持生成代码在线二次编辑（图片编组、源码调整等）；
 
-```bash
-npm install
-```
+④ 深度协同Sloth D2C MCP，通过配置拦截及数据推送突破RESTful API限制，最大化还原度。
 
-### 启动调试
+## 🚀 安装
 
-```bash
-npm run dev
-```
+### 方式一：从 Figma 社区安装（推荐）
+
+1. 访问 [Figma 社区页面](https://www.figma.com/community/plugin/1497969094291954974/sloth-d2c)
+2. 点击 "Install" 安装插件
+3. 在 Figma 中打开任意设计稿，通过 `Plugins` 菜单找到 "Sloth D2C 设计稿转代码"
+
+### 方式二：本地开发安装
+
+1. 克隆项目并安装依赖：
 
-调试/打包为Figma插件
 ```bash
-pnpm build
-pnpm dev  
+# 克隆项目
+git clone <repository-url>
+cd ai/apps/figma
+
+# 安装依赖（需要在根目录执行）
+cd ../..
+pnpm install
 ```
 
-调试/打包为node依赖
+2. 构建插件：
+
 ```bash
-pnpm dev:lib:node
-pnpm build:lib:node
+# 开发模式（支持热更新）
+pnpm dev:figma
+
+# 生产构建
+pnpm build:figma
 ```
 
-### 功能开发
+3. 在 Figma 中加载本地插件：
+   - 打开 Figma Desktop 应用
+   - 进入 `Plugins` → `Development` → `Import plugin from manifest`
+   - 选择 `apps/figma/manifest.json` 文件
 
-#### 目录约定
+## 💡 快速开始
 
-功能开发主要需要修改两处位置。
+### 基础使用流程
 
-- src/figma: 存储 Figma 沙箱中运行的代码，不可以使用 window / fetch 等各种 api，但是可以访问 figma 文档结构。
-- src/pages: React 开发的页面，和 create-react-app 创建的项目差别不大，可以正常使用 react-router (只能是 memory router) 和 antd 组件库等常用库。
+1. **打开插件**
+   - 在 Figma 中选择需要转换的设计稿或图层
+   - 通过 `Plugins` 菜单启动 "Sloth D2C 设计稿转代码"
 
-#### 内部通信
+2. **选择元素**
+   - 插件会自动识别当前选中的图层
+   - 也可以手动框选需要转换的区域
 
-当 pages 和 figma 中需要通信时，需要用到 postMessage 在两个窗口间通信，比较繁琐。
+3. **配置转换选项**
+   - 选择目标代码框架（HTML/Vue/React 等）
+   - 配置样式处理方式
+   - 设置资源处理策略
 
-我提取了一个帮助工具 `emitToFigma`，可以用于在 pages 中发消息给 figma，并获得其响应。
+4. **生成代码**
+   - 点击生成按钮，AI 将智能分析设计稿
+   - 实时预览生成的代码效果
+   - 一键复制或导出代码
 
-使用方法:
+## 🛠️ 开发指南
 
-首先，在 src/figma 中定义 actions，参见 `src/figma/index.ts`
+### 项目结构
 
-```typescript
-// 如果添加了新的文件，需要在上面导入，并在actions中加上相应的变量名
-const actions: Record<string, Record<string, FigmaMessageHandler>> = {
-  storage,
-  page,
-}
+```
+apps/figma/
+├── src/
+│   ├── code.ts              # 插件主入口
+│   ├── ui.tsx               # UI 界面入口
+│   ├── ui.html              # UI HTML 模板
+│   ├── types.ts             # 类型定义
+│   ├── figma/               # Figma 相关逻辑
+│   │   ├── index.ts         # Figma 逻辑入口
+│   │   ├── main.ts          # 主流程控制
+│   │   ├── layer.ts         # 图层处理
+│   │   ├── node.ts          # 节点操作
+│   │   ├── storage.ts       # 本地存储
+│   │   ├── event.ts         # 事件系统
+│   │   └── core/            # 核心算法
+│   │       ├── core.ts      # 核心转换逻辑
+│   │       ├── convert.ts   # 元素转换
+│   │       ├── extract-style.ts  # 样式提取
+│   │       ├── filter-blank.ts   # 空白节点过滤
+│   │       ├── text-style.ts     # 文本样式处理
+│   │       └── util.ts      # 工具函数
+│   └── utils/               # 工具函数
+├── manifest.json            # 插件配置文件
+├── package.json
+├── webpack.config.js        # Webpack 配置
+├── webpack.cjs.config.js    # CommonJS 构建配置
+└── tsconfig.json
+
+依赖共享包：
+├── @sloth-d2c/web          # 核心转码库
+├── @sloth-d2c/history      # 历史记录管理
+└── @sloth-d2c/shared-types # 类型定义
 ```
 
-然后在相应的文件，如 `src/figma/storage` 中定义方法，如 `get`
-
-之后在 `src/pages` 中的任何位置，可以通过 `await emitToFigma('storage.get', params)` 的方式调用此方法并获取响应值。
-
-### 打包发布
+### 本地开发
 
-执行命令
+1. **启动开发模式**
 
 ```bash
-npm run pack
-```
+# 在项目根目录
+pnpm dev:figma
 
-它会在 `dist` 目录中生成一个可供生产环境使用的 `ui.html`、`ui.js`、`code.js` 文件。
+# 或只启动插件开发
+cd apps/figma
+pnpm dev:plugin
 
-然后将 `manifest.json` 等必要的文件与 `dist` 目录一起打包成 `figma-plugin.zip` 文件。
-
-之后可以内部分享 `figma-plugin.zip` 文件给其他人（无需发布到市场，但需要用开发者模式导入），或者直接发布到 Figma 插件市场。
-
-## 避坑指南
+# 同时启动 Web 开发服务器（用于调试 UI）
+pnpm dev:web
+```
 
-Figma 插件，受限于其运行时环境，和普通的前端开发略有不同。
+2. **热更新**
 
-主要的区别是有些 API 或者库不再可用，列举如下：
+开发模式下，修改代码会自动重新构建。在 Figma 中需要手动重新运行插件以加载最新代码。
 
-### 沙箱环境中的代码可以访问 Figma，不能访问 window 等全局变量和 api
+3. **调试技巧**
 
-`src/figma` 中的代码，运行在沙箱环境中，基本上只能用 Figma 的 api，无法使用大部分的 window / fetch 等 api.
+```typescript
+// 在插件代码中使用 console.log
+console.log('Debug info:', data)
 
-### Iframe 中的代码，可以访问 window / fetch 等常见的前端全局变量和 API，但略有不同
+// 在 UI 代码中，日志会显示在浏览器控制台
+// Figma Desktop: 右键插件窗口 → Inspect
+```
 
-`src/pages` 中的代码，运行在 iframe 之中，但是它的 src 并不是一个远程地址(也没有 localhost 地址可用)，而是一段 dataurl，形如 `data:text/html;base64,` 这样的地址。
+### 构建和打包
 
-这就导致它不能正常使用 `BrowserRouter` 中的前进后退等能力，无法使用 `<a>` 标签进行页面导航，而只能使用 `MemoryRouter` 和 `history.push` 这样的内存路由进行页面导航。
+```bash
+# 构建
+pnpm build
 
-同时也会导致它不能正常使用 `localStorage` 等存储类的 api，而必须借助 `src/figma` 中的 `figma.clientStorage.getAsync` 和 `figma.clientStorage.setAsync` 等方法进行数据持久化存储。
+# Node.js 库构建（用于 MCP 服务）
+pnpm build:lib:node
+```
 
-更多原理介绍，请移步到我的博客文章 [Figma 插件开发浅浅谈](https://banyudu.com/posts/figma-plugin-development-intro.f7472f?v=OKGW6q)。
+**Sloth D2C Figma 插件** - 让设计稿转代码变得简单高效 🚀