v0.11.1（tokens 配對版 0.6.0）

三個工作項的合併發佈（守衛基建＋元件無障礙修正＋文件體系雙軌強化）。
tokens 維持 0.6.0——零新 token，不發 npm、不推 tokens tag。

文件體系雙軌強化：AI 取用入口＋貢獻端架構文件＋Storybook 互動 playground

1. 改了什麼：
   • 取用端（人＋AI）：文件站新增 /llms.txt（機器地圖）；AGENTS.md 由
     book/scripts/sync-root-docs.mjs 於 build 前同步上站（/AGENTS.md），並補強內容
     （元件清單指向 /r/index.json 不再寫死數字、五種頁型最小安裝集入口、
     @xyflow/react 大相依提醒、深色切換一行示範、可抄的符合性台帳骨架、
     repo 相對連結全面改絕對 URL）。
   • 貢獻端：新增 ARCHITECTURE.md（系統地圖：資料流、token／registry 管線、
     七支守衛一表、CI 閘門、版號模型、提案門口），同步為治理章「系統架構」頁。
   • Storybook：新增 demo/generate.ts 確定性資料生成器（LCG 播種，不隨套件發佈），
     五支中文 args 互動 playground（資料表、唯讀逐欄編輯、圖表、時間軸、節點畫布）——
     Controls 面板可調資料筆數、狀態比例、極端值，筆數拉到 0 直接驗空狀態；
     storySort 補「特殊介面」分類。
   • 文件 × Storybook：新增 <StoryLink> 深連結元件，元件章 28 頁逐頁掛
     「在 Storybook 開啟」；doc-hooks 守衛擴充為同時驗 StoryFrame 與 StoryLink 的 id，
     引用數下限 0 → 30；demo-data 守衛認可 demo/generate 為合法資料來源；
     de-domain 守衛加掃 ARCHITECTURE.md 與 llms.txt。
2. 我需要做什麼：不需要。全是文件與示範層；元件 API、token、registry 內容零變更
   （registry 只隨例行重建更新戳記）。AI agent 可改用 /llms.txt 當入口。
3. 為什麼改：取用契約此前只存在於 GitHub repo 根，只拿到文件站網址的人與 AI
   讀不到；貢獻端的系統全貌散在四個檔案裡沒有地圖；治理章寫了「互動 playground 用
   中文 arg」的規範卻零實作，Controls 面板一直是空的。這批把三個落差一次補平。

守衛基建：無障礙行為守衛＋視覺回歸（token 期望值掃描）

1. 改了什麼：兩支新守衛進 CI（Storybook 建置後自動跑）。
   verify:storybook 對全部 story 跑 axe 掃描（顏色對比除外——verify:color
   是唯一顏色權威）並驗收 play functions 全數執行；verify:visual 對六主題 ×
   兩模式 × 兩支哨兵 story 截圖掃全圖，驗「期望色存在＋其他主題的 --brand
   不存在」。互動元件補了七支 play functions（對話框焦點陷阱、下拉鍵盤操作、
   資料表排序與篩選、操作回饋宣告、勾選與開關）。開發期同步加 addon-a11y 面板。
2. 我需要做什麼：不需要。這批是驗收基建；元件修正見下一項。
3. 為什麼改：行為層（焦點、鍵盤、aria 連動）此前沒有任何守衛——規範書寫了
   行為規範卻驗不了；配色不符要靠肉眼在 12 種主題組合裡翻。方法論本來就寫在
   治理章（截圖三坑），這次把它從教訓變成閘門。

元件無障礙修正（首次全量掃描的收穫，patch → 0.11.1）

1. 改了什麼：DataTable 每頁筆數下拉補可及名稱、篩選面板補 Esc 關閉
   （原本只能點背景關，鍵盤使用者會被困住）；GraphCanvas 容器 role="img" 改
   role="group"（img 會把可聚焦的節點宣告成純呈現，構成巢狀互動違規）；
   示範頁的 SelectTrigger 全數接上 Label htmlFor——combobox 的可及名稱
   不能取自值文字，這條規則同步寫進 story 慣例。
2. 我需要做什麼：用到 DataTable 自訂 labels 的宿主可加 perPageLabel
   （不加就用預設「每頁筆數」）；其他修正重抄元件即得，無 API 變更。
3. 為什麼改：新守衛第一次全量跑就抓到 8 條真違規——這正是它的存在理由；
   修在元件層，所有取用端一起受益。

