AI to Figma

把产品需求、参考图片或 Figma 参考画板先变成可确认的视觉稿，再重建为经过本地验收、可通过 code-to-canvas 写入 Figma Design 的静态 HTML。

Turn a product brief, reference image, or Figma reference frame into an approved visual direction, then rebuild it as locally verified static HTML for Figma Design code-to-canvas.

中文 | English

---

中文

项目简介

ai-to-figma 是一个以 Codex 为首要验证环境的 Agent Skill。它先确认最终 Figma 交付位置；风格借鉴和 AI 自主设计会先生成整屏视觉稿，让用户反复修改并明确选定版本，再解析本地字体、准备独立资产并重建无远程运行时依赖的静态 HTML。完成本地尺寸、资源和视觉验收后，通过 Figma MCP code-to-canvas 创建可编辑的 Figma 图层。1:1 复刻不经过视觉稿审批门。

项目支持 PC Web 与 iOS Mobile。输入可以是产品 Brief、参考图片、节点级 Figma 参考画板，也可以由 AI 自主规划信息架构和视觉方向。

核心能力

• PC Web 固定宽 1440px、最小高 900px，内容可自然增高。
• iOS Mobile 固定宽 375px、最小高 812px，强制包含 44px Status Bar、内容区和最终底部 34px Home Indicator 安全区。
• 自动区分高保真复刻、风格借鉴和 AI 自主规划。
• 风格借鉴和 AI 自主规划（包括只有一句话的需求）必须先生成整屏视觉稿；用户可持续改图或上传修改版，明确确认后才进入 HTML。
• 开工前解析 Figma 交付目标；信息完整时静默继续，缺失时才插入 Codex 原生聊天内组件。新文件进入所选团队或组织的 Drafts。
• 先用完整资产表盘点并展示全部非文本视觉的构图重要性、身份要求、视觉复杂度和处理方式；资产门通过后才创建单入口 index.html。
• 批准的整屏视觉稿只用于确认构图、色彩、层级、材质和氛围，不能作为整图嵌入 HTML 或 Figma；最终内容必须重建为真实文字、组件、布局和独立资产。
• 通过 data-visual-id 双向校验资产表与 HTML，防止漏用资产或临时 CSS 替代主视觉。
• 普通界面默认使用本机 PingFang SC 的 Light、Regular、Medium 与 Semibold；艺术字体按参考识别，缺失时记录并使用最接近的本地替代，不下载或远程加载字体。
• 默认使用 MingCute Core Regular/Filled 图标，通过作者期工具内联为无运行时依赖的 SVG。
• 品牌 Logo 只接受用户原件或第一方资源，禁止生图、截图裁切和近似仿制。
• 首屏视觉主角按构图作用与 structural、flat、rich 视觉复杂度判定；抽象或几何外形不等于 CSS 装饰，3D、体积光、半透明、材质纹理或插画细节等 rich 视觉必须使用原件、项目/第一方资源或生图资产，验证器会拒绝 SVG/CSS 替代。
• GPT Image 2 生成资产直接请求原生透明背景和 PNG/WebP alpha，不再生成键色底后本地抠图；最终文件仍须通过透明边角、主体边界和实际页面合成校验。
• 本地预览通过后才创建一次性 Figma capture ID；捕获 URL 固定选择唯一的 [data-figma-capture-root]，不会把浏览器 viewport 或预览背景转成外层 Figma 框。写入后必须回读顶层节点的元数据和截图。
• 首版仅支持 Figma Design，不支持 FigJam、Slides 或 Make。

快速开始

环境要求

• Codex Skills 运行环境。
• 已连接并具有写权限的 Figma MCP。
• Node.js 与 npm，用于脚手架、MingCute 图标内联、预览服务和 HTML 校验。
• Python 3；透明资产 alpha 校验及旧素材纯色背景兼容去底需要 Pillow>=10.0.0。

安装 Skill

