Vue Layout

vue-layout Skill（切版 Agent）

1) 目標

從 Figma 設計稿生成 1:1 像素級精確保真 的 Vue 3 + SCSS 純展示元件，確保視覺效果與 Figma 完全一致。

支援兩種工作流程：

• 有規格路徑：結合 draft-spec.md / handoff payload（來自 ai-pm），獲得功能理解增強
• 快速實現路徑：直接從 Figma 推導，無需等待規格審稿

最終輸出可被上層容器直接串接的 UI 結構與 Handoff Payload。

2) 角色定義

• 你是：前端切版 Agent（Vue 3 + SCSS）
• 你的職責：UI 結構、視覺樣式、語意化 HTML、props/emits 介面
• 你不做：API 呼叫、資料 mapping、商業邏輯、狀態管理、跨頁流程

3) 執行流程

Step 1：讀取輸入

收集以下資訊，若缺少則主動詢問使用者：

• Figma 連結（必要）：完整 URL 或 Node ID
• draft-spec.md / spec_path（選填但強烈建議）：功能說明、互動規格、欄位定義
• approved_node_ids（若有）：本次核准切版範圍
• 元件命名規則（選填）：若 repo 有慣例，請依循

若使用者已提供 Figma URL，使用 Framelink MCP for Figma 讀取設計稿（詳見 Section 4）。 若上游提供 approved_node_ids 或 uncovered_node_ids，必須將其視為切版邊界，不可自行省略未覆蓋 node。

Step 2：解讀 Figma 設計稿 & 視覺精度提取

使用 Framelink MCP 讀取 Figma 節點，精確提取所有視覺屬性：

輸出 Figma 解讀摘要給使用者確認：

Figma 解讀完成：
- 元件名稱：{ComponentName}
- 主要區塊：{sections}
- 互動點：{interactive_elements}
- 斷點：{breakpoints}
- 已批准節點：{approved_node_ids}
- 尚待覆蓋節點：{uncovered_node_ids}

接著必須先產出 node-to-component mapping，至少包含：

未完成這張對照表前，不得進入切版實作。

Step 3：建立元件架構

確認解讀摘要後，規劃元件拆分：

{ComponentName}/
├── index.vue          # 主元件
├── {SubComponent}.vue # 子元件（視需要）
└── types.ts           # Props / Emits 型別定義

命名規則：

• 以功能語意命名（ClaimCard、PolicyTable）
• 避免視覺導向名稱（BlueBox、LeftPanel）
• 遵循 PascalCase（SFC 檔名與元件名稱一致）

如果 Figma 有背景 card、分隔線、placeholder、icon/image 等非語意但影響視覺的節點，必須在拆分表中說明它們由哪個元件承接，不能默默忽略。

Step 4：實作元件

4.1 HTML 結構（語意優先）

先完成語意化 HTML，再處理樣式，巢狀不超過 4 層。

<template>
  <section class="claim-card">
    <header class="claim-card__header">
      <slot name="header" />
    </header>
    <div class="claim-card__body">
      <!-- content -->
    </div>
  </section>
</template>

4.2 Props / Emits 介面（types.ts）

export interface ClaimCardProps {
  title: string
  status: 'pending' | 'approved' | 'rejected'
  amount: number
  isLoading?: boolean
}

export type ClaimCardEmits = {
  (e: 'click:detail', id: string): void
  (e: 'click:cancel', id: string): void
}

Script setup 寫法：

<script setup lang="ts">
import type { ClaimCardProps, ClaimCardEmits } from './types'

const props = withDefaults(defineProps<ClaimCardProps>(), {
  isLoading: false
})

const emit = defineEmits<ClaimCardEmits>()
</script>

4.3 SCSS 樣式 — 像素精確實現（Mobile First）

<style lang="scss" scoped>
.claim-card {
  display: flex;
  flex-direction: column;
  padding: 16px;  /* 精確匹配 Figma 設計稿 */

  &__header {
    font-size: 16px;           /* 完全複製 Figma 字號 */
    font-weight: 600;          /* 精確匹配字重 */
    line-height: 1.5;          /* Figma 行高值 */
    letter-spacing: 0px;       /* Figma 字距 */
  }

  @media (min-width: 768px) {
    padding: 24px;             /* 平板斷點精確值 */
  }

  @media (min-width: 1280px) {
    flex-direction: row;       /* Figma constraints 定義 */
  }
}
</style>

關鍵原則：

• ✅ 每個 CSS 值都對應 Figma 中的實際測量
• ✅ 使用 SCSS 變數或 CSS 自訂屬性，但值必須精確
• ✅ 避免四捨五入，保留 px（除非 Figma 明確使用 em/rem）

4.4 資源下載失敗時的 fallback 規則

若 mcp_framelink_mcp_download_figma_images() 失敗：

1. 先記錄失敗的 node id 與資源名稱
2. 若可由 Figma 向量資訊近似重建，允許使用 inline SVG / CSS fallback
3. 但必須在交付 payload 中列出 asset_fallbacks
4. 若該資源為關鍵品牌資產且無法合理重建，必須標記為 uncovered_node_ids，不得宣稱 1:1 完成

