@qijenchen/design-system 0.1.0-beta.13 → 0.1.0-beta.131

package/src/components/Input/input.principles.stories.tsx

@@ -0,0 +1,260 @@
+// @principles-rationale: UsageGuidance merges WhenToUse + WhenNotToUse into single 使用指引 story per refactor task (2026-04-26)
+import React from 'react'
+import LinkTo from '@storybook/addon-links/react'
+import type { Meta, StoryObj } from '@storybook/react'
+import {
+  Search, Mail, Lock, Globe, X, Eye, EyeOff, AlertCircle, CheckCircle2,
+} from 'lucide-react'
+import { Input } from './input'
+import { Tooltip, TooltipContent, TooltipTrigger } from '@/design-system/components/Tooltip/tooltip'
+
+const meta: Meta = {
+  title: 'Design System/Components/Input/設計原則',
+  parameters: { layout: 'padded' },
+}
+export default meta
+type Story = StoryObj
+
+// ── Helpers ───────────────────────────────────────────────────────────────────
+
+const Rule = ({
+  title, note, children,
+}: {
+  title: string; note?: string; children: React.ReactNode
+}) => (
+  <div className="mb-14">
+    <h3 className="text-body font-bold text-foreground mb-1">{title}</h3>
+    {note && <p className="text-caption text-fg-muted mb-5 max-w-[720px] leading-relaxed">{note}</p>}
+    <div className="flex flex-col gap-3 max-w-md">{children}</div>
+  </div>
+)
+
+const Label = ({ children, warn }: { children: React.ReactNode; warn?: boolean }) => (
+  <p className={`text-footnote leading-normal ${warn ? 'text-error font-medium' : 'text-fg-muted'}`}>{children}</p>
+)
+
+const Section = ({ title, children }: { title: string; children: React.ReactNode }) => (
+  <section className="mb-12">
+    <h2 className="text-h3 font-bold text-foreground mb-4 pb-2 border-b border-border">{title}</h2>
+    {children}
+  </section>
+)
+
+// ── Stories ───────────────────────────────────────────────────────────────────
+
+export const UsageGuidance: Story = {
+  name: '使用指引',
+  render: () => (
+    <div>
+      <Section title="何時用">
+        <div className="prose prose-sm max-w-prose mb-8">
+          <p>適合 Input 的真實業務場景(點擊跳轉「展示」頁範例):</p>
+          <ul className="space-y-1">
+            <li><LinkTo kind="Design System/Components/Input/展示" name="四模式"><span className="text-primary hover:text-primary-hover font-medium cursor-pointer">商品名稱欄位的編輯 / 純展示 / 唯讀 / 停用四模式</span></LinkTo></li>
+            <li><LinkTo kind="Design System/Components/Input/展示" name="三種尺寸"><span className="text-primary hover:text-primary-hover font-medium cursor-pointer">搜尋列 — 輸入框與按鈕並排等高</span></LinkTo></li>
+            <li><LinkTo kind="Design System/Components/Input/展示" name="尾端操作"><span className="text-primary hover:text-primary-hover font-medium cursor-pointer">密碼顯示切換 / 搜尋清除等尾端操作</span></LinkTo></li>
+            <li><LinkTo kind="Design System/Components/Input/展示" name="錯誤狀態"><span className="text-primary hover:text-primary-hover font-medium cursor-pointer">Email 格式錯誤的驗證回饋</span></LinkTo></li>
+          </ul>
+          <p className="text-fg-muted mt-3">判斷不確定時:對照 spec.md「何時用 / 何時不用」段;若仍不符,改用近親元件(見下方 vs 近親 段)。</p>
+        </div>
+      </Section>
+
+      <Section title="何時不用 + 替代方案">
+        <Rule
+          title="❌ 不用 Input startIcon 表達狀態(有效 / 無效)"
+          note="startIcon 是「欄位用途」識別符(郵件、搜尋、網址)。狀態用邊框 + help text。Stripe 信卡欄的有效狀態由邊框顏色傳達"
+        >
+          <Label warn>startIcon = 欄位身份,狀態由邊框 + help text 傳達</Label>
+        </Rule>
+      </Section>
+
+      <Section title="vs 近親元件">
+        <Rule
+          title="❌ 不用 Input 顯示需要格式化的資料 → NumberInput / DatePicker"
+          note="數字、日期、金額都需要格式化(千分位、時區、幣別符號)。每種資料類型有專屬元件,擁有該類型的格式化邏輯(唯一真實來源),同時服務 Form 和 DataTable"
+        >
+          <Input defaultValue="1234567" placeholder="金額" aria-label="金額（不建議用 Input）" />
+          <Label warn>↑ 金額 → 用 NumberInput + currency mode(自動 $1,234,567)</Label>
+          <Input defaultValue="2026-04-18" placeholder="日期" aria-label="日期（不建議用 Input）" />
+          <Label warn>↑ 日期 → 用 DatePicker(in-locale 顯示、避免時區誤判)</Label>
+          <Input defaultValue="1234567" placeholder="數量" aria-label="數量（不建議用 Input）" />
+          <Label warn>↑ 數字 → 用 NumberInput(千分位、min/max、step)</Label>
+        </Rule>
+
+        <Rule
+          title="✅ Input 只用於純文字——沒有格式化需求的 value"
+          note="姓名、URL、搜尋字串、email。格式化邏輯是 identity(value → value)"
+        >
+          <Input placeholder="姓名" defaultValue="Ada Chen" aria-label="姓名" />
+          <Input startIcon={Globe} defaultValue="https://example.com" aria-label="網址" />
+          <Input startIcon={Search} placeholder="搜尋..." aria-label="搜尋" />
+        </Rule>
+      </Section>
+    </div>
+  ),
+}
+
+export const ModeRule: Story = {
+  name: '模式選擇',
+  render: () => (
+    <div>
+      <Rule
+        title="edit — 表單中可編輯的欄位(預設)"
+        note="Focus 時邊框變 primary,使用者正在輸入或修改"
+      >
+        <Input defaultValue="Wireless Bluetooth Headphones" aria-label="商品名稱" />
+      </Rule>
+
+      <Rule
+        title="readonly — 表單中顯示但當下不可編輯"
+        note="同 edit 高度(neutral-2 底色、無邊框),確保與其他欄位並排對齊。常見場景:viewing mode、送出後鎖定但仍在表單脈絡"
+      >
+        <Input mode="readonly" value="alice@example.com" aria-label="Email（唯讀）" />
+      </Rule>
+
+      <Rule
+        title="disabled — 外部條件造成無法編輯"
+        note="停用原因不在 input 內放 info icon——由外部 Tooltip 或 Form help text 承擔。視覺:灰化文字 + cursor-not-allowed"
+      >
+        <Tooltip>
+          <TooltipTrigger asChild>
+            <div>
+              <Input mode="disabled" defaultValue="僅付費方案可用" aria-label="付費方案欄位（停用）" />
+            </div>
+          </TooltipTrigger>
+          <TooltipContent>此欄位在免費方案中不可編輯</TooltipContent>
+        </Tooltip>
+      </Rule>
+
+      <Rule
+        title="❌ 不用 readonly 作為 DataTable cell"
+        note="readonly 有底色 chrome(bg-readonly),密集列表會顯得鬆散。Table cell 用 `<Input mode='view'>`(Model A:edit 幾何減 chrome —— 保留 px 與高度,只拔 border/bg;cell 內經 naked variant 由 host cell 供 padding)"
+      >
+        <Input mode="readonly" value="alice@example.com" aria-label="Email（資料表誤用示範）" />
+        <Label warn>↑ 在 table cell 中有多餘底色 chrome → 用 &lt;Input mode=&quot;view&quot; /&gt;</Label>
+      </Rule>
+    </div>
+  ),
+}
+
+export const StartIconRule: Story = {
+  name: 'startIcon 語意',
+  render: () => (
+    <div>
+      <Rule
+        title="startIcon 描述 input 的「用途」,不是 value 的類型"
+        note="icon 幫助使用者一眼辨識這個欄位要填什麼——搜尋、Email、密碼、網址等。與 Button 的 startIcon 同理(描述動作),這裡描述欄位身份"
+      >
+        <Input startIcon={Search} placeholder="搜尋商品..." aria-label="搜尋商品" />
+        <Input startIcon={Mail} defaultValue="alice@example.com" aria-label="Email" />
+        <Input startIcon={Lock} type="password" defaultValue="secret-123" aria-label="密碼" />
+        <Input startIcon={Globe} placeholder="https://example.com" aria-label="網址" />
+      </Rule>
+
+      <Rule
+        title="❌ startIcon 不可隨 value 變化"
+        note="icon 是「身份」不是「狀態」——value 變了但欄位用途沒變,icon 不該跟著跳動。狀態回饋用 error border 或 Form help text"
+      >
+        <Input startIcon={AlertCircle} defaultValue="invalid-email" aria-label="Email（錯誤圖示誤用）" />
+        <Input startIcon={CheckCircle2} defaultValue="alice@example.com" aria-label="Email（成功圖示誤用）" />
+        <Label warn>↑ 用 icon 切換暗示「有效/無效」——status 應該走邊框和 help text,不佔 startIcon 語意槽</Label>
+      </Rule>
+    </div>
+  ),
+}
+
+export const EndActionRule: Story = {
+  name: 'endAction 適用場景',
+  render: () => {
+    const [showPwd, setShowPwd] = React.useState(false)
+    const [query, setQuery] = React.useState('Bluetooth')
+    return (
+      <div>
+        <Rule
+          title="endAction 是「可點擊的動作」——不是狀態指示"
+          note="典型場景:顯示/隱藏密碼、清除內容。都是「使用者可以按下」的操作。狀態指示(error、loading、valid)不屬於這個槽位"
+        >
+          <Input
+            type={showPwd ? 'text' : 'password'}
+            defaultValue="my-secret-123"
+            aria-label="密碼"
+            endAction={{
+              icon: showPwd ? EyeOff : Eye,
+              label: showPwd ? '隱藏密碼' : '顯示密碼',
+              onClick: () => setShowPwd(!showPwd),
+            }}
+          />
+          <Input
+            startIcon={Search}
+            value={query}
+            onChange={(e) => setQuery(e.target.value)}
+            aria-label="搜尋商品"
+            endAction={query ? { icon: X, label: '清除搜尋', onClick: () => setQuery('') } : undefined}
+          />
+        </Rule>
+
+        <Rule
+          title="清除按鈕只在有值時出現,消失後不佔位"
+          note="條件渲染 endAction,input 寬度自然擴展。避免永遠保留一個看起來可按但沒作用的 icon"
+        >
+          <Input
+            startIcon={Search}
+            value=""
+            placeholder="輸入後會出現清除按鈕"
+            aria-label="搜尋商品（空值）"
+            readOnly
+          />
+          <Input
+            startIcon={Search}
+            defaultValue="Bluetooth"
+            aria-label="搜尋商品（有值）"
+            endAction={{ icon: X, label: '清除搜尋', onClick: () => {} }}
+          />
+        </Rule>
+
+        <Rule
+          title="❌ endAction 不放狀態 / error icon"
+          note="狀態資訊由邊框顏色 + Form help text 傳達。如果放 AlertCircle 在 endAction,使用者會以為可以點擊處理錯誤"
+        >
+          <Input
+            error
+            defaultValue="invalid-email@"
+            aria-label="Email（錯誤狀態圖示誤用）"
+            endAction={{ icon: AlertCircle, label: '錯誤', onClick: () => {} }}
+          />
+          <Label warn>↑ 錯誤已由紅邊框傳達,endAction 放 AlertCircle 會讓使用者誤以為可點擊解決</Label>
+        </Rule>
+      </div>
+    )
+  },
+}
+
+export const ErrorRule: Story = {
+  name: '錯誤呈現',
+  render: () => (
+    <div>
+      <Rule
+        title="Error 只用邊框 + 外部 help text"
+        note="紅色邊框已足夠傳達「這個欄位有問題」,具體訊息由 Form 層的 help text 補充。Input 尾部不放 ⚠️ 狀態 icon"
+      >
+        <div>
+          <Input error defaultValue="invalid-email@" aria-label="Email（錯誤狀態）" />
+          <p className="text-caption text-error mt-1">請輸入有效的 email 地址</p>
+        </div>
+      </Rule>
+
+      <Rule
+        title="❌ 不在 input 尾部放 ⚠️ / ✅ 狀態 icon"
+        note="這個位置是 endAction(可點擊動作),放 icon 既無法點擊又稀釋了 action 槽的語意"
+      >
+        <Input
+          error
+          defaultValue="invalid-email@"
+          aria-label="Email（錯誤狀態圖示誤用）"
+          endAction={{ icon: AlertCircle, label: '錯誤', onClick: () => {} }}
+        />
+        <Label warn>↑ 邊框已紅,再加尾部 icon = 雙重傳達 + 佔用 action 槽</Label>
+      </Rule>
+    </div>
+  ),
+}

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

