AI导哈

设计令牌同步工具

Figma MCP Bridge 是一个双向同步工具，用于在 Figma 开发模式和设计系统之间同步设计令牌，支持拉取、推送、转换和自动化功能。

  • by jgtolentino
  • Python
  • 本地部署
  • 更新于
在 GitHub 查看 jgtolentino/figma-mcp-bridge

使用说明

Figma MCP电桥<

Figma开发模式和设计系统之间通过MCP（模型上下文协议）服务器和Claude代理进行双向同步。

概述

Figma MCP桥实现了Figma和代码库之间设计令牌的无缝同步。它提供：

  • 拉：从Figma文件中获取设计令牌
  • 推：用本地令牌更改更新Figma
  • 变换：在Figma和标准令牌格式之间转换
  • 自动化：GitHub持续同步操作

快速开始

1.安装

# Clone the repository
git clone https://github.com/jgtolentino/figma-mcp-bridge.git
cd figma-mcp-bridge

# Install dependencies
pip install -r server/requirements.txt

2.配置

# Initialize configuration
python cli/figma_ds_sync.py init

# Or manually create .env file
cat > .env << EOF
FIGMA_PAT=your_figma_personal_access_token
FIGMA_FILE_ID=your_figma_file_id
EOF

3.基本用法

# Pull tokens from Figma
python cli/figma_ds_sync.py pull

# Push tokens to Figma
python cli/figma_ds_sync.py push

# Validate token structure
python cli/figma_ds_sync.py validate tokens/tokens.json

MCP服务器

启动MCP服务器以启用API访问：

# Start server
cd server
uvicorn main:app --reload

# Server will be available at http://localhost:8000

API终点

  • GET / -健康检查
  • GET /figma/design-tokens -获取设计令牌
  • POST /figma/push -将代币推送到Figma
  • GET /figma/components -获取组件定义

CLI命令

拉动命令

python cli/figma_ds_sync.py pull [OPTIONS]

Options:
  -o, --output PATH      Output file path [default: tokens/tokens.json]
  -f, --file-id TEXT     Figma file ID (overrides env)
  -p, --pretty          Pretty print JSON [default: True]

推送命令

python cli/figma_ds_sync.py push [OPTIONS]

Options:
  -i, --input PATH       Input file path [default: tokens/tokens.json]
  -f, --file-id TEXT     Figma file ID (overrides env)
  -m, --merge           Merge with existing tokens [default: True]
  -d, --dry-run         Preview changes without applying

构建命令（样式词典）

python cli/figma_ds_sync.py build [OPTIONS]

Options:
  -c, --config PATH      Style Dictionary config [default: style-dictionary.config.js]
  -p, --platform TEXT    Build specific platform only

变换命令

python cli/figma_ds_sync.py transform INPUT OUTPUT [OPTIONS]

Options:
  -d, --direction TEXT   Transform direction: figma-to-sd or sd-to-figma
  -p, --platform TEXT    Target platform for transformation

推送组件命令

python cli/figma_ds_sync.py push-component COMPONENT_PATH [OPTIONS]

Options:
  -f, --file-id TEXT     Figma file ID (overrides env)
  -s, --as-set          Create as component set
  -d, --dry-run         Preview without pushing

merge命令

python cli/figma_ds_sync.py merge INPUT_FILES... [OPTIONS]

Options:
  -o, --output PATH      Output file for merged tokens [default: tokens/merged.json]

代币结构

令牌应遵循以下结构：

{
  "colors": {
    "primary": {
      "value": "#1E40AF",
      "type": "color"
    }
  },
  "spacing": {
    "sm": {
      "value": "8px",
      "type": "dimension"
    }
  },
  "typography": {
    "heading": {
      "value": {
        "fontFamily": "Inter",
        "fontSize": 24,
        "fontWeight": 700
      },
      "type": "typography"
    }
  }
}

GitHub操作

推送时自动同步令牌：

  1. 将机密添加到GitHub存储库：

    • FIGMA_PAT -您的Figma个人访问令牌
    • FIGMA_FILE_ID -您的Figma文件ID

  2. 当您向推送更改时，令牌将自动同步 tokens/ 目录

脉冲器集成

在Pulser CLI中注册：

# In your main repository
:clodrep run figma-agent.yaml

# Use Pulser commands
pulser figma:pull
pulser figma:push
pulser figma:build
pulser figma:transform

样式词典集成

该桥包括对多平台令牌生成的完整样式字典支持：

支持的平台

  • 网络：CSS变量、SCSS、JavaScript/TypeScript
  • iOS：Swift、Objective-C颜色/字体定义
  • 安卓：颜色、尺寸、字体的XML资源

工作流示例

# 1. Pull tokens from Figma
python cli/figma_ds_sync.py pull

# 2. Transform to Style Dictionary format
python cli/figma_ds_sync.py transform tokens/tokens.json tokens/sd-tokens.json

# 3. Build for all platforms
python cli/figma_ds_sync.py build

# 4. Or build for specific platform
python cli/figma_ds_sync.py build --platform css

组件推送（测试版）

将React组件作为原生组件推回Figma：

# Push single component
python cli/figma_ds_sync.py push-component src/components/Button.tsx

# Push directory of components
python cli/figma_ds_sync.py push-component src/components/

# Create component set from variants
python cli/figma_ds_sync.py push-component src/components/Button/ --as-set

支持的组件功能

  • TypeScript道具提取
  • 从联合类型中检测变量
  • 默认道具值
  • 组件文档

发展

项目结构

figma-mcp-bridge/
�� server/                 # FastAPI MCP server
   �� main.py            # API endpoints
   �� figma_client.py    # Figma API client
   �� design_token_utils.py  # Token utilities
�� cli/                   # CLI tool
   �� figma_ds_sync.py  # Typer CLI app
�� tokens/                # Token files
�� .github/workflows/     # GitHub Actions
�� figma-agent.yaml      # Claude agent config

运行测试

# Install dev dependencies
pip install pytest pytest-asyncio

# Run tests
pytest tests/

Figma设置

  1. 生成个人访问令牌：

    • 前往Figma� 设置� 个人访问令牌
    • 创建具有文件读/写权限的新令牌

  2. 获取您的文件ID:

    • 在浏览器中打开Figma文件
    • 从URL复制ID： figma.com/file/[FILE_ID]/...

  3. 启用开发模式：

    • 在Figma中打开文件
    • 在工具栏中切换开发模式

故障排除

常见问题

  1. 认证错误

    Error: FIGMA_PAT environment variable not set

    解决方案：确保 .env 文件存在有效令牌

  2. 找不到文件

    Error: Failed to fetch Figma file

    解决方案：验证文件ID和令牌权限

  3. 令牌验证失败

    Error: Token 'primary' missing 'value' field

    解决方案：确保令牌遵循所需的结构

贡献

  1. 分叉存储库
  2. 创建特征分支(git checkout -b feature/amazing-feature)
  3. 提交更改(git commit -m 'Add amazing feature')
  4. 推送到分支(git push origin feature/amazing-feature)
  5. 打开拉取请求

许可证

MIT许可证-请参阅 许可证 详细信息文件

作者

杰克A(@jgtoletino)

Built with d for the design-to-code community

相关 MCP