元件庫雙向約束方法論 - 設計端與工程端的雙向契約
核心概念
元件庫是設計端與工程端之間的雙向約束：設計端從元件庫拼組頁面（先設計元件，再組合為複合元件與整體空間配置），工程端只從元件庫取件（禁止散落自製元件）。Design token（顏色、尺寸、間距）只是參數共識；元件庫才是成果約束——相同行為有相同反應、相同外觀承載相同語意，頁面體現一致的產品風格，使用者看到相同元件即能理解功能，減少引導需求。
規範文件本身無法約束成果：AI agent 無跨 session 記憶，散落自製元件是「只靠文件約束」的高度可重現結果（agent 每 session 冷啟動，文件遵循率隨 context 壓力衰減）（實證：某 Flutter 專案 token 層收斂後，presentation 層仍累積約百處原生元件直用與 43 處手工邊框（權威清點以各專案 spec 禁用對照表的存量統計欄位為準，無此欄位者先補）；共用同一 design token 系統的 Chrome Extension 端更甚——HTML/CSS 無原生元件邊界，任意標籤加樣式即可成件，內嵌 CSS 規則與 design-system 外樣式宣告散落速度更快）。約束必須由「SPEC 階段元件庫先行 + 流程閘門 + 工具執法」三者共同承載。宿主技術的自由度越高（HTML/CSS > 元件類別框架），雙向約束越必要。
本方法論與具體 UI 框架無關，適用於 Flutter、Web 框架（React / Vue）、Tauri、Python GUI 等任何元件化 GUI 開發。判準以三層承載：L1 通用原則（本方法論）、L2 語言/框架實作規範、L3 專案元件庫章節，定義見〈分層架構〉。適用時機：新專案或新 UI 框架導入（見執行步驟）、UI 類提案的 SPEC 階段（見流程整合點）、存量元件治理與遷移。
術語速查：design token＝集中管理的樣式參數；variant＝同一元件的預設變化形；RWD 斷點＝依畫面寬度切換版型的門檻值；rebuild / re-render＝框架重新繪製元件的動作。
雙向約束判準
設計端（樣式的定義者）
| 判準 | 內容 |
|---|---|
| 元件先行 | 設計新頁面前，先確認所需元件在元件庫存在；缺件先補元件定義，再設計頁面 |
| 從元件拼組 | 頁面 = 元件庫元件的組合 + 空間配置；頁面級一次性樣式視為設計債（發現即建 ticket 追蹤） |
| 樣式收斂 | 同一語意只有一種外觀；避免過於多樣化的設計，頁面須體現一致的產品風格。語意是否相同以元件語意標註為比對基準，標註缺漏時先補標註 |
| 元件語意標註 | 每個元件標註設計意義：何時使用、何時不使用、對應的使用者心智模型 |
工程端（樣式的使用者）
| 判準 | 內容 |
|---|---|
| 禁自製元件 | 實作只從元件庫取件；元件庫缺件時停下補元件（走元件票——補元件定義與實作的獨立 ticket，設為原設計/實作票的 blockedBy 前置），不就地自刻 |
| 依語意選件 | 依語意選擇變體（確認操作用 confirm 變體），不依外觀湊件 |
| 商業邏輯註記 | 工程端補上元件的業務邏輯與注意事項：何種資料狀態對應何種元件狀態、邊界條件 |
| 狀態綁定一致 | 元件狀態變更遵循 L2 規範選定的狀態管理模式；禁混用指同一類共享狀態使用多種模式，元件內部暫態（區域 state）與全域 store 並存屬正常分層，不在禁列 |
命名與通用元件判準
命名是存在必要性的檢視工具：命不出目的的元件，多半可由通用元件取代。
| 判準 | 內容 |
|---|---|
| 命名體現目的 | 元件名承載設計目的（如 ConfirmDialog、RiskBadge）；無法命名出目的即為「此元件是否該獨立存在」的警訊。本判準僅適用特化元件；通用前綴元件的目的即「涵蓋無特殊語意的預設場景」，免受此檢視 |
| 通用前綴為預設 | 無特殊目的的通用元件以統一前綴標示（common / App 等，依專案約定），語意為「預設選用這個」；工程端選件順序：先通用元件，有明確設計目的才選特化元件 |
| 存在必要性檢視 | 新元件提案先問「能否以通用元件 + variant / 參數達成？」能 → 不建特化元件 |
| 通用元件可擴充性 | 通用元件以 variant 標籤（預設數種，數量定於 L2；有語意時優先語意名）+ 參數微調涵蓋變化；每遇新情況就得新建特化元件，即為通用元件 API 設計不足的訊號，應先擴充通用元件 |
驗收點：新元件的命名與存在必要性檢視，綁定元件票驗收條件，由 PM 驗收。
元件文字歸屬（i18n-first）
元件庫 text-agnostic 是 i18n-ready 的結構保證：多語系決策可延後，結構成本先付清——元件不綁文字，日後導入多語系只動呼叫端與資源檔，元件庫零改動；反之，寫死文字的改造成本隨元件採用面積單調上升，「開發到一定程度才決定支援多語系」的高成本大頭正是散落元件內的寫死文字。
| 層 | 規則 |
|---|---|
| 使用者可見文字 | 禁止字面寫死於元件；文字由呼叫端經參數 / slot 傳入，呼叫端從 i18n 系統取值 |
| 強語意預設文案 | confirm / cancel 類按鈕標籤、載入預設提示、無障礙標籤，得由元件引用 i18n key 作預設值，三條件 AND：走 i18n 系統非字面、參數可覆蓋、key 列入元件 API 契約（多端共用時進跨平台命名契約，防雙端預設文案漂移） |
| 非語意排版字元 | 省略號、分隔點、數字格式符號不屬文案，可內嵌 |
違反成本：元件寫死文字使「相同行為相同反應」在語言維度破功——同一元件在不同呼叫點切換語言時行為不一致。
形態因素先決（Form Factor）
元件庫設計前先定形態因素矩陣；其結論決定元件庫結構（單一響應式元件庫，或分版型雙軌 builder + 獨立元件設計）。
| 維度 | 決策問題 |
|---|---|
| 裝置光譜 | 手機 / 平板 / 桌面 / 摺疊機，各自是否為正式支援目標？ |
| 方向支援 | 直持 / 橫持是否皆支援？版型差異大到需獨立版面建構層（builder，各版型各自一套組版邏輯）與獨立元件設計，或以響應式單一元件涵蓋？ |
| 特殊表面 | 桌面 widget、懸浮視窗、畫中畫等系統表面是否需要？其尺寸約束是否需獨立元件變體？ |
| 斷點策略 | RWD 斷點由 design token 統一定義，禁止元件各自硬編碼斷點 |
矩陣為最小集，L3 得依產品增列維度（如輸入模態：觸控 / 指標 / 鍵盤的 hover 態與命中區尺寸；文字縮放適應：a11y 動態字級下元件是否須彈性高度）。
判準：形態因素矩陣記錄於 L3 元件庫章節開頭（欄位＝維度、結論、理由）。版型拆分（雙 builder）約等於元件庫雙軌的長期維護成本，屬用戶簽核決策——PM 不得自行拍板，須提供兩案成本對比後提請專案擁有者批准，須於 SPEC 階段決定並記錄；未明文即預設單一響應式元件庫。
豁免三條件（AND，全滿足才可豁免直用）
- 結構性無法收斂：第三方套件內部元件、測試斷言、效能豁免（元件組合無法達標的手工優化，須附 profiler 證據）、非視覺輔助結構件（無障礙包裝層），或一次性且不可重用的刻意破格（如行銷 campaign 頁，須限定表面範圍清單）。可重用的「元件庫缺件」不得引用本條件——缺件的指定路徑是元件票（見工程端判準），不是豁免
- 記錄理由：每筆豁免寫「路徑 + 具體理由」，禁無 trigger 的「暫時豁免」
- 列入工具白名單：豁免項登記於執法工具白名單，使工具與文件一致
豁免核可與權威源：豁免由 PM 於票驗收時核可，禁止實作端自行滿足三條件即視為豁免生效；L3 豁免清單為單一權威來源，執法工具白名單由其生成或定期比對。
原型豁免：標記為 spike / 實驗性且不合入生產路徑的程式碼，豁免禁自製判準；轉正（合入生產）閘門要求全數替換為元件庫元件或走元件票，轉正前其直用計數不納入版本驗收。
分層架構
| 層 | 載體 | 內容 |
|---|---|---|
| L1 通用原則 | 本方法論 | 雙向約束判準、命名與通用元件判準、形態因素先決、豁免三條件、流程整合點；與 UI 框架無關 |
| L2 語言/框架實作規範 | 框架 references/ 或專案 spec | 元件目錄結構、狀態綁定模式、最小重繪邊界、效能預算、測試斷言規範、執法工具偵測規則 |
| L3 專案元件庫章節 | 專案 spec 文件 | 元件清單、原生元件禁用對照表、豁免清單、跨平台命名契約 |
最小適用集：單端小型專案得裁剪為「token 層 + 禁自製 + 豁免清單」三件底線；跨端契約與形態因素矩陣依端數 / 表面數啟用，執法依執行步驟 6 的生態降級梯度調整。
L2 狀態綁定判準
狀態綁定模式必須在元件庫設計時決定，不留給實作時各自選擇。理由：綁定模式決定三件事——
| 決定項 | 說明 |
|---|---|
| 元件 API 形狀 | 傳值（值 + callback）或傳可觀察物件（observable / notifier / signal）。此二分屬框架相依決策軸，L2 得以該框架實際慣例改寫（如 React 以區域 state / 提升 / context / 外部 store 分層） |
| 最小重繪範圍 | rebuild / re-render 邊界落在元件內或元件外。手動邊界框架（Flutter、React）須於 L2 明文邊界標準寫法；自動依賴追蹤框架（Vue / Solid / Svelte）由框架承載，L2 僅需高頻場景檢核 |
| 效能預算 | 高頻場景（長列表每格、動畫、即時輸入）的效能檢核方式（如 Profiler 抽查），於元件設計時評估而非上線後補救；量化上限為選配 |
L2 規範須明文：本專案選定的狀態管理方案、元件接收狀態的標準形式、重繪邊界的標準寫法（自動依賴追蹤框架免列，僅列高頻檢核）、高頻場景的效能檢核方式。
Web/HTML 端 L2 特別判準
HTML/CSS 缺乏原生元件邊界，元件化必須由約定補足。本節屬跨框架 L2 元判準，Web 端專案的 L2 規範須涵蓋下列三項：
| 判準 | 內容 |
|---|---|
| 封裝強制 | 元件一律以工廠函式或框架元件封裝（createButton / createCard 等）；禁止裸 HTML 標籤 + inline style 直接成件 |
| CSS 收斂 | 樣式宣告收斂於 design-system；token 化配置的 utility 系統（如以 token 生成的 utility class 設定檔）與受 design-system 約束的 CSS-in-JS 屬收斂範圍內，禁的是繞過 token 的裸樣式值與頁面內嵌散落 CSS 規則 |
| variant 命名 | 工廠參數用語意 variant 名（primary / confirm / danger），與 token 對映，禁以外觀值傳參 |
多端共用 design-system 的跨端契約
同一 design token 系統被多端使用（如原生 App + Web Extension）時：
| 判準 | 內容 |
|---|---|
| 命名契約 | L3 元件庫章節須含跨平台對照表（元件語意名、variant、size、引用 token 的各端對映），指定單一權威端（權威端於 L3 對照表明文） |
| 契約變更同步 | 任一端變更元件命名或語意即為契約變更：契約版本標記於 L3 對照表（contract-version 欄位）；跨 repo 通知走既有追蹤機制（上游框架 repo 的 issue 或對方專案 ticket，雙方票面互相引用） |
| 差異分級 | 實作層差異（響應式單位 vs 固定 px）不屬契約；語意名與 token 引用屬契約 |
流程整合點
| 階段 | 閘門 | 執法載體 |
|---|---|---|
| SPEC 階段 | UI 類提案必須先有 design token 層 + 元件庫章節（L3），才能開 UI 實作票 | 版本規劃流程 checklist |
| 功能設計階段 | 介面設計只引用元件庫元件名；缺件先開元件票再繼續設計 | 設計職責條款 |
| 實作階段 | 禁止直接建構被元件庫涵蓋的原生元件 | hook / lint 靜態偵測：先警告模式（hook WARNING / lint warn）觀察誤報率，升為阻擋（hook deny / lint error）由 PM 依誤報率實證提請用戶簽核（觀察期與閾值量化值定於 L2 規範）；無現成偵測生態時依執行步驟 6 降級 |
| 版本驗收 | 原生元件直用計數為 0（豁免清單除外），計數來源＝執法工具掃描報告 | 發布前健康檢查 |
執行步驟（新專案或新 UI 框架導入）
- 定形態因素矩陣（裝置光譜 / 方向支援 / 特殊表面 / 斷點策略），決定單一響應式或分版型雙軌
- 建立 design token 層：顏色、間距、字體、圓角、陰影參數集中管理（載體依生態：Flutter 常數類、Web CSS 變數 / utility 設定檔、Qt QSS + 常數模組、Tkinter style 常數模組）
- 選定狀態綁定模式並寫入 L2 規範（含最小重繪邊界與效能檢核約定）
- 依 UC / spec 頁面清單盤點建立首批元件（按鈕、卡片、對話框、分隔、輸入、標籤為常見基本集），每個元件的設計語意標註與工程註記記入 L3 元件清單條目
- 在 spec 建立 L3 元件庫章節：元件清單 + 禁用對照表 + 豁免清單
- 建立工具執法：偵測直用（注意 naive 比對誤報——自製元件命名、theme 設定類、helper 方法常與原生元件共用字根，須用 word-boundary 與排除規則）。依生態成熟度調整：無現成 hook / lint 機制的生態（如 Python GUI）可自寫 AST / grep 掃描（原生元件字根可偵測），最低降級為 PR checklist + 定期人工清點；降級時版本驗收的計數來源同步改為人工清點記錄
- 存量遷移按 feature 目錄拆票並行（互不相依、單票檔案數受認知負擔閾值約束）
檢查清單
- UI 實作票開立前，design token 層 + L3 元件庫章節已存在？
- 設計產出只引用元件庫元件，缺件已開元件票？
- 實作無元件庫已涵蓋的原生元件直用，豁免有記錄理由並列白名單？
- 元件狀態綁定遵循 L2 規範選定的模式，同類共享狀態未混用？
- 新元件有設計語意標註 + 工程商業邏輯註記？
- 高頻場景元件的重繪成本已於設計時評估？
- 新元件命名體現設計目的，或已確認通用元件 + variant / 參數無法涵蓋？
- 元件庫元件無字面寫死的使用者可見文字，預設文案走 i18n key 且參數可覆蓋？
- 形態因素矩陣已於 SPEC 階段明文（含版型是否拆分的決策）？
- 禁令由工具執法承載，而非僅文件提醒？
Reference
.claude/rules/core/opinionated-default-design.md- 禁令由工具預設行為承載.claude/methodologies/knowledge-carrier-allocation-methodology.md- L1/L2/L3 載體分配依據.claude/rules/core/cognitive-load.md- 存量遷移拆票閾值.claude/skills/ticket/SKILL.md- 元件票開立與 blockedBy 設定- 各專案 spec 的元件庫章節（L3 實例）
Last Updated: 2026-07-09 Version: 1.6.0 - 新增「元件文字歸屬（i18n-first）」三層判準（使用者可見文字禁寫死 / 強語意預設文案走 i18n key 三條件 / 非語意排版字元可內嵌）：text-agnostic 元件庫是 i18n-ready 的結構保證，多語系決策可延後而結構成本先付清；檢查清單同步補項（用戶理念補充） Version: 1.5.0 - 多輪審查 R3 修正（steelman + outbound frame）：豁免體系邊界補齊（條件 1 限縮「可重用缺件不得引用豁免」消循環、原型豁免＋轉正閘門、效能豁免/非視覺輔助件/刻意破格子句）；命名判準排除通用元件消自我矛盾；「必然結果」降為高度可重現觀察＋機制論證；形態因素標最小集＋增列維度例；最小適用集規模裁剪條款；variant 數量定於 L2 Version: 1.4.0 - 多輪審查 R2 修正 17 項（冷讀零脈絡 + 跨框架 persona frame）：核心概念補三層路由/適用時機/術語速查；builder、元件票、用戶簽核、升為阻擋等行話內聯定義；跨框架適用性四處變異註記（重繪邊界依手動/自動追蹤分流、禁混用界定同類共享狀態、CSS 收斂涵納 token 化 utility 與 CSS-in-JS、執法依生態成熟度降級）；決策軸標框架相依；效能上限改選配 Version: 1.3.0 - 多輪審查 R1 修正 15 項（fact-check + downstream-task frame）：三個關鍵決策補簽核者（豁免核可＝PM 驗收、升 deny＝用戶簽核、版型拆分＝用戶簽核）；載體明定（形態因素矩陣、契約版本標記、元件定義記入 L3）；接線缺口（元件票 blockedBy、計數來源、設計債建票、語意比對基準）；「120 處」改「約百處＋權威清點指路」；L1 枚舉補齊；Web 端節改 L2 元判準框架 Version: 1.2.0 - 補「命名與通用元件判準」（命名體現目的＝存在必要性檢視、通用前綴預設、variant + 參數擴充防特化增生）與「形態因素先決」（裝置光譜/方向支援/特殊表面/斷點策略，版型拆分屬 SPEC 階段決策）；執行步驟前置形態因素為步驟 1 Version: 1.1.0 - 補 Web/HTML 端 L2 特別判準（封裝強制/CSS 收斂/variant 命名）與多端共用 design-system 跨端契約（用戶補充：HTML 無原生元件邊界，散落更快、更需規範） Version: 1.0.0 - 初始建立：雙向約束判準（設計端/工程端/豁免三條件）、L1/L2/L3 分層、狀態綁定與最小重繪判準、流程整合點