figma-design-handoff

Figma 设计交接

到 2026 年，Figma 已成为主流设计工具，大多数产品团队都将其作为首选设计工具。结构化的交接工作流可消除设计偏差——也就是设计师的创作与开发人员的实现之间的差距。本技能涵盖完整流程：将 Figma Variables 转换为设计令牌、提取组件规格、检查 Dev Mode、将 Auto Layout 映射为 CSS，以及进行视觉回归测试。

快速参考

规则	文件	影响	使用时机
Figma Variables 与令牌	rules/figma-variables-tokens.md	严重	将 Figma Variables 转换为 W3C 设计令牌 JSON
组件规格	rules/figma-component-specs.md	高	从 Figma 提取组件属性、变体和状态
Dev Mode 检查	rules/figma-dev-mode.md	高	测量尺寸、间距、字体排版和导出资源
Auto Layout → CSS	rules/figma-auto-layout.md	高	将 Auto Layout 映射为 Flexbox/Grid
视觉回归	rules/figma-visual-regression.md	中	将生产环境 UI 与 Figma 设计进行比较

总计：1 个类别下的 5 条规则

Figma Dev Mode MCP 服务（2026 年默认方案）

Figma Dev Mode MCP 服务可取代大多数手动 REST 和 Dev Mode 检查。只需配置一次，任何可访问 Figma 的 Claude Code 会话都能直接获取设计上下文、令牌和代码映射。

主要工具（已记录 16 个 — developers.figma.com/docs/figma-mcp-server/tools-and-prompts）：

工具	返回内容	用途
get_design_context	组件树 + 布局 + 字体排版 + 间距	检查任何 Figma 节点时的首次调用 → 为其他所有工具提供依据
get_variable_defs	令牌集合（变量 + 模式 + 别名）	直接导出为 W3C DTCG JSON — 跳过 REST 流程
get_code_connect_map	Figma 节点 → 代码库组件映射	将生成的代码关联到现有仓库组件
get_screenshot	节点或画面的 PNG 图像	用于视觉差异比较的截图 / 嵌入聊天
search_design_system	跨库搜索令牌/组件	生成新令牌前查找现有令牌
use_figma (beta)	回写 Figma 画布	代码与设计双向往返（写入画布）
generate_figma_design (beta)	根据提示词创建设计画面	为交接生成 AI 设计框架

安装：在 Figma 桌面应用中通过 Preferences → Dev Mode MCP Server 启用，或使用远程 MCP 端点（读取工具无需桌面应用）。搭配 Code Connect UI（2026 年正式发布）使用，无需手动配置 JSON，即可将 Figma 节点 ID 映射到代码库组件。

// .claude/mcp-servers/figma.json — sample config
{
  "figma": {
    "command": "figma-mcp",
    "args": ["--mode=dev"],
    "env": { "FIGMA_ACCESS_TOKEN": "${FIGMA_TOKEN}" }
  }
}

快速开始

# 1. Export Figma Variables (Figma REST API)
curl -s -H "X-Figma-Token: $FIGMA_TOKEN" \
  "https://api.figma.com/v1/files/$FILE_KEY/variables/local" \
  > tokens/figma-local.json

# 2. Convert that response to W3C Design Tokens. This skill does NOT ship a
#    converter — the mapping (variables, modes, aliases, and the $value/$type
#    shape) is specified in rules/figma-variables-tokens.md, and the right
#    implementation depends on which collections and modes your file uses.
#    Earlier revisions of this Quick Start piped into a
#    `scripts/figma-to-w3c-tokens.js` that has never existed in this skill.
#    Result: tokens/figma-raw.json

# 3. Transform with Style Dictionary
npx style-dictionary build --config sd.config.js

# 4. Output: CSS custom properties + Tailwind theme
# tokens/
#   figma-raw.json        ← W3C Design Tokens format
#   css/variables.css     ← --color-primary: oklch(0.65 0.15 250);
#   tailwind/theme.js     ← module.exports = { colors: { primary: ... } }

// W3C Design Tokens Format (DTCG)
{
  "color": {
    "primary": {
      "$type": "color",
      "$value": "{color.blue.600}",
      "$description": "Primary brand color"
    },
    "surface": {
      "$type": "color",
      "$value": "{color.neutral.50}",
      "$extensions": {
        "mode": {
          "dark": "{color.neutral.900}"
        }
      }
    }
  }
}

// Style Dictionary config for Figma Variables
import StyleDictionary from 'style-dictionary';

export default {
  source: ['tokens/figma-raw.json'],
  platforms: {
    css: {
      transformGroup: 'css',
      buildPath: 'tokens/css/',
      files: [{ destination: 'variables.css', format: 'css/variables' }],
    },
    tailwind: {
      transformGroup: 'js',
      buildPath: 'tokens/tailwind/',
      files: [{ destination: 'theme.js', format: 'javascript/module' }],
    },
  },
};

