D-20260708-10｜兩層 token 架構（語意層＋元件層 --o4-*）

背景與驅動力

拍 10a 落地 token 供應鏈（src/themes/default/theme.json＝token 名錄與預設值權威，生成 SCSS 基準、check:tokens 入驗證鏈）與 o4-* 基礎元件庫時，使用者提問引發定案：主題要做出大幅視覺分歧時 token 粒度夠不夠、要不要開放主題直接覆蓋元件 CSS。

考慮過的選項

• 開放任意主題 CSS 覆蓋：社群 PR 資料包成 overlay 釣魚面、gameplay 資訊完整性不可保（THEME_RESERVED_SFX 同哲學）、元件 DOM 非穩定 API——拒絕。
• 僅語意層 token：粒度不足以承載元件級視覺分歧。
• 語意層 ＋ 元件層兩層 token（採納）。

決定

• 兩層 token 架構：語意層之上加元件層 --o4-* 細粒度旋鈕；值可 var(--語意) 回退；元件層 token 必登錄 default manifest（validate 治理與 D-20260704-01 的資產槽同構）。主題自由度 ＝token 面豐富度。
• 拒任意主題 CSS 覆蓋；大幅視覺分歧走三正路：token 全面化 ＋ 資產槽 ＋3D preset 同步。
• 生成物（tokens SCSS）禁手改並入 .prettierignore；check:tokens 為驗證鏈固定一環。

後果與影響

主題能力邊界清楚（名錄治理、CI 可驗），元件內部 DOM 不成為相容面。其後 D-20260723-01 在此基礎上開放受控 theme.css（版本化 [data-theme-part]＋validator 守門）承載 token 化不合理的構圖需求——兩層 token 名錄與 default manifest 治理不變、「拒任意 CSS」的理由仍成立。權威見 ui-frontend.md 與 主題系統.md。