建立系統化設計系統
brand 技能決定品牌識別；frontend-design 技能決定介面的外觀。
這個套件決定如何將外觀「結構化以實現可擴展性」：一個三層代號架構，
搭配單一事實來源、涵蓋所有狀態的元件規格、以及防止原始值回滲的檢查。
當你需要深入細節時，請載入參考文件：
| 主題 | 參考文件 |
|---|---|
| 層級、命名、深色模式、DTCG JSON、從扁平代號遷移 | references/token-architecture.md |
| 按鈕/輸入/卡片/標籤/提示/對話框/表格的變體、尺寸與狀態矩陣 | references/component-specs.md |
| 狀態優先順序、焦點環、錯誤/載入模式、每個狀態的 ARIA | references/states-and-variants.md |
一句話說明架構
/* 原始層 — 原始數值，不含語意。極少變動。 */
--blue-600: oklch(55% 0.2 264);
/* 語意層 — 表達用途。主題切換點：淺色/深色/品牌覆蓋僅在此層。 */
--color-primary: var(--blue-600);
/* 元件層 — 每個元件的獨立參數，引用語意代號。 */
--button-bg: var(--color-primary);
元件應使用元件代號或語意代號 —— 絕不能使用原始代號或字面值。 主題（深色、高對比度、第二品牌）只需重新指派語意代號，無需更動其他層級。
單一事實來源。 如果倉庫使用 W3C Design Tokens Community Group
(DTCG) JSON 格式儲存代號 —— 該格式已於 2025 年 10 月達到第一個穩定版本 2025.10 ——
那麼這些檔案就是來源：代號包含 $value 和 $type，別名寫為
{color.blue.600}，並由建置工具（Style Dictionary 或倉庫中同等工具）
產生 CSS 變數、Tailwind 主題與原生值。請編輯 JSON 後重新產生；
切勿手動編輯產生的輸出。如果倉庫只有 CSS 自訂屬性，則以它們為來源。
請勿引入第二個來源。
步驟
- 閱讀現有內容。 使用
search_lore搜尋設計系統的 ADR；尋找代號檔案 （*.tokens.json、tokens/、theme.ts、:root區塊、Tailwind 設定）、用於產出結果的建置命令， 以及兩個同層級元件。請依其慣例擴展現有系統， 切勿加入另一個競爭系統。 - 先審計，再新增。 計算元件樣式中的字面值（使用下方命令）。你碰到的每個洩漏處 不是被現有代號取代，就是需要建立新代號。
- 將每個新代號放在正確的層級。 只有真正全新的原始數值才放原始層；
新的用途（
--color-surface-raised、--space-section）放語意層； 唯有當某個元件必須與眾不同時才放入元件層。 命名應描述用途，而非外觀 （--color-danger，而非--color-red）。顏色的原始代號使用oklch（團隊慣例）， 字體大小使用clamp()流暢縮放，間距以一個基礎單位（4px 或 8px）為基準。 - 在語意層進行主題切換。 深色模式及其他主題在一個區塊中覆蓋語意代號
（
[data-theme="dark"]、.dark或@media (prefers-color-scheme: dark)，依倉庫而定） 並設定color-scheme屬性，使原生控制項與捲軸能跟隨主題。 若某主題覆蓋了原始代號或元件代號，表示切換點位置有誤。 - 驗證每個主題的對比度。 對於每個實際使用的前景/背景語意配對
（文字在表面、文字在主色、邊框在表面、焦點環在表面），
計算每個主題中的 WCAG 對比度：一般文字 4.5:1，大型文字、
UI 邊界與焦點指示器為 3:1。
oklch的亮度不等於 WCAG 對比值——請 實際計算（透過腳本、倉庫的檢查工具或測試）。記錄對比度表格。 - 完整指定元件。 變體、尺寸（明確的高度、內邊距、字體代號）、
以及狀態矩陣——預設、懸停、焦點可見、啟用、停用、載入、錯誤、
以及相關的選中/勾選狀態——並附上每個狀態所暴露的 ARIA。
多重狀態同時生效時的優先順序：停用 > 載入 > 錯誤 > 啟用 > 焦點 > 懸停 > 預設。
焦點永遠可見（使用
--color-ring的:focus-visible外框，絕不能單用outline: none）。 詳細內容請見參考文件。 - 為新產品推薦設計系統： 從產品本身出發，而非套件——
(a) 模式與密度（行銷、數據密集儀表板、交易流程），
(b) 方向（遵循
brand的決定），(c) 調色板姿態（語意角色應包含 success/ warning/danger/info；僅在使用者需要時才提供深色模式），(d) 事先聲明可及性與 效能目標。輸出簡短的決策理由，加上代號與元件架構；視覺執行部分交給frontend-design。 - 驗證並提供證據。 如果倉庫會建置代號，請重新產生代號輸出並確認差異只包含你預期的內容；
執行 lint、型別檢查與測試；執行洩漏檢查；
透過倉庫的元件測試或螢幕截圖測試（若存在）在每個主題下渲染修改過的元件。
使用
record-evidence技能記錄每個驗收條件的證據（前後洩漏數量對比、對比度表格）， 然後結束。
洩漏檢查
在修改過的元件與樣式檔案上執行（排除代號檔案本身）：
- 原始顏色：
grep -rEn '#[0-9a-fA-F]{3,8}\b|rgba?\(|hsla?\(|oklch\(' src/components - 原始字體大小：
grep -rEn 'font-size:\s*[0-9.]+px' src/components - 元件中引用的原始代號：
grep -rEn 'var\(--(gray|blue|red|green)-[0-9]+' src/components - 已存在代號卻使用 Tailwind 任意值：
grep -rEn '\[(#|[0-9]+px)' src/components
請根據倉庫實際情況調整路徑與原始代號名稱。在你的差異中出現的新匹配屬於缺陷，
應由建置者修正，除非該行本身是代號定義；審查者可將其標記為
（可選），除非它違反某項驗收條件或某個主題的對比度。
完成條件
元件中沒有新的字面值或原始代號引用；每個主題只覆蓋語意代號； 對比度表格在每個主題中皆通過；每個被觸及的元件的狀態矩陣已實作並具有可見焦點； 產生的輸出與來源一致。
知識擷取
倉庫的代號架構——層級劃分、命名慣例、深色模式切換點，或「元件中絕不能引用原始代號」的規則——
正是下一個代理在開始工作前需要知道的事實。 這類事實屬於「知識」。
請透過你的簡報（CLAUDE.factory.md，步驟 11「記憶貢獻」）中的知識擷取
協議來記錄：在工作結束時呼叫一次 Memory MCP 的 suggest_lore——\n僅記錄可重複使用的慣例、訣竅、決策與邊界條件，而非每個任務的瑣碎細節。