DESIGN.md 都寫了，AI 頁面為什麼還是一接數據就崩？

哈佬，大家好，我係 Max King。

上篇寫 DESIGN.md 嘅時候，我其實有啲樂觀。

因為之前最令我煩惱嘅，係 AI 寫 UI 時風格亂咁飄。同一個項目入面，首頁仲係深色金融風，轉到設定頁突然變成白色極簡風；呢個頁面嘅按鈕圓角係一套，下一個頁面又換咗；卡片陰影、表格密度、字體大小，每次都好似重新開咗一個項目咁。

所以我當時嘅想法好簡單：首先將項目嘅設計規則寫低。顏色點用，按鈕點樣，卡片要咩風格，表格要緊湊定係舒展，邊啲效果唔好出現，全部放喺 DESIGN.md 度。至少先等 AI 唔好每次都自由發揮。

呢個方向冇錯。

但繼續做落去嘅時候，我發現事情冇咁簡單。風格係穩定咗啲，按鈕、卡片、顏色呢啲冇咁亂。但係頁面一接近真實數據，新問題即刻出嚟。

我而家測試 AI 頁面，會故意將 mockData 裏面嘅欄位拉長少少，表格塞多幾列，列表數據改成 0 條，再模擬一個接口報錯。然後你會好容易見到問題：客戶名一長，卡片就被撐開；表格多兩列，頁面開始橫向滾動；冇數據嗰陣，中間空咗喺度；接口報錯嗰陣，個頁面又唔知俾用戶睇咩好。

更尷尬嘅係，桌面端仲勉強睇到，但換成手機尺寸，好多時就直接冧咗。

呢兩個問題，唔可以溝埋一齊。

DESIGN.md 管嘅係項目整體風格。例如一個後台系統，究竟係 dark fintech，定係 clean SaaS；主色點用，字體層級點分，卡片要唔要陰影，表格係高密度定係留白多啲，按鈕係剋制啲定係強調行動，呢啲都適合放喺 DESIGN.md 度。

佢都適合寫一啲禁忌。例如唔好 cyberpunk，唔好過度霓虹，唔好將後台頁面做成展示大屏，唔好為咗視覺效果犧牲可讀性。

呢啲寫清楚之後，AI 後面係會乖啲。

但係具體到某個頁面，問題即刻變得仔細。一個訂單列表頁，唔單止要「睇落似訂單列表」。佢仲要知道表格有咩欄位，欄位有冇可能為空，訂單狀態有幾種，狀態文案會唔會好長，數據加載中顯示咩，接口失敗後可唔可以重試，刪除按鈕需唔需要二次確認，移動端仲適唔適合繼續用表格。

呢啲唔屬於項目整體風格。

問題就係呢度：AI 估出嚟嘅頁面，第一眼可能似，但一接數據就未必用得。

我而家更願意將好多 AI 生成嘅頁面叫做「演示態頁面」。

佢唔係完全冇用。佢可以幫你睇到大約佈局，睇到風格方向，甚至快速做一個 Demo。但佢默認展示嘅係最順眼嘅一種狀態：有數據，欄位唔長，表格啱啱好幾行，按鈕都撳得，圖表裏面都有內容，屏幕寬度又啱啱係桌面端。

呢個狀態好容易好睇。

真實項目麻煩嘅地方，正正唔係呢個狀態。接口慢嘅時候，頁面唔可以白屏；冇數據嘅時候，唔可以空咗一塊；接口報錯嘅時候，要話俾用戶知發生咩事，最好仲可以重試；欄位過長嘅時候，要決定係截斷、換行、tooltip，定係等列寬自動調整；用戶權限不足嘅時候，按鈕應該禁用，而唔係繼續擺喺度等㩒。

呢啲都唔係視覺風格問題。

呢個亦都係點解好多頁面截圖睇落還可以，但真正接接口、接權限、接移動端嗰陣就開始出事。唔係 AI 唔識寫 CSS，而係佢一開始收到嘅任務裏面，就冇定義呢啲邊界。

以前我都會先睇頁面似唔似參考圖。而家都會睇，但唔會淨係睇呢樣。

我會故意將一啲數據改差少少。例如將 customerName 換成 30 個字以上，將表格裏面嘅 status 增加幾個更長嘅枚舉文案，將某個金額欄位改成空值，將列表數據改成 0 條，再將接口狀態改成 loading 和 error。

呢啲測試唔複雜，但好快就睇到頁面係咪只係做咗一個好靚嘅靜態殼。