---

判斷要不要跟進：跟上新版

v0.11.0（tokens 配對版 0.6.0）

三個工作項的合併發佈（B 段終驗＋兩個 P0＋缺件六件）。
tokens 維持 0.6.0——全部用既有 token，不發 npm、不推 tokens tag。

交接包 B 段終驗：節級比對全數在頁，補上唯一的選用項（純文件）

改了什麼：逐份補充稿做節級比對（8 份、21 個插入節）——全部已在
先前批次落地，B 段實質完成。唯一缺的是 overview 補充稿標為「選用」的
共同約定第 6 條，這次補上：「分類色與狀態語意脫鉤（雙向）」一句＋連到
配色策略判斷樹（正本在 charts 頁，不寫第二份）。
我需要做什麼：不用。
為什麼改：草案當時把這條列為取捨（總覽收齊 vs 保持精簡）；
配色策略判斷樹落地後，這條有了可連結的正本，一句話收齊的成本趨近於零。
至此交接包 22 份草案全部收束，含所有選用項與合併注意事項。

兩個 P0 設計缺口：載入態與欄位錯誤態（規範 v0.11.0，tokens 不變）

改了什麼

覆蓋度清查（交接包 D 段）點名的兩個 P0——「全庫沒有 loading 態」
「全庫沒有 error 態」——它們是設計缺口不是測試缺口，先補 story 只會
補出五種不同的 loading。這批先定規範再落元件：

• 載入態規範〈載入中〉（色彩語意新節）：
  三種手段各有位置——首載＝Skeleton（版面已知不跳動）、
  重查＝就地變暗保留舊內容（已有資料再蓋骨架會閃）、
  提交＝disabled＋圖示＋文案（按鈕沒有 loading 變體的既有立場，銜接不推翻）。
  載入不是狀態語意，一律中性（--muted），不進提醒色彩色家族
• 新增 Skeleton／SkeletonText；DataTable 加 loading：
  首載渲染骨架列（列數＝每頁筆數、上限 15），已有資料就地變暗＋aria-busy；
  讀屏出口由容器宣告一次（role="status"），骨架塊 aria-hidden
• 新增 FormField／FieldError：「Label＋aria-describedby＋aria-invalid＋
  錯誤小字」的固定寫法元件化，id 連動自動接好；錯誤三重編碼（色＋圖示＋文字）；
  與區塊層 Callout 彙總是分工不是取代
• 修掉一個真實的深色違規：先前錯誤欄整格染 --danger-subtle，
  深色下 danger 邊框對那個底只有 2.42:1（低於 1.4.11 的 3:1）。
  修法不是放寬門檻也不是動全域淡底（會破壞染色量等量），而是不整格染紅——
  錯誤主訊號是邊框＋文字＋圖示，整格紅底還會吃掉高飽和面積預算
  （十個錯誤欄＝十塊紅底）。欄位狀態三層表同步修正
• verify:color 新門檻：danger 邊框對兩種欄位底（background／--field-editable）
  兩模式都 ≥3:1——這條第一次跑就抓到上述違規，反向驗證過
• 第一支 play function：FormField 的 aria 連動（aria-invalid／describedby
  指向存在的錯誤節點／無錯誤欄不得帶 invalid）——樣式看起來都對、
  讀屏卻接不到訊息，正是改版時最容易安靜壞掉的部分
• 缺件表劃掉 Skeleton 與 Form 兩列（missing-piece.yml 同步，表下補「畢業」紀錄）；
  文件八處同步（05-input 錯誤態節＋活範例、13-data-table 載入節、16-empty-state
  「載入中不是空」、01-button 連結、提醒色辭典同框表加錯誤行、表單頁改用 FormField）

我需要做什麼：

想用的專案：npx shadcn add …/r/skeleton.json／…/r/form-field.json。
已在用 aria-invalid 樣式鉤子的：錯誤欄不再整格染紅（深色違規修正）——
重抄 Input／Select 兩支，或自行拿掉 aria-[invalid=true]:bg-danger-subtle。
其餘零影響；DataTable 的 loading 是新增 prop，不傳＝現況。

為什麼改：

