❯❯ AI 生成之後呢？Vibe UI 治理：如何劃開語意與樣式邊界，避免視覺優化引發業務退化

📍 流水線位置｜入口 → flow → 型別 → mock → 測試 → UI → 【vibe】 → 上線（Arc 開場）

婚禮系統開發到一半，公開頁面（無須登入即可存取）在特定環境下突然出現嚴重的配色偏差，甚至連區塊都載入不完整。我把前端邏輯和樣式定義翻了兩輪，明明什麼都沒錯。最後真相是：系統被切換到深色模式（Dark Mode），頁面自動套上了預設深色樣式。

這起事故最終的修復紀錄收錄於 Issue #82：全站一律強制鎖定為淺色模式（Light Mode），不跟隨作業系統設定切換。

這件事也點出了前端介面驗收的盲點：

視覺呈現對不對，根本不能只靠開發者用肉眼「看一眼」來驗證。

用肉眼驗收 UI，非常容易產生雙向誤判。Issue #82 的狀況正是第一種：把明明正常的介面誤判為異常，白白浪費兩輪排查時間。至於更致命的第二種是把已經壞掉的業務邏輯誤判為正常，雖然這次沒發生悲劇，但既然肉眼連「好的東西」都會看錯，我們哪來的自信相信它能精準抓出「壞掉的東西」？

當系統從基礎原型跨入視覺與體驗重構階段（Vibe UI Phase）時，要是沒有一套客觀的驗證機制，單純改改 UI 樣式，隨時都可能默默把原本正常的業務功能改壞（Regression）。

這正是接下來幾天我們要深入探討的核心問題。

而我的解法，就是整套 AI 規格流水線裡我最想分享的部分。當初翻遍了市面上的現成框架，根本找不到能完美處理這問題的答案，最後乾脆自己做一套流程。

視覺調整與業務語意的衝突

在 Day 17 的自動化流水線執行完畢後，E2E 測試套件全數通過驗證。這時系統功能雖然完全正常，但介面就只是個基本原型，明眼人一看這又是個標準的「工程師 AI 直出作品」。

當準備要進行介面視覺優化時，危機才剛要開始。無論是調整配色系統、把跳出式 Modal 改成頁面內嵌元件、將表格改為卡片流，還是加上微互動效果，最容易踩到的坑就是：視覺元件一換，可能無意間連底層的業務語意（Business Semantics）也被一併破壞了。

舉個賓客名單「報到狀態」的例子：

• 原始實作： 使用直白的文字標籤（已報到 / 未報到）呈現。
• 重構實作： 為了畫面簡潔，把文字乾脆砍掉，改用顏色點代替（綠點代表已報到，灰點代表未報到）。

這類調整在視覺上或許變美了，但在工程維護與無障礙（Accessibility）上，卻默默埋下了兩大深坑：

1. 無障礙（a11y）直接棄守：
在宴會現場昏暗的燈光下，視覺障礙或色弱使用者完全無法辨識沒有文字標註的顏色小點。

2. 測試自動化失效：
自動化測試腳本與螢幕閱讀器（Screen Reader）原本都是靠 DOM 裡面的「文字語意」來抓元件、做斷言。當文字被硬生生換成沒有語意的顏色點，測試與 DOM 的連結當場斷裂。

文字標籤不僅是視覺呈現，它更是系統核心的業務語意。當我們為了畫面好看而侵蝕了業務語意，下場就是：表面上畫面美美美，實際上功能早就默默壞掉了。

鎖死或放飛，都不是答案

面對「視覺重構」與「功能穩定」的衝突，傳統開發很容易走入兩種極端，而且兩邊都是坑：

• 過度約束：
  將 UI 的任何細節變更都當成重大變更，每次動到樣式就要跑全量 E2E 回歸測試與人工驗收。穩是穩了，但改個介面成本高到嚇人，最後團隊乾脆擺爛：「沒壞就別動它」，任由 UI 停留在原型時代。

• 完全放飛：
  讓工程師或 AI 隨意改樣式、換 DOM 結構，等到線上爆掉或測試失敗才被動修補。這種做法會讓業務邏輯的入口在一輪輪的視覺改版中被默默擦掉，留下極度痛苦的維護地獄。

這兩種極端之所以會互相拉扯，關鍵就在於我們沒有把「UI 的視覺呈現」跟「UI 的業務語意」徹底解耦（Decoupling）。 當這兩件事被綁在一起時，追求美感與維持穩定就注定只能二選一。

解法的起點：把語意與樣式劃開

要解開這個結，架構上的核心關鍵，就是在 UI 元件內部劃出極度明確的權責邊界：

1. 業務語意層（Business Semantic Layer）：
包含實體識別碼、狀態可讀性、元件定位標籤（data-testid）與核心操作路徑。這一層屬於系統合約，不管視覺怎麼改，都必須嚴格守住、絕對不能動。

2. 樣式呈現層（Visual Style Layer）：
包含色彩、排版、邊距、圓角與微動效。這一層完全開放給 AI 與設計資源，自由進行視覺的解構與重構。

這條邊界劃分貫徹了 Day 05 的規格分離原則：

業務行為定義於 .feature 檔案，外觀配置收納於 ui-config.yaml。在 UI 重構階段，該原則被進一步落實於前端程式碼結構之中。

邊界立起來之後，視覺層的迭代就不再動搖業務邏輯的驗證機制。但要在日常開發裡長期守住這條邊界，還有幾個具體問題要面對：

• 邊界定義規範：
  業務語意與視覺樣式的精確劃分標準為何？

• 自動化約束機制：
  如何防止 AI 或開發人員（豬隊友XD？）在重構過程中意外改動業務語意？

• 新增互動之守護：
  重構過程中所衍生出的新型態互動（像是拖拽排序、動畫過渡），又該如何納入既有的測試合約？

接下來幾天就把這些難題逐一拆解。下一篇，我們直接來看這條邊界的三項核心工程準則，明天見！

📎 本篇證據｜ issue #82（整站鎖定 Light Mode 的修復紀錄，確認深色模式下預設樣式干擾之排查結果）