陷阱（Gotchas）

禁止在權杖命名中使用具體值 — blue-500, primary-blue ✗ → color.text.primary, color.background.brand ✓。數值改變時命名會產生落差，在重新品牌/暗黑模式切換時即刻崩潰。
不可僅使用 primitive 而無 semantic — 將 color.green.500 直接連接到元件上會導致主題無法切換。必須經過 primitive → semantic(alias) → component 三層架構。
不要將暗黑模式嵌入權杖名稱 — color-dark-text-primary, color-light-surface ✗。這會讓消費者被迫處理主題條件。正確做法是為一個 semantic 權杖對應不同模式的值。
禁止未經 scale 的任意數值 — 像 10px, 14px, 18px, 22px 這樣隨意累積的 spacing/radius 會破壞系統。先確定有限的 scale（例如 2/4/8/12/16/24/32），拒絕之外的數值。
不要將元件權杖當作全域權杖重複使用 — 在其他元件中引用 button.primary.background 會提高耦合度。僅當多個元件共同需要時，才將它提升為 semantic global 權杖。
字體排版應使用組合權杖而非個別數值 — 分別使用 font-size-14, line-height-20 可能產生組合錯誤。應優先提供像 font.body.medium 這樣將 size/weight/line-height 打包的 semantic style token。
必須明確標示 spacing base 的依據 — 若非 4px base，則必須文件化其理由。比起 base 數字，「使用允許的 scale 保持一致」更為重要。
DTCG 命名規則 — 權杖/群組名稱中不得使用 { } .，且不以 $ 開頭（$ 前綴是 $value · $type 等屬性鍵的保留字）。層級透過巢狀 JSON 群組建立。. 僅在撰寫參考時用於串接群組名稱（{color.text.primary}），不是名稱內的字元。來源：DTCG Format Module 2025.10。
禁止直接生成特定平台的程式碼 — 此技能僅輸出原則與權杖規格。不要直接產生 Flutter/React/CSS 程式碼。應委派給對應的 toolkit 外掛程式。
利用 DTCG $extends 群組繼承 — DTCG 2025.10 新增的 $extends 關鍵字允許群組間進行 deep merge 繼承。不要在多個 semantic 群組中重複定義相同的 primitive 值，而是建立共用群組並透過 $extends 參考。禁止循環參考，解析器應能偵測。來源：research-log §A。
HTML 範例中的 :root CSS 變數必須與 design-kit 既有檔案一致 — 在 Step 4 中包含權杖規格範例的 HTML 片段時，:root { --color-*: ...; } 的值必須與 design-kit/docs/ 或 design-kit/templates/ 中既有 HTML 檔案的 CSS 變數值一致。值不一致是系統分裂的開始，且曾是實際的 REJECT 原因（AR-06）。新增變數時必須同時更新既有檔案，或說明不一致的理由。
顏色 primitive 建議使用 OKLCH — Tailwind CSS v4（2025-01-22 發布 · 最新穩定版 v4.3.3，2026-07-16）已將預設色板從 rgb 改為 oklch，shadcn/ui v4 也完成了 HSL → oklch() 轉換。OKLCH 透過感知上的 lightness(L)·chroma(C)·hue(H) 軸提供均勻的色階，並能利用 P3 wide gamut 突破 sRGB 限制。定義 primitive 時優先使用 oklch(L% C H) 表示法，若需要舊版瀏覽器 fallback，則同時提供 sRGB hex。瀏覽器支援： Safari 16.4+ / Chrome 111+ / Firefox 128+（與 Tailwind v4 支援範圍相同）。Figma 注意： Figma 說明頁面將色彩模型列為 Hex · HSB · HSL · CSS · RGB 五種，OKLCH 不在列表中（About color models）。沒有直接寫明 Variables 無法接受 OKLCH 的句子，因此不要如此斷定；在轉移到 Figma 時，慣例是同時提供 hex 近似值（例如 Obra shadcn kit）。來源：Tailwind v4 blog, Tailwind v4.3.3, shadcn Tailwind v4, Evil Martians OKLCH, MDN oklch()。
先列舉再行動（Enumerate-before-Act）— 修改權杖前必須完整列舉 — 在收到現有設計系統的改善請求（例如「幫我處理暗黑模式」、「整理 semantic 權杖」）時，在編輯前必須按照以下順序列舉：(1) 現有權杖檔案完整列表 + 各類別數量，(2) Tier 1 primitive / Tier 2 semantic / Tier 3 component 分布，(3) 以違規列表呈現缺失類別 · 命名違規 · 未處理暗黑模式項目，(4) 使用者批准後再編輯。避免只修改一部分然後說「後續照此辦理」的反模式（對應 insights-report #1 "Proactive quality gaps" · skill-design-guide §5.5 Enumerate-before-Act 原則）。
遵循 DTCG v1 綱要 — alias 是大括號參考 — Design Tokens Community Group 已於 2025-10-28 將 Design Tokens Format Module 2025.10 作為第一個 stable "Final Community Group Report" 發布（DTCG v1）。JSON 格式使用 $value, $type, $description 前綴，群組物件（無 $value）可設定群組層級的 $type 預設值。$extensions 是工具廠商的中繼資料。$schema 不在 2025.10 Final Report 的群組屬性列表中——如果工具使用此擴展，應與 DTCG 規格區分標註。

