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

package/src/components/FileViewer/file-viewer.anatomy.stories.tsx

@@ -222,7 +222,8 @@ export const Overview: Story = {
             <tbody>
               {([
                 ['files', 'FileInfo[]', '—', '檔案清單(shell 依 index 渲染當前)'],
-                ['open', 'boolean', '—', 'Modal 開關(controlled)'],
+                ['open', 'boolean', '—', 'Modal 開關(controlled;與 defaultOpen 二擇一)'],
+                ['defaultOpen', 'boolean', 'false', 'Modal 開關預設(uncontrolled;對齊 Dialog/Sheet/Popover dual-mode canonical)'],
                 ['onOpenChange', '(open: boolean) => void', '—', 'Modal 開關 callback'],
                 ['initialIndex', 'number', '0', '初始 active 索引(uncontrolled)'],
                 ['index', 'number', '—', 'Active 索引(controlled);不傳則 shell 自理'],
@@ -232,6 +233,7 @@ export const Overview: Story = {
                 ['showFilmstrip', 'boolean', 'false', 'true && files.length>1 → 顯示 filmstrip'],
                 ['allowDownload', 'boolean', 'true', 'true → toolbar 顯示 download 按鈕'],
                 ['onDownload', '(file: FileInfo) => void', '—', '自訂 download(跨域檔案必傳)'],
+                ['labels', 'FileViewerLabels', 'DEFAULT_LABELS', 'i18n 文案 override(partial,與 DS 預設 merge;15 keys 覆蓋 toolbar / InfoPanel / filmstrip 的 aria-label 與 placeholder)'],
               ] as const).map(([p, t, d, desc]) => (
                 <tr key={p}>
                   <Td mono>{p}</Td>
@@ -410,7 +412,7 @@ export const Inspector: Story = {
                 </tr>
                 <tr>
                   <Td>InfoPanel 內 padding</Td>
-                  <Td mono>px-[var(--layout-space-loose)] py-[var(--layout-space-tight)]</Td>
+                  <Td mono>px-[var(--layout-space-loose)] pt-[var(--layout-space-tight)] pb-[var(--layout-space-loose)]</Td>
                 </tr>
                 <tr>
                   <Td>Filmstrip 高</Td>
@@ -703,7 +705,7 @@ export const SizeMatrix: Story = {
               <tr>
                 <Td>Body 水平 padding</Td>
                 <Td mono>px-[var(--layout-space-loose)]</Td>
-                <Td>24 / 32 px(隨 density)</Td>
+                <Td>16 / 24 px(隨 density)</Td>
               </tr>
               <tr>
                 <Td>Body 垂直 padding</Td>
@@ -713,7 +715,7 @@ export const SizeMatrix: Story = {
               <tr>
                 <Td>Section 間 gap</Td>
                 <Td mono>gap-[var(--layout-space-loose)]</Td>
-                <Td>說明 ↔ 檔案資訊 24 / 32 px(隨 density;跨範疇 parallel = loose)</Td>
+                <Td>說明 ↔ 檔案資訊 16 / 24 px(隨 density;跨範疇 parallel = loose)</Td>
               </tr>
               <tr>
                 <Td>檔案資訊 metadata</Td>

package/src/components/FileViewer/file-viewer.spec.md

@@ -210,7 +210,7 @@ Shell 看到 `pageNumber` capability 時自動在 toolbar 顯示 page navigator(
   - **100% 重設**(user 按 `0` 鍵;雙擊是 fit↔100% 條件式 toggle,見下「雙擊」bullet)— `centerZoomedOut: true` 讓 ≤100% 時自動 center,避免內容停在容器角落
   - 結果:user 看哪,zoom 完 **看哪**,視覺焦點不漂移 — 世界級 media viewer 共識
 - Min scale 10%,max scale 400%
-- **雙擊 = toggle fit-page ↔ 100%**(對齊 Apple Photos / Preview.app / Imgur / PhotoSwipe canonical):當前 zoom 在 fit-page ±5pt 內 → 跳 100% natural;否則 → 回 fit-page。`0` 鍵才是固定重設 100%(`file-viewer.tsx:835`),兩者不同(`image-renderer.tsx:144`)
+- **雙擊 = toggle fit-page ↔ 100%**(對齊 Apple Photos / Preview.app / Imgur / PhotoSwipe canonical):當前 zoom 在 fit-page ±5pt 內 → 跳 100% natural;否則 → 回 fit-page。`0` 鍵才是固定重設 100%(`file-viewer.tsx:863`),兩者不同(`image-renderer.tsx:144`)
 - 切換檔案時 shell **不重設 zoom**——把「下一張該怎麼初始化 zoom」的決定權交給 renderer:image-renderer 自己 watch `file.url` 變化 → reset loaded → onLoad → 重 fit-page(含 cache 命中時 `<img complete>` 主動觸發,避免 onLoad 不 fire 卡在上一張的 zoom)。原本 shell `setZoom(100)` 在 cache 命中時會卡 100% 不 fit,已移除
 
 ---
@@ -362,7 +362,7 @@ Radix DialogPrimitive 自動處理:
 - `../DropdownMenu/dropdown-menu.spec.md` — ZoomInput preset / fit 選單消費(取代先前 Popover)
 - `../Empty/empty.spec.md` — FallbackRenderer 佈局
 - `../AspectRatio/aspect-ratio.spec.md` — Filmstrip thumb 固定比例
-- `../ScrollArea/scroll-area.spec.md` — InfoPanel body 高度受限時 scroll(`file-viewer.tsx:478`);filmstrip 不用 ScrollArea(刻意走 fade-mask,屬 horizontal-overflow pattern)
+- `../ScrollArea/scroll-area.spec.md` — InfoPanel body 高度受限時 scroll(`file-viewer.tsx:493`);filmstrip 不用 ScrollArea(刻意走 fade-mask,屬 horizontal-overflow pattern)
 - `../../patterns/horizontal-overflow/horizontal-overflow.spec.md` — Filmstrip 水平捲動 + fade mask
 - `../../patterns/action-bar/action-bar.spec.md` — Toolbar 按鈕順序 canonical
 - `../FileItem/file-item.spec.md` — 上傳清單列元件(與 FileViewer 不同用途,FileItem 是 list item,FileViewer 是 fullscreen preview)

package/src/components/FileViewer/file-viewer.tsx

@@ -15,6 +15,7 @@ import {
   FileText,
 } from 'lucide-react'
 import { cn } from '@/lib/utils'
+import { OVERLAY_SIDE_OFFSET } from '@/design-system/tokens/elevation/overlay-geometry'
 import { Button } from '@/design-system/components/Button/button'
 import { Separator } from '@/design-system/components/Separator/separator'
 import { Input } from '@/design-system/components/Input/input'
@@ -33,14 +34,14 @@ import {
   DropdownMenuItem,
   DropdownMenuSeparator,
 } from '@/design-system/components/DropdownMenu/dropdown-menu'
-import {
+import { ARROW_BUTTON_WIDTH,
   useScrollEdges,
   useScrollByPage,
   buildFadeMask,
   OverflowScrollArrow,
 } from '@/design-system/patterns/horizontal-overflow/horizontal-overflow'
 import { useControllable } from '@/design-system/hooks/use-controllable'
-import { ImageRenderer, canRenderImage } from './image-renderer'
+import { canRenderImage } from './can-render-image'
 import type {
   FileInfo,
   FileRenderer,
@@ -107,10 +108,18 @@ const fallbackRenderer: FileRenderer = {
   component: FallbackRenderer,
 }
 
+// 2026-07-06 D3 bundle fix:ImageRenderer 改 React.lazy 動態 import——FileViewer 是
+// rare-use modal overlay,react-zoom-pan-pinch(~12KB gz)不該在 viewer 從未打開時就進
+// consumer 首屏 bundle。canRenderImage(registry 判斷 + Filmstrip 分流需同步呼叫)已拆至
+// ./can-render-image 保持靜態 import。
+const LazyImageRenderer = React.lazy(() =>
+  import('./image-renderer').then((m) => ({ default: m.ImageRenderer })),
+)
+
 const imageRenderer: FileRenderer = {
   id: 'image',
   canRender: canRenderImage,
-  component: ImageRenderer,
+  component: LazyImageRenderer,
 }
 
 // Registry 是 module-singleton:新 renderer 透過 registerFileRenderer 加入。
@@ -256,7 +265,7 @@ const ZoomInput: React.FC<ZoomInputProps> = ({ value, onChange, onFit, labels })
             Tailwind 條件 class + CSS variable 都要一起帶) */}
         <DropdownMenuContent
           align="end"
-          sideOffset={8}
+          sideOffset={OVERLAY_SIDE_OFFSET}  // 2026-07-04:M17 — elevation.spec「primitive default 必 import 該 const」
           // minWidth 對齊 trigger(Input autoWidth),menu 寬度 fit-content 更貼近觸發點視覺中心
           className="min-w-[9rem] w-auto bg-surface-raised text-foreground border-divider"
           data-theme="dark"
@@ -438,13 +447,16 @@ function formatBytes(bytes: number | undefined): string | undefined {
   return `${(bytes / (1024 * 1024 * 1024)).toFixed(1)} GB`
 }
 
-const InfoPanel: React.FC<InfoPanelProps> = ({
+// React.memo(2026-07-06 D3):同 Filmstrip——wheel-zoom 每 tick 全 chrome re-render,InfoPanel
+// 開啟時(Field/Textarea/DescriptionList subtree)白付。onClose 走 shell handleInfoClose
+// useCallback;file(files[activeIndex] identity 穩定)/readOnly/onDescriptionChange/labels 本已穩定。
+const InfoPanel = React.memo(function InfoPanel({
   file,
   readOnly,
   onDescriptionChange,
   onClose,
   labels,
-}) => {
+}: InfoPanelProps) {
   const [draft, setDraft] = React.useState(file.description ?? '')
 
   React.useEffect(() => {
@@ -537,7 +549,7 @@ const InfoPanel: React.FC<InfoPanelProps> = ({
       </ScrollArea>
     </aside>
   )
-}
+})
 
 // ─── Filmstrip ────────────────────────────────────────────────────────────────
 
@@ -551,10 +563,13 @@ interface FilmstripProps {
 // code-quality-allow: long-function — foundational composite main body — 拆 sub-fn 會複雜化 local state / ref / context binding
 const THUMB_SIZE = 64 // px, 固定
 
-const Filmstrip: React.FC<FilmstripProps> = ({ files, activeIndex, onSelect, labels }) => {
+// React.memo(2026-07-06 D3):wheel-zoom 每 tick(trackpad 60Hz+)setZoom → shell 全 chrome
+// re-render,Filmstrip(N thumbs × cn + buildFadeMask)是最貴的無關 subtree。props 已全穩定
+// (files=prop / activeIndex=primitive / onSelect=setIndex useCallback / labels=useMemo)→ memo 真命中。
+const Filmstrip = React.memo(function Filmstrip({ files, activeIndex, onSelect, labels }: FilmstripProps) {
   const { scrollRef, atStart, atEnd, canScroll } = useScrollEdges<HTMLDivElement>()
   const scrollByPage = useScrollByPage(scrollRef)
-  const maskImage = buildFadeMask({ canScroll, atStart, atEnd, reserveArrowWidth: 32 })
+  const maskImage = buildFadeMask({ canScroll, atStart, atEnd, reserveArrowWidth: ARROW_BUTTON_WIDTH })  // 2026-07-04:消 SSOT 硬寫(spec 禁止重新定義 ARROW_BUTTON_WIDTH)
 
   // 切換當前檔案時,自動 scroll 讓 active thumb 可見
   React.useEffect(() => {
@@ -649,7 +664,7 @@ const Filmstrip: React.FC<FilmstripProps> = ({ files, activeIndex, onSelect, lab
       )}
     </div>
   )
-}
+})
 
 // ─── FileViewer (shell) ───────────────────────────────────────────────────────
 
@@ -795,6 +810,10 @@ const FileViewer = React.forwardRef<HTMLDivElement, FileViewerProps>(function Fi
 
   // Info panel open state(shell own)
   const [infoOpen, setInfoOpen] = React.useState(false)
+  // 2026-07-06 D3 perf:抽 useCallback 穩定 identity——InfoPanel 上了 React.memo(見上),
+  // inline arrow 每 render 新 identity 會打穿 memo shallow-compare。
+  const handleInfoToggle = React.useCallback(() => setInfoOpen((o) => !o), [])
+  const handleInfoClose = React.useCallback(() => setInfoOpen(false), [])
 
   // Zoom state(shell own,renderer 消費 + 回報)
   const [zoom, setZoom] = React.useState(100)
@@ -960,7 +979,7 @@ const FileViewer = React.forwardRef<HTMLDivElement, FileViewerProps>(function Fi
               onZoomChange={setZoom}
               onFit={handleFit}
               infoOpen={infoOpen}
-              onInfoToggle={() => setInfoOpen((o) => !o)}
+              onInfoToggle={handleInfoToggle}
               onDownload={handleDownload}
               allowDownload={allowDownload}
               onClose={() => setOpen(false)}
@@ -1017,13 +1036,18 @@ const FileViewer = React.forwardRef<HTMLDivElement, FileViewerProps>(function Fi
                   </div>
                 )}
                 <div className="w-full h-full">
-                  <Renderer.component
-                    file={file}
-                    zoom={zoom}
-                    onZoomChange={setZoom}
-                    fitRequest={fitRequest}
-                    onCapabilitiesChange={setCapabilities}
-                  />
+                  {/* Suspense 兜 React.lazy renderer(ImageRenderer)chunk 載入。fallback=null
+                      = 既有 loading 行為——spec「Loading」段:shell 不提供全頁 loading state,
+                      loading 由 renderer 自理;chunk 載入期間的空 viewport 與 <img> 載入期間視覺一致。 */}
+                  <React.Suspense fallback={null}>
+                    <Renderer.component
+                      file={file}
+                      zoom={zoom}
+                      onZoomChange={setZoom}
+                      fitRequest={fitRequest}
+                      onCapabilitiesChange={setCapabilities}
+                    />
+                  </React.Suspense>
                 </div>
                 {showArrows && activeIndex < files.length - 1 && (
                   <div
@@ -1050,7 +1074,7 @@ const FileViewer = React.forwardRef<HTMLDivElement, FileViewerProps>(function Fi
                   file={file}
                   readOnly={readOnly}
                   onDescriptionChange={onDescriptionChange}
-                  onClose={() => setInfoOpen(false)}
+                  onClose={handleInfoClose}
                   labels={labels}
                 />
               )}
@@ -1083,9 +1107,11 @@ export const fileViewerMeta = {
   sizes: {
 
   },
-  states: ['default', 'hover', 'active', 'focus-visible', 'disabled'],
+  // 'selected' = 縮圖列當前頁持續選中(bg-neutral-selected);'active' 移除 — 全檔無按壓視覺
+  // (工具列按壓屬內嵌 Button meta;2026-07-07 詞彙統一 DS-wide 交叉掃補修)。
+  states: ['default', 'hover', 'selected', 'focus-visible', 'disabled'],
   tokens: {
-    bg: ['bg-muted', 'bg-overlay', 'bg-surface-raised'],
+    bg: ['bg-muted', 'bg-neutral-selected', 'bg-overlay', 'bg-surface-raised'],
     fg: ['text-fg-muted', 'text-foreground'],
     ring: ['ring-primary', 'ring-ring'],
   },

package/src/components/FileViewer/image-renderer.tsx

@@ -246,11 +246,6 @@ export const ImageRenderer: React.FC<FileRendererProps> = ({
 }
 ImageRenderer.displayName = 'ImageRenderer'
 
-const IMAGE_EXTS = new Set(['jpg', 'jpeg', 'png', 'gif', 'webp', 'svg', 'avif', 'bmp', 'ico'])
-
-/** 判斷檔案是否可用 ImageRenderer 渲染。 */
-export function canRenderImage(file: { mimeType: string; name: string }): boolean {
-  if (file.mimeType.startsWith('image/')) return true
-  const ext = file.name.split('.').pop()?.toLowerCase()
-  return ext ? IMAGE_EXTS.has(ext) : false
-}
+// canRenderImage 已拆至 ./can-render-image(2026-07-06 D3 bundle fix)——
+// shell 需同步呼叫它,而本檔頂層 import react-zoom-pan-pinch;留在本檔會把整個 lib
+// 拉進 shell 的靜態 import graph,React.lazy 切分就失效。

package/src/components/HoverCard/hover-card.spec.md

@@ -141,7 +141,7 @@ HoverCard 是**純行為 primitive**(只提供 hover 觸發邏輯 + 定位 + 動
 
 ## A11y 預設
 
-**ARIA / Pattern**:Radix `hover-card` 刻意**不**設 `role` / `aria-*`,定位為 sighted-mouse-user 增強,content 不暴露給輔助技術(grep Radix source 0 命中 role/aria-*)。Radix 只提供:hover / focus 開、Esc 關 + `data-state`。Trigger 的可聚焦性需 consumer 自補(如 Avatar `hoverCard` 在 `avatar.tsx` 手動加 `tabIndex=0` + `role="button"` + `aria-haspopup="dialog"`)。詳 [Radix Accessibility docs](https://www.radix-ui.com/primitives/docs/components/hover-card#accessibility)。
+**ARIA / Pattern**:Radix `hover-card` 刻意**不**設 `role` / `aria-*`,定位為 sighted-mouse-user 增強,content 不暴露給輔助技術(grep Radix source 0 命中 role/aria-*)。Radix 只提供:hover / focus 開、Esc 關 + `data-state`。Trigger 的可聚焦性需 consumer 自補(如 Avatar `hoverCard` 在 `avatar.tsx` 手動加 `tabIndex=0` + `aria-label`;**不掛 role/aria-haspopup**——2026-07-06 拆除,無 activation 行為的 role 宣告 = 對 AT 空承諾,對齊 Radix 官方零 role/aria 定位)。詳 [Radix Accessibility docs](https://www.radix-ui.com/primitives/docs/components/hover-card#accessibility)。
 
 **Keyboard 行為**:
 

package/src/components/HoverCard/hover-card.tsx

@@ -54,7 +54,9 @@ const HoverCardContent = React.forwardRef<
         // 2026-05-04 viewport-aware max-h SSOT(對齊 Popover):header/footer 永遠 in-viewport,body 壓縮 scroll
         // 2026-05-05 audit dim 35 fix:加 `min-h-0` 完成 M25 chain invariant
         "max-h-[var(--radix-hover-card-content-available-height,100vh)] flex flex-col overflow-hidden min-h-0",
-        "data-[state=open]:animate-in data-[state=closed]:animate-out",
+        // 2026-07-05 補 motion-reduce 豁免:對齊 overlay 家族 canonical(popover.tsx / dialog.tsx /
+        // dropdown-menu.tsx / tooltip.tsx 同位置寫法)— prefers-reduced-motion 下停用進出場動畫。
+        "data-[state=open]:animate-in data-[state=closed]:animate-out motion-reduce:animate-none",
         "data-[state=closed]:fade-out-0 data-[state=open]:fade-in-0",
         "data-[state=closed]:zoom-out-95 data-[state=open]:zoom-in-95",
         "data-[side=bottom]:slide-in-from-top-2 data-[side=left]:slide-in-from-right-2",

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,
@@ -215,17 +211,23 @@ Input.displayName = 'Input'
 // 對齊 Carbon read-only / PatternFly inline-edit hidden-input / Cloudscape display-mode 統一 mode 模型。
 
 // Story auto-compile metadata — Phase 1 mechanical migration(2026-04-24)
-// Phase 2 fill needed: purpose descriptions + when rationale + world-class refs
+// 2026-07-05 Phase 2 fill(deep-audit A.1b):variants 按 input.tsx variant jsdoc、sizes 按
+// fieldWrapperStyles cva 真值(h-field-sm/md/lg = 28/32/36,uiSize.css)+ ICON_SIZE SSOT
+// (sm/md 16、lg 20)填。`naked` 為 @internal cell-as-input substrate → 不列入 public variants。
 export const inputMeta = {
   component: 'Input',
   family: 4,
   variants: {
-
+    default: { purpose: 'Field wrapper 完整 chrome(bg-surface + border + hover/focus 回饋)— 表單 / Field 內嵌' },
+    bare: { purpose: '透明 chrome,hover / focus 才現 border — Toolbar inline editing(zoom input / config toolbar)' },
   },
   sizes: {
-
+    sm: { fieldHeight: 28, iconSize: 16, typography: 'body' },
+    md: { fieldHeight: 32, iconSize: 16, typography: 'body' },
+    lg: { fieldHeight: 36, iconSize: 20, typography: 'body-lg' },
   },
-  states: ['default', 'hover', 'active', 'focus-visible', 'disabled'],
+  // 'active' 移除 — Field chrome 無按壓態(對齊 Textarea / LinkInput meta 既有寫法)(2026-07-07 詞彙統一 DS-wide 按壓訊號盤點:檔內 0 active: utility / 0 *-active token)。
+  states: ['default', 'hover', 'focus-visible', 'disabled'],
   tokens: {
     bg: ['bg-surface'],
     fg: ['text-fg-disabled', 'text-fg-muted'],

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 ──────────────────────────────────────────────────────────
@@ -48,7 +48,10 @@ function renderLinkAnchor(value: string, label?: string) {
 // ── Component ───────────────────────────────────────────────────────────────
 
 export interface LinkInputProps
-  extends Omit<React.InputHTMLAttributes<HTMLInputElement>, 'size' | 'value' | 'onChange'>,
+  // `defaultValue` 一併 Omit(2026-07-05 deep-audit A.1b):spec.md「controlled-only,不支援
+  // defaultValue」宣稱的型別面機械封鎖 — 原本仍在型別 surface 且經 {...props} spread 到已
+  // controlled 的 input(React dev warning)。
+  extends Omit<React.InputHTMLAttributes<HTMLInputElement>, 'size' | 'value' | 'defaultValue' | 'onChange'>,
     Omit<VariantProps<typeof fieldWrapperStyles>, 'mode' | 'variant'> {
   mode?: FieldMode
   /**
@@ -110,6 +113,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 +174,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 +246,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 +267,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 +282,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 +306,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.anatomy.stories.tsx

@@ -774,7 +774,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">{"MenuItem 只負責單行的視覺排版,本身不接管鍵盤與焦點。真正的鍵盤導覽(上下鍵切換、Enter 選取、Esc 關閉)與焦點管理由外層的選單元件(SelectMenu / DropdownMenu)負責——MenuItem 不重複實作這些行為。\n\n  語意 role  :在 listbox 語境(SelectMenu / Combobox)MenuItem 預設渲染為 role=\"option\";在 menu 語境(DropdownMenu)外層會把每個 item 覆蓋為 role=\"presentation\",由 Radix parent 持有 role=\"menuitem\" 語意。哪一項目前被聚焦與選取由外層選單決定。\n\n  焦點外觀  :聚焦時以 bg-neutral-hover 背景高亮標示被聚焦的選項(cva base 為 outline-none + focus-visible:bg-neutral-hover),對齊 menu/listbox option 的 active-highlight 慣例,而非畫 outline ring。\n\n  驗證  :Storybook a11y addon 面板應 0 critical violation;整個選單用鍵盤即可完整操作(無需滑鼠);文字對比 ≥ 4.5:1、介面元素對比 ≥ 3:1(WCAG AA)。"}</p>
+      <p className="whitespace-pre-line">{"MenuItem 只負責單行的視覺排版,本身不接管鍵盤與焦點。真正的鍵盤導覽(上下鍵切換、Enter 選取、Esc 關閉)與焦點管理由外層的選單元件(SelectMenu / DropdownMenu)負責——MenuItem 不重複實作這些行為。\n\n  語意 role  :直接使用時(如本元件 stories 的 listbox demo)MenuItem 預設渲染為 role=\"option\" 並帶 aria-selected / aria-disabled;巢狀在外層互動節點內時(SelectMenu / Combobox 的 cmdk option、DropdownMenu 的 Radix menuitem)外層會傳 role=\"presentation\",MenuItem 同步抑制 aria-selected / aria-disabled——ARIA 語意由外層節點單一持有,內層僅保留 data-* 樣式屬性。哪一項目前被聚焦與選取由外層選單決定。\n\n  焦點外觀  :聚焦時以 bg-neutral-hover 背景高亮標示被聚焦的選項(cva base 為 outline-none + focus-visible:bg-neutral-hover),對齊 menu/listbox option 的 active-highlight 慣例,而非畫 outline ring。\n\n  驗證  :Storybook a11y addon 面板應 0 critical violation;整個選單用鍵盤即可完整操作(無需滑鼠);文字對比 ≥ 4.5:1、介面元素對比 ≥ 3:1(WCAG AA)。"}</p>
     </div>
   ),
 }