tarrragon 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。