@@ -1,8 +1,12 @@
 ---
 component: Input
 family: 4
-variants: {}
-sizes: {}
+variants:
+  default: { when: "Field wrapper 完整 chrome(bg-surface + border + hover/focus 回饋)— 表單 / Field 內嵌" }
+sizes:
+  sm: { when: "field-height 28、icon 16、text-body" }
+  md: { when: "default 一般表單(field-height 32、icon 16)" }   # ★ default
+  lg: { when: "touch / 大字級(field-height 36、icon 20、text-body-lg)" }
 traits:
   - hasInteractiveStates
   - isInputLike
@@ -13,7 +17,6 @@ benchmark:
   - Carbon TextInput: github.com/carbon-design-system/carbon/tree/main/packages/react/src/components/TextInput
 ---
 
-<!-- @benchmark-cited: D5 retrofit 2026-05-18 — body claims marked per-claim @benchmark-unverified inline; canonical source URLs in frontmatter benchmark list. -->
 
 # Input 設計原則
 
@@ -23,7 +26,7 @@ Input 是**純文字**的輸入與顯示元件。格式化邏輯為 identity（v
 
 共用規則見 `../Field/field-controls.spec.md`。本文件只記錄 Input 特有的原則。
 
-**Layout Family**：CLAUDE.md 4-Family Model **Family 4（Field control layout）** 消費者。結構繼承 `components/Field/field-controls.spec.md` 的 `fieldWrapperStyles + [startIcon?] [<editable>] [endAction?]` 規格,視覺對齊 Family 1（Menu item）讓 SelectMenu trigger + options 連續一致。
+**Layout Family**：本元件是 `components/Field/field-controls.spec.md` 所擁有的 **Family 4（Field control layout）** 消費者。結構繼承其 `fieldWrapperStyles + [startIcon?] [<editable>] [endAction?]` 規格,視覺對齊 Family 1（Menu item）讓 SelectMenu trigger + options 連續一致。
 
 ---
 