載入與錯誤是後台系統每一頁都會遇到的兩種狀態，卻是全庫唯二沒有規範的——
每個畫面自己發明的結果就是五種 loading、三種錯誤標法。規範先行
（決策表＋反例），元件只是把規範變成預設值；深色違規的修正順帶證明了
「新增守衛必須反向驗證」之外的另一半：新守衛第一次跑就該對著現況跑，
它抓到的每一條都是已經存在的問題。

缺件表六件收錄：Toast、Switch、Textarea、RadioGroup、Skeleton、DateRange（規範 v0.11.0，tokens 不變）

改了什麼

• 頁面章缺件表的前六列全數收錄，替代方案功成身退；表與認領模板同步刪除六個選項
• Toast 操作回饋（27-toast）：「操作回饋的去向全站固定一種」
  自此有載體，規則成文——右下、堆疊上限 3、success/info/warning 5 秒自動消失
  （hover/聚焦暫停）、danger 一律手動關閉、讀屏 status/alert 分級、z-[70]；
  表單驗證錯誤不進 Toast（貼欄位）。淡底表面與 Callout 共用同一份
  STATUS_SUBTLE_SURFACE（同一份事實只寫一次）
• Switch：切了立即生效；與 Checkbox 的分工成文（送出才生效用 Checkbox），
  因此刻意無「已改動未送出」琥珀態
• Textarea：逐項鏡射 Input（邊框/聚焦環/aria-invalid/停用）；只准直向調整大小
• RadioGroup：垂直、每項可帶說明；選中填實心點不只靠顏色；
  文件附單選四載體分工表（SegGroup/RadioGroup/Select/EditableField）
• Skeleton：保留真實版面形狀、只用於首載、aria-hidden＋容器 aria-busy、
  尊重 prefers-reduced-motion
• DateRange 期間選擇 v1：檔位一等公民（今日/近 7 日/近 30 日/本月）＋自訂起訖；
  反序自動修正；刻意不做日曆格（檔位＋原生 date 輸入涵蓋主要場景，
  視覺化日曆等三次法則證據）
• 順帶兩個既有小修：Stepper 步驟按鈕補標準聚焦環四件組（先前走瀏覽器預設）；
  Storybook 步驟指示 story 的 completed 死 key 修正

我需要做什麼

要用就抄：npx shadcn add <站台>/r/{toast,switch,textarea,radio-group,skeleton,date-range}.json。
Switch/RadioGroup 會自動帶入兩個新的 radix 相依。tokens 維持 0.6.0——
六件全部使用既有 token，npm 端零動作。已在用替代方案的畫面不必立刻改，
但新畫面請直接用正式件；操作回饋請照 Toast 頁的全站規則收斂。

為什麼改

頁面章成文時盤出九個缺件，其中六件已有多頁場景反覆出現（表單頁/設定頁/
清單頁/儀表板都指向同幾件）——三次法則的證據在成表當下就湊齊了。
一次收錄讓「先用替代方案」的過渡期最短，也讓認領表單聚焦在真正未定案的三件。

---

判斷要不要跟進：跟上新版

v0.10.0（tokens 配對版 0.6.0）

兩個工作項（圖表配色策略＋文件站成為第一個驗收宿主）。
tokens 維持 0.6.0——只引用既有 token，不發 npm、不推 tokens tag。

圖表配色策略：資料形態前置分支＋三層判斷樹（規範 v0.10.0，tokens 不變）

改了什麼

• Charts 圖表的〈色票〉重構為〈配色策略〉：
  一棵判斷樹成為單一入口——連續數值先分 Sequential（單色相染色量，Heatmap 現況
  命名成規則）／Diverging（danger-subtle ← muted → success-subtle，語意色相淡階、
  中性中點、對稱值域；只寫構造規則不寫 helper，三次法則）；離散類別走三層：
  語意 → 身分 → 區辨
• 新增兩個配色工具（charts/base.tsx，隨 charts registry item 散佈）：
  • STATUS_SERIES／STATUS_SERIES_STRONG：語意維度的現成色表——狀態組成
    堆疊圖從此有「回家的路」，與 Badge 同一套語意、同一條強度語法
    （預設淡底，實色只給線與點）
  • colorByKey(key, keys)：以宿主宣告一次的固定鍵清單決定色索引——
    「顏色跟實體走，不跟排序走」的機制化；超出封頂或找不到的鍵退 muted
• Storybook 新增「語意維度的堆疊」story（正誤並列）：同一份狀態資料，
  STATUS_SERIES 版與徽章同語意，PALETTE 版「已完成」變藍與徽章打架
