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

package/llms-full.txt

@@ -1,6 +1,6 @@
 # @qijenchen/design-system — 完整設計參考(llms-full)
 
-> 全 component / pattern 的 variants / sizes / 禁止事項。build-time 從 spec.md frontmatter 生成,禁手改。v0.1.0-beta.75。
+> 全 component / pattern 的 variants / sizes / 禁止事項。build-time 從 spec.md frontmatter 生成,禁手改。v0.1.0-beta.76。
 
 # Components
 
@@ -21,7 +21,7 @@ Source(AI 讀此看官方範例): src/components/Alert/
 - **warning**: 警告但非阻斷(方案即將到期、需更新付款方式);最高頻使用
 - **error**: 錯誤但非阻斷(系統錯誤但可重試、API 失敗摘要);搭配 aria-live=assertive
 
-## app-shell(family composite)
+## AppShell(family composite)
 
 Storybook: https://ajenchen-design-system.netlify.app
 Source(AI 讀此看官方範例): src/components/AppShell/
@@ -52,6 +52,11 @@ Source(AI 讀此看官方範例): src/components/Badge/
 Storybook: https://ajenchen-design-system.netlify.app
 Source(AI 讀此看官方範例): src/components/Breadcrumb/
 
+### Sizes
+- **sm**: Dialog / panel / drawer 內;text-body(14)+ icon 16,建議配 text-h4(20)title。對齊 BREADCRUMB_TEXT_CLASS.sm + BREADCRUMB_ICON_SIZE.sm(breadcrumb.tsx:124-136)
+- **md**: 預設 — 一般頁面 header;text-body(14)+ icon 16,建議配 text-h3(24)title
+- **lg**: Detail page hero / landing;text-body-lg(16)+ icon 20,建議配 text-h2(32)title
+
 ## BulkActionBar(family composite)
 
 Storybook: https://ajenchen-design-system.netlify.app

package/llms.txt

@@ -1,7 +1,7 @@
 # @qijenchen/design-system
 
 > World-class React design system(Radix/shadcn + Tailwind v4 + 自訂 design token)。
-> 54 components + 4 public patterns + design tokens。v0.1.0-beta.75。
+> 54 components + 4 public patterns + design tokens。v0.1.0-beta.76。
 
 本檔由 source(spec.md frontmatter + Storybook index)build-time 自動生成,**禁手改**(CI --check drift gate 守)。
 每元件 / pattern 的完整 variants / sizes / 禁止事項 全文見 [llms-full.txt](./llms-full.txt)。
