站內設計規範散落各處是常態。標題大小寫寫在主題 CSS 裡、品牌色碼藏在自訂 CSS、按鈕外觀靠頁面建構器一頁一頁手動套用，等到下次改版才發現同一支品牌色，在後台被改成了 4 種色碼。

theme.json 就是 WordPress 為了收斂這種混亂而設計的單一檔案。它不是一份普通的設定檔，而是把「設計系統」這個概念直接搬進主題根目錄。色票、字級、間距、區塊預設都在這份 JSON 裡定義一次，後台編輯器與前台輸出共用同一份來源。

這篇用設計系統的角度拆解 theme.json 全域樣式的層級結構，從最上層的 settings、styles 一路到區塊預設，示範站長怎麼把分散的樣式規則收進一份檔案，讓每個頁面、每個區塊預設拿到的，都是同一組值。

theme.json 不是設定檔而是設計系統的容器

把 theme.json 當成普通的 WordPress 設定檔看待，會錯失它真正的價值。一般設定檔像是「開關面板」，告訴系統某個功能要打開或關閉。這份檔案不是這種角色，它定義的是整個網站的視覺語言，包含哪些顏色可以用、字級有哪幾階、間距有幾種規格、每一種區塊預設長什麼樣。

換個角度看，這份檔案承擔的是設計系統（Design System）裡「設計權杖」（Design Tokens）的工作。設計權杖是命名好的視覺屬性，把色碼、字級、間距這些原本散落各處的值集中起來，給它們一個名字，全站引用名字而不是引用具體數值。改一次顏色定義，全站使用該名字的地方一起跟著動，這是設計系統的核心精神。

WordPress 把這個概念直接寫進核心。檔案裡定義的色票、字級、間距會被自動轉成 CSS 自訂屬性（CSS Custom Properties），同時送到前台與後台編輯器，作者在編輯器看到的下拉選單裡的字級、色塊背景的色碼，就是檔案裡的那組值。前後一致是基本要求，省下「後台選了 #2563eb，前台又被覆蓋成另一個藍」這種典型錯位。

設計層級從上到下的四層結構

theme.json 的頂層欄位有七個，扣掉 schema 跟 version 兩個元資料，真正承載設計決策的是四個區塊。理解這四層的層級關係，比死記欄位名稱更重要，因為層級決定了「誰會被誰覆蓋」。

最上層是 settings，定義「能用什麼」。色票有哪幾組、字級有哪幾階、間距尺度允許多少、自訂顏色開不開放給作者輸入，都在這裡決定。settings 不直接套用樣式，它只規範可選範圍，後台編輯器拿著這份清單去渲染選單。

往下一層是 styles，定義「實際套了什麼」。網站背景色、預設字體、連結色、按鈕外觀，這些立即可見的視覺結果寫在 styles 裡。styles 引用的色碼字級可以是 settings 裡定義過的權杖，也可以是具體值，但慣例是引用權杖，這樣才有設計系統的意義。

再往下是 styles.blocks，把樣式下放到「特定區塊」。同一份檔案可以給段落區塊一種預設、給標題區塊另一種預設、給按鈕區塊第三種預設。WordPress 規定的繼承順序，是「全域 styles 先套用，blocks 內的覆蓋值再蓋上去」，所以全域定義基準、區塊定義例外，是最乾淨的寫法。

最底層是 templateParts 與 customTemplates，管的是模板組裝。這層跟視覺權杖的關係比較遠，作用是告訴 WordPress 哪些區塊組合可以重複使用於頁首頁尾，或哪些自訂模板要登記。設計系統的色與型主要集中在前三層。

色票字級間距三組基礎 token 怎麼收

要把設計規範收進這份檔案，最先要處理的是三組基礎權杖。這三組落地之後，後面所有區塊預設、模板樣式都會以它們為基準。

• 色票（color.palette）：在 settings.color.palette 陣列裡每一筆給三個欄位，slug 是引用名（例如 primary、accent、surface），name 是後台顯示名稱，color 是色碼值。命名建議走語意（primary、accent、muted）而不是具體顏色（blue、gray），日後換色不必改 slug。版本 3 起，把 defaultPalette 設為 false 才會關掉 WordPress 預設色票，只留下自家品牌色，避免作者誤選核心預設值
• 字級（typography.fontSizes）：陣列裡每一筆同樣給 slug、name、size，slug 用 xs、s、m、l、xl 這類尺度命名，比用 small、medium 更接近設計系統慣例。流體字級（Fluid Typography）開啟後可在每一筆字級加 fluid 物件，給 min、max 兩個邊界，WordPress 會用 CSS 的 clamp() 函式產出隨視窗縮放的字級，等於一次處理掉桌機與手機的字級差異
• 間距（spacing.spacingSizes）：版本 3 把間距正式列為一級權杖，陣列結構跟字級相同。建議用倍數關係（0.25rem、0.5rem、1rem、1.5rem、2rem、3rem）對應 xxs、xs、s、m、l、xl，padding、margin、blockGap 都從這套尺度抓值，視覺上才會有節奏感

