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

package/src/components/Input/input.anatomy.stories.tsx

@@ -58,7 +58,7 @@ const SIZE_SPECS: Record<SizeKey, SizeSpec> = {
 
 const MODE_DESC: Record<ModeKey, string> = {
   edit:     '表單可編輯欄位 — bg-surface + border + hover/focus 回饋',
-  display:  '純展示資料 — 無 chrome（transparent）+ 文字正常色，空值顯示 —（em dash）',
+  display:  '純展示資料 — 無 chrome（transparent + !px-0 !py-0 零內距，field-wrapper.tsx Path Ⅰ）+ 文字正常色，空值顯示 —（em dash）',
   readonly: '不可編輯但可見 — bg-readonly(neutral-2) + 無邊框 + 文字正常色',
   disabled: '被停用的欄位 — bg-disabled(neutral-2) + 無邊框 + 文字灰化',
 }
@@ -360,7 +360,7 @@ const InspectorInner = () => {
             </div>
             <div className="flex items-center">
               <div className="flex items-center rounded-md overflow-hidden" style={{ height: 52, outline: `2px solid ${Z.dim.text}22` }}>
-                <BpZone w={44} color={Z.pad} label={s.pxToken} sub={`${s.px}px`} />
+                <BpZone w={44} color={Z.pad} label={mode === 'display' ? '!px-0' : s.pxToken} sub={mode === 'display' ? '0px' : `${s.px}px`} />
                 {hasStartIcon && (
                   <>
                     <BpZone w={44} color={Z.icon} label={`${s.icon}px`} sub="icon" />
@@ -374,7 +374,7 @@ const InspectorInner = () => {
                     <BpZone w={44} color={Z.action} label={`${s.icon}px`} sub="action" />
                   </>
                 )}
-                <BpZone w={44} color={Z.pad} label={s.pxToken} sub={`${s.px}px`} />
+                <BpZone w={44} color={Z.pad} label={mode === 'display' ? '!px-0' : s.pxToken} sub={mode === 'display' ? '0px' : `${s.px}px`} />
               </div>
               <div className="ml-3 flex items-center" style={{ height: 52 }}>
                 <svg width="10" height="52" className="shrink-0">
@@ -425,7 +425,7 @@ const InspectorInner = () => {
           <div className="px-4 py-1">
             <div className="py-2 border-b border-divider"><span className="text-[10px] font-semibold text-fg-muted uppercase tracking-wider">Layout</span></div>
             <PropRow label="高度" dot={Z.dim.text}><TkVal token={s.heightToken} value={s.height} /></PropRow>
-            <PropRow label="左右內距" dot={Z.pad.text}><TkVal token={s.pxToken} value={`${s.px}px`} /></PropRow>
+            <PropRow label="左右內距" dot={Z.pad.text}><TkVal token={mode === 'display' ? '!px-0 !py-0' : s.pxToken} value={mode === 'display' ? '0px（零 chrome）' : `${s.px}px`} /></PropRow>
             <PropRow label="元素間距" dot={Z.gap.text}><TkVal token={s.gapToken} value={`${s.gap}px`} /></PropRow>
             {hasStartIcon && (
               <PropRow label="Icon 尺寸" dot={Z.icon.text}>{s.icon}px</PropRow>

package/src/components/Input/input.principles.stories.tsx

@@ -35,7 +35,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/Input/input.spec.md

@@ -109,7 +109,7 @@ endAction(host 內嵌 inline action)vs 獨立 `<Button iconOnly>` 的分界詳 `
 
 ## 邊界案例
 
-- **Disabled**:`disabled` prop 由 Field SSOT own(`Field/field.spec.md`「Field state machine SSOT」段)。視覺 token:wrapper bg → `bg-disabled`(neutral-2)、text → `text-fg-disabled`(neutral-6,M24 state>emphasis canonical)、startIcon → `text-fg-disabled`、endAction button 自動 disabled、cursor → `cursor-not-allowed`、border 弱化、無 hover/focus ring。`readOnly` 與 `disabled` 視覺分離:readOnly 維持 default text color(可選取複製)、disabled 全面弱化(不可選)。
+- **Disabled**:`disabled` prop 由 Field SSOT own(`Field/field.spec.md`「Field state machine SSOT」段)。視覺 token:wrapper bg → `bg-disabled`(neutral-2)、text → `text-fg-disabled`(neutral-6,M24 state>emphasis canonical)、startIcon → `text-fg-disabled`、endAction 不渲染(僅 edit mode 渲染)、cursor → `cursor-not-allowed`、border 弱化、無 hover/focus ring。`readOnly` 與 `disabled` 視覺分離:readOnly 維持 default text color(可選取複製)、disabled 全面弱化(不可選)。
 - **Loading**:已 codify(見「Loading」段)。`loading=true` 時 endAction slot 自動切 `<CircularProgress/>`,input 仍可編輯(Ant Search 派 idiom)。
 - **Empty(no value)**:placeholder 走 `text-fg-muted`(neutral-7);`disabled + empty` 時 placeholder 切 `text-fg-disabled`(M24 state precedence)。
 - **Dark mode**:走 semantic token 自動 adapt,無 per-component override。

package/src/components/Input/input.stories.tsx

@@ -2,6 +2,7 @@ import React from 'react'
 import type { Meta, StoryObj } from '@storybook/react'
 import { Search, Eye, EyeOff, X } from 'lucide-react'
 import { Input } from './input'
+import { Field, FieldLabel, FieldError } from '@/design-system/components/Field/field'
 import { Button } from '@/design-system/components/Button/button'
 import { Tooltip, TooltipContent, TooltipTrigger } from '@/design-system/components/Tooltip/tooltip'
 
@@ -114,15 +115,20 @@ export const EndAction: Story = {
 }
 
 /* ── Error ── */
+// 2026-07-04 audit Dim 24/M23(d):錯誤訊息改消費 Field + FieldError primitive(對齊 Textarea / TimePicker /
+// Rating showcase idiom),不手刻 <p text-error>(重複 FieldError 內部樣式 = drift 來源)。
 export const ErrorState: Story = {
   name: '錯誤狀態',
   render: () => (
     <div className="flex flex-col gap-4 max-w-sm">
-      <p className="text-caption text-fg-muted">Error 以紅色邊框表示。錯誤訊息由 Form help text 提供，不在 input 內放狀態 icon</p>
-      <div>
-        <Input error defaultValue="invalid-email@" />
-        <p className="text-caption text-error mt-1">請輸入有效的 email 地址</p>
-      </div>
+      <p className="text-caption text-fg-muted">Error 以紅色邊框表示。錯誤訊息由 FieldError 提供，不在 input 內放狀態 icon</p>
+      {/* Field invalid 自動 cascade 到 Input(useResolvedFieldInvalid),不需重複傳 error;
+          standalone <Input error> 用法由 anatomy「+ error prop」section 展示 */}
+      <Field invalid>
+        <FieldLabel>Email</FieldLabel>
+        <Input defaultValue="invalid-email@" />
+        <FieldError>請輸入有效的 email 地址</FieldError>
+      </Field>
     </div>
   ),
 }

package/src/components/Input/input.tsx

@@ -155,11 +155,7 @@ const Input = React.forwardRef<HTMLInputElement, InputProps>(
     return (
       <div
         className={cn(
-          fieldWrapperStyles({ mode: resolvedMode, variant: variant, size }),
-          isEditable && resolvedError && [
-            'border-error hover:border-error-hover',
-            'focus-within:border-error focus-within:hover:border-error',
-          ],
+          fieldWrapperStyles({ mode: resolvedMode, variant: variant, size, error: resolvedError }),
           // autoWidth:wrapper 縮到 inline-flex + w-auto,讓寬度由 startIcon + input(field-sizing: content)+ endAction 自然累加
           autoWidth && 'inline-flex w-auto',
           className,

package/src/components/LinkInput/link-input.anatomy.stories.tsx

@@ -257,6 +257,7 @@ export const Overview = {
             <tbody>
               {[
                 ['mode', "'edit' | 'display' | 'readonly' | 'disabled'", "'edit'", 'FieldMode 四模式'],
+                ['variant', "'default' | 'bare' | 'naked'", "'default'", 'Field chrome variant（bare：toolbar / cell-as-input 透明 chrome）'],
                 ['size', "'sm' | 'md' | 'lg'", "'md'", '尺寸，與 Button 共用 token'],
                 ['error', 'boolean', 'false', '錯誤狀態，紅色邊框 + aria-invalid'],
                 ['value', 'string | null', '—', 'URL 值'],
@@ -264,6 +265,7 @@ export const Overview = {
                 ['placeholder', 'string', "'https://'", '空值時的佔位文字'],
                 ['disabled', 'boolean', 'false', '等同 mode="disabled"'],
                 ['label', 'string', '—', '自訂顯示文字（覆蓋自動 hostname 提取）'],
+                ['showDisplayEndIcon', 'boolean', 'false', 'display 態改包 Field naked wrapper（D-path opt-in，DataTable cell display↔edit 像素對齊；本元件 edit 無 endIcon，故僅 wrapper 無 ItemSuffix）'],
               ].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/LinkInput/link-input.tsx

@@ -4,7 +4,7 @@ import type { VariantProps } from 'class-variance-authority'
 import { cn } from '@/lib/utils'
 import type { FieldMode, FieldVariant } from '@/design-system/components/Field/field-types'
 import { fieldWrapperStyles, bareInputStyles, EMPTY_DISPLAY, fieldDisplayTextClass } from '@/design-system/components/Field/field-wrapper'
-import { useFieldContext, useResolvedFieldSize, useResolvedFieldDisabled, useResolvedFieldMode, useResolvedFieldVariant } from '@/design-system/components/Field/field-context'
+import { useFieldContext, useResolvedFieldSize, useResolvedFieldDisabled, useResolvedFieldMode, useResolvedFieldVariant, useResolvedFieldInvalid } from '@/design-system/components/Field/field-context'
 import { ItemInlineAction } from '@/design-system/patterns/element-anatomy/item-anatomy'
 
 // ── URL Validation ──────────────────────────────────────────────────────────
@@ -110,6 +110,37 @@ const LinkInput = React.forwardRef<HTMLInputElement, LinkInputProps>(
     // chrome resolution:per-prop > context > 'default'
     const resolvedVariant: FieldVariant = useResolvedFieldVariant(variantProp)
 
+    // 2026-07-05 D4:invalid 經 useResolvedFieldInvalid 統一接 fieldCtx.invalid(field-controls.spec.md
+    // resolver 契約「error/invalid = prop OR fieldCtx.invalid」)— 原本紅框只吃 errorProp||localError、
+    // aria-invalid 卻 inline 加 fieldCtx?.invalid → <Field invalid> 下 AT 聽到 invalid 視覺卻正常框
+    // (聚焦還變藍)。紅框與 aria 自此同源。宣告於 display early return 之前(Rules-of-Hooks)。
+    const fieldInvalid = useResolvedFieldInvalid(errorProp)
+
+    // ── Local state / refs ──────────────────────────────────────────────────
+    // 2026-07-04 Rules-of-Hooks 修:hooks 必在 display early return 之前宣告,
+    // 否則 mode 於 render 間切換 display↔edit 會改變 hook 呼叫數 → React #310 crash
+    // (同 beta.76 Combobox 同款修法;僅搬位置,hook 邏輯不變)。
+    const [editing, setEditing] = React.useState(false)
+    const [localValue, setLocalValue] = React.useState(value ?? '')
+    const [localError, setLocalError] = React.useState(false)
+    const inputRef = React.useRef<HTMLInputElement | null>(null)
+
+    // Sync external value → local
+    React.useEffect(() => {
+      if (!editing) setLocalValue(value ?? '')
+    }, [value, editing])
+
+    // Merge refs
+    const setRef = React.useCallback((el: HTMLInputElement | null) => {
+      inputRef.current = el
+      if (typeof ref === 'function') ref(el)
+      else if (ref) (ref as React.MutableRefObject<HTMLInputElement | null>).current = el
+    }, [ref])
+
+    // 2026-05-16 audit codex Round 6:capture rAF + cancel on unmount(defensive hygiene)
+    const focusRafIdRef = React.useRef<number>(0)
+    React.useEffect(() => () => { if (focusRafIdRef.current) cancelAnimationFrame(focusRafIdRef.current) }, [])
+
     // ── mode='display' ─────────────────────────────────────────────────────
     // 純展示:無 input chrome / 無 hover affordance / 無 Pencil edit 入口。
     // 取代既有 LinkInputDisplay sub-component(2026-05-05 Phase B3 retire)。
@@ -140,30 +171,9 @@ const LinkInput = React.forwardRef<HTMLInputElement, LinkInputProps>(
       )
     }
 
-    const [editing, setEditing] = React.useState(false)
-    const [localValue, setLocalValue] = React.useState(value ?? '')
-    const [localError, setLocalError] = React.useState(false)
-    const inputRef = React.useRef<HTMLInputElement | null>(null)
-
-    // Sync external value → local
-    React.useEffect(() => {
-      if (!editing) setLocalValue(value ?? '')
-    }, [value, editing])
-
-    // Merge refs
-    const setRef = React.useCallback((el: HTMLInputElement | null) => {
-      inputRef.current = el
-      if (typeof ref === 'function') ref(el)
-      else if (ref) (ref as React.MutableRefObject<HTMLInputElement | null>).current = el
-    }, [ref])
-
     const hasValidValue = !!value && isValidUrl(value)
     const showLink = isEditable && hasValidValue && !editing && !localError
-    const error = errorProp || localError
-
-    // 2026-05-16 audit codex Round 6:capture rAF + cancel on unmount(defensive hygiene)
-    const focusRafIdRef = React.useRef<number>(0)
-    React.useEffect(() => () => { if (focusRafIdRef.current) cancelAnimationFrame(focusRafIdRef.current) }, [])
+    const error = fieldInvalid || localError
 
     const handleEdit = () => {
       setEditing(true)
@@ -233,8 +243,11 @@ const LinkInput = React.forwardRef<HTMLInputElement, LinkInputProps>(
     if (showLink) {
       return (
         <div
-          className={cn(fieldWrapperStyles({ mode: 'edit', variant: resolvedVariant, size }), className)}
+          // 2026-07-05 D4:link 顯示分支同樣接 error(errorProp / fieldCtx.invalid)紅框,
+          // 否則 <Field invalid> 下 link state 完全無 error 呈現
+          className={cn(fieldWrapperStyles({ mode: 'edit', variant: resolvedVariant, size, error }), className)}
           data-field-mode="edit"
+          data-error={error ? '' : undefined}
         >
           <span className="flex-1 min-w-0">
             {value && renderLinkAnchor(value, label)}
@@ -251,11 +264,7 @@ const LinkInput = React.forwardRef<HTMLInputElement, LinkInputProps>(
     return (
       <div
         className={cn(
-          fieldWrapperStyles({ mode: 'edit', variant: resolvedVariant, size }),
-          error && [
-            'border-error hover:border-error-hover',
-            'focus-within:border-error focus-within:hover:border-error',
-          ],
+          fieldWrapperStyles({ mode: 'edit', variant: resolvedVariant, size, error }),
           className,
         )}
         data-field-mode="edit"
@@ -270,10 +279,10 @@ const LinkInput = React.forwardRef<HTMLInputElement, LinkInputProps>(
           onBlur={handleBlur}
           onKeyDown={handleKeyDown}
           placeholder={placeholder}
-          aria-invalid={(error || fieldCtx?.invalid) || undefined}
+          aria-invalid={error || undefined}
           aria-required={fieldCtx?.required || undefined}
           aria-describedby={ariaDescribedByProp ?? fieldCtx?.descriptionId}
-          aria-errormessage={ariaErrorMessageProp ?? ((error || fieldCtx?.invalid) ? fieldCtx?.errorId : undefined)}
+          aria-errormessage={ariaErrorMessageProp ?? (error ? fieldCtx?.errorId : undefined)}
           className={bareInputStyles}
           {...props}
         />
@@ -294,9 +303,12 @@ export const linkInputMeta = {
   sizes: {
 
   },
-  states: ['default', 'hover', 'active', 'focus-visible', 'disabled'],
+  // states 對齊真實 state 集:text-input 家族無 'active'(按下)專屬視覺態(同 textareaMeta 修法);
+  //   readonly / error 為 fieldWrapperStyles mode + errorProp/localError 實有狀態(2026-07-04 audit 對齊)。
+  states: ['default', 'hover', 'focus-visible', 'readonly', 'disabled', 'error'],
   tokens: {
-    bg: [],
+    // bg 經 fieldWrapperStyles 實渲:edit bg-surface / readonly bg-readonly / disabled bg-disabled(field-wrapper.tsx)。
+    bg: ['bg-surface', 'bg-readonly', 'bg-disabled'],
     fg: ['text-fg-disabled', 'text-fg-muted', 'text-primary'],
     ring: [],
   },

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 無豁免 |
 
 ### 消費者
 

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

@@ -202,9 +202,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}

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>