alias 表示法（容易出錯的地方）： 規格中的參考語法是以大括號包裹的字串 {group.token}。陷阱 8 禁止 { } 是針對權杖名稱的規則，因為大括號被保留作為參考的包裹符——在參考值中必須使用大括號。這兩條規則並不衝突。裸的點號字串（"color.background.surface"）不會被解釋為參考，只是普通的字串值。大括號參考只能指向完整的權杖（具有 $value 的物件），若要指向權杖值內部的個別屬性，則使用 JSON Pointer（RFC 6901）格式的 $ref（#/path/to/target）。
```
{
  "color": {
    "brand": { "$type": "color", "$value": { "colorSpace": "srgb", "components": [0, 0.4, 0.8], "hex": "#0066cc" } },
    "surface": { "$value": "{color.brand}" }
  }
}
```
禁止： 舊式 value/type 鍵（無前綴）、自訂 $ 前綴鍵、無大括號的裸點號 alias。color 權杖的值應採用包含 colorSpace / components / hex(可選) / alpha(可選) 的物件結構——純 hex 字串格式不存在於規格中。Tokens Studio / Style Dictionary / zeroheight 等下游工具皆假設此格式。來源：W3C DTCG v1 announcement 2025-10-28, W3C Final Report, DTCG Format Module (drafts), Tokens Studio DTCG vs Legacy。
不要將現有應用程式的顏色替換為新的色板（視覺真實來源優先） — 在已經有顏色體系的專案中導入權杖時，不要基於研究建立「更好」的新色板。首先要完整提取並呈現實際使用中的數值，並以將這些數值包裹進權杖作為基本方案。改變數值本身需要另外提出，並獲得使用者批准。如果使用者已在瀏覽器中確認並批准的設計稿顏色（記錄在 .design/approvals/）存在，則優先於專案色板——將已批准的顏色標準化為單一 tint 或現有 accent 權杖是一種退化。優先順序表：../../references/visual-change-protocol.md §1。
```
Bad:  "我定義了背景色權杖"（未讀取現有應用背景，直接建立新的中性色階）
      → "背景色還是不對，原本的顏色應該存在吧？"
Bad:  將已批准設計稿的 accent → 專案 accent 權杖取代 → "為什麼用不同的顏色？"
Good: 完整提取現有數值 → 以表格呈現 → "我將把這些數值包裹成 semantic 權杖。
      若有需要調整的項目請告知"
```
部分變更請求只針對該權杖 — 禁止同時調整周邊數值 — 對於「只要把這個邊框顏色加深」、「只要把 surface 調暗一階」這類請求，不要一併調整未被指定的權杖（背景、fill、文字、radius、elevation）。即使為了色階一致性而重新計算相鄰階梯，也超出了請求範圍。編輯前留下 變更 / 保留 清單，編輯後確認保留清單中的數值未變。若非預期的權杖發生變化，則回復並僅重新套用指定項目。「顏色現在是對的，但 gradient 回到之前」這類部分回退，只回退指定的軸。詳情：../../references/visual-change-protocol.md §2。
僅定義被要求的權杖類別 — 禁止任意擴展完整系統骨架（對應 insights-report #1 範圍誤讀 · #3 過度設計） — 如果只收到「建立顏色色板」、「設定 spacing scale」這類特定類別的要求，就只定義該類別。不要一次性地為整個系統（typography·radius·elevation·motion）搭建完整骨架，連同未要求的類別也包含進來。「完整的權杖體系」要求（其他陷阱中的三層級·semantic 強制）是指被要求類別內部的完整性，而不是任意擴展類別本身。若範圍模糊，不要猜測擴展，而是用一行話確認：「只要定義顏色，還是要設定整個權杖體系？」。若認為擴展提議有價值，不要將其嵌入產出物中，而是以獨立提案的形式提出：「建議額外設定 typography/spacing 權杖 — 要繼續嗎？」。三層級（primitive→semantic→component）的完整建構也是如此——根據 2026 年研究，大多數團隊使用 primitive+semantic 兩層就已足夠，component 權杖層僅在企業規模下需要。在未收到明確要求或規模依據時，不要預設輸出三層級。來源：zeroheight Design Systems Report 2026（兩層為實務標準，完全三層約僅半數團隊採用）, material-design.md:281（漸進式導入）。

