@qijenchen/design-system 0.1.0-beta.145 → 0.1.0-beta.147

package/src/components/LinkInput/link-input.spec.md

@@ -51,8 +51,16 @@ LinkInput 是 **URL 的**輸入與顯示元件。外觀基於 Input，但 value
 
 有合法 URL 且未在編輯中時：
 - value 以 `text-primary` 藍色顯示，hover 加底線，點擊開啟連結
+- **連結的可點範圍 = 網址文字本身**：連結只有文字那麼寬，太長時縮到欄寬並截斷；不撐滿整行
 - 右側 Pencil inline action 觸發編輯模式
-- 點擊 value 是開啟連結，不是編輯——這是 LinkInput 與 Input 的核心互動差異
+- **點外框裡其他地方 = 按 Pencil**(user 2026-09-26 原話「網址欄的部分你再好好研究Jira等世界級的設計是怎麼做的，確保沒有分歧才照你建議做。」;研究結論:查到的一手來源沒有一家從空白處開連結)：內距、1px 邊框、文字與 Pencil 之間、文字右側的空白，點下去都進入編輯並聚焦輸入框。外框滑過變色是 Field 家族共用外觀(`../Field/field-wrapper.tsx` `hover:border-border-hover`)，變色的地方點下去就要有反應(`../../../ds-canonical/references/hit-area-canonical.md`「看到亮起來卻點不到」)。外框用文字游標(`FIELD_TEXT_ENTRY_CURSOR`，同 `../Input/input.spec.md`「點外框 = 點輸入處」)；連結維持手形、Pencil 維持 `cursor-pointer`
+- 按在空白處、拖過網址文字再放開(選字)不算點一下，不進入編輯
+- 點擊 value 是開啟連結，不是編輯——這是 LinkInput 與 Input 的核心互動差異。「value」指網址文字本身，不含外框裡的空白
+
+**世界級對照**：
+- Atlassian inline-edit 的讀取態：點到連結照連結原本的行為，點讀取區其他地方進入編輯 —— [`read-view.js#L27-L37`](https://cdn.jsdelivr.net/npm/@atlaskit/inline-edit@16.4.5/dist/es2019/internal/read-view.js)「If a link is clicked in the read view, default action should be taken」，非連結的點擊 `onEditRequested()`；點擊入口只到滑過範圍為止([`CHANGELOG.md` 4.5.5](https://cdn.jsdelivr.net/npm/@atlaskit/inline-edit@16.4.5/CHANGELOG.md)「fix inline-edit component edit mode triggering when clicking outside hover width」)
+- Notion URL 屬性：點網址開啟、不進入編輯，編輯另有滑過才出現的按鈕 —— [2021-09-08 release note](https://www.notion.com/releases/2021-09-08)「Clicking the URL opens that page in your web browser, rather than selecting the property for editing. And there's a new Edit URL button that appears when you hover over the property with your cursor.」
+- Salesforce Lightning Design System 記錄詳情：`<a>` 只包住值的文字，編輯是另一顆鉛筆鈕(`Edit: ${label}`)—— [`record-detail/index.jsx#L64-L96`](https://github.com/salesforce-ux/design-system/blob/cb91709d48074a8422a968fecda298a8bc715749/ui/components/form-element/record-detail/index.jsx#L64-L96)
 
 ### Input 狀態
 
@@ -105,6 +113,8 @@ URL 格式要求：必須包含 `http://` 或 `https://` protocol。
 ## 禁止事項
 
 - ❌ 不在 link 狀態下讓點擊 value 進入編輯——點擊連結必須開啟連結
+- ❌ 不讓連結撐滿整行——文字右邊看起來空白的地方點下去卻開網頁
+- ❌ 不讓 link 狀態外框裡的空白處滑過變色、點下去卻沒有反應——空白處 = Pencil
 - ❌ 不在打字過程中即時驗證格式——等 blur
 - ❌ 不省略 protocol（http/https）驗證——裸 domain 不是合法 URL
 
@@ -134,6 +144,7 @@ LinkInput 是 **Field Controls family 成員**——互動狀態(focus / invalid
 - 字母鍵 — 輸入
 - Enter — 提交,觸發 blur 驗證
 - Esc — 取消編輯,回復原值,不觸發驗證
+- Link 狀態:Tab 依序停在連結(Enter 開啟)與 Pencil(Enter / Space 進入編輯並聚焦輸入框)。「點外框空白處 = 按 Pencil」是滑鼠的捷徑,外框本身不是 tab stop,鍵盤走 Pencil
 
 **Focus**:原生 input outline 已關閉;focus 視覺提示由 Field wrapper 的 `focus-within:!border-primary` 提供(滑鼠點入也亮藍框,對齊 Field wrapper canonical)。
 

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

@@ -3,7 +3,7 @@ import { Pencil } from 'lucide-react'
 import type { VariantProps } from 'class-variance-authority'
 import { cn } from '@/lib/utils'
 import type { FieldMode, FieldVariant, FieldVariantInternal } from '@/design-system/components/Field/field-types'
-import { fieldWrapperStyles, bareInputStyles, fieldDisplayTextClass } from '@/design-system/components/Field/field-wrapper'
+import { fieldWrapperStyles, bareInputStyles, fieldDisplayTextClass, FIELD_CHROME_OWN_TARGET, FIELD_TEXT_ENTRY_CURSOR, focusFieldInputFromChrome } 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'
 import { TruncatedText } from '@/design-system/patterns/element-anatomy/truncated-text'
@@ -32,6 +32,7 @@ function formatHostname(url: string): string {
 // 取代 LinkInputDisplay sub-component:純展示 a tag,無 input chrome、無 hover affordance。
 // edit mode 內 link state(showLink branch)也共用此 helper,確保「編輯態的 link 顯示」與
 // view mode 的視覺完全一致(SSOT)。
+// 連結 hover 字色瞬間切換,不寫 transition-colors(tokens/motion/motion.spec.md「hover 回饋不做過渡」;2026-09-26 由底色延伸到字色,待辦總帳 L9 / N4(3))。
 function renderLinkAnchor(value: string, label?: string) {
   const displayText = label || formatHostname(value)
   return (
@@ -39,7 +40,7 @@ function renderLinkAnchor(value: string, label?: string) {
       href={value}
       target="_blank"
       rel="noopener noreferrer"
-      className="block truncate min-w-0 text-primary hover:text-primary-hover hover:underline transition-colors"
+      className="block truncate min-w-0 text-primary hover:text-primary-hover hover:underline"
     >
       {/* 截斷必附 tooltip(tooltip.spec.md:32)— anchor 自身即 hover 目標、無疊層,TruncatedText
           放 anchor 內(trigger = 其 span child)即可;view/readonly/edit-showLink 共用本 helper 一處修。
@@ -194,6 +195,25 @@ const LinkInput = React.forwardRef<HTMLInputElement, LinkInputProps>(
       })
     }
 
+    // 連結狀態:外框裡「不是連結、不是鉛筆」的地方點下去 = 按鉛筆(user 2026-09-26「確保沒有分歧才照你建議做」,
+    // 研究後照做;規則與出處 link-input.spec.md「Link 狀態」)。
+    // 外框滑過會變色(Field 家族 hover:border-border-hover),變色的地方點下去就要有反應 ——
+    // hit-area-canonical.md 要防的「看到亮起來卻點不到」。連結與鉛筆照它們自己的行為走:
+    // 判斷用 Field 家族共用的「外框裡自有行為的東西」清單(field-wrapper.tsx FIELD_CHROME_OWN_TARGET),不另寫一份。
+    // 用 click 不用 mousedown:與鉛筆同一個觸發時機;按下後拖出外框才放開,click 落在外框之外的共同祖先,不會觸發這裡。
+    // 拖曳選字不是點一下:按在空白處、拖過網址文字、在外框裡放開,瀏覽器仍會在外框上發 click;
+    // 此時直接看「外框裡有沒有被選起來的文字」,有就不進編輯(量的就是要保護的那件事,不拿移動距離當代理)。
+    const handleLinkChromeClick = (event: React.MouseEvent<HTMLDivElement>) => {
+      const chrome = event.currentTarget
+      const target = event.target
+      if (!(target instanceof Element)) return
+      const own = target.closest(FIELD_CHROME_OWN_TARGET)
+      if (own && own !== chrome && chrome.contains(own)) return
+      const selection = window.getSelection()
+      if (selection && !selection.isCollapsed && selection.anchorNode && chrome.contains(selection.anchorNode)) return
+      handleEdit()
+    }
+
     const handleBlur = () => {
       setEditing(false)
       const trimmed = localValue.trim()
@@ -234,6 +254,9 @@ const LinkInput = React.forwardRef<HTMLInputElement, LinkInputProps>(
         <div
           className={cn(fieldWrapperStyles({ mode: resolvedMode, variant: resolvedVariant, size }), className)}
           data-field-mode={resolvedMode}
+          // 2026-09-29 a11y(待辦總帳 OE21):disabled 的純展示殼明告 inactive(對齊 FieldLabel 2026-06-10 同修),
+          // 否則 axe 把灰化連結文字當一般文字誤報 color-contrast(modes / 色彩對照 / 尺寸對照三則 story)
+          aria-disabled={resolvedMode === 'disabled' || undefined}
         >
           <span className="flex-1 min-w-0 truncate">
             {resolvedMode === 'disabled'
@@ -255,11 +278,17 @@ const LinkInput = React.forwardRef<HTMLInputElement, LinkInputProps>(
         <div
           // 2026-07-05 D4:link 顯示分支同樣接 error(errorProp / fieldCtx.invalid)紅框,
           // 否則 <Field invalid> 下 link state 完全無 error 呈現
-          className={cn(fieldWrapperStyles({ mode: 'edit', variant: resolvedVariant, size, error }), className)}
+          // 外框用文字游標:點空白處進入的是打字(field-controls.spec.md「游標指引」input → cursor-text;同 Input 外框)。
+          // 連結(瀏覽器預設手形)與鉛筆(cursor-pointer)各自覆寫。
+          className={cn(fieldWrapperStyles({ mode: 'edit', variant: resolvedVariant, size, error }), FIELD_TEXT_ENTRY_CURSOR, className)}
           data-field-mode="edit"
           data-error={error ? '' : undefined}
+          onClick={handleLinkChromeClick}
         >
-          <span className="flex-1 min-w-0">
+          {/* flex:連結是 flex item,寬度 = 文字本身、太長時縮到欄寬截斷(min-w-0 + truncate)。
+              不撐滿整行 —— 文字右邊看起來空白的那一段屬於外框,點下去進入編輯,不是開網頁。
+              只改這個分支:view / readonly 的外框沒有第二個動作,連結維持原樣。 */}
+          <span className="flex-1 min-w-0 flex">
             {value && renderLinkAnchor(value, label)}
           </span>
           <ItemInlineAction
@@ -275,8 +304,12 @@ const LinkInput = React.forwardRef<HTMLInputElement, LinkInputProps>(
       <div
         className={cn(
           fieldWrapperStyles({ mode: 'edit', variant: resolvedVariant, size, error }),
+          // 打字狀態的整個外框都是輸入處:文字游標 + 點內距 / 邊框就聚焦 input(同 Input / NumberInput;待辦總帳 N53③,
+          // input.spec.md 已寫三者同一條;共用實作 field-wrapper.tsx focusFieldInputFromChrome)
+          FIELD_TEXT_ENTRY_CURSOR,
           className,
         )}
+        onMouseDown={focusFieldInputFromChrome}
         data-field-mode="edit"
         data-error={error ? '' : undefined}
       >

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

@@ -8,6 +8,7 @@ import { useState, useEffect } from 'react'
 import { Mail, Bell, FileText } from 'lucide-react'
 import { MenuItem, MenuGroup } from './menu-item'
 import { Tag } from '@/design-system/components/Tag/tag'
+import { SegmentedControl, SegmentedControlItem } from '@/design-system/components/SegmentedControl/segmented-control'
 // Avatar is now passed as AvatarData (data object), rendered internally by MenuItem
 
 const meta: Meta = {
@@ -132,18 +133,6 @@ const TokenAnnotation = ({ colors }: { colors: ColorSpec }) => (
   </div>
 )
 
-const Tab = ({ active, onClick, disabled, children }: { active: boolean; onClick: () => void; disabled?: boolean; children: React.ReactNode }) => {
-  if (disabled) return <span className="px-2.5 py-1 text-[12px] font-mono rounded-md text-fg-disabled bg-neutral-hover cursor-not-allowed">{children}</span>
-  return (
-    <button type="button" onClick={onClick}
-      className={`px-2.5 py-1 text-[12px] font-mono rounded-md cursor-pointer transition-colors ${
-        active ? 'bg-primary text-white font-semibold' : 'bg-neutral-hover text-fg-secondary hover:bg-neutral-active'
-      }`}>
-      {children}
-    </button>
-  )
-}
-
 const PropRow = ({ label, dot, children }: { label: string; dot?: string; children: React.ReactNode }) => (
   <div className="flex items-start gap-3 py-2 border-b border-divider last:border-b-0">
     <span className="text-[11px] text-fg-muted font-medium w-[80px] shrink-0 pt-0.5 flex items-center gap-1.5">
@@ -186,8 +175,11 @@ const BpZoneV = ({ h, color, label, sub }: { h: number; color: { bg: string; bor
   </div>
 )
 
+// 靜態視覺預覽容器(不是真的 listbox)。2026-09-24 從 `role="listbox"` 改 `role="group"`、
+// 內部 MenuItem 一律傳 `role="presentation"`:預覽沒有選取狀態也沒有方向鍵,
+// 掛 composite 角色 = 空頭承諾(`ds-canonical/references/keyboard-model-canonical.md`「鐵律」)。
 const MenuContainer = ({ children, width = 320 }: { children: React.ReactNode; width?: number }) => (
-  <div role="listbox" aria-label="MenuItem 設計預覽" className="rounded-lg bg-surface-raised border border-border overflow-hidden"
+  <div role="group" aria-label="MenuItem 設計預覽" className="rounded-lg bg-surface-raised border border-border overflow-hidden"
     style={{ boxShadow: 'var(--elevation-200)', width }}>
     {children}
   </div>
@@ -324,62 +316,64 @@ const InspectorInner = () => {
 
   return (
     <div className="flex flex-col gap-6">
-      {/* Controls */}
+      {/* Controls — 互斥切換消費 SegmentedControl(segmented-control.spec.md「何時用」2–5 個互斥選項;
+          取代手刻 Tab:它靜止借 neutral-hover、hover 借 neutral-active,是 color.spec.md 成對 token 的錯配) */}
       <div className="flex flex-col gap-2.5">
         <div className="flex items-center gap-2">
           <span className="text-[11px] text-fg-muted w-20 shrink-0">Size</span>
-          <div className="flex gap-1.5">
-            {SIZES.map((sz) => <Tab key={sz} active={size === sz} onClick={() => setSize(sz)}>{sz}</Tab>)}
-          </div>
+          <SegmentedControl size="sm" aria-label="Size" value={size} onValueChange={(v) => setSize(v as SizeKey)}>
+            {SIZES.map((sz) => <SegmentedControlItem key={sz} value={sz}>{sz}</SegmentedControlItem>)}
+          </SegmentedControl>
         </div>
         <div className="flex items-center gap-2">
           <span className="text-[11px] text-fg-muted w-20 shrink-0">Mode</span>
-          <div className="flex gap-1.5">
-            <Tab active={mode === 'single'} onClick={() => setMode('single')}>single</Tab>
-            <Tab active={mode === 'multi'} onClick={() => setMode('multi')}>multi</Tab>
-          </div>
+          <SegmentedControl size="sm" aria-label="Mode" value={mode} onValueChange={(v) => setMode(v as ModeKey)}>
+            <SegmentedControlItem value="single">single</SegmentedControlItem>
+            <SegmentedControlItem value="multi">multi</SegmentedControlItem>
+          </SegmentedControl>
         </div>
         <div className="flex items-center gap-2">
           <span className="text-[11px] text-fg-muted w-20 shrink-0">selected</span>
-          <div className="flex gap-1.5">
-            <Tab active={!selected} onClick={() => setSelected(false)}>off</Tab>
-            <Tab active={selected} onClick={() => setSelected(true)}>on</Tab>
-          </div>
+          <SegmentedControl size="sm" aria-label="selected" value={selected ? 'on' : 'off'} onValueChange={(v) => setSelected(v === 'on')}>
+            <SegmentedControlItem value="off">off</SegmentedControlItem>
+            <SegmentedControlItem value="on">on</SegmentedControlItem>
+          </SegmentedControl>
         </div>
         <div className="flex items-center gap-2">
           <span className="text-[11px] text-fg-muted w-20 shrink-0">disabled</span>
-          <div className="flex gap-1.5">
-            <Tab active={!disabled} onClick={() => setDisabled(false)}>off</Tab>
-            <Tab active={disabled} onClick={() => setDisabled(true)}>on</Tab>
-          </div>
+          <SegmentedControl size="sm" aria-label="disabled" value={disabled ? 'on' : 'off'} onValueChange={(v) => setDisabled(v === 'on')}>
+            <SegmentedControlItem value="off">off</SegmentedControlItem>
+            <SegmentedControlItem value="on">on</SegmentedControlItem>
+          </SegmentedControl>
         </div>
         <div className="flex items-center gap-2">
           <span className="text-[11px] text-fg-muted w-20 shrink-0">startIcon</span>
-          <div className="flex gap-1.5">
-            <Tab active={!hasIcon} onClick={() => setHasIcon(false)}>off</Tab>
-            <Tab active={hasIcon} onClick={() => setHasIcon(true)} disabled={hasAvatar}>on</Tab>
-          </div>
+          {/* 停用項用元件自身 disabled(segmented-control.spec.md「disabled」);icon / avatar 互斥,停用的一側恆為 off,不會是當前值 */}
+          <SegmentedControl size="sm" aria-label="startIcon" value={hasIcon ? 'on' : 'off'} onValueChange={(v) => setHasIcon(v === 'on')}>
+            <SegmentedControlItem value="off">off</SegmentedControlItem>
+            <SegmentedControlItem value="on" disabled={hasAvatar}>on</SegmentedControlItem>
+          </SegmentedControl>
         </div>
         <div className="flex items-center gap-2">
           <span className="text-[11px] text-fg-muted w-20 shrink-0">avatar</span>
-          <div className="flex gap-1.5">
-            <Tab active={!hasAvatar} onClick={() => setHasAvatar(false)}>off</Tab>
-            <Tab active={hasAvatar} onClick={() => setHasAvatar(true)} disabled={hasIcon}>on</Tab>
-          </div>
+          <SegmentedControl size="sm" aria-label="avatar" value={hasAvatar ? 'on' : 'off'} onValueChange={(v) => setHasAvatar(v === 'on')}>
+            <SegmentedControlItem value="off">off</SegmentedControlItem>
+            <SegmentedControlItem value="on" disabled={hasIcon}>on</SegmentedControlItem>
+          </SegmentedControl>
         </div>
         <div className="flex items-center gap-2">
           <span className="text-[11px] text-fg-muted w-20 shrink-0">description</span>
-          <div className="flex gap-1.5">
-            <Tab active={!hasDesc} onClick={() => setHasDesc(false)}>off</Tab>
-            <Tab active={hasDesc} onClick={() => setHasDesc(true)}>on</Tab>
-          </div>
+          <SegmentedControl size="sm" aria-label="description" value={hasDesc ? 'on' : 'off'} onValueChange={(v) => setHasDesc(v === 'on')}>
+            <SegmentedControlItem value="off">off</SegmentedControlItem>
+            <SegmentedControlItem value="on">on</SegmentedControlItem>
+          </SegmentedControl>
         </div>
         <div className="flex items-center gap-2">
           <span className="text-[11px] text-fg-muted w-20 shrink-0">tag</span>
-          <div className="flex gap-1.5">
-            <Tab active={!hasTag} onClick={() => setHasTag(false)}>off</Tab>
-            <Tab active={hasTag} onClick={() => setHasTag(true)}>on</Tab>
-          </div>
+          <SegmentedControl size="sm" aria-label="tag" value={hasTag ? 'on' : 'off'} onValueChange={(v) => setHasTag(v === 'on')}>
+            <SegmentedControlItem value="off">off</SegmentedControlItem>
+            <SegmentedControlItem value="on">on</SegmentedControlItem>
+          </SegmentedControl>
         </div>
       </div>
 
@@ -390,7 +384,7 @@ const InspectorInner = () => {
           <div className="px-4 py-6 rounded-lg bg-canvas border border-divider flex items-center justify-center">
             <MenuContainer width={340}>
               <MenuGroup>
-                <MenuItem
+                <MenuItem role="presentation"
                   size={size}
                   startIcon={hasIcon ? Mail : undefined}
                   avatar={hasAvatar ? { alt: "Alice", color: "indigo" as const } : undefined}
@@ -567,7 +561,7 @@ export const ColorMatrix = {
                   <td className="p-3 border-b border-divider align-top min-w-[280px]">
                     <MenuContainer width={260}>
                       <MenuGroup>
-                        <MenuItem
+                        <MenuItem role="presentation"
                           size="md"
                           startIcon={Mail}
                           selected={st === 'selected'}
@@ -602,7 +596,7 @@ export const ColorMatrix = {
                   <td className="p-3 border-b border-divider align-top min-w-[280px]">
                     <MenuContainer width={260}>
                       <MenuGroup>
-                        <MenuItem
+                        <MenuItem role="presentation"
                           size="md"
                           startIcon={Mail}
                           checkbox
@@ -631,8 +625,8 @@ export const ColorMatrix = {
         <div className="flex items-start gap-4">
           <MenuContainer width={260}>
             <MenuGroup>
-              <MenuItem size="md" header>群組標題</MenuItem>
-              <MenuItem size="md" startIcon={FileText}>一般選項</MenuItem>
+              <MenuItem role="presentation" size="md" header>群組標題</MenuItem>
+              <MenuItem role="presentation" size="md" startIcon={FileText}>一般選項</MenuItem>
             </MenuGroup>
           </MenuContainer>
           <div className="flex flex-col gap-0.5">
@@ -742,19 +736,19 @@ export const SizeMatrix = {
               <span className="text-caption text-fg-muted font-mono">{sz}{sz === 'md' ? '（預設）' : ''}</span>
               <MenuContainer width={380}>
                 <MenuGroup>
-                  <MenuItem size={sz} startIcon={Mail} description="每日摘要信件">
+                  <MenuItem role="presentation" size={sz} startIcon={Mail} description="每日摘要信件">
                     電子郵件通知
                   </MenuItem>
-                  <MenuItem size={sz} avatar={{ src: "https://i.pravatar.cc/48?u=alice-chen", alt: "Alice", color: "indigo" as const }}>
+                  <MenuItem role="presentation" 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={{ src: "https://i.pravatar.cc/48?u=bob-wang", alt: "Bob", color: "magenta" as const }} description="工程部門">
+                  <MenuItem role="presentation" 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}>
+                  <MenuItem role="presentation" size={sz} checkbox checked={true} startIcon={Bell}>
                     推播通知
                   </MenuItem>
-                  <MenuItem size={sz} tag={<Tag size={sz} color="neutral">Admin</Tag>}>
+                  <MenuItem role="presentation" size={sz} tag={<Tag size={sz} color="neutral">Admin</Tag>}>
                     權限標記
                   </MenuItem>
                 </MenuGroup>
@@ -774,7 +768,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  :直接使用時(如本元件 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>
+      <p className="whitespace-pre-line">{"MenuItem 只負責單行的視覺排版,本身不接管鍵盤與焦點。真正的鍵盤導覽(上下鍵切換、Enter 選取、Esc 關閉)與焦點管理由外層的選單元件(SelectMenu / DropdownMenu)負責——MenuItem 不重複實作這些行為。\n\n  語意 role  :直接使用時 MenuItem 預設渲染為 role=\"option\" 並帶 aria-selected / aria-disabled——但那要求外層真的是一個有方向鍵、有焦點管理的 listbox;本元件 stories 的預覽容器並不是(2026-09-24 起容器為 role=\"group\"、每個 MenuItem 傳 role=\"presentation\",不假裝是選單);巢狀在外層互動節點內時(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>
   ),
 }

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

@@ -251,7 +251,7 @@ Menu item 的 prefix icon 跟 label 同色（foreground），不是 fg-muted。P
 | 建立操作選單（複製 / 刪除 / 分享）| 用 `DropdownMenu` + `DropdownMenuItem`（內部消費 MenuItem）|
 | 建立選值下拉（選項 + 搜尋）| 用 `SelectMenu`（內部消費 MenuItem）|
 | 建立右鍵選單 | 用未來的 `ContextMenu`（待開發）|
-| 直接在 JSX 中用 `<MenuItem>` | ❌ **禁止**——會失去 menu 外層的 Radix 無障礙 / 鍵盤 / 焦點管理。唯一例外:本元件**自身 stories** 的 internal 展示(demo 容器以 `role="listbox"` 滿足 a11y parent 要求,見 `menu-item.stories.tsx`),產品 code 無豁免 |
+| 直接在 JSX 中用 `<MenuItem>` | ❌ **禁止**——會失去 menu 外層的 Radix 無障礙 / 鍵盤 / 焦點管理。唯一例外:本元件與 Avatar / Separator / item-anatomy 的**自身 stories** 靜態視覺預覽;該預覽**不得**假裝成選單——容器用 `role="group"`、每個 MenuItem 傳 `role="presentation"`(2026-09-24 訂正,原本容器掛 `role="listbox"` 只為消 axe `aria-required-parent`,但那個容器沒有選取狀態、沒有方向鍵、沒有焦點管理 = 對輔助科技的空頭承諾,SSOT `ds-canonical/references/keyboard-model-canonical.md`「鐵律」)。產品 code 無豁免 |
 
 ### 消費者
 

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

@@ -37,9 +37,15 @@ const meta: Meta<typeof MenuItem> = {
 export default meta
 type Story = StoryObj<typeof MenuItem>
 
-/** Menu 容器 — 模擬浮層外觀。demo 用 role='listbox' 滿足 MenuItem role='option' 的 parent 要求(axe aria-required-parent);
- *  只放訊息列(非 option)的 demo 改 role='group' —— listbox 裡不得只有非 option 子元素(axe aria-required-children,2026-09-08)。 */
-const MenuContainer = ({ children, width = 320, role = 'listbox' }: { children: React.ReactNode; width?: number; role?: 'listbox' | 'group' }) => (
+/** Menu 容器 — 模擬浮層外觀的**靜態視覺預覽**,不是真的選單。
+ *
+ * 2026-09-24:預設 role 從 `'listbox'` 改 `'group'`,裡面的 MenuItem 一律傳 `role="presentation"`。
+ * 原本掛 listbox 的理由只是「滿足 MenuItem role='option' 的 parent 要求(axe aria-required-parent)」——
+ * 那是拿角色去消 lint,不是描述它真的是什麼:這個容器沒有選取狀態、沒有方向鍵、沒有焦點管理,
+ * `listbox` 對螢幕閱讀器是空頭承諾(SSOT:`ds-canonical/references/keyboard-model-canonical.md`「鐵律」)。
+ * 兩邊一起拿掉就同時消滅了孤兒 option 與假 composite,axe 仍 0 ARIA violation(2026-09-24 實跑)。
+ * `role` prop 保留是為了讓個別 demo 還能顯式標注,但沒有任何 demo 該回去用 listbox。 */
+const MenuContainer = ({ children, width = 320, role = 'group' }: { children: React.ReactNode; width?: number; role?: 'listbox' | 'group' }) => (
   <div role={role} aria-label="Menu demo items" className="rounded-lg bg-surface-raised border border-border overflow-hidden"
     style={{ boxShadow: 'var(--elevation-200)', width }}>
     {children}
@@ -52,9 +58,9 @@ export const Default: Story = {
   name: '基本',
   render: () => (
     <MenuContainer><MenuGroup>
-      <MenuItem>收件匣</MenuItem>
-      <MenuItem>草稿</MenuItem>
-      <MenuItem>已傳送</MenuItem>
+      <MenuItem role="presentation">收件匣</MenuItem>
+      <MenuItem role="presentation">草稿</MenuItem>
+      <MenuItem role="presentation">已傳送</MenuItem>
     </MenuGroup></MenuContainer>
   ),
 }
@@ -70,9 +76,9 @@ export const WithDescription: Story = {
   name: '前置圖示 + 說明文字',
   render: () => (
     <MenuContainer><MenuGroup>
-      <MenuItem startIcon={Mail} description="每日摘要信件">電子郵件通知</MenuItem>
-      <MenuItem startIcon={Bell} description="即時推播到裝置">推播通知</MenuItem>
-      <MenuItem startIcon={Settings} description="自訂通知偏好">進階設定</MenuItem>
+      <MenuItem role="presentation" startIcon={Mail} description="每日摘要信件">電子郵件通知</MenuItem>
+      <MenuItem role="presentation" startIcon={Bell} description="即時推播到裝置">推播通知</MenuItem>
+      <MenuItem role="presentation" startIcon={Settings} description="自訂通知偏好">進階設定</MenuItem>
     </MenuGroup></MenuContainer>
   ),
 }
@@ -83,9 +89,9 @@ export const AvatarInline: Story = {
   name: '頭像',
   render: () => (
     <MenuContainer><MenuGroup>
-      <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>
+      <MenuItem role="presentation" avatar={{ src: avatarSrc('Alice Chen', 48), alt: "Alice Chen", color: "indigo", hoverCard: personHover('Alice Chen') }}>Alice Chen</MenuItem>
+      <MenuItem role="presentation" avatar={{ src: avatarSrc('Bob Wang', 48), alt: "Bob Wang", color: "magenta", hoverCard: personHover('Bob Wang') }}>Bob Wang</MenuItem>
+      <MenuItem role="presentation" avatar={{ src: avatarSrc('Carol Lin', 48), alt: "Carol Lin", color: "green", hoverCard: personHover('Carol Lin') }}>Carol Lin</MenuItem>
     </MenuGroup></MenuContainer>
   ),
 }
@@ -96,9 +102,9 @@ export const AvatarBlock: Story = {
   name: '頭像 + 說明文字',
   render: () => (
     <MenuContainer><MenuGroup>
-      <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>
+      <MenuItem role="presentation" avatar={{ src: avatarSrc('Alice Chen', 64), alt: "Alice Chen", color: "indigo", hoverCard: personHover('Alice Chen', '設計部門') }} description="設計部門">Alice Chen</MenuItem>
+      <MenuItem role="presentation" avatar={{ src: avatarSrc('Bob Wang', 64), alt: "Bob Wang", color: "magenta", hoverCard: personHover('Bob Wang', '工程部門') }} description="工程部門">Bob Wang</MenuItem>
+      <MenuItem role="presentation" avatar={{ src: avatarSrc('Carol Lin', 64), alt: "Carol Lin", color: "green", hoverCard: personHover('Carol Lin', '行銷部門') }} description="行銷部門">Carol Lin</MenuItem>
     </MenuGroup></MenuContainer>
   ),
 }
@@ -119,10 +125,10 @@ export const WithStartContent: Story = {
     // 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>
+        <MenuItem role="presentation" size="sm" startContent={<TypeBadge hue="indigo" glyph={FileText} />} selected>Task</MenuItem>
+        <MenuItem role="presentation" size="sm" startContent={<TypeBadge hue="red" glyph={Bug} />}>Bug</MenuItem>
+        <MenuItem role="presentation" size="sm" startContent={<TypeBadge hue="turquoise" glyph={Rocket} />}>Release</MenuItem>
+        <MenuItem role="presentation" size="sm" startContent={<TypeBadge hue="purple" glyph={FileText} />} disabled>Epic（已停用）</MenuItem>
       </MenuGroup>
     </MenuContainer>
   ),
@@ -134,9 +140,9 @@ export const States: Story = {
   name: '狀態',
   render: () => (
     <MenuContainer><MenuGroup>
-      <MenuItem startIcon={Mail}>收件匣</MenuItem>
-      <MenuItem startIcon={Mail} selected>已星標（單選）</MenuItem>
-      <MenuItem startIcon={Mail} disabled>已封存</MenuItem>
+      <MenuItem role="presentation" startIcon={Mail}>收件匣</MenuItem>
+      <MenuItem role="presentation" startIcon={Mail} selected>已星標（單選）</MenuItem>
+      <MenuItem role="presentation" startIcon={Mail} disabled>已封存</MenuItem>
     </MenuGroup></MenuContainer>
   ),
 }
@@ -159,13 +165,13 @@ const MultiSelectDemo = () => {
   return (
     <>
       <MenuGroup>
-        <MenuItem checkbox checked={selected.email} startIcon={Mail} onClick={() => toggle('email')}>電子郵件</MenuItem>
-        <MenuItem checkbox checked={selected.push} startIcon={Bell} onClick={() => toggle('push')}>推播通知</MenuItem>
-        <MenuItem checkbox checked={selected.slack} startIcon={Settings} onClick={() => toggle('slack')}>Slack</MenuItem>
-        <MenuItem checkbox checked={false} disabled startIcon={Star}>SMS（已停用）</MenuItem>
+        <MenuItem role="presentation" checkbox checked={selected.email} startIcon={Mail} onClick={() => toggle('email')}>電子郵件</MenuItem>
+        <MenuItem role="presentation" checkbox checked={selected.push} startIcon={Bell} onClick={() => toggle('push')}>推播通知</MenuItem>
+        <MenuItem role="presentation" checkbox checked={selected.slack} startIcon={Settings} onClick={() => toggle('slack')}>Slack</MenuItem>
+        <MenuItem role="presentation" checkbox checked={false} disabled startIcon={Star}>SMS（已停用）</MenuItem>
       </MenuGroup>
       <MenuFooter>
-        <MenuItem checkbox checked={allState} onClick={toggleAll}>全部</MenuItem>
+        <MenuItem role="presentation" checkbox checked={allState} onClick={toggleAll}>全部</MenuItem>
       </MenuFooter>
     </>
   )
@@ -183,15 +189,15 @@ export const Groups: Story = {
   render: () => (
     <MenuContainer>
       <MenuGroup>
-        <MenuItem header>最近使用</MenuItem>
-        <MenuItem startIcon={FileText}>Q3 產品路線圖.md</MenuItem>
-        <MenuItem startIcon={FileText}>客戶反饋整理</MenuItem>
+        <MenuItem role="presentation" header>最近使用</MenuItem>
+        <MenuItem role="presentation" startIcon={FileText}>Q3 產品路線圖.md</MenuItem>
+        <MenuItem role="presentation" startIcon={FileText}>客戶反饋整理</MenuItem>
       </MenuGroup>
       <MenuGroup>
-        <MenuItem header>所有專案</MenuItem>
-        <MenuItem startIcon={Folder}>設計系統升級 v2</MenuItem>
-        <MenuItem startIcon={Folder}>行銷活動 2026</MenuItem>
-        <MenuItem startIcon={BarChart3}>業務儀表板</MenuItem>
+        <MenuItem role="presentation" header>所有專案</MenuItem>
+        <MenuItem role="presentation" startIcon={Folder}>設計系統升級 v2</MenuItem>
+        <MenuItem role="presentation" startIcon={Folder}>行銷活動 2026</MenuItem>
+        <MenuItem role="presentation" startIcon={BarChart3}>業務儀表板</MenuItem>
       </MenuGroup>
     </MenuContainer>
   ),
@@ -206,10 +212,10 @@ export const Messages: Story = {
     // 前綴槽放列圖示尺寸(md = ICON_SIZE.md)的轉圈,文字仍可見。
     <div className="flex gap-4">
       <MenuContainer width={240} role="group"><MenuGroup>
-        <MenuItem message>沒有人員</MenuItem>
+        <MenuItem role="presentation" message>沒有人員</MenuItem>
       </MenuGroup></MenuContainer>
       <MenuContainer width={240} role="group"><MenuGroup>
-        <MenuItem message startContent={<CircularProgress size={ICON_SIZE.md} />}>載入選項中</MenuItem>
+        <MenuItem role="presentation" message startContent={<CircularProgress size={ICON_SIZE.md} />}>載入選項中</MenuItem>
       </MenuGroup></MenuContainer>
     </div>
   ),
@@ -221,7 +227,7 @@ export const Creatable: Story = {
   name: '可建立新項',
   render: () => (
     <MenuContainer><MenuGroup>
-      <MenuItem startIcon={Plus}>直接使用「新標籤」</MenuItem>
+      <MenuItem role="presentation" startIcon={Plus}>直接使用「新標籤」</MenuItem>
     </MenuGroup></MenuContainer>
   ),
 }
@@ -245,13 +251,13 @@ const FullExampleDemo = () => {
   return (
     <MenuContainer>
       <MenuGroup>
-        <MenuItem header>成員</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>
+        <MenuItem role="presentation" header>成員</MenuItem>
+        <MenuItem role="presentation" checkbox checked={selected.alice} onClick={() => toggle('alice')} avatar={{ src: avatarSrc('Alice Chen', 64), alt: "Alice", color: "indigo" }} description="設計部門">Alice Chen</MenuItem>
+        <MenuItem role="presentation" checkbox checked={selected.bob} onClick={() => toggle('bob')} avatar={{ src: avatarSrc('Bob Wang', 64), alt: "Bob", color: "magenta" }} description="工程部門">Bob Wang</MenuItem>
+        <MenuItem role="presentation" 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>
+        <MenuItem role="presentation" checkbox checked={allState} onClick={toggleAll}>全部</MenuItem>
       </MenuFooter>
     </MenuContainer>
   )

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

@@ -20,6 +20,7 @@ import {
 } from 'lucide-react'
 import { Notice, SUBTLE_ICON_COLOR, type NoticeVariant } from './notice'
 import { Button } from '@/design-system/components/Button/button'
+import { Chip, ChipGroup } from '@/design-system/components/Chip/chip'
 import { H3, Desc, Td, Th, Swatch } from '@/design-system/stories-helpers/anatomy/anatomy-utils'
 
 const meta: Meta = {
@@ -277,22 +278,13 @@ function NoticeInspector() {
       <div className="flex flex-col gap-6">
         <div>
           <H3>Variant</H3>
-          <div className="flex flex-wrap gap-2">
-            {VARIANTS.map((v) => (
-              <button
-                key={v}
-                type="button"
-                onClick={() => setVariant(v)}
-                className={`px-2.5 py-1 text-caption rounded-md font-mono cursor-pointer ${
-                  v === variant
-                    ? 'bg-primary text-white'
-                    : 'bg-neutral-hover text-fg-secondary hover:bg-neutral-active'
-                }`}
-              >
-                {v}
-              </button>
-            ))}
-          </div>
+          {/* 5 個互斥選項放在 320px 右欄:SegmentedControl 連體不換行、放不下(segmented-control.spec.md「不支援 overflow…
+              若選項可能超出容器寬度,代表選錯元件了」)→ ChipGroup 單選 wrap(chip.spec.md「與 SegmentedControl 的差異」)。
+              取代手刻 pill:它靜止借 neutral-hover、hover 借 neutral-active(color.spec.md 成對 token 錯配)。
+              Radix 單選再點已選項回傳空字串 → 忽略,維持恆有一值 */}
+          <ChipGroup type="single" aria-label="Variant" value={variant} onValueChange={(v) => { if (v) setVariant(v as NoticeVariant) }}>
+            {VARIANTS.map((v) => <Chip key={v} value={v}>{v}</Chip>)}
+          </ChipGroup>
         </div>
 
         <div>

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

@@ -155,7 +155,7 @@ Notice 是 **Toast / Alert 共用的 layout primitive**,刻意不擁有尺寸與
 
 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**: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 決定)。
+**Focus**:Notice 自身渲染的唯一 focusable 元素是 dismiss `<Button>`(consumer 經 `endContent` 注入的互動元素——如上方建議的 tertiary Button——由 consumer 自管 a11y),focus indicator 走 Button canonical(全域 `:focus-visible` 外描邊 `outline: 2px solid var(--ring)`,往外 2px;Button 與 Notice 都不寫任何 focus class);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

@@ -153,7 +153,7 @@ const Notice = React.forwardRef<HTMLDivElement, NoticeProps>(
           // 已移除)。item-anatomy.spec.md 把 Notice 的 action/dismiss 對應到 suffix slot;ItemSuffix
           // base geometry(h-[1lh] shrink-0 ml-auto flex items-center gap-2)正是此處所需,hoverReveal
           // 預設 false 故無 row inline-action 機制干擾。內裝 dismiss = Button iconOnly dismiss xs(banner
-          // family canonical,overlay-surface.spec.md「Chrome dismiss size canonical」)。
+          // family canonical,patterns/overlay-surface/overlay-chrome-sizing.spec.md「Chrome dismiss size canonical」)。
           <ItemSuffix>
             {endContent}
             {/* 誤觸保護分隔線由 DS 放,consumer 零自刻(同 Dialog 先例 dialog.tsx:184-193)。