@qijenchen/design-system 0.1.0-beta.61 → 0.1.0-beta.63

package/src/components/DataTable/data-table.spec.md

@@ -29,9 +29,9 @@ TanStack Table 負責邏輯，DataTable 負責視覺與互動。
 
 **Layout Family**：非上述 family — composite / multi-section（多區塊組合，自 own layout）。
 
-### 檔案結構(2026-05-03 split matrix)
+### 檔案結構
 
-12 file,每個過 M21 / M17 / Rule-of-3 三 test:`data-table.tsx`(主,foundational)/ `data-table-filter-panel.tsx` + `data-table-sort-manager.tsx`(panel state 隔離)/ `column-types.ts` + `filter-operators.ts`(✓ Rule-of-3 SSOT,3+ consumer)/ `filter-tree.ts`(pure data + eval,test isolation)/ `lib/column-meta.ts`(Internal SSOT,消 5 處 `(col as any)`)+ stories/spec/css。**M21 retract**:`filter-value-picker.tsx` 1 consumer → 已 inline 回 panel。
+檔案拆分架構(12 file split matrix)與工程決策史屬 code home — 詳 `data-table.tsx` 檔頭 docblock(2026-06-11 遷移,Level 4;spec 只管設計語言)。
 
 ---
 
@@ -64,7 +64,7 @@ TanStack Table 負責邏輯，DataTable 負責視覺與互動。
 |------|------|------|
 | **L1 基礎結構** | 骨架、尺寸、border、色彩、高度模式、行高模式 | ✅ 完成(本文件 L1 段)|
 | **L2 選取** | row selection、checkbox、單/多選、bulk action 整合 | ✅ 完成(本文件 L2 段)|
-| **L3 欄位互動** | 排序(本文件 L3)、resize、reorder、pin、顯示隱藏 | ✅ 完成(sort + resize + reorder + pin + visibility 全 props 支援:`enableColumnResize` / `enableColumnReorder` / `columnVisibility` / `pinnedLeftColumns` / `pinnedRightColumns`,見 data-table.tsx L87-88,143,201,217)|
+| **L3 欄位互動** | 排序(本文件 L3)、resize、reorder、pin、顯示隱藏 | ✅ 完成(sort + resize + reorder + pin + visibility 全 props 支援:`enableColumnResize` / `enableColumnReorder` / `columnVisibility` / `pinnedLeftColumns` / `pinnedRightColumns`,見 `data-table.tsx` `DataTableProps` 宣告)|
 | **L4 資料操作 + Cell 能力** | 進階篩選(本文件 L4 Filter)、inline edit、nested rows、row drag(本文件 L4 段)| ✅ Filter / Inline edit / Nested rows / Row drag v3 完成(Jira canonical + virtualization fix) |
 | **L5 進階** | 分組、搜尋、tree data v2 enhancements、export CSV/Excel | 待 v2 |
 
@@ -105,17 +105,17 @@ Table 分三層:
 
 完整 class / overflow 規則見 `data-table.tsx`。
 
-**Header 在 scroll 容器外面。** 不用 CSS sticky——header 結構性地在 body 上方，永遠固定在頂部。Header bg 用 `neutral-2-opaque`（不透明），不受底層色影響。
+**Header 在 scroll 容器外面。** 不用 CSS sticky——header 結構性地在 body 上方，永遠固定在頂部。Header bg 用 `--muted`（code `HEADER_BG = 'bg-muted'`,比 surface 深一階,同 anatomy ColorMatrix）。
 
 **三個 region 共享垂直捲動。** body-viewport 是唯一的垂直 scroll container，三個 body region 是它的 flex children。垂直捲動天然同步，不需 JS。
 
-**只有 center 水平捲動。** center-body `overflow-x: auto`。center-header `overflow: hidden`，用 JS sync：`centerBody.scrollLeft → centerHeader.scrollLeft`。
+**只有 center 水平捲動。** center-body 是唯一的水平 scroll container,center-header 跟隨其捲動位置同步（同步機制見「捲軸」段 + `data-table.tsx`）。
 
-**Left / right 不水平捲動。** `overflow: hidden`。Frozen 邊界用 `border-divider`（全高度）。
+**Left / right 不水平捲動。** Frozen 邊界用 `border-divider`（全高度）。
 
 **固定行高確保跨 region 對齊。** 所有 row 用 `h-table-row-{size}`，三個 region 的 row 精確同高。
 
-**Header/body region 寬度同步。** Header region 寬度由內容決定（columns + actions），body region 用 ResizeObserver 量測 header 寬度並同步。
+**Header/body region 寬度同步。** Header region 寬度由內容決定（columns + actions），body region 量測 header 寬度同步（機制見 `data-table.tsx`）。
 
 ### 四、行高模式
 
@@ -173,10 +173,12 @@ Row actions 欄本質上是 frozen right column，左邊界也使用 full-height
 | Case | Story | Avg / p95 / long-task | Gate |
 |---|---|---|---|
 | A Plain virt | `VirtualScroll` | ≤16.67/≤33/0 | hard |
-| B Rich budget | `RoadmapPerfBudget`(500×13 rich+inline-edit,fixed 600px) | ≤50/≤80/≤1 | hard |
+| B Rich budget | `RoadmapPerfBudget`(500×13 rich+inline-edit,fixed 600px;2026-05-17 整併誤 retire → 2026-06-12 R2 重建,gate 恢復可跑) | ≤50/≤80/≤1 | hard |
 | C Row drag | `RowDragWithVirtualization` | ≤33/≤50/longest<100 | soft(DnD thermal) |
 | D Edit isolation | `<Profiler>` TBD | skip ≥ visible−active | hard |
 
+**2026-06-12 重建後實測**(static build,3 runs/case):1x CPU — A 16.56/16.8/0、B 24.0/33.4/0、C 16.67/16.8/0 全過 gate;script 預設 4x throttle 在有背景負載機器上全 case 一致 ~2.3x 超標(含未動過的對照組 A)→ 本表門檻實證對應 1x/閒置條件,4x 門檻是否重校 = user 決策(本表數字不動)。
+
 **Anti-pattern**:`RoadmapAllInOne`(全 features stack)≈117ms 不達 B,因 SortableRowProvider/column reorder/resize/selection/overlay 同時開。Consumer:13+ cols rich-cell → 拆 detail drawer / column visibility 預設 hide,不該期 60fps + 全 feature stack。Cite + Phase 1/2 history → `cell-registry.tsx:480-499` JSDoc + commits log。
 
 ### 七、Column Type