三組權杖一旦定義好，整個編輯器的選單會自動換成這份清單。作者再也看不到「自訂顏色」的色碼輸入框（前提是 custom 設為 false），下拉只剩自家定義的 6 個顏色，誤選率直接歸零。

區塊預設讓樣式自動套用到每一個段落

色票字級間距收完之後，接著要處理的是區塊預設（Block Defaults）。這是 theme.json 真正幫站長省下手動調整時間的地方。

WordPress 的每一種區塊都可以在 styles.blocks 底下單獨定義樣式。舉例來說，給 core/heading 設一份預設樣式，全站所有透過區塊編輯器產出的標題都會自動套用該樣式，作者不必每篇文章手動把 H2 改成自家品牌色。給 core/button 設預設，全站所有按鈕的圓角、內距、字級、懸停色一次到位，廠商換按鈕款式時改一個檔案就完成。

層級覆蓋邏輯在這裡發揮關鍵作用。全域 styles 是基準層，styles.blocks.core/heading 是區塊層，作者在單篇文章手動改的樣式是行內層。三層由下往上覆蓋——行內覆蓋區塊、區塊覆蓋全域。設計系統會希望多數樣式停在區塊層，少數例外才動行內。

引用權杖在這個時候特別重要。styles.blocks.core/button 的背景色不要直接寫色碼，而是寫 var:preset|color|primary 這種引用語法，等於告訴 WordPress「拿 settings 裡名為 primary 的色票來填」。將來改 primary 的色碼，按鈕、連結、強調區塊全部跟著換，這就是設計系統的複利效應。

從版本 2 升到版本 3 改變了什麼

theme.json 目前同時存在版本 2 與版本 3 兩種寫法。版本 2 從 WordPress 5.9 一路用到 6.5，版本 3 自 6.6 引入，需要 WordPress 6.6 以上才會完整支援。決定要用哪一版之前，先把核心差異攤開比對。

實務上的取捨大致這樣抓。新主題、新站台、自有主機可隨時升版的情境，直接走版本 3，未來才能用流體字級的細粒度控制與陰影權杖。如果站台跑在共用主機、WordPress 版本受限，或是還要支援多個舊客戶站，先用版本 2 把基本權杖收乾淨，等核心升上去再切版本 3。

把現行站內樣式遷進 theme.json 的順序

理解概念之後，真正的工程是「把現有站內樣式遷進來」。下面四個 H3 是建議的執行順序，從盤點到驗收一條鏈走完。

盤點現行樣式來源

先把目前站內所有樣式來源列出來，常見的有四處——主題的 style.css、頁面建構器內建的全域樣式、後台「外觀／自訂」裡的額外 CSS、單篇文章用區塊行內樣式硬寫的色碼。每一處抓出實際使用中的色碼、字級、間距、按鈕外觀，整理成一張對照表。沒做這一步直接動手寫設定檔，多半會漏掉一兩支品牌色，遷完之後發現某個頁面顏色不對。

把基礎權杖寫進 settings

對照表抓出共用的色碼、字級、間距後，把這些值寫進 settings.color.palette、settings.typography.fontSizes、settings.spacing.spacingSizes。命名走語意，slug 用英文短詞，name 用中文方便後台辨識。同時把 defaultPalette、defaultFontSizes、defaultSpacingSizes 設為 false，關掉核心預設值，避免清單裡多出非品牌色給作者誤選。

區塊預設搬進 styles.blocks

接著處理 styles.blocks 底下的區塊樣式。優先順序是「全站最常出現的區塊先動」，通常是段落、標題、按鈕、連結這幾個。每一個區塊的色碼字級背景全部改用 var:preset|color|xxx 這種引用語法，不要再寫死色碼。改完後在區塊編輯器隨手插一個新區塊，確認預設樣式自動套上。

跑視覺迴歸驗收

設定檔寫完別急著上線，跑一輪視覺迴歸（Visual Regression）。把站內前 10 個流量最大的頁面、5 種代表性區塊組合，遷移前後各截一張圖比對。常見的落差，是「某篇文章作者當初手動改了行內色碼，遷移後沒被全域樣式蓋掉」，這種要逐篇修正，或寫一支腳本掃 post_content 清掉行內樣式。驗收通過後再開放給其他編輯使用。

收斂到一份 theme.json 全域樣式檔之後，後續調整設計只剩一個入口。改色票、調字級、換間距，全部在這份 JSON 裡完成，編輯器跟前台同步生效。設計師交給工程師的是檔案而不是 PSD 標註，工程師交給編輯的是規範好的下拉選單而不是空白的色碼輸入框，這才是設計系統該有的協作型態。