@qijenchen/design-system 0.1.0-beta.83 → 0.1.0-beta.84

package/src/components/Input/input.spec.md

@@ -1,8 +1,12 @@
 ---
 component: Input
 family: 4
-variants: {}
-sizes: {}
+variants:
+  default: { when: "Field wrapper 完整 chrome(bg-surface + border + hover/focus 回饋)— 表單 / Field 內嵌" }
+sizes:
+  sm: { when: "field-height 28、icon 16、text-body" }
+  md: { when: "default 一般表單(field-height 32、icon 16)" }   # ★ default
+  lg: { when: "touch / 大字級(field-height 36、icon 20、text-body-lg)" }
 traits:
   - hasInteractiveStates
   - isInputLike
@@ -92,7 +96,7 @@ endAction(host 內嵌 inline action)vs 獨立 `<Button iconOnly>` 的分界詳 `
 
 `<Input mode="display">` 是 identity 顯示：
 - 有值：原樣輸出
-- null / undefined / 空字串：`—`（em dash），`text-fg-muted`
+- null / undefined / 空字串：半形 `-`（hyphen），`text-foreground`（display/readonly 供檢視值同色;disabled → fg-disabled）
 
 ---
 
@@ -125,26 +129,17 @@ endAction(host 內嵌 inline action)vs 獨立 `<Button iconOnly>` 的分界詳 `
 
 ## Variant(visual chrome,正交於 mode)
 
-Input 有兩個 visual chrome variant,**獨立於 mode**(mode 是 state,variant 是 chrome look):
+Input 有**一個公開** visual chrome variant `default`(+ 一個 `@internal` 的 `naked`),**獨立於 mode**(mode 是 state,variant 是 chrome look):
 
 | Variant | 原則 | 適用場景 | 世界級對照 |
 |---------|------|---------|-----------|
