@qijenchen/design-system 0.1.0-beta.8 → 0.1.0-beta.80

package/src/components/Textarea/textarea.principles.stories.tsx

@@ -0,0 +1,175 @@
+// @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.
+import React from 'react'
+import LinkTo from '@storybook/addon-links/react'
+import type { Meta, StoryObj } from '@storybook/react'
+import { Textarea } from './textarea'
+import { Input } from '@/design-system/components/Input/input'
+
+const meta: Meta = {
+  title: 'Design System/Components/Textarea/設計原則',
+  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>
+)
+
+// ── 定位與分界 ───────────────────────────────────────────────────────────────
+
+// ── UsageGuidance — 整合何時用 / 何時不用 / vs 近親(Polaris/Material/Ant 共識)
+// 合併自舊 WhenToUse / VsInputRule(2026-04-26 v3 canonical)
+
+export const UsageGuidance: Story = {
+  name: '使用指引',
+  render: () => {
+    const [comment, setComment] = React.useState('')
+    const [title, setTitle] = React.useState('')
+    return (
+    <div className="flex flex-col gap-12">
+      {/* 何時用 — 原 WhenToUse */}
+      <div className="prose prose-sm max-w-prose">
+      <p>適合 Textarea 的真實業務場景(點擊跳轉「展示」頁範例):</p>
+      <ul className="space-y-1">
+        <li>
+          <LinkTo kind="Design System/Components/Textarea/展示" name="基本用法"><span className="text-primary hover:text-primary-hover font-medium cursor-pointer">Issue 回報、評論留言等多行輸入(基本用法)</span></LinkTo>
+        </li>
+        <li>
+          <LinkTo kind="Design System/Components/Textarea/展示" name="在 Field 內"><span className="text-primary hover:text-primary-hover font-medium cursor-pointer">表單內的專案說明、備註欄位(在 Field 內)</span></LinkTo>
+        </li>
+      </ul>
+      <p className="text-fg-secondary mt-3">判斷不確定時:對照 spec.md「何時用 / 何時不用」段;若仍不符,見下方與 Input 的分界示範。</p>
+    </div>
+
+      {/* vs 近親 — 原 VsInputRule */}
+      <div>
+        <Rule
+          title="Textarea — 多行自由輸入(可能有換行、段落)"
+          note="評論、描述、備註、bio、issue content 等場景:內容可能多行,使用者需要看到全貌邊寫邊 review。Enter 在 Textarea 裡是換行,不是 submit"
+        >
+          <div>
+            <Label>✅ GitHub issue 留言框</Label>
+            <Textarea
+              value={comment}
+              onChange={(e) => setComment(e.target.value)}
+              placeholder="描述這個問題的發生步驟、預期行為、實際行為..."
+              rows={4}
+            />
+          </div>
+        </Rule>
+
+        <Rule
+          title="❌ 單行內容(標題 / 姓名 / URL)用 Textarea"
+          note="單行內容使用者預期 Enter 提交 form,Textarea 的 Enter 是換行會破壞預期。使用 Input,鍵盤行為對齊 form submit"
+        >
+          <div>
+            <Label>✅ 專案標題用 Input(單行,Enter 提交)</Label>
+            <Input
+              value={title}
+              onChange={(e) => setTitle(e.target.value)}
+              placeholder="輸入專案名稱"
+            />
+          </div>
+          <div>
+            <Label warn>❌ 錯用:把單行標題做成 Textarea</Label>
+            <Textarea rows={1} placeholder="輸入專案名稱" />
+            <Label warn>↑ 使用者按 Enter 會換行,無法提交 form</Label>
+          </div>
+        </Rule>
+      </div>
+    </div>
+    )
+  },
+}
+
+// ── Resize 行為 ───────────────────────────────────────────────────────
+
+export const ResizeRule: Story = {
+  name: '縮放只允許垂直,不允許水平',
+  render: () => (
+    <div>
+      <Rule
+        title="vertical resize — 使用者可拖下邊緣加高，但寬度固定"
+        note="寬度固定保證 form 佈局不被破壞——一個 Textarea 突然變寬會推擠旁邊的 field。高度使用者可自由控制(長內容拉高比較好看)"
+      >
+        <Textarea defaultValue="拖拉右下角可以垂直 resize 這個 textarea。試試看 ↓" rows={3} />
+        <Label>↑ 對照 Slack message box、GitHub comment box 的行為</Label>
+      </Rule>
+
+      <Rule
+        title="❌ 啟用 resize-x 或 resize: both"
+        note="Textarea 橫向撐開會破壞 form 佈局、影響旁邊欄位。世界級 DS 都只開 vertical。TS 型別擋不了 className 覆蓋,但設計上禁止"
+      >
+        <Label warn>(設計規則)不覆寫 resize-y 成 resize-x / resize-both</Label>
+      </Rule>
+    </div>
+  ),
+}
+
+// ── Readonly 保留邊框 ───────────────────────────────────────────────────
+
+export const ReadonlyRule: Story = {
+  name: '唯讀模式用底色標示閱讀區（不同於 Input）',
+  render: () => (
+    <div>
+      <Rule
+        title="Textarea readonly 保留 padding，用底色標示閱讀區"
+        note="多行內容需要明確的閱讀區域邊界——多行文字若直接攤平會跟周圍純文字區融合,讀者無法辨識「這是一個 field 的內容」還是「文章一部分」。所以 readonly 時填上 bg-readonly 底色並保留內距,圈出一塊可辨識的閱讀區。Input readonly 因為是單行,可以做得更緊湊"
+      >
+        <Textarea mode="readonly" defaultValue={'這是已送出的留言,現在呈現在 readonly 狀態。\n\n多行內容需要明確的閱讀區域邊界,所以 readonly 時保留內距並填上 bg-readonly 底色,圈出一塊閱讀區。'} rows={4} />
+        <Label>↑ 對照 Slack 已編輯留言 / Notion 嵌入文字塊的 readonly 呈現</Label>
+      </Rule>
+
+      <Rule
+        title="對比:Input readonly(無邊框、緊湊)"
+        note="單行內容跟文字段落視覺可分,移除邊框不會混淆。兩者的 readonly 策略差異源自「單行 vs 多行」的閱讀需求"
+      >
+        <Input mode="readonly" value="已送出的單行 URL:https://github.com/user/repo" onChange={() => {}} />
+      </Rule>
+    </div>
+  ),
+}
+
+// ── Icon / endAction 禁止 ────────────────────────────────────────────
+
+export const NoIconRule: Story = {
+  name: '框內不放圖示 / endAction',
+  render: () => (
+    <div>
+      <Rule
+        title="Textarea 不支援 startIcon / endAction"
+        note="Textarea 是多行閱讀區,icon 放在框內會跟多行文字位置衝突(icon 是跟第一行對齊還是 center?)。世界級 DS(Material / Chakra / Ant)textarea 都不放內嵌 icon。需要 icon 請放 Field 外(例如 Field 的 startIcon 或標題旁)"
+      >
+        <Label warn>(型別設計)TextareaProps 不接受 startIcon / endAction,設計上就擋住</Label>
+      </Rule>
+
+      <Rule
+        title="需要 action button → 放 Field 外(Textarea 下方或旁邊)"
+        note="例如 comment box 的「送出」按鈕放 Textarea 下方,不塞進框內"
+      >
+        <div className="flex flex-col gap-2">
+          <Textarea placeholder="留下你的評論..." rows={3} />
+          <div className="flex justify-end">
+            <button className="px-4 py-2 text-body bg-primary text-inverse-fg rounded-md">送出</button>
+          </div>
+        </div>
+        <Label>↑ 按鈕在 Textarea 下方,不塞進框內</Label>
+      </Rule>
+    </div>
+  ),
+}