交接工作流

设计到代码的流程分为五个阶段：

1. 在 Figma 中设计 — 设计师使用 Variables、Auto Layout 和恰当的命名创建组件
2. 提取规格 — 使用 Dev Mode 检查间距、字体排版、颜色并导出资源
3. 导出令牌 — 通过 REST API 或插件将 Figma Variables 转换为 W3C tokens JSON
4. 构建组件 — 将 Auto Layout 映射为 CSS Flexbox/Grid，应用令牌并实现变体
5. 视觉 QA — 使用 Applitools 将生产环境截图与 Figma 画面进行比较

┌─────────────┐     ┌──────────────┐     ┌───────────────┐
│  Figma File  │────▶│  Dev Mode    │────▶│  tokens.json  │
│  (Variables, │     │  (Inspect,   │     │  (W3C DTCG    │
│  Auto Layout)│     │   Export)    │     │   format)     │
└─────────────┘     └──────────────┘     └───────┬───────┘
                                                  │
                                                  ▼
┌─────────────┐     ┌──────────────┐     ┌───────────────┐
│  Visual QA  │◀────│  Components  │◀────│ Style         │
│  (Applitools,│     │  (React +   │     │ Dictionary    │
│   Chromatic) │     │  Tailwind)   │     │ (CSS/Tailwind)│
└─────────────┘     └──────────────┘     └───────────────┘

规则

每条规则都按需从 rules/ 目录加载：

Auto Layout 到 CSS 的映射

常见映射速查：

Figma Auto Layout	CSS 等效项	Tailwind 类
方向：水平	flex-direction: row	flex-row
方向：垂直	flex-direction: column	flex-col
间距：16	gap: 16px	gap-4
内边距：16	padding: 16px	p-4
内边距：16、24	padding: 16px 24px	py-4 px-6
对齐：居中	align-items: center	items-center
分布：两端对齐	justify-content: space-between	justify-between
填充容器	flex: 1 1 0%	flex-1
紧贴内容	width: fit-content	w-fit
固定宽度：200	width: 200px	w-[200px]
最小宽度：100	min-width: 100px	min-w-[100px]
最大宽度：400	max-width: 400px	max-w-[400px]
换行	flex-wrap: wrap	flex-wrap
绝对定位	position: absolute	absolute

视觉 QA 循环

// Applitools Eyes + Figma Plugin — CI integration
import { Eyes, Target } from '@applitools/eyes-playwright';

const eyes = new Eyes();

await eyes.open(page, 'MyApp', 'Homepage — Figma Comparison');

// Capture full page
await eyes.check('Full Page', Target.window().fully());

// Capture specific component
await eyes.check(
  'Hero Section',
  Target.region('#hero').ignoreDisplacements()
);

await eyes.close();

Applitools Figma Plugin 会将生产环境截图叠加到 Figma 画板上，以便发现：

• 颜色不匹配（未应用令牌或模式错误）
• 间距偏差（内边距／外边距偏差）
• 字体排版不一致（字号、字重、行高）
• 状态缺失（未实现悬停、焦点、禁用状态）

关键决策

决策	建议
令牌格式	W3C Design Tokens Community Group（DTCG）JSON
令牌流水线	Figma REST API → Style Dictionary → CSS/Tailwind
颜色格式	使用 OKLCH 实现感知均匀的主题化
布局映射	Auto Layout → CSS Flexbox（二维布局使用 Grid）
视觉 QA 工具	Applitools Eyes + Figma Plugin，用于设计与开发差异对比
规格格式	与 Figma 组件属性匹配的 TypeScript 接口
模式处理	Figma Variable 模式 → CSS 媒体查询／类切换

反模式（禁止）

• 硬编码值：切勿硬编码颜色、间距或字体排版值，始终引用令牌
• 跳过 Dev Mode：不要凭目测估算尺寸，使用 Dev Mode 获取精确值
• 手动同步令牌：不要从 Figma 手动复制值，使用 REST API 自动化
• 忽略模式：带有浅色／深色模式的变量必须映射到主题切换，而不是拆分成不同文件
• 仅用截图进行 QA：没有结构化回归测试的视觉对比会遗漏细微偏差
• 扁平令牌结构：使用嵌套的 W3C DTCG 格式，而不是扁平的键值对

参考资料

资源	描述
references/figma-to-code-workflow.md	端到端工作流、工具链选项
references/design-dev-communication.md	PR 模板、组件状态跟踪
references/applitools-figma-plugin.md	设置、CI 集成、对比配置

相关技能

• ork:design-system-tokens — W3C 令牌架构和 Style Dictionary 转换
• ork:ui-components — shadcn/ui 和 Radix 组件模式
• ork:accessibility — 从 Figma 提取的组件的 WCAG 合规性