流程

Step 1：偵測專案設計系統

在專案根目錄中搜尋設計權杖/主題檔案：

# 搜尋模式（無關技術棧）
**/theme/**
**/tokens/**
**/design/**
**/styles/**
**/colors.*
**/typography.*

若找到：HAS_DS=true，分析現有權杖結構
未找到：HAS_DS=false，進入新建權杖體系提案模式

Step 2：設計三層權杖架構

所有權杖都應分為以下三層，不可跳層連接。

Tier 1 — Primitive（數值儲存庫）
  例如：color.palette.green.500 = #22c55e
       space.scale.4 = 4px

Tier 2 — Semantic（角色/意圖別名）
  例如：color.text.success → {color.palette.green.500}
       color.background.surface → {color.palette.neutral.50}  (light mode)
       color.background.surface → {color.palette.neutral.900} (dark mode)

Tier 3 — Component（元件例外覆寫）
  例如：button.primary.background → {color.background.brand}
       card.border.radius → {radius.md}
  ※ 僅在跨多個元件共同需要時才提升至 Tier 2

各類別的必備/選用及 semantic 命名標準：

類別	必備	Semantic 範例	Scale 標準
Color	必備	text.primary, text.secondary, text.disabled, background.surface, background.brand, border.default, border.subtle	—
Typography	必備	font.display.lg, font.heading.md, font.body.sm, font.label.xs（size+weight+line-height 打包）	建議使用 Modular Scale 比例（1.125 Major Second ~ 1.618 Golden Ratio）。流體：`clamp(min, preferred, max)`
Spacing	必備	space.xs(4), space.sm(8), space.md(16), space.lg(24), space.xl(32), space.2xl(48)	4px base。流體 spacing：可考慮基於 `clamp()` 的連續間距
Radius	必備	radius.none(0), radius.sm(4), radius.md(8), radius.lg(16), radius.full(9999)	有限的 scale
Elevation	選用	elevation.level-0 ~ level-4 (陰影值)	—
Motion	選用	motion.duration.fast(100ms), motion.duration.normal(200ms), motion.easing.standard	—

備註 — Material 3 Expressive（2025-05 發布）： 官方 Material 文件指出 M3 Expressive 基於 46 項研究、超過 18,000 名參與者，提供更廣的顏色範圍 · 動態顏色 · 個人化 · 基於 spring 的 motion physics 系統。使用 HCT 為每個顏色建立 tonal palette 並將那些 tone 分配給 color role，這是 Expressive 特有的功能，而非 M3 顏色系統整體的描述。Roboto Flex 這類 variable font 是表達的選項，不屬於 M3 type scale。將 tonal palette 的 tone 對應到 primitive、color role 對應到 semantic alias，並非官方規則，而是此儲存庫三層權杖結構的慣例。來源：Start building with Material 3 Expressive, Color system, Typography, Motion（2026-09-28 查閱）。