@@ -84,19 +87,21 @@ startIcon 不隨 value 變化——它描述的是 input 的用途，不是 valu
 
 清除按鈕消失後不佔位——input 自然擴展。
 
+endAction(host 內嵌 inline action)vs 獨立 `<Button iconOnly>` 的分界詳 `../../patterns/element-anatomy/inline-action.spec.md`「Inline Action vs Button iconOnly」predicate。
+
 ---
 
-## Display
+## View
 
-`<Input mode="display">` 是 identity 顯示：
+`<Input mode="view">` 是 identity 顯示：
 - 有值：原樣輸出
-- null / undefined / 空字串：`—`（em dash），`text-fg-muted`
+- null / undefined / 空字串：半形 `-`（hyphen），`text-foreground`（view/readonly 供檢視值同色;disabled → fg-disabled）
 
 ---
 
 ## Loading
 
-`loading?: boolean`(Field SSOT,詳 `Field/field-controls.spec.md` L70-115):右側 endAction 自動顯 `<CircularProgress/>` + `aria-busy="true"`;input 維持可編輯(Ant Input.Search editable 派,反 Material readonly 派,適合 search debounce)。
+`loading?: boolean`(Field SSOT,詳 `Field/field-controls.spec.md`「Loading state」段 ~L93-138):右側 endAction 自動顯 `<CircularProgress/>` + `aria-busy="true"`;input 維持可編輯(Ant Input.Search editable 派,反 Material readonly 派,適合 search debounce)。
 
 ## 禁止事項
 