欄位長度係最容易暴露問題嘅地方。設計圖裏面寫「今日收入」「新增用戶」「訂單狀態」，呢啲欄位都好短，點擺都舒服。真實業務裏面，欄位可能係「2026 年第二季度企業客戶續費轉化率」，亦可能係「超過 SLA 嘅待處理異常訂單」。如果冇提前定義截斷、換行、列寬同 tooltip，卡片、表格、按鈕好容易一齊變形。

數據數量都係一樣。AI 默認畫出嚟嘅表格，往往得幾行，睇落好乾淨。但真實頁面可能冇數據，亦可能有幾百行。0 行嗰陣要有空狀態，300 行嗰陣要分頁或者滾動，列好多嘅時候仲要考慮固定操作列。DESIGN.md 可以規定表格嘅視覺風格，但唔會話俾 AI 知冇數據嗰陣點處理，亦唔會話俾 AI 知超過幾多行應該分頁。

狀態更加容易漏。好多 AI 頁面只寫 normal 狀態，即係「有數據嗰陣嘅樣」。但一個真正要交付嘅頁面，至少要考慮 loading、empty、error、disabled 同 normal。訂單列表加載中唔可以白屏，冇訂單唔可以留一塊空白，接口報錯要有提示同重試，提交按鈕處理中唔可以俾用戶連續撳。

按鈕邏輯都唔可以淨係睇有冇按鈕。「查看詳情」係跳轉定係彈窗？「刪除」要唔要二次確認？「導出」喺冇數據嗰陣可唔可以撳？篩選器係自動刷新，定係㩒查詢？呢啲如果唔寫清楚，AI 一係空咗，一係自己作。最後頁面睇落似產品，但撳起嚟唔似產品。

移動端就更明顯。桌面端四個指標卡橫排冇問題，但手機上係兩列定係單列？表格繼續橫向滾動，定係轉成卡片？篩選器要唔要摺疊？圖表高度點處理？呢啲如果冇提前講明，AI 好容易默認桌面端睇到就算完成。

我以前都會慳返 UI Spec 呢一步。

諗法好正常：首先等 AI 將頁面寫出嚟，行得鬱先算。真係爭啲嘢，再叫佢補。

但之後會發現，前面慳返嘅嘢，基本上都會喺返工裏面還返出嚟。你會不斷咁補：呢度冇 empty，嗰度冇 loading，呢個欄位唔應該咁樣展示，嗰個按鈕唔可以直接撳，移動端佈局冧咗，接口錯誤冇處理。

更麻煩嘅係，你叫 AI 改呢啲問題嗰陣，佢可能順手將原本啱嘅地方改錯。尤其係 UI 相關修改，好多時唔係淨係改一塊，而係將佈局、間距、組件結構一齊鬱。

所以我而家會喺寫 code 前加多一步：先叫 AI 將頁面拆成 UI Spec。

UI Spec 唔係 code，亦唔係設計圖。佢更加似係頁面說明書。

呢兩層要分開。

DESIGN.md 管顏色、字體、間距、圓角、組件風格。UI Spec 管頁面目標、模組、欄位、狀態、交互、響應式同驗收標準。

第一次唔使寫得好重。

你可以先將下面呢段發俾 AI，叫佢幫你拆一版 UI Spec。重點唔係一次過寫完美，而係先將容易漏嘅嘢暴露出來。

拆完之後，唔好即刻叫 AI 寫頁面。

先檢查佢有冇漏狀態、漏欄位、漏移動端。好多時你會發現，唔係 AI 冇諗清楚，而係你自己都冇將頁面諗清楚。UI Spec 呢一步嘅價值，唔單止係約束 AI，亦係逼自己將頁面補完整。

例如我要做一個 SaaS 後台首頁。

如果淨係話「幫我做一個 SaaS Dashboard」，AI 多數都會俾一個頁面。但佢點樣拆，我係唔放心嘅。佢可能放一大堆隨機圖表，可能加啲冇意義嘅卡片，亦可能自己作欄位。更常見嘅係，佢只做 normal 狀態，空數據同錯誤狀態完全冇。

如果先寫一份簡單 UI Spec，件事會穩定好多。

呢個仲未係 code。

但係頁面已經清楚好多。AI 後面再去實現，就唔係憑感覺做一個「似 Dashboard 嘅頁面」，而係跟住一個明確嘅頁面說明去寫。

所以返返去標題呢個問題：

