Communitygithub.com

SilentPolish:完整 Next.js 應用程式打磨工具

打磨 Next.js 應用程式(特別是 Google Stitch 或其他 AI UI 工具生成的專案)。修復內距/間距與響應式設計錯誤,將所有 `<img>` 轉換為 `next/image`,移除所有虛假或憑空捏造的資料(統計數字、價格、表格、見證、電子郵件、日期),並將所有可變動的值集中到一個型別安全的 `site.ts` 檔案,供擁有者手動編輯。當使用者提到清理、打磨、修正或稽核 Next.js / React / Tailwind 應用程式,移除佔位符或假資料,修正內距或間距,改用 next/image,或讓內容易於從一個設定檔更新時,請使用此技能,即使使用者從未提及此技能名稱。

SilentPolish:完整 Next.js 應用程式打磨工具 是什麼?

SilentPolish 是一個專為 Next.js 應用程式(尤其是 AI 生成工具產出)設計的全自動打磨技能。它能系統性地解決三個痛點:清除所有虛假或硬編碼的資料(如統計數字、價格、日期、表格列),並將其集中管理在一個型別安全的 `site.ts` 設定檔中;將所有原生 `<img>` 標籤轉換為 Next.js 最佳化的 `next/image` 元件;並透過統一的 Container/Section 元件與標準化間距系統,修復不一致的內距與響應式錯誤。 此技能支援 Next.js App Router 與 Pages Router,並採用八大步驟流程:稽核、建立 `site.ts`、取代虛假資料、轉換圖片、統整間距系統、修復設計缺陷、驗證建置,最後產出一份詳細的最終報告。它嚴格遵循硬性規則,如絕不捏造替代數字(使用 `null` 或空陣列)、保持設計方向不變、不破壞現有功能。 適用場景包括使用者要求清理/打磨/修正應用程式、移除佔位符或假資料、修正內距/間距、改用 `next/image`,或希望將所有可變內容集中到一個設定檔以便日常更新。執行後會產出完整的變更記錄與待辦事項,確保建置通過才算完成。

相容平台~Claude Code~Codex CLI~Cursor
npx skills add https://github.com/SilentCoder-HI/SilentPolish/tree/HEAD

在你喜歡的 AI 中提問

開啟一個已預先載入此 Agent Skill 的新對話。

說明文件

SilentPolish:Next.js 完整應用程式打磨

修復間距與設計錯誤,使用 next/image,移除所有假資料,並將所有內容集中到 site.ts。

觸發提示: "對整個應用程式執行此技能。依序執行每個步驟。不要跳過任何檔案。"

0. 背景

  • Next.js 應用程式(假設使用 App Router;可為 Pages Router 調整)。
  • UI 很可能由 AI 工具(例如透過 MCP 的 Google Stitch)生成。預期會有不一致的內距、固定的像素尺寸、純 img 標籤,以及虛構的數字、統計資料、價格、日期和表格列。
  • 擁有者需要頻繁(每天)手動更新真實資料。所有可變資料必須集中在一個檔案中:site.ts。

1. 嚴格規則(絕不違反)

  1. 元件中不得有假資料。 不得有虛構的數字、統計資料、百分比、價格、評分、計數、日期、姓名、電子郵件、電話、見證或表格列。
  2. 所有資料來自 site.ts。 元件僅從中讀取。元件不得包含文字資料。
  3. 絕不虛構替代數字。 使用 null(渲染為 —)或空陣列。佔位符必須明顯為空,而非看起來像真實資料。
  4. 所有內容圖片使用 next/image。 不得有 <img> 標籤。
  5. 統一的間距系統。 不得有隨機的一次性內距。
  6. 不改變設計方向(顏色、字體、品牌風格)。僅修正間距與錯誤。
  7. 不破壞現有功能。 最終需執行建置。
  8. 處理整個應用程式: 每個頁面、佈局、元件、以及 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 中的每個發現:

  1. 從元件中移除硬編碼的值或陣列。
  2. 在 site.ts 中新增對應的條目,使用空佔位符(null、""、[])。
  3. 在元件中匯入它並從中渲染。
  4. 優雅地處理空狀態(不崩潰,不破壞佈局)。

參考範例: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:內距與間距系統

  1. 將 assets/templates/Container.tsx 和 Section.tsx 複製到 components/ui/。
  2. 僅使用 references/spacing-system.md 中的尺度。
  3. 將每個頁面區塊包裝在 <Section> 中;移除重複的臨時 px-* / py-*。
  4. 移除雙重內距、基於像素的尺寸、以及區塊上的 h-screen/100vh。
  5. 標準化頁首、頁尾、卡片(統一半徑)、按鈕(44px 最小觸控目標)、表單、長文字(max-w-prose),並將表格包裝在 overflow-x-auto 中。
  6. 僅在修復真正原因後,才作為最後手段將 overflow-x-hidden 加到 body。

如果專案未使用 Tailwind,請使用相同尺度建立 CSS 變數。

步驟 6:設計錯誤清單

按照 references/design-checklist.md 進行檢查並修復所有項目。

步驟 7:驗證

執行 scripts/verify.sh <專案根目錄>(型別檢查、lint、建置,然後重新執行稽核)。修復所有失敗項目。在建置通過之前,不得說「完成」。

步驟 8:最終報告(必要輸出)

  1. 更改的檔案
  2. 移入 site.ts 的內容(區塊及各區塊控制的內容)
  3. 移除的假資料(內容與位置)
  4. 轉換的圖片(數量,以及需要擁有者提供真實檔案的部分)
  5. 間距修正(全域變更、新的 Container/Section 使用情況)
  6. 擁有者必須填寫的所有項目(null / [] 條目的列表)
  7. 建置結果(成功/失敗)

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 背景圖片作為內容。
  • 請勿新增隨機的內距值。
  • 請勿重新設計顏色、字體或品牌。
  • 除非確實需要,否則請勿新增依賴項。
  • 請勿跳過檔案或僅止於「主頁面」。
  • 在建置通過之前,不得說「完成」。

相關技能