@@ -446,7 +448,7 @@ Row drag + column reorder + TreeView 共用 `lib/drag-visual.ts`:source `opacity
 
 `enableRowDrag?: boolean` + `onRowReorder?: (sourceId, targetId, 'before' | 'after')`。Library:@dnd-kit/core(v15.0 Path B 用 `useDraggable` + `useDroppable`,不用 `@dnd-kit/sortable`)。**必填 `getRowId`**(否則 dnd 用 row.index reorder 後錯位)。
 
-- **Handle**:`<Button variant="tertiary" iconOnly size="xs" startIcon={GripVertical} />` 24px chip,所有 state(idle / hover / aria-disabled)統一 `bg-surface-raised`(border / shadow 已 retire,2026-05-12 per user「我有叫你加 elevation 嗎」),`absolute left-1 top-1/2 -translate-y-1/2` 4px inset 不佔 column 空間;**hover-reveal** `opacity-0 group-hover/row:opacity-100`。對齊 Jira backlog(@benchmark-unverified,M22)。Tertiary chip 非 ItemInlineAction 因透明背景撞 table border。
+- **Handle**:Button tertiary iconOnly xs(GripVertical)24px chip,所有 state(idle / hover / aria-disabled)統一 `bg-surface-raised`(border / shadow 已 retire,2026-05-12 per user「我有叫你加 elevation 嗎」),fixed-position 浮層貼 row 左緣、不佔 column 空間(位置 JS 計算,實作見 `data-table.tsx`);**hover-reveal** 由 JS 控 visibility / opacity(row 或 handle hover 顯示;drag 中 source 強制顯示、其他列隱藏)。對齊 Jira backlog(@benchmark-unverified,M22)。Tertiary chip 非 ItemInlineAction 因透明背景撞 table border。
 - **Sort × Drag 互斥**:sort.length>0 → handle disabled+Tooltip。**Top-level only**(`row.depth>0` 不顯 handle)。**Position**:active vs over 視覺位置 → `'after'`/`'before'` 對齊 `arrayMove`。**Consumer-managed mutation**:`onRowReorder(sourceId, targetId, position)`,DS 不持 row order(Notion/Airtable/Linear)。 <!-- @benchmark-unverified: see frontmatter benchmark list for canonical DS source URL -->
 - **Virtualization 整合**(v3 2026-05-05):enableRowDrag 自動把 overscan 拉到 `Math.max(overscan, 5)` + drag 期 freeze `measureElement` + `modifiers={[snapToCursorModifier]}`(ghost top-left 對齊 cursor,不鎖軸)。**3-panel mirror sync**:各 region 對同 row id 各呼叫 `useDraggable` + `useDroppable`,mirror 自然取得相同 transform;handle 只 render primary region(left 優先 → center)避雙觸發。**Cross-parent drop 禁止**(已知 limit):nested 只同 top-level 重排,collisionDetection 過濾,顯 invalid signal。
 
@@ -517,12 +519,14 @@ DataTable 是 composite multi-section 元件,**不套 canonical 5**(Inspector /
 
 **Why not radio-group**:之前 boilerplate 從 RadioGroup spec 誤抄。DataTable 是 multi-row / multi-column composite,not single-choice selection group;a11y semantics 完全不同(grid vs radio-group)。 <!-- @benchmark-verified: 2026-05-18 D1 rewrite -->
 
-
 ## 被引用(auto-maintained,Dim 3 reciprocal audit)
 
 > 本節由 `scripts/add-reciprocal-pointers.mjs` 自動維護,列出在 SSOT 語境下指向本 spec 的其他 spec。若要手動補充,寫在本節之前。
 
+- `bulk-action-bar.spec.md`
 - `carousel.spec.md`
 - `circular-progress.spec.md`
+- `description-list.spec.md`
+- `opacity.spec.md`
 - `scroll-area.spec.md`
-- `item-anatomy.spec.md`
+- `tree-view.spec.md`

package/src/components/DataTable/data-table.stories.tsx

@@ -163,7 +163,7 @@ export const ColumnResize: Story = {
           />
         </div>
         <div>
-          <h3 className="text-body font-bold text-foreground mb-2">Pinned + Resize 並存(USER #43 sanity)</h3>
+          <h3 className="text-body font-bold text-foreground mb-2">欄位釘選與欄寬調整並存</h3>
           <p className="text-caption text-fg-muted mb-3">
             把 SKU 跟產品名稱固定在左側,依然可以拖動分隔線調整這兩欄的寬度。
             <br />目前各欄寬度:{JSON.stringify(pinnedWidths)}
@@ -296,6 +296,7 @@ export const RowAutoHeight: Story = {
 }
 
 /* ── Empty State ── */
+// 「預設空狀態」pane = 「自訂空狀態」的對照基線;Empty primitive 消費教學 canonical → anatomy.EmptyState,此處不重複教學
 export const EmptyState: Story = {
   name: '空狀態',
   render: () => (
@@ -1390,11 +1391,11 @@ export const FilterPanelModified: Story = {
   },
 }
 
-/* ── 進階篩選 — 長 tag 溢出測試(A5 reproduce)── */
+/* ── 進階篩選 — 長標籤溢出 ── */
 export const FilterPanelLongTagOverflow: Story = {
   name: '進階篩選 — 長標籤溢出',
   render: () => {
-    // 故意用 select_multi op + 多個長 label values,測試 Combobox tag overflow + +N indicator
+    // 製造業 ERP 的產品分類名稱普遍很長 — 示範多選後 Combobox tag 溢出時的 +N 摘要收斂
     const longLabelColumns = [
       col.accessor('category', {
         header: '類別',
@@ -1418,7 +1419,7 @@ export const FilterPanelLongTagOverflow: Story = {
     }))
     return (
       <div className="w-full max-w-[680px]">
-        <p className="text-caption text-fg-muted mb-3">A5 reproduce — 多個超長 label values 是否觸發 Combobox `+N` overflow indicator?</p>
+        <p className="text-caption text-fg-muted mb-3">產品分類名稱很長(製造業 ERP 常見)時,已選的多個標籤超出單行寬度,Combobox 自動收斂為 +N 摘要。</p>
         <DataTableFilterPanel
           mode="flat"
           columns={[...longLabelColumns]}
@@ -1432,14 +1433,14 @@ export const FilterPanelLongTagOverflow: Story = {
 
 /* ── 列拖曳重排(Jira-style + 3-panel pinned columns)──────────────────────
    enableRowDrag + onRowReorder 整合範例(v3 Jira 設計準則):
-   - handle absolute 浮在 row 左 border(Button tertiary iconOnly xs = elevated chip)
+   - handle 浮在 row 左緣(fixed-position;Button tertiary iconOnly xs = elevated chip)
    - 不佔 column 空間 — table 看起來乾淨,沒有預留拖曳欄位
-   - hover row → handle 浮現(opacity 0 → 100)
-   - 拖曳 row → @dnd-kit/sortable 重排;放下 → onRowReorder(sourceId, targetId, 'before' | 'after')
+   - hover row → handle 浮現(JS 控 opacity)
+   - 拖曳 row → @dnd-kit/core useDraggable + useDroppable(v15.0 Path B);放下 → onRowReorder(sourceId, targetId, 'before' | 'after')
    - consumer 自管 data array mutation(同 Notion / Airtable / Linear pattern)
    - sort 啟用時 drag handle 自動 disabled + Tooltip 解釋
-   - pinned-left + pinned-right 同時存在 → mirror regions 跟動 transform(per-region useSortable
-     共享同 SortableContext state) */
+   - pinned-left + pinned-right 同時存在 → source 留原位,2px drop indicator 跨三 region 同步標示落點
+     (per-region useDraggable / useDroppable,不 auto-shift) */
 export const RowDragInteractive: Story = {
   name: '列拖曳重排（含釘選欄）',
   render: () => {
@@ -1462,8 +1463,8 @@ export const RowDragInteractive: Story = {
       <div className="flex flex-col gap-3 max-w-3xl">
         <p className="text-caption text-fg-muted">
           handle 浮在 row 左緣（不佔 column 空間，Jira 設計準則）。pinned-left（SKU）+ pinned-right（Updated）+
-          center 中段欄。拖曳任一列時，三個 region 的 row 會同步跟動 transform（per-region
-          <code>useSortable</code> 共享同 SortableContext state）。
+          center 中段欄。拖曳時 source 列留在原位（壓住視覺），2px 主色 drop indicator 跨三個 region
+          同步標示落點（per-region <code>useDraggable</code> / <code>useDroppable</code>，不 auto-shift）。
         </p>
         <DataTable
           columns={columnsWithPrice}
@@ -1510,8 +1511,8 @@ export const RowDragWithVirtualization: Story = {
     return (
       <div className="flex flex-col gap-3 max-w-3xl">
         <p className="text-caption text-fg-muted">
-          200 列 + 虛擬捲動。v3 修正:enableRowDrag 自動拉高 overscan ≥ 10、drag 期間 freeze
-          measureElement、modifier 鎖 Y 軸 — 拖曳 + 持續往下捲不再錯位。
+          200 列 + 虛擬捲動。v3 修正:enableRowDrag 自動拉高 overscan ≥ 5、drag 期間 freeze
+          measureElement、snapToCursorModifier ghost 對齊游標（不鎖軸）— 拖曳 + 持續往下捲不再錯位。
         </p>
         <DataTable
           columns={baseColumns}
@@ -1890,3 +1891,47 @@ export const RoadmapAllInOne: Story = {
     }
   },
 }
+
+/* ── Feature-split perf budget story(2026-05-14 codex perf debate verdict;2026-06-12 deep-audit
+   R2 重建 — 2026-05-17 stories 整併批次誤 retire,但 spec「六之三」Case B hard gate +
+   scripts/runtime-perf-datatable.mjs:20 仍指向本 story,gate 形同不可跑):──────────────────
+   獨立 perf 量測 story — 同 Roadmap 13 cols rich-cell data(useRoadmapColumns SSOT),但**禁用**
+   row drag / column reorder / column resize / selection / spreadsheet overlay,只保 inline edit
+   display。目的:隔離 feature-stack 疊加 cost(SortableRowProvider / filter / sort / columnOrder
+   state),驗證 rich cell 本體 scroll budget(avg ≤ 50ms / p95 ≤ 80ms / long-task ≤ 1,CPU 4x
+   throttle)。**不動** RoadmapAllInOne demo IA(user 2026-05-10 directive 全合一)。
+   重建版去掉原手刻說明 banner(px-loose + border-b border-divider = R9 chrome-header drift
+   簽名,且量測 story 不需 chrome;說明留本註解)。 */
+export const RoadmapPerfBudget: Story = {
+  name: '效能預算量測',
+  parameters: { layout: 'fullscreen' },
+  tags: ['!autodocs'],
+  render: () => {
+    const bigData = React.useMemo(() => {
+      const arr: RoadmapItem[] = []
+      for (let i = 0; i < 500; i++) {
+        const base = ROADMAP_DATA[i % ROADMAP_DATA.length]
+        const id = `RDM-${String(i + 100).padStart(3, '0')}`
+        arr.push({ ...base, id, title: `${base.title} (#${i + 1})` })
+      }
+      return arr
+    }, [])
+    const [data, setData] = React.useState(bigData)
+    const columns = useRoadmapColumns()
+    const handleCommit = (rowId: string, colId: string, value: unknown) => {
+      setData((prev) => prev.map((r) => (r.id === rowId ? { ...r, [colId]: value } : r)))
+    }
+    return (
+      <div className="mx-[var(--layout-space-loose)] mb-[var(--layout-space-loose)]">
+        <DataTable
+          columns={columns}
+          data={data}
+          height="600px"
+          inlineEdit
+          getRowId={(row) => row.id}
+          onCellCommit={handleCommit}
+        />
+      </div>
+    )
+  },
+}