DESIGN.md 都寫咗，點解 AI 頁面仲係一接數據就冧？

唔係 DESIGN.md 冇用。佢只係管唔到呢一層。

佢管嘅係風格。

真實頁面仲需要定義數據欄位、頁面模組、交互邏輯、loading、empty、error、響應式同驗收標準。呢啲嘢，應該交畀 UI Spec。

下一次做 AI 頁面時，我唔會一開波就叫佢寫 code。我會先叫佢做一件事：

哈嘍，大家好，我是 Max King。

上一篇寫 DESIGN.md 的時候，我其實有點樂觀。

因為之前讓我最煩的，是 AI 寫 UI 時風格亂飄。同一個項目裏，首頁還是深色金融風，換到設置頁突然變成白色極簡風；這個頁面按鈕圓角是一套，下一個頁面又換了；卡片陰影、表格密度、字體大小，每次都像重新開了一個項目。

所以我當時的想法很簡單：先把項目的設計規則寫下來。顏色怎麼用，按鈕怎麼長，卡片要什麼風格，表格要緊湊還是舒展，哪些效果不要出現，全部放到 DESIGN.md 裏。至少先讓 AI 別每次都自由發揮。

這個方向沒有錯。

但繼續往下做頁面的時候，我發現事情沒這麼簡單。風格確實穩了一點，按鈕、卡片、顏色這些東西沒那麼亂了。可是頁面一接近真實數據，新的問題馬上冒出來了。

我現在測試 AI 頁面，會故意把 mockData 裏的字段拉長一點，把表格多塞幾列，把列表數據改成 0 條，再模擬一個接口報錯。然後你會很容易看到問題：客戶名一長，卡片就被撐開；表格多兩列，頁面開始橫向滾動；沒有數據時，中間空在那裏；接口報錯時，頁面也不知道該給用戶看什麼。

更尷尬的是，桌面端還能勉強看，換到手機尺寸，經常就直接塌了。

這兩個問題，不能混在一起。

DESIGN.md 管的是項目整體風格。比如一個後台系統，到底是 dark fintech，還是 clean SaaS；主色怎麼用，字體層級怎麼分，卡片要不要陰影，表格是高密度還是留白多一點，按鈕是剋制一點還是強調行動，這些都適合放在 DESIGN.md 裏。

它也適合寫一些禁忌。比如不要賽博朋克，不要過度霓虹，不要把後台頁面做成展示大屏，不要為了視覺效果犧牲可讀性。

這些寫清楚以後，AI 後面確實會老實一點。

但具體到某一個頁面，問題馬上就變細了。一個訂單列表頁，不只是要“看起來像訂單列表”。它還要知道表格有哪些字段，字段是否可能為空，訂單狀態有幾種，狀態文案是否會很長，數據加載中顯示什麼，接口失敗後是否允許重試，刪除按鈕是否需要二次確認，移動端還適不適合繼續用表格。

這些不屬於項目整體風格。

問題就在這裏：AI 猜出來的頁面，第一眼可能像，但一接數據就不一定能用。

我現在更願意把很多 AI 生成的頁面叫做“演示態頁面”。

它不是完全沒用。它能幫你看到大概佈局，看到風格方向，甚至能快速做一個 Demo。但它默認展示的是最順眼的一種狀態：有數據，字段不長，表格剛好幾行，按鈕都能點，圖表裏也有內容，屏幕寬度也剛好是桌面端。

這個狀態很容易好看。

真實項目麻煩的地方，恰好不在這個狀態。接口慢的時候，頁面不能白屏；沒有數據的時候，不能空着一塊；接口報錯的時候，要告訴用戶發生了什麼，最好還能重試；字段過長的時候，要決定是截斷、換行、tooltip，還是讓列寬自動調整；用戶權限不足的時候，按鈕應該禁用，而不是繼續擺在那裏讓人點。

這些都不是視覺風格問題。

這也是為什麼很多頁面截圖看起來還可以，但真正接接口、接權限、接移動端時就開始出事。不是 AI 不會寫 CSS，而是它一開始拿到的任務裏，就沒有定義這些邊界。

以前我也會先看頁面像不像參考圖。現在還是會看，但不會只看這個。

我會故意把一些數據改壞一點。比如把 customerName 換成 30 個字以上，把表格裏的 status 增加幾個更長的枚舉文案，把某個金額字段改成空值，把列表數據改成 0 條，再把接口狀態改成 loading 和 error。

這些測試不復雜，但很快就能看出頁面是不是隻做了一個好看的靜態殼。

