Skip to content

SKILL.md

Latest commit

 

History

History
215 lines (155 loc) · 11.7 KB

SKILL.md

File metadata and controls

215 lines (155 loc) · 11.7 KB
Raw
name liaocao-figmaX
description 在 Figma 桌面端通过对话式 Agent（Claude Code / Cursor / Codex）进行平面/界面设计的工作流。组合使用 Figma 官方 MCP（读取上下文、截图、设计令牌）与 figma_editor MCP（往画布写入：创建画框、文本、矢量、自动布局、变量、组件、导出）。适用于公众号封面、小红书卡片、海报、Banner、Web 落地页 mockup、产品界面等以 Figma 为最终产出的场景。当用户提到"在 Figma 里画"、"做一张封面/海报/卡片"、"调整 Figma 画布"、"导出 PNG/SVG"、"基于现有 Figma 文件二次创作"时触发。

liaocao-figmaX

让 Agent 在 Figma 画布上完成"读 → 想 → 画 → 校对 → 导出"的完整闭环。

0. 工具栈与分工

两个 MCP 服务必须同时连通：

用途 MCP 服务 何时调用
读 Figma 上下文 plugin:figma:figma（官方） 解析用户给的 figma.com URL、获取 node 详情，验证完成效果
写 Figma 画布 figma_editor（本项目依赖） 创建/修改/删除节点、布局、变量、组件、导出图片

口诀：官方 MCP 是眼睛，figma_editor 是手。 没有眼睛先动手会闭眼乱画；只看不动手只能讲，不能画。

1. 起手三步（Pre-flight，每个会话开始前必做）

按顺序执行，任一失败就停下来引导用户解决，不要硬画。

Step 1.1 Figma 桌面端 + 插件就位

提醒用户：

  1. 打开 Figma Desktop App（Web 版无法导入未发布插件）。
  2. 在某个设计文件里 Plugins → Development → figma_editor，让小面板保持打开。

Step 1.2 校验 figma_editor 通路

调用：

figma_editor.get_connection_status()

期望响应：

{ "mode": "hub" 或 "proxy", "connected": true, "pluginConnected": true }
  • pluginConnected: false → 用户没运行插件，停下让用户开。
  • connected: false → MCP 没装好或端口被占，跑 scripts/check_connection.sh 自检并参考 commands/faq.md。

Step 1.3 校验官方 Figma MCP

随便调一次 mcp__plugin_figma_figma__whoami 或 get_metadata（如有 fileKey）确认能通。

如果用户没给 figma.com URL、纯白板从零开始画，可以略过官方 MCP 的读步骤；但只要用户给了 URL/参考稿，必须先读再画。

2. 标准工作流

意图 → 读环境 → 选风格 → 选版式 → 落画布 → 获取详情自检 → 迭代 → 导出/收尾

Step 2.1 收意图（必要时反问）

在动手之前明确 5 件事：

  • 产物形态：公众号封面 / 小红书 9:16 / A4 海报 / Web 落地页 / 移动端 UI / 信息卡。
  • 目标尺寸：参考 references/layouts.md，如不确定就问用户。
  • 风格定调：极简 / 杂志编辑 / 复古 / 大字号海报 / 黑白克制 / 拟物 / 玻璃感 ...
  • 品牌素材：先扫一遍 references/ 目录下用户已经沉淀的品牌资产（logo、主色、字体、设计规范、图片资源等），有就直接用；不够再追问用户。
  • 复用对象：基于已有 Figma 文件二改，还是空白起步。

意图不清晰，反问一两个最关键的问题，不要硬猜。

Step 2.2 读环境（有 URL时必做）

  • 用户给了 figma.com/design/...?node-id=... URL：解析出 fileKey + nodeId，调 mcp__plugin_figma_figma__get_design_context 拿到代码来查看内容。
  • 想检查变量/组件：figma_editor.get_local_styles、get_variables、list_components、scan_library、search_library_components。

已有设计系统/团队组件库，优先复用而不是重新造轮子。create_library_instance 直接落组件实例。