package/src/components/DataTable/data-table.tsx

@@ -1,5 +1,17 @@
 // @benchmark-unverified-blanket: file-level retraction per M22 (d) — claims herein not individually URL-cited; treat as unverified visual/usage rumor unless retrofit per-claim. Hook escape preserved.
 // code-quality-allow: file-size — foundational composite — 拆檔會複雜化 context / ref / state 同步
+//
+// ── 檔案結構(2026-05-03 split matrix;2026-06-11 自 data-table.spec.md 遷入,Level 4 code home)──
+// 每個檔過 M21 / M17 / Rule-of-3 三 test:
+//   - data-table.tsx(主,foundational)
+//   - data-table-filter-panel.tsx + data-table-sort-manager.tsx + data-table-column-visibility-panel.tsx(panel state 隔離)
+//   - cell-registry.tsx(column type → cell display / edit 解析 SSOT)
+//   - data-table-interaction-layer.tsx + active-editor-controller.ts(spreadsheet overlay + portal editor)
+//   - column-types.ts + filter-operators.ts(✓ Rule-of-3 SSOT,3+ consumer)
+//   - filter-tree.ts(pure data + eval,test isolation)
+//   - lib/column-meta.ts(Internal SSOT,消 5 處 `(col as any)`)
+//   - + stories / spec / css
+// M21 retract:filter-value-picker.tsx 1 consumer → 已 inline 回 panel。
 import * as React from 'react'
 import { createPortal } from 'react-dom'
 import { Empty } from '@/design-system/components/Empty/empty'
