今天要解的問題

我的部落格 kiwi-walk(Hugo 加 PaperMod)其實一直有一整套 body.dark 的深色樣式,也有在第一次繪製前設好主題的 theme-init.js。但 hugo.yml 裡的 disableThemeToggle 是關的,所以讀者根本切不到深色。

但每次改 UI,我還是要檢查一次深色,等於在維護一套沒有人看得到的東西。之前做顏色對比時就發現深色下文章頁有字看不清,當時判斷要修就等於讓整套深色模式能用,所以先不動。

而深色的顏色寫法也很亂。光是分類色就有三種換色方式:

  • 分類頁的 hero:靠一支 category-hero.js 在切換主題時換色。
  • 列表上的分類標籤:用一對 inline CSS 變數。
  • 文章標題下的 chip:帶著 data-*-dark 屬性,但沒有任何東西讀它。

另外還有好幾處直接寫死的深色色碼。

這次是從一次架構檢視列出的候選走到這裡的,第一個要決定的是:留著並真的打開,還是整個拿掉。我選了留著並打開。

想法與取捨

這次的改動依循下面幾個主軸:

  • 第一次進站跟隨系統設定,按過切換鈕之後記住讀者的選擇。
  • 有分類色、系列色的元素,只留一種換色機制。
  • 拆成三步,開關放在最後,前兩步做完時讀者看不到任何變化。
  • 沒有 JS 時一律是完整的淺色。
  • 深色下的對比用量的,確認每一頁都看得到。

深色要是什麼顏色

我希望深色可以相容,所以先請 AI 給我幾組範例,看了四組之後選了 B,咖啡棕。

開關還沒打開,要怎麼看深色

基於上面的主軸,開關要放到最後一步,所以前兩步做完時,讀者和我都切不到深色。這時候看深色的方法,就是在瀏覽器裡手動幫 <body> 加上 dark 這個 class,前兩步的檢查也都是這樣做的。

實作

只留一種換色機制,不靠 JS

hero 和 chip 都改成跟列表標籤一樣:淺色和深色的值寫成一對 inline CSS 變數,再由 custom.css 的一條 .dark 規則挑一個。

<!-- layouts/partials/category-hero.html -->
style="--accent-light: {{ $info.accent }}; --accent-bg-light: {{ $info.bg }}; --accent-dark: {{ $info.accentDark }}; --accent-bg-dark: {{ $info.bgDark }};">
/* assets/css/extended/custom.css */
.category-chip,
.category-hero {
    --accent: var(--accent-light);
    --accent-bg: var(--accent-bg-light);
}

.dark .category-chip,
.dark .category-hero {
    --accent: var(--accent-dark, var(--accent-light));
    --accent-bg: var(--accent-bg-dark, var(--accent-bg-light));
}

變數名要帶 -light,是因為 inline 寫的 --accent 會贏過樣式表裡的規則,.dark 那條就蓋不過去。所以 inline 只放成對的原料,真正用的 --accent 交給樣式表決定。

換色不再需要 JS,category-hero.js 整支刪掉。

配色 B,深色規則只引用 token

body.dark 的 token 換成配色 B,原本深色規則裡寫死的色碼都改成引用 token,要換這組配色只要改 token:

/* assets/css/extended/custom.css */
body.dark {
    --theme: #2B2520;            /* paper-cream-dark */
    --entry: #362F28;            /* card-surface-dark */
    --primary: #F0E8D8;          /* ink-warm-dark */
    --secondary: #C2B28C;        /* ink-soft-warm-dark */
    /* ... */
    --ink-warm: #F0E8D8;         /* 12.4:1 on paper-cream-dark */
    --ink-soft-warm: #C2B28C;    /* 7.2:1 on paper-cream-dark, 6.3:1 on card-surface-dark */
    --link-internal: #E09A7E;    /* 6.6:1 on paper-cream-dark */
}

換了底色之後,有幾個顏色跟著調:

  • 專案強調色:深色值 #7BAA95 → #8DBBA6,在新底色上對比不夠,調亮。
  • ironman 系列強調色:深色值 #C97755 → #E09A7E,同樣是調亮。
  • 月曆最淺一格:#3B2A22 → #47322A,讓它和頁面的差距跟淺色那組一樣。

打開:跟隨系統,沒有 JS 就是淺色

最後一步只動兩個地方。hugo.yml 的兩行:

  # First visit follows the system setting; the header toggle overrides it
  # and the choice is kept in localStorage (assets/js/theme-init.js).
  defaultTheme: auto
  disableThemeToggle: false