在官方 Figma MCP 里：

  • 获取某个 node id 的结构化详情：mcp__plugin_figma_figma__get_design_context
  • 获取整个页面/文件的高层节点树、页面结构、节点列 表：mcp__plugin_figma_figma__get_metadata
  • 截图是：mcp__plugin_figma_figma__get_screenshot 但是因为截图很消耗 token，非必要不要使用截图功能

Step 2.3 选风格（design.md + references/品牌资产）

读 assets/design.md，按它的"Design Thinking → Aesthetic Default → Color/Typo/Spacing/Motion"框架，给用户一个明确的风格主张。

优先级：用户在 references/ 里沉淀的品牌资产 > 用户当下提供的参考站> assets/design.md 默认主张。

  • 如果 references/ 下有品牌色卡 / 品牌字体 / 设计规范文件（例如 references/brand-*.md、references/logo-*.svg / *.png），先吃这些，不要绕开重做一套。
  • 如果用户给了参考站，按参考站抽取 token。
  • 都没有，再回落到 assets/design.md 的默认推荐。

风格定调要落到 6 个 token：

  • 主色 / 辅助色 / 文本主色 / 边框色 / 背景色 / 强调色
  • 标题字体 / 正文字体（含中英 fallback）
  • 字号阶梯（display / heading / body / label）
  • 间距阶梯（4 / 8 / 12 / 16 / 24 / 32 / 48 / 64 / 96）
  • 圆角（无/小 / 中 / 大 / pill）
  • 阴影层级（无 / 轻 / 中 / 重）

token 确认后，直接开始画图，颜色用具体 hex 色值硬编码（在节点命名里备注 token 名方便后期维护），不需要先建变量。bind_variable 仅在用户明确要求建立设计变量库时才使用。

Step 2.4 选版式（layouts.md）

按产物形态从 references/layouts.md 挑模板，得到画布尺寸 + 区块结构 + 排版规则。

Step 2.5 落画布（figma_editor 写入）

推荐顺序，避免来回返工：

  1. 底框：create_frame（带正确尺寸 + 自动布局参数）。

  2. 结构区块：create_section 或子 frame，先把版式骨架排好。

  3. 填充内容：create_text、create_rectangle、create_ellipse、create_svg_node。

  4. 样式：set_fill / set_stroke / set_effects，颜色/边框/阴影直接传 hex 色值（例如 { "r": 0.1, "g": 0.1, "b": 0.1, "a": 1 } 的 RGBA 格式），不要先建变量再绑定，直接写硬编码色值。

  5. 布局：将每个区块的内容合理地设置为set_auto_layout，能自动布局的绝不手动算坐标。避免在产量好 frame 以后就将整个 frame 设置为 aulo layout。

  6. 图片：set_image_fill，本地路径 / base64 / usePluginImage: true 三选一。

    上传前必做：读取本地图片原始尺寸

    把图片填入 Figma 前，先查清原始宽 × 高，再决定容器比例与 scaleMode。这样能防止 FILL 模式把主体裁掉，或 FIT 模式留出不必要的空白。

    macOS（需要 ImageMagick，首次安装：brew install imagemagick）：

    identify -format "%wx%h\n" /path/to/image.jpg
# 输出示例：1920x1080

    Windows（PowerShell 内置，无需额外安装）：

    Add-Type -AssemblyName System.Drawing
$img = [System.Drawing.Image]::FromFile("C:\path\to\image.jpg")
Write-Output "$($img.Width)x$($img.Height)"
$img.Dispose()

    如果 Windows 已安装 ImageMagick（winget install ImageMagick.ImageMagick），也可以用：

    magick identify -format "%wx%h\n" C:\path\to\image.jpg

    拿到宽高后的决策逻辑：

    • 容器需跟图片等比：直接用图片宽高创建 frame，scaleMode: "FILL"。
    • 容器尺寸固定（如公众号封面 900×383）：计算图片宽高比，决定用 scaleMode: "FIT" 留边还是 "FILL" 裁边，并说明主体保留情况。

  7. 复杂矢量：create_svg_node（直接传 SVG 字符串），或 boolean_operation 合成。

  8. 组件化：成系统的元素用 create_component + create_component_set，使用时 create_component_instance。

