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

package/src/components/Select/select.anatomy.stories.tsx

@@ -47,11 +47,11 @@ const TOKEN_MAP: Record<ModeKey, Record<StateKey, ColorSpec>> = {
   },
   // readonly wrapper 為靜態 bg-readonly(field-wrapper.tsx 無 hover/focus 樣式;mode prop 勝 disabled)
   readonly: {
-    default:  { bg: '--bg-readonly', text: '--foreground',  border: 'transparent', icon: '--fg-muted' },
-    hover:    { bg: '--bg-readonly', text: '--foreground',  border: 'transparent', icon: '--fg-muted' },
-    focus:    { bg: '--bg-readonly', text: '--foreground',  border: 'transparent', icon: '--fg-muted' },
-    error:    { bg: '--bg-readonly', text: '--foreground',  border: 'transparent', icon: '--fg-muted' },
-    disabled: { bg: '--bg-readonly', text: '--foreground',  border: 'transparent', icon: '--fg-muted' },
+    default:  { bg: '--bg-readonly', text: '--foreground',  border: 'transparent', icon: '—' },
+    hover:    { bg: '--bg-readonly', text: '--foreground',  border: 'transparent', icon: '—' },
+    focus:    { bg: '--bg-readonly', text: '--foreground',  border: 'transparent', icon: '—' },
+    error:    { bg: '--bg-readonly', text: '--foreground',  border: 'transparent', icon: '—' },
+    disabled: { bg: '--bg-readonly', text: '--foreground',  border: 'transparent', icon: '—' },
   },
   disabled: {
     default:  { bg: '--bg-disabled', text: '--fg-disabled', border: 'transparent', icon: '--fg-disabled' },
@@ -86,7 +86,7 @@ interface SizeSpec {
 const SIZE_SPECS: Record<SizeKey, SizeSpec> = {
   sm: {
     heightToken: 'h-field-sm', height: '28px',
-    pxToken: 'px-3', px: '12px',
+    pxToken: 'px-[var(--field-px)]', px: '12px',
     gapToken: 'gap-2', gap: '8px',
     fontToken: 'text-body', font: '14px',
     icon: 16,
@@ -95,7 +95,7 @@ const SIZE_SPECS: Record<SizeKey, SizeSpec> = {
   },
   md: {
     heightToken: 'h-field-md', height: '32px',
-    pxToken: 'px-3', px: '12px',
+    pxToken: 'px-[var(--field-px)]', px: '12px',
     gapToken: 'gap-2', gap: '8px',
     fontToken: 'text-body', font: '14px',
     icon: 16,
@@ -104,7 +104,7 @@ const SIZE_SPECS: Record<SizeKey, SizeSpec> = {
   },
   lg: {
     heightToken: 'h-field-lg', height: '36px',
-    pxToken: 'px-3', px: '12px',
+    pxToken: 'px-[var(--field-px)]', px: '12px',
     gapToken: 'gap-2', gap: '8px',
     fontToken: 'text-body-lg', font: '16px',
     icon: 20,
@@ -271,7 +271,7 @@ export const Overview = {
               <span className="rounded px-2 py-1 text-[11px] font-mono border border-dashed"
                 style={{ borderColor: 'var(--color-turquoise-6)', backgroundColor: 'var(--color-turquoise-1)', color: 'var(--color-turquoise-6)' }}>Tag</span>
             </div>
-            <span className="text-[10px] text-fg-muted font-mono">chevron 恆顯(類型身份 indicator)· 不可開選單 · tagPadding 置中</span>
+            <span className="text-[10px] text-fg-muted font-mono">chevron:readonly 不顯示 / disabled 保留(類型身份 indicator)· 不可開選單 · tagPadding 置中</span>
           </div>
         </div>
       </div>
@@ -437,7 +437,7 @@ const InspectorInner = () => {
                     { c: Z.gap, l: '元素間距' },
                     { c: Z.select, l: 'Select 文字' },
                     ...(clearable && value ? [{ c: Z.action, l: 'Clear' }] : []),
-                    { c: Z.icon, l: 'Chevron' },
+                    ...(mode !== 'readonly' ? [{ c: Z.icon, l: 'Chevron' }] : []),
                   ].map(({ c, l }) => (
                     <span key={l} className="inline-flex items-center gap-1">
                       <span className="w-2.5 h-2.5 rounded-md" style={{ background: c.bg, border: `1px dashed ${c.border}` }} />
@@ -452,7 +452,7 @@ const InspectorInner = () => {
                     {hasStartIcon && <BpZone w={32} color={Z.gap} label={s.gapToken} sub={s.gap} />}
                     <BpZone w={80} color={Z.select} label="flex-1" sub="select 文字" />
                     {clearable && value && <BpZone w={36} color={Z.action} label={`${s.icon}px`} sub="clear" />}
-                    <BpZone w={36} color={Z.icon} label={`${s.icon}px`} sub="chevron" />
+                    {mode !== 'readonly' && <BpZone w={36} color={Z.icon} label={`${s.icon}px`} sub="chevron" />}
                     <BpZone w={44} color={Z.pad} label={s.pxToken} sub={s.px} />
                   </div>
                   <div className="ml-3 flex items-center" style={{ height: 52 }}>
@@ -475,7 +475,7 @@ const InspectorInner = () => {
                     { c: Z.select, l: 'Select (hidden)' },
                     { c: Z.gap, l: 'Spacer' },
                     ...(clearable && value ? [{ c: Z.action, l: 'Clear' }] : []),
-                    { c: Z.icon, l: 'Chevron' },
+                    ...(mode !== 'readonly' ? [{ c: Z.icon, l: 'Chevron' }] : []),
                   ].map(({ c, l }) => (
                     <span key={l} className="inline-flex items-center gap-1">
                       <span className="w-2.5 h-2.5 rounded-md" style={{ background: c.bg, border: `1px dashed ${c.border}` }} />
@@ -490,7 +490,7 @@ const InspectorInner = () => {
                     <BpZone w={40} color={Z.select} label="select" sub="hidden" />
                     <BpZone w={36} color={Z.gap} label="flex-1" sub="spacer" />
                     {clearable && value && <BpZone w={36} color={Z.action} label={`${s.icon}px`} sub="clear" />}
-                    <BpZone w={36} color={Z.icon} label={`${s.icon}px`} sub="chevron" />
+                    {mode !== 'readonly' && <BpZone w={36} color={Z.icon} label={`${s.icon}px`} sub="chevron" />}
                     <BpZone w={44} color={Z.pad} label="12px" sub="pR fixed" />
                   </div>
                   <div className="ml-3 flex items-center" style={{ height: 52 }}>
@@ -520,7 +520,7 @@ const InspectorInner = () => {
             <PropRow label="Fill"><TokenValue value={colors.bg} /></PropRow>
             <PropRow label="Text"><TokenValue value={colors.text} /></PropRow>
             <PropRow label="Stroke"><TokenValue value={colors.border} /></PropRow>
-            <PropRow label="Icon"><TokenValue value={colors.icon} /></PropRow>
+            {mode !== 'readonly' && <PropRow label="Icon"><TokenValue value={colors.icon} /></PropRow>}
           </div>
 
           {/* LAYOUT */}
@@ -530,14 +530,14 @@ const InspectorInner = () => {
             {isTag ? (
               <>
                 <PropRow label="tagPadding" dot={Z.pad.text}><TkVal token="calc()" value={s.tagPaddingFormula} /></PropRow>
-                <PropRow label="右側 pR"><TkVal token="0.75rem" value="12px" /></PropRow>
+                <PropRow label="右側 pR"><TkVal token="var(--field-px)" value="12px" /></PropRow>
                 <PropRow label="Tag 高度" dot={Z.tag.text}>{s.tagHeight}</PropRow>
               </>
             ) : (
               <PropRow label="左右內距" dot={Z.pad.text}><TkVal token={s.pxToken} value={s.px} /></PropRow>
             )}
             <PropRow label="元素間距" dot={Z.gap.text}><TkVal token={s.gapToken} value={s.gap} /></PropRow>
-            <PropRow label="Icon 尺寸" dot={Z.icon.text}>{s.icon}px</PropRow>
+            {mode !== 'readonly' && <PropRow label="Icon 尺寸" dot={Z.icon.text}>{s.icon}px</PropRow>}
           </div>
 
           {/* TYPOGRAPHY */}
@@ -722,7 +722,7 @@ export const SizeMatrix = {
       {/* ── tag mode additional tokens ── */}
       <div className="flex flex-col gap-2">
         <span className="text-caption font-medium text-fg-secondary">tag 模式額外 token</span>
-        <Desc>tag 模式的 padding 用 calc() 公式置中 Tag：px = (field-height - tag-height) / 2。右側 paddingRight 固定 12px（0.75rem）。</Desc>
+        <Desc>tag 模式的 padding 用 calc() 公式置中 Tag：px = (field-height - tag-height) / 2。右側 paddingRight 固定 12px（--field-px token）。</Desc>
         <div className="overflow-x-auto">
           <table className="border-collapse text-caption">
             <thead><tr>
@@ -752,7 +752,7 @@ export const SizeMatrix = {
                 <Td>paddingRight</Td>
                 {SIZES.map((sz) => (
                   <Td key={sz} mono>
-                    <div className="text-fg-secondary">0.75rem</div>
+                    <div className="text-fg-secondary">var(--field-px)</div>
                     <div className="text-fg-muted text-[10px]">12px（固定）</div>
                   </Td>
                 ))}

package/src/components/Select/select.spec.md

@@ -240,7 +240,7 @@ Select 的值套用時機是**由 onChange handler 的副作用決定**，不是
 - Tag 元件呈現選中值 + 隱藏的原生 select overlay
 - Tag 設為 `pointer-events-none`，點擊穿透到底層 select
 - edit 模式：Tag + ChevronDown + 可選 clear
-- readonly / disabled：Tag 顯示 + ChevronDown 恆顯(類型身份 indicator;readonly fg-muted / disabled fg-disabled),不可開選單
+- readonly：Tag 顯示，**ChevronDown 不顯示**（純值、不可開選單）；disabled：Tag 顯示 + **ChevronDown 保留**（類型身份 indicator，fg-disabled），不可開選單
 
 ---
 

package/src/components/Select/select.tsx

@@ -327,12 +327,12 @@ function ReadonlyDisplay({
     )
   }
 
-  // 2026-06-10 user 拍板「類型身份 indicator」規則:readonly/disabled 保留 ChevronDown(表單情境恆顯;
-  // naked cell 情境依 showDisplayEndIcon = isEditable,維持 2026-05-10 cell canonical「非可編欄不顯」)。
-  // disabled → fg-disabled(對齊 spec L213 + Accordion M24 precedent + 原生 select/MUI/Carbon 慣例)。
+  // 2026-06-26 類型身份 indicator 規則:edit 顯示 / readonly 不顯示(純值、不可開下拉,箭頭會誤導) /
+  // disabled 保留(fg-disabled,對齊原生 <select disabled> 灰示箭頭 + Accordion M24 precedent)。
+  // naked cell 情境依 showDisplayEndIcon = isEditable,維持 2026-05-10 cell canonical「非可編欄不顯」。
   // aria-disabled:styled-disabled(非 native disabled 元素)需明告 AT「inactive」,同時讓 axe 正確
   // 豁免 disabled 文字的 color-contrast(WCAG 1.4.3 inactive UI 例外)。
-  const showIndicator = variant === 'naked' ? !!showDisplayEndIcon : true
+  const showIndicator = variant === 'naked' ? !!showDisplayEndIcon : resolvedMode === 'disabled'
   const ariaDisabled = resolvedMode === 'disabled' ? true : undefined
 
   if (isTextDisplay) {
@@ -351,7 +351,7 @@ function ReadonlyDisplay({
   const tagVariant = selectedOpt?.tagVariant as 'blue' | 'green' | 'red' | 'yellow' | 'neutral' | undefined
 
   return (
-    <div className={cn(fieldWrapperStyles({ mode: resolvedMode, variant, size: sz }), value && tagPadding[sz], className)} data-field-mode={resolvedMode} aria-disabled={ariaDisabled}>
+    <div className={cn(fieldWrapperStyles({ mode: resolvedMode, variant, size: sz }), value && tagPadding[sz], className)} style={{ paddingRight: 'var(--field-px)' }} data-field-mode={resolvedMode} aria-disabled={ariaDisabled}>
       {value ? <Tag size={sz} color={tagVariant}>{label}</Tag> : <span className={emptyColorCls}>{emptyText}</span>}
       {showIndicator && <ItemSuffix className="pointer-events-none"><ChevronDown size={iconSize} className={cn('shrink-0', iconColor)} aria-hidden /></ItemSuffix>}
     </div>
@@ -429,7 +429,7 @@ const NativeSelect = React.forwardRef<HTMLSelectElement, SelectProps>(
       return (
         <div className={cn(fieldWrapperStyles({ mode: 'edit', variant: variant, size }), value && tagPadding[size], 'relative',
           error && ['border-error hover:border-error-hover', 'focus-within:border-error focus-within:hover:border-error'], className)}
-          style={{ paddingRight: '0.75rem' }} data-field-mode="edit" data-error={error ? '' : undefined}>
+          style={{ paddingRight: 'var(--field-px)' }} data-field-mode="edit" data-error={error ? '' : undefined}>
           {value ? <Tag size={size} color={nativeTagVariant} className="shrink-0 relative z-10 pointer-events-none">{label}</Tag> : <span className="text-fg-muted">{placeholder ?? '選擇...'}</span>}
           {selectEl}
           <span className="flex-1" />
@@ -599,7 +599,7 @@ const CustomSelect = React.forwardRef<HTMLDivElement, SelectProps>(
           'cursor-pointer',
           className,
         )}
-        style={!isTextDisplay ? { paddingRight: '0.75rem' } : undefined}
+        style={!isTextDisplay ? { paddingRight: 'var(--field-px)' } : undefined}
         data-field-mode="edit"
         data-error={error ? '' : undefined}
         onKeyDown={(e) => {

package/src/components/SelectMenu/select-menu.anatomy.stories.tsx

@@ -806,7 +806,7 @@ export const Accessibility = {
   render: () => (
     <div className="max-w-3xl text-body text-fg-secondary">
       <h3 className="text-h5 text-foreground mb-2">無障礙設計</h3>
-      <p className="whitespace-pre-line">{"詳 `select-menu.spec.md` 「A11y 預設」段。摘要:\n\n  ARIA / Pattern  :基於  cmdk  library a11y(combobox / listbox / option role + aria-activedescendant)。詳 [cmdk a11y](https://cmdk.paco.me/#accessibility)。\n\n  Keyboard 行為  :\n\n- Tab — focus trigger\n- Enter / Space — 開啟 menu(trigger 由 consumer 經 PopoverTrigger asChild 提供:Select / Combobox 的 trigger 是 role=\"combobox\" 容器自綁 Enter / Space handler;若 consumer 用 DS Button 則由 native click 觸發)\n- ↑/↓ — 導覽 options(menu 開啟後)\n- Enter — 選擇\n- 字母鍵 — type-ahead 過濾(search 模式)\n- Esc — 關閉\n\n  Focus  :menu 開啟時 active-descendant 虛擬焦點落在第一個 / 已選 option(aria-activedescendant 高亮,非 DOM focus);searchable 時 DOM focus 給搜尋 input;option 無 tabIndex,DOM focus 不落在 option 上。關閉時 focus 回 trigger。\n\n  驗證  :Storybook a11y addon panel 應 0 critical violation;鍵盤完整可操作(無需滑鼠)。WCAG AA contrast ≥ 4.5:1(text)/ 3:1(UI)。"}</p>
+      <p className="whitespace-pre-line">{"詳 `select-menu.spec.md` 「A11y 預設」段。摘要:\n\n  ARIA / Pattern  :基於  cmdk  library a11y(combobox / listbox / option role + aria-activedescendant)。詳 [cmdk a11y](https://cmdk.paco.me/#accessibility)。\n\n  Keyboard 行為  :\n\n- Tab — focus trigger\n- Enter / Space — 開啟 menu(trigger 由 consumer 經 PopoverTrigger asChild 提供:Select / Combobox 的 trigger 是 role=\"combobox\" 容器自綁 Enter / Space handler;若 consumer 用 DS Button 則由 native click 觸發)\n- ↑/↓ — 導覽 options(menu 開啟後)\n- Enter — 選擇\n- 字母鍵 — type-ahead 過濾(search 模式)\n- Esc — 關閉\n\n  Focus  :menu 開啟時 active-descendant 虛擬焦點落在第一個 / 已選 option(aria-activedescendant 高亮,非 DOM focus);searchable 時 DOM focus 給搜尋 input;非 searchable 時 DOM focus 移到 cmdk 的 [cmdk-root](Command 元素,見 handleNonSearchableAutoFocus),讓 cmdk 內建方向鍵 / Enter / Home / End 導覽生效;option 無 tabIndex,DOM focus 不落在 option 上。關閉時 focus 回 trigger。\n\n  驗證  :Storybook a11y addon panel 應 0 critical violation;鍵盤完整可操作(無需滑鼠)。WCAG AA contrast ≥ 4.5:1(text)/ 3:1(UI)。"}</p>
     </div>
   ),
 }

package/src/components/Sidebar/sidebar.spec.md

@@ -74,7 +74,7 @@ benchmark:
 
 ```
 SidebarProvider              ← 全域 context（open 狀態、cookie、快捷鍵）
-  Sidebar                    ← 主容器（variant + collapsible + side）
+  Sidebar                    ← 主容器（collapsible + side + viewportInsetTop）
     SidebarHeader            ← 頂部：logo、workspace switcher
     SidebarContent           ← 中間可捲動區
       SidebarGroup           ← 分組容器（可多個，純視覺分段）
@@ -83,7 +83,7 @@ SidebarProvider              ← 全域 context（open 狀態、cookie、快捷
           │
           ├─ SidebarMenu           扁平選單（1 層、有限可列舉）
           │    SidebarMenuItem
-          │      SidebarMenuButton   ← 必須有 icon
+          │      SidebarMenuButton   ← icon 模式下 consumer 應確保每個 item 有 icon（否則 collapsed rail 出現空槽；非元件強制）
           │      SidebarMenuBadge    ← 右側 badge
           │      SidebarMenuAction   ← hover 浮出的 action
           │

package/src/components/Slider/slider.anatomy.stories.tsx

@@ -43,7 +43,7 @@ export const Overview: Story = {
                 ['min / max', 'number', '0 / 100', '值範圍'],
                 ['step', 'number', '1', '步進'],
                 ['size', "'sm' | 'md' | 'lg'", "'md'", '**只影響容器外高**,不影響 track/thumb 尺寸'],
-                ['disabled', 'boolean', 'false', '灰階降級(range/thumb border→border,thumb bg 保留白)'],
+                ['disabled', 'boolean', 'false', '灰階降級(range/thumb border→border,thumb bg 沉回 bg-canvas(不透明背景色))'],
                 ['minStepsBetweenThumbs', 'number', '—', 'range mode 兩 thumb 最小距離'],
               ].map(([p, t, d, desc]) => (
                 <tr key={p}><Td mono>{p}</Td><Td mono>{t}</Td><Td mono>{d}</Td><Td>{desc}</Td></tr>

package/src/components/Steps/steps.spec.md

@@ -80,7 +80,7 @@ Steps 是 `patterns/element-anatomy/item-anatomy.spec.md` 的 row primitive **co
 - **字體 tier**:label `text-body` (sm/md) / `text-body-lg` (lg);description `text-caption` (sm/md) / `text-body` (lg)。跟 MenuItem / TreeItem 同一套。
 - **字重**:`font-medium`(含 label,不隨 focus 變)
 - **預設文字色**:`text-fg-secondary`;`value` 指向的 step(focused)為 `text-foreground`
-- **Icon tier**:`ICON_SIZE = { sm: 16, md: 16, lg: 20 }`
+- **Icon tier**:`INDICATOR_ICON_SIZE = { sm: 0, md: 16, lg: 20 }`(sm 為純圓點無內部 icon,見 size table)
 - **Description 永遠可選**,任何 size 都不強制
 - **Hit area 地板**:可點擊的 indicator 至少 `field-height-xs`(24px),不足者用透明 padding 撐開
 
@@ -172,7 +172,7 @@ indicator 圓形 flex items-center 居中
 
 | State | 視覺 | 觸發 |
 |---|---|---|
-| `upcoming` | 灰底(`bg-muted`)+ 灰字(`text-fg-disabled`)| 未走到 |
+| `upcoming` | 灰底(inline `background: var(--muted)`)+ 灰字(`text-fg-disabled`)| 未走到 |
 | `current` | 藍底(`bg-info`)+ 白字數字 | step === `value` 且不在 completedValues / errorValues |
 | `completed` | 藍底(`bg-info`)+ 白色 ✓ | step 在 `completedValues` 內 |
 | `reachable` | 藍底(`bg-info`)+ 白字數字(僅 linear;sm 為空心環)| linear 下「下一個未完成」step(非 current / completed / error),可點 |

package/src/components/Tabs/tabs.principles.stories.tsx

@@ -57,7 +57,7 @@ export const UsageGuidance: Story = {
               <LinkTo kind="Design System/Components/Tabs/展示" name="溢出處理 — 水平捲動"><span className="text-primary hover:text-primary-hover font-medium cursor-pointer">溢出處理 — 水平捲動</span></LinkTo>
             </li>
             <li>
-              <LinkTo kind="Design System/Components/Tabs/展示" name="溢出處理 — ⌄ 導覽選單"><span className="text-primary hover:text-primary-hover font-medium cursor-pointer">溢出處理 — 收進選單</span></LinkTo>
+              <LinkTo kind="Design System/Components/Tabs/展示" name="溢出處理 — ⌄ 導覽選單"><span className="text-primary hover:text-primary-hover font-medium cursor-pointer">溢出處理 — ⌄ 導覽選單</span></LinkTo>
             </li>
           </ul>
           <p className="text-fg-muted mt-3">判斷不確定時:對照 spec.md「何時用 / 何時不用」段;若仍不符,改用近親元件(見下方「vs 近親」)。</p>

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

@@ -207,7 +207,7 @@ TabsList 底部有 1px gray border（`border-divider`，neutral-4），selected
 
 Tabs 常與容器 header 的底邊 border 合併——**視覺上只有一條線**,不是 header border + tabs border 疊兩條。
 
-**做法**:Tabs 的 `TabsList` 底部 border 與 header 的 `border-b` 實際上是**同一條線**(設計上重疊、實作上不重複渲染)。**Header 退讓**(移除自己 `border-b`),**Tabs 接管**(自身 `border-b border-divider` per `TABS_LIST_BASE`,2026-05-18 fd843c25 統一 chrome separator 色)。三種 overflow mode(none / scroll / menu)的 TabsList 一律 `inline-flex w-fit`(`TABS_LIST_BASE` + `w-fit`;2026-05-19 c359c711 border owner 升 list 內部 + `overflow-y-hidden` 阻 y auto-promote);chrome header 內的全寬 paint 由 `ChromeHeader` tabsSlot wrapper 以 `[&>[role=tablist]]:w-full` 強制(見 `header-canonical.spec.md`)。
+**做法**:Tabs 的 `TabsList` 底部 border 與 header 的 `border-b` 實際上是**同一條線**(設計上重疊、實作上不重複渲染)。**Header 退讓**(移除自己 `border-b`),**Tabs 接管**(自身 `border-b border-divider` per `TABS_LIST_BASE`,2026-05-18 fd843c25 統一 chrome separator 色)。三種 overflow mode 的 TabsList 一律跨滿父容器(none 模式 `w-full`;scroll / menu 模式 inner list `min-w-full` 保留溢出成長,見 L184;`TABS_LIST_BASE` + `overflow-y-hidden` 阻 y auto-promote,2026-05-19 c359c711 border owner 升 list 內部);chrome header 內的全寬 paint 由 `ChromeHeader` tabsSlot wrapper 以 `[&>[role=tablist]]:w-full` 強制(見 `header-canonical.spec.md`)。
 
 **世界級對照(verbatim cite)**:
 - **GitHub Primer PageHeader**:「`hasBorder` defaults true,**but border NOT rendered if Navigation child contains UnderlineNav**;UnderlineNav itself provides bottom border」(`primer.style/components/page-header/react`)

package/src/components/Textarea/textarea.tsx

@@ -19,7 +19,7 @@ import { EMPTY_DISPLAY } from '@/design-system/components/Field/field-wrapper'
  *
  * ── Padding 規則 ───────────────────────────────────────────────────────
  * 多行內容必須有上下內距才能閱讀舒適。不沿用 Input 的 items-center，
- * 改用 py-2（8px）固定上下內距 + px-3 左右內距（與 Input 一致）。
+ * 改用 py-2（8px）固定上下內距 + px-[var(--field-px)]（12px token，左右內距 SSOT，與 Input/Field family 一致）。
  *
  * ── Size ────────────────────────────────────────────────────────────────
  * sm / md → text-body（14px）
@@ -40,7 +40,7 @@ const textareaVariants = cva(
     // K10 fix(2026-05-04):disabled 時 placeholder + text 切 fg-disabled(parallel 到 bareInputStyles)
     //   Textarea 自身 `<textarea disabled>` 帶 disabled HTML attribute,用 `disabled:` variant 直接命中
     'disabled:placeholder:text-fg-disabled disabled:text-fg-disabled',
-    'px-3 py-2',
+    'px-[var(--field-px)] py-2',
     'transition-colors duration-150',
   ],
   {
@@ -77,7 +77,7 @@ const textareaVariants = cva(
       {
         mode: 'display',
         variant: 'default',
-        // 2026-05-13 Q3 Path Ⅰ:Textarea default display zero chrome,!px-0 !py-0 override base `px-3 py-2`
+        // 2026-05-13 Q3 Path Ⅰ:Textarea default display zero chrome,!px-0 !py-0 override base `px-[var(--field-px)] py-2`
         // (跟 Input 同 SSOT,per field-controls.spec.md (d))
         className: 'bg-transparent border border-transparent !px-0 !py-0',
       },

package/src/components/TimePicker/time-picker.spec.md

@@ -152,7 +152,7 @@ Panel 展開後的 column picker 結構:
 
 ### Spacing + 結構(2026-04-21 canonical,2026-04-21 window width 修正)
 
-- Footer 內 padding = `--layout-space-tight`(12px @ md density)
+- Footer 內 padding = `--layout-space-tight`(12px @ md density);**消費 `<SurfaceFooter>` SSOT**(border-t + py + gap + justify + shrink-0),px 經 `className` override 回 tight——因滿欄 column 面板無 chrome-padded body 內縮邊可對齊(見 `overlay-surface.spec.md` SurfaceFooter「footer px = body 內縮原則」例外);此刻按鈕 `mr-auto` 推右,視覺等同原 justify-between(零視覺變化)
 - **Panel 容器固定寬:2 欄(時 / 分)`w-40`(160px)/ 3 欄(時 / 分 / 秒)`w-60`(240px)**;**每欄 `flex-1 h-full` 等分**容器寬(非固定 `w-12`)。**分隔「:」移除**(AR8 canonical — Ant TimePicker / Google Calendar 同樣不加 `:`,靠 column 間距自明 `@benchmark-unverified` visual)
 - Scrollable list 用 **`<ScrollArea>`**(對齊 DS 跨 OS 一致 overlay 捲軸 canonical);不 raw `overflow-y-auto`
 - **Scroll-into-view**:mount = `behavior:'auto'`(避閃爍),後續 `value` 變更 = `behavior:'smooth'`(對齊 iOS / Material / Ant timepicker idiom)。SSOT 在 `time-columns.tsx` `TimeColumn` useEffect

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

@@ -14,6 +14,7 @@ import { ItemInlineAction, ItemSuffix } from '@/design-system/patterns/element-a
 import { Popover, PopoverTrigger, PopoverContent } from '@/design-system/components/Popover/popover'
 import { useFieldContext, useResolvedFieldSize, useResolvedFieldDisabled, useResolvedFieldMode, useResolvedFieldVariant, useResolvedFieldInvalid } from '@/design-system/components/Field/field-context'
 import { Button } from '@/design-system/components/Button/button'
+import { SurfaceFooter } from '@/design-system/patterns/overlay-surface/overlay-surface'
 import {
   TimeColumns,
   isoToTimeParts,
@@ -279,8 +280,8 @@ const TimePicker = React.forwardRef<HTMLDivElement, TimePickerProps>(
               : <span className="text-fg-muted">{EMPTY_DISPLAY}</span>
             }
           </span>
-          {/* 2026-06-10 類型身份 indicator gate:naked cell 依 showDisplayEndIcon=isEditable(修 disabled cell 漏顯 bug)*/}
-          {EndIconCmp && (variant === 'naked' ? showDisplayEndIcon : true) && (
+          {/* 2026-06-26 類型身份 indicator:edit 顯示 / readonly 不顯示 / disabled 保留(fg-disabled);naked cell 依 showDisplayEndIcon=isEditable(修 disabled cell 漏顯 bug)*/}
+          {EndIconCmp && (variant === 'naked' ? showDisplayEndIcon : resolvedMode === 'disabled') && (
             <ItemSuffix className="pointer-events-none">
               <EndIconCmp
                 size={iconSize}
@@ -389,15 +390,13 @@ const TimePicker = React.forwardRef<HTMLDivElement, TimePickerProps>(
               // 不會走到 document body 把 popover 內容推出畫面(user 報「hours 欄空白」根因)。
               className="flex-1 min-h-0"
             />
-            {/* Footer:Now + OK */}
-            <div
-              className={cn(
-                'flex items-center justify-between gap-2',
-                'border-t border-divider',
-                'px-[var(--layout-space-tight)] py-[var(--layout-space-tight)]',
-              )}
-            >
-              <Button variant="text" size="sm" onClick={handleNow}>
+            {/* Footer:消費 SurfaceFooter SSOT(border-t + py-tight + gap-2 + shrink-0 + justify-end)。
+                px override 回 layout-space-tight,因 TimePicker 滿欄 column 面板無 chrome-padded body
+                內縮邊可對齊(footer px = body 內縮 原則;column-selector 數字置中、零內距,
+                見 time-picker.spec.md)。此刻 mr-auto 把確定推右,視覺等同原 justify-between
+                —— 純結構消費 overlay-surface canonical(overlay-surface.spec.md:17「不自寫 padding token」),零視覺變化。 */}
+            <SurfaceFooter className="px-[var(--layout-space-tight)]">
+              <Button variant="text" size="sm" onClick={handleNow} className="mr-auto">
                 此刻
               </Button>
               <Button
@@ -407,7 +406,7 @@ const TimePicker = React.forwardRef<HTMLDivElement, TimePickerProps>(
               >
                 確定
               </Button>
-            </div>
+            </SurfaceFooter>
           </div>
         </PopoverContent>
       </Popover>

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

@@ -1057,7 +1057,7 @@ export const treeViewMeta = {
   },
   states: ['default', 'hover', 'active', 'focus-visible', 'disabled'],
   tokens: {
-    bg: ['bg-neutral-hover', 'bg-primary', 'bg-primary-subtle', 'bg-surface'],
+    bg: ['bg-neutral-hover', 'bg-neutral-selected', 'bg-surface'],
     fg: ['text-fg-disabled', 'text-fg-muted', 'text-fg-secondary', 'text-foreground'],
     ring: ['ring-ring'],
   },

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

@@ -474,7 +474,7 @@ MenuItem 承載 Switch 時,**整列 row 的 click = toggle 這個 control**(不
 | 內容物高度 | 對齊容器 | 對齊目標 |
 |---|---|---|
 | ≤ 24px | `h-[1lh]` | 第一行 label 的垂直中心 |
-| > 24px(+ 有 description) | `h-[calc(1lh + 2px + desc_1lh)]` | label + gap + description 文字塊的垂直中心 |
+| > 24px(+ 有 description) | `h-[calc(1lh + var(--item-gap-label-desc-<mode>[-lg]) + desc-font-size*1.3)]` | label + gap + description 文字塊的垂直中心 |
 | > 24px(無 description) | `h-[1lh]` | 強制 inline(沒有文字塊可對齊) |
 
 ### 為什麼 prefix 和 suffix 各自獨立(不互相同步)

package/src/patterns/element-anatomy/item-anatomy.stories.tsx

@@ -161,7 +161,7 @@ const SCANNING_SPECS: Record<SizeKey, TypoSpec> = {
 const READING_SPECS: Record<SizeKey, TypoSpec> = {
   sm: { labelFont: 'text-body', labelSize: '14px', labelLh: '1.5', descFont: 'text-body', descSize: '14px', descLh: '1.5', iconPx: 16 },
   md: { labelFont: 'text-body', labelSize: '14px', labelLh: '1.5', descFont: 'text-body', descSize: '14px', descLh: '1.5', iconPx: 16 },
-  lg: { labelFont: 'text-body-lg', labelSize: '16px', labelLh: '1.5', descFont: 'text-body-lg', descSize: '16px', descLh: '1.5', iconPx: 20 },
+  lg: { labelFont: 'text-body-lg', labelSize: '16px', labelLh: '1.5', descFont: 'text-body', descSize: '14px', descLh: '1.5', iconPx: 20 },
 }
 
 /* ═══════════════════════════════════════════════════════════════════════════

package/src/patterns/overlay-surface/overlay-surface.spec.md

@@ -177,6 +177,7 @@ list 不再是 body 唯一 region → **不該撤 body chrome padding**(撤了
 - `border-t border-divider`
 - `px-[var(--layout-space-loose)] py-[var(--layout-space-tight)]`
 - `flex items-center justify-end gap-2 shrink-0`(右對齊按鈕列,不被壓縮)
+- **Footer px = body 內容內縮原則**:預設 `layout-space-loose` 讓 footer 按鈕左緣對齊 SurfaceHeader title / SurfaceBody 內容左緣(整面板內容垂直對齊一條線,同 Body alignment rationale)。**例外**:body 為 full-bleed(滿欄 column selector / 無 chrome padding 的 unbounded list)、無內容左緣可對齊時,可經 `className` override 較緊 px(eg. TimePicker footer override `px-[var(--layout-space-tight)]` 對齊滿欄置中 columns、保窄面板平衡)。**注**:`--field-px` 是 form-field gutter 概念(uiSize),**不**用於 overlay footer——footer 屬 overlay chrome,padding 走 layoutSpace 家族。
 
 ---
 

package/src/patterns/resize-handle/resize-handle.spec.md

@@ -59,7 +59,7 @@ benchmark:
 取值依據:7px 命中區 / 1px line 非自創——來自下方「世界級對照細節」5 家共識(hit zone 7-8px fingertip-friendly / 1px line non-intrusive)+ DataTable v11 已 ship 的既有 canonical(本 primitive 抽取自它,M17)。
 
 - **命中區**:7px 寬(horizontal)/ 高(vertical),`-3px` outward offset 跨 boundary 抓得到
-- **Visual line**:1px,positioned `right-[3px]` / `bottom-[3px]`,default full-extent
+- **Visual line**:1px,line offset 3px from the position edge(inline style `right: 3` / `bottom: 3`,非 Tailwind class — 見 tsx JIT-quirk note),default full-extent
   - **idle**:`bg-divider`
   - **disabled**:`bg-divider`(無 hover affordance)
   - **hover**:`bg-[var(--border-hover)]`(via `group/resize` selector)

package/src/tokens/color/semantic.css

@@ -197,7 +197,7 @@
 
   /* Brand / Action — 品牌主操作色
      --primary-text 為 SOP 規定的 5 件套之一，目前無消費者
-     （Button 直接用 text-white, Tag 用 primitive --color-blue-7） */
+     （Button 直接用 text-on-emphasis, Tag 用 primitive --color-blue-7） */
   --primary:              var(--color-blue-6);
   --primary-hover:        var(--color-blue-5);
   --primary-active:       var(--color-blue-7);

package/src/tokens/uiSize/uiSize.css

@@ -24,6 +24,11 @@
   --field-height-md: 2rem;      /* 32px */
   --field-height-lg: 2.25rem;   /* 36px */
 
+  /* Field horizontal padding — 固定 12px(不隨 size/density);form-context field 左右內距 SSOT。
+     跟 --table-cell-px(cell-context)同 -px 慣例;Input/Select/Combobox/DatePicker/TimePicker/Textarea
+     + tag 模式右緣 re-assert 全消費此 token(取代散落的 px-3 / inline 0.75rem,M17 SSOT 可傳播)。 */
+  --field-px: 0.75rem;          /* 12px */
+
   /* Table Row Height — DataTable */
   --table-row-sm: 2rem;         /* 32px */
   --table-row-md: 2.5rem;       /* 40px */

package/src/tokens/uiSize/uiSize.spec.md

@@ -94,6 +94,20 @@ Consumer 寫 Form 或 Toolbar 時並排多個 field-height 元件：
 
 本專案曾發生 SegmentedControl 的 code defaults 是 `md`、spec + docblock 寫 `sm ★default` 的三方不一致（2026-04-18 修正）。避免方式：改 cva `defaultVariants` 前先讀本表，確認新值仍符合 family 約束。
 
+## Field Horizontal Padding
+
+Form-context field 控件的左右水平內距。**固定 12px,不隨 size / density 變化**——縱向才是 density 節奏;橫向是內容溝槽常數,對齊 field-height family 全控件。
+
+| Token | 值 | 說明 |
+|-------|-----|------|
+| `--field-px` | 0.75rem (12px) | form-context field 左右內距 SSOT;固定不隨 size / density |
+
+**消費者**:`Input` / `NumberInput` / `Select` / `Combobox` / `DatePicker` / `TimePicker` / `LinkInput` / `Textarea`(經 `fieldWrapperStyles` cva `px-[var(--field-px)]`)+ `PeoplePicker`(form-context inject `!px-[var(--field-px)]`)+ tag 模式右緣 re-assert(`paddingRight: var(--field-px)`,Select / Combobox readonly + edit)。
+
+**與 `--table-cell-px` 的關係**:同 `-px` 命名慣例。`--table-cell-px`(DataTable-scoped)預設 `var(--field-px)`(form / cell 同 12px content gutter SSOT),但仍是獨立 named token、可被 DataTable 單獨 override(per `components/Field/field-controls.spec.md` contract (c) scoped 決策)。
+
+**Why 固定不隨 density**:density 本質是縱向密度(一屏幾列);橫向管可讀性(字離格線距離),目的不同不綁。對齊 Ant Table(橫向 padding 不隨 density 變、縱橫分離)+ 全 DS field 控件 12px 常數。M17「SSOT 必可傳播」:散落的 `px-3` / inline `0.75rem` 全收斂進此 token。
+
 ## Table Row
 
 DataTable 行高。density 切換統一 +0.5rem (+8px)。
@@ -152,9 +166,9 @@ DataTable 行高。density 切換統一 +0.5rem (+8px)。
 | Avatar 內 icon | `components/Avatar/avatar.spec.md:165` | `round_even(size × 0.6)` formula | Material / Apple HIG |
 | Empty illustration | `components/Empty/empty.tsx:48` | Avatar 48 wrap → icon 28(Avatar formula derived)| Empty-state canonical |
 | FileViewer thumb | `components/FileViewer/file-viewer.tsx:621` | thumb 64 → icon 20(file-type indicator hardcode 無公式)| Thumbnail UI 慣例 |
-| CircularProgress | `components/CircularProgress/circular-progress.tsx:87` | `strokeWidth = max(2, size/10)` stroke ring 厚度非 icon | Geometric scaling |
-| Steps indicator icon | `components/Steps/steps.tsx:24` | `INDICATOR_ICON_SIZE {sm:0, md:16, lg:20}`(sm 因圓圈 8px 太小)| Indicator-internal |
-| Checkbox/Switch check | `components/Checkbox/checkbox.tsx:49` + `components/Switch/switch.tsx:73` | `{sm:12, md:12, lg:16}` form-control internal + stroke 下限 12 | iOS HIG / Material 3 / Polaris | <!-- @benchmark-unverified -->
+| CircularProgress | `components/CircularProgress/circular-progress.tsx:86` | `strokeWidth = max(2, round(size/10))` stroke ring 厚度非 icon | Geometric scaling |
+| Steps indicator icon | `components/Steps/steps.tsx:25` | `INDICATOR_ICON_SIZE {sm:0, md:16, lg:20}`(sm 因圓圈 8px 太小)| Indicator-internal |
+| Checkbox/Switch check | `components/Checkbox/checkbox.tsx:52` + `components/Switch/switch.tsx:83` | `{sm:12, md:12, lg:16}` form-control internal + stroke 下限 12 | iOS HIG / Material 3 / Polaris | <!-- @benchmark-unverified -->
 
 **程式化 SSOT**:`patterns/element-anatomy/item-anatomy.tsx:66` `ICON_SIZE = {sm:16, md:16, lg:20}` 是本 tier 的 type-safe const。**Form control 透過 `tokens/uiSize/icon-size.ts` re-export entry import**(避 components→patterns 反向 dependency)。