@@ -107,7 +112,7 @@ startIcon 不隨 value 變化——它描述的是 input 的用途，不是 valu
 
 ## 邊界案例
 
-- **Disabled**:`disabled` prop 由 Field SSOT own(`Field/field-controls.spec.md` State machine 段)。視覺 token:wrapper bg → `bg-fg-disabled-subtle`、text → `text-fg-disabled`(neutral-6,M24 state>emphasis canonical)、startIcon → `text-fg-disabled`、endAction button 自動 disabled、cursor → `cursor-not-allowed`、border 弱化、無 hover/focus ring。`readOnly` 與 `disabled` 視覺分離:readOnly 維持 default text color(可選取複製)、disabled 全面弱化(不可選)。
+- **Disabled**:`disabled` prop 由 Field SSOT own(`Field/field.spec.md`「Field state machine SSOT」段)。視覺 token:wrapper bg → `bg-disabled`(neutral-2)、text → `text-fg-disabled`(neutral-6,M24 state>emphasis canonical)、startIcon → `text-fg-disabled`、endAction 不渲染(僅 edit mode 渲染)、cursor → `cursor-not-allowed`、border 弱化、無 hover/focus ring。`readOnly` 與 `disabled` 視覺分離:readOnly 維持 default text color(可選取複製)、disabled 全面弱化(不可選)。
 - **Loading**:已 codify(見「Loading」段)。`loading=true` 時 endAction slot 自動切 `<CircularProgress/>`,input 仍可編輯(Ant Search 派 idiom)。
 - **Empty(no value)**:placeholder 走 `text-fg-muted`(neutral-7);`disabled + empty` 時 placeholder 切 `text-fg-disabled`(M24 state precedence)。
 - **Dark mode**:走 semantic token 自動 adapt,無 per-component override。