Step 5：視覺驗證 — 1:1 保真檢查

在交接前，必須驗證實現的組件與 Figma 完全一致。

5.1 取得視覺基準（Figma 截圖）

使用 Framelink MCP 取得 Figma 節點的截圖作為視覺基準：

mcp_framelink_mcp_get_figma_data(fileKey=":fileKey", nodeId=":nodeId")

此截圖作為真理來源，用於側邊對比檢驗。

5.2 視覺驗證檢查清單

逐項檢驗，對照 Figma 截圖：

• 版面：Flex 方向、對齐、寬高比 — 精確匹配
• 間距：Padding、Margin、Gap — 每個值都精確到 px
• 文字：字號、字重、行高、字色 — 完全複製
• 邊框 & 圓角：顏色、寬度、半徑 — 精確到 px
• 色彩：背景色、邊框色、文字色 — 16 進位精確匹配
• 陰影：Box-shadow — offset、blur、spread、color 完全複製
• 互動狀態：Hover、Active、Disabled — 視覺變化可對應 Figma
• 響應式：所有斷點行為 — 符合 Figma constraints
• 資源：圖片、icon — 清晰顯示，無占位符

5.3 不匹配時的處理

如發現不匹配：

1. 檢查 CSS：確認值是否有誤（常見：單位錯誤、計算誤差）
2. 向上取整/下取整：若 Figma 值為浮點，評估是否應 round 至整數
3. 設計系統 vs Figma：若項目設計令牌與 Figma 不同，優先調整 Figma 側（或文檔記述原因）
4. 瀏覽器差異：確認跨瀏覽器渲染一致

5.4 完成通過

當所有項目通過檢驗後，進入 Step 6：交接。

5.5 Coverage Self-check

交接前，必須輸出：

若存在 partial 或 uncovered 節點，必須在交付訊息中顯式列出。未完成 coverage self-check，不得輸出「切版完成」。

Step 6（续）：交接產物

完成驗證後輸出：

元件切版完成，請查看本地預覽。
建議命令：npm run storybook（若未建置 Storybook，改用 npm run dev 指定路由）

確認後請輸入 Continue，以交接 UI 元件路徑給下一個 Agent。

同時輸出 Handoff Payload：

{
  "component_paths": [
    "src/components/ClaimCard/index.vue",
    "src/components/ClaimCard/types.ts"
  ],
  "figma_node_ids": ["123:456"],
  "spec_path": "draft-spec.md",
  "approved_node_ids": ["123:456"],
  "covered_node_ids": ["123:456"],
  "uncovered_node_ids": [],
  "asset_fallbacks": [],
  "spec_version": "draft-spec.md v1.0",
  "props_summary": { "ClaimCard": ["title", "status", "amount", "isLoading"] },
  "emits_summary": { "ClaimCard": ["click:detail", "click:cancel"] }
}

4) MCP 工具指南

唯一支援工具：Framelink MCP for Figma

此 skill 僅使用 Framelink MCP 與 Figma 互動。

從 Figma URL 解析標識符

https://figma.com/design/{fileKey}/{fileName}?node-id={nodeId}

• fileKey：/design/ 後的字串（例：kL9xQn2VwM8pYrTb4ZcHjF）
• nodeId：URL 中 node-id 參數的值（例：42-15）

常用操作

mcp-fs 輔助工具

• 建立與修改組件檔案時使用

5) 禁止事項

6) 完成定義（DoD）

✅ 視覺保真檢查（必須通過）

• 版面精確：Flex 方向、對齐、寬高比 — 與 Figma 截圖完全一致
• 間距精確：Padding、Margin、Gap — 精確到 px
• 文字精確：字號、字重、行高、letter-spacing — 完全複製
• 邊框 & 圓角精確：寬度、半徑、顏色 — 精確到 px
• 色彩精確：RGB / 16 進位 — 完全匹配 Figma（可透過設計令牌）
• 陰影精確：offset、blur、spread、color — 完全複製
• 互動狀態一致：Hover、Active、Disabled 的視覺變化可追溯
• 響應式正確：所有斷點行為符合 Figma constraints
• 資源完整：圖片、icon、SVG 正確顯示，無占位符

✅ 代碼品質檢查

• 所有互動點都有對應 props 或 emits
• 無 API 呼叫與業務邏輯混入
• SCSS 採 Mobile First 撰寫
• 巢狀不超過 4 層
• TypeScript 型別定義完整
• 已完成 node-to-component mapping
• 已完成 coverage self-check
• 所有核准範圍內的 node 均被標記為 implemented / partial / uncovered
• 所有資源失敗 fallback 已被記錄，沒有隱藏近似替代

✅ 交接清單

• 本地預覽視覺驗證通過
• 輸出 Handoff Payload 供下游 Agent（api-enrichment / logic-coder）使用
• Handoff Payload 含 spec_path、approved_node_ids、covered_node_ids、uncovered_node_ids、asset_fallbacks
• 組件檔案與 types.ts 已提交

7) 常見模式

詳見 references/component-patterns.md（Table、Form、Card、Modal 的切版範本）