Skill 真源位于 skills/ai-to-figma/。将绝对路径替换为本机仓库路径：

mkdir -p "${CODEX_HOME:-$HOME/.codex}/skills"
ln -s "/absolute/path/to/AItoFigma/skills/ai-to-figma" "${CODEX_HOME:-$HOME/.codex}/skills/ai-to-figma"

需要验证透明图片或兼容处理旧素材纯色背景时安装 Pillow：

python3 -m pip install -r skills/ai-to-figma/requirements-image.txt

安装固定版本的 MingCute 作者期 SVG 依赖：

npm install --omit=dev --prefix skills/ai-to-figma

该依赖只供 Skill 将图标内联进 HTML；最终页面不包含 npm import、图标字体或网络图标请求。

使用方法

在 Codex 中调用 $ai-to-figma：

使用 $ai-to-figma 设计一个 1440 宽的数据分析落地页，并推送到这个 Figma 文件：。

使用 $ai-to-figma 把这张截图高保真还原成 375 宽的 iOS 页面，包含完整 Status Bar 和 Home Indicator，然后推送到 Figma。

使用 $ai-to-figma 把这个 Figma 画板作为视觉语言参考，重新规划一个 onboarding 页面，并新建 Figma Design 文件承载结果。

如果提示中已经给出有效的目标 Design 链接，或已明确指定当前账号下唯一匹配的团队/组织，Skill 不会重复询问。只有交付目标缺失或无效时，才会在创建 .ai-to-figma// 前插入 Codex 原生目标组件；新建文件默认放入所选计划的 Drafts，不询问项目文件夹。

运行时产物会创建在 .ai-to-figma//，该目录默认被 Git 忽略。

运行采用严格三阶段。脚手架必须接收 reconstruction、adaptation 或 independent-planning 模式且不会创建 HTML；后两种模式先生成并明确批准视觉稿，再补全字体与资产表、准备本地资源，最后初始化 HTML。复刻模式只跳过整屏视觉稿审批，不会跳过独立最终资产生图：

node skills/ai-to-figma/scripts/scaffold.mjs --device web --mode adaptation --slug landing-page
node skills/ai-to-figma/scripts/record-preview-approval.mjs --dir .ai-to-figma/landing-page --file previews/approved-v3.png
node skills/ai-to-figma/scripts/list-local-fonts.mjs --query "PingFang"
node skills/ai-to-figma/scripts/validate-design.mjs --file .ai-to-figma/landing-page/design.md
node skills/ai-to-figma/scripts/init-html.mjs --dir .ai-to-figma/landing-page
node skills/ai-to-figma/scripts/validate-html.mjs --file .ai-to-figma/landing-page/index.html --device web --design .ai-to-figma/landing-page/design.md

record-preview-approval.mjs 只接受任务目录 previews/ 下的 PNG、JPEG 或 WebP，并把相对路径、模式、画板、批准时间和 SHA-256 写入 preview-approval.json。文件被替换、删除或移出目录后，设计门会失效。字体或资产处于 planned、resolving 或 blocked 状态也不能通过；本地字体不可用、艺术字体尚未替代、找不到身份关键原件或资产处理失败时，流程会在生成 HTML 前停止。

Visual Asset Plan 需要在 身份关键 与 处理方式 之间填写 视觉复杂度，取值为 structural、flat 或 rich。旧版十列表格必须补充该列后才能通过 validate-design.mjs；选择 image-generation 后必须实际调用运行环境的生图能力并落盘验收，能力不可用时保持 blocked，不能回退成 SVG/CSS。

Figma 捕获时，将工具返回的脚本保存到任务临时文件，并让预览服务生成唯一可用的元素级捕获 URL：

node skills/ai-to-figma/scripts/serve-preview.mjs \
  --dir .ai-to-figma/landing-page \
  --port 4173 \
  --inject-file .ai-to-figma/landing-page/capture-snippet.html \
  --capture-id  \
  --capture-endpoint  \
  --capture-delay 1000