另一個是 head 裡 PaperMod 為 auto 主題準備的 prefers-color-scheme: dark 樣式,整段拿掉。網站自己的深色 token 掛在 body.dark 上,而 body.dark 只有 theme-init.js 會設;若留著那段,沒有 JS 時系統是深色的讀者,會看到 PaperMod 的灰色混進淺色頁面。拿掉之後,沒有 JS 就是完整的淺色(關掉 JS 的實機表現我沒有試過,是從輸出的 HTML 裡已經沒有 prefers-color-scheme 判斷的)。

檢查:16 頁、兩種寬度,一個一個文字量

在瀏覽器裡對一份 16 頁的清單各跑 1280px 和 375px:首頁、兩個分類 hub、一個分類頁、三篇文章、/archives/、三個系列頁、/projects/ 和一個專案頁、搜尋、404、tags。每一頁走過每個看得到的文字節點,算它和實際背景的對比,低於 4.5:1(大字 3:1)就算不足,同時量頁面有沒有比畫面還寬。

上線前在本機跑完 32 次,文字對比 0 項不足,也沒有橫向捲動。

踩到的坑

五張截圖,其實是同一個 selector

在還沒打開開關、先手動看深色的時候,我截了五張覺得不對的地方:文章頁的 chip 是深色字配深色底,目錄、系列導覽、標籤、文末「也看看其他文章」的卡片都還是淺色的。

看起來是五個問題,原因卻是同一個,也就是之前那篇就提過的 selector。淺色 token 寫成:

:root,
.list:not(.dark),
.post-single:not(.dark),
body:not(.dark) {

文章頁的 .post-single 自己沒有 .dark class,所以在深色頁面裡又被套回淺色 token,裡面的元素拿到的全是淺色的值。改成只剩 :root, body:not(.dark) 之後,五個一次解決。

撇除這個,還有幾處是真的對比不足,另外修:hub 的光暈和副標、分頁和 404 這些填色按鈕、專案強調色。

第一輪只量了文字

第一輪的檢查只看文字,但 hover、圖示、控制項的邊界一樣會看不到,所以又補量了一輪,門檻是 3:1:hover / focus 狀態 104 個、SVG 圖示 70 個、控制項 65 個。

找到 2 項不足並修掉:

  • 月曆箭頭 hover:3.2 → 5.7。
  • 搜尋框邊界:1.5 → 7.2。

但修完月曆箭頭後,量測腳本還是說它不足。後來用真的滑鼠 hover 上去量,顏色是對的,才發現是腳本模擬 hover 的方式造成的假警報。也因為腳本沒辦法真的觸發 hover,其他 hover 狀態都是用模擬的量出來的,只有月曆箭頭有用滑鼠確認過。

上線後,在正式站又找到三處

上線後在 kiwi-walk.com 照同一份清單再走一次,32 次都跟著系統變成深色,375px 每頁的 scrollWidth 都是 375,console 也沒有錯誤。但文字對比又找到三處不足:

  • /series/ 卡片的標籤:深色的系列色字放在自己 16% 的色塊上,對比 3.62–4.25。
  • 系列頁選中分頁的篇數:3.93。
  • 程式碼區塊的註解色:這組顏色在淺色模式也一樣,不是這次造成的,所以沒有動。

前兩處是上線前的檢查漏掉的,各加一條只在深色生效的規則:

.dark .series-badge { color: var(--ink-warm); }
.dark .series-group-toc a[aria-selected="true"] .series-group-count { opacity: 1; }

標籤改成 8.05–8.42,篇數改成 5.03(修完的數字是在本機量的)。

修篇數時我第一次改錯對象,以為是所有分頁的篇數都不夠;量完才發現不足的只有選中的那一個,因為選中時篇數的字是 0.85 的透明度,疊在深色的系列色底上就不夠了。

正式站不能用本機的檢查方式

本機是把每一頁放進同源的 iframe 批次檢查。但正式站的 Content-Security-Policy 裡,frame-src 沒有列自己的網域(這是讀 header 判斷的,沒有實際試),所以改成一頁一頁開、一頁一頁量。

小結

現在讀者第一次進 kiwi-walk,會跟著系統設定看到淺色或深色;按了 header 上的切換鈕,選擇會記在那台裝置上。深色下 16 頁、兩種寬度都量過文字對比,換色只剩一種寫法,深色規則也只引用 token。