@qijenchen/design-system 0.1.0-beta.95 → 0.1.0-beta.99

package/src/components/ProgressBar/progress-bar.principles.stories.tsx

@@ -122,7 +122,7 @@ export const UsageGuidance: Story = {
           note="status 三選一是系統決定的語意。consumer 要紅、綠、藍以外的色 → 提到系統層討論是否新增 status,不要每個消費者自己用 className override fill 色。"
         >
           <Frame>
-            <ProgressBar value={55} status="inProgress" />
+            <ProgressBar value={55} status="inProgress" aria-label="標準進度色示範" />
           </Frame>
           <Label>✅ 走 status token(info / success / error),不 override 色值</Label>
         </Rule>
@@ -139,7 +139,7 @@ export const UsageGuidance: Story = {
               <span className="text-body flex-1">匯出客戶名單 CSV</span>
               <span className="text-caption text-fg-muted tabular-nums">812 / 1,250 筆</span>
             </div>
-            <ProgressBar value={65} status="inProgress" />
+            <ProgressBar value={65} status="inProgress" aria-label="匯出客戶名單進度" />
           </Frame>
           <Label>✅ CSV 匯出 / 批次處理:總量已知 → ProgressBar(檔案上傳改用 FileItem,見下方)</Label>
 
@@ -159,7 +159,7 @@ export const UsageGuidance: Story = {
               <FileText size={16} className="text-fg-muted" />
               <span className="text-body flex-1">產生季度報表中...</span>
             </div>
-            <ProgressBar value={0} status="inProgress" />
+            <ProgressBar value={0} status="inProgress" aria-label="無法量化的報表產生進度（誤用）" />
           </Frame>
           <Label warn>❌ 若無法量化卻硬用 ProgressBar(永遠卡 0% 或亂跳):使用者會以為壞掉 → 改用 CircularProgress(indeterminate)</Label>
         </Rule>
@@ -174,7 +174,7 @@ export const UsageGuidance: Story = {
               <span className="text-body flex-1">附件_會議記錄.docx</span>
               <span className="text-caption text-fg-muted">58%</span>
             </div>
-            <ProgressBar value={58} status="inProgress" />
+            <ProgressBar value={58} status="inProgress" aria-label="附件上傳進度（自組誤用）" />
           </Frame>
           <Label warn>❌ Consumer 自組檔名 + Paperclip + ProgressBar 做上傳列表 → 應該用 FileItem</Label>
 
@@ -184,7 +184,7 @@ export const UsageGuidance: Story = {
               <span className="text-body-lg font-medium flex-1">匯入客戶名單</span>
               <span className="text-caption text-fg-muted tabular-nums">812 / 1,250 筆</span>
             </div>
-            <ProgressBar value={65} status="inProgress" affix="value" />
+            <ProgressBar value={65} status="inProgress" affix="value" aria-label="匯入客戶名單進度" />
             <p className="text-footnote text-fg-muted mt-2">處理中,預計剩餘 28 秒</p>
           </Frame>
           <Label>✅ CSV 批次匯入 / 報表生成 → 直接用 ProgressBar(非檔案情境,FileItem 不適用)</Label>
@@ -207,7 +207,7 @@ export const StatusRule: Story = {
             <Paperclip size={16} className="text-fg-muted" />
             <span className="text-body flex-1">Q1_財報.xlsx</span>
           </div>
-          <ProgressBar value={42} status="inProgress" affix="value" />
+          <ProgressBar value={42} status="inProgress" affix="value" aria-label="Q1 財報上傳進度" />
         </Frame>
         <Label>✅ 上傳中用 inProgress,affix 顯示進度百分比</Label>
 
@@ -216,7 +216,7 @@ export const StatusRule: Story = {
             <Paperclip size={16} className="text-fg-muted" />
             <span className="text-body flex-1">簡報_final.pptx</span>
           </div>
-          <ProgressBar value={100} status="success" affix="status-icon" />
+          <ProgressBar value={100} status="success" affix="status-icon" aria-label="簡報上傳完成" />
         </Frame>
         <Label>✅ 完成用 success + 勾 icon(終態指示)</Label>
 
@@ -226,7 +226,7 @@ export const StatusRule: Story = {
             <span className="text-body flex-1">影片素材.mp4</span>
             <span className="text-caption text-error">檔案過大</span>
           </div>
-          <ProgressBar value={68} status="error" affix="status-icon" />
+          <ProgressBar value={68} status="error" affix="status-icon" aria-label="影片素材上傳失敗" />
         </Frame>
         <Label>✅ 失敗用 error + 叉 icon,旁邊可補上具體錯誤說明</Label>
       </Rule>
@@ -240,7 +240,7 @@ export const StatusRule: Story = {
             <span className="text-body flex-1">儲存空間</span>
             <span className="text-caption text-error tabular-nums">95% 使用</span>
           </div>
-          <ProgressBar value={95} status="error" />
+          <ProgressBar value={95} status="error" aria-label="儲存空間使用率" />
         </Frame>
         <Label>✅ 配額快滿:consumer 判斷「95% 以上顯示警示」後自行把 status 切成 error</Label>
       </Rule>
@@ -260,7 +260,7 @@ export const AffixRule: Story = {
           <div className="flex items-center gap-2 mb-2">
             <span className="text-body flex-1">儲存空間</span>
           </div>
-          <ProgressBar value={78} status="inProgress" affix="value" />
+          <ProgressBar value={78} status="inProgress" affix="value" aria-label="儲存空間使用率" />
         </Frame>
         <Label>✅ 配額顯示:affix=value,使用者要知道確切百分比</Label>
 
@@ -269,7 +269,7 @@ export const AffixRule: Story = {
             <Paperclip size={16} className="text-fg-muted" />
             <span className="text-body flex-1">提案書_終版.pdf</span>
           </div>
-          <ProgressBar value={100} status="success" affix="status-icon" />
+          <ProgressBar value={100} status="success" affix="status-icon" aria-label="提案書上傳完成" />
         </Frame>
         <Label>✅ 上傳完成:affix=status-icon,終態不需要再看百分比</Label>
       </Rule>
@@ -286,6 +286,7 @@ export const AffixRule: Story = {
           <ProgressBar
             value={42}
             status="inProgress"
+            aria-label="設計規範上傳進度"
             affix={<Button variant="text" size="xs" iconOnly startIcon={X} aria-label="取消上傳" />}
           />
         </Frame>
@@ -299,6 +300,7 @@ export const AffixRule: Story = {
           <ProgressBar
             value={66}
             status="inProgress"
+            aria-label="影片素材上傳進度"
             affix={<span className="text-caption text-fg-muted tabular-nums shrink-0">3.3 / 5.0 MB</span>}
           />
         </Frame>
@@ -315,7 +317,7 @@ export const AffixRule: Story = {
             <span className="text-body flex-1">附件.zip</span>
             <span className="text-caption text-fg-muted tabular-nums">55%</span>
           </div>
-          <ProgressBar value={55} status="inProgress" />
+          <ProgressBar value={55} status="inProgress" aria-label="附件上傳進度" />
         </Frame>
         <Label>✅ 上方已有 55% 文字 → bar 不加 affix,避免重複</Label>
       </Rule>

package/src/components/RadioGroup/radio-group.anatomy.stories.tsx

@@ -429,7 +429,11 @@ export const ColorMatrix = {
                   return (
                     <td key={st} className="p-3 border-b border-divider align-top min-w-[160px]">
                       <RadioGroup defaultValue={isChecked ? 'demo' : undefined}>
-                        <RadioGroupItem value="demo" disabled={isDisabled} />
+                        <RadioGroupItem
+                          value="demo"
+                          disabled={isDisabled}
+                          aria-label={`${c} ${st} Radio`}
+                        />
                       </RadioGroup>
                       <TokenAnnotation colors={TOKEN_MAP[c][st]} />
                     </td>

package/src/components/RadioGroup/radio-group.spec.md

@@ -111,7 +111,7 @@ Item-level default / hover / checked / disabled **色彩**與 Checkbox 共用同
 - **No value selected**:`value=null` 為合法 initial state(所有 radio 都 unchecked);Field validation 在 required + null 時觸發 error。
 - **極長 label / description**:預設不截斷、自然換行(`labelMaxLines` / `descMaxLines` 預設 `'none'`,Clamp 政策 SSOT 見 `checkbox.spec.md`「Clamp 政策」)。
 - **icon / avatar prefix**:`RadioGroupItem` 一級 `icon` / `avatar` props 轉發 `SelectionItem` prefix 槽(2026-06-12 M30;規則 SSOT 見 `checkbox.spec.md` 同段 + `selection-item.spec.md`)。
-- **RTL**:未實作方向鏡像;RTL 屬 DS-wide 決策,未定(與 Chip / Breadcrumb 同口徑)。
+- **RTL**:不支援；全域 LTR-only compatibility contract 見 `packages/design-system/README.md#compatibility-matrix`。
 - **Dark mode / density**:走 SelectionItem semantic token 自動 adapt;垂直行距由 SelectionItem `py = (field-height − 1lh) / 2` 公式消費 uiSize token(`--field-height-*`)生成,隨 density 自動調整(零外部 gap 機制 SSOT 見 `checkbox.spec.md`「群組模式」)。
 
 ---

package/src/components/Rating/rating.principles.stories.tsx

@@ -84,8 +84,8 @@ export const UsageGuidance: Story = {
           <Label>✅ `aria-label=&quot;平均評分 4.5 星，共 5 星&quot;`</Label>
         </div>
         <div className="flex flex-col gap-2 w-[320px] p-4 border border-border rounded-md">
-          <Rating value={4.5} readOnly precision="half" size="md" />
-          <Label warn>❌ 無 aria-label，螢幕閱讀器讀不出分數</Label>
+          <Rating value={4.5} readOnly precision="half" size="md" aria-label="平均評分 4.5 星，共 5 星" />
+          <Label warn>❌ 若省略 aria-label，螢幕閱讀器會讀不出分數；此可執行示範仍保留名稱，避免 demo 本身成為違規來源</Label>
         </div>
       </Rule>
 

package/src/components/ScrollArea/scroll-area.anatomy.stories.tsx

@@ -140,7 +140,7 @@ export const Overview: Story = {
                 ['className',  'string',                            '—',       '傳入容器 className(常見:設定 height / border / rounded)'],
                 ['children',   'ReactNode',                         '—',       '要被捲動的內容'],
                 ['type',       "'auto'|'always'|'scroll'|'hover'",  "'hover'", 'Radix:scrollbar 顯示時機(hover = 游標進入才顯示)'],
-                ['dir',        "'ltr'|'rtl'",                       "'ltr'",   '文字方向(影響 horizontal scrollbar 起點)'],
+                ['dir',        "'ltr' only",                        "'ltr'",   '全域 compatibility contract 為 LTR-only；不宣稱 RTL 覆蓋'],
                 ['scrollHideDelay', 'number',                       '600',     'type=scroll / hover 時 scrollbar 隱藏前的延遲(ms)'],
               ].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/ScrollArea/scroll-area.spec.md

@@ -16,7 +16,7 @@ ScrollArea 是**跨 OS 視覺一致的自訂捲動容器**——用 overlay 捲
 
 **Layout Family**:非上述 family — self-contained primitive(純捲動容器,無 slot 結構)。
 
-**實作基礎**:基於 Radix ScrollArea primitive(shadcn passthrough 結構)——由 Radix 處理 viewport / scrollbar / thumb 的 pointer 拖曳與 overflow-detection,本 DS 橋接 token(scrollbar 寬度、thumb bg、hover 反饋)與 a11y 行為(Viewport `tabIndex={0}` 預設 + `viewportTabIndex={-1}` opt-out + DS focus ring;Radix 不處理 keyboard,亦不自動標 Viewport focusable)。
+**實作基礎**:基於 Radix ScrollArea primitive(shadcn passthrough 結構)——由 Radix 處理 viewport / scrollbar / thumb 的 pointer 拖曳與 overflow-detection,本 DS 橋接 token(scrollbar 寬度、thumb bg、hover 反饋)與 a11y 行為(Viewport `tabIndex={0}` 預設 + `viewportTabIndex={-1}` 雙 tab-stop opt-out + `viewportTabIndex={null}` ARIA composite wrapper opt-out + DS focus ring;Radix 不處理 keyboard,亦不自動標 Viewport focusable)。
 
 **世界級對照**:shadcn `ScrollArea` / Radix primitive 本身。Polaris / Carbon 未提供等效元件(預設相信 native scrollbar);我們採用 shadcn / Radix 派:為了跨 OS 視覺一致、避免 DataTable / Sheet / Dialog 遇 Windows always-visible scrollbar 吃寬度跑版。 <!-- @benchmark-unverified: see frontmatter benchmark list for canonical DS source URL -->
 
@@ -100,12 +100,12 @@ ScrollArea 用 Radix 自訂 overlay 捲軸 → **跨 OS 一致、不吃寬度、
 
 Radix primitive + 本 DS a11y 橋接:
 
-- **鍵盤捲動**:本 DS 在 Viewport 加 `tabIndex={0}`(預設)使其可被鍵盤聚焦(Radix 不自動把 scroll container 標 focusable,Safari 尤其需要;此即 axe `scrollable-region-focusable` fix)。聚焦後 `ArrowUp/Down/Left/Right` / `PageUp/Down` / `Home/End` 捲動為瀏覽器原生行為,非 Radix 提供。**`viewportTabIndex={-1}` opt-out(2026-07-14)**:內容已有自帶 focusable + 鍵盤處理的元素(如 TimePicker `role="listbox"` `tabIndex={0}`)時傳 `-1`,消除「Viewport+內容雙 tab stop、焦點落 Viewport 時方向鍵觸發原生捲動非元件行為」;axe 由內部 focusable 內容滿足
+- **鍵盤捲動**:本 DS 在 Viewport 加 `tabIndex={0}`(預設)使其可被鍵盤聚焦(Radix 不自動把 scroll container 標 focusable,Safari 尤其需要;此即 axe `scrollable-region-focusable` fix)。聚焦後 `ArrowUp/Down/Left/Right` / `PageUp/Down` / `Home/End` 捲動為瀏覽器原生行為,非 Radix 提供。**`viewportTabIndex={-1}` opt-out(2026-07-14)**:內容已有自帶 focusable + 鍵盤處理的元素(如 TimePicker `role="listbox"` `tabIndex={0}`)時傳 `-1`,消除「Viewport+內容雙 tab stop、焦點落 Viewport 時方向鍵觸發原生捲動非元件行為」;axe 由內部 focusable 內容滿足。**`viewportTabIndex={null}` composite opt-out(2026-07-31)**:ScrollArea 被 `role="menu"` 等 ARIA composite 當純結構 wrapper、鍵盤與 focus 由其 item family own 時,完全省略 viewport `tabindex`;`-1` 仍會留下 `div[tabindex]`,不能滿足 composite 的 required-children 結構
 - **Focus 可見**:聚焦的 Viewport 顯示 DS focus ring(`focus-visible:outline-ring`,inset 2px),非瀏覽器原生 focus ring
 - **Scrollbar 非 tab stop**:scrollbar thumb 不搶焦點,使用鍵盤的使用者透過 viewport 捲動(Radix 內建)
 - **Pointer 支援**:thumb 可拖曳,track 可 click-to-jump(Radix 內建)
 
-本元件已內建 `tabIndex`(預設 0;`viewportTabIndex={-1}` 可 opt-out,見「鍵盤捲動」)+ focus ring(滿足 axe `scrollable-region-focusable`)。但 Viewport 預設**無 `role` / accessible name**——**若 scroll 區域有具體語意(如「留言列表」「程式碼區塊」),consumer 應提供 `aria-label`**,否則 SR 只報「可捲動區域」無內容描述;純視覺裝飾容器可省略。(2026-05-31 #31:修正原「consumer 無需額外處理 a11y」過度宣稱)
+本元件已內建 `tabIndex`(預設 0;`viewportTabIndex={-1}` / `{null}` 依上述兩種 owner 情境 opt-out)+ focus ring(滿足 axe `scrollable-region-focusable`)。但 Viewport 預設**無 `role` / accessible name**——**若 scroll 區域有具體語意(如「留言列表」「程式碼區塊」),consumer 應提供 `aria-label`**,否則 SR 只報「可捲動區域」無內容描述;純視覺裝飾容器可省略。(2026-05-31 #31:修正原「consumer 無需額外處理 a11y」過度宣稱)
 
 ---
 

package/src/components/ScrollArea/scroll-area.tsx

@@ -43,9 +43,10 @@ const ScrollArea = React.forwardRef<
      *  場景勿開 — table wrapper 是其 min-content 溢出機制)。 */
     fillX?: boolean
     /** Viewport tabIndex(預設 0 = axe scrollable-region-focusable fix)。內容已有自帶
-     *  focusable 元素(如 TimePicker role=listbox tabIndex=0)時傳 -1 消除雙 tab stop —
-     *  axe 由內部 focusable 內容滿足,焦點直接落在有 keydown 的 listbox 上。 */
-    viewportTabIndex?: 0 | -1
+     *  focusable 元素(如 TimePicker role=listbox tabIndex=0)時傳 -1 消除雙 tab stop。
+     *  當 ScrollArea 是 ARIA composite(role=menu 等)的純結構 wrapper 時傳 null,完全省略
+     *  tabindex,避免在 composite 直屬樹插入不合法的可聚焦 generic div。 */
+    viewportTabIndex?: 0 | -1 | null
   }
 >(({ className, children, fillX, viewportTabIndex = 0, ...props }, ref) => (
   <ScrollAreaPrimitive.Root
@@ -63,7 +64,7 @@ const ScrollArea = React.forwardRef<
         才能 keyboard focus(Safari 不自動把 scroll container 標 focusable)。focus-
         visible:outline 用 DS focus ring,不破壞視覺。 */}
     <ScrollAreaPrimitive.Viewport
-      tabIndex={viewportTabIndex}
+      tabIndex={viewportTabIndex ?? undefined}
       className={cn(
         'flex-1 min-h-0 w-full rounded-[inherit] focus-visible:outline-2 focus-visible:outline-offset-[-2px] focus-visible:outline-ring',
         fillX && '[&>div]:!block [&>div]:!w-full [&>div]:!min-w-0',

package/src/components/Select/select.principles.stories.tsx

@@ -7,6 +7,7 @@ import LinkTo from '@storybook/addon-links/react'
 import type { Meta, StoryObj } from '@storybook/react'
 import { Flag } from 'lucide-react'
 import { Select } from './select'
+import { Field, FieldLabel } from '@/design-system/components/Field/field'
 
 const meta: Meta = {
   title: 'Design System/Components/Select/設計原則',
@@ -216,10 +217,10 @@ export const ImmediateVsSubmitRule: Story = {
           note="建立/編輯表單、對話框設定。onChange 寫進 React state,直到 submit button 被按才送出。有「取消」可回復"
         >
           <div className="border border-border rounded-lg p-4 space-y-3">
-            <div>
-              <label className="text-caption text-fg-muted mb-1 block">Category</label>
+            <Field>
+              <FieldLabel>Category</FieldLabel>
               <Select options={categoryOptions} value={draft} onChange={setDraft} />
-            </div>
+            </Field>
             <div className="flex gap-2 pt-2">
               <button className="h-field-md px-3 text-body rounded-md bg-primary text-inverse-fg">儲存</button>
               <button className="h-field-md px-3 text-body rounded-md border border-border">取消</button>

package/src/components/Select/select.stories.tsx

@@ -6,6 +6,7 @@ import type { Meta, StoryObj } from '@storybook/react'
 import { createColumnHelper } from '@tanstack/react-table'
 import { Select } from './select'
 import { Button } from '@/design-system/components/Button/button'
+import { Field, FieldLabel } from '@/design-system/components/Field/field'
 import { DataTable } from '@/design-system/components/DataTable/data-table'
 import '@/design-system/components/DataTable/column-types'
 
@@ -73,12 +74,12 @@ export const HugWidth: Story = {
     return (
       // 任務詳情右欄場景:label 上、hug 寬 select 下 — 框線互動與一般 field 完全相同,只有寬度依 value 收縮
       <div className="flex w-72 flex-col gap-[var(--layout-space-loose)]">
-        <div className="flex flex-col gap-1">{/* @layout-space-magic-ok: gap-1 = label↔control 4px 內距 demo */}
-          <span className="text-caption text-fg-secondary">Status</span>
+        <Field>
+          <FieldLabel>Status</FieldLabel>
           <Select width="hug" size="sm" options={statusOptions} value={status} onChange={setStatus} aria-label="Status(hug width demo)" />
-        </div>
-        <div className="flex flex-col gap-1">{/* @layout-space-magic-ok: gap-1 = label↔control 4px 內距 demo */}
-          <span className="text-caption text-fg-secondary">Priority</span>
+        </Field>
+        <Field>
+          <FieldLabel>Priority</FieldLabel>
           <Select
             width="hug"
             size="sm"
@@ -91,7 +92,7 @@ export const HugWidth: Story = {
             onChange={setPriority}
             aria-label="Priority(hug width demo)"
           />
-        </div>
+        </Field>
       </div>
     )
   },

package/src/components/Select/select.tsx

@@ -9,6 +9,9 @@ import type { FieldMode, FieldVariant, FieldVariantInternal, FieldWidth } from '
 import { fieldWrapperStyles, bareInputStyles, nakedCellRowModeAlign, fieldDisplayTextClass } from '@/design-system/components/Field/field-wrapper'
 import { Tag } from '@/design-system/components/Tag/tag'
 import { ItemInlineAction, ItemPrefix, ItemSuffix } from '@/design-system/patterns/element-anatomy/item-anatomy'
+import { TruncatedText } from '@/design-system/patterns/element-anatomy/truncated-text'
+import { Tooltip, TooltipContent, TooltipTrigger } from '@/design-system/components/Tooltip/tooltip'
+import { useTruncated } from '@/design-system/hooks/use-truncated'
 import { useFieldContext, useResolvedFieldSize, useResolvedFieldDisabled, useResolvedFieldMode, useResolvedFieldVariant, useResolvedFieldInvalid, useFieldEmptyDisplay, fieldEmptyColorClass } from '@/design-system/components/Field/field-context'
 import { SelectMenu, forwardKeyToListbox, useActiveDescendant, type SelectMenuOption } from '@/design-system/components/SelectMenu/select-menu'
 import { useIsTouchDevice } from '@/design-system/hooks/use-is-touch-device'
@@ -242,6 +245,7 @@ function CustomSelectTriggerContent({
   ariaLabel,
   labelId,
   selectedItemRenderer,
+  truncationRef,
 }: {
   searchable: boolean
   open: boolean
@@ -261,6 +265,8 @@ function CustomSelectTriggerContent({
   ariaLabel?: string
   labelId?: string
   selectedItemRenderer?: (selectedOpt: SelectOption) => React.ReactNode
+  /** 截斷 tooltip 量測點(text display 的值 span;tooltip trigger 在外層 combobox host,見 CustomSelect triggerTruncationRef 註解)*/
+  truncationRef?: React.Ref<HTMLSpanElement>
 }): React.ReactNode {
   // Searchable + open: 顯示搜尋 input
   // 2026-05-15 Bug 2 fix(Claude+Codex Step 5 比稿 consensus,user verbatim「就 A」):
@@ -332,7 +338,7 @@ function CustomSelectTriggerContent({
       <>
         {StartIcon && <ItemPrefix><StartIcon size={iconSize} className="text-fg-muted pointer-events-none" aria-hidden /></ItemPrefix>}
         {!StartIcon && SelectedIcon && value && <ItemPrefix><SelectedIcon size={iconSize} className="pointer-events-none" aria-hidden /></ItemPrefix>}
-        <span className={cn('flex-1 min-w-0 truncate', !value && 'text-fg-muted')}>
+        <span ref={truncationRef} className={cn('flex-1 min-w-0 truncate', !value && 'text-fg-muted')}>
           {value ? selectedLabel : (placeholder ?? '選擇…')}
         </span>
       </>
@@ -399,7 +405,9 @@ function ReadonlyDisplay({
           </span>
         )
       }
-      if (isTextDisplay) return <span className={cn(fieldDisplayTextClass(sz), 'truncate', className)}>{label}</span>
+      // 截斷必附 tooltip(tooltip.spec.md:32)— 改消費 truncated-text primitive(同 input.tsx:196 同型修;
+      // display='tag' 路徑由 Tag 內建 useTruncated 自管,text 路徑原本裸 truncate = gap)
+      if (isTextDisplay) return <TruncatedText className={cn(fieldDisplayTextClass(sz), className)}>{label}</TruncatedText>
       const tVariant = selectedOpt?.tagVariant as 'blue' | 'green' | 'red' | 'yellow' | 'neutral' | undefined
       return <Tag size={sz} color={tVariant} className={className}>{label}</Tag>
     }
@@ -416,9 +424,10 @@ function ReadonlyDisplay({
             {selectedItemRenderer(selectedOpt)}
           </span>
         ) : isTextDisplay ? (
-          <span className={cn(bareInputStyles, 'flex-1 min-w-0 truncate', !value && emptyColorCls)}>
+          // 截斷必附 tooltip(tooltip.spec.md:32;data-table.spec.md:183 view 態元件自管 truncation)
+          <TruncatedText className={cn(bareInputStyles, 'flex-1 min-w-0', !value && emptyColorCls)}>
             {value ? label : emptyText}
-          </span>
+          </TruncatedText>
         ) : value ? (
           <Tag size={sz} color={tVariant}>{label}</Tag>
         ) : (
@@ -457,9 +466,10 @@ function ReadonlyDisplay({
     return (
       <div className={cn(fieldWrapperStyles({ mode: resolvedMode, variant, width, size: sz }), className)} data-field-mode={resolvedMode} aria-disabled={ariaDisabled}>
         {StartIcon && <ItemPrefix><StartIcon size={iconSize} className={cn('pointer-events-none', iconColor)} aria-hidden /></ItemPrefix>}
-        <span className={cn('flex-1 min-w-0 truncate', resolvedMode === 'disabled' && 'text-fg-disabled')}>
+        {/* 截斷必附 tooltip(tooltip.spec.md:32)— readonly/disabled 無下拉入口,tooltip 是唯一補救路徑 */}
+        <TruncatedText className={cn('flex-1', resolvedMode === 'disabled' && 'text-fg-disabled')}>
           {value ? label : <span className={emptyColorCls}>{emptyText}</span>}
-        </span>
+        </TruncatedText>
         {showIndicator && <ItemSuffix className="pointer-events-none"><ChevronDown size={iconSize} className={cn('shrink-0', iconColor)} aria-hidden /></ItemSuffix>}
       </div>
     )
@@ -631,6 +641,17 @@ const CustomSelect = React.forwardRef<HTMLDivElement, SelectProps>(
     // 級 fallback `?? value`。
     const selectedLabel = selectedOpt?.label ?? value ?? ''
     const SelectedIcon = selectedOpt?.icon
+    // 截斷 tooltip(tooltip.spec.md:32 截斷 → 顯完整內容,僅實際截斷時):closed trigger text
+    // display 的值 span 是截斷元素;trigger = 整個 combobox host(interactive host,hover 直達)、
+    // 量測內層值 span — useTruncated 自組 pattern(truncated-text.spec.md「trigger 需自控」指定解;
+    // 範本 inline-edit.tsx:251。tag display 由 Tag 內建 useTruncated 自管,不經此路)。
+    // deps 含 open:searchable && open 切搜尋 input branch 時值 span 會 unmount,關閉重掛後
+    // effect 需重跑重新 observe(Tag always-wrap 教訓:RO 卡在 detached node → isTruncated 凍結)。
+    // hook 必在下方 resolvedMode early return 之前(React #310 hook-count 鐵律,見上方註解)。
+    const { ref: triggerTruncationRef, isTruncated: triggerTruncated } = useTruncated<HTMLSpanElement>({
+      deps: [open, isTextDisplay && value ? selectedLabel : ''],
+    })
+    const triggerTooltipActive = isTextDisplay && !!value && triggerTruncated && !open
     // ── 過濾選項 ──
     // 2026-07-18:filter 用 trim 過的 search,對齊 SelectMenu creatable 的 `search.trim()` create-row 判定 —
     //   否則尾隨空白(如 "Bug ")會讓 filter 漏掉完全同名選項、SelectMenu 卻誤判「無同名」提議重複建立。
@@ -748,6 +769,7 @@ const CustomSelect = React.forwardRef<HTMLDivElement, SelectProps>(
         ariaLabel={ariaLabel}
         labelId={fieldCtx?.labelId}
         selectedItemRenderer={selectedItemRenderer}
+        truncationRef={triggerTruncationRef}
       />
     )
 
@@ -828,29 +850,39 @@ const CustomSelect = React.forwardRef<HTMLDivElement, SelectProps>(
     )
 
     return (
-      <SelectMenu
-        options={menuOptions}
-        groups={groups}
-        value={value ?? null}
-        onValueChange={handleValueChange}
-        searchable={false}
-        creatable={creatable}
-        onCreate={onCreate}
-        createLabel={createLabel}
-        search={searchable ? search : undefined}
-        onSearchChange={searchable ? setSearch : undefined}
-        loading={loading}
-        emptyText={emptyText}
-        size={size}
-        minRows={minRows}
-        open={open}
-        onOpenChange={(o) => { setOpen(o); onOpenChange?.(o) }}
-        contentId={listboxId}
-        renderLabel={renderLabel}
-        onOpenAutoFocus={searchable ? (e) => { e.preventDefault(); inputRef.current?.focus() } : undefined}
-      >
-        {trigger}
-      </SelectMenu>
+      // 截斷 tooltip:恆 wrap(truncated-text.spec.md always-wrap),未截斷或選單開啟時 open={false}
+      // 靜默。TooltipTrigger 放 SelectMenu 的 PopoverTrigger asChild 內側(緊貼 trigger div):
+      // PopoverTrigger 注入的 data-state(Field open 邊框樣式依賴)在 TooltipTrigger 內以
+      // triggerProps 後 spread 勝出;反序會被 tooltip 的 data-state 蓋掉。Tooltip root / Content
+      // 都不產 DOM(Content portal),SelectMenu children 結構與佈局不變。
+      <Tooltip open={triggerTooltipActive ? undefined : false}>
+        <SelectMenu
+          options={menuOptions}
+          groups={groups}
+          value={value ?? null}
+          onValueChange={handleValueChange}
+          searchable={false}
+          creatable={creatable}
+          onCreate={onCreate}
+          createLabel={createLabel}
+          search={searchable ? search : undefined}
+          onSearchChange={searchable ? setSearch : undefined}
+          loading={loading}
+          emptyText={emptyText}
+          size={size}
+          minRows={minRows}
+          open={open}
+          onOpenChange={(o) => { setOpen(o); onOpenChange?.(o) }}
+          contentId={listboxId}
+          renderLabel={renderLabel}
+          onOpenAutoFocus={searchable ? (e) => { e.preventDefault(); inputRef.current?.focus() } : undefined}
+        >
+          <TooltipTrigger asChild>
+            {trigger}
+          </TooltipTrigger>
+        </SelectMenu>
+        <TooltipContent>{triggerTooltipActive ? selectedLabel : null}</TooltipContent>
+      </Tooltip>
     )
   }
 )

package/src/components/SelectMenu/select-menu.spec.md

@@ -213,7 +213,7 @@ SelectMenu 是 **composite**(Popover trigger + Command search + 滾動 MenuItem
 
 ## A11y 預設
 
-**ARIA / Pattern**:基於 `cmdk` library a11y(combobox / listbox / option role + aria-activedescendant)。詳 [cmdk a11y](https://cmdk.paco.me/#accessibility)。選項 row 的內層 `MenuItem` 傳 `role="presentation"`(cmdk CommandItem 是唯一 option 節點,避免 option 巢狀 option + 內外 `aria-selected` 語意相反;鏡射 DropdownMenu canonical,2026-07-05 D4)。分組標題走 cmdk `CommandGroup heading`(自動產 `cmdk-group-heading` id,選項容器 `role="group"` + `aria-labelledby` 指向之,AT 可感知);combobox accessible name 來自 `Command label`(= `searchPlaceholder`,僅 searchable 時傳),listbox 容器經 cmdk `List label` 預設「選項」取代 cmdk 內建英文 "Suggestions"(2026-07-06)。多選 footer 全選列為 `role="checkbox"` + `aria-checked`(indeterminate → `"mixed"`)。空狀態 / loading 經 visually-hidden `role="status"` + `aria-live="polite"` live region 對 SR 播報(cmdk CommandEmpty 是 `role="presentation"`,SR 原本聽不到;2026-07-05 D4)。
+**ARIA / Pattern**:基於 `cmdk` library a11y(combobox / listbox / option role + aria-activedescendant)。詳 [cmdk a11y](https://cmdk.paco.me/#accessibility)。選項 row 的內層 `MenuItem` 傳 `role="presentation"`(cmdk CommandItem 是唯一 option 節點,避免 option 巢狀 option + 內外 `aria-selected` 語意相反;鏡射 DropdownMenu canonical,2026-07-05 D4)。分組標題走 cmdk `CommandGroup heading`(自動產 `cmdk-group-heading` id,選項容器 `role="group"` + `aria-labelledby` 指向之,AT 可感知);combobox accessible name 來自 `Command label`(= `searchAriaLabel`,default「搜尋選項」,僅 searchable 時傳)，與可見 `searchPlaceholder` 分離；listbox 容器經 cmdk `List label` 預設「選項」取代 cmdk 內建英文 "Suggestions"(2026-07-06)。多選 footer 全選列為 `role="checkbox"` + `aria-checked`(indeterminate → `"mixed"`)。空狀態 / loading 經 visually-hidden `role="status"` + `aria-live="polite"` live region 對 SR 播報(cmdk CommandEmpty 是 `role="presentation"`,SR 原本聽不到;2026-07-05 D4)。
 
 **Keyboard 行為**:
 

package/src/components/SelectMenu/select-menu.tsx

@@ -95,6 +95,8 @@ export interface SelectMenuProps {
   children: React.ReactNode
   /** 搜尋框 placeholder */
   searchPlaceholder?: string
+  /** 搜尋框 accessible name；與可見 placeholder 分離。 */
+  searchAriaLabel?: string
   /** 空選項提示 */
   emptyText?: string
   /** 多選 footer 全選列文字(2026-07-05 D4:原「全部」字面 hardcode,無法覆寫也無法 i18n) */
@@ -183,6 +185,7 @@ const SelectMenu = React.forwardRef<HTMLElement, SelectMenuProps>(function Selec
   onSearchChange,
   children,
   searchPlaceholder = '搜尋…', // i18n-allow: DS default; consumer override via searchPlaceholder prop
+  searchAriaLabel = '搜尋選項', // i18n-allow: DS default; consumer override via searchAriaLabel prop
   emptyText = '沒有符合的選項', // i18n-allow: DS default; consumer override via emptyText prop
   selectAllLabel = '全部', // i18n-allow: DS default; consumer override via selectAllLabel prop
   loading = false,
@@ -394,7 +397,7 @@ const SelectMenu = React.forwardRef<HTMLElement, SelectMenuProps>(function Selec
           // 不存在的 input」仍存在(upstream cmdk 限制;空 label 無 accessible name,不產生朗讀
           // 內容)。僅 searchable(真的有 input)時傳內容 = 避免 non-searchable 帶 search
           // placeholder 的 accessible name 卻無對應 input;真要消除 orphan label 需 upstream 修。
-          label={searchable ? searchPlaceholder : undefined}
+          label={searchable ? searchAriaLabel : undefined}
           className="bg-transparent"
         >
           {searchable && (

package/src/components/SelectionControl/selection-item.anatomy.stories.tsx

@@ -83,7 +83,7 @@ export const Overview: Story = {
         </Desc>
         <div className="border border-divider rounded-md p-4 bg-muted max-w-xl">
           <SelectionItem
-            control={<Checkbox defaultChecked />}
+            control={<Checkbox defaultChecked aria-label="讀取 email 信箱" />}
             icon={Mail}
             label="讀取 email 信箱"
             description="僅用於通知,永遠不會外流"
@@ -246,7 +246,14 @@ function SelectionInspector() {
           <div className="border border-divider rounded-md p-4 bg-muted">
             <SelectionItem
               size={size}
-              control={<Checkbox size={size} defaultChecked disabled={disabled} />}
+              control={
+                <Checkbox
+                  size={size}
+                  defaultChecked
+                  disabled={disabled}
+                  aria-label="Admin 層級操作"
+                />
+              }
               icon={prefix === 'icon' ? Shield : undefined}
               avatar={prefix === 'avatar' ? { alt: 'Ada Chen', color: 'indigo' } : undefined}
               label="Admin 層級操作"
@@ -438,7 +445,7 @@ export const PrefixAlignment: Story = {
             </span>
             <div className="border border-divider rounded-md p-4 bg-muted">
               <SelectionItem
-                control={<Checkbox defaultChecked />}
+                control={<Checkbox defaultChecked aria-label="選取 Ada Chen（單行）" />}
                 avatar={{ src: 'https://i.pravatar.cc/48?u=ada-chen', alt: 'Ada Chen', color: 'indigo' }}
                 label="Ada Chen"
               />
@@ -450,7 +457,7 @@ export const PrefixAlignment: Story = {
             </span>
             <div className="border border-divider rounded-md p-4 bg-muted">
               <SelectionItem
-                control={<Checkbox defaultChecked />}
+                control={<Checkbox defaultChecked aria-label="選取 Ada Chen（含職稱）" />}
                 avatar={{ src: 'https://i.pravatar.cc/64?u=ada-chen', alt: 'Ada Chen', color: 'indigo' }}
                 label="Ada Chen"
                 description="Design Engineer · Frontend team"
@@ -467,11 +474,15 @@ export const PrefixAlignment: Story = {
         </Desc>
         <div className="grid grid-cols-2 gap-6 max-w-4xl">
           <div className="border border-divider rounded-md p-4 bg-muted">
-            <SelectionItem control={<Checkbox defaultChecked />} icon={Folder} label="存取 Drive 檔案" />
+            <SelectionItem
+              control={<Checkbox defaultChecked aria-label="存取 Drive 檔案（單行）" />}
+              icon={Folder}
+              label="存取 Drive 檔案"
+            />
           </div>
           <div className="border border-divider rounded-md p-4 bg-muted">
             <SelectionItem
-              control={<Checkbox defaultChecked />}
+              control={<Checkbox defaultChecked aria-label="存取 Drive 檔案（含說明）" />}
               icon={Folder}
               label="存取 Drive 檔案"
               description="讀取並修改你授權的資料夾"
@@ -538,13 +549,13 @@ export const SizeMatrix: Story = {
               <div className="border border-divider rounded-md bg-muted flex flex-col">
                 <SelectionItem
                   size={s}
-                  control={<Checkbox size={s} defaultChecked />}
+                  control={<Checkbox size={s} defaultChecked aria-label={`${s} 尺寸產品更新電子報`} />}
                   icon={Mail}
                   label="產品更新電子報"
                 />
                 <SelectionItem
                   size={s}
-                  control={<Checkbox size={s} />}
+                  control={<Checkbox size={s} aria-label={`${s} 尺寸安全性警告`} />}
                   icon={Shield}
                   label="安全性警告"
                   description="登入裝置變動、密碼變更等重要事件"

package/src/components/SelectionControl/selection-item.stories.tsx

@@ -73,24 +73,24 @@ export const WithPrefixIcon: Story = {
         Figma-like permission scope picker — control + icon(24px 閾值內 inline)+ label + description。
       </p>
       <SelectionItem
-        control={<Checkbox defaultChecked />}
+        control={<Checkbox defaultChecked aria-label="讀取 email 信箱" />}
         icon={Mail}
         label="讀取 email 信箱"
         description="僅用於通知,永遠不會外流"
       />
       <SelectionItem
-        control={<Checkbox />}
+        control={<Checkbox aria-label="存取 Drive 檔案" />}
         icon={Folder}
         label="存取 Drive 檔案"
         description="讀取並修改你授權的資料夾"
       />
       <SelectionItem
-        control={<Checkbox defaultChecked />}
+        control={<Checkbox defaultChecked aria-label="推播通知權限" />}
         icon={Bell}
         label="推播通知權限"
       />
       <SelectionItem
-        control={<Checkbox />}
+        control={<Checkbox aria-label="Admin 層級操作" />}
         icon={Shield}
         label="Admin 層級操作"
         description="僅限 workspace owner 開啟"
@@ -113,19 +113,19 @@ export const WithPrefixAvatarBlock: Story = {
         role。
       </p>
       <SelectionItem
-        control={<Checkbox defaultChecked />}
+        control={<Checkbox defaultChecked aria-label="選取 Ada Chen" />}
         avatar={{ src: 'https://i.pravatar.cc/64?u=ada-chen', alt: 'Ada Chen', color: 'indigo' }}
         label="Ada Chen"
         description="Design Engineer · Frontend team"
       />
       <SelectionItem
-        control={<Checkbox />}
+        control={<Checkbox aria-label="選取張美真" />}
         avatar={{ src: 'https://i.pravatar.cc/64?u=zhang-meizhen', alt: '張美真', color: 'magenta' }}
         label="張美真"
         description="Product Designer · Platform team"
       />
       <SelectionItem
-        control={<Checkbox defaultChecked />}
+        control={<Checkbox defaultChecked aria-label="選取林伯彥" />}
         avatar={{ src: 'https://i.pravatar.cc/64?u=lin-boyan', alt: '林伯彥', color: 'green' }}
         label="林伯彥"
         description="Staff Engineer · Infra team"

package/src/components/Sheet/sheet.spec.md

@@ -108,7 +108,7 @@ Sheet 為容器,內容由 consumer 決定;focus trap + Escape close + `aria-labe
 - **Empty(no content)**:Sheet 必含 title(`aria-labelledby` 強制要求);body 為空時 consumer 應渲 `<Empty>` placeholder,不渲空白 panel。
 - **Scroll(body 內容超過視口高度)**:`SheetBody` = `<ScrollArea>`(`flex-1 min-h-0`),超高內容在 body 內部捲動,header / footer 固定不動;consumer 不需自寫 `overflow-y-auto`。
 - **誤嵌套降級(nested Sheet)**:禁止事項已禁 nested;若 consumer 不慎嵌套,Radix 的 Esc 與 focus trap 只作用於**最上層** layer(DismissableLayer 只 dismiss highest layer;FocusScope stack 最新 scope active),關閉由上而下逐層。
-- **RTL**:`side` 為物理方向(`right-0` 物理定位),不隨 `dir="rtl"` 自動鏡像。
+- **RTL**:不支援；全域 LTR-only compatibility contract 見 `packages/design-system/README.md#compatibility-matrix`。`side` 維持 physical direction。
 - **Dark mode**:overlay-surface SSOT 自動 adapt(`overlay-surface.spec.md`);Sheet 不獨立 own dark token。
 - **Density**:Sheet body density 由 consumer 控(若內含 form / DataTable / Menu 各自有 density 規則);Sheet container 自身不持 density。