@qijenchen/design-system 0.1.0-beta.76 → 0.1.0-beta.79

package/src/components/Tabs/tabs.spec.md

@@ -185,6 +185,8 @@ Tabs 是 **navigation anchor**，不是 compact control：
 
 **TabsContent 與 TabsList 間距(2026-06-12 user 拍板)**:`--layout-space-tight`(md 12px,density 連動),**內建於 TabsContent**(`mt-[var(--layout-space-tight)]`,className 可覆寫;full-height 佈局用 `mt-0`)。依 `layoutSpace.spec`「親疏 3 級」第一級(同 bundle,元件 spec own)+ 規則 3「直接功能依賴 = tight」精神;**不**取 Ant 的固定 16px(M23 自家 token 優先)。內容本身的排版歸 item-anatomy / 各內容元件管,本條只管 list↔content gap。
 
+> ⚠️ **此預設只在 TabsContent 緊接 tab bar 當直接 sibling 時成立**(standalone 頁面 tabs、ChromeHeader-as-sibling)。當 `tabsSlot` composition 把 tab bar 抬進 chrome header、TabsContent 留在 `DialogBody`/`SheetBody`/`SurfaceBody`(chrome scroll body,已自帶 `pt-/py-[var(--layout-space-tight)]`)內時,body 已擁有 header→content gap,TabsContent 的預設 `mt-tight` 會**雙重疊加**(md 24 / lg 32)。此時 TabsContent **必 `className="mt-0"`** 把 ownership 轉移給 body — 詳見下方「出現在 Dialog」段。一軸單一 spacing owner,per `item-anatomy.spec.md`「垂直 padding 歸屬 / 禁雙重 padding」。Hook `check_tabs_content_chrome_body_double_gap.sh` 機械強制。
+
 ---
 
 ## Underline 與 TabsList border 的視覺關係
@@ -219,6 +221,8 @@ Tabs 常與容器 header 的底邊 border 合併——**視覺上只有一條線
 
 Size 建議:overlay / chrome header 內用 `sm`(32/40)— 對應 close X 也是 sm,視覺一致;**獨立取代 chrome header** 的 page-level workspace tabs 用 `lg`(48/56,= chrome-header-height)。
 
+**間距 ownership**:tabsSlot 模式下 `TabsContent` 放 `DialogBody`/`SheetBody`/`SurfaceBody`(自帶 `pt-/py-tight`)內時**必 `className="mt-0"`** — body 已擁有 header→content gap,TabsContent 預設 `mt-tight` 會雙重(md 24 / lg 32,2026-07-01 user 抓)。詳「TabsContent 與 TabsList 間距」段;hook `check_tabs_content_chrome_body_double_gap.sh` 強制。
+
 ---
 
 ## 狀態

package/src/components/Tag/tag.tsx

@@ -68,6 +68,8 @@ export interface TagProps
   avatar?: React.ReactNode
   /** 可移除——Tag 自動渲染 remove 按鈕並控制尺寸與互動樣式(從集合移除 item) */
   onRemove?: () => void
