Back to Editor

Figma 设计规范（Vue + MCP Server + Lingma 自动产研版）

Markdown Document
Reading time about 3 minutes

太好了：Vue + Figma MCP Server + Lingma（VS Code） 这条链路要想“自动识别结构 → 自动出开发文档/脚手架”，关键是让 Figma 里的信息能稳定落到**“可解析的结构化元数据 + 可映射的组件/样式 token”**。

下面我给你一份 “Vue & MCP & Lingma 专用增强版规范（Markdown）”。你可以直接丢到团队 Confluence / 仓库 /docs/design/figma-spec.md，也可以作为 Figma 00_Cover 页面里的规范文本。

Figma 设计规范（Vue + MCP Server + Lingma 自动产研版）

目标：让 MCP Server 能稳定解析页面结构（Layout Tree / Component Tree / Tokens / States / Interaction），Lingma 在 VS Code 中能一键生成：

  • 页面开发文档（路由、接口、状态、权限、字段、组件依赖）
  • Vue 组件/页面脚手架（.vue、types.ts、api.ts、route.ts 等）

0. 总体约定（你们栈的最佳实践）

  • Vue 页面 = Screen：Figma 顶层 Frame 对应 src/pages/**/index.vue
  • Vue 组件 = Component/Pattern：Figma Component 对应 src/components/**
  • Props / Emits / Slots / v-model：必须在 Figma 的 Spec 元数据里写清楚，便于生成组件接口
  • Tokens = CSS Variables / Design Tokens：Figma Variables/Styles 命名必须可直接映射到 CSS 变量、Tailwind/Uno 或你们的主题系统

1. 文件/页面（Pages）组织（建议固定）

Pages 顺序固定（减少 MCP 噪音解析）：

  • 00_Cover：规范、版本、发布说明
  • 01_Foundation：Tokens（Colors/Typography/Spacing/Radius/Shadow/Icon）
  • 02_Components：原子组件（Button/Input/Table/Modal/Drawer…）
  • 03_Patterns：组合模式（FilterBar/SearchBar/ListHeader/DetailDrawer…）
  • 20_Screens_Web：页面级设计（按模块分区）
  • 90_Archive：历史稿/草稿（不参与解析）

MCP 解析范围建议：仅扫描 01/02/03/20，跳过 90。

2. 命名规范（让 MCP 推断类型 + 生成 Vue 路径）

2.1 顶层命名格式（强制）

统一格式：

[Type] / [Module] / [Name] / [State] / [Size]

  • Type：Screen | Component | Pattern | Section | Asset
  • Module：业务模块（英文/拼音均可，但需一致，例如 Leakage / Huinan）
  • Name：页面/组件名（PascalCase 推荐）
  • State：Default | Loading | Empty | Error | Disabled | Readonly
  • Size：W1440 | W1200 | W768 | W375（或 S/M/L）

示例

  • Screen / Leakage / ValveControl / Default / W1440
  • Component / Form / Input / Default / M
  • Pattern / Leakage / FilterBar / Default / W1440

2.2 组件 → Vue 文件路径映射规则（建议写死）

让 Lingma 能“看名字就落盘”

  • Component / Button / Primary → src/components/ui/button/Button.vue
  • Component / Form / Input → src/components/ui/form/Input.vue
  • Pattern / Leakage / FilterBar → src/components/patterns/leakage/FilterBar.vue
  • Screen / Leakage / ValveControl → src/pages/leakage/valve-control/index.vue

命名约束：Name 建议用 PascalCase；落地文件夹用 kebab-case（自动转换）。

3. 页面结构骨架（让 MCP 自动识别 Layout Tree）

每个 Screen 顶层 Frame 里必须具备稳定骨架：

  • Section / Header（可选）
  • Section / Sidebar（可选）
  • Section / Content（必选）
  • Section / Footer（可选）
  • Spec / Notes（必选）
  • Spec / Data（必选）
  • Spec / Behavior（可选）

3.1 Content 内部建议分层（固定语义）

在 Section / Content 内按语义拆分容器（Frame + Auto Layout）：

  • Container / PageTitle
  • Container / ToolBar
  • Container / Main
  • Container / Secondary（可选）
  • Container / Pagination（可选）
  • Layer / FloatingAction（悬浮按钮/浮层宿主）

禁用：用 Group 当布局容器；必须用 Frame + Auto Layout。

4. Auto Layout / Constraints（决定能否生成“可用布局代码”）

4.1 强制要求

  • 可复用组件、列表行、卡片、ToolBar、表单区域：必须 Auto Layout
  • 页面主容器（Content/Main/Sidebar）：设置 Constraints（Left/Right/Top/Bottom）

4.2 Spacing 体系（推荐 8pt scale）

统一：0, 4, 8, 12, 16, 24, 32, 40, 48

在 01_Foundation 中定义变量或 styles：

  • Spacing / 4
  • Spacing / 8 …

禁止：同类间距出现大量随机值（13/15/18），会降低规则抽取质量。

5. 组件体系（Variants = Vue props 的来源）

5.1 Variants 属性命名规范（强烈建议英文）

组件必须使用 Component + Variants 表达类型/尺寸/状态：

  • type: primary | secondary | ghost | danger
  • size: s | m | l
  • state: default | hover | pressed | disabled | loading
  • icon: none | leading | trailing

对应 Vue：这些属性可以直接生成 defineProps 的 union type。

5.2 Slot 规则（必须命名 Slot 图层）

凡是可插内容的组件，必须使用固定命名：

  • Slot / Default
  • Slot / LeadingIcon
  • Slot / TrailingIcon
  • Slot / Actions
  • Slot / Header
  • Slot / Footer

对应 Vue：直接映射到 <slot name="...">。

5.3 v-model 规则（表单组件必须声明）

表单组件（Input/Select/Switch/DatePicker 等）必须在 Spec 中声明：

  • vmodel: modelValue
  • emit: update:modelValue

6. Tokens（Figma Variables/Styles → CSS 变量/主题系统）

6.1 Token 命名（可直接映射 CSS Variables）

建议统一：

  • Color / Primary / 500 → --color-primary-500
  • Color / Neutral / 50 → --color-neutral-50
  • Text / Body / M / Regular → --font-body-m-regular
  • Radius / 8 → --radius-8
  • Shadow / 1 → --shadow-1

要求：页面与组件里的颜色/字体/阴影尽量只引用 styles/variables，不要手填任意值。

6.2 Vue 落地建议

  • 方案 A：CSS Variables（推荐）
    • :root { --color-primary-500: ... }
  • 方案 B：Uno/Tailwind tokens
    • tokens 命名仍需可映射（便于生成 theme 配置）

7. 结构化元数据（MCP & Lingma 生成开发文档的关键）

强烈建议：把“可生成内容”写成结构化块（YAML/JSON），放在 Screen Frame 的 Description 或 Spec / Notes 文本层里。
YAML 对人和 AI 都友好，推荐 YAML。

7.1 Screen 元数据模板（YAML）

把下面这段复制到每个 Screen 的 Spec / Notes（或 Frame Description）：

id: leakage.valve_control
route: /leakage/valve-control
page:
  title: 爆管关阀
  layout: default        # default | full | blank
  state: [default, loading, empty, error]
permission:
  view: leakage:valve:view
  edit: leakage:valve:edit
api:
  - name: listValves
    method: GET
    path: /api/leakage/valves
  - name: closeValve
    method: POST
    path: /api/leakage/valves/{id}/close
components:
  - FilterBar
  - ValveTable
  - DetailDrawer
events:
  - onFilterChange
  - onRowClick
  - onCloseValve

效果：Lingma 可以直接生成 route.ts、api.ts、权限守卫、页面骨架和组件引用。

7.2 表格/字段映射（放 Spec / Data）

data:
  table: ValveTable
  rowKey: id
  columns:
    - key: valveName
      label: 阀门名称
      type: string
      sortable: true
    - key: status
      label: 状态
      type: enum
      enum: [OPEN, CLOSED, FAULT]
    - key: updatedAt
      label: 更新时间
      type: datetime
      format: YYYY-MM-DD HH:mm
  actions:
    - name: viewDetail
      permission: leakage:valve:view
    - name: closeValve
      permission: leakage:valve:edit

7.3 组件接口模板（放组件主 Frame 的 Spec/Notes）

对每个可复用组件写：

component: Input
props:
  modelValue: string
  placeholder: string
  disabled: boolean
  clearable: boolean
emits:
  - update:modelValue
  - change
slots:
  - LeadingIcon
  - TrailingIcon

对应 Vue：可生成 defineProps/defineEmits、slot 注释、Story/Doc。

8. 交互/状态表达（AI 更容易生成状态机/逻辑）

8.1 状态优先用 Variants

按钮、输入框、Tag、菜单项、表格行高亮等全部走 state variant。

8.2 页面状态（Empty/Loading/Error）

页面级状态用同名 Screen 的不同 State：

  • Screen / Leakage / ValveControl / Loading / W1440
  • Screen / Leakage / ValveControl / Empty / W1440
  • Screen / Leakage / ValveControl / Error / W1440

并在 YAML 的 page.state 中列出。

9. 导出资源（Icon/图像/插画）

  • Icon：统一组件化 Component / Icon / icon-close（kebab-case）
  • SVG 用于 icon；PNG 用于位图（1x/2x）
  • 导出命名：
    • asset_{module}_{name}_{size}

10. 禁止事项（会显著降低 MCP 识别率）

  • ❌ 用 Group 当布局容器（改 Frame + Auto Layout）
  • ❌ 任意颜色/字号/间距（必须 token 化）
  • ❌ 复制粘贴改状态（必须 variants）
  • ❌ 图层名无语义（矩形1/Frame123）
  • ❌ 关键说明散落在画布外/截图里/聊天里（必须进入 Spec）

11. 交付检查清单（Review 必过）

Screen 必过

  • <input type="checkbox" disabled=""> Screen 命名符合规范
  • <input type="checkbox" disabled=""> Header/Content 等骨架齐全且命名一致
  • <input type="checkbox" disabled=""> Spec / Notes 含 YAML（id/route/api/components/permission）
  • <input type="checkbox" disabled=""> 主区域全 Auto Layout + 合理约束
  • <input type="checkbox" disabled=""> 关键状态（loading/empty/error）齐全（如适用）

Components 必过

  • <input type="checkbox" disabled=""> 位于 02_Components
  • <input type="checkbox" disabled=""> Variants 覆盖 type/size/state（至少 state）
  • <input type="checkbox" disabled=""> token 引用一致（Color/Text/Effect）
  • <input type="checkbox" disabled=""> Slot 命名规范
  • <input type="checkbox" disabled=""> 表单组件声明 v-model（props/emits）

12. （给你们）Lingma 在 VS Code 的“推荐生成文档输出结构”

当 MCP 拉到 Figma JSON 后，建议 Lingma 生成如下目录（可固定模板）：

/docs
  /pages
    leakage.valve_control.md
/src
  /pages/leakage/valve-control/index.vue
  /pages/leakage/valve-control/useValveControl.ts
  /api/leakage.ts
  /types/leakage.ts
  /router/modules/leakage.ts

并在 leakage.valve_control.md 中输出：

  • 页面概述（title/route/permission）
  • 组件树（Header/ToolBar/Main/Drawer）
  • 状态（default/loading/empty/error）
  • API 列表（method/path/request/response）
  • 字段与枚举（columns/enum）
  • 事件流（onFilterChange → fetch → render）

13. 你们链路的最小落地（MVP 6 条）

只要先做到这些，识别率就会明显提升：

  1. Screen 命名统一（Type/Module/Name/State/Size）
  2. 页面骨架固定（Header/Content + Spec）
  3. Auto Layout 覆盖主要容器
  4. 组件全部 variants（至少 state）
  5. Color/Text token 化
  6. 每个 Screen 写 YAML 元数据（route/api/components/permission）

我建议下一步（我来帮你把规范“落到你们项目可用”）

你们是 Vue + MCP Server + Lingma，我可以进一步给你两样“能直接用的”东西：

  1. Lingma 提示词模板（Prompt Template）
    用于：把 MCP 输出的 Figma 节点树 + YAML 元数据 → 生成指定目录结构的开发文档/脚手架。

  2. 你们业务的词表（Dictionary）

  • Module 列表（Leakage/Pipe/Plant…）
  • state 枚举（Default/Loading/Empty/Error…）
  • permission 命名规则（{module}:{resource}:{action}）
    这样能让命名和生成更稳定。

两个关键问题（回答一下我就能给你“可直接复制到 Lingma 的模板”）

  1. 你们的 UI 组件库是 Element Plus / Ant Design Vue / 自研 哪个？（决定生成的组件标签与 props）
  2. 你们希望生成的 API 层形态：axios 封装 + api.ts，还是 TanStack Query/Vue Query 这种 hooks 化？

你回我这俩点后，我就把：

  • Figma → MCP → Lingma 的标准 Prompt
  • Vue 目录结构 + 代码骨架生成规则
    一起补齐给你（保证能直接用）。
📋 Document Outline