@@ -10,11 +10,11 @@
 ## Components
 - [Accordion](https://ajenchen-design-system.netlify.app): 見 Storybook / spec — src:components/Accordion
 - [Alert](https://ajenchen-design-system.netlify.app): variants:neutral/info/success/warning/error — src:components/Alert
-- [app-shell](https://ajenchen-design-system.netlify.app): 見 Storybook / spec — src:components/AppShell
+- [AppShell](https://ajenchen-design-system.netlify.app): 見 Storybook / spec — src:components/AppShell
 - [AspectRatio](https://ajenchen-design-system.netlify.app): 見 Storybook / spec — src:components/AspectRatio
 - [Avatar](https://ajenchen-design-system.netlify.app): 見 Storybook / spec — src:components/Avatar
 - [Badge](https://ajenchen-design-system.netlify.app): variants:critical/high/medium/low — src:components/Badge
-- [Breadcrumb](https://ajenchen-design-system.netlify.app): 見 Storybook / spec — src:components/Breadcrumb
+- [Breadcrumb](https://ajenchen-design-system.netlify.app): sizes:sm/md/lg — src:components/Breadcrumb
 - [BulkActionBar](https://ajenchen-design-system.netlify.app): 見 Storybook / spec — src:components/BulkActionBar
 - [Button](https://ajenchen-design-system.netlify.app): variants:primary/secondary/tertiary/text/link;sizes:xs/sm/md/lg — src:components/Button
 - [Calendar](https://ajenchen-design-system.netlify.app): 見 Storybook / spec — src:components/Calendar

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@qijenchen/design-system",
-  "version": "0.1.0-beta.75",
+  "version": "0.1.0-beta.76",
   "private": false,
   "description": "World-class design system — components, patterns, tokens, hooks (single source of truth for team distribution).",
   "type": "module",

package/src/components/Alert/alert.anatomy.stories.tsx

@@ -128,10 +128,10 @@ export const ColorMatrix: Story = {
             <thead><tr><Th>Variant</Th><Th>Subtle</Th><Th>Solid</Th></tr></thead>
             <tbody>
               <tr><Td mono>neutral</Td><Td mono>bg-muted + border-border;無 status icon(VARIANT_ICON.neutral = null)</Td><Td>bg-surface-raised + data-theme inverse(跟頁面反)</Td></tr>
-              <tr><Td mono>info</Td><Td mono>bg-info-subtle + border-info-hover + text-info-text</Td><Td mono>bg-info + data-theme="dark"(藍底白字)</Td></tr>
-              <tr><Td mono>success</Td><Td mono>bg-success-subtle + border-success-hover + text-success-text</Td><Td mono>bg-success + data-theme="dark"(綠底白字)</Td></tr>
-              <tr><Td mono>warning</Td><Td mono>bg-warning-subtle + border-warning-hover + text-warning-text</Td><Td mono>bg-warning + data-theme="light"(黃底深字)</Td></tr>
-              <tr><Td mono>error</Td><Td mono>bg-error-subtle + border-error-hover + text-error-text</Td><Td mono>bg-error + data-theme="dark"(橘底白字)</Td></tr>
+              <tr><Td mono>info</Td><Td mono>bg-info-subtle + border-[var(--info-text)] + text-info-text</Td><Td mono>bg-info + data-theme="dark"(藍底白字)</Td></tr>
+              <tr><Td mono>success</Td><Td mono>bg-success-subtle + border-[var(--success-text)] + text-success-text</Td><Td mono>bg-success + data-theme="dark"(綠底白字)</Td></tr>
+              <tr><Td mono>warning</Td><Td mono>bg-warning-subtle + border-[var(--warning-text)] + text-warning-text</Td><Td mono>bg-warning + data-theme="light"(黃底深字)</Td></tr>
+              <tr><Td mono>error</Td><Td mono>bg-error-subtle + border-[var(--error-text)] + text-error-text</Td><Td mono>bg-error + data-theme="dark"(橘底白字)</Td></tr>
             </tbody>
           </table>
         </div>

package/src/components/AppShell/app-shell.spec.md

@@ -1,5 +1,5 @@
 ---
-pattern: app-shell
+component: AppShell
 family: composite  # 組合 sidebar+header+main+aside,非 Family 1-4 row element
 scope: web service page-level layout primitive (sidebar + header + main + aside composition)
 benchmark:
@@ -58,7 +58,7 @@ benchmark:
   asideOpen={open}      onAsideOpenChange={setOpen}      // ⌘. / Ctrl+. toggle (本 AppShell own)
   sidebar={<Sidebar>...</Sidebar>}              // SSOT in components/Sidebar/sidebar.spec.md
   header={<ChromeHeader>...</ChromeHeader>}     // SSOT in patterns/header-canonical/header-canonical.spec.md
-  aside={<AppShellAside title="Detail">...</AppShellAside>}   // 本 pattern own;modal mode 必 title(Sheet a11y)
+  aside={<AppShellAside title="Detail">...</AppShellAside>}   // 本 composite own;modal mode 必 title(Sheet a11y)
 >
   {children}    {/* <main> landmark, padding=0,內容遵循 layoutSpace 6 條規則 */}
 </AppShell>
@@ -288,7 +288,7 @@ Main 內塞什麼(table / field / card / page header / list)的 layout + spacing
 
 ## Future extension(目前不定義)
 
-**Multi-sidebar**(Notion / Linear 雙側欄派):**尚未實作**。目前 `sidebar` prop 僅 `React.ReactNode`(單一 slot,無 array signature、無取首位邏輯、無 dev warning)。未來若支援會擴充為 array,SSOT 放 `sidebar.spec.md`,不在本 pattern(per user 2026-05-19「AppShell 不該 customize Sidebar」)。
+**Multi-sidebar**(Notion / Linear 雙側欄派):**尚未實作**。目前 `sidebar` prop 僅 `React.ReactNode`(單一 slot,無 array signature、無取首位邏輯、無 dev warning)。未來若支援會擴充為 array,SSOT 放 `sidebar.spec.md`,不在本 composite(per user 2026-05-19「AppShell 不該 customize Sidebar」)。
 
 **Footer**:不 expose slot(per user 2026-05-19「不用 footer」)。Web service 通常不用 footer,consumer 若需要自貼 Main 底。
 
@@ -342,7 +342,7 @@ Main 內塞什麼(table / field / card / page header / list)的 layout + spacing
 
 ## 相關 spec(per codex Layer B 比稿修正 path/case)
 
-- `components/Sidebar/sidebar.spec.md` — sidebar 視覺 + 鍵盤 + mobile + SidebarTrigger Pattern A/B SSOT(本 pattern 必消費)
+- `components/Sidebar/sidebar.spec.md` — sidebar 視覺 + 鍵盤 + mobile + SidebarTrigger Pattern A/B SSOT(本 composite 必消費)
 - `patterns/header-canonical/header-canonical.spec.md` — header 視覺契約 SSOT
 - `patterns/overlay-surface/overlay-surface.spec.md` — Aside modal mode 上層 SSOT
 - `components/Sheet/sheet.spec.md` — modal fallback SSOT(`aria-labelledby` 強制 + `z-50`)

package/src/components/AppShell/app-shell.tsx

@@ -2,14 +2,14 @@
 /**
  * AppShell — web service page-level layout primitive。
  *
- * 組合 Sidebar + ChromeHeader + Aside + main 成完整 page shell。SSOT 邊界:本 pattern only
+ * 組合 Sidebar + ChromeHeader + Aside + main 成完整 page shell。SSOT 邊界:本 composite component only
  * own slot composition + layout mode + Aside responsive mode;不 own sidebar / header /
  * sheet 視覺(各自 spec own)。
  *
  * 對齊 Mantine AppShell compound API + Ant Layout slot 模式 + Material 3 standard/modal
  * drawer canonical(per spec.md frontmatter cite)。
  *
- * Spec SSOT:`patterns/app-shell/app-shell.spec.md`
+ * Spec SSOT:`components/AppShell/app-shell.spec.md`
  */
 
 import * as React from 'react'

package/src/components/Avatar/avatar.tsx

@@ -277,7 +277,7 @@ const AvatarInner = React.forwardRef<HTMLDivElement, AvatarProps>(
               style={{
                 boxShadow: `0 0 0 2px var(--surface-raised, var(--canvas))`,
               }}
-              aria-label={`${badgeCount} unread`}
+              aria-label={`${badgeCount} unread`} // i18n-allow: DS default(未覆寫英文 'N unread')
             />
           )}
         </div>

package/src/components/Breadcrumb/breadcrumb.spec.md

@@ -2,9 +2,19 @@
 component: Breadcrumb
 family: composite
 variants: {}
-sizes: {}
+sizes:
+  sm:
+    when: "Dialog / panel / drawer 內;text-body(14)+ icon 16,建議配 text-h4(20)title。對齊 BREADCRUMB_TEXT_CLASS.sm + BREADCRUMB_ICON_SIZE.sm(breadcrumb.tsx:124-136)"
+    world-class: ["Atlassian Breadcrumb", "Ant Design Breadcrumb"]
+  md:
+    when: "預設 — 一般頁面 header;text-body(14)+ icon 16,建議配 text-h3(24)title"
+    world-class: ["Ant Design Breadcrumb default", "MUI Breadcrumbs", "Polaris Breadcrumbs"]
+  lg:
+    when: "Detail page hero / landing;text-body-lg(16)+ icon 20,建議配 text-h2(32)title"
+    world-class: ["Carbon Breadcrumb", "Material 3 breadcrumb"]
 traits:
   - hasInteractiveStates
+  - hasSizes
   - isStructural
 benchmark:
   - Ant Design Breadcrumb: github.com/ant-design/ant-design/tree/master/components/breadcrumb

package/src/components/Button/button.tsx

@@ -313,16 +313,6 @@ export interface ButtonProps
   fullWidth?: boolean
 }
 
-/**
- * Icon-only padding — calc `(field-height - icon-size) / 2` per size。
- *
- * 設計:startIcon 到左邊距離 = padding = `(height - icon) / 2`。
- * 純 icon-only 時 width = 2*padding + icon = height → **自然正方形**,不需要 aspect-square。
- * 有 suffix(badge / endIcon)時 width = 2*pad + icon + gap + suffix > height → **自然長方形**。
- * StartIcon 到左邊距離始終不變,形狀自動適應內容。
- *
- * 用 CSS var 讓 density 切換時 padding 自動跟著算(field-height 會變)。
- */
 // IconOnly 用 padding-free + aspect-square + flex-center 的 Polaris/Atlassian idiom
 // (M17 SSOT 必可傳播 — 取代 4 個 size 的 magic-number 公式):
 //   - aspect-square 鎖 width=height(來自 h-field-X)

package/src/components/Calendar/calendar.anatomy.stories.tsx

@@ -124,7 +124,7 @@ export const ColorMatrix: Story = {
                 <tr>
                   <Td>Today cell(日期數字)</Td>
                   <Td mono>bg-info · text-on-emphasis · rounded-full · min-w-6 h-6 px-2 · text-body font-medium</Td>
-                  <Td>info-filled pill,固定 h-6 + min-w-6 做圓形 badge(對齊 Google Calendar today pill)</Td>
+                  <Td>info-filled pill,固定 h-6 + min-w-6 做 pill badge(對齊 Google Calendar today pill)</Td>
                 </tr>
                 <tr>
                   <Td>Outside day cell</Td>

package/src/components/Chart/chart.tsx

@@ -15,7 +15,7 @@ import { cn } from '@/lib/utils'
  * 預設建議使用 --chart-1..5(本 DS 提供的 5 色類別 token)
  *
  * ── 視覺 token ──
- * Tooltip: bg-surface-raised / border-border / shadow-[elevation-200] / rounded-md
+ * Tooltip: bg-surface-raised / border-border / shadow-[var(--elevation-200)] / rounded-md
  * Legend text: text-fg-secondary / text-caption
  * Grid: stroke-divider
  * Axis tick: text-fg-muted / text-caption

package/src/components/Checkbox/checkbox.tsx

@@ -281,7 +281,7 @@ export const checkboxMeta = {
     // 2026-06-10 修 stale meta:iconSize 對齊 checkIconSize 真值(L49 sm/md=12, lg=16;deep-audit A.1b 抓 metadata drift)
     sm: { fieldHeight: 28, iconSize: 12, typography: 'body' },
     md: { fieldHeight: 32, iconSize: 12, typography: 'body' },
-    lg: { fieldHeight: 36, iconSize: 16, typography: 'body' },
+    lg: { fieldHeight: 36, iconSize: 16, typography: 'body-lg' },
   },
   states: ['default', 'hover', 'focus-visible', 'disabled'],
   tokens: {

package/src/components/Coachmark/coachmark.anatomy.stories.tsx

@@ -167,7 +167,7 @@ export const Inspector: Story = {
                 <tr><Td>Previous / Skip variant</Td><Td mono>tertiary</Td></tr>
                 <tr><Td>Next variant</Td><Td mono>primary</Td></tr>
                 <tr><Td>sideOffset</Td><Td mono>8px(對齊 Popover DS 設計準則)</Td></tr>
-                <tr><Td>Density</Td><Td mono>繼承 Popover(鎖 md)</Td></tr>
+                <tr><Td>Layout-space</Td><Td mono>繼承 Popover(鎖 layout-space md;ui-size 繼承 page)</Td></tr>
               </tbody>
             </table>
           </div>

package/src/components/Coachmark/coachmark.spec.md

@@ -193,7 +193,7 @@ Previous(可選)→ Skip(可選)→ Next / Done。對齊 Ant Tour / Intercom con
 - ❌ **不用 Coachmark 做確認框**——確認破壞性動作必須阻斷流程,改用 `Dialog`
 - ❌ **Media 區不放互動元件**——按鈕 / 輸入 / checkbox 一律走 footer。Media 是視覺說明不是互動區
 - ❌ **Description 不寫超過 3 行**——Coachmark 是快速說明,超過 3 行改用 Dialog + 完整 body 或連結到說明文件
-- ❌ **不強迫完成 tour**——永遠提供退出機制(Esc / header Close / 第一步 Skip)。沒有退出的 onboarding 讓使用者感到被綁架,反而降低完成率
+- ❌ **不強迫完成 tour**——永遠提供退出機制(Esc / header Close / 第一步 Skip)。沒有退出的 onboarding 讓使用者感到被綁架,反而降低完成率。註:header Close 僅在傳 `kind`(有 header)時才 render;無 `kind` 的 multi-step tour 第 2+ 步退出靠 Esc(永遠可用),multi-step 務必傳 `kind` 以提供 header Close 退出入口
 - ❌ **單步驟 CTA 不叫 "Next"**——沒有下一步就不用 Next 字眼,用 `'知道了' / 'Got it' / 'Start'`
 - ❌ **有 Prev 時不同時顯示 Skip**——使用者投入進度後兩個退出路徑衝突(見 CTA 語義表)
 - ❌ **不自包視覺 token**——bg / shadow / radius / padding 一律繼承 Popover,改視覺就改 Popover
@@ -212,7 +212,7 @@ Previous(可選)→ Skip(可選)→ Next / Done。對齊 Ant Tour / Intercom con
 
 ## 邊界狀態
 
-disabled / density 繼承 Popover(density 鎖 md,見 `../Popover/popover.spec.md`);empty(title + description 都不傳)則 Body 不渲染(已於「Props 結構」規定);loading 由 consumer 決定。
+disabled / layout-space 繼承 Popover(鎖 `data-layout-space="md"` 保持 header py-tight 精簡;ui-size / 控件大小繼承 page density),SSOT 見 `tokens/density/density.spec.md` L47;empty(title + description 都不傳)則 Body 不渲染(已於「Props 結構」規定);loading 由 consumer 決定。
 
 - **步數 > 5**:元件不機械限制 — `step.total` 照實顯示(如「6 of 8」);≤ 5 是設計建議(見 Multi-step Tour),超過應改靜態 onboarding 頁
 - **無 `image`**:整個 Media 區不渲染(非 skeleton 佔位,見「Props 結構」)

package/src/components/Combobox/combobox.anatomy.stories.tsx

@@ -39,15 +39,15 @@ const TOKEN_MAP: Record<ModeKey, Record<StateKey, ColorSpec>> = {
   },
   readonly: {
     default:  { bg: '--bg-readonly', text: '--foreground', border: 'transparent', icon: '—' },
-    hover:    { bg: '--bg-disabled', text: '--foreground', border: 'transparent', icon: '—' },
-    focus:    { bg: '--bg-disabled', text: '--foreground', border: 'transparent', icon: '—' },
-    disabled: { bg: '--bg-disabled', text: '--foreground', border: 'transparent', icon: '—' },
+    hover:    { bg: '--bg-readonly', text: '--foreground', border: 'transparent', icon: '—' },
+    focus:    { 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: '—' },
-    hover:    { bg: '--bg-disabled', text: '--fg-disabled', border: 'transparent', icon: '—' },
-    focus:    { bg: '--bg-disabled', text: '--fg-disabled', border: 'transparent', icon: '—' },
-    disabled: { bg: '--bg-disabled', text: '--fg-disabled', border: 'transparent', icon: '—' },
+    default:  { bg: '--bg-disabled', text: '--fg-disabled', border: 'transparent', icon: '--fg-disabled' },
+    hover:    { bg: '--bg-disabled', text: '--fg-disabled', border: 'transparent', icon: '--fg-disabled' },
+    focus:    { bg: '--bg-disabled', text: '--fg-disabled', border: 'transparent', icon: '--fg-disabled' },
+    disabled: { bg: '--bg-disabled', text: '--fg-disabled', border: 'transparent', icon: '--fg-disabled' },
   },
 }
 
@@ -270,7 +270,7 @@ export const Overview = {
       <div className="flex flex-col gap-4">
         <div className="flex flex-col gap-1">
           <H3>結構（Anatomy）— readonly / disabled</H3>
-          <Desc>Tag 沒有 dismiss 按鈕、沒有 clear;ChevronDown 保留為類型身份 indicator(pointer-events-none,readonly fg-muted / disabled fg-disabled)。溢出行為與 edit 相同(+N 指示器)。</Desc>
+          <Desc>Tag 沒有 dismiss 按鈕、沒有 clear;readonly 不顯示 ChevronDown(純值、不可開下拉),disabled 保留為類型身份 indicator(pointer-events-none,fg-disabled)。溢出行為與 edit 相同(+N 指示器)。</Desc>
         </div>
         <div className="flex gap-8">
           <div className="flex flex-col gap-2 items-start">
@@ -285,7 +285,7 @@ export const Overview = {
                   style={{ borderColor: `var(--${s.color})`, backgroundColor: `var(--${s.color}-subtle)`, color: `var(--${s.color})` }}>{s.name}</span>
               ))}
             </div>
-            <span className="text-[10px] text-fg-muted font-mono">無 dismiss · 無 clear · chevron=類型 indicator · tagPadding</span>
+            <span className="text-[10px] text-fg-muted font-mono">無 dismiss · 無 clear · chevron:readonly 不顯示 / disabled 保留 · tagPadding</span>
           </div>
           <div className="flex flex-col gap-2 items-start">
             <span className="text-[11px] text-fg-secondary font-medium">空值</span>
@@ -466,7 +466,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>
-            {isEdit && <PropRow label="Icon"><TokenValue value={colors.icon} /></PropRow>}
+            {mode !== 'readonly' && <PropRow label="Icon"><TokenValue value={colors.icon} /></PropRow>}
           </div>
 
           {/* LAYOUT */}
@@ -479,7 +479,7 @@ const InspectorInner = () => {
               }
             </PropRow>
             <PropRow label="tagPadding" dot={Z.pad.text}><TkVal token="calc()" value={s.tagPaddingCalc} /></PropRow>
-            <PropRow label="右側內距">0.75rem (12px)</PropRow>
+            <PropRow label="右側內距">var(--field-px) (12px)</PropRow>
             <PropRow label="Tag 間距" dot={Z.gap.text}>{s.tagGap}</PropRow>
             <PropRow label="Icon 尺寸" dot={Z.icon.text}>{s.icon}px</PropRow>
             <PropRow label="Tag 高度" dot={Z.tag.text}>{s.tagHeight} ({s.tagSize})</PropRow>
@@ -677,7 +677,7 @@ export const SizeMatrix = {
               {SIZES.map((sz) => (
                 <Td key={sz} mono>
                   <div className="text-fg-secondary">paddingRight</div>
-                  <div className="text-fg-muted text-[10px]">0.75rem (12px)</div>
+                  <div className="text-fg-muted text-[10px]">var(--field-px) (12px)</div>
                 </Td>
               ))}
             </tr>

package/src/components/Combobox/combobox.principles.stories.tsx

@@ -195,7 +195,7 @@ export const TagOperationRule: Story = {
 
         <Rule
           title="readonly / disabled 的 Tag 沒有任何互動"
-          note="沒有 dismiss X、沒有 clear;ChevronDown 保留為類型身份 indicator(不可開啟)。Tag 變純顯示,溢出規則仍然套用(+N 指示器可 hover 查看完整)"
+          note="沒有 dismiss X、沒有 clear;readonly 不顯示 ChevronDown(純值、不可開啟),disabled 才保留為類型身份 indicator。Tag 變純顯示,溢出規則仍然套用(+N 指示器可 hover 查看完整)"
         >
           <Combobox mode="readonly" options={categoryOptions} value={ro} />
           <Label>↑ 不可移除、不可新增、不可清空——整個 field 變「顯示」</Label>

package/src/components/Combobox/combobox.spec.md

@@ -116,7 +116,7 @@ value 軸 controlled-only;open 軸方向相反 — **uncontrolled-only**:`defaul
 ## readonly / disabled 的 Tag
 
 - 沒有 dismiss 按鈕——不可操作
-- ChevronDown 保留——類型身份 indicator(2026-06-10;`pointer-events-none` 不可開啟新增、readonly `fg-muted` / disabled `fg-disabled`、naked cell 依 `showDisplayEndIcon`)
+- ChevronDown:**readonly 不顯示**(純值、不可開下拉)/ **disabled 保留**(類型身份 indicator,`fg-disabled`,`pointer-events-none`)/ naked cell 依 `showDisplayEndIcon`(2026-06-26)
 - 沒有 clear 按鈕——不可清除
 - 溢出行為與 edit 模式相同（+N 指示器）
 

package/src/components/Combobox/combobox.tsx

@@ -448,7 +448,7 @@ export interface ComboboxProps {
    * **2026-05-13 v2 deprecate path**:原 PeoplePicker pass `{8}` 假設「Combobox tagPadding=4px,4+8=12」
    * 但 `tagPadding[size]` 是 density-dependent calc `(field-height - icon-size) / 2`,只在 md size +
    * default density 才 = 4px;其他 size/density 漂 6/8px → 4+8=12 公式破。改 PeoplePicker 直接 inject
-   * `!px-3` className 到 Combobox Field wrapper(per people-picker.spec.md:94 v2),`tagAreaPaddingLeftPx`
+   * `!px-[var(--field-px)]` className 到 Combobox Field wrapper(per people-picker.spec.md:94 v2),`tagAreaPaddingLeftPx`
    * 走 undefined。Future 仍保留此 prop 給其他 consumer 精準調整 padding,但 PeoplePicker 已不再用。
    */
   tagAreaPaddingLeftPx?: number
@@ -488,6 +488,7 @@ function ReadonlyMultiSelect({
   const variant = variantProp ?? 'default'
   const sz = size ?? 'md'
   const iconSize = sz === 'lg' ? 20 : 16
+  const tagHeight = sz === 'sm' ? 20 : 24
   const containerRef = React.useRef<HTMLDivElement>(null)
   const hasTags = (value?.length ?? 0) > 0
 
@@ -527,8 +528,10 @@ function ReadonlyMultiSelect({
         // 2026-05-18 #6A Round 1 Step 1/4(per user 拍板「決策6選a」+ codex M31 Step 5 verdict cite combobox.tsx:451):
         // readonly/disabled path 對齊 L293 display wrapper 已 ship 的 overflow-hidden fix。
         // M10 propagation:原 overflow-visible 讓 readonly tag 越界蓋 indicator,跟 display 不對稱。
-        wrap ? 'flex-wrap py-1' : 'overflow-hidden', className)}
-      style={{ gap: GAP, ...(wrap ? { height: 'auto' } : undefined) }} data-field-mode={resolvedMode}
+        // 2026-06-27 對齊 edit path(L598-617):wrap 時 items-start + chevron self-start/tagHeight 鎖第一行;
+        // paddingRight: var(--field-px) re-assert 右緣 12px(tagPadding 對稱 calc 會吃掉右緣,跟 edit 一致)。
+        wrap ? 'flex-wrap items-start py-1' : 'overflow-hidden', className)}
+      style={{ gap: GAP, paddingRight: 'var(--field-px)', ...(wrap ? { height: 'auto' } : undefined) }} data-field-mode={resolvedMode}
       aria-disabled={resolvedMode === 'disabled' ? true : undefined}>
       {hasTags ? (
         <ComboboxTagStack value={value} options={options} tagSize={sz} wrap={wrap}
@@ -536,9 +539,9 @@ function ReadonlyMultiSelect({
       ) : (
         <span className="text-fg-muted">{EMPTY_DISPLAY}</span>
       )}
-      {/* 2026-06-10 類型身份 indicator 規則:readonly/disabled 保留 chevron(naked cell 依 showDisplayEndIcon);disabled → fg-disabled */}
-      {(variant === 'naked' ? !!showDisplayEndIcon : true) && (
-        <ItemSuffix className="pointer-events-none">
+      {/* 2026-06-26 類型身份 indicator:edit 顯示 / readonly 不顯示(純值、不可開下拉) / disabled 保留(fg-disabled,對齊原生 <select disabled>);naked cell 依 showDisplayEndIcon */}
+      {(variant === 'naked' ? !!showDisplayEndIcon : resolvedMode === 'disabled') && (
+        <ItemSuffix className={cn('pointer-events-none', wrap && 'self-start')} style={wrap ? { height: tagHeight } : undefined}>
           <ChevronDown size={iconSize} className={cn('shrink-0', resolvedMode === 'disabled' ? 'text-fg-disabled' : 'text-fg-muted')} aria-hidden />
         </ItemSuffix>
       )}
@@ -575,14 +578,18 @@ function NativeCombobox({
   const handleRemove = (v: string) => onChange?.(value.filter(x => x !== v))
   const handleAdd = (v: string) => { if (!value.includes(v)) onChange?.([...value, v]) }
 
+  // React #310 fix(對齊 select.tsx):hooks 必在 conditional early-return 前無條件呼叫。
+  // resolvedMode 在 edit↔非edit 切換(<Field mode/disabled> cascade / DataTable cell 進出編輯)時
+  // hook 數量不可變動,否則 Rules of Hooks violation → React #310 「rendered fewer/more hooks」crash。
+  const selectRef = React.useRef<HTMLSelectElement>(null)
+  const tagAreaRef = React.useRef<HTMLDivElement>(null)
+
   if (resolvedMode !== 'edit') {
     return <ReadonlyMultiSelect mode={resolvedMode} variant={variant} size={size} options={options} value={value} wrap={wrap} className={className} showDisplayEndIcon={showDisplayEndIcon} />
   }
 
   const items = value.map(v => ({ value: v, label: options.find(o => o.value === v)?.label ?? v }))
   const unselected = options.filter(o => !value.includes(o.value))
-  const selectRef = React.useRef<HTMLSelectElement>(null)
-  const tagAreaRef = React.useRef<HTMLDivElement>(null)
   const tagHeight = size === 'sm' ? 20 : 24
 
   const selectDropdown = unselected.length > 0 ? (
@@ -597,7 +604,7 @@ function NativeCombobox({
   return (
     <div ref={__triggerRef} className={cn(fieldWrapperStyles({ mode: 'edit', variant: variant, size }), value.length > 0 && tagPadding[size], 'relative',
       wrap && 'items-start py-1', error && ['border-error hover:border-error-hover', 'focus-within:border-error focus-within:hover:border-error'], className)}
-      style={{ paddingRight: '0.75rem', ...(wrap ? { height: 'auto' } : undefined) }} data-field-mode="edit" data-error={error ? '' : undefined}
+      style={{ paddingRight: 'var(--field-px)', ...(wrap ? { height: 'auto' } : undefined) }} data-field-mode="edit" data-error={error ? '' : undefined}
       onClick={(e) => { if (e.target === e.currentTarget) { selectRef.current?.showPicker?.(); selectRef.current?.focus() } }}>
       {/* 2026-05-18 F2 sync(per user verbatim「modifying 修好 PeoplePicker stack 後改壞 Combobox tag display」
           + 「tag 應該要判斷所在空間最多可以呈現幾個tag(包括＋n)去自動判斷何時要變成+n」):
@@ -671,10 +678,10 @@ function CustomCombobox({
 
   React.useEffect(() => { if (!open) setSearch('') }, [open])
 
-  if (resolvedMode !== 'edit') {
-    return <ReadonlyMultiSelect mode={resolvedMode} variant={variant} size={size} options={options} value={value} wrap={wrap} className={className} showDisplayEndIcon={showDisplayEndIcon} />
-  }
-
+  // React #310 fix(對齊 select.tsx):以下 hooks(useMemo/useRef)必在 conditional early-return 前
+  // 無條件呼叫。resolvedMode 在 edit↔非edit 切換時 hook 數量不可變動,否則 Rules of Hooks
+  // violation → React #310 「rendered fewer/more hooks」crash(ReadonlyMultiSelect 用不到這些值,
+  // 多算無害,對齊 select.tsx hoist pattern)。
   const items = React.useMemo(
     () => value.map(v => ({ value: v, label: options.find(o => o.value === v)?.label ?? v })),
     [value, options]
@@ -708,6 +715,10 @@ function CustomCombobox({
     [filteredOptions]
   )
 
+  if (resolvedMode !== 'edit') {
+    return <ReadonlyMultiSelect mode={resolvedMode} variant={variant} size={size} options={options} value={value} wrap={wrap} className={className} showDisplayEndIcon={showDisplayEndIcon} />
+  }
+
   const chevronEl = <ChevronDown size={iconSize} className={cn('shrink-0 text-fg-muted transition-transform', open && 'rotate-180')} aria-hidden />
 
   const trigger = (
@@ -725,7 +736,7 @@ function CustomCombobox({
         // 2026-05-06 v13.3 SSOT retire:per-control `open && 'border-primary'` 移除。Field default
         // 統一處理 — open=灰深(data-state)/ focus=藍(focus-within !important)。改一處全 control 跟動。
         error && ['border-error hover:border-error-hover', 'focus-within:border-error focus-within:hover:border-error'], className)}
-      style={{ paddingRight: '0.75rem', ...(wrap ? { height: 'auto' } : undefined) }}
+      style={{ paddingRight: 'var(--field-px)', ...(wrap ? { height: 'auto' } : undefined) }}
       data-field-mode="edit" data-error={error ? '' : undefined}
       // WAI-ARIA APG combobox 鍵盤開啟語意 — 對齊 sibling Select(select.tsx:593-598)。
       // <div role=combobox> 不像 native <button> 自動 synthesize Enter/Space click,故顯式補:

package/src/components/Command/command.anatomy.stories.tsx

@@ -14,6 +14,7 @@ import {
   CommandGroup,
   CommandItem,
   CommandSeparator,
+  CommandShortcut,
 } from './command'
 import { H3, Desc, Td, Th } from '@/design-system/stories-helpers/anatomy/anatomy-utils'
 
@@ -44,6 +45,7 @@ export const Overview: Story = {
                 <CommandItem>
                   <Settings className="mr-2 h-4 w-4" />
                   前往設定
+                  <CommandShortcut>⌘K</CommandShortcut>
                 </CommandItem>
               </CommandGroup>
               <CommandSeparator />

package/src/components/Command/command.tsx

@@ -135,7 +135,7 @@ const CommandItem = React.forwardRef<
   <CommandPrimitive.Item
     ref={ref}
     className={cn(
-      "relative flex cursor-default gap-2 select-none items-center rounded-md px-2 py-1.5 text-body outline-none data-[disabled=true]:pointer-events-none data-[selected='true']:bg-neutral-hover data-[selected=true]:text-foreground data-[disabled=true]:text-fg-disabled [&_svg]:pointer-events-none [&_svg]:size-4 [&_svg]:shrink-0",
+      "relative flex cursor-default gap-2 select-none items-center rounded-md px-2 py-1.5 text-body outline-none data-[disabled=true]:pointer-events-none data-[selected=true]:bg-neutral-hover data-[selected=true]:text-foreground data-[disabled=true]:text-fg-disabled [&_svg]:pointer-events-none [&_svg]:size-4 [&_svg]:shrink-0",
       className
     )}
     {...props}
@@ -164,7 +164,7 @@ CommandShortcut.displayName = "CommandShortcut"
 // Phase 2 fill needed: purpose descriptions + when rationale + world-class refs
 export const commandMeta = {
   component: 'Command',
-  family: null, // non-family composite / overlay / layout
+  family: 'composite', // 對齊 command.spec.md frontmatter family: composite(SSOT)
   variants: {
 
   },

package/src/components/DataTable/cell-registry.tsx

@@ -174,6 +174,11 @@ function NumberCell({ value, meta, mode, size, isDisabled, onCommit, onCancel, o
   // currency 透過 columnType-aware prefix:type='currency' → 預設 '$'(可 override)
   const isCurrency = meta?.type === 'currency'
   const prefix = isCurrency ? (meta?.prefix ?? '$') : meta?.prefix
+  // React #310 fix:useState 必在 display early-return 前無條件呼叫。同一 memo'd cell instance
+  // 在 display↔edit 切換時被重用(render site 無 key={mode},data-table.tsx:1352),hook 數量不可變,
+  // 否則 Rules of Hooks violation → React #310 crash。對齊 combobox/select hoist pattern。
+  const initial = typeof value === 'number' ? value : null
+  const [localValue, setLocalValue] = React.useState<number | null>(initial)
   if (mode === 'display') {
     return (
       <NumberInput
@@ -193,8 +198,7 @@ function NumberCell({ value, meta, mode, size, isDisabled, onCommit, onCancel, o
   // (`value={value ?? ''}`)— 若 NumberCell 以 `defaultValue` 傳入,NumberInput value=undefined → ''
   // empty。對齊 cell-as-input「edit mode 自動帶入 display 值」(對齊 Notion / Airtable 共識),
   // 改用 local state controlled。User typing → setLocalValue;blur/Enter → onCommit(localValue)。
-  const initial = typeof value === 'number' ? value : null
-  const [localValue, setLocalValue] = React.useState<number | null>(initial)
+  // (initial + useState 已 hoist 到 display-return 前 — 見上方 React #310 fix。)
   return (
     <NumberInput
       autoFocus

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

@@ -650,13 +650,13 @@ function ConjunctionLabel({
   // index === 1:**唯一可改**的 AND/OR Select(連動整 group conjunction)
   // index ≥ 2:被連動的 row,read-only 顯示當前 conjunction 文字(同 Where 視覺,A6 canonical)
   //   對齊 Airtable / Notion / Linear 共識 @benchmark-unverified(non-OSS)
-  //   px-3 對齊 Field 內部 padding 12px(Q13)
+  //   px-[var(--field-px)] 對齊 Field 內部 padding 12px(Q13)
   if (index === 0) {
-    return <div className="w-20 shrink-0 text-body text-fg-muted px-3 self-center">Where</div>
+    return <div className="w-20 shrink-0 text-body text-fg-muted px-[var(--field-px)] self-center">Where</div>
   }
   if (index >= 2) {
     const label = conjunction === 'and' ? 'And' : 'Or'
-    return <div className="w-20 shrink-0 text-body text-fg-muted px-3 self-center">{label}</div>
+    return <div className="w-20 shrink-0 text-body text-fg-muted px-[var(--field-px)] self-center">{label}</div>
   }
   // index === 1:可切換的 AND/OR Select
   // minRows={2} — And/Or 2 選項,顯式縮 menu 高度避免 reserve 3 row 空白(Q5)

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

@@ -131,7 +131,7 @@ export const Inspector: Story = {
     bordered: { control: 'boolean', description: '外框(嵌入已帶框容器時可設 false 避免雙重邊框)' },
     pinnedLeft: { control: 'boolean', description: 'Pin 產品名稱欄到左側,橫向捲動時保持可見' },
     pinnedRight: { control: 'boolean', description: 'Pin 上架日期欄到右側' },
-    inlineEdit: { control: 'boolean', description: 'inline edit 視覺:cell 間加垂直分隔線 + select 欄顯示 chevron' },
+    inlineEdit: { control: 'boolean', description: 'inline edit 視覺:cell 間加垂直分隔線(dtCellGrid)。Select 欄 chevron 由 column meta.editable 控制(showDisplayEndIcon),非本 prop' },
     height: {
       control: 'select',
       options: ['auto', '300px'],

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

@@ -7,7 +7,7 @@
    ───────────────────────────────────────────────────────── */
 
 :root {
-  --table-cell-px: 0.75rem;
+  --table-cell-px: var(--field-px);  /* 預設取自 --field-px(form/cell 同 12px content gutter SSOT);仍是 DataTable-scoped named token、可獨立 override(spec field-controls.spec.md:330 scoped 決策不變) */
 }
 
 [data-table-size="sm"] {

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

@@ -386,12 +386,12 @@ ValueShape ↔ DS picker 對照(canonical 2026-05-02):
 
 ### 四、UI canonical
 
-- 第 1 row conjunction 是靜態 `Where` label(`px-3` 對齊下方 Field value 起點 = 12px)
+- 第 1 row conjunction 是靜態 `Where` label(`px-[var(--field-px)]` 對齊下方 Field value 起點 = 12px)
 - field 未選 → operator + value picker disabled;同 group 共用 conjunction(toggle 任一 → flip 整 group)
 - **空狀態**:無 condition → 只顯 inline `+ 加篩選` CTA(對齊 Notion / Airtable / Linear,**禁止** auto-create 空 row) <!-- @benchmark-unverified: see frontmatter benchmark list for canonical DS source URL -->
 - **CTA 位置**:緊貼最後一條 row(text variant 輕量,**廢 SurfaceFooter**),條件與「加入」屬同一語境
 - **Trash / 刪除**:row 是 form-control row → text Button(non Inline Action,違 item-anatomy canonical)
-- **And/Or Select** `minRows={2}`(2 選項顯式縮 menu 高度);**Where padding** `px-3` align Field
+- **And/Or Select** `minRows={2}`(2 選項顯式縮 menu 高度);**Where padding** `px-[var(--field-px)]` align Field
 - Header refresh icon:`value !== defaultValue` 顯;ButtonDivider 串接 close X(對齊欄位顯示 chrome canonical)
 - **Relative date 群組**:`DATE_RELATIVE_GROUPS` Past / Current / Future,走 `<Select groups>`
 - Trigger button checked(`aria-pressed`):`value` 有 ≥ 1 active condition → on(語意:資料被篩,獨立於 refresh)

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

@@ -39,7 +39,7 @@ const PARTS: Record<PartKey, PartSpec> = {
   caption:      { label: '月份標題',    bg: 'transparent',     text: '--foreground',  border: 'transparent', extra: 'text-body font-medium' },
   nav:          { label: 'Nav 按鈕',    bg: 'transparent',     text: '--foreground',  border: 'transparent', extra: 'Button variant=text size=xs iconOnly · hover 藍圈' },
   weekday:      { label: '星期標頭',    bg: 'transparent',     text: '--foreground',  border: 'transparent', extra: 'text-body font-medium · h-7' },
-  day:          { label: '日格(default)', bg: 'transparent',   text: '--foreground',  border: 'transparent', extra: 'h-field-sm w-field-sm rounded-full' },
+  day:          { label: '日格(default)', bg: 'transparent',   text: '--foreground',  border: 'transparent', extra: 'h-field-sm w-[var(--field-height-sm)] rounded-full' },
   daySelected:  { label: 'Selected',     bg: '--primary',       text: 'white',         border: 'transparent' },
   dayToday:     { label: 'Today(未選)', bg: 'transparent',     text: '--foreground',  border: 'transparent', extra: '數字下方藍色底線(underline bar)' },
   dayHover:     { label: 'Hover',        bg: 'transparent',     text: '--foreground',  border: '--primary',   extra: 'hover 藍圈 1.5px(無填底)' },

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

@@ -82,7 +82,7 @@ DateGrid 是 internal primitive(見「定位」),一般 consumer 經 `DatePicker
 
 因此用 `[&[data-range-middle=true]]:xxx` 這種 attribute selector **根本不會生效**(舊版做法錯誤)。
 
-**正解**:把 state 樣式放進 `classNames[state]` 物件,v9 的 `getClassNamesForModifiers` 會在對應 modifier 為 true 時把該 key 的 class 附加到 Day CELL。範例:`classNames.range_middle: 'bg-[var(--color-neutral-2)] [&>button]:!bg-transparent'`。
+**正解**:把 state 樣式放進 `classNames[state]` 物件,v9 的 `getClassNamesForModifiers` 會在對應 modifier 為 true 時把該 key 的 class 附加到 Day CELL。範例:`classNames.range_middle: "before:content-[''] before:absolute before:inset-y-0 before:-inset-x-[2px] before:bg-neutral-selected [&>button]:!bg-transparent"`(用 `before:` pseudo + semantic `--neutral-selected` token,對齊下方 Range track canonical 與 tsx)。
 
 `[&>button]:xxx` 從 cell 向內選子 button 用於 button-level 樣式(selected / disabled 的藍底白圓等)。