字段長度是最容易暴露問題的地方。設計圖裏寫“今日收入”“新增用戶”“訂單狀態”，這些字段都很短，怎麼放都舒服。真實業務裏，字段可能是“2026 年第二季度企業客戶續費轉化率”，也可能是“超過 SLA 的待處理異常訂單”。如果沒有提前定義截斷、換行、列寬和 tooltip，卡片、表格、按鈕很容易一起變形。

數據數量也是一樣。AI 默認畫出來的表格，往往只有幾行，看起來很乾淨。但真實頁面可能沒有數據，也可能有幾百行。0 行時要有空狀態，300 行時要分頁或者滾動，列很多時還要考慮固定操作列。DESIGN.md 可以規定表格的視覺風格，但不會告訴 AI 沒有數據時怎麼處理，也不會告訴 AI 超過多少行應該分頁。

狀態更容易漏。很多 AI 頁面只寫 normal 狀態，也就是“有數據時的樣子”。但一個真正要交付的頁面，至少要考慮 loading、empty、error、disabled 和 normal。訂單列表加載中不能白屏，沒有訂單不能留一塊空白，接口報錯要有提示和重試，提交按鈕處理中不能讓用戶連續點。

按鈕邏輯也不能只看有沒有按鈕。“查看詳情”是跳轉還是彈窗？“刪除”要不要二次確認？“導出”在沒有數據時能不能點？篩選器是自動刷新，還是點查詢？這些如果不寫清楚，AI 要麼空着，要麼自己編。最後頁面看起來像產品，點起來不像產品。

移動端就更明顯了。桌面端四個指標卡橫排沒有問題，但手機上是兩列還是單列？表格繼續橫向滾動，還是轉成卡片？篩選器要不要摺疊？圖表高度怎麼處理？這些如果沒有提前說明，AI 很容易默認桌面端能看就算完成。

我以前也會省掉 UI Spec 這一步。

想法很正常：先讓 AI 把頁面寫出來，跑起來再說。真缺什麼，再讓它補。

但後面會發現，前面省掉的東西，基本都會在返工裏還回來。你會不斷補：這裏沒有 empty，那裏沒有 loading，這個字段不該這樣展示，那個按鈕不能直接點，移動端佈局崩了，接口錯誤沒處理。

更麻煩的是，你讓 AI 修這些問題時，它可能順手把原來對的地方改壞。尤其是 UI 相關修改，經常不是隻改一塊，而是把佈局、間距、組件結構一起帶着動。

所以我現在會在寫代碼前加一步：先讓 AI 把頁面拆成 UI Spec。

UI Spec 不是代碼，也不是設計圖。它更像頁面說明書。

這兩層要分開。

DESIGN.md 管顏色、字體、間距、圓角、組件風格。UI Spec 管頁面目標、模塊、字段、狀態、交互、響應式和驗收標準。

第一次不用寫得很重。

你可以先把下面這段發給 AI，讓它幫你拆一版 UI Spec。重點不是一次寫完美，而是先把容易漏的東西暴露出來。

拆完以後，不要馬上讓 AI 寫頁面。

先檢查它有沒有漏狀態、漏字段、漏移動端。很多時候你會發現，不是 AI 沒想清楚，是你自己也沒把頁面想清楚。UI Spec 這一步的價值，不只是約束 AI，也是在逼自己把頁面補完整。

比如我要做一個 SaaS 後台首頁。

如果只說“幫我做一個 SaaS Dashboard”，AI 多半也能給一個頁面。但它怎麼拆，我是不放心的。它可能放一堆隨機圖表，可能加一些沒意義的卡片，也可能自己編字段。更常見的是，它只做 normal 狀態，空數據和錯誤狀態完全沒有。

如果先寫一份簡單 UI Spec，事情會穩很多。

這還不是代碼。

但頁面已經清楚很多了。AI 後面再去實現，就不是憑感覺做一個“像 Dashboard 的頁面”，而是在按一個明確的頁面說明往下寫。

所以回到標題這個問題：

DESIGN.md 都寫了，AI 頁面為什麼還是一接數據就崩？

不是 DESIGN.md 沒用。它只是管不到這一層。

它管的是風格。

真實頁面還需要定義數據字段、頁面模塊、交互邏輯、loading、empty、error、響應式和驗收標準。這些東西，應該交給 UI Spec。

下一次做 AI 頁面時，我不會一上來就讓它寫代碼。我會先讓它做一件事：