@qijenchen/design-system 0.1.0-beta.80 → 0.1.0-beta.82

package/src/components/Menu/menu-item.spec.md

@@ -150,6 +150,7 @@ Menu 的設計目的是「**快速掃視多個選項挑一個**」。垂直空
 | default | transparent | foreground | — |
 | hover | `--neutral-hover` | foreground | 滑鼠 hover |
 | selected（單選） | `--neutral-selected` | foreground | bg 高亮（不用 ✓ 勾號，避免影響 prefix 對齊） |
+| **selected × hover（疊加）** | `--neutral-selected`（**selected 勝**） | foreground | 2026-07-04 Q2 拍板 M5 明文:bg 是唯一選中指示器,hover 不得洗掉。code = selected 時關 hover bg(menu-item.tsx)。對齊 Ant Menu `:not(-item-selected)` / VS Code list `:hover:not(.selected)`;消費者(DropdownMenu highlighted)同規則 |
 | selected（多選） | transparent | foreground | checkbox 勾選 |
 | disabled | transparent | `--fg-disabled` | disabled prop |
 
@@ -223,7 +224,7 @@ Menu item 的 prefix icon 跟 label 同色（foreground），不是 fg-muted。P
 | 建立操作選單（複製 / 刪除 / 分享）| 用 `DropdownMenu` + `DropdownMenuItem`（內部消費 MenuItem）|
 | 建立選值下拉（選項 + 搜尋）| 用 `SelectMenu`（內部消費 MenuItem）|
 | 建立右鍵選單 | 用未來的 `ContextMenu`（待開發）|
-| 直接在 JSX 中用 `<MenuItem>` | ❌ **禁止**——會失去 menu 外層的 Radix 無障礙 / 鍵盤 / 焦點管理 |
+| 直接在 JSX 中用 `<MenuItem>` | ❌ **禁止**——會失去 menu 外層的 Radix 無障礙 / 鍵盤 / 焦點管理。唯一例外:本元件**自身 stories** 的 internal 展示(demo 容器以 `role="listbox"` 滿足 a11y parent 要求,見 `menu-item.stories.tsx`),產品 code 無豁免 |
 
 ### 消費者
 
@@ -259,7 +260,7 @@ MenuItem 的狀態色(default / hover / selected / disabled)是**結構性的**
 
 ## 邊界案例
 
-- **Disabled**:`disabled` prop 由 MenuItem primitive own;視覺 `text-fg-disabled`(neutral-6,M24 state>emphasis)、無 hover bg、`aria-disabled="true"`、Enter / click 不觸發 onSelect、鍵盤導覽自動 skip(由 consumer SelectMenu / DropdownMenu / cmdk 處理)。已在「選擇 / 狀態視覺規則」段 codify。
+- **Disabled**:`disabled` prop 由 MenuItem primitive own;視覺 `text-fg-disabled`(neutral-6,M24 state>emphasis)、無 hover bg、`aria-disabled="true"`(巢狀 `role="presentation"` 用法時抑制、由外層 primitive 宣告,見「A11y 預設」)、Enter / click 不觸發 onSelect、鍵盤導覽自動 skip(由 consumer SelectMenu / DropdownMenu / cmdk 處理)。已在「選擇 / 狀態視覺規則」段 codify。
 - **Loading**:MenuItem 為單一 row primitive 非 async surface,本身不擁有 loading prop。Async option list 的 loading 由 consumer(SelectMenu / Combobox / DropdownMenu)在 list body 替換為 `<Empty icon={<CircularProgress/>}/>`(SelectMenu SSOT)。
 - **Empty(label-only / icon-only)**:label 為必傳;若無 prefix icon / avatar / checkbox,layout 自動收斂為 `[label] [suffix?]`;若無 suffix(shortcut / endAction / chevron),收斂為純 `[label]`。
 - **極長 label / description**:預設各 clamp 1 行 truncate(見「Clamp 政策」),row 高度恆為兩種之一不被撐高。
@@ -278,7 +279,7 @@ MenuItem 的狀態色(default / hover / selected / disabled)是**結構性的**
 
 ## A11y 預設
 
