一個下午用 Claude Code 翻新整個 Blog

那個「受不了了」的瞬間

這個 blog 用的是 Astro 的社群模板改的。看了兩三遍就煩了——配色是 Tailwind 預設的灰藍色系，排版是標準的卡片式 grid，跟 GitHub 上幾千個 Astro blog 長得八成像。真的是千篇一律。

問題不是它醜，是它沒有個性。

其實也沒有醞釀多久。煩了之後想到手邊有個看了一陣子但還沒實際用過的前端 skill——Claude Code 的 frontend-design skill，專門處理 UI 設計和實作。與其繼續忍，不如拿它試試看。

「文房書齋」這個方向怎麼來的

說出來有點好笑——「文房書齋」這個名字不是我想的，是 Claude Code 在互動過程中自己冒出來的。

我只是說想要「溫暖的書房」的感覺，那種走進去會想坐下來慢慢讀東西的空間，不要科技感，不要極簡到冷冰冰。Claude Code 接過這個方向，在生成設計規格的時候自己取了「文房書齋」這個名字，warm-brown 色系、serif 標題字、editorial 排版，一整套意象就這樣成型了。

跟它溝通設計方向比我預期的容易。我不是丟一句「幫我設計一個好看的 blog」，而是先描述氛圍和感覺，它幫我收斂成具體的設計語言。比方我說「像老書房的紙張」，它就提出 #faf6f1 這類偏暖的米白色當底色。來回幾輪，設計方向就定了。AI 取的名字比我自己想的還貼切，這點倒是沒預料到。

關鍵流程：先寫規格書，不是直接改 code

這是整個翻新最重要的一步，也是我覺得用 Claude Code 做大規模改動最值得分享的心得。

不要直接叫 AI 開始改檔案。

我用 Claude Code 的 plan 模式，先生成了一份完整的設計規格書。這份文件大概涵蓋：

Design tokens：所有顏色值、字體組合、間距，light 和 dark 兩組
元件規格：Header、Footer、PostCard、TOC 每個元件長什麼樣
頁面規格：首頁、文章列表、文章頁、Projects、About 各自的排版
執行順序：哪個檔案先改、哪個後改，按依賴關係排

有了規格書，接下來才進入 plan 模式生成實作計畫。計畫把工作拆成 20 多個步驟，每一步對應一個 commit，按「基礎設施 → 殼 → 內頁」的順序推進。

為什麼這樣做有效？因為 AI 的 context window 是有限的。如果你一口氣叫它「把整個網站改成暖色調」，它要同時記住設計意圖、所有檔案的現狀、和改動之間的依賴——很容易丟東西。拆成小步驟，每一步的目標明確、範圍小，出錯率低很多。

技術面：CSS Custom Properties 的 Dark Mode 策略

這裡穿插一個技術細節，我覺得這個做法很漂亮。

傳統 Tailwind dark mode 的寫法是到處加 dark: prefix：

<div class="bg-white dark:bg-gray-900 text-gray-900 dark:text-gray-100">

每個元素都要寫兩次顏色，很煩，也容易漏。

這次的做法是用 CSS custom properties 搭配 .dark class，在 global.css 裡一次定義所有 token：

:root {
  --c-page: #faf6f1;      /* 米白 */
  --c-heading: #3d3028;    /* 深棕 */
  --c-accent: #c4a882;     /* 金棕 */
}

.dark {
  --c-page: #1c1917;       /* 深褐 */
  --c-heading: #e8dfd3;    /* 淺米 */
  --c-accent: #d4a86a;     /* 亮金 */
}

然後透過 Tailwind 4 的 @theme 把這些 token 接進去，元件裡只要寫一次 bg-page text-heading，light / dark 自動切換。整個專案裡幾乎看不到 dark: prefix。

撞牆紀錄

90 分鐘不是全程順風。幾個卡住的地方：

Theme 切換閃爍。 點 dark mode toggle 的時候，整個頁面會閃一下白色。原因是 .dark class 切換的瞬間，有些元素的 transition 還沒生效，導致背景色瞬間跳回預設值再過渡。解法是切換的瞬間暫時對所有元素強制啟用 transition，切完再移除。不算優雅，但有效。

CJK 路徑在靜態建置爆掉。 文章的 category 是中文（「技術」「日誌」），Astro 直接拿它當 URL slug，產生了 /blog/category/技術/ 這種路徑。本地 dev server 沒問題，部署到 Cloudflare Pages 之後就 404 了。改成用英文 slug 對照表解決。

這些問題都是我自己手動操作的時候發現的——點一點、切換個頁面就踩到了。回頭想，下次或許可以搭配瀏覽器操作的 MCP tool，讓 AI 自己開瀏覽器跑一輪，自動化抓這類視覺和路由問題，不用靠人肉 QA。

Pagination 的 edge case。 分頁加上 category filter 之後，routing 邏輯變複雜了。比如第一頁是 /blog，第二頁是 /blog/2，但如果是 category filter 就是 /blog/category/tech、/blog/category/tech/2。靜態建置需要在 getStaticPaths 裡窮舉所有組合，漏掉任何一個就是 404。

成果和感受

從 16:00 開始寫設計規格，到 17:26 CI/CD 上線——大約 90 分鐘。

最終產出：20 多個 commits，涵蓋全站設計系統、Header、Footer、首頁、文章列表、文章頁、TOC、Projects、About、Tag/Category 頁面，加上 theme transition 修復和 CI/CD 部署。

成品我還蠻喜歡的。

整個過程中印象最深的一件事：AI 教我用了一個可以即時跟瀏覽器互動的工具，能監控我的瀏覽器操作行為，直接看到畫面上的變化。這在調整細部 CSS 的時候特別有用——不用再來回切 terminal 和瀏覽器，改了什麼馬上就能看到效果。

但也正是在調 CSS 細節的時候，碰到了一個很熟悉的感覺。

改了一版，不太對，再改。改到第三版，回頭一看——這不就是第一版嗎？做過前端的人應該都懂：客戶說要 B，你改了，看了幾輪又改回 A。只不過這次的「客戶」是我自己，而幫我改的是 AI。審美這種東西，果然不管誰來執行，感覺性的問題還是一樣難搞。

幾個誠實的觀察：

AI 能做的： 大量重複性的樣式修改、根據規格書精確執行、記住設計 token 在每個元件保持一致、處理 dark mode 的機械性工作。這些如果手動做，可能要花一整天。

AI 不能做的： 審美判斷的最後一哩路還是得自己來。它能給你「合理」的配色，但「這個棕色偏暖還是偏冷比較好」——你得自己盯著螢幕看，而且你可能盯了半天又改回去。

最大的心得： 「先寫規格、再拆計畫、最後執行」這個三步流程，比直接跟 AI 對話改 code 有效太多了。規格書是你和 AI 之間的合約——寫得越清楚，它越不會自作主張。Plan 模式把大任務拆成原子操作，每一步都可以驗證，出問題也容易定位。

一個下午翻新整個 blog，以前不敢想。現在做完了，覺得門檻確實降了不少。但降的不是「設計能力」的門檻——你還是得知道自己要什麼。降的是「從想法到實作」的摩擦力。而那個「改了 B 又改回 A」的輪迴，不管有沒有 AI，大概永遠不會消失。