package/src/components/Textarea/textarea.spec.md

@@ -0,0 +1,162 @@
+---
+component: Textarea
+family: 4
+variants: {}
+sizes:
+  sm:
+    when: "form field-height 28 / compact chrome / dialog / panel context"
+  md:
+    when: "default general UI"
+  lg:
+    when: "text-body-lg（16px）"
+traits:
+  - hasSizes
+  - hasInteractiveStates
+  - isInputLike
+benchmark:
+  - Carbon TextArea: github.com/carbon-design-system/carbon/tree/main/packages/react/src/components/TextArea
+  - MUI TextField (multiline): github.com/mui/material-ui/tree/master/packages/mui-material/src/TextField
+  - Ant Design Input.TextArea: github.com/ant-design/ant-design/tree/master/components/input
+---
+
+<!-- @benchmark-cited: D5 retrofit 2026-05-18 — body claims marked per-claim @benchmark-unverified inline; canonical source URLs in frontmatter benchmark list. -->
+
+# Textarea 設計原則
+
+## 定位
+
+Textarea 是**多行文字**的輸入與顯示元件——Input 的多行版本。格式化邏輯為 identity（value → value）。
+
+**Layout Family**：Family 4（Field control）— multi-line variant。**繼承** Family 4 的 token（字體 / padding / border / state 色彩），但**結構簡化為單一 native `<textarea>`**（edit 態裸 `<textarea>`、display 態裸 `<div>`）——無 fieldWrapper composite、無 startIcon / content / endAction 多 slot anatomy（見下方「與 Input 的差異」表與「禁止事項」）。高度可隨 rows / resize-y 擴展、不受 `--field-height-*` 約束。
+
+**實作基礎**：native `<textarea>` + 橋接 DS token，無 external primitive base。shadcn 同類做法。
+
+共用規則見 `../Field/field-controls.spec.md`。本文件只記錄 Textarea 特有的原則。
+
+---
+
+## 何時用
+
+- **多行 / 長文字輸入**：評論、描述、備註、文章草稿、bio、issue content
+- **使用者需要看到已輸入的全部內容**：邊寫邊 review（不像 Input 捲動）
+- **內容可能包含換行**：段落、列表、程式碼片段
+- **沒有字符數強限制的自由輸入**：content editor、markdown 編輯器 body
+
+## 何時不用
+
+| 場景 | 改用 | 原因 |
+|------|------|------|
+| 單行文字（姓名、標題、URL、search）| `Input` | 單行用 Input，鍵盤 Enter 應該 submit 而非換行 |
+| 數字 | `NumberInput` | 數字不該是自由多行文字 |
+| 富文本 / WYSIWYG 編輯 | 專用 rich-text editor | Textarea 是純文字 |
+| 搜尋輸入（即使可能長）| `Input` + `Combobox`（searchable）| 搜尋慣例是單行 + instant feedback |
+| Code 編輯 | 專用 code editor（Monaco / CodeMirror）| Textarea 無語法 highlight / auto-complete |
+
+---
+
+## 與 Input 的差異
+
+| | Input | Textarea |
+|---|---|---|
+| 行數 | 單行 | 多行（`rows` prop 控制預設）|
+| 高度 | 固定 `h-field-*` | 由 rows / min-h 決定，支援 `resize-y` |
+| Padding | `items-center`（單行垂直置中）| `py-2`（上下固定內距，多行需閱讀空間）|
+| startIcon / endAction | 支援 | ❌ 不支援（textarea 慣例無 icon 框內）|
+| Enter 鍵 | 觸發 form submit | 換行 |
+| Readonly 呈現 | 同高度、灰底 | 保留 padding，用底色標示閱讀區（讓多行文字有閱讀區）|
+
+---
+
+## Rows / 高度控制
+
+- **`rows` prop**：預設 `3`，控制初始可見行數
+- **`resize-y`**：使用者可手動拖拉下邊緣垂直 resize
+- **`min-h-*` className**：消費者可透過 Tailwind utility 覆寫最小高度
+- **禁止 `resize: horizontal` 或 `both`**：水平 resize 破壞 form 佈局
+
+---
+
+## Size
+
+| Size | 字體 | 使用場景 |
+|------|------|---------|
+| sm / md | `text-body`（14px） | 一般 form / comment |
+| lg | `text-body-lg`（16px） | 長篇閱讀（bio editor、article body）|
+
+sm 與 md 視覺相同（純命名 mapping，對齊 Field family）。
+
+### 為什麼不完全對齊 `--field-height-*`
+
+- **現況**:Textarea 高度由 `rows` + `resize-y` 決定,**不綁 `--field-height-*`**;`size` 只控字體(sm/md = text-body 14px / lg = text-body-lg 16px)與 padding 風格,**不控高度**
+- **Rationale**:Textarea 是**多行輸入**,高度由內容 / rows 決定是本質特徵——若硬綁 field-height 只有單行高度,multi-line 場景無法表達。字體 tier 仍對齊 Field family(sm/md 共 text-body、lg 切 text-body-lg),確保並排單行 Input 的視覺 rhythm 一致
+- **世界級對照**:Ant Design `<Input.TextArea>` rows 決定高度、autoSize object 配置 min/max / Material MUI `<TextField multiline>` 用 minRows/maxRows / Polaris `<TextField multiline>` 同流派——全部 textarea 的 container 高度獨立於 field-height,只繼承字體 / padding / border token <!-- @benchmark-unverified: see frontmatter benchmark list for canonical DS source URL -->
+
+---
+
+## Mode / Validation / a11y
+
+詳見 `../Field/field-controls.spec.md`(Mode / Validation)+ `../Field/form-validation.spec.md`(驗證時機)。三 mode 的色彩 / 互動 / aria 規則 Textarea 全部對齊。
+
+### Controlled / Uncontrolled(M26)
+
+native `<textarea>` 自帶 `value` / `defaultValue` / `onChange` triplet — Textarea 是 thin wrapper 直接 forward。3 模式:uncontrolled(只 `defaultValue`)/ controlled(`value` + `onChange`)/ read-only(走 `readOnly` prop,Radix-style)。
+
+### Readonly 特例
+
+不同於 Input 的 readonly（同高度、緊湊底色），`variant="default"` 的 Textarea readonly **保留 padding，並填上 `bg-readonly` 底色標示閱讀區**——多行內容需要明確的閱讀區域邊界訊號,沒有這塊填色區會無法與周圍純文字內容區分。`variant="bare"` readonly 維持透明無填色;`variant="naked"`(cell-as-input substrate)readonly 透明且 `!px-0 !py-0`——兩者的邊界訊號由 host context(toolbar / table cell)提供(`textarea.tsx` compoundVariants,intentional divergence)。
+
+### 邊界案例
+
+- **空值**:edit 態顯示 placeholder;display 態 value 為空(`null` / `''`)時渲染 `—`(`EMPTY_DISPLAY`)+ `text-fg-muted`
+- **極長文字**:edit 態高度固定於 rows / resize 結果,內容超出時 native 內部捲動;display 態 `<div>` 隨內容增高(`whitespace-pre-wrap break-words`),無截斷
+- **resize 上限**:`resize-y` 預設無上限;需限制時 consumer 傳 `max-h-*` className(native resize 受 max-height 約束)
+
+---
+
+## 禁止事項
+
+- ❌ 把 Input 強制換行使用（撐高、ignore Enter 為 submit）——多行用 Textarea
+- ❌ Textarea 裡放 startIcon / endAction——textarea 慣例無 icon 框內
+- ❌ Textarea 啟用水平 resize（`resize-x` / `resize: both`）——破壞 form 佈局
+- ❌ 把 Textarea 當 code editor 用（無 syntax highlight / auto-complete）
+- ❌ `variant="default"` readonly 移除底色填充 + padding——多行內容需要閱讀區域邊界訊號(bare / naked 變體本就透明、邊界由 host context 提供,不在此限)
+
+---
+
+## 為何無 StateBehavior
+
+Textarea 是 **Field Controls family 的多行變體**,共用規則由 `../Field/field-controls.spec.md` own:
+
+- **無 StateBehavior**:Textarea 的互動狀態(focus ring / invalid / disabled / readonly)完全繼承 Field Controls SSOT(`field-controls.spec.md`「Mode 狀態」),無 Textarea 特有的 state 行為。重寫 StateBehavior = 與 Field family 漂移風險——改由 `ColorMatrix`(各 mode × state 色彩 token)+ `ModeMatrix`(edit / readonly / disabled / error 視覺對照)涵蓋。
+
+對應 anatomy story:`Overview` + `Inspector` + `SizeMatrix` + `ModeMatrix`(edit/readonly/disabled continuation of Field) + `ColorMatrix` + 元件特有 `RowsResizeMatrix` + `Accessibility`。
+
+---
+
+## 相關
+
+- `../Input/input.spec.md` — 單行文字的對應元件
+- `../Field/field-controls.spec.md` — Field Control 共用規則（mode / size / error / focus）
+- `../Field/form-validation.spec.md` — blur 驗證標準（多行輸入的驗證時機）
+- `../LinkInput/link-input.spec.md` — URL 特殊處理
+
+## A11y 預設
+
+**ARIA / Pattern**:native `<textarea>` element 預設 a11y;label 關聯走 native `<label htmlFor>`(FieldLabel 渲染 `<label htmlFor={ctx.id}>`,textarea `id` 對應)。搭配 Field 時 textarea 自身補 `aria-invalid`(error 態)/ `aria-describedby`(description / error 文字)。
+
+**Keyboard 行為**:
+
+- Tab — focus
+- 字母鍵 — 輸入
+- Enter — 換行（不觸發 form submit，與 Input 不同）
+
+**Focus**:DS focus-visible 邊框(`focus-visible:!border-primary`)由 `<textarea>` 自身的 cva compoundVariants 直接套用（textarea.tsx default/bare/naked edit 態），無 fieldWrapper composite——Textarea 是裸 native textarea（見「定位」L30），standalone 使用即取得 primary focus 邊框。
+
+**驗證**:Storybook a11y addon panel 應 0 critical violation;鍵盤完整可操作(無需滑鼠)。WCAG AA contrast ≥ 4.5:1(text)/ 3:1(UI)。
+
+## 被引用(auto-maintained,Dim 3 reciprocal audit)
+
+> 本節由 `scripts/add-reciprocal-pointers.mjs` 自動維護,列出在 SSOT 語境下指向本 spec 的其他 spec。若要手動補充,寫在本節之前。
+
+- `field-controls.spec.md`
+- `input.spec.md`

