# Component Contract Design

> 從規格狀態表、設計畫布或既有程式碼推導元件目錄，逐元件填齊元件契約欄位表（語意、變體、狀態、操作機制、尺寸、內容政策、slot、組合、無障礙、回饋契約、測試、反例），盤點容器元件與排列不變式，產出讓畫面票只需選件與排位的元件庫規格。觸發詞：元件契約、元件庫設計、元件目錄、容器元件、按鈕重疊、文字溢位、拆解設計稿、接手既有元件庫。Do NOT use for token 萃取（用 foundation-design）或畫面級狀態矩陣（用 ux-design-evaluation）。

- Skill: `tarrragon/component-contract-design` (Agent Skill, multi-file: 9 files)
- Install (CLI): `npx skillmds@latest add tarrragon/component-contract-design`
- Raw SKILL.md: https://api.skillmd.com/api/skills/tarrragon/component-contract-design/raw
- Safety review: pending
- Works with: Claude Code, Claude.ai, OpenAI Codex
- Category: Web & Frontend
- License: MIT
- Author: tarrragon (https://skillmd.com/u/tarrragon)
- Updated: 2026-09-10
- Page: https://skillmd.com/skills/tarrragon/component-contract-design

---


# Component Contract Design

把「這個畫面該用什麼元件、文字要不要換行、按鈕排在一起會不會重疊」這類決策，從畫面實作期前移到元件庫規格。產出是一份 L3 元件庫規格（L3 指專案元件庫章節；L1 通用原則、L2 語言／框架實作規範、L3 的分層見元件庫雙向約束方法論〈分層架構〉）：每個元件契約欄位表全部欄位齊全、每個排列關係有容器元件承載，畫面票因此只剩「選件與排位」。

判準的權威在該方法論的〈元件契約判準〉（元件契約欄位表、容器亦為元件、派發語言）；產物形狀在 `doc` skill 的元件庫規格範本。兩者與其餘外部資產的地址見 `references/addresses.md`——該表是權威，消費點就近帶一句路徑不算重複，但不得與表衝突。本 skill 承載的是**程序**：從三種不同起點走到契約齊全，各起點的步驟不同，判準相同。

## 三種起點

先判定起點，再進對應模式。三種模式共用的內容在〈按需讀取〉表的後四列。用詞：**元件目錄**指程式碼中實際存在的元件集合；**元件清單**指規格第 3 章的總表；**元件庫**指統一匯出入口涵蓋的目錄，入口外的任何 widget 檔皆屬頁面層。

| 起點 | 判定訊號 | 模式 |
|------|---------|------|
| 有規格（狀態矩陣、畫面清單），元件庫尚未建 | spec 有逐畫面狀態表（一張全域狀態清單可拆成逐畫面者亦算）；元件目錄為空或只有 scaffold 產生的無呼叫端佔位元件（spec 有無元件清單不影響判定，清單無契約在三種模式都是常態） | A 規格推導 |
| 有設計畫布（artboard、wireframe 的統稱，設計稿為其輸出物；下文簡稱畫布），無規格或規格未到元件層 | 畫布是主要來源；畫面上的視覺單元尚未有語意名（設計工具的自動命名如 Frame 123 視同未命名；設計工具內已有具名元件但無程式碼者仍走 B，具名視為候選名，經語意問句驗證） | B 畫布拆解 |
| 已有元件程式碼與頁面，無契約或契約不全 | 三訊號任一命中即足：元件目錄非空且有呼叫端；頁面直接用原生佈局排列元件；曾發生重疊、截斷、功能補做 | C 程式碼萃取 |

**判錯起點的代價**：這是全程第一個分岔，且錯誤在後續步驟不會自我暴露。該走 C 而走了 A，產出的契約與存量不符、既有的重疊與截斷事故對應不到任何缺件、遷移票整批缺失，而規格本身讀起來完好；發現時已在實作期。A 與 C 之間猶豫時，逐一核對上表 C 列的三訊號（元件目錄非空且有呼叫端／頁面直接用原生佈局／曾發生事故），任一命中即為 C。A 與 B 之間猶豫時，三訊號判不了——改用下段的來源就近原則：有畫布且畫布是主要來源走 B，只有規格走 A。一律不以「哪個來源比較新」替代。

多個訊號同時命中時，以「哪個來源最接近使用者實際看到的畫面」為主，判定不看新舊：有可跑且有頁面呼叫元件的程式碼一律走 C（畫布較新也一樣，畫布上的差異在模式 C 的填契約步驟當作漂移處理），無程式碼有畫布走 B，只有規格走 A。先萃取事實，再對照規格找漂移。三個例外：只有路由殼與佔位元件、頁面尚未呼叫任何元件的專案，模式 C 的呼叫端回收與原生佈局掃描會全空，仍走 A 或 B；已決議整體換版且決策有記錄者，舊碼只供模式 C 的事故對照與呼叫端回收當反例來源，契約值以畫布為準走 B；標記為 spike 且不合入生產的程式碼依方法論的原型豁免不走本 skill，轉正時再走 C。

**前置**：design token 層須已存在（token 指集中定義、程式碼只引用名字的樣式參數；顏色、間距、字級、圓角有具名常數），形態因素矩陣須已定（支援哪些形態的決策表，形態以使用者操作方式界定而非顯示空間：桌機指標加鍵盤、平板觸控、手機單手觸控各為一個形態；位於元件庫規格範本第 1 章；判準見方法論〈形態因素先決〉）。前置缺料的出口一律是建前置票，不在本規格票內補：token 缺走 `foundation-design` skill 的 UI 維度，前置票設為本規格票的 blockedBy；矩陣缺先填範本第 1 章作為提案送簽核（範本的「預設單一形態」是提案值，仍須簽核；支援幾個形態屬用戶簽核，PM 不得自行拍板），簽核未回前尺寸契約、測試契約的「每種尺寸」與操作機制標待決（操作機制同樣依形態而定），其餘欄照填。互動反應規格是第三項輸入而非阻擋條件：未產出時建 `ux-design-evaluation` skill 的 UX 審查票，規格票照跑，只有填契約時的互動反應子節標待決並以該票為元件票的 blockedBy。

**時序**：本 skill 在 `version-bootstrap` skill 地基波的第 3 塊（UX 審查）之後、第 4 塊（元件庫實作）之前執行，互動反應規格是它的輸入。規劃波前段的 L3 章節得先只含元件清單與禁用對照，契約於此時補齊。

**產出檔案**：複製 `doc` skill 的元件庫規格範本（路徑見〈外部資產與跨檔用詞的地址〉）到專案的 spec 目錄，檔名依專案 spec 命名慣例（有編號慣例者用編號，範本檔頭的建議檔名只是預設）。專案已有範本格式的元件庫 spec 者不複製，就地補缺的子節；元件清單散在 design-system spec 或其他 spec 者，新建元件庫 spec 並把原清單改為指向它，清單不雙份維護。

## 按需讀取

前兩列是模式檔，依起點選一為主——三種模式互斥，不會同時走兩條。但模式 C 另需 `modes-a-b.md` 的同型歸併規則與存在必要性檢視（步驟 4、6 各指向一次）。後四列是三種模式共用的檔，依所在步驟另讀，與起點無關。

| 何時讀 | 檔案 | 涵蓋章節 |
|--------|------|---------|
| 起點為「有規格」或「有畫布」，走模式 A / B | `references/modes-a-b.md` | 〈模式 A：規格推導〉〈模式 B：畫布拆解〉 |
| 起點為「已有元件程式碼與頁面」，走模式 C | `references/mode-c.md` | 〈模式 C：程式碼萃取〉 |
| 走到任一模式的「填契約」步驟；或專案支援多個形態；或想看一個填好的元件契約條目 | `references/field-questions.md` | 〈元件契約欄位填寫問句〉〈多形態專案〉〈正例：清單卡的元件契約欄位〉 |
| 要寫任何票（畫面／元件／遷移／決策），或派發前查誰執行誰簽核 | `references/dispatch-language.md` | 〈執行者與簽核者〉〈派發語言〉 |
| 卡住要查症狀處置，或想看三種模式的實例，或想看完整的容器條目／畫面票／歸併判斷正例 | `references/examples-troubleshooting.md` | 〈Examples〉〈正例〉〈Troubleshooting〉 |
| 不確定某件事該由本 skill 還是相鄰資產處理 | `references/adjacent-assets.md` | 〈分工邊界〉 |
| 正文出現簡稱而不知它在哪 | `references/addresses.md` | 〈外部資產與跨檔用詞的地址〉 |

## 契約齊全的定義

一份元件庫規格可被畫面票消費，須同時滿足六條：

- 每個元件契約欄位表全部欄位無空白。**除落成值與附舉證的「不適用」外，任何佔位標記皆視同空白**——待決、待核定、提案、漂移待決、待實作、待接線一律計入，該元件不得被畫面票引用，決策票設為元件票的 blockedBy
- 元件清單總表中每個畫面的每個排列關係都對應到**至少一個**容器元件（一個容器可承載多個排列關係，同一排列關係不得分屬兩個容器）
- 每個容器的排列不變式三項齊全，子件數量無上限者空間不足策略非空
- 每個文字 slot 的最長測試文案是具體字串或 i18n key，不是「長文字」
- 每個元件的無障礙欄有朗讀標籤與焦點路徑，每個有互動的元件在每個形態各有一份操作機制；回饋契約每個事件在每形態各有通道或「不可用 + 替代」
- 本規格票內每個**關機判定**各有一條依據紀錄。關機判定指「判定為某值即關掉一段後續步驟」的任何判定——下列為已知者，不是窮盡清單，新遇到的一律比照辦理：

  | 關機判定 | 紀錄須含 |
  |---------|---------|
  | 起點判定 | 命中的訊號，與另兩起點各自的排除理由 |
  | 形態數 | 簽核人與日期 |
  | 最小適用集 | 方法論最小適用集的命中項 |
  | 零事故 | 查過哪些來源、各自為空 |
  | 空間不足策略「不觸發」 | 代入值與比較結果 |
  | 特徵測試「補不起」 | 覆蓋數字與門檻值 |
  | spike 原型豁免 | 該判定使整個 skill 不適用、本規格票不存在，故紀錄落在做此判定的那張票 |
  | 單一子件包裝不是容器候選 | 被判定的包裝位置 |
  | 原生佈局掃描的三條排除 | 逐處記位置與被判為隔開的那個元件 |
  | 同形態內視窗尺寸差異不是新形態 | 該差異的尺寸範圍 |
  | 方法論豁免三條件 | 命中的是哪一條 |

  關機判定的產物是一句宣告，沒有紀錄則認真做過與完全沒做在票面上無差別

**三條路徑上六條不全部適用，各有替代判準**：

| 路徑 | 哪一條失效 | 替代判準 |
|------|-----------|---------|
| 模式 C（接手既有） | 第 2 條——分母「每個畫面的每個排列關係」無來源，模式 C 步驟 3 的 grep 只掃頁面層原生佈局，已被既有容器承載的排列關係不入表 | 分母改為「步驟 3 掃出的排列關係 + 既有容器已承載者」，後者由步驟 1 的元件盤點取得；兩者聯集才是本條的分母 |
| 形態因素矩陣待簽核（見〈前置〉） | 第 5 條——該路徑允許「每種尺寸」標待決，但操作機制同樣依形態而定，未列入待決清單 | 操作機制一併標待決，第 5 條在簽核回覆前只驗朗讀標籤與焦點路徑 |
| 最小適用集（見〈元件契約欄位填寫問句〉） | 第 1 條與第 5 條——欄位表縮至最小適用集，兩條的投影未定義 | 第 1 條改為「最小適用集內的欄位無空白」；第 5 條不適用（該制仍須填排列不變式，但不要求逐形態操作機制與回饋契約——回饋契約不在最小適用集） |

六條都是存在性檢查，可機械執行：前五條逐一對應為欄位為落成值或合法的「不適用」、每個排列關係有容器、三項非空、文案是字串或 key、朗讀標籤與操作機制非空；第 6 條為本規格票內每個關機判定各有一條非空紀錄。文案放不放得下不在此判定，由測試契約的測試驗證。未齊全的元件不得被畫面票引用；元件票的驗收條件即上列前五項對該元件的投影（第 6 條屬本規格票層級，不逐元件投影）。本節六條是「可被畫面票消費」的判準；spec 票本身的驗收權威是範本第 9 章，六條是其子集。

契約先於實作指「改動先落在契約」，不指契約不可變：實作中發現契約值不成立（策略選錯、尺寸公式不成立）時，先改契約條目再改實作，變更理由記入該元件票的 acceptance 修訂或 spec 變更歷史。

---

版本紀錄在同目錄的 `CHANGELOG.md`。