SilentPolish:Next.js 完整應用程式打磨
修復間距與設計錯誤,使用 next/image,移除所有假資料,並將所有內容集中到 site.ts。
觸發提示: "對整個應用程式執行此技能。依序執行每個步驟。不要跳過任何檔案。"
0. 背景
- Next.js 應用程式(假設使用 App Router;可為 Pages Router 調整)。
- UI 很可能由 AI 工具(例如透過 MCP 的 Google Stitch)生成。預期會有不一致的內距、固定的像素尺寸、純
img標籤,以及虛構的數字、統計資料、價格、日期和表格列。 - 擁有者需要頻繁(每天)手動更新真實資料。所有可變資料必須集中在一個檔案中:
site.ts。
1. 嚴格規則(絕不違反)
- 元件中不得有假資料。 不得有虛構的數字、統計資料、百分比、價格、評分、計數、日期、姓名、電子郵件、電話、見證或表格列。
- 所有資料來自
site.ts。 元件僅從中讀取。元件不得包含文字資料。 - 絕不虛構替代數字。 使用
null(渲染為—)或空陣列。佔位符必須明顯為空,而非看起來像真實資料。 - 所有內容圖片使用
next/image。 不得有<img>標籤。 - 統一的間距系統。 不得有隨機的一次性內距。
- 不改變設計方向(顏色、字體、品牌風格)。僅修正間距與錯誤。
- 不破壞現有功能。 最終需執行建置。
- 處理整個應用程式: 每個頁面、佈局、元件、以及 loading/error/not-found 檔案。
2. 工作流程
依序執行步驟。在進行任何更改前,先報告稽核結果。
步驟 1:稽核
執行 scripts/audit.sh <專案根目錄>(或 references/audit-patterns.md 中的手動 grep)。輸出簡潔的分組列表:
- A. 虛假 / 硬編碼資料:JSX 文字中的數字、元件內類似資料的陣列、假聯絡資訊、假日期。
- B. 圖片:
<img>標籤、用作內容的 CSS 背景圖片。 - C. 佈局 / 內距問題:固定的像素尺寸、
h-screen/100vh、混合的區塊內距、雙重內距、行動裝置邊緣貼齊、水平捲動、用於佈局的絕對定位、負邊距 hack、缺少max-width、文字溢出、不一致的卡片尺寸/圓角。
步驟 2:建立 site.ts
將 assets/templates/site.ts 複製到 src/config/site.ts(或 config/ / lib/ 以符合專案結構;使用專案現有的匯入別名,例如 @/config/site)。
- 完整的型別定義。所有可變的值都放在這裡。
- 未知的值為
null或[],絕不虛構。 - 每個區塊上方都有註解,告訴擁有者該編輯什麼。
- 保持扁平且簡單。僅保留與實際應用程式相符的區塊;為稽核查到的內容(價格、行程、費率、團隊...)新增區塊。
- 將擁有者快速更新指南(下方第 5 節)作為註解放在檔案頂部。
步驟 3:取代每個元件中的假資料
對於稽核 A 中的每個發現:
- 從元件中移除硬編碼的值或陣列。
- 在
site.ts中新增對應的條目,使用空佔位符(null、""、[])。 - 在元件中匯入它並從中渲染。
- 優雅地處理空狀態(不崩潰,不破壞佈局)。
參考範例:assets/templates/StatsExample.tsx、assets/templates/TableExample.tsx。
規則:
- 數字、日期、價格、表格資料和聯絡資訊必須放在
site.ts中。靜態品牌詞語(標題、按鈕標籤、導航標籤)可以留在元件中,或移到site.ts中(如果可能變更)。 - 使用穩定的
id作為 React 鍵,而非陣列索引。 - 僅用於佈局的數字(如
grid-cols-3)可以保留。 - 禁止使用
Math.random()和虛假的動畫計數器。計數器只能動畫顯示從site.ts讀取的值,若為null則顯示—。 - 當聯絡/社交項目為空時隱藏:
{contact.email && <a ...>}。
步驟 4:使用 next/image 處理圖片
取代每個 <img> 和內容 background-image。完整規則請見 references/image-rules.md。摘要:
- 務必有有意義的
alt(僅純裝飾性圖片可留空)。 width+height,或搭配relative父層使用fill。兩者不可同時使用。- 使用
fill時:加上sizes和object-cover/object-contain。 priority僅用於首屏 / LCP 圖片。- 本地檔案放在
/public/images/;遠端主機需加入next.config的remotePatterns。 - 路徑、替代文字和尺寸存在
site.ts(images)。 - 如果沒有真實檔案,請勿使用外部圖庫網址。請渲染一個中性的空白區塊(
bg-muted aspect-[16/9]),並將site.ts中的條目留給擁有者處理。 - 將
rounded和overflow-hidden放在包裝容器上。
步驟 5:內距與間距系統
- 將
assets/templates/Container.tsx和Section.tsx複製到components/ui/。 - 僅使用
references/spacing-system.md中的尺度。 - 將每個頁面區塊包裝在
<Section>中;移除重複的臨時px-*/py-*。 - 移除雙重內距、基於像素的尺寸、以及區塊上的
h-screen/100vh。 - 標準化頁首、頁尾、卡片(統一半徑)、按鈕(44px 最小觸控目標)、表單、長文字(
max-w-prose),並將表格包裝在overflow-x-auto中。 - 僅在修復真正原因後,才作為最後手段將
overflow-x-hidden加到body。
如果專案未使用 Tailwind,請使用相同尺度建立 CSS 變數。
步驟 6:設計錯誤清單
按照 references/design-checklist.md 進行檢查並修復所有項目。
步驟 7:驗證
執行 scripts/verify.sh <專案根目錄>(型別檢查、lint、建置,然後重新執行稽核)。修復所有失敗項目。在建置通過之前,不得說「完成」。
步驟 8:最終報告(必要輸出)
- 更改的檔案
- 移入
site.ts的內容(區塊及各區塊控制的內容) - 移除的假資料(內容與位置)
- 轉換的圖片(數量,以及需要擁有者提供真實檔案的部分)
- 間距修正(全域變更、新的
Container/Section使用情況) - 擁有者必須填寫的所有項目(
null/[]條目的列表) - 建置結果(成功/失敗)
5. 擁有者快速更新指南(也會放在 site.ts 頂部)
- 更新數字:
site.ts→stats→ 修改value。 - 更新表格(每日):
tables.main.rows→ 編輯/新增列 → 將updatedAt設為今天的日期("YYYY-MM-DD")。 - 變更聯絡資訊:
contact。 - 替換圖片: 將檔案放入
/public/images/→ 更新images中的src、alt、width、height。 - 隱藏某項內容: 將值設為
null或將列表設為[]。 - 儲存。下次重新載入/部署時網站即更新。無需編輯元件。
6. 禁止事項
- 請勿為了「填補空間」而虛構數字、名稱、價格、評論或日期。
- 請勿將資料陣列留在元件內。
- 請勿使用
<img>或 CSS 背景圖片作為內容。 - 請勿新增隨機的內距值。
- 請勿重新設計顏色、字體或品牌。
- 除非確實需要,否則請勿新增依賴項。
- 請勿跳過檔案或僅止於「主頁面」。
- 在建置通過之前,不得說「完成」。