@@ -123,22 +128,17 @@ startIcon 不隨 value 變化——它描述的是 input 的用途，不是 valu
 
 ## Variant(visual chrome,正交於 mode)
 
-Input 有兩個 visual chrome variant,**獨立於 mode**(mode 是 state,variant 是 chrome look):
+Input 有**一個公開** visual chrome variant `default`(+ 一個 `@internal` 的 `naked`),**獨立於 mode**(mode 是 state,variant 是 chrome look):
 
-| Variant | 視覺 | 適用場景 | 世界級對照 |
+| Variant | 原則 | 適用場景 | 世界級對照 |
 |---------|------|---------|-----------|
-| `'default'`(預設) | bg-surface + 明顯 border + hover/focus 回饋 | 表單 / Field 內嵌 / 標準 edit UI | Material Input / Ant Input default |
-| `'bare'` | 透明 chrome,hover / focus 才出現 border;保留 padding / typography / height | **Toolbar inline editing**(FileViewer zoom input / chart config / rich text toolbar number input / Sidebar inline rename) | VS Code settings input / Figma toolbar number / Notion prop input |
+| `'default'`(預設) | 完整 field chrome(背景 + 常態 border + hover/focus 回饋)——明確邀請輸入 | 表單 / Field 內嵌 / 標準 edit UI / toolbar 內小尺寸輸入(如 FileViewer zoom,搭 `size="sm" autoWidth`) | [Material Input](https://github.com/material-components/material-web/blob/main/docs/components/text-field.md) / [Ant Input](https://github.com/ant-design/ant-design/blob/master/components/input/index.en-US.md) default |
 
-**判斷法**:Input 放在表單或 Field 內 → `default`;放在 Toolbar chrome 或 page-body inline → `bare`。
+**透傳**:在 `<Field variant="default">` 內自動繼承 context variant,per-prop override(code:`useResolvedFieldVariant`)。
 
-**`bare` 使用情境的 canonical 要求**:
-- 外層 chrome 必須已提供「這是可編輯」的 affordance(Toolbar 的 icon / prop label / row structure);否則 user 看不到 input chrome 找不到可編輯位置
-- 保留 DS field-height(`h-field-sm/md/lg`)、typography、icon tier、error 視覺——**bare 只動 chrome 不動 sizing**
+> **內部 variant `naked`(@internal,非公開)**：`FieldVariant` 型別含第二值 `'naked'`,但**不是公開 Input variant**——單獨使用無視覺邊界,**不可 standalone**。naked = 剝除 chrome(無 padding / bg / rounded),但 **edit 態仍由自身 border-based state machine 渲染 border + focus 藍框**（field-wrapper.tsx edit×naked compound = cell-as-input state machine;非「完全無 border」、亦非「host cell 自管」）；正被 `FieldSurfaceContext='table-cell'` 取代。consumer 只用 `default`。對齊 public-vs-internal canonical（`ui-development.md`：能直接被使用且用在合理地方才公開）。
 
-**禁止**:
-- ❌ 在**表單** context 用 `bare`——表單需要明確的 field chrome 邀請輸入,bare 會失去 affordance
-- ❌ 拿 `bare` 來當「空白 div 替代品」——variant 不是拿掉視覺的工具,而是特定 chrome context 的 canonical
+> **`bare` variant 退役(2026-07-09,user 拍板)**:原「透明外殼、hover/focus 才顯 border」variant,宣稱用途 = toolbar inline editing,但全 repo(DS + apps + stories)**零真實 JSX 消費者**——FileViewer zoom 實為 `<Input size="sm" autoWidth>`(default variant),非 bare;唯一出現處是一個 ❌ 反例 story + 過時註解。toolbar 小輸入用 `default`(對齊「邊框給互動元素、輸入框就該有邊框」原則),cell-as-input 用 `naked` → `bare` 純冗餘,移除。Benchmark:[Ant Input](https://github.com/ant-design/ant-design/blob/master/components/input/index.en-US.md) 有 `variant="borderless"`(概念合法),但 [Material M3](https://github.com/material-components/material-web/blob/main/docs/components/text-field.md) 只有 filled/outlined、無無邊框變體;我們無真實消費場景 → 不留純預留 variant。詳 `field-types.ts` FieldVariant note。
 
 ---
 
@@ -156,11 +156,13 @@ Input 有兩個 visual chrome variant,**獨立於 mode**(mode 是 state,variant
 - **Tag / Chip rename**:選中 chip 進入 inline edit,寬度跟 chip 內容保持視覺一致
 - **Spreadsheet-like cells**:內容寬度自動跟字數走
 
+**邊界(內容超寬)**:寬度上限 = 父容器可用寬(wrapper `inline-flex w-auto` shrink-to-fit);超過後 input 不再增寬,溢出文字走原生水平捲動。不支援 `field-sizing` 的瀏覽器退化 `w-auto`(fallback 細節見 tsx jsDoc)。
+
 **禁止**:
-- ❌ **表單 Field 內**——Field 欄位必須欄寬對齊,寬度隨值跳動會破壞 grid layout
-- ❌ **搭配 `variant="default"` 放在主表單區**——auto-width 預設搭 `variant="bare"`(toolbar inline 語意),default chrome 自動對齊 Field canonical
+- ❌ **表單 Field 內**——Field 欄位必須遵守共享欄寬；內容驅動寬度會破壞 grid alignment contract
+- ❌ **放在主表單欄位區**——主表單需要穩定的 column sizing；`autoWidth` 只適用 toolbar / page-body inline 場景，使用 `variant="default"`（`bare` 已退役）
 
-**世界級對照**:VS Code settings inline input 用同 pattern;Notion property field、Airtable cell edit 皆 auto-size。 <!-- @benchmark-unverified: see frontmatter benchmark list for canonical DS source URL -->
+Auto-size 只服務 inline editing：view 與 edit 共用內容寬度，避免進入編輯態時欄位突然撐滿整列。
 
 ---
 
@@ -174,15 +176,15 @@ Input 有兩個 visual chrome variant,**獨立於 mode**(mode 是 state,variant
 
 ## A11y 預設
 
-**ARIA / Pattern**:native `<input>` element 預設 a11y;Field wrapper 補 `aria-labelledby` / `aria-invalid` / `aria-describedby`。
+**ARIA / Pattern**:native `<input>` element 預設 a11y。Label 關聯走原生 `<label htmlFor={fieldCtx.id}>` ↔ input `id`(FieldLabel 提供,非 `aria-labelledby`)。Input 自身在 `<input>` 上設 `aria-invalid`(error 時)/ `aria-required` / `aria-describedby`(指向 FieldContext descriptionId)/ `aria-errormessage`(error 時指向 errorId)。
 
 **Keyboard 行為**:
 
 - Tab — focus
 - 字母鍵 — 輸入
-- Esc — 清空(若 clearable + 有值)
+- 一般文字編輯鍵(方向鍵 / Backspace / Delete / 全選)由瀏覽器原生提供
 
-**Focus**:native input focus ring;DS focus-visible ring(`focus-visible:!border-primary`)由 Field wrapper 提供。
+**Focus**:原生 input outline 已關閉（`outline-none`）；focus 視覺提示由 Field wrapper 的 `focus-within:!border-primary` 提供。
 
 **驗證**:Storybook a11y addon panel 應 0 critical violation;鍵盤完整可操作(無需滑鼠)。WCAG AA contrast ≥ 4.5:1(text)/ 3:1(UI)。
 
@@ -190,4 +192,10 @@ Input 有兩個 visual chrome variant,**獨立於 mode**(mode 是 state,variant
 
 > 本節由 `scripts/add-reciprocal-pointers.mjs` 自動維護,列出在 SSOT 語境下指向本 spec 的其他 spec。若要手動補充,寫在本節之前。
 
+- `date-picker.spec.md`
+- `field-controls.spec.md`
+- `form-validation.spec.md`
+- `link-input.spec.md`
+- `number-input.spec.md`
+- `textarea.spec.md`
 - `time-picker.spec.md`

package/src/components/Input/input.stories.tsx

@@ -0,0 +1,150 @@
+import React from 'react'
+import type { Meta, StoryObj } from '@storybook/react'
+import { Search, Eye, EyeOff, X } from 'lucide-react'
+import { Input } from './input'
+import { Field, FieldLabel, FieldError } from '@/design-system/components/Field/field'
+import { Button } from '@/design-system/components/Button/button'
+import { Tooltip, TooltipContent, TooltipTrigger } from '@/design-system/components/Tooltip/tooltip'
+
+const meta: Meta<typeof Input> = {
+  title: 'Design System/Components/Input/展示',
+  component: Input,
+  tags: ['autodocs'],
+  parameters: {
+    docs: { description: { component: '單行文字輸入控制項，提供前後圖示、清除與密碼等常見模式。需要輸入短文字、搜尋詞或單行識別資料時使用；多行內容改用 Textarea。' } },
+  },
+}
+
+export default meta
+type Story = StoryObj<typeof Input>
+
+/* ── 四模式 ── */
+export const Modes: Story = {
+  name: '四模式',
+  render: () => (
+    <div className="flex flex-col gap-6 max-w-sm">
+      <div>
+        <h3 className="text-body font-bold text-foreground mb-2">edit</h3>
+        <p className="text-caption text-fg-muted mb-3">Focus 時邊框變 primary</p>
+        <Input defaultValue="Wireless Bluetooth Headphones" placeholder="輸入商品名稱" aria-label="商品名稱(edit mode demo)" />
+      </div>
+      <div>
+        <h3 className="text-body font-bold text-foreground mb-2">view</h3>
+        <p className="text-caption text-fg-muted mb-3">純展示（read-only 內容）— 無 input chrome / 無互動 affordance</p>
+        <Input mode="view" value="Wireless Bluetooth Headphones" aria-label="商品名稱(view 模式示範)" />
+      </div>
+      <div>
+        <h3 className="text-body font-bold text-foreground mb-2">readonly</h3>
+        <p className="text-caption text-fg-muted mb-3">neutral-2 底色、無邊框、文字正常色</p>
+        <Input mode="readonly" defaultValue="Wireless Bluetooth Headphones" aria-label="商品名稱(readonly mode demo)" />
+      </div>
+      <div>
+        <h3 className="text-body font-bold text-foreground mb-2">disabled</h3>
+        <p className="text-caption text-fg-muted mb-3">停用原因用 Tooltip 或 Form help text 說明</p>
+        <Tooltip>
+          <TooltipTrigger asChild>
+            <div>
+              <Input mode="disabled" defaultValue="Wireless Bluetooth Headphones" aria-label="商品名稱(disabled mode demo)" />
+            </div>
+          </TooltipTrigger>
+          <TooltipContent>此欄位在免費方案中不可用</TooltipContent>
+        </Tooltip>
+      </div>
+    </div>
+  ),
+}
+
+/* ── 尺寸與 Button 對齊 ── */
+export const SizeAlignment: Story = {
+  name: '三種尺寸',
+  render: () => (
+    <div className="flex flex-col gap-4">
+      {(['sm', 'md', 'lg'] as const).map(size => (
+        <div key={size} className="flex items-center gap-3">
+          <Input
+            size={size}
+            defaultValue="Wireless Bluetooth Headphones"
+            aria-label={`商品名稱（${size} 尺寸）`}
+            className="max-w-xs"
+          />
+          <Button variant="primary" size={size}>送出</Button>
+          <span className="text-caption text-fg-muted">size="{size}"</span>
+        </div>
+      ))}
+    </div>
+  ),
+}
+
+/* @story-history: WithIcon retired per F migration 2026-05-15 — anatomy.stories.tsx auto-compile owns icon slot showcase。 */
+/* ── endAction（Inline Action 宣告式 API） ── */
+export const EndAction: Story = {
+  name: '尾端操作',
+  render: () => {
+    const [showPwd, setShowPwd] = React.useState(false)
+    const [query, setQuery] = React.useState('Bluetooth')
+    const [queryLg, setQueryLg] = React.useState('Bluetooth')
+
+    return (
+      <div className="flex flex-col gap-6 max-w-sm">
+        <div>
+          <p className="text-caption text-fg-muted mb-1">顯示/隱藏密碼 — 宣告式 API，Field 自動決定 icon 尺寸和 hover 背景</p>
+          <Input
+            type={showPwd ? 'text' : 'password'}
+            defaultValue="my-secret-123"
+            aria-label="密碼"
+            endAction={{
+              icon: showPwd ? EyeOff : Eye,
+              label: showPwd ? '隱藏密碼' : '顯示密碼',
+              onClick: () => setShowPwd(!showPwd),
+            }}
+          />
+        </div>
+        <div>
+          <p className="text-caption text-fg-muted mb-1">清除 — 有值時出現，清空後消失，不佔位</p>
+          <Input
+            startIcon={Search}
+            value={query}
+            onChange={(e) => setQuery(e.target.value)}
+            aria-label="搜尋商品"
+            endAction={query ? { icon: X, label: '清除搜尋', onClick: () => setQuery('') } : undefined}
+          />
+        </div>
+        <div>
+          <p className="text-caption text-fg-muted mb-1">Size lg — endAction icon 自動放大到 20px，與 startIcon 對稱</p>
+          <Input
+            size="lg"
+            startIcon={Search}
+            value={queryLg}
+            onChange={(e) => setQueryLg(e.target.value)}
+            aria-label="搜尋商品（大尺寸）"
+            endAction={queryLg ? { icon: X, label: '清除搜尋', onClick: () => setQueryLg('') } : undefined}
+          />
+        </div>
+      </div>
+    )
+  },
+}
+
+/* ── Error ── */
+// 2026-07-04 audit Dim 24/M23(d):錯誤訊息改消費 Field + FieldError primitive(對齊 Textarea / TimePicker /
+// Rating showcase idiom),不手刻 <p text-error>(重複 FieldError 內部樣式 = drift 來源)。
+export const ErrorState: Story = {
+  name: '錯誤狀態',
+  render: () => (
+    <div className="flex flex-col gap-4 max-w-sm">
+      <p className="text-caption text-fg-muted">Error 以紅色邊框表示。錯誤訊息由 FieldError 提供，不在 input 內放狀態 icon</p>
+      {/* Field invalid 自動 cascade 到 Input(useResolvedFieldInvalid),不需重複傳 error;
+          standalone <Input error> 用法由 anatomy「+ error prop」section 展示 */}
+      <Field invalid>
+        <FieldLabel>Email</FieldLabel>
+        <Input defaultValue="invalid-email@" />
+        <FieldError>請輸入有效的 email 地址</FieldError>
+      </Field>
+    </div>
+  ),
+}
+
+// @story-history: BorderStates retired 2026-05-17 per audit Dim 24/25 strict re-run —
+//   anatomy.stories.tsx StateBehavior「Focus — border-primary」section 已 cover hover/focus 邊框互動
+//   (同 2 inputs 同 placeholder「點擊或 Tab 觀察 focus 邊框」)。Showcase tier 展示 anatomy 已覆蓋
+//   不教新原則 = retire。ErrorState 已滿足 isInputLike + hasInteractiveStates trait mandate。