Architecture Journal
Figma-to-Code 之前：先建立 Design Evidence Pack 對齊需求與技術規格
從設計開始做功能時，輸入不一定是完整的 Figma file。
可能是一組 Figma frames，也可能是 Stitch 產生的 UI、Claude 根據 prompt 做出的 prototype、一張 screenshot，甚至只是白板 wireframe。
這些工具能加快 UI 探索，但輸出通常還不是一份可以直接交給團隊實作的規格。畫面能告訴我們元件怎麼排列，卻不一定能說明誰可以操作、資料從哪裡來、狀態怎麼轉換、API 如何定義，以及錯誤發生時系統要做什麼。
Figma-to-Code 之前，需要先把 UI/UX 輸出整理成有來源、可追蹤的 Design Evidence Pack，再依不同角色轉換成可實作的規格：
flowchart TD
A[UI/UX tool output] --> B[Design Evidence Pack]
B --> C[SA: Business Requirements]
C --> D[SD: Technical Design]
D --> E[Frontend / Backend implementation contracts]
E --> F[Implementation delivery and verification]本文中的 SA 負責整理業務與行為資訊，SD 負責整理系統、API、資料與技術限制。SD 定義系統層級的技術決策與契約。前端和後端的 implementation contract，則是同一份 Technical Design 針對不同實作者整理出的角色視圖。
先理解 UI/UX 工具輸出缺少什麼
不同工具提供的訊息密度不一樣，但共同點是：它們能產生設計線索，不能自動補齊完整的 business semantics 與 production contract。
| 輸入 | 最適合提供的資訊 | 通常還缺少什麼 |
|---|---|---|
| Figma | frame、component、variant、token、layout、prototype link | 完整 business rule、API semantics、DB design |
| Figma MCP／Code Connect[3] | design context、變數、元件與 code component mapping | domain decision、完整 production architecture |
| Stitch[2] | UI variant、layout exploration、初步 frontend code | approved design、domain model、backend contract |
| Claude 或其他 multimodal agent | screenshot interpretation、flow draft、spec draft | source confidence、正式決策、技術契約 |
| 純 screenshot／wireframe | 視覺結構與互動線索 | 元件語意、狀態、資料、權限與 responsive 規則 |
因此，對需要進入正式開發流程的功能，第一個產物應該是 Design Evidence Pack，code 留到後面。工具可以產生候選畫面，agent 可以協助解析畫面，但最後仍要把「看得到的內容」和「推測出來的內容」分開。
Coinbase 如何讓 AI 參與實作
Coinbase 的案例補充了一個重要細節：AI 不只是根據畫面產生 code，還需要一組能限制輸出方向的上下文與工作流程[1]。
Screenshot 是視覺輸入，不是完整規格
Coinbase 的 frontend workflow 會把每個 Figma tab 截成 screenshot，再交給 agent。他們選 screenshot，是因為它能一次保留頁面的 visual hierarchy 和 component relationship；相較之下，structured design data 可能把視覺關係拆成較零散的資訊，也會增加上下文成本[1]。
這是 Coinbase 對自身 workflow 的取捨，不是 screenshot 比 Figma、Figma MCP、Code Connect、Stitch 或 Claude 更完整。Screenshot 能提供視覺線索，但不一定包含 component metadata、variables、prototype semantics、code mapping、domain decision 或 production contract。輸入方式應依任務、工具成熟度、上下文成本和團隊流程選擇。
Reference implementation、rules document、prompt templates
Coinbase 將三種既有資產組合成 agent 的工作上下文：
- Reference implementation：讓 agent 參考既有 component、route、data fetching、命名、測試、permission 和註冊方式，理解團隊希望複製的結構與慣例。
- Rules document：把 page structure、component pattern、data fetching、permission、validation、error handling、audit logging、service registration，以及 lint、type check、tests 和 coverage gates 寫清楚。
- Prompt templates：固定 product、route、endpoint、設計輸入、reference implementation 和 rules 等欄位，讓每次 feature context 都能用一致格式組合。
這三項不是取代 Figma 或其他設計輸入，而是讓 agent 能把不同輸入轉成符合團隊慣例的 code。Prompt 也不是品質保證；如果設計來源不明、reference 不適用，或規則沒有定義清楚，agent 只會更快產出錯的方向。
Plan、scaffold、slice，讓產出可以 review
Coinbase 一開始讓 agent 一次生成完整 frontend page，得到過 85 個檔案、超過 6,300 行新增內容；backend 版本則是 19 個檔案、超過 14,000 行新增內容。程式可以運作，卻大到難以進行有效的人工 review[1]。
後來他們使用 orchestrator pattern：先由 agent 產生 component-by-component plan，等待工程師確認；再建立 folder structure、routing、permissions、空 stub 和 validation gates；最後由平行 worker 依 tab 或 upstream service group 實作，開出較小的 draft PR。重新執行 frontend generation 後，原本一個 85-file PR 被拆成 7 個較小的 PR[1]。
這裡的重點不是讓 AI 取代 SA、SD、前後端或 QA，而是讓 agent 負責較規則化的 translation work；角色分工仍負責補上 business meaning、technical contract 和 verification conditions。
Design Evidence Pack：所有角色共用的中間層
Design Evidence Pack 不負責決定業務或技術方案，只負責把設計材料整理成可引用的 evidence。它讓 SA、SD、前端和後端使用同一份有來源的輸入，不必各自重新解讀原始設計檔。
先盤點三類 evidence
- 畫面與結構：screen、route、tab、modal、drawer、navigation、component、variant、props、token 與 asset。
- 行為與狀態：loading、empty、error、success、disabled、read-only、permission denied、validation、confirmation、retry、undo 與 duplicate submission。
- 跨裝置與可用性：responsive viewport、breakpoint、long text、large number、overflow、keyboard、focus、accessible name 與 contrast。
每個 observation 都要附來源，例如 Figma node URL、Stitch export、screenshot 或 prototype link。
把觀察與推測分開
每筆 evidence 使用三種標記：
observed：設計上明確看得到inferred：從視覺或互動合理推測unknown：從目前輸入無法判斷，或尚未完成決策
例如，畫面上有一個 Create 按鈕，可以記錄：
observed: 畫面上有 Create button
inferred: 點擊後可能建立一個 resource
unknown: 是否需要二次確認、誰可以操作、失敗後是否可重試Create 是設計 evidence；它對應哪個 business operation，則需要後續分析。這個區分也能避免 agent 把推測直接寫成需求或技術決策。
Design Evidence Pack 的最小格式
EVID-001
source: Figma node URL
type: screen | component | interaction | token | asset
observed: 畫面上實際看得到的內容
inferred: 從設計合理推測的內容
unknown: 從目前輸入無法判斷，或尚未完成決策的事情
confidence: high | medium | low
related_nodes: 相關 frame 或 component完成這一層後，所有由設計衍生的需求、API 與測試，都能回指原始設計線索；其他技術或業務決策則回指對應的決策來源，避免只留下「這是設計師或 agent 說的」這種無法追蹤的描述。
從 evidence 轉成角色專用規格
同一筆 evidence 會被不同角色轉換成不同資訊。SA 關心它代表什麼業務行為；SD 關心系統如何提供這個能力；前後端則需要可以直接實作和整合的 contract。
SA：定義業務行為與語意
SA 的文件重點在整理畫面背後的業務與行為，同時回答四件事：
- 這個功能服務什麼 problem、goal、actor 與 user role？
- 它提供哪個 use case 或 business capability？
- 有哪些 business rule、business state、scope 與 out-of-scope？
- 欄位代表什麼業務資料，以及什麼結果算符合目的，也就是
acceptance intent？
例如，從前面的 Create button，SA 需要補出：
Use case: 建立 resource
Actor: 具備 resource:create 權限的使用者
Precondition: 必填欄位合法，且使用者屬於可操作的組織
Main flow:
1. 使用者填寫欄位
2. 系統驗證輸入
3. 系統建立 resource
4. 系統顯示成功結果並導向 detail
Business rule:
- 同一個 external reference 不可重複建立
- 建立失敗時不得產生半完成資料
Acceptance intent:
- 合法輸入可成功建立
- 重複 reference 顯示可理解的錯誤
- request 重送不會重複建立 resource這份資料描述「系統要提供什麼行為」；API 和資料庫設計留到後續的 SD 階段。
SA 也需要定義欄位的業務意義：
| 欄位 | 業務意義 | 必填 | 合法值 | 真實來源 | 敏感性 |
|---|---|---|---|---|---|
| resource status | resource 目前所處的業務狀態 | 是 | draft／active／archived | Resource service | internal |
這一層要先回答：archived 能不能回到 active？使用者看到的是本系統狀態，還是 upstream 狀態？哪些角色可以改變狀態？哪些欄位不能被使用者直接修改？這些是 business semantics，應該先被定義，技術設計才有穩定的輸入。
SD：把業務能力轉成系統契約
SD 的文件負責把業務能力轉成系統可以實作的邊界與契約，主要分成四組：
- 邊界與介面：service boundary、API resource、operation、request／response schema。
- 安全與錯誤：authentication、authorization、permission、error model、retryability、idempotency。
- 資料與執行：database schema、constraint、index、query pattern、transaction、concurrency。
- 非功能需求：performance、audit、observability、migration、rollback 與 compatibility。
例如，SA 定義「可以依狀態與日期範圍查詢自己組織的 resource」，SD 再設計 API：
GET /resources?status=active&from=2026-01-01&to=2026-01-31&cursor=...&limit=50這份 contract 還需要明確說明：
- organization scope 由 server-side authorization 決定，不信任 client 傳入的 organization id。
- status 和日期範圍的 filter semantics 要寫進 contract。
- 大量資料採用 cursor pagination，index 要對應實際 query pattern。
- response schema、error code、retryability、timeout 和 rate limit 都要明確。
API 要提供穩定的 business capability interface，不必逐一暴露畫面上的欄位。
API contract 可以用 OpenAPI[4] 固化，讓 request、response 與 error schema 有共同格式。
Technical data dictionary 則處理 API 與資料庫的實際表示：
| Business field | API type | DB type | Nullable | Constraint | Index | Transform |
|---|---|---|---|---|---|---|
| resource status | enum string | varchar(32) | No | status enum | composite index | direct mapping |
SD 還需要決定 primary key、foreign key、unique constraint、normalization 或 denormalization、transaction boundary、locking、concurrency、retention 與 migration。業務資料字典定義語意，技術資料字典定義實作，兩者不應混在一起。
前端：取得畫面與互動的 implementation contract
前端需要一份與畫面和互動直接相關的角色視圖。這份視圖不必包含整份原始 Figma，也不能只丟一段沒有上下文的 API spec；至少要交代：
- route、navigation entry、route guard、screen structure、component、variant 與 code component mapping。
- API query、mutation、cache、refetch、pagination、form schema、validation timing 與 unsaved changes。
- loading、empty、error、permission、disabled、success、retry、duplicate submission、optimistic update 或 rollback。
- responsive、keyboard、focus、semantic HTML、accessible name，以及 visual acceptance 的 viewport、reference screenshot 與允許差異；accessibility checks 可對照 WCAG 2[5]。
前端需要一張可以直接對照的 mapping：
| UI action | Business capability | API ID | Permission | Loading／error behavior | Verification ID |
|---|---|---|---|---|---|
| Create button | 建立 resource | API-001 | resource:create | disable submit、顯示 field error | AC-001 |
| Status filter | 查詢 resource | API-002 | resource:read | loading state、保留 filter | AC-002 |
這張表讓前端知道每個互動背後的 business operation、API 和預期狀態，不必從畫面自行猜測。
後端：取得 API、資料與執行的 implementation contract
後端規格要描述表格背後的查詢能力、資料來源、權限與效能要求，不能只記錄「這個畫面有一個表格」。至少要交代：
- API operation、handler／use case mapping、request validation、business validation、response schema 與 field source。
- authorization、resource scope、error model、error forwarding、retry behavior 與 negative path。
- repository、upstream client、transaction boundary、query pattern、expected scale、index 與 latency target。
- audit event、correlation id、metrics、logs、traces，以及 unit、integration、contract、permission 與 performance tests。
例如，前端的 status filter 轉到後端後，至少要能回答：
API: GET /resources
Query: status, from, to, cursor, limit
Permission: resource:read
Scope: current user's organization
Data source: resource service database
Pagination: cursor-based
Error: invalid date range → 400
Performance target: p95 < agreed threshold
Verification: API contract + permission + query plan test畫面只顯示結果；後端規格要說清楚結果怎麼被正確、有效率且安全地取得。
角色與交付如何接起來
交付要讓每個產出都有明確 owner、交付對象，以及下一階段可以直接使用的內容。
| 角色 | 主要負責工作 | 主要交付物 | 交付對象 | 交付重點 |
|---|---|---|---|---|
| Design / UX | 視覺、互動與元件整理 | approved frames、prototype、state inventory | SA、SD、Frontend | 視覺、互動、狀態、responsive |
| SA | 業務目標、actor、use case、business rule | Business Requirements、business state、business data dictionary | SD、前後端、QA | 業務語意、scope、規則、acceptance intent |
| SD | 系統邊界、API、DB、效能與安全設計 | Technical Design、API contract、DB design、NFR | 前後端、QA、Security／DBA | 契約、資料、效能、安全限制 |
| Frontend | 畫面、互動與 client state 實作 | frontend code、visual diff、UI tests | Design、SA、SD、QA | 畫面、互動、狀態、accessibility、API |
| Backend | API、domain logic、persistence 與整合實作 | backend code、migration、API／contract tests | SD、Frontend、QA | API、權限、資料、錯誤、監控 |
| QA | verification 執行與結果整理 | test result、verification report、defect report | SA、SD、Release owner | 覆蓋率、結果、回歸、發布證據 |
本文不把驗收當成另一個與交付並列的角色流程。acceptance intent 是 SA 對預期業務結果的描述；visual acceptance 是前端 contract 中的設計基準；AC／Verification ID 是可執行、可追蹤的驗證案例；verification 則是 QA 和工程團隊交付的測試結果。它們分別存在於不同交付物中，再透過 ID 串起來。
從規格到實作：用 traceability 串起交付
文件拆分與索引方式可依團隊現有的工具和協作習慣決定；以下先聚焦在分工與流程。
1. 固定輸入與版本
先建立 feature intake，固定 feature id、設計來源和版本。輸入可包含 Figma node links、Stitch 或 Claude export、approved viewport、design system、reference implementation、repo、已知的 route 或 upstream API。
如果目前只有 screenshot，先標成 prototype，不要直接標成 ready for implementation。
同時記錄 actor、目標、scope 和限制。
2. 產生 evidence，再形成業務與技術規格
由 agent 協助整理 screens、components、states、tokens 和 assets，並標記 observed、inferred、unknown。接著由 SA 形成 Business Requirements，再由 SD 形成 Technical Design。
這兩個階段的完成條件不同：SA 階段要讓團隊知道系統要支援什麼行為；SD 階段要讓前後端知道依賴什麼 contract，以及系統如何支援主要 query 和 state transition。
3. 產生角色視圖與 traceability
同一份 feature spec 可以依角色輸出不同 view，不需要每個人閱讀所有內容。至少維護一張 mapping：
前一張 mapping 是給前端直接實作的 view；這一張則補上 requirement、business rule 與 data effect，作為跨角色追蹤用的 view。
| UI action | Requirement | Business rule | API ID | Data effect | Verification ID |
|---|---|---|---|---|---|
| Create | FE-001 | BR-001 | API-001 | insert resource | AC-001 |
如果一個 UI action 沒有對應的 business rule、API 或 verification，通常代表規格還缺一段。這裡以 AC-001 作為可執行驗證案例的 ID；團隊也可以依既有慣例改用 TEST-001。requirement ID、API ID 和 Verification ID 讓交付物與後續驗證可以互相追蹤。
4. Slice、驗證與回寫
先輸出 component、screen、service 或 upstream group 的 plan，再建立 route、permission、API、migration 和 test skeleton，最後切成可以獨立 review 的 slices。
這和前述 Coinbase 的做法一致：不要把整個頁面一次塞成巨大 PR。讓每個 slice 都有自己的 requirement IDs、API IDs、tests、owner 和 reviewer，審查才跟得上產出速度[1]。
最後分層產生 verification evidence。若要延伸閱讀測試與驗收如何建立信任系統，可參考這篇自動化測試與驗收文章：
| 驗證層 | 主要問題 |
|---|---|
| Business | 功能是否符合 use case 和 business rule？ |
| Visual／Interaction | 畫面、狀態與互動是否符合 approved design？ |
| API／Data | contract、schema、query 和 error behavior 是否正確？ |
| Security／Operations | 權限、audit、效能、監控與 rollback 是否可用？安全檢查可參考 OWASP ASVS[6]。 |
實作過程出現變更時，也要回寫到正確層次：技術細節更新 Technical Design，API 改變更新 contract，business semantics 改變則回到 Business Requirements 做決策。
先整理 evidence，再交付可追蹤規格
UI/UX 工具的價值，是縮短探索與表達介面的時間；它們不必承擔完整需求規格的責任。
做法是把工具輸出先轉成有來源、有 confidence、有 unknown 的 Design Evidence Pack，再依角色轉換：
- SA 取得 actor、use case、business rule、state 和 acceptance intent。
- SD 取得 service boundary、API、DB、query、security 和 operational constraints。
- 前端取得 route、component、state、API mapping 和 visual acceptance。
- 後端取得 operation、schema、validation、persistence、query 和 test requirements。
這樣不論輸入來自 Figma、Stitch、Claude 或一張 screenshot，後面的規格流程都可以維持一致。AI 負責加速擷取、整理和轉換，團隊仍要決定 business meaning、technical contract 和 verification conditions。要先對齊的，是每個角色交付什麼、下一個角色依據什麼往下做，以及變更發生時要回寫到哪一層。
參考資料
- [1] Coinbase，
Automating Figma-to-Code at Coinbase - [2] Google Developers，
From idea to app — Introducing Stitch - [3] Figma，
Guide to the Figma MCP server - [4] OpenAPI Initiative，
OpenAPI Specification - [5] W3C，
WCAG 2 Overview - [6] OWASP，
Application Security Verification Standard