ADR-0001：語意色，而不是色票

• 狀態：已採用
• 日期：2026-07

背景

設計 token 的色彩層有兩種常見做法：

1. 色票式：--blue-50 … --blue-900、--red-500，元件自己挑
2. 語意式：--primary、--danger、--field-editable，值由 token 決定

多數大型設計系統（Material、Tailwind 預設）採第一種或兩者並存。

選項

選項	優點	缺點
A. 純色票	彈性大、設計師熟悉	換皮要改所有使用處；同一個「危險」在不同畫面用不同紅
B. 純語意	換皮只改值；語意一致	遇到 token 沒涵蓋的需求會卡住
C. 兩者並存	兩全	實務上等於純色票——有捷徑就沒人走遠路

決定

採 B：只提供語意色。 不提供 --blue-500 這類色階 token。

唯一的例外是圖表分類色票（--chart-1 … --chart-8）， 它們本質上就是「一組彼此可區分的顏色」，沒有個別語意。

理由

1. 換皮是真實需求。 同一套後台介面要掛不同品牌，這件事一定會發生。 語意色讓它變成改一個 JSON。
2. 一致性靠限制達成，不靠自律。 提供色階就等於提供捷徑， 而趕時間的時候大家都會走捷徑。
3. 語意是可討論的，色碼不是。 「危險用哪個紅」是設計決策， 「這個狀態算不算危險」是產品決策——語意命名讓後者浮上檯面。

選項 C 被否決的理由最實際：只要留了後門，就等於沒有規則。

影響

• 遇到 token 沒涵蓋的顏色需求時，正確做法是討論要不要新增一個語意， 而不是硬編一個色碼。這會讓開發變慢，但那個慢是有價值的。
• 需要一支守衛測試防止硬編色回流。
• destructive（控制項語意）與 danger（狀態語意）必須分成兩個 token， 因為它們會同時出現在同一個畫面上。