@qijenchen/design-system 0.1.0-beta.85 → 0.1.0-beta.86

package/src/components/Coachmark/coachmark.anatomy.stories.tsx

@@ -68,7 +68,7 @@ export const Overview: Story = {
           <table className="text-caption border-collapse">
             <thead><tr><Th>Prop</Th><Th>Type</Th><Th>Default</Th><Th>說明</Th></tr></thead>
             <tbody>
-              <tr><Td mono>children</Td><Td mono>ReactNode</Td><Td mono>—</Td><Td>anchor trigger element(Popover asChild)</Td></tr>
+              <tr><Td mono>children</Td><Td mono>ReactElement</Td><Td mono>—</Td><Td>anchor trigger element(Popover asChild Slot 單 element 契約,2026-07-05 型別收緊)</Td></tr>
               <tr><Td mono>open / onOpenChange</Td><Td mono>boolean / (o) =&gt; void</Td><Td mono>—</Td><Td>controlled 控制(多步 tour 必用)</Td></tr>
               <tr><Td mono>defaultOpen</Td><Td mono>boolean</Td><Td mono>—</Td><Td>uncontrolled 初始開啟狀態</Td></tr>
               <tr><Td mono>kind</Td><Td mono>'tips' | 'new-features' | ReactNode</Td><Td mono>—</Td><Td>有值則渲染 Header(tour-level title);'tips'→「使用技巧」、'new-features'→「新功能介紹」、ReactNode→自訂;multi-step tour 建議傳</Td></tr>
@@ -126,9 +126,9 @@ export const Inspector: Story = {
             </div>
             <Coachmark
               open
-              image={hasImage ? <MediaGradient from="var(--color-indigo-6)" to="var(--color-purple-6)" icon={Sparkles} label="功能介紹" /> : undefined}
-              title="試試新功能"
-              description="這是 Coachmark 的說明文字;多行內容會自動換行並保持 leading 一致。"
+              image={hasImage ? <MediaGradient from="var(--color-indigo-6)" to="var(--color-purple-6)" icon={Sparkles} label="AI 續寫" /> : undefined}
+              title="讓 AI 幫你續寫草稿"
+              description="選取一段文字,AI 會依前後文續寫並保留你的語氣;不滿意可以一鍵重新產生。"
               step={hasStep ? { current: 2, total: 3 } : undefined}
               onPrev={hasPrev ? () => {} : undefined}
               onSkip={hasSkip ? () => {} : undefined}
@@ -137,7 +137,7 @@ export const Inspector: Story = {
               side="right"
               align="start"
             >
-              <Button variant="primary" size="sm" startIcon={Sparkles}>Anchor</Button>
+              <Button variant="primary" size="sm" startIcon={Sparkles}>AI 續寫</Button>
             </Coachmark>
           </div>
         </div>

package/src/components/Coachmark/coachmark.principles.stories.tsx

@@ -158,7 +158,7 @@ export const UsageGuidance: Story = {
             image={<MediaGradient from="var(--color-indigo-6)" to="var(--color-purple-6)" icon={Bot} label="AI 助理" />}
             title="試試新的 AI 助理"
             description="在任何文件中按下 AI 按鈕,讓 Claude 幫你摘要、翻譯或改寫內容。"
-            onSkip={() => {}}
+            isLastStep
             onNext={() => {}}
             side="bottom"
             align="start"

package/src/components/Combobox/combobox.anatomy.stories.tsx

@@ -306,7 +306,7 @@ export const Overview = {
             <thead><tr><Th>Prop</Th><Th>Type</Th><Th>Default</Th><Th>說明</Th></tr></thead>
             <tbody>
               {[
-                ['mode', "'edit'|'display'|'readonly'|'disabled'", "'edit'", 'FieldMode 四模式;顯式傳入時永遠最優先,不被 disabled 覆蓋'],
+                ['mode', "'edit'|'view'|'readonly'|'disabled'", "'edit'", 'FieldMode 四模式;顯式傳入時永遠最優先,不被 disabled 覆蓋'],
                 ['size', "'sm'|'md'|'lg'", "'md'", '尺寸，與 Button 共用 field-height token'],
                 ['options', 'ComboboxOption[]', '—', '選項列表（extends SelectMenuOption：value / label / icon / avatar / description / disabled / group）'],
                 ['value', 'string[]', '[]', '已選中的值陣列'],
@@ -410,6 +410,7 @@ const InspectorInner = () => {
               value={value}
               onChange={setValue}
               placeholder="選擇分類"
+              aria-label="產品分類"
               className="w-72"
             />
           </div>
@@ -551,6 +552,7 @@ export const ColorMatrix = {
                         size="sm"
                         disabled={st === 'disabled'}
                         onChange={() => {}}
+                        aria-label={`產品分類(${st})`}
                       />
                       <TokenAnnotation colors={st === 'disabled' ? TOKEN_MAP.disabled.default : TOKEN_MAP.edit[st]} />
                     </td>
@@ -567,6 +569,7 @@ export const ColorMatrix = {
                         error={st !== 'disabled'}
                         disabled={st === 'disabled'}
                         onChange={() => {}}
+                        aria-label={`產品分類(錯誤態、${st})`}
                       />
                       <TokenAnnotation colors={st === 'disabled' ? TOKEN_MAP.disabled.default : ERROR_COLORS[st]} />
                     </td>
@@ -588,10 +591,10 @@ export const ColorMatrix = {
                   <tr key={m}>
                     <Td mono>{m}</Td>
                     <td className="p-3 border-b border-divider align-top min-w-[180px]">
-                      <Combobox mode={m} options={categoryOptions} value={['electronics', 'food']} size="sm" />
+                      <Combobox mode={m} options={categoryOptions} value={['electronics', 'food']} size="sm" aria-label={`產品分類(${m})`} />
                     </td>
                     <td className="p-3 border-b border-divider align-top min-w-[160px]">
-                      <Combobox mode={m} options={categoryOptions} value={[]} size="sm" />
+                      <Combobox mode={m} options={categoryOptions} value={[]} size="sm" aria-label={`產品分類(${m}、空值)`} />
                     </td>
                     <td className="p-3 border-b border-divider align-top min-w-[160px]">
                       <TokenAnnotation colors={TOKEN_MAP[m].default} />
@@ -726,7 +729,7 @@ export const SizeMatrix = {
         <div className="flex flex-col gap-3">
           {SIZES.map((sz) => (
             <div key={sz} className="flex items-center gap-3">
-              <Combobox size={sz} options={categoryOptions} value={['electronics', 'food']} onChange={() => {}} className="w-64" />
+              <Combobox size={sz} options={categoryOptions} value={['electronics', 'food']} onChange={() => {}} className="w-64" aria-label={`產品分類(size=${sz})`} />
               <span className="text-caption text-fg-secondary font-mono">size=&quot;{sz}&quot;</span>
             </div>
           ))}
@@ -778,6 +781,7 @@ export const StateBehavior = {
               options={categoryOptions}
               value={overflowV}
               onChange={setOverflowV}
+              aria-label="產品分類(單行溢出 +N 範例)"
             />
           </div>
           <div className="flex flex-col gap-1 text-[11px] text-fg-secondary">
@@ -814,6 +818,7 @@ export const StateBehavior = {
                   value={wrapV}
                   onChange={setWrapV}
                   wrap
+                  aria-label="產品分類(換行模式範例)"
                 />
               </div>
             </div>
@@ -846,6 +851,7 @@ export const StateBehavior = {
               onChange={setClearV}
               clearable
               className="w-64"
+              aria-label="產品分類(清除全部範例)"
             />
             <button
               type="button"
@@ -872,6 +878,7 @@ export const StateBehavior = {
               value={dismissV}
               onChange={setDismissV}
               className="w-72"
+              aria-label="產品分類(個別移除 Tag 範例)"
             />
             <button
               type="button"

package/src/components/Combobox/combobox.principles.stories.tsx

@@ -60,10 +60,7 @@ export const UsageGuidance: Story = {
           <LinkTo kind="Design System/Components/Combobox/展示" name="四模式"><span className="text-primary hover:text-primary-hover font-medium cursor-pointer">四模式</span></LinkTo>
         </li>
         <li>
-          <LinkTo kind="Design System/Components/Combobox/展示" name="尺寸與 Button 對齊"><span className="text-primary hover:text-primary-hover font-medium cursor-pointer">尺寸與 Button 對齊</span></LinkTo>
-        </li>
-        <li>
-          <LinkTo kind="Design System/Components/Combobox/展示" name="單行 vs 換行"><span className="text-primary hover:text-primary-hover font-medium cursor-pointer">單行 vs 換行</span></LinkTo>
+          <LinkTo kind="Design System/Components/Combobox/展示" name="三種尺寸"><span className="text-primary hover:text-primary-hover font-medium cursor-pointer">尺寸與 Button 對齊</span></LinkTo>
         </li>
         <li>
           <LinkTo kind="Design System/Components/Combobox/展示" name="搜尋"><span className="text-primary hover:text-primary-hover font-medium cursor-pointer">搜尋</span></LinkTo>
@@ -81,14 +78,14 @@ export const UsageGuidance: Story = {
           title="Combobox 的 sweet spot — 多選 + 空間受限 + 選項數 6+"
           note="Tag / 分類 / 協作成員 / 通知訂閱。使用者快速加選、移除，label 自帶語意不需描述"
         >
-          <Combobox options={categoryOptions} value={tags} onChange={setTags} />
+          <Combobox options={categoryOptions} value={tags} onChange={setTags} aria-label="商品分類(多選 Tag 範例)" />
         </Rule>
 
         <Rule
           title="❌ 單選:用 Select"
           note="Combobox 永遠多選——單選塞進來使用者每次要手動先移除舊 Tag 再選新的，多餘的互動"
         >
-          <Combobox options={categoryOptions} value={['electronics']} onChange={() => {}} />
+          <Combobox options={categoryOptions} value={['electronics']} onChange={() => {}} aria-label="商品分類(單選反例——應改用 Select)" />
           <Label warn>↑ 只選一個 electronics → 應該用 Select，一次點擊完成切換</Label>
         </Rule>
 
@@ -104,6 +101,7 @@ export const UsageGuidance: Story = {
             ]}
             value={['terms']}
             onChange={() => {}}
+            aria-label="同意項目"
           />
           <Label warn>↑ 條款勾選是「完整閱讀後同意」→ 用 Checkbox stack 全露內容</Label>
         </Rule>
@@ -121,6 +119,7 @@ export const UsageGuidance: Story = {
             ]}
             value={['eng-fe']}
             onChange={() => {}}
+            aria-label="部門"
           />
           <Label warn>↑ 用縮排偽造階層 → 沒有展開收合、不能按父節點全選、破壞資料結構</Label>
         </Rule>
@@ -141,7 +140,7 @@ export const WrapRule: Story = {
           title="單行（預設）— Table cell、空間受限的 Form"
           note="固定高度，與 Input / Select 等欄位並排對齊。多於可見寬度的 Tag 以 +N 指示器代替，hover 可看完整清單"
         >
-          <Combobox options={categoryOptions} value={single} onChange={setSingle} />
+          <Combobox options={categoryOptions} value={single} onChange={setSingle} aria-label="商品分類(單行溢出範例)" />
           <Label>↑ 單行：高度固定，超出的 Tag → +N</Label>
         </Rule>
 
@@ -149,7 +148,7 @@ export const WrapRule: Story = {
           title="多行 wrap — 空間充裕的 Form"
           note="高度隨選中數量展開，每個 Tag 都完整可見。適合填答型表單——使用者一眼看到所有選項，不需 hover 溢出指示器"
         >
-          <Combobox wrap options={categoryOptions} value={wrapped} onChange={setWrapped} />
+          <Combobox wrap options={categoryOptions} value={wrapped} onChange={setWrapped} aria-label="商品分類(多行 wrap 範例)" />
           <Label>↑ 多行：完整展開，無溢出</Label>
         </Rule>
 
@@ -189,7 +188,7 @@ export const TagOperationRule: Story = {
           title="Tag 只能被「移除」，不能被「編輯」或「重排」"
           note="每個 Tag 右側的 X 是唯一被允許的互動——保持 Tag 的心智模型單純：它代表一個已選中的選項，要換就刪了重選"
         >
-          <Combobox options={categoryOptions} value={value} onChange={setValue} />
+          <Combobox options={categoryOptions} value={value} onChange={setValue} aria-label="商品分類(Tag 移除範例)" />
           <Label>↑ 點 Tag 的 X 移除；右側 clear all 一次清除；新增從 dropdown 選擇</Label>
         </Rule>
 
@@ -205,7 +204,7 @@ export const TagOperationRule: Story = {
           title="已選中的選項在下拉裡以打勾標示，再點一次即取消"
           note="桌機（預設）走自建浮層選單：已選項保留在清單中並以打勾呈現，再點一次即移除——避免使用者跨越下拉與 field 才能對照已選狀態。手機 / 觸控裝置改走原生 select，已選項則不重複出現在原生下拉"
         >
-          <Combobox options={categoryOptions} value={['electronics']} onChange={() => {}} />
+          <Combobox options={categoryOptions} value={['electronics']} onChange={() => {}} aria-label="商品分類(已選項打勾範例)" />
           <Label>↑ 打開 dropdown，Electronics 仍在清單裡並打勾，可再點一次取消</Label>
         </Rule>
       </div>
@@ -223,7 +222,7 @@ export const OverflowRule: Story = {
           title="+N 指示器是單行模式的必要元件"
           note="使用者必須知道「還有多少沒看到」——沒有 +N 的單行會誤導使用者以為選項已完整顯示。Hover 可看完整清單"
         >
-          <Combobox options={categoryOptions} value={value} onChange={setValue} />
+          <Combobox options={categoryOptions} value={value} onChange={setValue} aria-label="商品分類(+N 溢出指示範例)" />
           <Label>↑ 窄容器內多個 Tag，自動出現 +N</Label>
         </Rule>
 

package/src/components/Combobox/combobox.spec.md

@@ -124,7 +124,7 @@ value 軸 controlled-only;open 軸方向相反 — **uncontrolled-only**:`defaul
 
 ## Loading
 
-`loading?: boolean`(forward 給 SelectMenu SSOT,2026-05-15 audit B 補):dropdown body 內取代 options 顯 `<Empty icon={<CircularProgress size={48}/>}/>`(消費 既有 empty.spec.md「現有消費者」SelectMenu loading row SSOT)。Trigger 不變,user 隨時可開。對齊 Ant AutoComplete loading idiom。 <!-- @benchmark-unverified: see frontmatter benchmark list for canonical DS source URL -->
+`loading?: boolean`(forward 給 SelectMenu SSOT,2026-05-15 audit B 補;措辭對齊 `select.spec.md`「Loading」2026-07-04 Q3 拍板 — 不清空 stale options):spinner 只在**無可顯示選項時**佔 empty slot 顯 `<Empty icon={<CircularProgress size={48}/>}/>`(cmdk `CommandEmpty` 機制;已有 options 時保留顯示,不取代)。Trigger 不變,user 隨時可開。對齊 MUI Autocomplete「loading 只在無 suggestions 時顯 loadingText」共識(cite 詳 select.spec.md 同段)。 <!-- @benchmark-unverified: see frontmatter benchmark list for canonical DS source URL -->
 
 ---
 
@@ -132,7 +132,7 @@ value 軸 controlled-only;open 軸方向相反 — **uncontrolled-only**:`defaul
 
 - **Disabled**:Field SSOT own(`Field/field-controls.spec.md`)。trigger / tag dismiss / 搜尋 input 全部 disabled,token 走 M24 state precedence(`text-fg-disabled`);已選 Tag 的 dismiss X 自動隱藏(見「readonly / disabled 的 Tag」段)。
 - **Loading**:已 codify(見「Loading」段)。
-- **Empty(no search results)**:dropdown body 內渲 SelectMenu 預設 `emptyText`「沒有符合的選項」(Combobox 不傳 `emptyText`,走 SelectMenu primitive default)。Combobox 不暴露 `creatable` / `onCreate` prop(僅 SelectMenu primitive 本身支援),故 Combobox consumer 無「建立 "xxx"」row。
+- **Empty(no search results)**:dropdown body 內渲 `emptyText`(Combobox 暴露 `emptyText` prop 並 forward 給 SelectMenu;未傳時走 SelectMenu 預設「沒有符合的選項」)。Combobox **暴露 `creatable` / `onCreate` / `createLabel` prop 並 forward 給 SelectMenu**(2026-07-18 user 拍板;搜尋非空且無完全同名既有選項時,dropdown 顯 create row `Plus + createLabel`)——邏輯/顯示/互動 SSOT 住在 SelectMenu(`select-menu.tsx` :271-275 顯隱 / render)。僅 searchable 桌機路徑生效(native mobile 不支援)。對齊 Ant tags / react-select Creatable。
 - **Empty(no value selected)**:multi mode `value=[]` 時 trigger 顯 placeholder(如「請選擇」);empty state 不渲 tag 區。
 - **Dark mode / density**:走 Field + SelectMenu SSOT 自動 adapt。
 
@@ -145,6 +145,10 @@ value 軸 controlled-only;open 軸方向相反 — **uncontrolled-only**:`defaul
 - multi mode 可附 `min` / `max` selected count 限制(consumer 自驗,Combobox 不獨立 own validation rules)
 - Validation timing:預設 onBlur + onSubmit,onChange 不立即 validate(避免邊選邊紅)
 
+## Ref 契約(cross-mode 例外,2026-07-17 user 拍板)
+
+Combobox 是 **4-mode field**(edit / view / readonly / disabled),各 mode 渲染**本質不同的 subtree**(edit = trigger + hidden select;view/readonly = `ReadonlyMultiSelect`)。**`ref` 只保證在 edit mode 指向 trigger root(`__triggerRef`)**;view / readonly / disabled mode **不保證穩定 root**(對齊 React「avoid over-exposing DOM nodes in higher-level components」)。需在任意 mode 取穩定 DOM root 的 consumer 應在外層自包一層容器,不依賴 Combobox `ref` 跨 mode 一致。與 T1 RadioGroup / Switch 的跨 mode 缺口採同一哲學(記錄例外,不硬造統一 host)。
+
 ---
 
 ## 禁止事項

package/src/components/Combobox/combobox.stories.tsx

@@ -26,7 +26,7 @@ const meta: Meta<typeof Combobox> = {
 export default meta
 type Story = StoryObj<typeof Combobox>
 
-// @story-trait-rationale: pre-existing trait gaps (Default/WithError) tracked separately; this PR scope = add display mode card to Modes story only.
+// @story-trait-rationale: pre-existing trait gaps (Default/WithError) tracked separately; this PR scope = add view mode card to Modes story only.
 /* ── 四模式 ── */
 export const Modes: Story = {
   name: '四模式',
@@ -39,8 +39,8 @@ export const Modes: Story = {
           <Combobox options={categoryOptions} value={value} onChange={setValue} aria-label="類別(edit mode demo)" />
         </div>
         <div>
-          <h3 className="text-body font-bold text-foreground mb-2">display</h3>
-          <Combobox mode="display" options={categoryOptions} value={value} aria-label="類別(display mode demo)" />
+          <h3 className="text-body font-bold text-foreground mb-2">view</h3>
+          <Combobox mode="view" options={categoryOptions} value={value} aria-label="類別(view 模式示範)" />
         </div>
         <div>
           <h3 className="text-body font-bold text-foreground mb-2">readonly</h3>
@@ -61,7 +61,7 @@ export const Modes: Story = {
 
 /* ── 尺寸與 Button 對齊 ── */
 export const SizeAlignment: Story = {
-  name: '尺寸與 Button 對齊',
+  name: '三種尺寸',
   render: () => {
     const [sm, setSm] = React.useState(['electronics', 'food', 'lifestyle'])
     const [md, setMd] = React.useState(['electronics', 'food', 'lifestyle'])
@@ -71,7 +71,7 @@ export const SizeAlignment: Story = {
       <div className="flex flex-col gap-4">
         {(['sm', 'md', 'lg'] as const).map(size => (
           <div key={size} className="flex items-center gap-3">
-            <Combobox size={size} options={categoryOptions} value={states[size][0]} onChange={states[size][1]} className="max-w-xs" />
+            <Combobox size={size} options={categoryOptions} value={states[size][0]} onChange={states[size][1]} className="max-w-xs" aria-label={`商品分類(size=${size})`} />
             <Button variant="primary" size={size}>送出</Button>
             <span className="text-caption text-fg-muted">size="{size}"</span>
           </div>
@@ -81,37 +81,10 @@ export const SizeAlignment: Story = {
   },
 }
 
-/* ── 單行 vs 換行 ── */
-export const WrapModes: Story = {
-  name: '單行 vs 換行',
-  render: () => {
-    const init = ['electronics', 'food', 'lifestyle', 'clothing', 'furniture']
-    const [v1, setV1] = React.useState(init)
-    const [v2, setV2] = React.useState(init)
-    return (
-      <div className="flex flex-col gap-6 w-72">
-        <div>
-          <h3 className="text-body font-bold text-foreground mb-2">單行（預設）</h3>
-          <p className="text-caption text-fg-muted mb-3">塞不下的自動收進 +N，hover 顯示隱藏項</p>
-          <Combobox options={categoryOptions} value={v1} onChange={setV1} />
-        </div>
-        <div>
-          <h3 className="text-body font-bold text-foreground mb-2">單行 readonly</h3>
-          <Combobox mode="readonly" options={categoryOptions} value={init} />
-        </div>
-        <div>
-          <h3 className="text-body font-bold text-foreground mb-2">換行（wrap）</h3>
-          <p className="text-caption text-fg-muted mb-3">高度隨內容長，badges 自動換行</p>
-          <Combobox options={categoryOptions} value={v2} onChange={setV2} wrap />
-        </div>
-        <div>
-          <h3 className="text-body font-bold text-foreground mb-2">換行 readonly</h3>
-          <Combobox mode="readonly" options={categoryOptions} value={init} wrap />
-        </div>
-      </div>
-    )
-  },
-}
+// @story-trait-rationale: 原 WrapModes(單行 vs 換行)retired 2026-07-17(Dim 24 earn-existence)—
+//   單行/wrap × edit/readonly 矩陣已由 anatomy「狀態行為」(單行溢出 + readonly 溢出 + edit/readonly wrap)
+//   完整覆蓋機制,wrap 選擇原則由 principles「Wrap 模式選擇」(WrapRule)owns。展示層不重演矩陣(三層定位);
+//   principles 使用指引頁對應 LinkTo(單行 vs 換行)同步移除。
 
 /* ── 搜尋 ── */
 export const Searchable: Story = {

package/src/components/Combobox/combobox.tsx

@@ -1,5 +1,5 @@
 // @benchmark-unverified-blanket: file-level retraction per M22 (d) — claims herein not individually URL-cited; treat as unverified visual/usage rumor unless retrofit per-claim. Hook escape preserved.
-// @renderer-symmetry-allow: ComboboxTagStack(display path)接 consumer tagRenderer 是 Stream C 下 cycle 工作 — 2026-05-12 先 ship Issues 2/3/4 surgical fixes(placeholder vocabulary + cell surface metrics + placeholder truncate),tagRenderer display-path unify deferred per field-controls.spec.md 共享 contract a。當前 multi=1 顯示已透過 PeoplePicker tagRenderer(people-picker.tsx:426-444)PersonDisplay SSOT 對齊;其他 Combobox consumer 走 default `<Tag>` 純文字 backward-compat。
+// @renderer-symmetry-allow: ComboboxTagStack(view path)接 consumer tagRenderer 是 Stream C 下 cycle 工作 — 2026-05-12 先 ship Issues 2/3/4 surgical fixes(placeholder vocabulary + cell surface metrics + placeholder truncate),tagRenderer view-path unify deferred per field-controls.spec.md 共享 contract a。當前 multi=1 顯示已透過 PeoplePicker tagRenderer(people-picker.tsx:426-444)PersonDisplay SSOT 對齊;其他 Combobox consumer 走 default `<Tag>` 純文字 backward-compat。
 // code-quality-allow: file-size — Combobox 含 NativeCombobox/CustomCombobox/useOverflowCount/OverflowTagList/ComboboxTagStack 5 子元件 + 共用 helpers,split-into-files 會破壞 measurement closures + 重複 type definitions。
 import * as React from 'react'
 import { X, ChevronDown } from 'lucide-react'
@@ -237,7 +237,7 @@ interface OverflowTagListProps {
    * 2026-05-14 I4 fix(per codex M31 verdict + user 抓「display overflow 有 avatar / edit 無」):
    * Optional renderer for hidden items in `+N` overflow popover。Default fallback = `<Tag>{label}</Tag>`
    * (純文字 chip,backward-compat)。Consumer pass 此 prop 讓 hidden items 顯示同 avatar 視覺
-   * (對齊 display MultiPersonDisplay overflow popover Tag avatar SSOT)。
+   * (對齊 view path MultiPersonDisplay overflow popover Tag avatar SSOT)。
    */
   renderHiddenTag?: (item: { value: string; label: string }) => React.ReactNode
   onRemove?: (value: string) => void
@@ -297,7 +297,7 @@ function OverflowTagList({ containerRef, items, size, wrap, renderTag, renderHid
       {items.map((item, i) => (
         // 2026-05-14 I5 fix(per codex M31 verdict + user 抓「avatar stack 堆疊方向不一致」):
         // 加 z-index per-index — 前 item z 高(對齊 MultiPersonDisplay zIndex: visible.length - i
-        // canonical + MUI AvatarGroup surplus pattern)。display + edit stack 堆疊方向統一。
+        // canonical + MUI AvatarGroup surplus pattern)。view + edit stack 堆疊方向統一。
         <div key={item.value} ref={el => { tagEls.current[i] = el }} className={cn('shrink-0 max-w-full', tagWrapperClassName)} style={{ zIndex: items.length - i }}>{renderTag(item, i)}</div>
       ))}
       <div ref={overflowEl} className={cn('shrink-0', overflowWrapperClassName)}>
@@ -316,9 +316,9 @@ function OverflowTagList({ containerRef, items, size, wrap, renderTag, renderHid
   )
 }
 
-// ── Internal tag-stack renderer (consumed by ReadonlyMultiSelect / mode='display') ───
+// ── Internal tag-stack renderer (consumed by ReadonlyMultiSelect / mode='view') ───
 //
-// Phase B2(2026-05-05):原 ComboboxDisplay sub-component 已 retire,改 inline `<Combobox mode="display">`。
+// Phase B2(2026-05-05):原 ComboboxDisplay sub-component 已 retire,改 inline `<Combobox mode="view">`。
 // 本 helper 只負責 tag-stack 內容渲染(OverflowTagList 消費),不包 Field wrapper。
 function ComboboxTagStack({
   value, options, tagSize = 'md', wrap = false, containerRef: externalRef, disabled = false,
@@ -328,7 +328,7 @@ function ComboboxTagStack({
 }) {
   const emptyDisplay = useFieldEmptyDisplay()
   const ownRef = React.useRef<HTMLDivElement>(null)
-  if (!value || value.length === 0) return <span className={fieldEmptyColorClass(disabled ? 'disabled' : 'display')}>{emptyDisplay}</span>
+  if (!value || value.length === 0) return <span className={fieldEmptyColorClass(disabled ? 'disabled' : 'view')}>{emptyDisplay}</span>
   const items = value.map(v => ({ value: v, label: options?.find(o => o.value === v)?.label ?? v }))
   const disabledClass = disabled ? 'bg-disabled text-fg-disabled' : undefined
 
@@ -345,10 +345,10 @@ function ComboboxTagStack({
   )
 
   if (externalRef) return content
-  // 2026-05-05 v9 fix(Bug 4):display path 內 wrapper 必須 `flex-1 min-w-0`,否則在 cell flex
+  // 2026-05-05 v9 fix(Bug 4):view path 內 wrapper 必須 `flex-1 min-w-0`,否則在 cell flex
   // parent 下不認領完整可用寬度 → OverflowTagList 量得寬度小於 edit path → 顯 `+N` 多於 edit。
   // edit path tagAreaRef wrapper 已是 `flex-1 min-w-0`(NativeCombobox/CustomCombobox line 258 / 354),
-  // display 必對稱才 SSOT。
+  // view 必對稱才 SSOT。
   // 2026-05-15 F1 Q3 fix(per user round 3 verbatim「單人選取時 Tag 越界蓋 indicator」):
   // `overflow-visible` → `overflow-hidden` 讓 narrow cell width 強制 clip(Tag 內建 truncate
   // 處理 text ellipsis,stack `-ml-0.5` 負 margin 在 wrapper 內不受影響)。對齊
@@ -384,8 +384,9 @@ export interface ComboboxProps {
   /** 啟用搜尋 */
   searchable?: boolean
   /** Loading state(2026-05-15 audit B fix per user verbatim「dropdown 隨時可開,讀取在 panel 中間 CircularProgress」)。
-   *  Forward 給 SelectMenu primitive SSOT;dropdown 開啟時取代 options 顯 CircularProgress + loadingText。
-   *  Trigger 不變(user 隨時可開)。對齊 MUI Autocomplete `loadingText` + Field SSOT + Empty 元件 compose。*/
+   *  Forward 給 SelectMenu primitive SSOT;spinner 只在無可顯示選項時佔 CommandEmpty slot 顯 CircularProgress
+   *  (已有 options 保留顯示,不取代)。Trigger 不變(user 隨時可開)。
+   *  對齊 MUI Autocomplete「loading 只在無 suggestions 時顯 loadingText」+ Field SSOT + Empty 元件 compose。*/
   loading?: boolean
   /** 搜尋框位置：menu（浮層內，預設）或 trigger（inline input） */
   searchIn?: 'menu' | 'trigger'
@@ -397,6 +398,14 @@ export interface ComboboxProps {
   emptyPlaceholder?: string
   /** 搜尋無結果提示(2026-07-04 Q4 拍板接線)— forward SelectMenu primitive SSOT(default「沒有符合的選項」) */
   emptyText?: string
+  /** 可建立新選項(creatable tag,2026-07-18 user 拍板 forward)—— 搜尋非空且無完全同名既有選項時,
+   *  dropdown 顯 create row(Plus + `createLabel`);forward 給底層 SelectMenu(邏輯/顯示/互動 SSOT 住在 SelectMenu)。
+   *  僅 searchable 桌機路徑生效(需打字);native mobile 路徑不支援。對齊 Ant tags / react-select Creatable。 */
+  creatable?: boolean
+  /** 建立新選項 callback(forward SelectMenu `onCreate`)。 */
+  onCreate?: (value: string) => void
+  /** create row 文字格式(forward SelectMenu `createLabel`,預設「直接使用「{query}」」)。 */
+  createLabel?: (query: string) => string
   /** a11y:無 Field wrapper 時提供 role='combobox' 的 accessible name(axe aria-input-field-name) */
   'aria-label'?: string
   /** Initial open state(uncontrolled)— 對齊 Select.defaultOpen / Radix Popover canonical。
@@ -416,8 +425,8 @@ export interface ComboboxProps {
   tagRenderer?: (item: { value: string; label: string }, onRemove: () => void) => React.ReactNode
   /**
    * 2026-05-14 I4 fix:Optional renderer for hidden items in `+N` overflow popover
-   * (對齊 display MultiPersonDisplay overflow popover 含 avatar SSOT)。PeoplePicker stack
-   * pass 此 prop 讓 hidden items 顯 avatar + name(同 display path)。Default fallback
+   * (對齊 view path MultiPersonDisplay overflow popover 含 avatar SSOT)。PeoplePicker stack
+   * pass 此 prop 讓 hidden items 顯 avatar + name(同 view path)。Default fallback
    * `<Tag>{label}</Tag>` 純文字 backward-compat。
    */
   renderHiddenTag?: (item: { value: string; label: string }) => React.ReactNode
@@ -477,8 +486,8 @@ export interface ComboboxProps {
   visibleCountOverride?: number
   /**
    * Display 是否渲 ChevronDown + Field naked wrapper(D-path opt-in,2026-05-08)
-   * — DataTable cell display↔edit 像素級對齊用。預設 false(裸 tag stack,backward compat)。
-   * 設 true 時 display 走 fieldWrapperStyles(naked variant)+ ItemSuffix ChevronDown,
+   * — DataTable cell view↔edit 像素級對齊用。預設 false(裸 tag stack,backward compat)。
+   * 設 true 時 view 走 fieldWrapperStyles(naked variant)+ ItemSuffix ChevronDown,
    * 與 edit 同 DOM 結構,消除 Layer-B padding mismatch。
    */
   showDisplayEndIcon?: boolean
@@ -487,7 +496,7 @@ export interface ComboboxProps {
 // 2026-05-18 改 import ICON_SIZE SSOT(per user『做完』approval,消除 M17 違反)
 const getIconSize = (size: string) => ICON_SIZE[size as 'sm' | 'md' | 'lg']
 
-// ── Shared readonly/disabled/display render ─────────────────────────────────
+// ── Shared readonly/disabled/view render ─────────────────────────────────
 
 function ReadonlyMultiSelect({
   mode, variant: variantProp, width, size, options, value, wrap, className, showDisplayEndIcon = false,
@@ -504,13 +513,13 @@ function ReadonlyMultiSelect({
   const containerRef = React.useRef<HTMLDivElement>(null)
   const hasTags = (value?.length ?? 0) > 0
 
-  // mode='display'(Phase B2 2026-05-05):純內容輸出 — tag stack 不包 Field wrapper / 不 reserve 高度。
+  // mode='view'(Phase B2 2026-05-05):純內容輸出 — tag stack 不包 Field wrapper / 不 reserve 高度。
   //   對齊原 ComboboxDisplay sub-component(retired)。
   //   Opt-in(showDisplayEndIcon=true,2026-05-08 D-path):Field naked wrapper + ItemSuffix ChevronDown,
-  //   與 edit 同結構消除 cell display↔edit 像素偏移(Layer-B padding mismatch)。
-  if (resolvedMode === 'display') {
+  //   與 edit 同結構消除 cell view↔edit 像素偏移(Layer-B padding mismatch)。
+  if (resolvedMode === 'view') {
     if (!showDisplayEndIcon) {
-      // 2026-05-14 I2 fix(spec contract (e) display typography canonical):empty bare span 套
+      // 2026-05-14 I2 fix(spec contract (e) view typography canonical):empty bare span 套
       // `fieldDisplayTextClass(sz)`(sm/md→text-body,lg→text-body-lg)— 對齊跨 Field family 統一。
       if (!hasTags) return <span className={cn(fieldDisplayTextClass(sz), fieldEmptyColorClass(resolvedMode), className)}>{emptyDisplay}</span>
       return (
@@ -519,8 +528,8 @@ function ReadonlyMultiSelect({
     }
     return (
       <div
-        className={cn(fieldWrapperStyles({ mode: 'display', variant, width, size: sz }), hasTags && tagPadding[sz], className)}
-        data-field-mode="display"
+        className={cn(fieldWrapperStyles({ mode: 'view', variant, width, size: sz }), hasTags && tagPadding[sz], className)}
+        data-field-mode="view"
       >
         {hasTags ? (
           <ComboboxTagStack value={value} options={options} tagSize={sz} wrap={wrap} />
@@ -538,8 +547,8 @@ function ReadonlyMultiSelect({
     <div ref={containerRef}
       className={cn(fieldWrapperStyles({ mode: resolvedMode, variant, width, size: sz }), hasTags && tagPadding[sz],
         // 2026-05-18 #6A Round 1 Step 1/4(per user 拍板「決策6選a」+ codex M31 Step 5 verdict cite combobox.tsx:451):
-        // readonly/disabled path 對齊 L293 display wrapper 已 ship 的 overflow-hidden fix。
-        // M10 propagation:原 overflow-visible 讓 readonly tag 越界蓋 indicator,跟 display 不對稱。
+        // readonly/disabled path 對齊 L293 view wrapper 已 ship 的 overflow-hidden fix。
+        // 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)}
@@ -586,7 +595,7 @@ function NativeCombobox({
   const fieldCtx = useFieldContext()
   const disabled = useResolvedFieldDisabled(disabledProp)
   const variant: FieldVariantInternal = useResolvedFieldVariant(variantProp)
-  // 2026-06-08 SSOT:mode 經 useResolvedFieldMode;修 <Field mode="display"> 漏 cascade
+  // 2026-06-08 SSOT:mode 經 useResolvedFieldMode;修 <Field mode="view"> 漏 cascade
   const resolvedMode = useResolvedFieldMode({ mode, disabled })
   const iconSize = getIconSize(size)
   const showClear = clearable && value.length > 0 && resolvedMode === 'edit'
@@ -633,7 +642,7 @@ function NativeCombobox({
       onClick={(e) => { if (e.target === e.currentTarget) { selectRef.current?.showPicker?.(); selectRef.current?.focus() } }}>
       {/* 2026-05-18 F2 sync(per user verbatim「modifying 修好 PeoplePicker stack 後改壞 Combobox tag display」
           + 「tag 應該要判斷所在空間最多可以呈現幾個tag(包括＋n)去自動判斷何時要變成+n」):
-          edit path tagArea 對齊 display path L293 已 ship 的 `overflow-hidden` fix。原 `overflow-visible`
+          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 }}
@@ -670,6 +679,9 @@ function CustomCombobox({
   searchAriaLabel = '搜尋選項', // i18n-allow: DS default
   emptyPlaceholder = '選擇…', // i18n-allow: DS default
   emptyText,
+  creatable = false,
+  onCreate,
+  createLabel,
   defaultOpen = false,
   onOpenChange,
   __triggerRef,
@@ -688,7 +700,7 @@ function CustomCombobox({
   const fieldCtx = useFieldContext()
   const error = useResolvedFieldInvalid(errorProp)
   const disabled = useResolvedFieldDisabled(disabledProp)
-  // 2026-06-08 SSOT:mode 經 useResolvedFieldMode;修 <Field mode="display"> 漏 cascade
+  // 2026-06-08 SSOT:mode 經 useResolvedFieldMode;修 <Field mode="view"> 漏 cascade
   const resolvedMode = useResolvedFieldMode({ mode, disabled })
   const variant: FieldVariantInternal = useResolvedFieldVariant(variantProp)
   const iconSize = getIconSize(size)
@@ -797,7 +809,7 @@ function CustomCombobox({
         if (e.key === 'Escape') setOpen(false)
       }}>
       {/* 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 display + L451 readonly + L518 native edit 已 ship 的 overflow-hidden fix。
+          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 }}>
         {value.length > 0 ? (
@@ -863,6 +875,9 @@ function CustomCombobox({
       value={value}
       onValueChange={onChange as (value: string | string[]) => void}
       multiple
+      creatable={creatable}
+      onCreate={onCreate}
+      createLabel={createLabel}
       searchable={searchable && searchIn === 'menu'}
       searchPlaceholder={searchPlaceholder}
       size={size}

package/src/components/Command/command.spec.md

@@ -20,7 +20,7 @@ Command 是**搜尋 + 鍵盤導覽的指令清單**——提供搜尋框、分
 
 **實作基礎**：shadcn passthrough——基於 cmdk + Radix Dialog（Command Palette 模式）。本 DS 保留 shadcn 原結構,視覺樣式以 inline Tailwind class 直接掛在 cmdk primitive 上（`command.tsx`），token 值對齊（非結構繼承）MenuItem / Input / Empty 的 canonical token——改 MenuItem 不會自動連動 Command。
 
-**分類**：Internal primitive——由 SelectMenu 消費（Select / Combobox / PeoplePicker 透過 SelectMenu 使用）。App 不直接使用 Command;若要 Command Palette 類 UX,用本檔 export 的 `CommandDialog`(cmdk + Radix Dialog 包裝,showcase「CommandPalette」story 消費)。
+**分類**：Internal primitive——由 SelectMenu 消費（Select / Combobox / PeoplePicker 透過 SelectMenu 使用）。App **不從 root barrel front-door 直接 import** Command 家族;若要 Command Palette 類 UX,經 per-component subpath `@qijenchen/design-system/components/Command` 取用 `CommandDialog`(自行包裝確認後使用,對齊 `.claude/rules/ui-development.md`「Root barrel front-door 排除」— internal ≠ 禁用;cmdk + Radix Dialog 包裝,showcase「CommandPalette」story 消費)。
 
 **Layout Family**：非上述 family — composite / multi-section（多區塊組合，自 own layout）。
 
@@ -66,7 +66,7 @@ Command 通常由 `SelectMenu` 或自訂 Command Palette 元件消費——直
 - **SelectMenu**：Select / Combobox / PeoplePicker 的 searchable 浮層（**由 Field 觸發**,帶有 input field + 選中值回填）
 - **獨立 Command Palette**（Cmd+K）：也用 Command 但**不在 Field 觸發**——透過全域快捷鍵開啟,用於跨頁面搜尋 / 快速動作入口
 
-兩者底層都消費 Command。Field 場景用 SelectMenu（已處理 input binding）；非 Field 場景(Cmd+K)用 `CommandDialog`(cmdk + Radix Dialog 包裝)。
+兩者底層都消費 Command。Field 場景用 SelectMenu（已處理 input binding）；非 Field 場景(Cmd+K)用 `CommandDialog`(經 subpath `@qijenchen/design-system/components/Command` 取用,cmdk + Radix Dialog 包裝)。
 
 ---
 
@@ -97,7 +97,7 @@ Consumer 無需額外處理 a11y,保留 cmdk 原結構 + 使用 `<CommandInput>`
 - **Disabled item**:`<CommandItem disabled>` 透過 cmdk 內建支援,視覺繼承 MenuItem SSOT(`text-fg-disabled` + `aria-disabled=true` + 鍵盤導覽自動 skip + Enter 不觸發 onSelect)。skip 是「不進導覽清單」(cmdk `:not([aria-disabled="true"])` selector)— ↑/↓ 直接跳到下一個可選項,無中途 highlight。
 - **Group heading 不可選中**:heading 是 `aria-hidden` 裝飾 div(group container `role="presentation"`),不參與導覽與選取;SR 經 items wrapper `role="group"` + `aria-labelledby` 取得群組語意。
 - **Empty 後持續打字**:cmdk 每個 keystroke 重新過濾(`filtered.count` 驅動),`<CommandEmpty>` 持續顯示直到有 match;input 不鎖、不清空。
-- **Loading**:Command 本身非 async surface。async option fetch 應由 consumer(SelectMenu / Cmd+K palette)在外層處理 — 將 `<CommandList>` body 切換為 `<Empty icon={<CircularProgress size={48}/>}/>`(對齊 `empty.spec.md`「現有消費者」SelectMenu loading row SSOT,禁止事項見其「禁止事項」loading 條)。Command primitive 不獨立 own loading prop。
+- **Loading**:Command 本身非 async surface。async option fetch 應由 consumer(SelectMenu / Cmd+K palette)在外層處理 — 在 `<CommandEmpty>` slot 內渲 `<Empty icon={<CircularProgress size={48}/>}/>`(spinner 只在無可顯示選項時出現;已有 options 保留顯示,不取代 — 對齊 `select.spec.md`「Loading」2026-07-04 拍板措辭 + `empty.spec.md`「現有消費者」SelectMenu loading SSOT,禁止事項見其「禁止事項」loading 條)。Command primitive 不獨立 own loading prop。
 - **Empty(no results)**:`<CommandEmpty>` 自動偵測 search filter result = 0 時渲;consumer 必傳 fallback 文案(預設 cmdk 不渲)。
 - **Dark mode / density**:Command 的 inline Tailwind class 直接消費 semantic token（`bg-neutral-hover` / `text-fg-muted` / `text-fg-disabled` 等），token 在 dark mode 自動切值——非透過 MenuItem / Input / Empty primitive 連動。density 不獨立 own（由 consumer SelectMenu 控）。
 

package/src/components/Command/command.tsx

@@ -48,7 +48,7 @@ const CommandInput = React.forwardRef<
   React.ElementRef<typeof CommandPrimitive.Input>,
   React.ComponentPropsWithoutRef<typeof CommandPrimitive.Input>
 >(({ className, ...props }, ref) => (
-  <div className="flex items-center border-b border-divider px-3" cmdk-input-wrapper="">
+  <div className="flex shrink-0 items-center border-b border-divider px-3" cmdk-input-wrapper="">
     <Search className="mr-2 h-4 w-4 shrink-0 text-fg-muted" />
     <CommandPrimitive.Input
       ref={ref}
@@ -80,7 +80,14 @@ const CommandList = React.forwardRef<
   React.ElementRef<typeof CommandPrimitive.List>,
   React.ComponentPropsWithoutRef<typeof CommandPrimitive.List>
 >(({ className, ...props }, ref) => (
-  <ScrollArea className="max-h-[var(--menu-max-height,300px)]">
+  /* @story-baseline: overlay-surface.spec.md#Viewport-aware-scroll-chain-invariant(M25 SSOT owner)
+      owner spec: overlay-surface.spec.md:34/53/347-362 —— 「浮層 body 永遠 flex-1 min-h-0 overflow-y-auto;
+        中間 wrapper 都必 flex flex-col h-full min-h-0;viewport 太小 body 內壓縮捲動」。
+      conflicting code(修前): 本 ScrollArea 固定 max-h-300 無 flex-1 → 在夾住的 SelectMenu PopoverContent
+        (max-h=available-height)內撐破外殼、底部選項被裁(320px viewport 實測 bottom 425 > 320 溢出)。
+      修: 加 flex-1 min-h-0(對齊 M25 canonical + HoverCard/Popover),max-h-300 降為上限。Command root 已
+        `flex h-full flex-col`(command.tsx:23)= chain 完整;非 flex 容器內 flex-1 為 no-op(spec:34 backward compat)。 */
+  <ScrollArea className="flex-1 min-h-0 max-h-[var(--menu-max-height,300px)]">
     <CommandPrimitive.List ref={ref} className={cn("overflow-x-hidden", className)} {...props} />
   </ScrollArea>
 ))