+  /** remove 按鈕的 aria-label 目標名(a11y)。children 為非字串 ReactNode 時建議傳,否則 SR 讀不出移除哪個 tag。預設取 string children。 */
+  dismissLabel?: string
   /** 深底模式（step-6 背景 + on-emphasis 配對前景;亮色 hue yellow/amber/orange/lime 用深字 --on-emphasis-dark,green 白字例外） */
   solid?: boolean
   /**
@@ -107,7 +109,7 @@ function TagDismiss({ onRemove, label, solid, color }: { onRemove: () => void; l
       icon={X}
       size="md"
       onClick={(e) => { e.stopPropagation(); onRemove() }}
-      aria-label={`移除 ${label}`}
+      aria-label={label ? `移除 ${label}` : '移除'}
       style={solidColors ? ({ '--dismiss-hover': solidColors.hover, '--dismiss-active': solidColors.active } as React.CSSProperties) : undefined}
       hoverBgClassName={
         solidColors
@@ -121,7 +123,7 @@ function TagDismiss({ onRemove, label, solid, color }: { onRemove: () => void; l
 }
 
 function TagInner(
-  { className, color, size, icon: Icon, avatar, onRemove, solid, unbounded = false, children, style, ...props }: TagProps,
+  { className, color, size, icon: Icon, avatar, onRemove, dismissLabel, solid, unbounded = false, children, style, ...props }: TagProps,
   forwardedRef: React.ForwardedRef<HTMLDivElement>,
 ) {
   const solidClass = solid ? SOLID_CLASSES[color ?? 'neutral'] : undefined
@@ -178,7 +180,7 @@ function TagInner(
       {Icon && <Icon size={16} aria-hidden />}
       {avatar && <span className="shrink-0 w-4 h-4 rounded-full overflow-hidden inline-grid place-content-center [&>*]:w-full [&>*]:h-full">{avatar}</span>}
       <span data-tag-text="" className="px-1 truncate min-w-0">{children}</span>
-      {onRemove && <TagDismiss onRemove={onRemove} label={label} solid={solid} color={color ?? 'neutral'} />}
+      {onRemove && <TagDismiss onRemove={onRemove} label={dismissLabel || label} solid={solid} color={color ?? 'neutral'} />}
     </div>
   )
 

package/src/components/TimePicker/time-columns.tsx

@@ -106,6 +106,11 @@ function TimeColumn({ values, selected, disabledSet, label, onSelect, withDivide
     isFirstRunRef.current = false
   }, [values, selected])
 
+  // a11y:穩定 id 前綴,讓 listbox `aria-activedescendant` 指向目前 active(= selected)option。
+  // single-tabstop + 方向鍵 listbox 應透過 activedescendant 告知 AT 哪個 option active,
+  // 否則 SR 方向鍵移動時讀不出目前 option(WAI-ARIA listbox virtual-focus 慣例)。
+  const baseId = React.useId()
+
   // WAI-ARIA listbox keyboard pattern:ArrowUp/Down 切 option / Home / End 跳邊界。
   // 對標 Ant TimePicker / Material TimePicker。Tab 跳離 listbox(走預設行為,不 stopPropagation)。
   const handleKeyDown = (e: React.KeyboardEvent<HTMLDivElement>) => {
@@ -147,6 +152,7 @@ function TimeColumn({ values, selected, disabledSet, label, onSelect, withDivide
         ref={listRef}
         role="listbox"
         aria-label={label}
+        aria-activedescendant={selected != null ? `${baseId}-opt-${selected}` : undefined}
         tabIndex={0}
         onKeyDown={handleKeyDown}
         className="flex flex-col py-2 focus-visible:outline-2 focus-visible:outline-ring focus-visible:outline-offset-[-2px]"
@@ -157,6 +163,7 @@ function TimeColumn({ values, selected, disabledSet, label, onSelect, withDivide
           return (
             <button
               key={v}
+              id={`${baseId}-opt-${v}`}
               type="button"
               role="option"
               aria-selected={isSelected}

package/src/components/TreeView/tree-view.tsx

@@ -90,10 +90,11 @@ export interface TreeDragEndEvent {
 // Icon / chevron 尺寸——從 item-layout pattern module 引入(在檔頂 import),
 // 這裡本地不再宣告。所有 row primitives 共用同一個常數。
 
-// indentStep = chevronSize + gap-2(8px)— 2026-05-04 升 SSOT 為 token `--tree-indent-{sm,md,lg}`
-// 在 `tokens/uiSize/uiSize.css`。DataTable nested rows 共用此 SSOT,跨元件視覺一致。
-// 結構對齊:子 chevron 對齊父 icon,子 icon 對齊父 label。
-// Numeric value 此處保留(drop indicator JS px 計算需 number),Tailwind class 走 token。
+// indentStep = chevronSize + gap-2(8px)。值 {24,24,28} 與 CSS token `--tree-indent-{sm,md,lg}`
+// (`tokens/uiSize/uiSize.css`)**完全一致、必須同步維護**(改一處要兩處一起改;非「token 取代 literal」)。
+// 為何兩源並存:本元件 render 用此 JS literal 算 `indentPx`(L808 inline calc 需 number)+ drop-indicator
+// pointer 數學(L352,需 number 做 px 命中判斷,CSS var 在 JS 計算層拿不到);DataTable nested rows
+// 則走 CSS token 的 Tailwind class(跨元件視覺一致)。結構對齊:子 chevron 對齊父 icon,子 icon 對齊父 label。
 const INDENT_STEP: Record<SizeKey, number> = { sm: 24, md: 24, lg: 28 }
 
 // ═══════════════════════════════════════════════════════════════════════════

package/src/patterns/element-anatomy/item-anatomy.spec.md

@@ -245,6 +245,8 @@ Row 集合是**內容(content)**,不是區段(region)。加 py 到 row 集合會
 
 **曾經發生的 bug**:TreeView 原本硬寫 `py-2`,放進 `SidebarGroup`(也有 `py-2`)導致 label 和 first tree item 之間多出 8px 無法解釋的 gap;後來改成「只有 menu context 加 py-2」,結果 story 的 bordered wrapper 不屬於 menu context,items 貼邊。最終解法:TreeView root 一律不加 py,所有外層容器自己負責。
 
+**同源 invariant(不只 row 集合)**:「一軸單一 spacing owner」也適用元件的**單一 margin**跨 composition boundary。2026-07-01:`TabsContent` 內建 `mt-[var(--layout-space-tight)]`(tab bar 下方間距),`tabsSlot` 模式把 tab bar 抬進 chrome header 後 TabsContent 留在 `DialogBody`(自帶 `pt-tight`)內 → header→content gap 兩個 owner 疊加 = 雙重 tight(「專案名稱」上方 md 24 / lg 32)。解法同上:chrome body 已擁有 gap,TabsContent 加 `mt-0` 轉移 ownership。詳 `components/Tabs/tabs.spec.md`「出現在 Dialog」段 + hook `check_tabs_content_chrome_body_double_gap.sh`。
+
 ### 實作規則
 
 - 寫 row 集合元件(新 tree / menu / list)時,**root div 不加 py**

package/src/tokens/layoutSpace/layoutSpace.spec.md

@@ -145,6 +145,23 @@ Pattern C 的視覺邏輯見 `overlay-surface.spec.md`「Hover bg 貼邊 chrome
 
 ---
 
+## 該用 token(縮放)vs 刻意固定(magic number 合法)的邊界(2026-07-01 codify)
+
+**核心**:layout-space token(density-scaling)只管 **macro 結構間距**;**不是所有 px 都該 token 化**。硬把刻意固定值 token 化 = over-tokenize(反 pattern,跟「硬寫該縮放的 gap」同樣是 bug 的反面)。
+
+| 該用 layout-space token(density-scaling) | 刻意固定值 OK(magic number 合法) |
+|---|---|
+| 並列獨立 **區塊 / 卡片 / 表單欄位** 之間(規則 3 parallel = loose)| **同質 list 的列間距**(一串同類 rows,規則 3「同範疇 spec-own」)|
+| **Header → 內容**(規則 2 = tight)| **micro / icon / 控件內部** 間距(gap-1/2、icon padding)|
+| **Chrome 水平內距**(規則 6 = loose)| **為視覺平衡 / 對稱 刻意調的值**(設計裁量)|
+| **內容 → action button**(規則 4 = bottom 48)| **元件自身刻意固定**(如 FieldGroup 三級固定 gap,不隨 density)|
+
+**判準一句話**:是「並列/區塊/chrome/header→content/content→action 的 macro 結構間距、規則說該縮放」→ 用 token;是「list 列間距 / micro / 刻意固定 / 元件內部決定」→ magic number 合法,**不要 token 化**。
+
+**機械強制**:`check_tabs_content_chrome_body_double_gap.sh` Check 2 抓「浮層 body 自身固定 macro gap」(明確 pattern);判斷題(這是並列還是 list?macro 還是 micro?)靠 **週期 LLM sweep**(`/design-system-audit` dim「layout-space macro 合規」)—— 純 regex 分不出,不硬機械化(否則 over-flag 合法 magic number)。
+
+---
+
 ## 心智模型(三步推理 + 具體 self-questions)
 
 ### Step 1 — 判角色(對單一元素)
@@ -290,6 +307,7 @@ document.documentElement.setAttribute('data-layout-space', 'lg')
 
 - **不抽 universal LayoutBody / FormLayout primitive**:world-class(Material / Polaris / Atlassian / Carbon / Mantine)都「每元件 own variant + 共享 token」;規則 1-6 universal,角色 scope-relative 易誤封裝。獨特 chrome 已在 `overlay-surface.spec.md` + `action-bar.spec.md`
 - **List-as-region in overlay body**(2026-05-01 canonical):當 Dialog / Sheet / Popover body 內容 = unbounded list-as-region(menu / Cmd+K / nav)時,consumer 用 className override 撤掉 chrome padding(`<DialogBody className="!px-0 !pt-0 !pb-0">`)+ 自管 list outer wrapper(`<div className="py-2">`)+ item 自帶 `px-loose rounded-md`。**不做成 body variant**(`flush?: boolean`)— Material/Atlassian/Mantine/shadcn 都 consumer 自管,Polaris flush API scope 極窄;variant 不解決底層脆弱(加 1 row search/banner 就破功),反把 1 surface decision 拆兩 API。詳 `overlay-surface.spec.md`「List-as-region in overlay body」+ `dialog.tsx:165` JSDoc
+- **Tabs-in-chrome-body 單一 gap owner**(2026-07-01 canonical):`tabsSlot` 模式下 `TabsContent` 放進 `DialogBody`/`SheetBody`/`SurfaceBody`(自帶 `pt-/py-tight`)時**必 `className="mt-0"`** — chrome body 已擁有 header→content gap(規則 2「element → tight」),TabsContent 內建 `mt-tight` 會雙重疊加(md 24 / lg 32)。同「一軸單一 spacing owner」原則(`item-anatomy.spec.md`「垂直 padding 歸屬 / 禁雙重 padding」)。詳 `components/Tabs/tabs.spec.md`「出現在 Dialog」段 + hook `check_tabs_content_chrome_body_double_gap.sh`
 - **v1 → v6**(2026-04-30):block-adjacent 機械 → 親疏判 + bundled-family 分權 + region 二分(bounded/unbounded)+ 多 region 限制。詳 git + memory `feedback_layout_v6_canonical.md`
 
 ---