只打开命令输出的 captureUrl。该 URL 固定包含 figmaselector=[data-figma-capture-root]；验收时检查生成的顶层节点本身是否等于目标画板尺寸，不能用尺寸正确的内部子节点掩盖外层 viewport 框。

项目结构

• AGENTS.md：仓库内容边界与维护约束。
• skills/ai-to-figma/：完整、可独立安装的 Skill 真源。
• skills/ai-to-figma/SKILL.md：触发、路由、硬规则和停止条件。
• skills/ai-to-figma/references/：工作流、画板、资产、HTML、Figma 捕获和恢复规范。
• skills/ai-to-figma/assets/：原生目标组件、捕获 HTML 骨架和 design.md 模板。
• skills/ai-to-figma/scripts/：Skill 运行所需的目标组件渲染、脚手架、预览、校验和图片处理工具。
• skills/ai-to-figma/package.json：固定版本的 MingCute 作者期依赖。
• README.zh-CN.md：独立中文阅读版本；根 README 是双语真源。

维护与校验

python3 "${CODEX_HOME:-$HOME/.codex}/skills/.system/skill-creator/scripts/quick_validate.py" skills/ai-to-figma

冒烟测试、临时 fixture、生成预览与真实端到端捕获都属于本地验证内容，统一放在已忽略的 .ai-to-figma/，不作为项目或 Skill 内容提交。真实端到端验证可能新建 Figma Design 测试文件；Capture ID 只能使用一次，测试文件不会自动删除。

限制与故障边界

• 找不到官方 Logo 时停止，不会臆造或从截图裁切。
• 风格借鉴或自主设计没有用户明确批准的视觉稿时停止；批准稿不能直接成为最终页面图片。
• 要求身份完全一致的产品、人物、包装或吉祥物必须提供原件或第一方资产。
• GPT Image 2 原生透明输出未通过 alpha 校验时只允许一次针对性重生成；用户或第一方旧素材仅在背景纯色且可分离时兼容本地去底，复杂边缘无法可靠处理时停止并要求透明原件。
• Figma 写入失败后只允许一次有依据的修正，并使用新的 capture ID 重试。

许可证

本项目使用 MIT License，版权主体为 AItoFigma contributors，详见 LICENSE。MingCute Core 图标使用 Apache License 2.0，许可文本随 Skill 一并保留。

English · 返回顶部

---

English

Overview

ai-to-figma is an Agent Skill validated primarily in Codex. It first resolves the final Figma delivery target. Visual-language adaptation and AI-led independent design then generate a full-screen visual preview for unlimited user iteration and explicit selection before local fonts and separate assets are resolved and the direction is rebuilt as runtime-free static HTML. After local dimension, asset, and visual checks pass, it uses Figma MCP code-to-canvas to create editable Figma layers. Literal reconstruction skips the preview-approval gate.

The project supports PC Web and iOS Mobile. Inputs can be a product brief, a reference image, a node-specific Figma reference frame, or an independently planned information architecture and visual direction.

Features