package/src/components/Textarea/textarea.stories.tsx

@@ -0,0 +1,53 @@
+// @story-trait-rationale: hasSizes 由 anatomy.stories.tsx SizeMatrix auto-compile owns size showcase(2026-05-15 F-migration)。
+import type { Meta, StoryObj } from '@storybook/react'
+import { Textarea } from './textarea'
+import { Field, FieldLabel, FieldDescription, FieldError } from '@/design-system/components/Field/field'
+
+const meta: Meta<typeof Textarea> = {
+  title: 'Design System/Components/Textarea/展示',
+  component: Textarea,
+  tags: ['autodocs'],
+  parameters: { layout: 'padded' },
+}
+export default meta
+
+type Story = StoryObj<typeof Textarea>
+
+export const Default: Story = {
+  name: '基本用法',
+  args: {
+    placeholder: '請輸入多行文字...',
+  },
+  render: (args) => (
+    <div className="max-w-md">
+      <Textarea {...args} />
+    </div>
+  ),
+}
+
+// @story-trait-rationale: AllSizes / Modes / WithError retired per F migration 2026-05-15+17 —
+//   anatomy.stories.tsx SizeMatrix + ModeMatrix own trait matrices(state/mode/size 全 cover)。
+//   展示層保留 typical real-product 情境(Default + InField),避免跟 anatomy trait grid 重複。
+export const InField: Story = {
+  name: '在 Field 內',
+  render: () => (
+    <div className="max-w-md flex flex-col gap-4">
+      <Field required>
+        <FieldLabel>專案說明</FieldLabel>
+        <Textarea placeholder="描述這個專案的目的、時程、關鍵議題..." rows={5} />
+        <FieldDescription>會顯示在專案列表的摘要欄</FieldDescription>
+      </Field>
+
+      <Field invalid>
+        <FieldLabel>備註</FieldLabel>
+        <Textarea defaultValue="太短了" rows={3} />
+        <FieldError>備註至少 20 字</FieldError>
+      </Field>
+
+      <Field orientation="horizontal" labelWidth="120px">
+        <FieldLabel>補充說明</FieldLabel>
+        <Textarea placeholder="橫式 field 內的 textarea" rows={4} />
+      </Field>
+    </div>
+  ),
+}