字体踩坑提醒：

  • 调 figma_editor.list_available_fonts 看本机有哪些字体。
  • 中文字体优先 PingFang SC / Noto Sans SC；英文标题 Inter / Montserrat 是 AI 烂大街选项，谨慎使用，参考 assets/design.md 的"禁止常见字体"清单。

Step 2.6 获取 Node 情况自检（每完成一个区块都做一次）

调 figma 官方 MCP 的获取 node_id 详情的 tools （传刚创建的 frame 的 nodeId），亲眼看一下而不是凭脑补判断。AI 直接生成的画面经常有：

  • 文字溢出到框外
  • 自动布局没生效，元素叠在一起
  • 颜色没吃到变量，写死了 hex
  • 图片填充比例错位

发现问题立即修复。

Step 2.7 走 checklist

完成主要区块后，强制对照 assets/checklist.md 自检一遍。没过的项必须改，不要交付半成品。

3. 何时使用三个 command

commands/ 下的文件不是技能本体，而是用户手动触发的快捷流程。出现以下情境主动建议用户用：

  • 用户报错或感觉不对劲 → commands/faq.md。
  • 用户对本次产出不满，希望让技能更适配 ta 的工作流 → commands/optimize.md。
  • 用户做出了一个满意的画稿，希望沉淀成模板 → commands/save_template.md。

4. 平台差异

本仓库同时为三个 Agent 客户端提供入口：

客户端 入口文件
Claude Code .claude/skills/figma-access/SKILL.md（本仓库根 SKILL.md 的同步副本）
Cursor .cursor/rules/figma-access.mdc
Codex CLI 仓库根 AGENTS.md

实际指南正文统一以 本文件 + references/ + assets/ + commands/ 为准；其它三个入口只做"指针"，避免内容漂移。

5. 失败约束（务必遵守）

不要做：

  • 在 pluginConnected: false 时硬调 figma_editor 的写入工具——会丢命令。
  • 在没读过 assets/design.md 之前自由发挥色板/字体——容易回到 AI 烂大街审美。
  • 用绝对坐标拼版面——优先 set_auto_layout，否则改尺寸时全乱。
  • 除非用户明确要建设计变量库，否则不要在画图前先调 create_variable_collection / create_variable——这步往往报错且耗时，直接用 hex 色值画更可靠。
  • 跳过 assets/checklist.md 直接说"完成了"。

6. 资源索引

  • scripts/check_connection.sh — 一键检查两个 MCP + Figma 插件状态。
  • scripts/install_guide.md — figma_editor 插件 + MCP 配置详细安装步骤。
  • assets/design.md — 设计系统主张范例（含核心原则 / 配色 / 字体 / 间距 / 动效）。
  • assets/checklist.md — 完成任务前的通用自检清单。
  • references/ — 用户沉淀的参考资产库，可放任意数量、任意命名的文件，由 Agent 在动手前主动扫读：
    • references/layouts.md — 公众号封面 / 小红书 / 海报 / Web / 移动端 常用版式与尺寸（仓库自带）。
    • references/brand-*.md — 品牌设计规范，例如 brand-acme.md、brand-personal.md，写明品牌主色、辅色、字体、Logo 用法、文案口吻、禁用样式等。
    • references/logo-*.svg / logo-*.png — 品牌 Logo 矢量与位图素材，落画布时用 set_image_fill 或 create_svg_node 引用。
    • references/palette-*.md — 单独维护的色板（含十六进制色值、用途、深浅模式映射）。
    • references/typography-*.md — 字体清单与字号阶梯（含中英 fallback、商用授权说明）。
    • references/assets/ — 任意图片 / 图标 / 插画素材子目录，按品牌或项目分文件夹。
    • 其他用户自定义文件（如 references/voice-*.md 文案口吻、references/icon-*.md 图标库索引等）一律允许，名字清晰即可。
  • commands/faq.md — 安装、连接、字体、变量等高频问题速查。
  • commands/optimize.md — 用户驱动的技能改进流程。
  • commands/save_template.md — 把当前 Figma 画稿沉淀成可复用模板。