• PC Web uses a fixed 1440px width, a 900px minimum height, and natural content growth.
• iOS Mobile uses a fixed 375px width and an 812px minimum height, with a mandatory 44px Status Bar, content region, and final-bottom 34px Home Indicator safe area.
• Automatically routes high-fidelity reconstruction, visual-language adaptation, and independent planning.
• Requires a full-screen preview for adaptation and independent planning, including one-sentence briefs; users may keep editing or upload a revision, and HTML starts only after explicit approval.
• Resolves the Figma delivery target before work begins; complete prompts continue silently, while missing targets insert a native Codex inline component. New files go to the selected plan’s Drafts.
• Inventories every non-text visual in a complete table that exposes compositional importance, identity requirements, visual complexity, and handling method, then creates the single-entry index.html only after the asset gate passes.
• Treats the approved preview only as evidence for composition, palette, hierarchy, material, and atmosphere. It cannot be embedded as a flattened HTML or Figma image; final output is rebuilt from real text, components, layout, and separate assets.
• Cross-checks the asset plan and HTML through data-visual-id, preventing omitted assets and temporary CSS substitutes for hero art.
• Uses local PingFang SC Light, Regular, Medium, and Semibold for ordinary UI text. Reference-driven display fonts use an installed exact match or a documented closest local substitute; fonts are never downloaded or loaded remotely.
• Uses MingCute Core Regular/Filled by default and inlines selected icons as runtime-free SVG during authoring.
• Brand logos must come from user originals or first-party sources; generation, screenshot cropping, and approximate imitation are prohibited.
• Hero visuals are classified as structural, flat, or rich alongside their compositional role. An abstract or geometric silhouette is not automatically CSS decoration; 3D form, volumetric light, translucency, material texture, or illustrative detail makes a visual rich, and the validator rejects SVG/CSS substitutes in favor of originals, project/first-party media, or generated assets.
• GPT Image 2 assets request native transparent backgrounds and PNG/WebP alpha directly instead of generating a keyed background for local removal. The final file still must pass transparent-corner, subject-edge, and real-page composite checks.
• Creates a single-use Figma capture ID only after local preview passes. The capture URL is fixed to the one [data-figma-capture-root], so the browser viewport and preview background cannot become an outer Figma frame. After writing, it reads back metadata and a screenshot for the generated top-level node.
• The first release supports Figma Design only, not FigJam, Slides, or Make.

Quick Start

Prerequisites

• A Codex Skills runtime.
• A connected Figma MCP account with write access.
• Node.js and npm for scaffolding, MingCute icon inlining, preview serving, and HTML validation.
• Python 3; transparent-asset alpha validation and legacy flat-background removal require Pillow>=10.0.0.

Install the Skill

The Skill source of truth is skills/ai-to-figma/. Replace the absolute path with the local repository path:

mkdir -p "${CODEX_HOME:-$HOME/.codex}/skills"
ln -s "/absolute/path/to/AItoFigma/skills/ai-to-figma" "${CODEX_HOME:-$HOME/.codex}/skills/ai-to-figma"

Install Pillow when validating transparent images or processing a legacy flat-background asset:

python3 -m pip install -r skills/ai-to-figma/requirements-image.txt

Install the pinned authoring-time MingCute SVG dependency:

npm install --omit=dev --prefix skills/ai-to-figma

This dependency is used only to inline icons into HTML. Final pages contain no npm import, icon font, or network icon request.

Usage

Invoke $ai-to-figma in Codex:

Use $ai-to-figma to design a 1440px analytics landing page and push it to this Figma file: .

Use $ai-to-figma to reconstruct this screenshot as a 375px iOS page with a complete Status Bar and Home Indicator, then push it to Figma.

Use $ai-to-figma to treat this Figma frame as a visual-language reference, replan an onboarding page, and create a new Figma Design file for the result.

When the prompt already contains a valid destination Design URL, or uniquely identifies a team or organization under the current account, the Skill does not ask again. Only a missing or invalid delivery target inserts the native Codex target component before .ai-to-figma// is created. New files are placed in the selected plan’s Drafts; project folders are not requested.

Runtime artifacts are created under .ai-to-figma//, which Git ignores by default.

Runtime uses a strict three-stage flow. Scaffolding requires reconstruction, adaptation, or independent-planning and does not create HTML. The latter two modes first generate and explicitly approve a preview, then resolve typography and final assets, and only then initialize HTML. Reconstruction skips only full-screen preview approval; it still generates separate final assets when required:

