项目演进和关键问题

项目演进

前司版本核心价值

前司版本验证了 Figma 可以作为素材模板入口，也验证了"模板定义 + 数据替换 + 批量渲染"的业务闭环。

它的核心能力包括：

Figma 插件内完成变量绑定
后台管理模板和字段
支持 Excel 或页面录入数据
将 HTML 模板替换变量后渲染为图片
支持任务进度和结果下载

前司版本主要问题

前司版本在实际使用中暴露了一些关键问题，主要集中在开发成本和还原质量两个方面。

开发维护成本高

Figma 插件环境复杂，iframe、postMessage、SSO 和调试链路成本高
变量绑定依赖人工，素材团队需要在 Figma 插件中进行绑定，在后台替换数据，工具变换时需要记住变量和图层对应关系
Figma 节点到 HTML 的转换采用硬编码方式，还原度不稳定

渲染质量问题

字体、蒙版、图片裁切、渐变、背景等渲染问题维护成本高
缺少系统化的模板质量校验和异常兜底机制

当前版本演进思路

为了解决前司版本的问题，当前版本进行了架构调整，核心思路是解耦工具链，简化协作流程。

具体改进包括：

放弃自创 Figma 插件，使用 Sloth-D2c-MCP 工具导出 HTML
平台侧完成模板导入、变量识别替换、预览和批量渲染任务
通过细致的 HTML 规则调节来解决还原度问题
渲染侧使用 Puppeteer 统一截图

这样的架构带来了明显的优势：

素材团队在绑定变量和替换数据时，可以避免频繁切换平台
与平台隔绝开生成 HTML 的过程，后续替换更好的工具也更加方便
降低了整体系统的耦合度

关键问题

自动变量识别

在变量识别方案上，项目经历了一次重要调整：从 NodeList.json 文件识别变量，修改为从 refined HTML 识别变量。

为什么选择 HTML 识别？

HTML 是最终用于渲染的产物，更接近真实可替换对象
NodeList 需要反序列化解析，且解析后的内容很多，从中进行节点识别很复杂
一些默认命名如 Group 390391、Mask group 容易导致变量误判

识别规则

文本和图片的识别规则：

data-type="TEXT" 的节点识别为文字候选变量
data-type="IMG" 或 data-type="IMAGE" 的节点识别为图片候选变量

背景图过滤规则：

如果图片尺寸接近整张画布，且位置接近左上角，则不作为业务变量识别
这样可以避免将背景图误识别为可替换的业务图片

组合节点处理：

data-id 中包含 + 的组合节点会被跳过
因为这类节点通常不是单一可替换对象

SVG 尝试

在处理复杂视觉效果时，项目曾尝试引入 SVG 方案，但最终在 MVP 阶段没有正式接入。

遇到的问题

部分复杂文本效果，例如径向渐变填充或渐变描边，HTML/CSS 路径无法稳定还原。如果把整个模板都改成 SVG，会影响变量替换和批量渲染的可控性。

尝试与结论

项目中曾评估过 SVG fallback 方案：

希望只对局部复杂节点做替换，而不是把整张模板 SVG 化
但由于当时对 SVG 细节掌握还不够，MVP 阶段落地效果不理想
因此当前版本并没有正式接入这条链路

💡 未来方向：这部分更适合作为后续增强方向，在不破坏 HTML 变量替换主链路的前提下，对少量复杂节点做局部 SVG 渲染。

产品收益

保留 HTML 变量替换链路的简单性
把 SVG 作为未来增强方案，而不是在 MVP 阶段提前把系统复杂度做高

HTML 二次调整

由于 Figma 转 HTML 后存在字体、渐变、旋转、描边、蒙版等还原问题，引入 Refiner 层对 CSS 进行修正。

确定性规则

字体处理

根据 nodeList 中的字体信息，为对应节点补齐和强制指定 font-family
减少导出 HTML 与本地字体环境不一致带来的偏差
补充斜体样式判断：除了直接读取节点的 fontStyle，也会从 commonTextStyle、italic 等字段推断
统一补上 font-style: italic 或 normal

文本效果增强

对部分文本节点补偿 Figma 导出中的斜切效果，转换为 CSS skewX(...)
尽量贴近原稿字形视觉

渐变处理

仅对文本节点修正渐变填充：

把节点中的线性渐变、径向渐变等信息转换成 CSS background
补上 background-clip: text、透明文字填充等样式，让渐变文字能正常显示
保留非文本节点原有的导出渐变样式，不再额外覆盖

⚠️ 注意：当前不处理 stroke 渐变，避免在 HTML/CSS 路径下引入新的方向误差。

其他优化

支持少量模板级定点补丁，用于修复个别节点的位置偏差
保留可选的 AI patch 兜底能力，但默认仍以确定性规则为主，避免不可控修改

项目结果

当前版本完成了从模板导入到结果下载的完整闭环：

完成从模板导入、变量识别、数据录入、批量渲染到结果下载的完整闭环
将 1.0 中强依赖人工绑定和插件环境的链路，演进为更轻量的 Web 平台验证版
沉淀了 Figma 到 HTML 批量出图的产品边界、模板规范和 AI 协作研发方法