-| `'default'`(預設) | 完整 field chrome(背景 + 常態 border + hover/focus 回饋)——明確邀請輸入 | 表單 / Field 內嵌 / 標準 edit UI | Material Input / Ant Input default |
-| `'bare'` | 常態無 chrome,hover / focus 才現 border;sizing(padding / typography / height)不變 | **Toolbar inline editing**(FileViewer zoom input / chart config / rich text toolbar number input / Sidebar inline rename) | VS Code settings input / Figma toolbar number / Notion prop input |
+| `'default'`(預設) | 完整 field chrome(背景 + 常態 border + hover/focus 回饋)——明確邀請輸入 | 表單 / Field 內嵌 / 標準 edit UI / toolbar 內小尺寸輸入(如 FileViewer zoom,搭 `size="sm" autoWidth`) | [Material Input](https://github.com/material-components/material-web/blob/main/docs/components/text-field.md) / [Ant Input](https://github.com/ant-design/ant-design/blob/master/components/input/index.en-US.md) default |
 
-**判斷法**:Input 放在表單或 Field 內 → `default`;放在 Toolbar chrome 或 page-body inline → `bare`。
+**透傳**:在 `<Field variant="default">` 內自動繼承 context variant,per-prop override(code:`useResolvedFieldVariant`)。
 
-**透傳**:在 `<Field variant="default|bare">` 內自動繼承 context variant,per-prop override(code:`useResolvedFieldVariant`)。
+> **內部 variant `naked`(@internal,非公開)**：`FieldVariant` 型別含第二值 `'naked'`,但**不是公開 Input variant**——單獨使用無視覺邊界,**不可 standalone**。naked = 剝除 chrome(無 padding / bg / rounded),但 **edit 態仍由自身 border-based state machine 渲染 border + focus 藍框**（field-wrapper.tsx edit×naked compound = cell-as-input state machine;非「完全無 border」、亦非「host cell 自管」）；正被 `FieldSurfaceContext='table-cell'` 取代。consumer 只用 `default`。對齊 public-vs-internal canonical（`ui-development.md`：能直接被使用且用在合理地方才公開）。
 
-> **內部 variant `naked`(@internal,非公開)**：`FieldVariant` 型別含第三值 `'naked'`(完全無 chrome / border / focus ring),但**不是公開 Input variant**——單獨使用無視覺邊界,**不可 standalone**。僅供 DS 內部 cell-as-input 組合(host cell 自管 border + focus visual;正被 `FieldSurfaceContext='table-cell'` 取代）。consumer 只用 `default` / `bare`。對齊 public-vs-internal canonical（`ui-development.md`：能直接被使用且用在合理地方才公開）。
-
-**`bare` 使用情境的 canonical 要求**:
-- 外層 chrome 必須已提供「這是可編輯」的 affordance(Toolbar 的 icon / prop label / row structure);否則 user 看不到 input chrome 找不到可編輯位置
-- 保留 DS field-height(`h-field-sm/md/lg`)、typography、icon tier、error 視覺——**bare 只動 chrome 不動 sizing**
-
-**禁止**:
-- ❌ 在**表單** context 用 `bare`——表單需要明確的 field chrome 邀請輸入,bare 會失去 affordance
-- ❌ 拿 `bare` 來當「空白 div 替代品」——variant 不是拿掉視覺的工具,而是特定 chrome context 的 canonical
+> **`bare` variant 退役(2026-07-09,user 拍板)**:原「透明外殼、hover/focus 才顯 border」variant,宣稱用途 = toolbar inline editing,但全 repo(DS + apps + stories)**零真實 JSX 消費者**——FileViewer zoom 實為 `<Input size="sm" autoWidth>`(default variant),非 bare;唯一出現處是一個 ❌ 反例 story + 過時註解。toolbar 小輸入用 `default`(對齊「邊框給互動元素、輸入框就該有邊框」原則),cell-as-input 用 `naked` → `bare` 純冗餘,移除。Benchmark:[Ant Input](https://github.com/ant-design/ant-design/blob/master/components/input/index.en-US.md) 有 `variant="borderless"`(概念合法),但 [Material M3](https://github.com/material-components/material-web/blob/main/docs/components/text-field.md) 只有 filled/outlined、無無邊框變體;我們無真實消費場景 → 不留純預留 variant。詳 `field-types.ts` FieldVariant note。
 
 ---
 
@@ -166,7 +161,7 @@ Input 有兩個 visual chrome variant,**獨立於 mode**(mode 是 state,variant
 
 **禁止**:
 - ❌ **表單 Field 內**——Field 欄位必須欄寬對齊,寬度隨值跳動會破壞 grid layout
-- ❌ **搭配 `variant="default"` 放在主表單區**——auto-width 預設搭 `variant="bare"`(toolbar inline 語意),default chrome 自動對齊 Field canonical
+- ❌ **放在主表單欄位區**——auto-width 讓欄寬隨值跳動、破壞 grid 對齊;autoWidth 適用 toolbar / page-body inline 場景,搭 `variant="default"`(小尺寸有框輸入,如 FileViewer zoom;`bare` 2026-07-09 退役)
 
 **世界級對照**:VS Code settings inline input 用同 pattern;Notion property field、Airtable cell edit 皆 auto-size。 <!-- @benchmark-unverified: see frontmatter benchmark list for canonical DS source URL -->
 

package/src/components/Input/input.tsx

@@ -3,9 +3,10 @@ import * as React from 'react'
 import { type VariantProps } from 'class-variance-authority'
 import type { LucideIcon } from 'lucide-react'
 import { cn } from '@/lib/utils'
-import type { FieldMode, FieldVariant } from '@/design-system/components/Field/field-types'
-import { fieldWrapperStyles, bareInputStyles, EMPTY_DISPLAY } from '@/design-system/components/Field/field-wrapper'
-import { useFieldContext, useResolvedFieldSize, useResolvedFieldDisabled, useResolvedFieldMode, useResolvedFieldVariant, useResolvedFieldInvalid } from '@/design-system/components/Field/field-context'
+import type { FieldMode, FieldVariant, FieldVariantInternal } from '@/design-system/components/Field/field-types'
+import { fieldWrapperStyles, bareInputStyles } from '@/design-system/components/Field/field-wrapper'
+import { useFieldContext, useResolvedFieldSize, useResolvedFieldDisabled, useResolvedFieldMode, useResolvedFieldVariant, useResolvedFieldInvalid, useFieldEmptyDisplay, fieldEmptyColorClass } from '@/design-system/components/Field/field-context'
+import { useControllable } from '@/design-system/hooks/use-controllable'
 import { ItemInlineAction, ItemPrefix, type InlineActionConfig } from '@/design-system/patterns/element-anatomy/item-anatomy'
 import { CircularProgress } from '@/design-system/components/CircularProgress/circular-progress'
 import { ICON_SIZE } from '@/design-system/tokens/uiSize/icon-size'
@@ -14,19 +15,17 @@ import { ICON_SIZE } from '@/design-system/tokens/uiSize/icon-size'
 
 export interface InputProps
   extends Omit<React.InputHTMLAttributes<HTMLInputElement>, 'size'>,
-    Omit<VariantProps<typeof fieldWrapperStyles>, 'mode' | 'variant'> {
+    Omit<VariantProps<typeof fieldWrapperStyles>, 'mode' | 'variant' | 'width'> {
   /** Field display mode */
   mode?: FieldMode
   /**
-   * Visual chrome(正交於 mode);Phase B1(2026-05-05)從 `variant` 改名 `chrome`,對齊 FieldContext.variant 透傳。
-   * 公開 variant 兩個:
+   * Visual variant(正交於 mode),對齊 FieldContext.variant 透傳。
+   * 公開 variant 一個(2026-07-09 `bare` 退役,詳 field-types.ts FieldVariant note;naked 2026-07-14 型別收窄至 FieldVariantInternal):
    * - `'default'`(預設)— Field wrapper 完整 variant:bg-surface + 明顯 border + hover/focus 回饋。適用表單、Field 內嵌。
-   * - `'bare'` — 透明 variant,hover / focus 才出現 border。適用 Toolbar inline editing(如 FileViewer zoom input / chart config toolbar / rich text toolbar number input)。保留 padding / typography / height,只拿掉背景和常態 border。
    *
-   * @internal `'naked'` — 完全無 chrome / 無 border / 無 focus ring。單獨使用無視覺邊界,**不可直接 standalone 用**;僅供 DS 內部 cell-as-input 組合(host cell 自管 border + focus visual,正被 `FieldSurfaceContext='table-cell'` 取代)。consumer 請用 `default` / `bare`。
+   * @internal `'naked'` — 完全無 chrome / 無 border / 無 focus ring。單獨使用無視覺邊界,**不可直接 standalone 用**;僅供 DS 內部 cell-as-input 組合(edit×naked 的 border/hover/focus/error 由 field-wrapper 自渲 state machine 提供,非 host cell 自管;詳 field-wrapper.tsx)。consumer 請用 `default`(2026-07-14 起型別層已擋:公開 FieldVariant 不含 naked,僅 DataTable cell-registry 經 WithFieldVariantInternal 通道傳入)。
    *
-   * 透傳:在 `<Field variant="default|bare">` 內自動繼承 context.variant;per-prop override context。
-   * 世界級對照(bare):VS Code settings input / Figma toolbar number / Notion prop input。
+   * 透傳:在 `<Field variant="default">` 內自動繼承 context.variant;per-prop override context。
    */
   variant?: FieldVariant
   /** Error 狀態（正交於 mode）。border-error + aria-invalid。 */
@@ -63,7 +62,7 @@ export interface InputProps
    * **不要用在**:表單 Field(Field 需要欄寬對齊,不該隨值跳動)
    *
    * **fallback**:不支援 `field-sizing` 的瀏覽器會退化為 `w-auto`(wrapper 縮到 content 尺寸,
-   * input 本身有 min-width 避免消失)。UX 上稍不一致但不致斷;若必須精準對齊所有瀏覽器,
+   * input 為 min-w-0,依 content/placeholder 撐寬)。UX 上稍不一致但不致斷;若必須精準對齊所有瀏覽器,
    * consumer 可自行傳 `style={{ width: ... }}` 顯式寬度,不走 auto。
    */
   autoWidth?: boolean
@@ -88,6 +87,7 @@ const Input = React.forwardRef<HTMLInputElement, InputProps>(
       disabled: disabledProp,
       readOnly,
       value,
+      defaultValue,
       id: idProp,
       'aria-describedby': ariaDescribedByProp,
       'aria-errormessage': ariaErrorMessageProp,
@@ -102,10 +102,11 @@ const Input = React.forwardRef<HTMLInputElement, InputProps>(
     const size = useResolvedFieldSize(sizeProp)
     const disabled = useResolvedFieldDisabled(disabledProp)
     // chrome 透傳:per-prop override context;context 沒值則 'default'
-    const variant: FieldVariant = useResolvedFieldVariant(variantProp)
+    const variant: FieldVariantInternal = useResolvedFieldVariant(variantProp)
     // 2026-06-08 SSOT:mode 經 useResolvedFieldMode 統一解析(prop > 有效 disabled > fieldCtx.mode > readOnly > 'edit')。
     // loading 期間 input 保持可編輯(Ant Input.Search 派),只用 aria-busy + endAction Spinner,不動 mode。
     const resolvedMode: FieldMode = useResolvedFieldMode({ mode: modeProp, disabled, readOnly })
+    const emptyDisplay = useFieldEmptyDisplay()
     const isEditable = resolvedMode === 'edit'
     const isDisplay = resolvedMode === 'display'
     // error 合併:自身 error prop OR Field context invalid
@@ -114,18 +115,59 @@ const Input = React.forwardRef<HTMLInputElement, InputProps>(
   const iconSize = ICON_SIZE[size as 'sm' | 'md' | 'lg']
     const iconColor = resolvedMode === 'disabled' ? 'text-fg-disabled' : 'text-fg-muted'
 
-    // ── display mode:純展示,渲染 <span> 取代 <input> ──
+    // ── display mode(+ readonly 空值)純展示,渲染 <span> 取代 <input> ──
     // 對齊 Carbon read-only / PatternFly inline-edit hidden-input / Cloudscape display-mode
-    if (isDisplay) {
-      const displayValue = value != null && value !== '' ? String(value) : null
+    // 2026-07-08 user 拍板:readonly 空值也走 display-span 顯 '-'(readonly **有值** 仍走下方
+    // native <input readOnly> 保留選取/複製語意 — field-controls.spec.md「null / undefined 值」)。
+    // 2026-07-14 audit Dim 26(dual-mode coherence):uncontrolled `defaultValue` 也要被
+    // display / readonly-空值判定認得 — 原本只讀 `value`,uncontrolled Input 切 display 會誤顯 '-'。
+    // 2026-07-14 R2(dual-model consensus,取代同日稍早 onChange-mirror 版):resolved value 改走
+    // useControllable 內部 SSOT(Radix idiom,同 Select / Pagination 既有消費)。uncontrolled 時
+    // native input 由 value={resolved} 內部驅動(defaultValue 只作初始值,不落 DOM attribute),
+    // 修 mirror 版兩個真缺陷:
+    // (1) remount-stale — 切 display / readonly(native input unmount)再回 edit,native input 從
+    //     defaultValue attribute 重掛 → 顯示 stale 初始值,與 mirror 判定分歧;
+    // (2) form.reset() stale — HTML 標準 reset 不發 input event,onChange mirror 停在 reset 前的值
+    //     (下方 reset bridge 修)。
+    // controlled(傳 value)時 useControllable 純 passthrough,行為與原本完全一致。
+    // consumer onChange 不接進 hook(保留 native event signature),於 <input> onChange 另行轉發。
+    const isControlled = value !== undefined
+    const [resolved, setResolved] = useControllable<string | number | readonly string[]>({
+      value: value as string | number | readonly string[] | undefined,
+      defaultValue: defaultValue ?? '',
+    })
+    const displayValue = resolved != null && resolved !== '' ? String(resolved) : null
+    const showDisplaySpan = isDisplay || (resolvedMode === 'readonly' && displayValue == null)
+
+    // form.reset() bridge(uncontrolled only):reset 恢復 defaultValue 但不發 input event →
+    // 手動把 resolved 歸位 defaultValue。keyed on showDisplaySpan:display 分支不掛 native input,
+    // 回 edit 重掛時 effect 重跑補掛 listener。
+    const innerRef = React.useRef<HTMLInputElement | null>(null)
+    React.useEffect(() => {
+      if (isControlled || showDisplaySpan) return
+      const form = innerRef.current?.form
+      if (!form) return
+      const handleReset = () => setResolved(defaultValue ?? '')
+      form.addEventListener('reset', handleReset)
+      return () => form.removeEventListener('reset', handleReset)
+    }, [isControlled, showDisplaySpan, defaultValue, setResolved])
+    // Merge refs(LinkInput setRef idiom,link-input.tsx:138)
+    const setRef = React.useCallback((el: HTMLInputElement | null) => {
+      innerRef.current = el
+      if (typeof ref === 'function') ref(el)
+      else if (ref) (ref as React.MutableRefObject<HTMLInputElement | null>).current = el
+    }, [ref])
+
+    if (showDisplaySpan) {
+      const spanMode = isDisplay ? 'display' : 'readonly'
       return (
         <div
           className={cn(
-            fieldWrapperStyles({ mode: 'display', variant: variant, size }),
+            fieldWrapperStyles({ mode: spanMode, variant: variant, size }),
             autoWidth && 'inline-flex w-auto',
             className,
           )}
-          data-field-mode="display"
+          data-field-mode={spanMode}
         >
           {StartIcon && (
             <ItemPrefix>
@@ -143,10 +185,10 @@ const Input = React.forwardRef<HTMLInputElement, InputProps>(
               //   cell display canonical:single-line value 過長 → ellipsis。Textarea display 走 wrap path,
               //   不在此處;Input display 永遠 single-line。)
               'truncate',
-              displayValue == null && 'text-fg-muted',
+              displayValue == null && fieldEmptyColorClass(resolvedMode),
             )}
           >
-            {displayValue ?? EMPTY_DISPLAY}
+            {displayValue ?? emptyDisplay}
           </span>
         </div>
       )
@@ -174,10 +216,10 @@ const Input = React.forwardRef<HTMLInputElement, InputProps>(
           </ItemPrefix>
         )}
         <input
-          ref={ref}
+          ref={setRef}
           type="text"
           id={idProp ?? fieldCtx?.id}
-          value={value as string | number | readonly string[] | undefined}
+          value={resolved}
           readOnly={resolvedMode === 'readonly'}
           disabled={resolvedMode === 'disabled'}
           aria-invalid={resolvedError || undefined}
@@ -192,6 +234,11 @@ const Input = React.forwardRef<HTMLInputElement, InputProps>(
             autoWidth && '[field-sizing:content] w-auto min-w-0',
           )}
           {...props}
+          // 置於 {...props} 後:寫回 resolved SSOT(controlled 時 useControllable 內部為 no-op)再轉發 consumer onChange。
+          onChange={(e) => {
+            setResolved(e.target.value)
+            props.onChange?.(e)
+          }}
         />
         {loading ? (
           <CircularProgress size={iconSize} className="shrink-0" />
@@ -219,7 +266,7 @@ export const inputMeta = {
   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)' },
+    // (2026-07-09 `bare` variant 退役 — 見 field-types.ts FieldVariant note)
   },
   sizes: {
     sm: { fieldHeight: 28, iconSize: 16, typography: 'body' },

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

@@ -257,7 +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）'],
+                ['variant', "'default'", "'default'", 'Field chrome variant（naked：cell-as-input 透明 chrome，@internal，2026-07-14 型別收窄至 FieldVariantInternal）'],
                 ['size', "'sm' | 'md' | 'lg'", "'md'", '尺寸，與 Button 共用 token'],
                 ['error', 'boolean', 'false', '錯誤狀態，紅色邊框 + aria-invalid'],
                 ['value', 'string | null', '—', 'URL 值'],

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

@@ -172,8 +172,8 @@ export const EmptyRule: Story = {
       </Rule>
 
       <Rule
-        title="readonly 空值 → 顯示 empty placeholder（—）"
-        note="table cell / 個人資料展示頁,沒填 website 時以 em-dash 表達「未填」,跟其他 Field readonly 空值呈現一致"
+        title="readonly 空值 → 顯示半形連字號（-）"
+        note="table cell / 個人資料展示頁,沒填 website 時以半形連字號 - 表達「未填」,跟其他 Field readonly 空值呈現一致"
       >
         <LinkInput mode="readonly" value={null} />
       </Rule>

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

@@ -2,9 +2,9 @@ import * as React from 'react'
 import { Pencil } from 'lucide-react'
 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, useResolvedFieldInvalid } from '@/design-system/components/Field/field-context'
+import type { FieldMode, FieldVariant, FieldVariantInternal } from '@/design-system/components/Field/field-types'
+import { fieldWrapperStyles, bareInputStyles, fieldDisplayTextClass } from '@/design-system/components/Field/field-wrapper'
+import { useFieldContext, useResolvedFieldSize, useResolvedFieldDisabled, useResolvedFieldMode, useResolvedFieldVariant, useResolvedFieldInvalid, useFieldEmptyDisplay, fieldEmptyColorClass } from '@/design-system/components/Field/field-context'
 import { ItemInlineAction } from '@/design-system/patterns/element-anatomy/item-anatomy'
 
 // ── URL Validation ──────────────────────────────────────────────────────────
@@ -52,12 +52,12 @@ export interface LinkInputProps
   // defaultValue」宣稱的型別面機械封鎖 — 原本仍在型別 surface 且經 {...props} spread 到已
   // controlled 的 input(React dev warning)。
   extends Omit<React.InputHTMLAttributes<HTMLInputElement>, 'size' | 'value' | 'defaultValue' | 'onChange'>,
-    Omit<VariantProps<typeof fieldWrapperStyles>, 'mode' | 'variant'> {
+    Omit<VariantProps<typeof fieldWrapperStyles>, 'mode' | 'variant' | 'width'> {
   mode?: FieldMode
   /**
    * Visual chrome(2026-05-05 Phase B3)。對齊 FieldContext.variant 透傳。
    * - `'default'`(預設)— Field wrapper 完整 chrome(form / Field 內嵌)。
-   * - `'bare'` — 透明 variant,hover/focus 才現 border(Toolbar inline edit / DataTable cell-as-input)。
+   * (2026-07-09 `bare` variant 退役;naked = cell-as-input substrate,@internal)
    *
    * mode='display' 時 chrome 無視覺意義(display 完全無 wrapper);chrome 僅作用於 edit / readonly / disabled。
    */
@@ -109,9 +109,10 @@ const LinkInput = React.forwardRef<HTMLInputElement, LinkInputProps>(
     // 2026-06-08 SSOT:mode 經 useResolvedFieldMode 統一解析(prop > 有效 disabled > fieldCtx.mode > readOnly > 'edit')。
     // spec field-controls.spec.md L125「readOnly 原生屬性自動覆蓋 mode」契約落地。
     const resolvedMode: FieldMode = useResolvedFieldMode({ mode: modeProp, disabled, readOnly })
+    const emptyDisplay = useFieldEmptyDisplay()
     const isEditable = resolvedMode === 'edit'
     // chrome resolution:per-prop > context > 'default'
-    const resolvedVariant: FieldVariant = useResolvedFieldVariant(variantProp)
+    const resolvedVariant: FieldVariantInternal = useResolvedFieldVariant(variantProp)
 
     // 2026-07-05 D4:invalid 經 useResolvedFieldInvalid 統一接 fieldCtx.invalid(field-controls.spec.md
     // resolver 契約「error/invalid = prop OR fieldCtx.invalid」)— 原本紅框只吃 errorProp||localError、
@@ -156,7 +157,7 @@ const LinkInput = React.forwardRef<HTMLInputElement, LinkInputProps>(
         // anchor / span 必套 `fieldDisplayTextClass(size)`(sm/md→text-body,lg→text-body-lg)
         // — 對齊跨 Field family display 視覺尺寸統一。原無 font-size class → 用 browser default
         // 字體 → 跟其他 Field display 不一致(user 抓 I2)。truncate 同需,長 URL ellipsis(I1)。
-        if (!value) return <span className={cn(fieldDisplayTextClass(size), 'text-fg-muted block truncate')}>{EMPTY_DISPLAY}</span>
+        if (!value) return <span className={cn(fieldDisplayTextClass(size), fieldEmptyColorClass(resolvedMode), 'block truncate')}>{emptyDisplay}</span>
         return <span className={cn(fieldDisplayTextClass(size), 'block truncate')}>{renderLinkAnchor(value, label)}</span>
       }
       return (
@@ -167,7 +168,7 @@ const LinkInput = React.forwardRef<HTMLInputElement, LinkInputProps>(
           <span className="flex-1 min-w-0 truncate">
             {value
               ? renderLinkAnchor(value, label)
-              : <span className="text-fg-muted">{EMPTY_DISPLAY}</span>
+              : <span className={fieldEmptyColorClass(resolvedMode)}>{emptyDisplay}</span>
             }
           </span>
         </div>
@@ -232,10 +233,10 @@ const LinkInput = React.forwardRef<HTMLInputElement, LinkInputProps>(
             {resolvedMode === 'disabled'
               ? (displayText
                   ? <span className="text-fg-disabled">{displayText}</span>
-                  : <span className="text-fg-muted">{EMPTY_DISPLAY}</span>)
+                  : <span className={fieldEmptyColorClass(resolvedMode)}>{emptyDisplay}</span>)
               : (value
                   ? renderLinkAnchor(value, label)
-                  : <span className="text-fg-muted">{EMPTY_DISPLAY}</span>)
+                  : <span className={fieldEmptyColorClass(resolvedMode)}>{emptyDisplay}</span>)
             }
           </span>
         </div>

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

@@ -551,7 +551,7 @@ export const ColorMatrix = {
     <div className="flex flex-col gap-8">
       <div className="flex flex-col gap-1">
         <H3>State 色彩對照</H3>
-        <Desc>單選用 bg-neutral-selected 背景指示選中，多選用 Checkbox 勾選——背景不變。disabled 時所有元素統一 fg-disabled。色塊即時渲染，切 dark mode 自動更新。</Desc>
+        <Desc>單選用 bg-neutral-selected 背景指示選中，多選用 Checkbox 勾選——背景不變。disabled 時文字 / startIcon 用 fg-disabled、tag / endContent / startContent 用 opacity-disabled、checkbox 走自身 disabled、avatar 不變暗。色塊即時渲染，切 dark mode 自動更新。</Desc>
       </div>
 
       {/* Single-select */}
@@ -745,10 +745,10 @@ export const SizeMatrix = {
                   <MenuItem size={sz} startIcon={Mail} description="每日摘要信件">
                     電子郵件通知
                   </MenuItem>
-                  <MenuItem size={sz} avatar={{ alt: "Alice", color: "indigo" as const }}>
+                  <MenuItem size={sz} avatar={{ src: "https://i.pravatar.cc/48?u=alice-chen", alt: "Alice", color: "indigo" as const }}>
                     Alice Chen
                   </MenuItem>
-                  <MenuItem size={sz} avatar={{ alt: "Bob", color: "magenta" as const }} description="工程部門">
+                  <MenuItem size={sz} avatar={{ src: "https://i.pravatar.cc/48?u=bob-wang", alt: "Bob", color: "magenta" as const }} description="工程部門">
                     Bob Wang
                   </MenuItem>
                   <MenuItem size={sz} checkbox checked={true} startIcon={Bell}>

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

@@ -74,7 +74,7 @@ export const CompositionRules: Story = {
         <h4>Pattern 3 — ContextMenu + MenuItem(右鍵選單,未來)</h4>
         <p>右鍵觸發 contextual action → 預留消費者(Radix ContextMenu + MenuItem 同 layout primitive)。</p>
 
-        <p className="text-fg-muted">禁止:在產品頁面裡自己用 <code>&lt;div&gt;</code> 拼一列選單(像 <code>&lt;div className="flex px-2 py-1.5"&gt;</code>)— 一律使用 MenuItem,才能確保所有選單列的對齊與間距一致。各區塊的對齊規則(左側圖示/頭像在 24px 內對齊、文字往下堆疊、右側標記可有可無)由選項列共用設計準則統一規範。</p>
+        <p className="text-fg-muted">禁止:在產品頁面裡自己用 <code>&lt;div&gt;</code> 拼一列選單(像 <code>&lt;div className="flex px-2 py-1.5"&gt;</code>)— 一律透過上方的 MenuItem 系選單元件(DropdownMenu / SelectMenu 等,內部消費 MenuItem),才能確保所有選單列的對齊與間距一致。MenuItem 本身是 internal 排版元件,在產品頁面直接裸用會失去外層選單的無障礙 / 鍵盤 / 焦點管理(詳 spec「何時用 / 何時不用」)。各區塊的對齊規則(左側圖示/頭像在 24px 內對齊、文字往下堆疊、右側標記可有可無)由選項列共用設計準則統一規範。</p>
       </div>
     </div>
   ),

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

@@ -28,14 +28,16 @@ MenuItem 是所有 menu 類元件的**共用視覺佈局層**——處理 prefix
 ## 結構
 
 ```
-prefix                       content               suffix
-[checkbox?] [icon? | avatar?]  [label + description?]  [tag?]
+prefix                                      content               suffix
+[checkbox?] [icon? | avatar? | content?]  [label + description?]  [tag?]
 ```
 
-- **Prefix**：checkbox（多選，由父層注入）+ startIcon 或 avatar（互斥）
+- **Prefix**：checkbox（多選，由父層注入）+ startIcon 或 avatar 或 startContent（三者互斥）
 - **Content**：label + 可選 description
 - **Suffix**：tag（ml-auto 靠右）
 
+**`startContent`（2026-07-10 加，WM TypeIcon 彩色徽章需求）**：LucideIcon / Avatar 表達不了的自訂 leading 視覺（類型徽章 = 彩底方塊 + glyph、status 組合點等）。**渲染在同一個 prefix 對齊容器內——佔位與排列邏輯跟 startIcon 一模一樣**（gap / 24px 閾值對齊 / shrink 全繼承 `itemPrefixAlignVariants` SSOT，零平行 layout），consumer 唯一責任是節點尺寸對齊 `ICON_SIZE[size]`（sm/md=16px、lg=20px）。與 `endContent` 對稱（同為自訂 ReactNode slot）。disabled 時容器套 `opacity-disabled`（對齊 `tag` / `endContent` 自訂節點同款處理;**與 `avatar` 不變暗的分界**:Avatar 有自己的 self-dim 體系〔`fieldCtx.disabled` 觸發,同一顆 `opacity-disabled` token,avatar.spec.md「Disabled」段〕,MenuItem 非 Field context 故不觸發;startContent 是任意 consumer 節點、無任何 DS context 可自 dim → 容器套 opacity 是唯一可靠機制。放頭像請用 `avatar` prop 非 startContent）。
+
 prefix icon 跟 label 同色（foreground），不是 fg-muted。詳見 item-anatomy.spec.md 的 Icon 色彩原則。
 
 ---
@@ -59,14 +61,19 @@ prefix icon 跟 label 同色（foreground），不是 fg-muted。詳見 item-ana
 
 ---
 
-## startIcon vs avatar
+## startIcon vs avatar vs startContent(怎麼選)
 
-| | `startIcon` | `avatar` |
-|---|---|---|
-| 型別 | `LucideIcon` | `AvatarData` |
-| 角色 | **描述**選項的性質（形容詞） | **代表**選項的身份（名詞） |
-| 尺寸 | 16/20px（icon tier，元件控制） | 由 description 決定：無 desc → 20/24/24px，有 desc → 32/32/40px |
-| 對齊 | 永遠 inline（≤ 24px） | 無 desc → inline；有 desc → block |
+**一句話判準:看內容「是什麼」,不是看喜好** —— 線性圖示 → `startIcon`;人/實體頭像 → `avatar`;其他任何自訂視覺 → `startContent`。每槽綁不同的自動行為,型別即理由:
+
+| | `startIcon` | `avatar` | `startContent` |
+|---|---|---|---|
+| 型別 | `LucideIcon` | `AvatarData` | `ReactNode` |
+| 角色 | **描述**性質（形容詞） | **代表**身份（名詞） | 圖示/頭像表達不了的視覺(類型徽章、狀態組合點) |
+| 尺寸 | 16/20px（**元件自動控**） | 由 description 決定：無 desc → 20/24/24px，有 desc → 32/32/40px(**元件自動推導**) | consumer 自理,對齊 `ICON_SIZE[size]` |
+| disabled | 自動 `fg-disabled` 換色 | 不變暗（自有 fieldCtx self-dim 體系） | 容器自動 `opacity-disabled` |
+| 對齊 | 永遠 inline（≤ 24px） | 無 desc → inline；有 desc → block | inline(同 startIcon 容器) |
+
+**為什麼三槽而不是一個 ReactNode 口**:合成一口(Atlassian `iconBefore: ReactNode` 式)會失去前兩槽的自動行為 —— 每個 consumer 都得自己記尺寸、自己處理 disabled、自己接 hoverCard = 漂移溫床。世界級同構:MUI List 正是三分 —— [`ListItemIcon`](https://mui.com/material-ui/api/list-item-icon/) 與 [`ListItemAvatar`](https://mui.com/material-ui/api/list-item-avatar/) 是**兩個獨立 wrapper 元件**、任意節點則直接放 —— 我們用 props 表達同一套分工。
 
 ### avatar 尺寸推導
 
@@ -150,7 +157,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 × 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 在 selected × highlighted(鍵盤 cursor)深化一階為 `--neutral-selected-active`(2026-07-05 D4,WCAG 2.4.7 cursor 可見;dropdown-menu.tsx `selected && data-[highlighted]:bg-neutral-selected-active`)——此為 wrapper 層鍵盤 cursor 增強,MenuItem primitive 的 selected × hover(滑鼠)仍維持 `--neutral-selected` 不深化 |
 | selected（多選） | transparent | foreground | checkbox 勾選 |
 | disabled | transparent | `--fg-disabled` | disabled prop |
 
@@ -163,7 +170,7 @@ Menu 的設計目的是「**快速掃視多個選項挑一個**」。垂直空
 
 單選和 DropdownMenu RadioItem 統一用 `bg-neutral-selected`。不用 ✓ 勾號——勾號在 prefix 會影響群組內對齊。
 
-disabled 時：文字（label / description）與 `startIcon` 套 `fg-disabled`；`checkbox` 套用自身 `disabled` 樣式（非 `fg-disabled`）；`tag` / `endContent` 容器套 `opacity-disabled`；`avatar` 在 MenuItem 內不變暗（Avatar 僅在 disabled Field wrapper context 內自 dim，MenuItem 非 Field wrapper）。
+disabled 時：文字（label / description）與 `startIcon` 套 `fg-disabled`；`checkbox` 套用自身 `disabled` 樣式（非 `fg-disabled`）；`tag` / `endContent` / `startContent` 容器套 `opacity-disabled`（自訂節點自帶配色、不能硬換字色,降透明是唯一通用機制;MUI 佐證:disabled MenuItem 整列 root 直接套 `opacity: disabledOpacity` 連 avatar 都 dim — 我們比它細粒度）；`avatar` 在 MenuItem 內不變暗（Avatar 僅在 disabled Field wrapper context 內自 dim，MenuItem 非 Field wrapper）。
 
 ### 浮層關閉行為
 
@@ -206,10 +213,10 @@ Menu item 的 prefix icon 跟 label 同色（foreground），不是 fg-muted。P
 
 ## 禁止事項
 
-- ❌ `startIcon` 和 `avatar` 不可同時使用
+- ❌ `startIcon` / `avatar` / `startContent` 三者不可同時使用（同一 prefix 位置）
 - ❌ 無 `description` 時不可使用 > 24px 的 avatar
 - ❌ disabled item 不可有 hover 效果
-- ❌ disabled item 內的子元件不可保持 enabled 外觀——文字 / `startIcon` 套 `fg-disabled`、`checkbox` 用自身 `disabled` 樣式、`tag` / `endContent` 套 `opacity-disabled`（`avatar` 在 MenuItem 內維持原樣，因 Avatar 僅在 disabled Field wrapper context 內自 dim）
+- ❌ disabled item 內的子元件不可保持 enabled 外觀——文字 / `startIcon` 套 `fg-disabled`、`checkbox` 用自身 `disabled` 樣式、`tag` / `endContent` / `startContent` 套 `opacity-disabled`（`avatar` 在 MenuItem 內維持原樣，因 Avatar 僅在 disabled Field wrapper context 內自 dim）
 - ❌ header item 不可被選中
 - ❌ 不在 item 內放獨立互動元素（如 Button）——item 本身就是互動單位
 
@@ -217,7 +224,7 @@ Menu item 的 prefix icon 跟 label 同色（foreground），不是 fg-muted。P
 
 ## 何時用 / 何時不用
 
-**MenuItem 是 internal primitive**——不直接使用，透過 `SelectMenu` / `DropdownMenu` 等外層 menu 元件消費。
+**MenuItem 是 internal primitive**——不進 root barrel front-door、不裸用；一般透過 `SelectMenu` / `DropdownMenu` 等外層 menu 元件消費；consumer 自建 nav row 等場景可經 per-component subpath 包裝並自行確認後使用（`.claude/rules/ui-development.md`「Root barrel front-door 排除」SSOT，internal ≠ 禁用）。
 
 | 場景 | 正確做法 |
 |------|---------|

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

@@ -1,17 +1,20 @@
 import React from 'react'
 import type { Meta, StoryObj } from '@storybook/react'
 import { useState } from 'react'
-import { Mail, Star, Bell, Settings, Plus, Folder, FileText, BarChart3 } from 'lucide-react'
+import { Mail, Star, Bell, Settings, Plus, Folder, FileText, BarChart3, Bug, Rocket } from 'lucide-react'
 import { MenuItem, MenuGroup, MenuFooter } from './menu-item'
+import { CAT_SOLID, type CategoricalHue } from '@/design-system/tokens/categorical-color'
 import { ProfileCard, ProfileCardDefaultActions } from '@/design-system/components/ProfileCard/profile-card'
 
 // DS-wide canonical:person avatar 必 hover → ProfileCard(含 status / statusMessage / fields
 // / actions / onViewMore,profile-card.spec.md 重要資訊)。demo helper:
+// 真實人像(2026-07-08 sweep):固定 u= key 保 determinism(對齊 avatar.stories.tsx pravatar 慣例)
+const avatarSrc = (name: string, px = 96) => `https://i.pravatar.cc/${px}?u=${name.toLowerCase().replace(/\s+/g, '-')}`
 const personHover = (name: string, subtitle?: string) => (
   <ProfileCard
     name={name}
     subtitle={subtitle ?? 'Design｜D-0042｜EMP-1001'}
-    avatar={{ alt: name }}
+    avatar={{ src: avatarSrc(name), alt: name }}
     status="online"
     statusMessage="Out of Office: Back on Monday!"
     actions={<ProfileCardDefaultActions />}
@@ -77,9 +80,9 @@ export const AvatarInline: Story = {
   name: '頭像',
   render: () => (
     <MenuContainer><MenuGroup>
-      <MenuItem avatar={{ alt: "Alice Chen", color: "indigo", hoverCard: personHover('Alice Chen') }}>Alice Chen</MenuItem>
-      <MenuItem avatar={{ alt: "Bob Wang", color: "magenta", hoverCard: personHover('Bob Wang') }}>Bob Wang</MenuItem>
-      <MenuItem avatar={{ alt: "Carol Lin", color: "green", hoverCard: personHover('Carol Lin') }}>Carol Lin</MenuItem>
+      <MenuItem avatar={{ src: avatarSrc('Alice Chen', 48), alt: "Alice Chen", color: "indigo", hoverCard: personHover('Alice Chen') }}>Alice Chen</MenuItem>
+      <MenuItem avatar={{ src: avatarSrc('Bob Wang', 48), alt: "Bob Wang", color: "magenta", hoverCard: personHover('Bob Wang') }}>Bob Wang</MenuItem>
+      <MenuItem avatar={{ src: avatarSrc('Carol Lin', 48), alt: "Carol Lin", color: "green", hoverCard: personHover('Carol Lin') }}>Carol Lin</MenuItem>
     </MenuGroup></MenuContainer>
   ),
 }
@@ -90,13 +93,38 @@ export const AvatarBlock: Story = {
   name: '頭像 + 說明文字',
   render: () => (
     <MenuContainer><MenuGroup>
-      <MenuItem avatar={{ alt: "Alice Chen", color: "indigo", hoverCard: personHover('Alice Chen', '設計部門') }} description="設計部門">Alice Chen</MenuItem>
-      <MenuItem avatar={{ alt: "Bob Wang", color: "magenta", hoverCard: personHover('Bob Wang', '工程部門') }} description="工程部門">Bob Wang</MenuItem>
-      <MenuItem avatar={{ alt: "Carol Lin", color: "green", hoverCard: personHover('Carol Lin', '行銷部門') }} description="行銷部門">Carol Lin</MenuItem>
+      <MenuItem avatar={{ src: avatarSrc('Alice Chen', 64), alt: "Alice Chen", color: "indigo", hoverCard: personHover('Alice Chen', '設計部門') }} description="設計部門">Alice Chen</MenuItem>
+      <MenuItem avatar={{ src: avatarSrc('Bob Wang', 64), alt: "Bob Wang", color: "magenta", hoverCard: personHover('Bob Wang', '工程部門') }} description="工程部門">Bob Wang</MenuItem>
+      <MenuItem avatar={{ src: avatarSrc('Carol Lin', 64), alt: "Carol Lin", color: "green", hoverCard: personHover('Carol Lin', '行銷部門') }} description="行銷部門">Carol Lin</MenuItem>
     </MenuGroup></MenuContainer>
   ),
 }
 
+// ── startContent(自訂 leading 徽章;佔位排列 = startIcon 同容器,見 menu-item.spec.md「結構」)──
+
+/** 類型徽章 demo helper — 消費 CAT_SOLID token pair(彩底 + 深/白字由 token 決定);size-4 = ICON_SIZE sm/md */
+const TypeBadge = ({ hue, glyph: Glyph }: { hue: CategoricalHue; glyph: typeof FileText }) => (
+  <span aria-hidden className={`inline-flex size-4 shrink-0 items-center justify-center rounded-md ${CAT_SOLID[hue]}`}>
+    <Glyph className="size-3" strokeWidth={2.5} />
+  </span>
+)
+
+export const WithStartContent: Story = {
+  name: '自訂前綴內容',
+  render: () => (
+    // 工作項類型設定的左側導覽(Jira / Meegle type settings):類型徽章 = 彩底 + glyph,
+    // LucideIcon 表達不了 → startContent;selected = 目前編輯中的類型
+    <MenuContainer width={224}>
+      <MenuGroup>
+        <MenuItem size="sm" startContent={<TypeBadge hue="indigo" glyph={FileText} />} selected>Task</MenuItem>
+        <MenuItem size="sm" startContent={<TypeBadge hue="red" glyph={Bug} />}>Bug</MenuItem>
+        <MenuItem size="sm" startContent={<TypeBadge hue="turquoise" glyph={Rocket} />}>Release</MenuItem>
+        <MenuItem size="sm" startContent={<TypeBadge hue="purple" glyph={FileText} />} disabled>Epic（已停用）</MenuItem>
+      </MenuGroup>
+    </MenuContainer>
+  ),
+}
+
 // ── 狀態 ──
 
 export const States: Story = {
@@ -197,9 +225,9 @@ const FullExampleDemo = () => {
     <MenuContainer>
       <MenuGroup>
         <MenuItem header>成員</MenuItem>
-        <MenuItem checkbox checked={selected.alice} onClick={() => toggle('alice')} avatar={{ alt: "Alice", color: "indigo" }} description="設計部門">Alice Chen</MenuItem>
-        <MenuItem checkbox checked={selected.bob} onClick={() => toggle('bob')} avatar={{ alt: "Bob", color: "magenta" }} description="工程部門">Bob Wang</MenuItem>
-        <MenuItem checkbox checked={false} avatar={{ alt: "Carol", color: "green" }} description="行銷部門" disabled>Carol Lin（已離職）</MenuItem>
+        <MenuItem checkbox checked={selected.alice} onClick={() => toggle('alice')} avatar={{ src: avatarSrc('Alice Chen', 64), alt: "Alice", color: "indigo" }} description="設計部門">Alice Chen</MenuItem>
+        <MenuItem checkbox checked={selected.bob} onClick={() => toggle('bob')} avatar={{ src: avatarSrc('Bob Wang', 64), alt: "Bob", color: "magenta" }} description="工程部門">Bob Wang</MenuItem>
+        <MenuItem checkbox checked={false} avatar={{ src: avatarSrc('Carol Lin', 64), alt: "Carol", color: "green" }} description="行銷部門" disabled>Carol Lin（已離職）</MenuItem>
       </MenuGroup>
       <MenuFooter>
         <MenuItem checkbox checked={allState} onClick={toggleAll}>全部</MenuItem>