package/src/components/Textarea/textarea.tsx

@@ -3,7 +3,7 @@ import * as React from 'react'
 import { cva, type VariantProps } from 'class-variance-authority'
 import { cn } from '@/lib/utils'
 import type { FieldMode, FieldVariant } from '@/design-system/components/Field/field-types'
-import { useFieldContext } from '@/design-system/components/Field/field-context'
+import { useFieldContext, useResolvedFieldSize, useResolvedFieldMode, useResolvedFieldVariant, useResolvedFieldInvalid } from '@/design-system/components/Field/field-context'
 import { EMPTY_DISPLAY } from '@/design-system/components/Field/field-wrapper'
 
 /**
@@ -19,7 +19,7 @@ import { EMPTY_DISPLAY } from '@/design-system/components/Field/field-wrapper'
  *
  * ── Padding 規則 ───────────────────────────────────────────────────────
  * 多行內容必須有上下內距才能閱讀舒適。不沿用 Input 的 items-center，
- * 改用 py-2（8px）固定上下內距 + px-3 左右內距（與 Input 一致）。
+ * 改用 py-2（8px）固定上下內距 + px-[var(--field-px)]（12px token，左右內距 SSOT，與 Input/Field family 一致）。
  *
  * ── Size ────────────────────────────────────────────────────────────────
  * sm / md → text-body（14px）
@@ -40,7 +40,7 @@ const textareaVariants = cva(
     // K10 fix(2026-05-04):disabled 時 placeholder + text 切 fg-disabled(parallel 到 bareInputStyles)
     //   Textarea 自身 `<textarea disabled>` 帶 disabled HTML attribute,用 `disabled:` variant 直接命中
     'disabled:placeholder:text-fg-disabled disabled:text-fg-disabled',
-    'px-3 py-2',
+    'px-[var(--field-px)] py-2',
     'transition-colors duration-150',
   ],
   {
@@ -77,14 +77,14 @@ const textareaVariants = cva(
       {
         mode: 'display',
         variant: 'default',
-        // 2026-05-13 Q3 Path Ⅰ:Textarea default display zero chrome,!px-0 !py-0 override base `px-3 py-2`
+        // 2026-05-13 Q3 Path Ⅰ:Textarea default display zero chrome,!px-0 !py-0 override base `px-[var(--field-px)] py-2`
         // (跟 Input 同 SSOT,per field-controls.spec.md (d))
         className: 'bg-transparent border border-transparent !px-0 !py-0',
       },
       {
         mode: 'readonly',
         variant: 'default',
-        className: 'bg-disabled border border-transparent',
+        className: 'bg-readonly border border-transparent',
       },
       {
         mode: 'disabled',
@@ -162,7 +162,8 @@ export interface TextareaProps
   /**
    * Visual chrome(正交於 mode);Phase B1(2026-05-05)新增。透傳自 FieldContext.variant,per-prop override。
    * - `'default'` — 完整 chrome(form 場景)
-   * - `'bare'` — 透明 variant,hover/focus reveal(toolbar / cell-as-input)
+   * - `'bare'` — 透明 variant,hover/focus 才 reveal inner border(toolbar / inline editing)
+   * - `'naked'` — 完全無 chrome,cell-as-input(host cell 提供 border + focus frame,對齊 Airtable / Notion / Excel cell editing)
    */
   variant?: FieldVariant
   /** Error 狀態（正交於 mode）。border-error + aria-invalid。 */
