ADR-0005：token 是唯一的硬相依
- 狀態：已採用
- 日期：2026-07
背景
一個設計工具箱可以在很多層要求宿主相依：token、元件、版面框架、圖示集、 狀態管理慣例、甚至建置工具。
相依越多，一致性越高，但被採用的門檻也越高——而沒有被採用的設計系統一致性是零。
選項
| 選項 | 相依面 |
|---|---|
| A. 全套框架（token ＋ 元件 ＋ 版面 ＋ 建置） | 最一致，但只有全新專案能用 |
| B. 只有 token 是硬相依，其餘可選 | 門檻低，任何專案都能踏第一步 |
| C. 什麼都不相依，純文件 | 零門檻，但一致性完全靠自律 |
決定
採 B。
硬相依 @dooping/tokens ← 唯一建議 npm 安裝的一層
複製走 @dooping/react ← registry，複製後就是你的
只讀 模式 Patterns ← 用你自己的技術棧實作
@dooping/tokens 的產物刻意做成框架中立：
tokens.css：純 CSS 變數，任何宿主都吃得下（不含任何 Tailwind 指令）tailwind-preset.cjs：可選，給用 Tailwind 的人index.ts：型別化的 JS 讀取 API，給非 CSS 宿主（Canvas 圖表、伺服器端 PDF、Figma plugin）- 深色同時提供
.dark與[data-theme="dark"]兩種鉤子
理由
- token 幾乎不會被改，元件一定會。 把不會被改的東西做成套件才有機會真的統一； 把會被改的東西做成套件，只會逼所有人 fork。
- 第一步的門檻決定採用率。 「裝一個 CSS 變數套件」是任何團隊都願意試的； 「換掉整套 UI」不是。
- 兩種深色鉤子的成本只是多一個 CSS 選擇器，但少支援一個就少掉一整類宿主。
（這個文件站本身就是靠
[data-theme]那一條。）
影響
- token 的破壞性變更成本很高（影響所有宿主），所以移除或改名一律 major， 且要先標記棄用。見「治理 → 版本策略」。
- token 的 JSON 來源不能直接被 TS 用 import attributes 引入
（
with { type: "json" }在各家打包器支援度不一致）——改由建置腳本產生.ts資料模組。 這是實際踩到的坑。 - 元件層不得反過來要求宿主安裝額外的執行期相依（狀態管理、路由）， 由邊界守衛測試強制。