@@ -56,6 +68,7 @@ type TableSize = 'sm' | 'md' | 'lg'
 export interface DataTableProps<TData>
   extends Omit<React.HTMLAttributes<HTMLDivElement>, 'children'>,
     VariantProps<typeof dataTableVariants> {
+  // any-allow: TanStack ColumnDef TValue idiom(per-column value 型別異質,官方範例同)— 對齊本 module 既有 escape 紀律
   columns: ColumnDef<TData, any>[]
   data: TData[]
   size?: TableSize

package/src/components/DataTable/filter-operators.spec.md

@@ -1,6 +1,6 @@
-# Advanced Filter — Operator × ColumnType × ValueShape SSOT(DRAFT v3)
+# Advanced Filter 設計原則(Operator × ColumnType × ValueShape SSOT,v3)
 
-> **狀態**:Draft for review。Phase A 結案版 + datetime 擴充。確認後升 `filter-operators.spec.md` + 寫成 `filter-operators.ts` registry。
+> **狀態**:已落地 — registry 寫成 `filter-operators.ts`,`filter-tree.ts` + `data-table-filter-panel.tsx` 消費(原 draft 兩個升級條件皆已達成,2026-06-11 對齊)。
 > **M8 benchmark**:對照 ClickUp(CU)/ Airtable(AT)/ Notion(NT)三家。**v3 加 datetime / includeTime + 砍 number.between(2/3 業界共識)**。
 > **設計路線**:**ClickUp 為 baseline**,合理 + 不衝突 + 真實用的擴充採納。
 > **檔位**:暫放 DataTable/,若決定抽 `patterns/advanced-filter/` 再搬。
@@ -10,7 +10,7 @@
 - **砍 `number.between`**(9→8 ops)— Notion + Airtable 共識,同 field 重複 condition 可組合 `gte X AND lte Y`,無自然視覺也無業界 NumberRangeInput 元件
 - **加 `column.meta.includeTime: boolean` 旗標** — 對齊 Notion idiom,不另設 datetime column type
 - **加 ValueShape `datetime_single` / `datetime_range`** — `includeTime=true` 時切到這兩個 shape
-- **加 ValueShape `datetime_relative`**(同 date_relative,relative 邏輯不變)
+- **datetime 不另設 relative shape** — `is_relative` 維持 `date_relative`(relative 邏輯不變;12-shape 表與 code `ValueShape` union 皆無 `datetime_relative`)
 - **filter 比對精度**:`includeTime=true` 走 ms 精度(避開 Airtable 著名地雷:filter 忽略 time)
 - **不新增 `time-only` column type**(業界沒人做,罕見場景)
 
@@ -33,8 +33,8 @@
 | `select_single` | `<Select>` from `column.meta.options` | (預留)罕用 |
 | `person_single` | `<PeoplePicker>` 單選 | (預留)罕用 |
 
-**date_relative 預設選項**(11 個):
-`today / yesterday / tomorrow / this_week / last_week / next_week / this_month / last_month / next_month / past_7_days / past_30_days`
+**date_relative 預設選項**(13 個,分過去 / 目前 / 未來三組 — 對齊 code `DATE_RELATIVE_OPTIONS` / `DATE_RELATIVE_GROUPS`):
+`today / yesterday / tomorrow / this_week / last_week / next_week / this_month / last_month / next_month / past_7_days / past_30_days / next_7_days / next_30_days`
 
 **`number_range` 已砍**(配合 `number.between` 砍除)。
 
@@ -189,30 +189,15 @@
 | 統一用 `is_set` / `is_not_set`(不混 `is_empty`) | 9 types 全用(boolean 豁免) |
 | select / person 用 `is` 配多值 picker(不另設 `is_any_of`) | ✓ 對齊 CU UX |
 | multiSelect / multiPerson 用 `has_*` 動詞(對應 CU labels Any/All/None) | ✓ |
-| number 用 `between` 對應 CU RANGE | ✓ |
+| number 不設 `between`(v3 砍 — 同 field `gte AND lte` 組合替代,見拍板 #10) | ✓ |
 | date 用 `before/after/between/relative` + `is_set` 不混 Airtable `is_empty` 風 | ✓ |
 | 6 ops 擴充項皆有 ≥ 2 家 world-class DS 採用,且不衝突 CU 設計語言 | ✓ |
 
 **未跑 audit / test 驗證**,僅與 web-researched ClickUp / Airtable / Notion docs 自我比對。
 
-## 5. TypeScript 結構草案
+## 5. TypeScript 結構(已落地)
 
-```ts
-export type ValueShape =
-  | 'none' | 'text' | 'number' | 'number_range'
-  | 'date_single' | 'date_range' | 'date_relative'
-  | 'select_single' | 'select_multi'
-  | 'person_single' | 'person_multi'
-
-export interface OperatorSpec {
-  op: string                 // e.g. 'contains'
-  label: string              // e.g. '包含'(暫硬編,留 i18n hook)
-  valueShape: ValueShape
-}
-
-export const OPERATOR_REGISTRY: Record<ColumnType, OperatorSpec[]> = { ... }
-export const DEFAULT_OPERATOR: Record<ColumnType, string> = { ... }
-```
+型別與 registry 落地於 `filter-operators.ts`(`ValueShape` 12 種含 `datetime_*`、無 `number_range`;`OPERATOR_REGISTRY` / `DEFAULT_OPERATOR`;`getValueShape` 處理 `includeTime` auto-promote)。Tree 型別與求值在 `filter-tree.ts`。原 v2 草案已退役,以 code 為準。
 
 ## 6. 拍板紀錄
 
@@ -253,12 +238,19 @@ export const DEFAULT_OPERATOR: Record<ColumnType, string> = { ... }
 
 **技術坑(信心 85%,Phase B spec.md 詳)**:TanStack `ColumnFiltersState` per-column 一筆 filter value,N 條同 column 會 AND-chain 不能 OR。**業界標準解法**:棄用 `columnFilters`,改自管 FilterTree state + 用 `globalFilter` + 自訂 `globalFilterFn` 走樹求 boolean。
 
-## 8. Phase B 進度
+## 8. 邊界案例(code 真值 — `filter-tree.ts` / `data-table-filter-panel.tsx`)
+
+- **Condition 值空 / 未選 field**:視為 incomplete,求值 **pass-through**(不過濾任何 row);空值 ≠ `is_not_set`(後者是顯式 op)— `isConditionComplete` 守門
+- **群組刪光 condition**:空群組保留並 pass-through(true),panel 顯示「移除空群組」按鈕由 user 顯式刪除,不自動消失
+- **巢狀深度**:1-level cap 由 TypeScript 型別鎖死(`FilterGroup.children: FilterCondition[]`),無 runtime guard;繞過型別塞入的非 condition 物件缺 `field`/`op` → incomplete → pass-through,不 crash
+- **relative 區間邊界**:全部 local time、雙端 inclusive(`startOfDay`–`endOfDay`);`past_7_days` = 7 天前 00:00 起**含今天整天**;week 以週一起算(`weekStartsOn: 1`)
+
+## 9. Phase B 進度
 
-- [x] ValueShape × DS 元件對照 — 完成,coverage 8/12 直接消費 + 4 預留 + 2 新建(DateTimePicker / DateTimeRangePicker)
+- [x] ValueShape × DS 元件對照 — 完成,coverage 8/12 直接消費 + 4 預留;datetime 走 `<DatePicker showTime>` / `<DatePickerRange showTime>` prop variant(M21,非新元件)
 - [x] InputSurface 議題消失(配合砍 `number.between`)
-- [→] `advanced-filter.draft.md` — FilterTree data model + DataTable 耦合(本 turn 同步寫)
-- [→] `datetime-picker.draft.md` — DateTimePicker / Range spec(本 turn 同步寫)
+- [x] FilterTree data model + DataTable 耦合 — 已落地 `filter-tree.ts` + `data-table-filter-panel.tsx`(原規劃 `advanced-filter.draft.md` 未另立檔,內容即本 spec + code)
+- [x] datetime spec — 併入本 spec v3(原規劃 `datetime-picker.draft.md` 不需要,無新元件)
 - [x] i18n 策略 — 暫硬編繁中,留 i18n hook(對齊 DS 既有元件慣例)
 - [→] Phase B.5 lock canonical via `/ensure-canonical`(spec 全收斂後)
 

package/src/components/DateGrid/date-grid.anatomy.stories.tsx

@@ -105,7 +105,7 @@ export const Overview = {
       <div>
         <H3>視覺一覽</H3>
         <Desc>實際渲染 — single mode,已選今日的前一日展示 selected 視覺,today 以數字下方藍色底線標示。</Desc>
-        <div className="inline-flex bg-surface-raised border border-border rounded-lg p-2 w-fit">
+        <div className="inline-flex bg-surface-raised border border-border rounded-lg w-fit">
           <DateGrid
             mode="single"
             selected={(() => {
@@ -196,7 +196,7 @@ export const Inspector = {
           {/* Left: live preview + blueprint */}
           <div className="flex flex-col gap-5">
             <div className="px-6 py-6 rounded-lg bg-canvas border border-divider flex items-center justify-center">
-              <div className="bg-surface-raised border border-border rounded-lg p-2">
+              <div className="bg-surface-raised border border-border rounded-lg">
                 <DateGrid
                   mode="single"
                   selected={selected}
@@ -288,7 +288,7 @@ export const Inspector = {
     return (
       <div className="flex flex-col gap-4">
         <H3>元件檢閱器</H3>
-        <Desc>DateGrid 的所有 layout token 一覽。theme / density 切換時色彩自動反轉,日格尺寸保持不變(浮層 / dashboard 專用,不配對 field-height family)。</Desc>
+        <Desc>DateGrid 的所有 layout token 一覽。theme / density 切換時色彩自動反轉,日格走 h-field-sm 隨 density 縮放(28×28 md / 32×32 lg),與 field 家族保持比例。</Desc>
         <InspectorInner />
       </div>
     )
@@ -442,13 +442,13 @@ export const SizeMatrix = {
       <div className="flex flex-wrap gap-6 items-start">
         <div className="flex flex-col gap-2">
           <span className="text-caption font-medium text-fg-secondary">單月(預設)</span>
-          <div className="bg-surface-raised border border-border rounded-lg p-2">
+          <div className="bg-surface-raised border border-border rounded-lg">
             <DateGrid mode="single" defaultMonth={new Date()} locale={zhTW} />
           </div>
         </div>
         <div className="flex flex-col gap-2">
           <span className="text-caption font-medium text-fg-secondary">雙月並排(range 常用)</span>
-          <div className="bg-surface-raised border border-border rounded-lg p-2">
+          <div className="bg-surface-raised border border-border rounded-lg">
             <DateGrid mode="single" defaultMonth={new Date()} locale={zhTW} numberOfMonths={2} />
           </div>
         </div>
@@ -483,7 +483,7 @@ export const StateBehavior = {
         <div className="flex flex-wrap gap-6 items-start">
           <div className="flex flex-col gap-2 min-w-0">
             <span className="text-caption font-medium text-fg-secondary">mode="single"</span>
-            <div className="bg-surface-raised border border-border rounded-lg p-2">
+            <div className="bg-surface-raised border border-border rounded-lg">
               <DateGrid
                 mode="single"
                 selected={single}
@@ -499,7 +499,7 @@ export const StateBehavior = {
 
           <div className="flex flex-col gap-2 min-w-0">
             <span className="text-caption font-medium text-fg-secondary">mode="multiple"</span>
-            <div className="bg-surface-raised border border-border rounded-lg p-2">
+            <div className="bg-surface-raised border border-border rounded-lg">
               <DateGrid
                 mode="multiple"
                 selected={multiple}
@@ -515,7 +515,7 @@ export const StateBehavior = {
 
           <div className="flex flex-col gap-2 min-w-0">
             <span className="text-caption font-medium text-fg-secondary">mode="range"</span>
-            <div className="bg-surface-raised border border-border rounded-lg p-2">
+            <div className="bg-surface-raised border border-border rounded-lg">
               <DateGrid
                 mode="range"
                 selected={range}

package/src/components/DateGrid/date-grid.principles.stories.tsx

@@ -80,7 +80,7 @@ export const UsageGuidance: Story = {
                 <LinkTo kind="Design System/Internal/DateGrid/展示" name="範圍 — 分析時段 / 訂單範圍"><span className="text-primary hover:underline font-medium cursor-pointer">Range — 分析時段 / 訂單範圍</span></LinkTo>
               </li>
               <li>
-                <LinkTo kind="Design System/Internal/DateGrid/展示" name="行內 — 儀表板小卡"><span className="text-primary hover:underline font-medium cursor-pointer">行內 — 儀表板小卡</span></LinkTo>
+                <LinkTo kind="Design System/Internal/DateGrid/展示" name="行內 — 儀表板小卡"><span className="text-primary hover:underline font-medium cursor-pointer">行內 — Linear 專案截止日小卡</span></LinkTo>
               </li>
             </ul>
             <p className="text-fg-muted mt-3">判斷不確定時:對照 spec.md「何時用 / 何時不用」段;若仍不符,改用近親元件(見下方「vs 近親」)。</p>
@@ -120,10 +120,10 @@ export const UsageGuidance: Story = {
           </Rule>
         </Section>
 
-        <Section title="vs 近親 — Calendar(inline) vs DatePicker(field trigger)">
+        <Section title="vs 近親 — DateGrid(inline)vs DatePicker(field trigger)">
           <Rule
-            title="Calendar — inline 月曆,頁面上常駐可見"
-            note="dashboard 小卡、側欄 widget、日期 filter bar。使用者一眼就看到整月,不需點開。Calendar 是純 primitive,不自包 Popover。"
+            title="DateGrid — inline 月曆,頁面上常駐可見"
+            note="dashboard 小卡、側欄 widget、日期 filter bar。使用者一眼就看到整月,不需點開。DateGrid 是純 primitive,不自包 Popover。"
           >
             <Demo title="Linear 專案截止日 widget">
               <div className="flex flex-col gap-2 w-fit">
@@ -152,7 +152,7 @@ export const UsageGuidance: Story = {
 
           <Rule
             title="判斷法 — 看「頁面是否常駐顯示整月」"
-            note="常駐(月曆是主要內容)→ Calendar;輔助(主要是一個欄位,偶爾改)→ DatePicker。空間有限的表單永遠用 DatePicker,不要塞整個月曆進表單。"
+            note="常駐(月曆是主要內容)→ DateGrid;輔助(主要是一個欄位,偶爾改)→ DatePicker。空間有限的表單永遠用 DatePicker,不要塞整個月曆進表單。"
           >
             <Label>
               常駐月曆 = 使用者「在選日的脈絡中」(排班、活動、分析時段篩選);
@@ -304,9 +304,9 @@ export const LocaleRule: Story = {
     <div>
       <Rule
         title="locale prop 控制週首日與星期標頭語言"
-        note="react-day-picker 接受 date-fns locale 物件。週首日由 locale 物件決定,不以語言籠統判斷:zhTW 週日起、en-US 週日起,但 en-GB / de / fr 週一起(同樣是英文,en-US 與 en-GB 週首日就不同)。Consumer 決定傳哪個 locale,DateGrid 不內建語言。"
+        note="react-day-picker 接受 date-fns locale 物件。週首日由 locale 物件決定,不以語言籠統判斷:en-US 週日起、en-GB 週一起——同樣是英文,週首日就不同;zhTW / de / fr(date-fns 內建值)都是週一起。下方對照:zhTW 首欄是週一,en-US 首欄是週日。Consumer 決定傳哪個 locale,DateGrid 不內建語言。"
       >
-        <Demo title="zhTW(繁體中文 · 週日起)">
+        <Demo title="zhTW(繁體中文 · 週一起)">
           <DateGrid mode="single" defaultMonth={new Date(2026, 3, 1)} locale={zhTW} />
         </Demo>
         <Demo title="預設(en-US · 週日起)">

package/src/components/DateGrid/date-grid.spec.md

@@ -26,7 +26,7 @@ DateGrid 是 **DatePicker 內部的 date-grid primitive**(月份格網 + 前後
 
 **Layout Family**:非上述 family — composite / multi-section(月份 caption + 星期標頭 + 日期網格 + nav 按鈕,多區塊組合)。
 
-**Storybook title 層級**:`Design System/Internal/DateGrid/*`(非 Components/,因為它是 DatePicker 的 internal primitive;對齊 CLAUDE.md「Internal vs Components 判斷 test」:無預設視覺 context、所有 consumer 透過 DatePicker 包)。
+**Storybook title 層級**:`Design System/Internal/DateGrid/*`(非 Components/,因為它是 DatePicker 的 internal primitive;對齊 `.claude/rules/ui-development.md`「Public component vs Internal primitive canonical」(intent-based 判準):consumer 經 `DatePicker` wrapper 取得,不直接 import 本元件)。
 
 **世界級命名對照(為什麼不叫 Calendar)**:
 
@@ -46,6 +46,8 @@ DateGrid 是 **DatePicker 內部的 date-grid primitive**(月份格網 + 前後
 
 ## 何時用
 
+DateGrid 是 internal primitive(見「定位」),一般 consumer 經 `DatePicker` 取得;以下為 DS 內部組合或進階 inline 場景:
+
 - **Inline 月曆顯示**:dashboard / 行事曆小卡 / 日期 filter bar
 - **DatePicker 浮層內嵌**:DatePicker 消費本元件作為選日 popup(見 `../DatePicker/date-picker.spec.md`)
 - **範圍選擇**:`mode="range"` 適用「from → to」場景(訂單日期範圍、查詢時段)
@@ -57,7 +59,7 @@ DateGrid 是 **DatePicker 內部的 date-grid primitive**(月份格網 + 前後
 |------|------|------|
 | 日期輸入欄位 | `DatePicker` | DateGrid 是 inline,欄位需要 trigger + popup 結構 |
 | 純顯示單日期 | `<DatePicker mode="display">` / `Intl.DateTimeFormat` | 不需 interactive 月曆 |
-| 時間選擇(時分) | ⚠️ 未來 TimePicker | DateGrid 只處理日期層級 |
+| 時間選擇(時分) | `TimePicker`(見 `../TimePicker/time-picker.spec.md`)| DateGrid 只處理日期層級 |
 | 事件行事曆(日程本) | 專用行事曆元件 | DateGrid 是日期選擇;事件日誌需要 event overlay / drag / week/month view 切換 |
 
 ---
@@ -70,6 +72,8 @@ DateGrid 是 **DatePicker 內部的 date-grid primitive**(月份格網 + 前後
 | `multiple` | 可勾選多個不連續日期 | event 報名多日 |
 | `range` | from → to 連續範圍 | 訂單日期範圍 / 查詢時段 |
 
+**range vs multiple 分界**:選的是「連續區間」(只在乎起迄兩端)→ `range`;選的是「各自獨立的日子」(可不連續、逐日增減)→ `multiple`。起迄日場景(訂單 / 查詢時段)固定走 `range`;簽核 / 報名這類逐日勾選走 `multiple`。
+
 ---
 
 ## 實作機制:classNames 鏡射 modifier keys(2026-04-21 AR43 修正)
@@ -99,10 +103,10 @@ DateGrid 是 **DatePicker 內部的 date-grid primitive**(月份格網 + 前後
 | **today + selected** | 數字下方短圓桿(白) | bar 色切 `on-emphasis` | 選中藍底上藍 bar 隱形,必切白;以 state 疊加 selector 覆寫 |
 | **disabled** | 灰底 + 淡字 | `bg-disabled` + `fg-disabled` + `cursor-not-allowed` | 跟 Button disabled token 一致,不自創 palette |
 | **outside(非本月)**| 淡字(只文字) | `fg-muted` | 比 disabled 弱:outside 仍可 hover / 可點,純是「非焦點月份」的標示 |
-| **selected / range 端點** | 藍底白字圓 | button `primary` 底 + `on-emphasis` 字(cell `data-selected="true"`) | range_start / range_end 共用此視覺 |
-| **range 端點 cell bg** | 灰底半圓 track,**高度 = button** | `before:` pseudo `inset-y-0`(滿 cell 高度)+ `rounded-l/r-full` + start `left-0 -right-[2px]` / end `-left-[2px] right-0`(向 middle 外擴 2px bridge gap)(M8 對齊 Ant `cell-range-start::before { border-radius: 9999px 0 0 9999px }` — [ant-design picker style](https://github.com/ant-design/ant-design/blob/master/components/date-picker/style/panel.ts) `@benchmark-unverified` style file path,Material X / Apple / Google `@benchmark-unverified` visual)| 圓弧半徑 = button 半徑無錯位;舊版 cell-level bg 圓弧半徑 16px 比 button 14px 大 = 視覺 misalign |
-| **range track(中間)** | 灰底矩形,**高度 = button**(28×28 @ md)| `before:` pseudo `inset-y-0 -inset-x-[2px]` `bg-neutral-selected`(對齊 range_start/end pseudo + tsx L146-159 實作);button 透明顯露 track | track 高度跟 selected 圓一致,不留 2px「fat」邊;cell 寬度維持 32px → 相鄰 pseudo 接合連貫橫向 track |
-| **hover(未選中)** | 藍圈 outline(無 fill) | button hover ring 色 `primary`,寬度 1.5px,無 bg | 1.5px ring 對齊 Apple HIG `@benchmark-unverified` / Ant `@benchmark-unverified`(visual,non-source-citable) |
+| **selected / range 端點** | 藍底白字圓 | button `primary` 底 + `on-emphasis` 字 | range_start / range_end 共用此視覺 |
+| **range 端點 cell bg** | 灰底半圓 track,**高度 = button**,向 middle 外擴 2px bridge gap | `neutral-selected`;class 細節見「Range track canonical」+ tsx | 圓弧半徑 = button 半徑無錯位;舊版 cell-level bg 圓弧半徑 16px 比 button 14px 大 = 視覺 misalign |
+| **range track(中間)** | 灰底矩形,**高度 = button**(28×28 @ md),左右各外擴 2px 接合相鄰 cell | `neutral-selected`;button 透明顯露 track(class 細節見 tsx)| track 高度跟 selected 圓一致,不留 2px「fat」邊;相鄰 pseudo 接合連貫橫向 track |
+| **hover(未選中)** | 藍圈 outline(無 fill) | button hover ring 色 `primary`,無 bg(ring 寬度等 class 細節見 tsx)| 細 ring 對齊 Apple HIG `@benchmark-unverified` / Ant `@benchmark-unverified`(visual,non-source-citable) |
 
 ## 組合狀態(state stacking order)
 
@@ -110,7 +114,7 @@ DateGrid 是 **DatePicker 內部的 date-grid primitive**(月份格網 + 前後
 - range-start / range-end → selected 規則(cell 半圓 track + button 圓)
 - range-middle → track 規則(cell 灰底矩形 + button 透明)
 - today + range-middle → track(灰底)+ today bar(藍色仍可見,cell 未 selected)
-- hover 在 selected / range-middle 上被 ring-0 壓制(避免二次 hover 出現方框 bug)
+- hover 在 selected / disabled 上被 ring-0 壓制(避免二次 hover 出現方框 bug);range-middle 的 button 透明顯露 track,hover ring 仍顯示(見 tsx `range_middle` 註解)
 
 ## Spacing canonical(2026-05-03 v8)
 
@@ -136,7 +140,7 @@ Prev/Next chevron 用 `<Button variant="text" size="xs" iconOnly>`(DS primitive
 - `fg-muted`(45%)專屬 dismiss / inline action / placeholder(spec.md 既有定義)
 - chevron nav 是 functional navigation,不是 dismiss → 不該套 fg-muted 自開新 tier
 
-歷史(2026-05-03):v6-v8 我憑印象引「Ant chevron muted」(`@benchmark-unverified` 印象,non-cited claim)覆蓋 DS canonical(text-fg-muted 45%)→ user 4 輪糾正後撤回(M23 防再犯)。
+歷史(2026-05-03):v6-v8 曾以未驗證的「Ant chevron muted」印象覆蓋 DS canonical,已撤回(M23 防再犯)。
 
 ⚠️ RDP `PreviousMonthButton` override 必丟 `children`(RDP 把 `<Chevron>` 當 children 傳)否則 double svg(2026-05-03 v8 抓到 bug)。
 
@@ -147,9 +151,8 @@ Prev/Next chevron 用 `<Button variant="text" size="xs" iconOnly>`(DS primitive
 ## Range track canonical(2026-05-03 v8)
 
 對齊 Ant `cell-range-start::before { border-radius: 9999px 0 0 9999px }`(stadium pattern): <!-- @benchmark-unverified: see frontmatter benchmark list for canonical DS source URL -->
-- `range_start` cell pseudo:`before:left-0 -right-[2px] inset-y-0 rounded-l-full bg-neutral-selected`
-- `range_end` cell pseudo:鏡像 `rounded-r-full`
-- `range_middle` cell pseudo:`before:-inset-x-[2px] inset-y-0 bg-neutral-selected`(無 rounding)
+- `range_start` / `range_end` cell pseudo:左 / 右半圓 stadium,向 middle 側外擴 2px bridge gap(class 細節見 tsx `range_start` / `range_end`)
+- `range_middle` cell pseudo:滿 cell 高矩形、左右各外擴 2px,無 rounding(class 細節見 tsx)
 - pseudo 蓋全 cell + bridge 4px gap → button 圓的 corner triangle 看到 pseudo bg(對齊 button 圓的左/右半弧,無「凸出」)
 - `bg-neutral-selected`(semantic = neutral-2)— 對齊 TimePicker 選中項目樣式
 
@@ -173,7 +176,7 @@ react-day-picker v9 自動處理:
 - **Focus**：`autoFocus` prop 自動 focus 到選中日(或今天)
 - **Locale**：`locale` prop 控制週首日、星期標頭語言
 
-Consumer 無需額外處理,保留 react-day-picker API 即可。
+**DS 自訂部分**:day button 的 focus ring 由本元件 classNames 覆寫為 DS canonical(`focus-visible:ring-2 ring-ring`,非 RDP 預設樣式);nav 按鈕為 DS `<Button>` 並帶 `aria-label`(上一個月 / 下一個月)。其餘 consumer 無需額外處理,保留 react-day-picker API 即可。
 
 ---
 
@@ -195,9 +198,9 @@ DateGrid 本元件是**對 `react-day-picker` 的 `<DayPicker>` 元件薄包裝*
 
 - **Disabled day**:`disabled` prop 走 react-day-picker matcher;disabled cell 視覺 `text-fg-disabled`(M24)、`cursor-not-allowed`、click 不觸發 onSelect、鍵盤導覽自動 skip。
 - **Loading(server-rendered grid)**:DateGrid 為 sync render(date math 在 client),非 async surface。consumer 若需 async disabled-dates fetch(如後端 holiday list),應先 disable trigger 直到 fetch 完成,DateGrid 開啟後立即 ready。
-- **Empty(全 disabled days)**:極端場景(所有日期都被 disabled matcher 命中),DateGrid 渲完整 grid 但全部 cell 為 disabled state,鍵盤焦點停留無導覽目標(react-day-picker v9 內建)。
+- **Empty(全 disabled days)**:極端場景(所有日期都被 disabled matcher 命中),DateGrid 渲完整 grid 但全部 cell 為 disabled state,鍵盤焦點停留無導覽目標(react-day-picker v9 內建)。Enter / Space 在 disabled cell 上無動作不報錯(RDP DayButton 對 disabled day 渲染 native `disabled`,focus target 時改掛 `aria-disabled`),Tab 走 roving tabIndex 整個 grid 只停一格。
 - **Dark mode**:走 semantic token(primary / neutral / fg-muted)自動 adapt。
-- **Density**:DateGrid day cell 走 `h-field-sm w-[var(--field-height-sm)]`,**隨 density 縮放**(md = 28×28 / lg = 32×32,token `--field-height-sm` 在 `[data-density="lg"]` override 為 `2rem`),跟 popup 內 Input / Button 等 field 家族一起放大保持比例(見 L128 + L120)。
+- **Density**:DateGrid day cell 走 `h-field-sm w-[var(--field-height-sm)]`,**隨 density 縮放**(md = 28×28 / lg = 32×32,token `--field-height-sm` 在 `[data-density="lg"]` override 為 `2rem`),跟 popup 內 Input / Button 等 field 家族一起放大保持比例(見 L128 + L120)。grid 寬度為 intrinsic(7 × cell + 4px gap + `p-3`),lg 下整體變寬;DateGrid 無內部 overflow / responsive 縮排機制,容器(Popover / parent)以內容寬呈現。
 
 ---
 

package/src/components/DateGrid/date-grid.tsx

@@ -1,3 +1,7 @@
+/**
+ * @internal — DS-internal 單元(per `.claude/rules/ui-development.md` Public vs Internal canonical;spec frontmatter `isInternal`)。
+ * 不進 root barrel front-door;由 DatePicker wrap 消費,end-user app 請用 wrapper 元件。
+ */
 // @benchmark-unverified-blanket: file-level retraction per M22 (d) — claims herein not individually URL-cited; treat as unverified visual/usage rumor unless retrofit per-claim. Hook escape preserved.
 // M22 retrofit DONE 2026-05-03 v11(real source URLs added inline at lines 38 + 111)
 import * as React from 'react'
@@ -17,8 +21,8 @@ import { Button } from '@/design-system/components/Button/button'
  * |------|------|
  * | Outer padding | `p-3`(12px 四邊對稱) |
  * | Nav + Month caption row | h-field-xs(24px)單行,chevron(xs)分居左右 / 月份置中垂直對齊 |
- * | Nav → Weekday gap | 12px(mt-3) |
- * | Weekday | text-body(14px)text-fg-secondary(neutral-8) |
+ * | Nav → Weekday gap | 12px(month_caption mb-3) |
+ * | Weekday | text-body(14px)text-foreground font-medium(neutral-9,同 caption 權重;撤銷 v3 fg-secondary) |
  * | Cell gap(水平 + 垂直)| 4px(gap-1) |
  * | Day cell size | h-field-sm w-[var(--field-height-sm)](28×28 md / 32×32 lg) |
  * | Day button | rounded-full 填滿 cell |
@@ -200,8 +204,8 @@ export const dateGridMeta = {
   },
   states: ['default', 'hover', 'active', 'focus-visible', 'disabled'],
   tokens: {
-    bg: ['bg-disabled', 'bg-primary', 'bg-primary-hover', 'bg-transparent'],
-    fg: ['text-fg-disabled', 'text-fg-muted', 'text-fg-secondary', 'text-foreground'],
+    bg: ['bg-disabled', 'bg-neutral-selected', 'bg-on-emphasis', 'bg-primary', 'bg-primary-hover', 'bg-transparent'],
+    fg: ['text-fg-disabled', 'text-fg-muted', 'text-foreground', 'text-on-emphasis'],
     ring: ['ring-primary', 'ring-ring'],
   },
 } as const