@qijenchen/design-system 0.1.0-beta.111 → 0.1.0-beta.113

package/src/components/Combobox/combobox.tsx

@@ -18,6 +18,15 @@ import { ICON_SIZE } from '@/design-system/tokens/uiSize/icon-size'
 
 const GAP = 4
 
+// 非-wrap tag 列 clip SSOT(4-path 共用:OverflowTagList base / readonly / native edit / custom edit):
+// 2026-05-18 F2 以 overflow-hidden 修「窄容器 tags 水平越界蓋 chevron / +N」,但雙軸 hidden 副作用
+// 是垂直同裁 — PeoplePicker stack hover 的 AvatarDismissOverlay(`-top-px` + 2px ring,
+// person-display.tsx v15.15,早於 F2)上緣被切(user 2026-08-05 抓「曾經沒有這問題」= F2 前確實沒有)。
+// 雙贏 = overflow-x-clip:水平維持 clip(F2 bug 不回歸;`clip` 不建 scroll container),垂直 visible
+// (overlay / avatar ring 完整)。**不可**改 overflow-x-hidden:單軸 hidden 令另一軸 visible 計算成
+// auto → 生 scroll container,垂直反而可捲。
+const tagRowOverflowClass = 'overflow-x-clip'
+
 const tagPadding: Record<string, string> = {
   sm: 'px-[calc((var(--field-height-sm)_-_1.25rem)_/_2)]',
   md: 'px-[calc((var(--field-height-md)_-_1.5rem)_/_2)]',
@@ -355,7 +364,7 @@ function ComboboxTagStack({
   // `data-table.spec.md:233`「禁硬裁無 ellipsis」+ MUI X / Ant Table column.ellipsis 共識。
   // (2026-05-14 nakedCellRowModeAlign 同保留 — autoRowHeight cell first-line align canonical。)
   return (
-    <div ref={ownRef} className={cn('flex-1 min-w-0 flex items-center', nakedCellRowModeAlign, wrap ? 'flex-wrap' : 'overflow-hidden')} style={{ gap: GAP }}>
+    <div ref={ownRef} className={cn('flex-1 min-w-0 flex items-center', nakedCellRowModeAlign, wrap ? 'flex-wrap' : tagRowOverflowClass)} style={{ gap: GAP }}>
       {content}
     </div>
   )
@@ -551,7 +560,7 @@ function ReadonlyMultiSelect({
         // M10 propagation:原 overflow-visible 讓 readonly tag 越界蓋 indicator,跟 view 不對稱。
         // 2026-06-27 對齊 edit path(L598-617):wrap 時 items-start + chevron self-start/tagHeight 鎖第一行;
         // paddingRight: var(--field-px) re-assert 右緣 12px(tagPadding 對稱 calc 會吃掉右緣,跟 edit 一致)。
-        wrap ? 'flex-wrap items-start py-1' : 'overflow-hidden', className)}
+        wrap ? 'flex-wrap items-start py-1' : tagRowOverflowClass, className)}
       style={{ gap: GAP, paddingRight: 'var(--field-px)', ...(wrap ? { height: 'auto' } : undefined) }} data-field-mode={resolvedMode}
       aria-disabled={resolvedMode === 'disabled' ? true : undefined}>
       {hasTags ? (
@@ -614,6 +623,11 @@ function focusAfterTagRemoval(container: HTMLElement | null, owner: HTMLElement
 function NativeCombobox({
   mode, variant: variantProp, width, error = false, size = 'md', options, value = [], onChange, placeholder,
   className, disabled: disabledProp, wrap = false, clearable = false, showDisplayEndIcon = false,
+  // Display-layer parity(2026-08-05 user 拍板):renderer / overflow props 必雙分支(custom/native)
+  // 同消費 — 原 native 硬編碼 <Tag> 令 PeoplePicker 手機 edit 掉回文字 pill、avatar stack 全滅
+  // (touch 分支從未接 display 層的病根)。新增 renderer-affecting prop 時必同步本 destructure。
+  tagRenderer, renderHiddenTag, tagWrapperClassName, overflowWrapperClassName,
+  overflowShape, visibleCountOverride, tagAreaGapPx, tagAreaPaddingLeftPx,
   __triggerRef,
   'aria-label': ariaLabel,
 }: ComboboxInternalProps) {
@@ -646,6 +660,7 @@ function NativeCombobox({
   const items = value.map(v => ({ value: v, label: options.find(o => o.value === v)?.label ?? v }))
   const unselected = options.filter(o => !value.includes(o.value))
   const tagHeight = size === 'sm' ? 20 : 24
+  const tagAreaGap = tagAreaGapPx ?? GAP
 
   const selectDropdown = unselected.length > 0 ? (
     <select ref={selectRef} value="" onChange={(e) => handleAdd(e.target.value)}
@@ -675,13 +690,33 @@ function NativeCombobox({
           edit path tagArea 對齊 view path L293 已 ship 的 `overflow-hidden` fix。原 `overflow-visible`
           讓 tag 視覺越界蓋 chevron / +N indicator(useOverflowCount measurement 對但 CSS overflow 仍露)。
           M10 violation root cause:2026-05-15 F1 Q3 只 fix display path,edit + Native(L518)沒同步。 */}
-      <div ref={tagAreaRef} className={cn('flex-1 min-w-0 flex items-center relative', nakedCellRowModeAlign, wrap ? 'flex-wrap' : 'overflow-hidden')} style={{ gap: GAP }}
+      {/* Display-layer parity(2026-08-05):OverflowTagList 消費與 CustomCombobox(L859-867)同一組
+          renderer / overflow props — tagRenderer 存在(PeoplePicker avatar stack 等)→ 手機 edit 與
+          桌機同視覺;未傳 → 原 <Tag> 文字 pill 預設不變。 */}
+      <div ref={tagAreaRef} className={cn('flex-1 min-w-0 flex items-center relative', nakedCellRowModeAlign, wrap ? 'flex-wrap' : tagRowOverflowClass)} style={{ gap: tagAreaGap, paddingLeft: tagAreaPaddingLeftPx }}
         onClick={(e) => { if (e.target === e.currentTarget) { selectRef.current?.showPicker?.(); selectRef.current?.focus() } }}>
         <OverflowTagList containerRef={tagAreaRef} items={items} size={size} wrap={wrap}
+          tagWrapperClassName={tagWrapperClassName}
+          // Review fix(2026-08-05 F2):+N 抬到 overlay 上(可見不被壓)且 pointer 穿透 —
+          // touch 無 hover 開不了 HoverCard,tap 穿透開原生 picker(原生多選單列全員含 hidden,
+          // 即 touch 的 overflow 檢視/增刪路徑)。桌機 CustomCombobox 呼叫端不變。
+          overflowWrapperClassName={cn(overflowWrapperClassName, 'relative z-10 pointer-events-none')}
+          gap={tagAreaGap}
+          overflowShape={overflowShape}
+          visibleCountOverride={visibleCountOverride}
           renderTag={(item) => (
-            <Tag size={size} className="shrink-0 relative z-10" onClick={() => { selectRef.current?.showPicker?.(); selectRef.current?.focus() }}
-              onRemove={() => handleRemove(item.value)}>{item.label}</Tag>
-          )} onRemove={handleRemove} trailing={value.length === 0 ? selectDropdown : undefined} />
+            tagRenderer
+              // Review fix(2026-08-05 F1/F3):renderer 輸出必套「抬升+穿透+按鈕回收」三件套 —
+              // relative z-10 抬到透明 native <select> overlay(z-0)之上(對齊 default <Tag> 的
+              // z-10;wrap 分支 OverflowTagList 無 wrapper div 時尤其必要);pointer-events-none 讓
+              // 非互動顯示區 tap 穿透 overlay(spec「點擊任何位置喚起原生 picker」);[&_button]:auto
+              // 回收 remove X / Tag onRemove 點擊。
+              ? <span className="relative z-10 min-w-0 flex-1 inline-flex items-center pointer-events-none [&_button]:pointer-events-auto">{tagRenderer(item, () => handleRemove(item.value))}</span>
+              : <Tag size={size} className="shrink-0 relative z-10" onClick={() => { selectRef.current?.showPicker?.(); selectRef.current?.focus() }}
+                  onRemove={() => handleRemove(item.value)}>{item.label}</Tag>
+          )}
+          renderHiddenTag={renderHiddenTag}
+          onRemove={handleRemove} trailing={value.length === 0 ? selectDropdown : undefined} />
       </div>
       {value.length > 0 && selectDropdown}
       <ItemSuffix className={cn('relative z-10 pointer-events-none', wrap && 'self-start')}
@@ -844,7 +879,7 @@ function CustomCombobox({
       {/* 2026-05-18 #6A Round 1 Step 2/4(per user 拍板「決策6選a」+ codex M31 Step 5 verdict cite combobox.tsx:648):
           CustomCombobox edit non-wrap tagArea 對齊 L293 view + L451 readonly + L518 native edit 已 ship 的 overflow-hidden fix。
           原 overflow-visible 讓 tag 越界蓋 chevron / +N indicator(user 圖三)。M10 propagation 完整 4-path align。 */}
-      <div ref={tagAreaRef} className={cn('flex-1 min-w-0 flex items-center relative', nakedCellRowModeAlign, wrap ? 'flex-wrap' : 'overflow-hidden')} style={{ gap: tagAreaGap, paddingLeft: tagAreaPaddingLeftPx }}>
+      <div ref={tagAreaRef} className={cn('flex-1 min-w-0 flex items-center relative', nakedCellRowModeAlign, wrap ? 'flex-wrap' : tagRowOverflowClass)} style={{ gap: tagAreaGap, paddingLeft: tagAreaPaddingLeftPx }}>
         {value.length > 0 ? (
           <OverflowTagList containerRef={tagAreaRef} items={items} size={size} wrap={wrap}
             tagWrapperClassName={tagWrapperClassName}

package/src/components/Field/field.spec.md

@@ -59,6 +59,16 @@ Field 和 Field Controls（Input / NumberInput / DatePicker / Select / Combobox
 
 子元件寫法採**扁平結構**（直接作為 Field children），Field 內部用 `displayName` 判別 slot 類型並自動組合。consumer 不需要包 wrapper。
 
+### Field 次要 action 的預留位置（canonical,尚未實作）
+
+Field 若需要次要 action（如「重設」「全選」「從範本帶入」），**唯一預留位置 = label 行最右端**（label 與 action 兩端對齊）：
+
+- 形式：超連結樣文字（link-like text），**字級與行高皆同 FieldLabel**（`text-body` 14px、同 label 的 leading）——同字級同行高即天然等高，這是「不增高」的機制核心（user 2026-08-05 確認）。
+- 硬約束：**不得增加 label 行高度**（避免 field 被撐高）。等高機制之外還需三個盒模型條件缺一不可：(1) **零垂直 padding、無固定高度盒**——禁用 DS `Button`（xs 也自帶 `h-field-xs` 固定盒 + 自身 leading，`button.tsx` xs variant），必須是純文字元素；(2) **單行 `whitespace-nowrap`**（換行即行盒 ×2）；(3) **hit target 以 pseudo-element／負 margin 擴大**，不得用 padding 滿足 a11y 觸控目標（underline／focus ring 不佔佈局，無礙）。
+- 此位置是 field 次要 action 的**專屬 slot**——禁止把次要 action 放在 control 下方、error 位置或 field 外圍（那些位置屬 description/error/表單層動作）。
+- 對齊世界級：Polaris TextField `labelAction`（https://polaris.shopify.com/components/selection-and-input/text-field 的「With label action」example；2026-08-05 WebFetch 驗證 prop 存在）。
+- 狀態：**2026-08-05 user 拍板記錄,尚未實作**。實作時走 `<FieldLabelAction>` 類 slot + `/component-quality-gate`；在那之前任何 story/產品範例**不得**自行發明次要 action 擺位（anchor：PeoplePicker 多人 story 曾把 play() 測試用「重設協作者」按鈕誤植為 control 下方的產品 UI,2026-08-05 移除）。
+
 ---
 
 ## 樣式規範（全部 codify 在 field.tsx，不依賴 consumer）

package/src/components/FileUpload/file-upload.stories.tsx

@@ -85,9 +85,7 @@ export const BulkImageUpload = {
 // 不傳 `files` 則自動回 pre-2026-04-24 consumer-composed pattern(無須 story 示範「不傳 prop」)。
 
 // 2026-04-24 canonical:內建 `files` prop — FileUpload own success state display
-export const WithFileList = {
-  name: '內建 files 屬性',
-  render: () => {
+const FileListDemo = () => {
     type UploadItem = { id: string; name: string; size?: number; status?: 'uploading' | 'completed' | 'error'; progress?: number; description?: string }
     const [items, setItems] = useState<UploadItem[]>([
       { id: '1', name: '2026-Q1-report.pdf', size: 2_500_000, status: 'completed' },
@@ -118,7 +116,20 @@ export const WithFileList = {
         />
       </div>
     )
-  },
+}
+
+export const WithFileList = {
+  name: '內建 files 屬性',
+  render: () => <FileListDemo />,
+}
+
+// Roving-focus 契約 probe:移除檔案後焦點落到下一個移除鈕。破壞性互動(移除
+// 檔案)只屬測試,不得寄生在 reader-facing 展示 story(同 PeoplePicker
+// 2026-08-05 anchor;story-rules「Technical probe visibility」canonical)。
+export const FileListRemoveFocusContract = {
+  name: '移除焦點接力驗證',
+  tags: ['test-only'],
+  render: () => <FileListDemo />,
   play: async ({ canvasElement }: { canvasElement: HTMLElement }) => {
     const canvas = within(canvasElement)
     await userEvent.click(await canvas.findByRole('button', { name: '移除 2026-Q1-report.pdf' }))

package/src/components/PeoplePicker/people-picker.spec.md

@@ -81,6 +81,18 @@ PeoplePicker 永遠支援搜尋（內部使用 `Command` / cmdk）——因為
 
 ---
 
+## 一鍵清空(clearable)
+
+`clearable`(2026-08-05 加)機械轉發 wrapped Select(single)/ Combobox(multi)——X 的渲染、位置與清空行為 SSOT 在基座與 family canonical,本元件不另定義:
+
+- **幾何**:有值時 clear X 在 ChevronDown 左(`../Field/field-controls.spec.md`「下拉箭頭與類型身份 indicator」段)
+- **單選**:清除後回 placeholder 態(`../Select/select.spec.md`「Clearable」);wrapper 把基座 clear 的空字串映射為 `onChange([])`,不進 people 回查(fallback 會產生空名假人員)
+- **多選**:clear all 一次清除所有已選人員(`../Combobox/combobox.spec.md`「全部清除」),與 per-chip 移除並存
+- **何時開**:繼承 select.spec.md「何時開 clearable」判準——「無選擇是有效狀態」(選填人員欄位如觀察者 / 可清的人員 filter)開;必須有人(assignee 必填)不開
+- 只在 edit 模式顯示;readonly / disabled 不渲(基座行為)
+
+---
+
 ## 與 Select / Combobox 的分界
 
 | | PeoplePicker | Select | Combobox |
@@ -183,6 +195,18 @@ PeoplePicker 永遠支援搜尋（內部使用 `Command` / cmdk）——因為
 
 ---
 
+## 觸控裝置(native 分支)
+
+觸控裝置(`(pointer: coarse)`,`use-is-touch-device.ts`)上 wrapped Select / Combobox 切至 native 分支(下拉 = 原生 `<select>` picker)。**Display 層與桌機同 SSOT — 「Trigger display SSOT canonical table」§B-§D 對觸控同樣成立**(2026-08-05 user 拍板;先前 native 分支硬編碼純文字/文字 Tag,手機 edit 單人無 avatar、多人掉回矩形 pill = canonical 違反,已修):
+
+- **單人 edit**:avatar + 人名(`selectedItemRenderer` 經 NativeSelect 透明 overlay pattern,見 `select.spec.md`「雙分支同 SSOT」);無 inline search,tap 開原生選單
+- **多人 edit → 自動降階 pill(2026-08-05 user 拍板)**:觸控多選一律走既有 `multiDisplay='pill'`(**不是新型態**:Combobox tag SSOT + Tag `avatar` prop,見「多選顯示樣式(multiDisplay)」),每顆 pill 自帶 X = Combobox「個別移除」canonical。**理由**:stack 的移除鈕是 hover-reveal,觸控無 hover;而讓每個 avatar 恆顯 X 視覺過載(user 否決前一版)。consumer 顯式傳 `'pill'` 時此降階為 no-op;**桌機(fine pointer)完全不受影響** — 仍是 avatar stack + 圓形 +N + hover X。實作 `people-picker.tsx` `effectiveMultiDisplay`(`useIsTouchDevice`)
+- **顯示層 pointer 契約**:renderer 輸出套「抬升 z-10 + pointer-events-none + 按鈕 `[&_button]` 回收」三件套(NativeCombobox 消費同一組 display props,見 `combobox.spec.md`「Display 層雙分支同 SSOT」)— pill 本體 tap 穿透喚起原生 picker(新增成員),pill 上的 X 照常可點(移除成員)
+- **選單**:觸控走原生 `<select>` picker(Combobox 觸控 SSOT,平台 a11y 最佳);原生選項無法渲 avatar 屬平台限制,桌機選單維持 PeoplePicker avatar + description 選項不變
+- 一鍵清空 X(`clearable`)由基座 native 分支自行渲染,觸控同樣可用
+
+---
+
 ## PersonValue 型別
 
 ```tsx

package/src/components/PeoplePicker/people-picker.stories.tsx

@@ -122,7 +122,6 @@ const MultiPicker = () => {
       <div>
         <h3 className="text-body font-bold text-foreground mb-2">edit（可互動,多選）</h3>
         <PeoplePicker value={val} people={samplePeople} onChange={setVal} aria-label="專案協作者(edit multi demo)" />
-        <Button variant="text" size="xs" onClick={() => setVal(samplePeople.slice(0, 4))}>重設協作者</Button>
       </div>
       <div>
         <h3 className="text-body font-bold text-foreground mb-2">readonly</h3>
@@ -135,6 +134,17 @@ const MultiPicker = () => {
 export const Multi: Story = {
   name: '多人',
   render: () => <MultiPicker />,
+}
+
+// Roving-focus 契約 probe:逐一移除 chip 時焦點依序落到下一個移除鈕,移除
+// 最後一人後回到 combobox。破壞性互動(清空全員)只屬測試,不得寄生在
+// reader-facing 展示 story(anchor:2026-08-05 user 抓「多人一打開就自己清空」;
+// 前身還為此加過「重設協作者」假 UI,ccf83b24)。story-rules「Technical probe
+// visibility」canonical:標 test-only,自 sidebar/Autodocs 排除,test runner 照跑。
+export const MultiRemoveFocusContract: Story = {
+  name: '移除焦點接力驗證',
+  tags: ['test-only'],
+  render: () => <MultiPicker />,
   play: async ({ canvasElement }) => {
     const canvas = within(canvasElement)
     await userEvent.click(await canvas.findByRole('button', { name: '移除 Alice Chen' }))
@@ -145,10 +155,49 @@ export const Multi: Story = {
     await waitFor(() => expect(canvas.getByRole('button', { name: '移除 Diana Huang' })).toHaveFocus())
     await userEvent.click(canvas.getByRole('button', { name: '移除 Diana Huang' }))
     await waitFor(() => expect(canvas.getByRole('combobox', { name: '專案協作者(edit multi demo)' })).toHaveFocus())
-    await userEvent.click(canvas.getByRole('button', { name: '重設協作者' }))
   },
 }
 
+// Stack 移除鈕完整性 probe:AvatarDismissOverlay(`-top-px` + 2px ring,person-display.tsx)
+// 必須完整可見,不被 tag 列裁切(combobox.tsx tagRowOverflowClass 只裁水平;anchor:2026-08-05
+// user 抓「hover X 上緣被裁」— 2026-05-18 F2 雙軸 overflow-hidden 副作用)。screenshot lane
+// 無 hover 能力,以 keyboard focus 觸發 group-focus-within 顯示 overlay。
+export const StackRemoveOverlayProbe: Story = {
+  name: '移除鈕完整性驗證',
+  tags: ['test-only'],
+  render: () => <MultiPicker />,
+  play: async ({ canvasElement }) => {
+    const canvas = within(canvasElement)
+    const btn = await canvas.findByRole('button', { name: '移除 Alice Chen' })
+    btn.focus()
+  },
+}
+
+/* ── 一鍵清空(選填欄位) ── */
+// X 在 ChevronDown 左(family SSOT field-controls.spec.md「下拉箭頭」段)。「無選擇是有效
+// 狀態」的選填欄位才開 clearable(select.spec.md「何時開」)——代理人 / 觀察者是典型選填人員欄位。
+const ClearablePicker = () => {
+  const [delegate, setDelegate] = React.useState<PersonValue | null>(samplePeople[1])
+  const [watchers, setWatchers] = React.useState<PersonValue[]>(samplePeople.slice(2, 5))
+  return (
+    <div className="flex flex-col gap-6 max-w-xs">
+      <div>
+        <h3 className="text-body font-bold text-foreground mb-2">單人(代理人,選填)</h3>
+        <PeoplePicker clearable value={delegate} people={samplePeople} onChange={(v) => setDelegate(v[0] ?? null)} aria-label="代理人(選填)" />
+      </div>
+      <div>
+        <h3 className="text-body font-bold text-foreground mb-2">多人(觀察者,選填)</h3>
+        <PeoplePicker clearable value={watchers} people={samplePeople} onChange={setWatchers} aria-label="觀察者(選填)" />
+      </div>
+    </div>
+  )
+}
+
+export const Clearable: Story = {
+  name: '一鍵清空(選填欄位)',
+  render: () => <ClearablePicker />,
+}
+
 /* ── 尺寸與 Button 對齊 ── */
 const SizePicker = ({ size }: { size: 'sm' | 'md' | 'lg' }) => {
   const [val, setVal] = React.useState<PersonValue | null>(samplePeople[0])

package/src/components/PeoplePicker/people-picker.tsx

@@ -38,6 +38,7 @@ import {
   findPerson,
 } from './people-picker-helpers'
 import { ICON_SIZE } from '@/design-system/tokens/uiSize/icon-size'
+import { useIsTouchDevice } from '@/design-system/hooks/use-is-touch-device'
 export { PEOPLE_PICKER_LENGTH1_WRAPPER_CLASS, getPeoplePickerTagWrapperClass }
 
 // ── PeoplePicker ────────────────────────────────────────────────────────────
@@ -118,6 +119,13 @@ export interface PeoplePickerProps extends Omit<React.HTMLAttributes<HTMLDivElem
    * Single mode 永遠 inline-trigger(wrap Select searchable 直接走 inline),此 prop multi 才有意義。
    */
   searchIn?: 'menu' | 'trigger'
+  /**
+   * 一鍵清空(2026-08-05):X 在 ChevronDown 左,family SSOT → field-controls.spec.md「下拉箭頭」段。
+   * 機械轉發 wrapped Select(single)/ Combobox(multi)的 `clearable` — X 渲染與清空行為 SSOT 在基座
+   * (SelectClearButton / Combobox clear),本 wrapper 不另 render。何時開的判準繼承 select.spec.md
+   * 「Clearable」:「無選擇是有效狀態」(選填欄位 / 可清 filter)才開;必填欄位不開。
+   */
+  clearable?: boolean
   /**
    * View 態是否渲 ChevronDown + Field naked wrapper(D-path opt-in,2026-05-08)
    * — DataTable cell view↔edit 像素級對齊用。預設 false(裸 PersonDisplay,backward compat)。
@@ -149,6 +157,7 @@ const PeoplePicker = React.forwardRef<HTMLDivElement, PeoplePickerProps>(functio
   pillShowAvatar = true,
   pillWrap = true,
   searchIn = 'menu',
+  clearable = false,
   showDisplayEndIcon = false,
   'aria-label': ariaLabel,
   ...rest
@@ -162,6 +171,14 @@ const PeoplePicker = React.forwardRef<HTMLDivElement, PeoplePickerProps>(functio
   const resolvedVariant: FieldVariantInternal = useResolvedFieldVariant(variantProp)
   const isMulti = Array.isArray(value)
   const isEmpty = !value || (isMulti && value.length === 0)
+  // 觸控多選一律走既有 pill 型態(2026-08-05 user 拍板:「手機上自動把多選 people picker 改成
+  // combobox 的型態,所有樣式互動都是 combobox 的 SSOT,不要再造輪子」)。理由:stack 的移除鈕
+  // 是 hover-reveal,觸控沒有 hover;恆顯 X 又太亂(user 否決)。pill 是 DS 既有 canonical
+  // (`multiDisplay='pill'` + Tag `avatar` prop),每顆 pill 自帶 X = Combobox tag 移除 SSOT。
+  // 桌機(fine pointer)完全不受影響:仍是 avatar stack + 圓形 +N + hover X。
+  // consumer 顯式傳 'pill' 時本行為 no-op(同值)。hook 必在任何 early return 前呼叫(React #310)。
+  const isTouch = useIsTouchDevice()
+  const effectiveMultiDisplay = isTouch && isMulti ? 'pill' : multiDisplay
 
   // 2026-07-05 D3 P0 修:以下派生 + 4 hooks 原宣告在 view/readonly/single/pill 四個 early return
   // 之後 — 同一 mounted instance 的 resolvedMode 於 edit↔view/disabled 切換(<Field mode>/<Field
@@ -178,7 +195,7 @@ const PeoplePicker = React.forwardRef<HTMLDivElement, PeoplePickerProps>(functio
   const stackContainerRef = React.useRef<HTMLDivElement | null>(null)
   const [stackVisibleCount, setStackVisibleCount] = React.useState<number | undefined>(undefined)
   React.useLayoutEffect(() => {
-    if (resolvedMode !== 'edit' || !isMulti || multiDisplay !== 'stack' || selectedNames.length <= 1) {
+    if (resolvedMode !== 'edit' || !isMulti || effectiveMultiDisplay !== 'stack' || selectedNames.length <= 1) {
       setStackVisibleCount(undefined); return
     }
     const root = stackContainerRef.current
@@ -190,7 +207,11 @@ const PeoplePicker = React.forwardRef<HTMLDivElement, PeoplePickerProps>(functio
     // Combobox DOM-based useOverflowCount(非 deterministic 那個算法)。修:用 root 自己當 trigger,
     // 從 root 內找 tagArea(flex-1 min-w-0 div)。
     const calc = () => {
-      const trigger = root.matches('[role="combobox"]') ? root : root.querySelector<HTMLElement>('[role="combobox"]')
+      // 2026-08-05 native-parity fix(touch 實圖抓「多人只剩 +N」):NativeCombobox root 無
+      // role="combobox"(a11y 在隱藏 <select> 上)→ 原查法 trigger=null → available=0 → 全
+      // overflow。雙分支通用:查無 combobox role 時 root 自身就是 trigger(native __triggerRef
+      // 即 field wrapper root),tagArea(flex-1 min-w-0)兩分支同構。
+      const trigger = root.matches('[role="combobox"]') ? root : (root.querySelector<HTMLElement>('[role="combobox"]') ?? root)
       const tagArea = trigger?.querySelector<HTMLElement>('div[class*="flex-1"][class*="min-w-0"]')
       const available = tagArea?.clientWidth ?? trigger?.clientWidth ?? 0
       const visible = getAvatarStackVisibleCount({
@@ -205,7 +226,7 @@ const PeoplePicker = React.forwardRef<HTMLDivElement, PeoplePickerProps>(functio
     const ro = new ResizeObserver(calc)
     ro.observe(root)
     return () => ro.disconnect()
-  }, [resolvedMode, isMulti, multiDisplay, selectedNames.length, size])
+  }, [resolvedMode, isMulti, effectiveMultiDisplay, selectedNames.length, size])
   // Merge ref:forward to parent + capture for ResizeObserver
   const mergedStackRef = React.useCallback((el: HTMLDivElement | null) => {
     stackContainerRef.current = el
@@ -295,7 +316,9 @@ const PeoplePicker = React.forwardRef<HTMLDivElement, PeoplePickerProps>(functio
 
   // ── single mode → wraps Select ────────────────────────────────────────────
   if (!isMulti) {
-    const handleSingleChange = (name: string) => onChange?.([findPerson(people, name)])
+    // clearable X 清空時 Select emit onChange('') — 空字串必映射為空陣列,
+    // 不可進 findPerson(fallback 會回 '' 字串 = 假人員)。清除後回 placeholder 態(select.spec.md「Clearable」)。
+    const handleSingleChange = (name: string) => onChange?.(name ? [findPerson(people, name)] : [])
     return (
       <Select
         ref={ref as React.Ref<HTMLDivElement>}
@@ -308,6 +331,7 @@ const PeoplePicker = React.forwardRef<HTMLDivElement, PeoplePickerProps>(functio
         value={selectedNames[0] ?? null}
         onChange={handleSingleChange}
         searchable
+        clearable={clearable}
         placeholder={placeholder}
         // 2026-05-12 Issue 4:placeholder = trigger empty。2026-07-04 Q4:emptyText 走 Select →
         // SelectMenu 接線(search-empty 語意,與 trigger-empty 分離)。
@@ -330,7 +354,8 @@ const PeoplePicker = React.forwardRef<HTMLDivElement, PeoplePickerProps>(functio
   }
 
   // ── multi 'pill' → wraps Combobox(對齊 GitHub Reviewers / Combobox idiom)────
-  if (multiDisplay === 'pill') {
+  // 觸控多選亦走此分支(effectiveMultiDisplay,見上方 isTouch 註解)。
+  if (effectiveMultiDisplay === 'pill') {
     const handleMultiChange = (next: string[]) => {
       onChange?.(next.map(name => findPerson(people, name)))
     }
@@ -347,6 +372,7 @@ const PeoplePicker = React.forwardRef<HTMLDivElement, PeoplePickerProps>(functio
         // 2026-07-14 deep-audit fix:searchIn 補 forward(原漏傳 → pill 模式永遠 Combobox default 'menu',
         // documented multi opt-in `searchIn='trigger'` silently 無效;stack branch 已傳,對齊 M30 forward 全 surface)
         searchIn={searchIn}
+        clearable={clearable}
         searchPlaceholder={searchPlaceholder}
         searchAriaLabel={searchAriaLabel}
         // 2026-05-12 Stream C Issue 4(codex Q3):placeholder = trigger empty hint('請選擇人員')
@@ -413,6 +439,7 @@ const PeoplePicker = React.forwardRef<HTMLDivElement, PeoplePickerProps>(functio
       onChange={handleMultiChange}
       searchable
       searchIn={searchIn}
+      clearable={clearable}
       searchPlaceholder={searchPlaceholder}
       searchAriaLabel={searchAriaLabel}
       // 2026-05-12 Stream C Issue 4(codex Q3):placeholder = trigger empty('請選擇人員');emptyText = search-empty(僅 backward-compat forward 1 cycle)

package/src/components/PeoplePicker/person-display.tsx

@@ -348,7 +348,10 @@ function AvatarDismissOverlay({ onRemove, label }: { onRemove: () => void; label
         'bg-surface-strong text-on-emphasis hover:bg-surface-strong-hover',
         // a11y(codex P1 fix):opacity 而非 display:none — element 在 DOM/tab-order,
         // keyboard 可達。Hover / focus-within / focus-visible 三條件之一觸發。
-        'opacity-0 group-hover/avatar:opacity-100 group-focus-within/avatar:opacity-100 focus-visible:opacity-100',
+        // **不加 touch 恆顯**(2026-08-05 user 否決前一版 A 案:「一般狀態直接把所有成員 avatar
+        // 的 X 都秀出來,這樣看起來超亂」)。觸控的多人移除改由 PeoplePicker 自動降階為既有
+        // pill 型態(Combobox tag SSOT,每顆 pill 自帶 X)承擔 — 見 people-picker.spec.md
+        // 「觸控裝置(native 分支)」。本 overlay 維持 hover / focus 才顯的桌機語意。
         'transition-opacity duration-150 motion-reduce:duration-0',
         'focus-visible:outline-none focus-visible:ring-2 focus-visible:ring-ring',
       ].join(' ')}

package/src/components/Select/select.spec.md

@@ -241,9 +241,11 @@ Select 的值套用時機是**由 onChange handler 的副作用決定**，不是
 
 **`selectedItemRenderer` 優先於兩種顯示模式**(2026-07-08 A 案回歸修正):設定時已選值改渲 consumer renderer 輸出(status icon+text / PersonDisplay 等),且 **edit / view / readonly / disabled 4 mode 共享同一 renderer**(`field-controls.spec.md` 共享 contract (a),禁 edit-only)。renderer 輸出屬「值內容」— `mode="view"` 照常渲染(無 chrome 無 chevron);與 affordance(chevron/outline)分層見 `field.spec.md` L6。
 
+**雙分支同 SSOT(2026-08-05 修)**:觸控 NativeSelect edit 有值時同樣渲 renderer 輸出為可見層(native `<select>` 沿 tag 模式既有透明 overlay pattern,tap 開原生 picker;空值走原生 placeholder)——先前 native edit 只顯 option 純文字,PeoplePicker 手機單人因此無 avatar = touch 分支漏接 display 層(canonical 違反)。**Root invariant:display-layer renderer props 必雙分支(Custom/Native)同消費;新增 renderer-affecting prop 必同步 NativeSelect。**
+
 ### plain 模式
 
-- 桌面使用 custom trigger + SelectMenu；觸控裝置使用 NativeSelect 的純文字 + ChevronDown
+- 桌面使用 custom trigger + SelectMenu；觸控裝置使用 NativeSelect 的純文字 + ChevronDown(`selectedItemRenderer` 設定時觸控同渲 renderer 輸出,見「雙分支同 SSOT」段)
 - **Icon-binding 矩陣**(icon kind canonical,2026-05-09 clarified):
 
 | Icon 角色 | Prop | 語意 | 色彩 | 優先序 |

package/src/components/Select/select.tsx

@@ -526,6 +526,7 @@ const NativeSelect = React.forwardRef<HTMLSelectElement, SelectProps>(
       return <ReadonlyDisplay mode={resolvedMode} variant={variant} width={width} size={size} options={options} value={value} display={display} startIcon={StartIcon} className={className} placeholder={placeholder} showDisplayEndIcon={showDisplayEndIcon} selectedItemRenderer={selectedItemRenderer} />
     }
 
+    const selectedOpt = options?.find(o => o.value === value)
     const selectEl = (
       <select
         ref={setSelectRef}
@@ -537,7 +538,7 @@ const NativeSelect = React.forwardRef<HTMLSelectElement, SelectProps>(
         aria-required={fieldCtx?.required || undefined}
         aria-describedby={ariaDescribedByProp ?? fieldCtx?.descriptionId}
         aria-errormessage={ariaErrorMessageProp ?? (error ? fieldCtx?.errorId : undefined)}
-        className={cn(bareInputStyles, 'cursor-pointer appearance-none', !value && 'text-fg-muted', !isTextDisplay && value && 'absolute inset-0 w-full h-full opacity-0 z-0')}
+        className={cn(bareInputStyles, 'cursor-pointer appearance-none', !value && 'text-fg-muted', value && (!isTextDisplay || (selectedItemRenderer && selectedOpt)) && 'absolute inset-0 w-full h-full opacity-0 z-0')}
         {...props}
       >
         {placeholder && <option value="" disabled>{placeholder}</option>}
@@ -555,11 +556,34 @@ const NativeSelect = React.forwardRef<HTMLSelectElement, SelectProps>(
         <ChevronDown size={iconSize} className="text-fg-muted" aria-hidden />
       </ItemSuffix>
     )
-    const selectedOpt = options?.find(o => o.value === value)
     const label = selectedOpt?.label ?? value
     const nativeTagVariant = selectedOpt?.tagVariant as 'blue' | 'green' | 'red' | 'yellow' | 'neutral' | undefined
     const SelectedOptIcon = selectedOpt?.icon
 
+    // Display-layer parity(2026-08-05 user 拍板):selectedItemRenderer 有值 → 渲 renderer 輸出為
+    // 可見層(PeoplePicker 單人手機 = avatar+人名,與桌機同 SSOT),native <select> 沿 tag 模式既有
+    // pattern 作透明 overlay(tap 開原生 picker)。原 native edit 只顯 option 純文字 = touch 分支
+    // 從未接 display 層的病根。空值 fall through 原分支(native placeholder)。selectedOpt 查無
+    // (async options 未到)→ fallback {value,label:value},renderer 端自行降級(initials)。
+    if (selectedItemRenderer && value && selectedOpt) {
+      return (
+        <div className={cn(fieldWrapperStyles({ mode: 'edit', variant: variant, width, size, error }), 'relative', className)}
+          style={{ paddingRight: 'var(--field-px)' }} data-field-mode="edit" data-error={error ? '' : undefined}>
+          {/* Review fix(2026-08-05 F5/F6):StartIcon + nakedCellRowModeAlign 與桌機 renderer 分支
+              (CustomSelect,gate 同為 selectedOpt truthy — renderer 公開契約只收 options 真實 entry,
+              async options 未到 fall through 原生文字分支,與桌機 fallback 對稱)逐項對齊;
+              pointer-events-none → tap 穿透 select overlay 開原生 picker。 */}
+          {StartIcon && <ItemPrefix><StartIcon size={iconSize} className="text-fg-muted pointer-events-none" aria-hidden /></ItemPrefix>}
+          <span className={cn('relative z-10 pointer-events-none flex-1 min-w-0 inline-flex items-center', nakedCellRowModeAlign)}>
+            {selectedItemRenderer(selectedOpt)}
+          </span>
+          {selectEl}
+          {clearEl}
+          {chevronEl}
+        </div>
+      )
+    }
+
     if (!isTextDisplay) {
       return (
         <div className={cn(fieldWrapperStyles({ mode: 'edit', variant: variant, width, size, error }), value && tagPadding[size], 'relative',

package/src/components/Steps/steps.stories.tsx

@@ -58,8 +58,10 @@ export const Default: Story = {
     }
 
     // ── Pattern A:submit 在最後一步,送出後整個 wizard 替換成 success banner ──
-    // 世界級 wizard UX(Ant / Linear / Stripe 常見):最後一步的 submit 按下後,
-    // stepper 不再顯示,改成一個 success card(+ 重置 button for demo 用)。
+    // Pattern A:最後一步 submit 按下後 stepper 不再顯示,整個 wizard 替換成
+    // success card;「再填一份申請」是成功頁的真實產品 action(Google Forms
+    // 「Submit another response」同款,https://support.google.com/docs/answer/2839588),
+    // 非 demo 治具。
     if (submitted) {
       return (
         <div className="w-[480px] flex flex-col gap-4 p-6 bg-muted rounded-md border border-border">