Figma SIR Compiler

将 Figma 设计转换为语义中间表示的编译器，支持代码生成。

安装

npm install figma-sir-compiler

CLI 使用

1. 创建配置文件

在项目根目录创建 figma.config.json：

npx figma-sir init

或手动创建：

{
  "figmaToken": "your-figma-token",
  "fileKey": "your-file-key",
  "nodeId": "",
  "outputDir": "output",
  "cacheDir": ".figma-cache",
  "filterRules": {
    "namePatterns": ["status bar", "tab bar", "nav bar"],
    "filterHidden": true
  }
}

2. 运行编译

npx figma-sir compile

CLI 命令

# 编译 Figma 文件
npx figma-sir compile

# 强制刷新缓存
npx figma-sir compile --refresh

# 初始化配置文件
npx figma-sir init
npx figma-sir init --force  # 覆盖已存在的配置

Figma UI 设计约定

遵循本文档可确保 Figma 设计稿被正确解析为高质量的 DSL 和 Vue 代码。

目录

1. 文件结构
2. 页面命名
3. 图层命名规范
4. 节点类型识别规则
5. 样式约定
6. 交互原型
7. 组件使用
8. 常见问题

1. 文件结构

1.1 层级结构

📁 Figma 文件
├── 📂 Canvas (画布)
│   ├── 📁 SECTION: Flow 名称        ← 定义一个用户流程
│   │   ├── 🖼️ FRAME: Page 1         ← 页面（必须放在 SECTION 下）
│   │   ├── 🖼️ FRAME: Page 2
│   │   └── 🖼️ FRAME: Page 3
│   │
│   └── 📁 SECTION: 另一个 Flow
│       ├── 🖼️ FRAME: Login
│       └── 🖼️ FRAME: Home

1.2 关键规则

| 规则 | 说明 | |------|------| | ✅ SECTION = Flow | 每个 SECTION 会被识别为一个用户流程 | | ✅ FRAME = Page | SECTION 下的 FRAME 会被识别为页面 | | ❌ 禁止嵌套 SECTION | SECTION 不应嵌套在其他 SECTION 内 | | ❌ 禁止游离 FRAME | 页面 FRAME 必须放在 SECTION 下，否则不会被识别 |

1.3 示例

✅ 正确：

Canvas
└── SECTION: Checkout Flow
    ├── FRAME: Cart
    ├── FRAME: Shipping
    ├── FRAME: Payment
    └── FRAME: Confirmation

❌ 错误：

Canvas
├── FRAME: Cart           ← 不会被识别（游离页面）
└── SECTION: Checkout
    └── SECTION: Payment  ← 错误嵌套

2. 页面命名

2.1 页面名称规范(推荐)

页面名称会直接影响生成的文件名和路由路径，请使用清晰、有意义的命名。

| 命名风格 | 示例 | 生成的文件 | |---------|------|-----------| | 驼峰命名 | ProductPage | product-page.vue | | 空格分隔 | Product Page | product-page.vue | | 连字符 | product-page | product-page.vue |

2.2 推荐命名

| 页面类型 | 推荐命名 | |---------|---------| | 首页 | Home | | 登录 | Login | | 注册 | Sign up / Register | | 商品详情 | Product Page | | 购物车 | Cart | | 结账 | Checkout | | 个人中心 | Profile / Settings | | 搜索 | Search / Search results |

3. 图层命名规范

3.1 自动识别的命名关键词

以下关键词会触发特定的语义识别：

按钮 (Button)

✅ "Button", "Btn", "CTA", "Action", "Submit"
示例：Button Primary, Submit Button, CTA Buy Now

标签 (Tag/Badge)

✅ "Tag", "Badge", "Chip", "Label"
示例：Tag New, Badge Sale, Chip Filter

导航栏 (NavigationBar)

✅ "Nav", "Header", "Top Bar", "Title Bar"
示例：Navigation Bar, Header Home, Top Bar

底部标签栏 (TabBar)

✅ "Tab Bar", "Bottom Nav", "Footer Nav"
示例：Tab Bar Main, Bottom Navigation

输入框 (Input)

✅ "Input", "Field", "Search Field", "Text Field"
示例：Input Email, Password Field, Search Field

文本字段组 (TextField)

✅ "Text Field" (容器名)
子元素会自动识别为：
  - Label (标签文本)
  - Input (输入区域)
  - HelperText (帮助文本)

卡片 (Card)

✅ "Card", "Item", "Product", "Listing"
示例：Product Card, List Item, Card Featured

3.2 命名最佳实践

✅ 好的命名：
├── Button Primary
├── Input Email
├── Card Product
├── Tag New
└── Navigation Bar

❌ 不推荐的命名：
├── Rectangle 123        ← 无意义默认名
├── Frame 1              ← 无意义默认名
├── Copy of Button       ← 复制后的默认名
└── 矩形 1               ← 非英文命名

6.2 设置交互原型

在 Figma 中设置 Prototype 连接：

1. 选中要添加交互的元素（如按钮）
2. 在右侧面板切换到 Prototype 标签
3. 拖拽连接线到目标页面
4. 设置触发条件：
   - On click → 点击触发
   - On hover → 悬停触发
5. 设置过渡动画：
   - Smart Animate
   - Dissolve
   - Push / Slide

6.3 交互数据示例

Figma 设置：

Button "Buy Now"
├── Trigger: On Click
├── Action: Navigate to
├── Destination: Product Page
└── Transition: Smart Animate, 0.3s, Ease Out

生成的 DSL：

{
  "type": "Button",
  "props": {
    "name": "Buy Now",
    "interactions": [{
      "trigger": "click",
      "action": "navigate",
      "target": "Product Page",
      "transition": {
        "type": "SMART_ANIMATE",
        "duration": 0.3,
        "easing": "ease_out"
      }
    }]
  }
}

6. 组件使用

6.1 组件实例 (INSTANCE)

使用 Figma 组件可以保持一致性，组件引用会被提取：

设计稿中：
├── INSTANCE: "Button Primary"
│   └── componentId: "109:2240"
│   └── componentName: "Button Primary"

生成的 DSL：
{
  "type": "View",
  "props": {
    "componentId": "109:2240",
    "componentName": "Button Primary"
  }
}

6.2 组件属性

组件的覆盖属性会被提取：

{
  "componentProperties": {
    "Text": { "type": "TEXT", "value": "Submit" },
    "Disabled": { "type": "BOOLEAN", "value": false }
  }
}

License

MIT