• 新增守衛：STATUS_SERIES 的鍵必須是提醒色辭典的合法語意、值必須引用
  對應 token——反向驗證過（塞 PALETTE 值會紅並指名語意錯置）
• 01-color〈分類色票與狀態語意脫鉤〉補上
  雙向敘述（維度是狀態時必須沿用狀態色）；
  提醒色辭典連到判斷樹

我需要做什麼：

已抄走 charts 的專案想用新工具就重抄一次 base.tsx；不用的話零影響。
畫圖前照判斷樹走一次——特別是狀態組成的堆疊圖：維度是狀態就用
STATUS_SERIES，不要照序取 PALETTE。

為什麼改：

使用者要求「系統整體用色有一套語意邏輯傳達，讓使用者長期使用可以快速透過顏色
了解系統傳達語意，而不是單純五顏六色」。UX 分析發現生成與守衛層已完備，
缺的是語意記憶的機制——三個洞：「顏色跟實體走」只有文件一句話沒有工具
（最自然的寫法恰好違反它）；語意維度的圖表沒有肯定式規則與現成色表
（徽章教的「已完成＝綠」會被堆疊圖的隨機分類色拆掉）；「這張圖用哪套色」
散在三頁文件五個段落、沒有單一判斷入口。

經色彩顧問方法論會診補上三條紀律：連續數值不套分類色盤（Sequential／Diverging
前置分支）；狀態色進圖表用淡底（提醒視窗與圖表重點色共用同一份高飽和
面積預算）；超過封頂或要強調走 highlight＋mute（capItems 彙總、
selectedIndex 淡化），永不加色相；同類次要用同色相降階。

系統的色彩語法自此閉環：紅＝有問題、綠＝完成、琥珀＝改了未送出、藍＝中性訊息、
分類彩色＝身分、中性＝焦點與動作、主題色相＝識別——從徽章、提示框、欄位到圖表，
同一個顏色永遠回答同一個問題。

文件站成為第一個驗收宿主：站台 chrome 橋接 token、嵌入跟主題

改了什麼

• Infima → token 橋接（book/src/css/custom.css）：站台的主色六階、頁面底、
  navbar／card／footer、邊框、程式碼底、字體全部改為引用 token
  （hsl(var(--x))），原本兩段手寫 hex 副本整組刪除。只寫一次 :root——
  token 自己在 [data-theme="dark"] 下翻值，橋接引用自動跟著翻
• StoryFrame 把文件站的明暗傳進 iframe（&globals=theme:dark，
  對建置產物實測過語法）；色相主題刻意不傳——兩邊預設都是石墨，本來就一致
• 修掉 StoryFrame 註解裡「守衛還沒寫」的過期敘述（doc-hooks 已在）

我需要做什麼：不用。純文件站變更，token 與元件零改動。

為什麼改：

v0.9.0 合併後使用者回報「文件和 Storybook 元件配色有些不符合」。查出兩個根因，
共同點是文件站沒有把自己當成宿主：

1. iframe 是獨立 document：文件站切深色動的是自己的 <html>，
   Storybook 嵌入永遠停在預設淺色。respectPrefersColorScheme: true 讓
   OS 深色的使用者一進站就深色——24／25 兩頁整頁亮色 iframe，
   23-charts 同一頁上活範例（跟深色）與嵌入（不跟）並排成兩種配色
2. 站台表面不是 token 表面：Storybook canvas 是 bg-background
   （深色 222 22% 8%），文件站是 Infima 的 #1b1b1d——元件裡吃
   --background 的部份（outline 按鈕、Gantt 未完成段遮罩）在深色頁上
   是一塊塊色差補丁。而 custom.css 那兩段 hex 本身就是 token primary 的
   手寫副本——漂移防護第 6 支點名要消滅的東西

定調（使用者）：文件庫應該等同於第一個驗收設計版本的宿主。
修法因此不是把示範容器補個底色，而是站台 chrome 直接消費 token——
與 GraphCanvas 橋接 --xy-* 同一個手法。hover 色階用 color-mix 從
primary 衍生而非複寫：primary 換值時它們自動跟上，不產生新副本。

實測數字：深色下頁面 html 底與 iframe 內部底同為 rgb(16, 19, 25)
（token --background 深色值），逐位元同色；淺色連結 #0f172a ≈ 原硬編
#1e293b，視覺回歸幾乎無感。