-**ARIA / Pattern**:對齊 [W3C ARIA Authoring Practices Guide](https://www.w3.org/WAI/ARIA/apg/patterns/) 對應 pattern。
+**ARIA / Pattern**:對齊 [W3C ARIA Authoring Practices Guide](https://www.w3.org/WAI/ARIA/apg/patterns/) 對應 pattern。直接使用時 MenuItem 預設渲染 `role="option"` + `aria-selected` / `aria-disabled`;consumer 把 MenuItem 巢狀在 Radix / cmdk 互動節點內時傳 `role="presentation"`,MenuItem 同步抑制 `aria-selected` / `aria-disabled`(presentation 節點不得掛 ARIA state;ARIA 單一 owner = 外層 primitive),僅保留 `data-selected` / `data-disabled` 供樣式。
 
 **Keyboard 行為**(由外層選單元件提供,MenuItem 本身不實作任何 key handler,只渲染 row 視覺):
 

package/src/components/Menu/menu-item.tsx

@@ -185,12 +185,21 @@ const MenuItem = React.forwardRef<HTMLDivElement, MenuItemProps>(
       )
     }
 
+    // ── ARIA 單一 owner gate(2026-07-05)──
+    // consumer(DropdownMenu 各 item / SelectMenu option row)把 MenuItem 巢狀在 Radix / cmdk
+    // 互動節點內時傳 role="presentation":外層 primitive 是唯一 ARIA owner(aria-checked /
+    // aria-disabled 由外層宣告)。presentation 節點不得掛 ARIA state(axe aria-prohibited-attr
+    // + 內外雙重宣告)→ 同步抑制 role="option" 與 aria-selected / aria-disabled 預設;
+    // data-selected / data-disabled 保留(純樣式 hook,非 ARIA)。正規 listbox option 用法
+    //(不傳 role)與 select-all row(role="checkbox")不受影響。
+    const isPresentation = props.role === 'presentation'
+
     return (
       <div
         ref={ref}
-        role="option"
-        aria-selected={selected || (checked === true) || undefined}
-        aria-disabled={disabled || undefined}
+        role={isPresentation ? 'presentation' : 'option'}
+        aria-selected={isPresentation ? undefined : selected || (checked === true) || undefined}
+        aria-disabled={isPresentation ? undefined : disabled || undefined}
         data-selected={selected ? '' : undefined}
         data-disabled={disabled ? '' : undefined}
         className={cn(
@@ -202,9 +211,11 @@ const MenuItem = React.forwardRef<HTMLDivElement, MenuItemProps>(
           disabled && 'text-fg-disabled cursor-not-allowed',
           className,
         )}
+        // 2026-07-04 robustness:先 spread 其餘 props、後放 guarded handlers — 消除
+        // 「handler 置前 + 後方 runtime filter 同名 key」對屬性順序的隱性依賴,行為不變
+        {...Object.fromEntries(Object.entries(props).filter(([k]) => k !== 'onClick' && k !== 'onKeyDown'))}
         onClick={disabled ? undefined : props.onClick}
         onKeyDown={disabled ? undefined : props.onKeyDown}
-        {...Object.fromEntries(Object.entries(props).filter(([k]) => k !== 'onClick' && k !== 'onKeyDown'))}
       >
         {/* Prefix 對齊容器 */}
         {hasPrefix && (

package/src/components/Notice/notice.anatomy.stories.tsx

@@ -96,6 +96,7 @@ export const Overview: Story = {
                 升級方案
               </Button>
             }
+            onDismiss={() => {}} // anatomy 4-slot 展示含 dismiss X(2026-07-05 D4:X 僅在傳 onDismiss 時渲染)
           />
         </SubtleShell>
       </div>
@@ -189,13 +190,13 @@ export const Overview: Story = {
                 <Td mono>dismissible</Td>
                 <Td mono>boolean</Td>
                 <Td mono>true</Td>
-                <Td>顯示關閉按鈕</Td>
+                <Td>搭配 onDismiss 顯示關閉按鈕(兩者同時成立才渲染 X)</Td>
               </tr>
               <tr>
                 <Td mono>onDismiss</Td>
                 <Td mono>() =&gt; void</Td>
                 <Td mono>undefined</Td>
-                <Td>關閉按鈕 callback</Td>
+                <Td>關閉按鈕 callback;未傳則不渲染 X(2026-07-05 D4)</Td>
               </tr>
               <tr>
                 <Td mono>iconClassName</Td>
@@ -248,6 +249,7 @@ function NoticeInspector() {
                 ) : undefined
               }
               dismissible={dismissible}
+              onDismiss={() => {}} // 2026-07-05 D4:X 僅在傳 onDismiss 時渲染,Inspector 切 dismissible 才看得到 X
             />
           </SubtleShell>
         </div>
@@ -481,19 +483,22 @@ export const StateBehavior: Story = {
       <div>
         <H3>Dismissible 行為</H3>
         <Desc>
-          Alert 預設可 dismiss(持久通知,使用者需主動關);Toast 通常不 dismiss(計時器自動關)。兩者共用 Notice,僅透過
+          Alert 預設可 dismiss(持久通知,使用者需主動關);Toast 通常不 dismiss(計時器自動關)。兩者共用 Notice,透過
           <code className="font-mono text-footnote mx-1">dismissible</code>
-          prop 控制。
+          +
+          <code className="font-mono text-footnote mx-1">onDismiss</code>
+          控制(X 僅在兩者同時成立時渲染——未接 handler 的 X 是死按鈕,2026-07-05 D4)。
         </Desc>
         <div className="grid grid-cols-2 gap-3 max-w-3xl">
           <div>
-            <p className="text-caption text-fg-muted mb-2">dismissible (default)</p>
+            <p className="text-caption text-fg-muted mb-2">dismissible + onDismiss</p>
             <SubtleShell variant="info">
               <Notice
                 variant="info"
                 iconClassName={SUBTLE_ICON_COLOR.info}
                 title="Audit log 僅限 Business 方案"
                 dismissible
+                onDismiss={() => {}}
               />
             </SubtleShell>
           </div>

package/src/components/Notice/notice.spec.md

@@ -57,7 +57,7 @@ item-layout 4-slot：
 ```
 
 - Icon: 16px，`h-[1lh]` inline 對齊 first line
-- Dismiss X: `<Button iconOnly dismiss size="xs" />` — chrome corner action group region(Cat 3)。xs 是 **Notification banner family canonical**(Notice / Alert / Toast inherit):ephemeral banner `px-4 py-3` 固定不隨 density,dismiss 邊角小 affordance 輕量不搶眼。詳見 `patterns/overlay-surface/overlay-surface.spec.md`「Chrome dismiss size canonical」(overlay header 走 sm native + 負 margin trick;只有 notification banner family 用 xs)+ `patterns/element-anatomy/item-anatomy.spec.md`「Dismiss canonical — X close only」
+- Dismiss X: `<Button iconOnly dismiss size="xs" />` — chrome corner action group region(Cat 3)。xs 是 **Notification banner family canonical**(Notice / Alert / Toast inherit):ephemeral banner `px-4 py-3` 固定不隨 density,dismiss 邊角小 affordance 輕量不搶眼。詳見 `patterns/overlay-surface/overlay-surface.spec.md`「Chrome dismiss size canonical」(overlay header 走 sm native + 負 margin trick;只有 notification banner family 用 xs)+ `patterns/element-anatomy/inline-action.spec.md`「Dismiss canonical — X close only」
 - endContent: 通常放 `<Button variant="tertiary" size="xs">`
 
 ## Variant
@@ -121,6 +121,7 @@ Notice 是 **Toast / Alert 共用的 layout primitive**,刻意不擁有尺寸與
 - **Loading**:Notice 非 async surface,無 loading state。Body 內若 consumer 注入 CTA Button,該 Button 自行處理 loading。
 - **Empty**:Notice 的 `title` 為必填(TypeScript required prop,消費合約),`description` 選填;layout 至少 1 行 title 內容。誤傳空字串時照常 render(無 runtime warn / throw),空 title 的內容責任在 consumer(Alert / Toast)。`neutral` variant 不渲 status icon 時即為 title-only icon-less 形態(見 `NeutralTitleOnly` story),仍合法 render。
 - **Icon-only / variant=neutral**:`neutral` variant 不渲 status icon,layout 自動收斂為 `[title + description?]  [endContent?]  [dismiss X?]` 三 slot。
+- **`dismissible` 無 `onDismiss`**(2026-07-05 D4):X 渲染條件 = `dismissible`(預設 true)**且**有傳 `onDismiss`——Notice / Alert 為 controlled-only(不自我移除),無 handler 的 X 是可 focus、SR 播報「關閉通知」但按下零反應的死按鈕(假 affordance)。對齊 Polaris Banner(`onDismiss` 存在才顯示 X)/ Ant Alert(`closable` 預設 false)。顯式傳 `dismissible={true}` 卻缺 `onDismiss` 時 dev-only `console.warn` 提示(預設未傳不吵)。
 
 ---
 
@@ -138,12 +139,12 @@ Notice 是 **Toast / Alert 共用的 layout primitive**,刻意不擁有尺寸與
 
 **Keyboard 行為**:
 
-- Tab — focus dismiss button(若 dismissible)
+- Tab — focus dismiss button(若 dismissible 且有傳 `onDismiss`——X 僅在兩者同時成立時渲染,見「邊界案例」,2026-07-05 D4;consumer 經 `endContent` 注入互動元素時,其 DOM 順序在 dismiss 之前,Tab 先落 endContent)
 - Enter / Space — 觸發 focus 中的 dismiss button(原生 button 行為,呼叫 `onDismiss`)
 
 Notice **不**自帶 Esc-to-dismiss 行為(`notice.tsx` 無 keydown handler);dismiss 純粹由 dismiss button 的 `onClick={onDismiss}` 觸發。若 consumer(Alert / Toast)需要 Esc 關閉,於 consumer 層自行掛 keydown。Dismiss 後的焦點處置 Notice 同樣不管理(無 focus restoration 邏輯)——節點移除後焦點落點由 consumer(Alert / Toast host)決定。
 
-**Focus**:唯一 focusable 元素是 dismiss `<Button>`,focus indicator 走 Button canonical(`focus-visible:ring-2 ring-ring`,box-shadow ring 非 CSS `outline`);Notice 本身無 focus management(dismiss 後焦點處置見上段,由 consumer 決定)。
+**Focus**:Notice 自身渲染的唯一 focusable 元素是 dismiss `<Button>`(consumer 經 `endContent` 注入的互動元素——如上方建議的 tertiary Button——由 consumer 自管 a11y),focus indicator 走 Button canonical(`focus-visible:ring-2 ring-ring`,box-shadow ring 非 CSS `outline`);Notice 本身無 focus management(dismiss 後焦點處置見上段,由 consumer 決定)。
 
 **驗證**:Storybook a11y addon panel 應 0 critical violation;鍵盤完整可操作(無需滑鼠)。WCAG AA contrast ≥ 4.5:1(text)/ 3:1(UI)。
 

package/src/components/Notice/notice.tsx

@@ -6,7 +6,7 @@ import * as React from 'react'
 import { X as XIcon, Info, CircleCheck, TriangleAlert, XCircle, type LucideIcon } from 'lucide-react'
 import { cn } from '@/lib/utils'
 import { Button } from '@/design-system/components/Button/button'
-import { ItemContent, ItemPrefix, ItemSuffix } from '@/design-system/patterns/element-anatomy/item-anatomy'
+import { ICON_SIZE, ItemContent, ItemPrefix, ItemSuffix } from '@/design-system/patterns/element-anatomy/item-anatomy'
 
 /**
  * Notice — Toast / Alert 共用的視覺佈局層
@@ -75,6 +75,11 @@ export interface NoticeProps
   title: React.ReactNode
   description?: React.ReactNode
   endContent?: React.ReactNode
+  /**
+   * 顯示關閉鈕(預設 true)。**需同時傳 `onDismiss` 才會渲染 X** — Notice 是 controlled-only
+   * (不自我移除),無 handler 的 X 是可 focus、SR 播報「關閉通知」但按下零反應的死按鈕
+   * (2026-07-05 D4;對齊 Polaris Banner `onDismiss` 存在才顯示 X / Ant Alert `closable` 預設 false)。
+   */
   dismissible?: boolean
   onDismiss?: () => void
   /** ARIA label for the dismiss button. Override for i18n. Default: "關閉通知" */
@@ -99,7 +104,9 @@ const Notice = React.forwardRef<HTMLDivElement, NoticeProps>(
       title,
       description,
       endContent,
-      dismissible = true,
+      // 不 destructure-default(保留「顯式傳 true」的可辨識性給下方 dev-warn);等效預設 true 由
+      // showDismiss 的 `!== false` 承擔。
+      dismissible,
       onDismiss,
       dismissAriaLabel = '關閉通知', // i18n-allow: DS default; consumer override via dismissAriaLabel prop
       iconClassName,
@@ -110,6 +117,16 @@ const Notice = React.forwardRef<HTMLDivElement, NoticeProps>(
   ) => {
     const StatusIcon = VARIANT_ICON[variant]
 
+    // 2026-07-05 D4:X 渲染條件 = dismissible(預設 true)**且**有傳 onDismiss — 原 `dismissible &&`
+    // 單獨判斷讓預設用法 <Alert title="…"/> 渲染一顆死 X(controlled-only 不自我移除,onClick=undefined
+    // 零反應;keyboard / SR 使用者按 Enter 零回饋 = 假 affordance)。對齊 Polaris Banner(onDismiss
+    // 存在才顯示 X)/ Ant Alert(closable 預設 false)。
+    const showDismiss = dismissible !== false && onDismiss != null
+    if (process.env.NODE_ENV !== 'production' && dismissible === true && onDismiss == null) {
+      // 只在「顯式傳 dismissible={true} 卻沒接 onDismiss」的消費端矛盾時提示(預設 undefined 不吵)
+      console.warn('[Notice] dismissible=true 但未傳 onDismiss,關閉鈕不會渲染(需同時提供 onDismiss)。')
+    }
+
     return (
       <div
         ref={ref}
@@ -118,7 +135,7 @@ const Notice = React.forwardRef<HTMLDivElement, NoticeProps>(
       >
         {StatusIcon && (
           <ItemPrefix>
-            <StatusIcon size={16} className={cn('shrink-0', iconClassName)} aria-hidden />
+            <StatusIcon size={ICON_SIZE.md} className={cn('shrink-0', iconClassName)} aria-hidden />
           </ItemPrefix>
         )}
 
@@ -130,7 +147,7 @@ const Notice = React.forwardRef<HTMLDivElement, NoticeProps>(
           labelClassName={description ? 'font-medium' : undefined}
         />
 
-        {(endContent || dismissible) && (
+        {(endContent || showDismiss) && (
           // 2026-06-15 user 拍板:消費 ItemSuffix primitive(原手刻 div + @row-slot-handcraft-allow
           // 已移除)。item-anatomy.spec.md 把 Notice 的 action/dismiss 對應到 suffix slot;ItemSuffix
           // base geometry(h-[1lh] shrink-0 ml-auto flex items-center gap-2)正是此處所需,hoverReveal
@@ -138,7 +155,7 @@ const Notice = React.forwardRef<HTMLDivElement, NoticeProps>(
           // family canonical,overlay-surface.spec.md「Chrome dismiss size canonical」)。
           <ItemSuffix>
             {endContent}
-            {dismissible && (
+            {showDismiss && (
               <Button
                 data-dismiss
                 iconOnly

package/src/components/NumberInput/number-input.anatomy.stories.tsx

@@ -178,7 +178,7 @@ export const Overview = {
           <div className="flex flex-col gap-2 items-start">
             <span className="text-[11px] text-fg-muted font-medium">edit</span>
             <div className="inline-flex items-center border-2 border-dashed border-primary/30 rounded-md px-3 py-2.5 gap-2">
-              {[{ name: 'wrapper', color: 'info' }, { name: 'wrapper', color: 'success' }, { name: 'wrapper', color: 'warning' }].map((s) => (
+              {[{ name: 'wrapper', color: 'info' }, { name: 'input', color: 'success' }, { name: 'endAction', color: 'warning' }].map((s) => (
                 <span key={s.name} className="rounded px-2 py-1 text-[11px] font-mono border border-dashed"
                   style={{ borderColor: `var(--${s.color})`, backgroundColor: `var(--${s.color}-subtle)`, color: `var(--${s.color})` }}>{s.name}</span>
               ))}
@@ -189,7 +189,7 @@ export const Overview = {
           <div className="flex flex-col gap-2 items-start">
             <span className="text-[11px] text-fg-muted font-medium">readonly / disabled</span>
             <div className="inline-flex items-center border-2 border-dashed border-primary/30 rounded-md px-3 py-2.5 gap-2">
-              {[{ name: 'wrapper', color: 'info' }, { name: 'wrapper', color: 'success' }].map((s) => (
+              {[{ name: 'wrapper', color: 'info' }, { name: 'formatted span', color: 'success' }].map((s) => (
                 <span key={s.name} className="rounded px-2 py-1 text-[11px] font-mono border border-dashed"
                   style={{ borderColor: `var(--${s.color})`, backgroundColor: `var(--${s.color}-subtle)`, color: `var(--${s.color})` }}>{s.name}</span>
               ))}
@@ -255,6 +255,7 @@ export const Overview = {
                 ['precision', 'number', '—', '小數位數'],
                 ['locale', 'string', "'en-US'", '數字格式 locale'],
                 ['endAction', 'InlineActionConfig', '—', '右側 inline action（宣告式 API）'],
+                ['endSlot', 'ReactNode', '—', '右側自訂 slot（escape hatch，僅 edit 渲染）；與 endAction 互斥，同時傳時 endSlot 優先'],
                 ['disabled', 'boolean', 'false', '原生屬性；mode 未顯式指定時解析為 disabled（顯式 mode prop 永遠最優先，useResolvedFieldMode SSOT）'],
                 ['readOnly', 'boolean', 'false', '原生屬性；mode 未顯式指定且無 Field context mode 時解析為 readonly（優先序 mode > 有效 disabled > fieldCtx.mode > readOnly）'],
               ].map(([p, t, d, desc]) => (
@@ -744,7 +745,7 @@ export const StateBehavior = {
               <div key={m} className="flex flex-col gap-1 items-start">
                 <span className="text-[11px] text-fg-muted font-mono">{m}</span>
                 <div className="w-[160px]"><NumberInput mode={m} value={null} prefix="$" /></div>
-                <span className="text-[10px] text-fg-muted">{m === 'edit' ? '空白 input' : 'em dash — + fg-muted'}</span>
+                <span className="text-[10px] text-fg-muted">{m === 'edit' ? '空白 input' : m === 'disabled' ? 'em dash — + fg-disabled（M24 state > emphasis）' : 'em dash — + fg-muted'}</span>
               </div>
             ))}
           </div>
@@ -781,7 +782,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">{"ARIA  :使用原生  <input type=\"text\" inputMode=\"decimal\">  ;外層 Field 自動補上標籤、錯誤狀態與描述的關聯。 inputMode=\"decimal\"  讓行動裝置彈出數字鍵盤。\n\n  鍵盤行為  :\n\n- Tab — 移入欄位\n- 數字鍵 — 輸入數值\n\n  焦點  :原生 input 焦點外框,聚焦時外框轉為主色,由外層 Field 提供。\n\n  驗證  :Storybook 無障礙檢查面板應為 0 項嚴重問題;不靠滑鼠也能完整操作。文字對比度至少 4.5:1、介面元件至少 3:1(WCAG AA)。"}</p>
+      <p className="whitespace-pre-line">{"ARIA  :使用原生  <input type=\"text\" inputMode=\"decimal\">  ;外層 Field 自動補上標籤、錯誤狀態與描述的關聯。 inputMode=\"decimal\"  讓行動裝置彈出數字鍵盤。\n\n  鍵盤行為  :\n\n- Tab — 移入欄位\n- 數字鍵 — 輸入數值\n\n  焦點  :原生 input 以  outline-none  移除預設焦點外框;聚焦時由元件自身 wrapper 的  focus-within  將邊框轉為主色(border-primary)。\n\n  驗證  :Storybook 無障礙檢查面板應為 0 項嚴重問題;不靠滑鼠也能完整操作。文字對比度至少 4.5:1、介面元件至少 3:1(WCAG AA)。"}</p>
     </div>
   ),
 }

package/src/components/NumberInput/number-input.principles.stories.tsx

@@ -1,4 +1,5 @@
 // @principles-rationale: UsageGuidance merges WhenToUse + WhenNotToUse into single 使用指引 story per refactor task (2026-04-26)
+// @story-baseline: packages/design-system/src/components/DataTable/data-table.stories.tsx#NumberAlignment
 import React from 'react'
 import LinkTo from '@storybook/addon-links/react'
 import type { Meta, StoryObj } from '@storybook/react'
@@ -35,7 +36,7 @@ const Label = ({ children, warn }: { children: React.ReactNode; warn?: boolean }
 
 const Section = ({ title, children }: { title: string; children: React.ReactNode }) => (
   <section className="mb-12">
-    <h2 className="text-heading-3 font-bold text-foreground mb-4 pb-2 border-b border-border">{title}</h2>
+    <h2 className="text-h3 font-bold text-foreground mb-4 pb-2 border-b border-border">{title}</h2>
     {children}
   </section>
 )

package/src/components/NumberInput/number-input.spec.md

@@ -106,7 +106,8 @@ col.accessor('price', {
 - **Disabled**:由 Field SSOT own(`Field/field-controls.spec.md` State machine 段)。視覺:wrapper bg → `bg-disabled`(neutral-2,`semantic.css` `--bg-disabled`)、formatted text → `text-fg-disabled`(M24 state>emphasis)。Display mode + disabled 維持格式化輸出但 token 切 disabled。
 - **Loading**:NumberInput 不提供 loading state(`NumberInputProps` 無 `loading` prop、無 `CircularProgress` / `aria-busy` 邏輯)。數值輸入為同步操作,無 async fetch 語意;若需 async 場景(如遠端校驗)請走外層 Field validation + `endSlot` 自訂 spinner。
 - **Empty(null / undefined / 空字串)**:Display mode 渲 `—`(em dash + `text-fg-muted`);Edit mode placeholder 走 default placeholder color。
-- **Invalid input**(non-numeric):input 為 `type="text" inputMode="decimal"`,onChange 以 `Number(raw)` parse,NaN 時忽略不觸發 `onChange`(value 維持原值);搭配 Field validation 渲 error variant(`aria-invalid="true"` + `text-fg-error` border + 下方 error message)。
+- **Invalid input**(non-numeric):input 為 `type="text" inputMode="decimal"`,onChange 以 `Number(raw)` parse,NaN 時忽略不觸發 `onChange`(value 維持原值);搭配 Field validation 渲 error variant(`aria-invalid="true"` + wrapper `border-error`(hover 時 `border-error-hover`)+ 下方 error message)。
+- **輸入中間態**(`-`、`1.`、`0.0` 等 parse 後 lossy 的 raw 字串,2026-07-05 D4 codify):edit mode 以 internal draft string 承載——輸入期間 DOM 顯示 draft 原字串(負號、尾點不被 controlled 回寫吃掉),parse 成功即時同步 `onChange(parsed)`;blur / Enter commit(清 draft、顯示回 committed value,不合法殘字自然還原)、Escape 棄 draft(對齊 form-validation 規則 4)。value 面語意不變:`''` / `'-'` 視為 `null`。對齊 Ant InputNumber / Adobe Spectrum NumberField internal draft canonical。 <!-- @benchmark-unverified -->
 - **負數 / 超大數字**:`toLocaleString(locale)` 自動處理負號與千分位分組,無特殊 prop。
 - **科學記號輸入**(`1e5`):`Number(raw)` parse 為 `100000`,非 NaN 即觸發 `onChange`(`number-input.tsx:136-138`)。
 - **精度上限**:`precision` > 6 為禁止事項(浮點精度雜訊),極端精度走 `Input` + 自驗證。

package/src/components/NumberInput/number-input.tsx

@@ -89,6 +89,8 @@ const NumberInput = React.forwardRef<HTMLInputElement, NumberInputProps>(
       disabled: disabledProp,
       readOnly,
       id: idProp,
+      onBlur: onBlurProp,
+      onKeyDown: onKeyDownProp,
       'aria-describedby': ariaDescribedByProp,
       'aria-errormessage': ariaErrorMessageProp,
       ...props
@@ -104,6 +106,15 @@ const NumberInput = React.forwardRef<HTMLInputElement, NumberInputProps>(
     // 2026-06-08 SSOT:mode 經 useResolvedFieldMode 統一解析(prop > 有效 disabled > fieldCtx.mode > readOnly > 'edit')
     const resolvedMode: FieldMode = useResolvedFieldMode({ mode: modeProp, disabled, readOnly })
 
+    // 2026-07-05 D4 draft state:controlled value 回寫會吃掉輸入中間態('-'、'1.'、'0.0' 等
+    // parse 後 lossy 的 raw 字串)— 例:已有值 5 全選打「-」→ onChange(null) 回寫把 DOM 重設
+    // 為空,負號被吃、無法打出 -5。修法對齊 Ant InputNumber / Adobe Spectrum NumberField 的
+    // internal draft string canonical:輸入期間 DOM 顯示以 local draft 優先,parse 成功即時同步
+    // onChange(parsed);blur / Enter commit 清 draft 回 value 顯示;Escape 一併棄 draft(對齊
+    // form-validation 規則 4 回復原值)。宣告於 non-edit early return 之前(Rules-of-Hooks,
+    // 同 LinkInput 2026-07-04 修法)。
+    const [draft, setDraft] = React.useState<string | null>(null)
+
     // display / readonly / disabled 都顯示格式化值(span 取代 input)
     if (resolvedMode !== 'edit') {
       return (
@@ -125,10 +136,11 @@ const NumberInput = React.forwardRef<HTMLInputElement, NumberInputProps>(
       )
     }
 
-    // edit 模式：raw 數值輸入
+    // edit 模式:raw 數值輸入(draft 承載中間態;value 面語意不變 — ''/'-' 視為空、NaN 忽略)
     const handleChange = (e: React.ChangeEvent<HTMLInputElement>) => {
-      if (!onChange) return
       const raw = e.target.value
+      setDraft(raw)
+      if (!onChange) return
       if (raw === '' || raw === '-') {
         onChange(null)
         return
@@ -142,11 +154,7 @@ const NumberInput = React.forwardRef<HTMLInputElement, NumberInputProps>(
     return (
       <div
         className={cn(
-          fieldWrapperStyles({ mode: 'edit', variant: variant, size }),
-          error && [
-            'border-error hover:border-error-hover',
-            'focus-within:border-error focus-within:hover:border-error',
-          ],
+          fieldWrapperStyles({ mode: 'edit', variant: variant, size, error }),
           className,
         )}
         data-field-mode="edit"
@@ -157,8 +165,15 @@ const NumberInput = React.forwardRef<HTMLInputElement, NumberInputProps>(
           type="text"
           inputMode="decimal"
           id={idProp ?? fieldCtx?.id}
-          value={value ?? ''}
+          // 輸入期間 draft(raw 字串)優先;非輸入期間才從 value prop 同步顯示(2026-07-05 D4)
+          value={draft ?? (value != null ? String(value) : '')}
           onChange={handleChange}
+          // blur / Enter = commit(清 draft,顯示回 committed value);Escape 棄 draft
+          onBlur={(e) => { setDraft(null); onBlurProp?.(e) }}
+          onKeyDown={(e) => {
+            if (e.key === 'Enter' || e.key === 'Escape') setDraft(null)
+            onKeyDownProp?.(e)
+          }}
           aria-invalid={error || undefined}
           aria-required={fieldCtx?.required || undefined}
           aria-describedby={ariaDescribedByProp ?? fieldCtx?.descriptionId}
@@ -190,7 +205,8 @@ export const numberInputMeta = {
   sizes: {
 
   },
-  states: ['default', 'hover', 'active', 'focus-visible', 'disabled'],
+  // 'active' 移除 — Field chrome 無按壓態;stepper 按壓屬內嵌 ItemInlineActionButton(2026-07-07 詞彙統一 DS-wide 按壓訊號盤點:檔內 0 active: utility / 0 *-active token)。
+  states: ['default', 'hover', 'focus-visible', 'disabled'],
   tokens: {
     bg: [],
     fg: ['text-fg-disabled', 'text-fg-muted'],

package/src/components/OverflowIndicator/overflow-indicator.anatomy.stories.tsx

@@ -46,8 +46,8 @@ type ShapeKey = 'circle' | 'tag'
 const SIZES: SizeKey[] = ['sm', 'md', 'lg']
 const SHAPES: ShapeKey[] = ['circle', 'tag']
 
-// font-size 依 shape 分流(re-verified 2026-06-01):circle shape 走元件內建 triggerText
-// map(overflow-indicator.tsx:24-28),tag shape 走 tagVariants({ size })(tag.tsx:45-47)。
+// font-size 依 shape 分流(re-verified 2026-07-04):circle shape 走元件內建 triggerText
+// map(overflow-indicator.tsx:28-32),tag shape 走 tagVariants({ size })(tag.tsx:40-44)。
 // circleText / tagText 兩欄分別對應,避免把 circle-only 字級當成兩 shape 通用。
 const SIZE_SPECS: Record<
   SizeKey,
@@ -467,7 +467,7 @@ export const SizeMatrix: Story = {
           <code className="font-mono">tag</code> 走 <code className="font-mono">tagVariants</code>(對齊 Tag 字級)。
           circle shape 的 <code className="font-mono">sm</code> 用
           <code className="font-mono mx-1">text-[10px]</code>
-          的理由見 spec「尺寸」段——sub-footnote 特殊例外,與 Badge 共享 micro-indicator typography tier。
+          的理由見 spec「尺寸」段——與 Badge 共享 micro-indicator typography tier 的特殊例外(10px)。
         </p>
       </div>
 

package/src/components/OverflowIndicator/overflow-indicator.spec.md

@@ -63,7 +63,7 @@ sm / md 跟 Tag 同階（20/24px），lg 對齊 md（尺寸需求一致，不需
 
 **字級依 shape 分流**：`circle` shape 走元件內建的 `triggerText` map（sm 10px / md·lg 12px）；`tag` shape 直接套 `tagVariants({ size })`（sm 12px / md·lg 14px，見 `tag.spec.md`），刻意對齊 Tag 視覺一致（見上方「trigger 不用 Tag 元件」段）。下方「sm 用 `text-[10px]`」的理由僅適用於 circle shape。
 
-**sm 用 `text-[10px]` 的理由**：sub-footnote 特殊例外,與 Badge 共享「micro-indicator typography」tier——trigger 數字是次要輔助 indicator（非主訊息）,在 20px 小容器內 12px 會擠。完整理由與 pattern-family 說明詳見 `badge.spec.md`「字體例外：`text-[10px]`」。若未來 OverflowIndicator / Badge 以外的元件也需要 sub-footnote 尺寸,應在 typography system 加 `--font-micro` token,再改用 token 而非 arbitrary value。
+**sm 用 `text-[10px]` 的理由**：micro-indicator 特殊例外（10px,與 `--font-footnote` 同值但不消費其 utility——lh 1.3 vs 需要的緊湊行高）,與 Badge 共享「micro-indicator typography」tier——trigger 數字是次要輔助 indicator（非主訊息）,在 20px 小容器內 caption 12px 會擠。完整理由與 pattern-family 說明詳見 `badge.spec.md`「字體例外：`text-[10px]`」。若未來 OverflowIndicator / Badge 以外的元件也需要這個 10px micro-indicator 尺寸,先依 `badge.spec.md`「其他元件不得比照」歸同一 family 討論,確立第三個消費者才升 typography token,而非直接抄 arbitrary value。
 
 ---
 

package/src/components/OverflowIndicator/overflow-indicator.tsx

@@ -158,7 +158,8 @@ export const overflowIndicatorMeta = {
   sizes: {
 
   },
-  states: ['default', 'hover', 'active', 'focus-visible', 'disabled'],
+  // 2026-07-04 audit 對齊(spec:95「本身無 hover / active / disabled / selected 變化」;code 有 focus-visible ring tsx:106/121)
+  states: ['default', 'focus-visible'],
   tokens: {
     bg: ['bg-muted'],
     fg: ['text-foreground'],

package/src/components/Pagination/index.ts

@@ -0,0 +1,5 @@
+// AUTO-GENERATED by scripts/gen-component-indexes.mjs — DO NOT EDIT MANUALLY.
+// Re-export pattern enables package.json exports map subpath:
+//   import { ... } from '@qijenchen/design-system/{components,patterns}/<Dir>'
+// Regenerate: node scripts/gen-component-indexes.mjs
+export * from './pagination'

package/src/components/Pagination/pagination.anatomy.stories.tsx

@@ -0,0 +1,143 @@
+// @anatomy-exempt: anatomy specs / token 對照表格用 raw <table>,非業務資料表。業務資料表才用 <DataTable>。
+//   SizeMatrix N/A — 無 size 軸(按鈕固定 size="sm",chrome 級導覽不隨密度縮放;詳 pagination.spec.md「SizeMatrix N/A rationale」)
+import React from 'react'
+import type { Meta, StoryObj } from '@storybook/react'
+import { Pagination } from './pagination'
+import { H3, Desc, Td, Th, TokenCell } from '@/design-system/stories-helpers/anatomy/anatomy-utils'
+
+type InspectorArgs = {
+  page: number
+  total: number
+}
+
+const meta: Meta = {
+  title: 'Design System/Components/Pagination/設計規格',
+  parameters: { layout: 'padded' },
+}
+export default meta
+type Story = StoryObj
+type InspectorStory = StoryObj<InspectorArgs>
+
+export const Overview: Story = {
+  name: '元件總覽',
+  render: () => {
+    const [page, setPage] = React.useState(5)
+    return (
+      <div className="flex flex-col gap-10">
+        <div>
+          <H3>Anatomy</H3>
+          <Desc>
+            {'nav[aria-label="Pagination"] > ul > li(shadcn 骨架);上下頁 = Button text sm iconOnly,'}
+            {'未選數字 = Button text sm、當前頁 = Button secondary(等寬 min-w = field-height-sm,方形節奏對齊 Ant);'}
+            {'當前頁 aria-current="page" + 選中 canonical(主色描邊+染字、不染底,semantic.css SSOT);'}
+            {'… = MoreHorizontal 純指示(aria-hidden,不可點)。格位恆 ≤ 7(boundary/sibling = 1/1)。'}
+          </Desc>
+          <Pagination total={240} page={page} onPageChange={setPage} />
+        </div>
+      </div>
+    )
+  },
+}
+
+export const Inspector: InspectorStory = {
+  name: '互動檢視',
+  args: { page: 5, total: 240 },
+  argTypes: {
+    page: { control: { type: 'number', min: 1, max: 500 } },
+    total: { control: { type: 'number', min: 0, max: 10000 } },
+  },
+  render: (args) => (
+    <div className="flex flex-col gap-3">
+      <Desc>調 page / total 觀察摺疊行為(總頁數 = ceil(total / 20)):≤ 7 頁不摺疊;超過後依當前頁位置單側或雙側摺疊。</Desc>
+      <Pagination total={args.total} page={args.page} onPageChange={() => {}} />
+    </div>
+  ),
+}
+
+export const ColorMatrix: Story = {
+  name: '色彩對照',
+  render: () => (
+    <div className="flex flex-col gap-6">
+      <Desc>
+        數字鈕四態的 token 對照。default / hover / disabled 全數繼承 Button text variant;
+        selected(當前頁)消費 DS「持續選中」canonical —— 主色 base 同時染邊框與文字、底色維持
+        surface 不染(semantic.css「選中狀態」段 SSOT;與 Chip / SegmentedControl 選中同族)。
+      </Desc>
+      <table className="text-body">
+        <thead>
+          <tr><Th>State</Th><Th>text</Th><Th>border</Th><Th>bg</Th></tr>
+        </thead>
+        <tbody>
+          <tr>
+            <Td>default</Td>
+            <Td><TokenCell token="--fg" display="text-foreground" /></Td>
+            <Td mono>transparent(佔位防選中位移)</Td>
+            <Td mono>transparent</Td>
+          </tr>
+          <tr>
+            <Td>hover</Td>
+            <Td><TokenCell token="--fg" display="text-foreground" /></Td>
+            <Td mono>transparent</Td>
+            <Td><TokenCell token="--neutral-hover" display="bg-neutral-hover" /></Td>
+          </tr>
+          <tr>
+            <Td>selected(當前頁 = Button secondary)</Td>
+            <Td><TokenCell token="--primary" display="text-primary" /></Td>
+            <Td><TokenCell token="--primary" display="border-primary" /></Td>
+            <Td><TokenCell token="--surface" display="bg-surface(不染底,同 Chip selected)" /></Td>
+          </tr>
+          <tr>
+            <Td>disabled(上下頁邊界)</Td>
+            <Td><TokenCell token="--fg-disabled" display="text-fg-disabled" /></Td>
+            <Td mono>transparent</Td>
+            <Td mono>transparent</Td>
+          </tr>
+        </tbody>
+      </table>
+      <div className="flex flex-col gap-2">
+        <p className="text-caption text-fg-muted">實例對照(第 1 頁:上一頁 disabled + 當前頁選中):</p>
+        <Pagination total={100} page={1} onPageChange={() => {}} />
+      </div>
+    </div>
+  ),
+}
+
+export const StateBehavior: Story = {
+  name: '狀態行為',
+  render: () => {
+    const [page, setPage] = React.useState(2)
+    return (
+      <div className="flex flex-col gap-6">
+        <Desc>
+          hover / active / focus-visible 全數繼承 Button:未選數字與上下頁 = text variant(hover 淡灰底、
+          active 深一階);當前頁 = secondary variant(hover 升 primary-hover 階、按壓 primary-active,
+          無灰底 —— 選中之上的互動 = 同色相升降階)。當前頁是位置指示非 toggle —— 點擊當前頁
+          fire onPageChange(同頁),不會「取消選中」。第一頁 / 最後一頁時對應箭頭 disabled
+          (focus 掉落行為對齊 Ant / MUI,不做 focus 轉移)。
+        </Desc>
+        <Pagination total={100} page={page} onPageChange={setPage} />
+        <p className="text-caption text-fg-muted">目前在第 {page} 頁 —— 點數字 / 箭頭觀察 controlled 行為。</p>
+      </div>
+    )
+  },
+}
+
+export const Accessibility: Story = {
+  name: '無障礙',
+  render: () => (
+    <div className="flex flex-col gap-4 max-w-[720px]">
+      <H3>A11y 預設</H3>
+      <p className="text-body leading-relaxed whitespace-pre-line">
+        {'ARIA:WAI-ARIA 無專門 pagination pattern,公認做法(shadcn / MUI / Atlassian 一致)=\n' +
+          '- root <nav aria-label="Pagination">(landmark;英文 pattern 名,follow Breadcrumb 慣例)\n' +
+          '- 當前頁 aria-current="page"(不用 aria-pressed —— pressed 是可取消 toggle,當前頁不可取消)\n' +
+          '- ellipsis aria-hidden(純視覺指示)\n' +
+          '- 上下頁 iconOnly 帶 aria-label(預設「上一頁」/「下一頁」,props 可覆寫)\n\n' +
+          '鍵盤:Tab 逐鈕(原生 button 序)、Enter / Space 觸發 —— 全繼承 Button 原生語意,' +
+          '不做 roving tabindex(nav landmark 內獨立按鈕群,非 composite widget)。\n\n' +
+          '驗證:Storybook a11y 面板 0 critical violation;純鍵盤可完成翻頁與跳頁。'}
+      </p>
+      <Pagination total={180} page={3} onPageChange={() => {}} />
+    </div>
+  ),
+}