node skills/ai-to-figma/scripts/scaffold.mjs --device web --mode adaptation --slug landing-page
node skills/ai-to-figma/scripts/record-preview-approval.mjs --dir .ai-to-figma/landing-page --file previews/approved-v3.png
node skills/ai-to-figma/scripts/list-local-fonts.mjs --query "PingFang"
node skills/ai-to-figma/scripts/validate-design.mjs --file .ai-to-figma/landing-page/design.md
node skills/ai-to-figma/scripts/init-html.mjs --dir .ai-to-figma/landing-page
node skills/ai-to-figma/scripts/validate-html.mjs --file .ai-to-figma/landing-page/index.html --device web --design .ai-to-figma/landing-page/design.md

record-preview-approval.mjs accepts only PNG, JPEG, or WebP files under the task’s previews/ directory and writes the relative path, mode, canvas, approval time, and SHA-256 to preview-approval.json. Replacing, deleting, or moving the selected file invalidates the design gate. Typography or asset rows in planned, resolving, or blocked also cannot pass. An unavailable local font, unresolved display substitution, missing identity-critical original, or failed asset process stops the workflow before HTML is generated.

The Visual Asset Plan now requires a 视觉复杂度 column between 身份关键 and 处理方式, with structural, flat, or rich as the only values. Legacy ten-column plans must add this column before validate-design.mjs can pass. Once a row selects image-generation, the runtime image-generation capability must produce and persist the inspected asset; an unavailable capability leaves the row blocked and never falls back to SVG or CSS.

For Figma capture, save the returned script in the task workspace and let the preview server generate the only valid element-scoped capture URL:

node skills/ai-to-figma/scripts/serve-preview.mjs \
  --dir .ai-to-figma/landing-page \
  --port 4173 \
  --inject-file .ai-to-figma/landing-page/capture-snippet.html \
  --capture-id  \
  --capture-endpoint  \
  --capture-delay 1000

Open only the emitted captureUrl. It always contains figmaselector=[data-figma-capture-root]. Verification checks that the generated top-level node itself matches the target artboard dimensions; a correctly sized descendant cannot hide a viewport-sized wrapper.

Project Structure

• AGENTS.md: repository content boundaries and maintenance constraints.
• skills/ai-to-figma/: the complete, independently installable Skill source of truth.
• skills/ai-to-figma/SKILL.md: triggers, routing, hard rules, and stop conditions.
• skills/ai-to-figma/references/: workflow, canvas, asset, HTML, Figma capture, and recovery specifications.
• skills/ai-to-figma/assets/: native delivery-target component, capture-safe HTML shell, and design.md template.
• skills/ai-to-figma/scripts/: Skill runtime tools for target-component rendering, scaffolding, preview, validation, and image processing.
• skills/ai-to-figma/package.json: pinned authoring-time MingCute dependency.
• README.zh-CN.md: standalone Chinese reading version; the root README is the bilingual source of truth.

Maintenance and Validation

python3 "${CODEX_HOME:-$HOME/.codex}/skills/.system/skill-creator/scripts/quick_validate.py" skills/ai-to-figma

Smoke tests, temporary fixtures, generated previews, and real end-to-end captures are local validation material. Keep them in the ignored .ai-to-figma/ directory rather than committing them as project or Skill content. Real end-to-end verification may create a Figma Design test file; capture IDs are single-use, and the test file is not deleted automatically.

Limits and Failure Boundaries

• The workflow stops when an official logo cannot be found; it never invents one or crops one from a screenshot.
• Adaptation and independent design stop without an explicitly approved preview, and that preview can never become the final page bitmap.
• Identity-critical products, people, packages, or mascots require an original or first-party asset.
• A GPT Image 2 native-transparent result gets at most one targeted regeneration after failed alpha validation. Local removal remains compatible only with user-provided or first-party legacy assets that have a flat, separable background; complex edges require a proper alpha source.
• After a Figma write failure, only one evidence-based correction is allowed, using a new capture ID.

License

This project uses the MIT License with copyright held by AItoFigma contributors. See LICENSE. MingCute Core icons use Apache License 2.0, whose license text is bundled with the Skill.

中文 · Back to top