Step 3：HAS_DS=true → 分析現有系統

以三層架構為基準比較現有權杖，輸出報告：

層級缺失：將 primitive 直接連接到元件的項目
命名違規：名稱中包含數值的權杖（blue-500, color-dark-*）
未處理暗黑模式：缺少 mode alias 的 color semantic 權杖
脫離 scale：使用允許 scale 之外的任意數值
元件權杖誤用：在其他元件中重複使用 component 權杖
字體排版分離問題：僅以個別權杖提供 size/weight/line-height 的情況

Step 4：HAS_DS=false → 產生權杖規格

以 templates/design-tokens.md 格式產生權杖規格。按以下順序向使用者提出各類別的選項並取得共識：

確定品牌顏色色板（primitive）
semantic color 權杖 — 包含 light/dark 兩側的對應
spacing scale（預設 4px base，變更時需說明依據）
typography 樣式權杖組合
radius scale
elevation/motion（若需要）

Step 5：確認產出

確認所有必備類別已分為三層
確認 semantic 權杖已定義為 primitive alias（非直接寫入數值 ✗）
確認存在 light/dark 兩側的 semantic 對應
確認無允許 scale 之外的任意數值
若有 component 權杖，確認其範圍僅限於該元件
檢查 :root CSS 變數的一致性（陷阱 #11）— 若產出包含 HTML :root 片段，請對照 design-kit/docs/ 及 design-kit/templates/ 中既有 HTML 檔案的 CSS 變數值，確認無不一致項目。發現不一致時，同時更新既有檔案或說明理由。
Figma Variables → Tokens Studio → Style Dictionary v5 管線指引 — 在產生權杖規格時，向使用者說明 Figma Variables(primitive + semantic) → Tokens Studio DTCG JSON 匯出 → Style Dictionary v5 平台別轉換 → Git 同步的管線。建議啟用 Code Syntax、使用 Description 欄位、限制 Scope。v5 需要 Node.js 22 以上，且不再接受指向非權杖值的參考、附加 .value 的參考、以及更改參考語法——將 v4 設定遷移時需先檢查這三點。convertTokenData 物件輸出的原型污染漏洞已在 v5.5.5(2026-09-20) 修復，請勿使用低於此版本的版本。來源：research-log §I, Style Dictionary v5.0.0, v5.5.5, v5 Migration。
流體字體排版指南 — 在定義 typography 權杖時，除了固定尺寸，應提出基於 clamp(min, preferred, max) 的流體 scale 選項。推薦符合專案性質的 Modular Scale 比例（1.125 Major Second ~ 1.618 Golden Ratio），並參考 Utopia 方法（小/大螢幕兩種 scale 內插）。來源：research-log §E。
流體 Spacing 指南 — spacing 權杖除了 Fixed(固定) 之外，應提出 Fluid(clamp()) 及 Adaptive（根據 breakpoint 切換）選項。明確說明 Internal ≤ External 規則（元素內部邊距 ≤ 外部邊距）。來源：research-log §F。

參考資料

references/token-principles.md — 權杖設計原則詳情
templates/design-tokens.md — 權杖規格輸出格式
../../references/visual-change-protocol.md — 視覺優先順序 · 部分變更隔離（SSOT）

joo6077/design-system

design-system 是什麼？

在你喜歡的 AI 中提問

說明文件

陷阱（Gotchas）

流程

Step 1：偵測專案設計系統

Step 2：設計三層權杖架構

Step 3：HAS_DS=true → 分析現有系統

Step 4：HAS_DS=false → 產生權杖規格

Step 5：確認產出

參考資料

Individual skills in this repo

joo6077/design-audit

joo6077/design-mockup

joo6077/design-test

joo6077/react-animation

相關技能

steipete/sag

steipete/oracle

steipete/peekaboo

mattpocock/design-an-interface

mattpocock/prototype

mattpocock/grill-me