# Token 命名與元件狀態：補齊步驟

日期：2026-10-20。範圍：token-registry.html、js/token-registry-page.js 及該頁局部共用 CSS。
資料基準：站內 Registry 2026-09-18 UTC 快照，363 筆 Token、12 個元件 collection、28 個元件。

## 本次已完成

- 保留「Token 對照表／Token 治理規範」，新增「元件與狀態對照」。
- HTML 補入命名欄位字典、來源命名差異、狀態分類及待補充執行步驟。
- 元件表讀取 Registry，列出中文名稱、站內 ID、collection、Token 路徑識別字及明示狀態；未登錄 collection 者仍列出。
- 資料筆數與完整性分開呈現；存在 Token 不表示已驗收。
- 辨識 selected-locked、current、box、control、dot、value 等既有路徑。無明示狀態不推定為 default；未知用詞保留原文。
- 增加全部分類、中文與空白分隔多關鍵字搜尋、空結果提示；URL 保留分類、搜尋及頁籤。
- 狀態連結以完整路徑段查找，例如 /selected 不會包含 selected-locked。
- 點選分類時清除舊搜尋與 URL 的 q；搜尋摘要顯示關鍵字，並可使用「清除搜尋」恢復目前分類全部資料。
- Light／Dark 使用 resolvedLightValue／resolvedDarkValue，缺值才回退原始模式欄位；不改動 Registry。現有快照 136 筆 darkValue 與 resolvedDarkValue 不同。
- 顯示型別與可展開的預設 alias 引用鏈；Light／Dark 的模式解析值各自顯示，預設鏈不代表所有模式的引用必定相同。單位不自行補 px。

## 接續執行順序

| 順序 | 負責角色 | 工作與交付 | 狀態 |
| --- | --- | --- | --- |
| 1 | 設計／工程 | 核定 namespace、層級、元件識別字、變體／尺寸、部位、屬性、狀態位置；交付允許詞彙及命名實例。核對治理頁與現行 Figma 檔案來源關係。 | 待補充 |
| 2 | 設計／工程 | 逐元件確認狀態：需要獨立 Token、沿用共用規則、不適用，並寫出理由；先做 Button、Input、Checkbox、Radio。 | 待補充 |
| 3 | 設計 | 核對 Figma 精確節點、Variables／Text Styles、模式與 scope；將核定資料寫入正式來源與 manifest。 | 待補充 |
| 4 | 工程 | 核對 alias、Light／Dark 解析值、單位及實際元件套用；交付 Token → CSS／元件屬性對照。 | 待補充 |
| 5 | 維護者 | 修改正式來源後執行 node scripts/generate-registry.mjs；產生器須將「資料存在」與「完整性驗收」分開，不能僅依筆數宣告完整。 | 待補充 |
| 6 | 設計／工程／維護者 | 比對 Figma、Token 與 Storybook，驗證焦點、選取、停用及深淺色，登錄負責人、版本、日期及證據，再更新完成狀態。 | 待補充 |

人工元件治理資料只在 js/data/component-manifest.js 維護；不手改 js/data/design-system-registry.js。不要為了填滿狀態表而製造 Token 或宣告不適用。

## 優先狀態核對

| 元件 | 驗收要求與目前路徑差異 | 處理方式 | 狀態 |
| --- | --- | --- | --- |
| Button | 驗收要求 focus、loading；目前未明示同名狀態路徑 | 確認共用焦點／載入規則或獨立 Token，保留實例 | 待補充 |
| Input | 驗收要求 filled；目前未明示 filled 路徑 | 確認沿用 default 或獨立視覺差異 | 待補充 |
| Checkbox／Radio | 驗收要求錯誤與鍵盤操作；目前未明示 error、focused 路徑 | 確認焦點與錯誤的來源及 selected-locked 精確語意 | 待補充 |

## 未登錄獨立 collection 的 16 項

下列全部為「待補充：確認共用或獨立 Token 對應」，不是直接判定缺少獨立 Token：

- 頁籤圖標、側邊選單、麵包屑、阻擋頁。
- 下拉選單、日期選單、時間選單。
- 資訊小卡、快速撥號、穿梭框、Loading、提示工具。
- 表單頁籤、表單標題、表單版型、表單按鈕區。

例如 Navigation 內已有 breadcrumb 路徑，需先確認來源歸屬，避免重複建置。

## 後續查找功能

部位／屬性／狀態組合篩選、元件 × 狀態矩陣、複製按鈕仍待補充；先核定適用狀態，才可建立有意義的完整性矩陣。本次已提供搜尋及狀態查找連結。

## 驗證

- JavaScript 語法通過；以真實 Registry 檢查 selected-locked／box、current、未明示狀態與 136 筆模式差異。
- 瀏覽器 1280×720 桌面、390×844 窄版，淺色／深色；窄版文件寬度維持 390px。
- 操作中文多關鍵字、無結果提示、治理與元件頁籤、分類方向鍵、selected 精確連結、預設引用展開及局部鍵盤捲動；selected 查到 Checkbox 4 筆，不包含 selected-locked。
- 元件對照 28 列；方向鍵使窄版表格 scrollLeft 增加至 78px；受測頁面主控台無警告或錯誤。
- 未修改 Figma、Token 正式來源、Registry 產出或 Storybook；未部署。正式工程適用性仍待上述核定。

## 分類切換修正（2026-10-20）

已重現：帶 /selected 從 Checkbox 切至 Button，原本保留搜尋導致 0 筆。修正為點選分類即清除搜尋，包含重新點選目前分類；清除後同步移除 URL q。瀏覽器逐項確認 14 個分類的實際列數與總筆數一致（全部 363、基礎 145、按鈕 36）；已操作無結果、清除搜尋、1280×720 與 390×844 深淺色，主控台無警告錯誤。

## 入門順序與分頁調整（2026-10-20）

通用命名說明移至頁籤上方，依 Token 意義、三層架構、Alias、Collection、Figma／CSS 名稱、欄位與實例閱讀。原「元件與狀態對照」改為「Token元件命名與狀態檢核」，移至第一個分頁且首次開啟預設選取；其後為 Token 對照表、Token 治理規範。保留 #table、#status、#governance 及搜尋／分類深連結；通用說明不在各頁籤重複。已驗證 1280×720、390×844 淺深色、分頁方向鍵及按鈕分類 36 筆；窄版無整頁水平溢出，主控台無警告錯誤。未部署。