@@ -192,13 +193,11 @@ const Textarea = React.forwardRef<HTMLTextAreaElement, TextareaProps>(
     // Field context 整合：disabled / mode / chrome / invalid / size / id 都能從 context 繼承
     const fieldCtx = useFieldContext()
     // chrome 透傳:per-prop override context
-    const variant: FieldVariant = variantProp ?? fieldCtx?.variant ?? 'default'
-    const error = errorProp || (fieldCtx?.invalid ?? false)
-    const size = sizeProp ?? fieldCtx?.size ?? 'md'
-    // mode resolve order(Phase B1 2026-05-05):prop > fieldCtx > readOnly/disabled fallback > 'edit'
-    const resolvedMode: FieldMode = modeProp
-      ?? fieldCtx?.mode
-      ?? (readOnly ? 'readonly' : (disabled ?? fieldCtx?.disabled) ? 'disabled' : 'edit')
+    const variant: FieldVariant = useResolvedFieldVariant(variantProp)
+    const error = useResolvedFieldInvalid(errorProp)
+    const size = useResolvedFieldSize(sizeProp)
+    // 2026-06-08 SSOT:mode 經 useResolvedFieldMode 統一解析(prop > 有效 disabled > fieldCtx.mode > readOnly > 'edit')
+    const resolvedMode: FieldMode = useResolvedFieldMode({ mode: modeProp, disabled, readOnly })
     const isEditable = resolvedMode === 'edit'
     const isDisplay = resolvedMode === 'display'
     const inputId = idProp ?? fieldCtx?.id
@@ -256,7 +255,8 @@ const Textarea = React.forwardRef<HTMLTextAreaElement, TextareaProps>(
 Textarea.displayName = 'Textarea'
 
 // Story auto-compile metadata — Phase 1 mechanical migration(2026-04-24)
-// Phase 2 fill needed: purpose descriptions + when rationale + world-class refs
+// sizes 只反映 Textarea 真實控制的軸:typography(size 只控字體,不綁 field-height、無 icon slot —
+//   高度由 rows + resize-y 決定,per textarea.spec.md L88-92 / L64 / L113)。
 export const textareaMeta = {
   component: 'Textarea',
   family: 4,
@@ -264,11 +264,13 @@ export const textareaMeta = {
 
   },
   sizes: {
-    sm: { fieldHeight: 28, iconSize: 16, typography: 'body' },
-    md: { fieldHeight: 32, iconSize: 16, typography: 'body' },
-    lg: { fieldHeight: 40, iconSize: 20, typography: 'body' },
+    sm: { typography: 'body' },
+    md: { typography: 'body' },
+    lg: { typography: 'body-lg' },
   },
-  states: ['default', 'hover', 'active', 'focus-visible', 'disabled'],
+  // states 對齊 cva compoundVariants + anatomy ColorMatrix 真實 state 集合;
+  //   text input 無 'active'(按下)視覺態(Material/Polaris/Carbon TextArea 共識)。
+  states: ['default', 'hover', 'focus-visible', 'readonly', 'disabled', 'error'],
   tokens: {
     bg: ['bg-disabled', 'bg-surface'],
     fg: ['text-fg-disabled', 'text-fg-muted', 'text-foreground'],

package/src/components/TimePicker/index.ts

@@ -0,0 +1,5 @@
+// AUTO-GENERATED by scripts/gen-component-indexes.mjs — DO NOT EDIT MANUALLY.
+// Re-export pattern enables package.json exports map subpath:
+//   import { ... } from '@qijenchen/design-system/{components,patterns}/<Dir>'
+// Regenerate: node scripts/gen-component-indexes.mjs
+export * from './time-picker'

package/src/components/TimePicker/time-columns.tsx

@@ -106,6 +106,11 @@ function TimeColumn({ values, selected, disabledSet, label, onSelect, withDivide
     isFirstRunRef.current = false
   }, [values, selected])
 
+  // a11y:穩定 id 前綴,讓 listbox `aria-activedescendant` 指向目前 active(= selected)option。
+  // single-tabstop + 方向鍵 listbox 應透過 activedescendant 告知 AT 哪個 option active,
+  // 否則 SR 方向鍵移動時讀不出目前 option(WAI-ARIA listbox virtual-focus 慣例)。
+  const baseId = React.useId()
+
   // WAI-ARIA listbox keyboard pattern:ArrowUp/Down 切 option / Home / End 跳邊界。
   // 對標 Ant TimePicker / Material TimePicker。Tab 跳離 listbox(走預設行為,不 stopPropagation)。
   const handleKeyDown = (e: React.KeyboardEvent<HTMLDivElement>) => {
@@ -147,9 +152,10 @@ function TimeColumn({ values, selected, disabledSet, label, onSelect, withDivide
         ref={listRef}
         role="listbox"
         aria-label={label}
+        aria-activedescendant={selected != null ? `${baseId}-opt-${selected}` : undefined}
         tabIndex={0}
         onKeyDown={handleKeyDown}
-        className="flex flex-col py-2 focus-visible:outline-2 focus-visible:outline-primary focus-visible:outline-offset-[-2px]"
+        className="flex flex-col py-2 focus-visible:outline-2 focus-visible:outline-ring focus-visible:outline-offset-[-2px]"
       >
         {values.map((v) => {
           const isSelected = v === selected
@@ -157,6 +163,7 @@ function TimeColumn({ values, selected, disabledSet, label, onSelect, withDivide
           return (
             <button
               key={v}
+              id={`${baseId}-opt-${v}`}
               type="button"
               role="option"
               aria-selected={isSelected}