`，那 `body { color: var(--color-fg) }` 仍解析成**淺色**值——任何只靠**繼承**取色的文字就變暗底暗字、直接看不見。兩道防線一起用： 1. 把基礎文字色掛在**主題容器本身**（root div 給 `class="text-fg theme-dark"`），讓子孫繼承到已解析的值。 2. 文字仍給**明確**顏色 class——尤其裸 ``/``、清單項、以及 modal / dropdown / portal 裡的東西。別信任繼承。每個深色畫面都自問：有沒有讀不到的字？modal、下拉、表格格、空狀態是常見兇手。 ## 整理 className 的習慣 - 順序大致：佈局 → 盒模型 → 排版 → 視覺 → 狀態/變體（`hover: focus: dark: sm:`）。 - className 太長、或同組合重複 3+ 次 → 抽成元件，或 `@layer components` 的 class（用 `@apply`）。 - 用 `clsx` / `cn()` 處理條件 class，不要字串拼接一堆三元運算。 - 不要 `@apply` 一長串把 Tailwind 當 CSS 寫——失去 utility 意義；元件化更好。 ## 元件配方（重複 3+ 次就抽成這些） - **Button**：variants（`primary` 實心／漸層強調、`secondary` 描邊、`ghost` 透明），一套尺寸，`rounded-xl`，可見的 `focus-visible:ring-2 ring-brand-500`，按壓回饋 `active:scale-[0.98]`；停用 `disabled:opacity-40 disabled:cursor-not-allowed`。 - **Card**：`rounded-2xl border border-border bg-surface shadow-card`。用 padding／陰影分強弱，別靠染背景色。 - **Badge / Chip**：柔和 tonal 填色（`bg-brand-50 text-brand-600`）、小圓角、克制。選取態的邊框用半透明強調色（`border-brand-500/35`）勝過亮實色——亮邊在深色會刺眼。 - **Input**：一致高度、`border border-border bg-surface`、`focus:border-brand-500` 或 focus ring；**永不拿掉 focus 樣式**。 - 巢狀圓角：內圈 ≈ 外圈 − padding（同心），否則轉角會歪。 ## 數字與動態 - **會變動或要對齊的數字一律 `tabular-nums`**（價格、計數、表格格），等寬字位不跳動。 - 動畫**指定屬性**：`transition-[transform,color,background-color]`，**別用 `transition-all`**——它會animate layout 屬性造成 jank，也吃掉 GPU 合成。尊重 `motion-reduce:`。 - 顏色不作唯一資訊（配 icon／文字）；紅／綠只留給真正的負／正、跌／漲。 ## 常見雷 - arbitrary value 濫用（`w-[327px]`、`text-[#abc]`）→ 多半該用 token 或標準 scale。 - 動態拼 class（`` `text-${color}-500` ``）→ Tailwind 掃不到、會被 purge 掉；改用完整 class 對照表。 - `transition-all`、拿掉 focus outline 不補替代。 - 直接改第三方/全域樣式而非用 token。 - 忘了深色或響應式分支，或深色畫面有繼承色文字看不見。 ## 自我檢查 - [ ] 有先讀專案的 tailwind.config 與設計系統文件 - [ ] 沒寫死 hex / 任意 px（除非真的一次性無 token） - [ ] 用語意 token，不是色相名 - [ ] 深淺主題、響應式都顧到；深色畫面沒有繼承色看不見的文字 - [ ] 複用了既有元件 / component class，沒重造 - [ ] focus / 對比 / 觸控尺寸符合無障礙 - [ ] 會變動 / 要對齊的數字有 `tabular-nums`；動畫沒用 `transition-all`