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

package/src/components/Tag/tag.spec.md

@@ -0,0 +1,282 @@
+---
+component: Tag
+family: 3
+variants:
+  neutral:
+    when: "通用分類、草稿、無特定語義（GitHub label default / Notion page tag untagged）"
+    world-class: ["Polaris Tag default", "Atlassian Tag standard", "Ant Tag default"]
+  blue:
+    when: "進行中、資訊提示、active 狀態（對應 --info）"
+    world-class: ["Atlassian Lozenge inProgress", "Jira status=in progress", "Linear status=in progress"]
+  red:
+    when: "錯誤、已封鎖、危險（對應 --error）"
+    world-class: ["Atlassian Lozenge removed", "Jira status=blocked", "Ant Tag color=red"]
+  green:
+    when: "成功、已完成、已核准（對應 --success）"
+    world-class: ["Atlassian Lozenge success", "Jira status=done", "GitHub label merged"]
+  yellow:
+    when: "警告、待審核、注意（對應 --warning）"
+    world-class: ["Atlassian Lozenge moved", "Jira status=review", "Ant Tag color=warning"]
+  turquoise:
+    when: "分類色（無固定語義）— 產品線 / 團隊區別標記"
+    world-class: ["GitHub label custom hex", "Notion tag color=teal", "Linear label color=turquoise"]
+  purple:
+    when: "分類色（無固定語義）— 產品線 / 團隊區別標記"
+    world-class: ["GitHub label custom hex", "Notion tag color=purple", "Linear label color=purple"]
+  magenta:
+    when: "分類色（無固定語義）— 產品線 / 團隊區別標記"
+    world-class: ["GitHub label custom hex", "Notion tag color=pink", "Linear label color=pink"]
+  indigo:
+    when: "分類色（無固定語義）— 產品線 / 團隊區別標記"
+    world-class: ["GitHub label custom hex", "Notion tag color=blue", "Linear label color=indigo"]
+sizes:
+  sm:
+    when: "form field-height 28 / compact chrome / dialog / panel context"
+  md:
+    when: "default general UI"
+  lg:
+    when: "touch / prominent CTA / stakeholder-facing surface"
+traits:
+  - hasVariants
+  - hasSizes
+  - hasInteractiveStates
+benchmark:
+  - Ant Design Tag: github.com/ant-design/ant-design/tree/master/components/tag
+  - MUI Chip: github.com/mui/material-ui/tree/master/packages/mui-material/src/Chip
+  - Carbon Tag: github.com/carbon-design-system/carbon/tree/main/packages/react/src/components/Tag
+---
+
+<!-- @benchmark-cited: D5 retrofit 2026-05-18 — body claims marked per-claim @benchmark-unverified inline; canonical source URLs in frontmatter benchmark list. -->
+
+# Tag 設計原則
+
+## 定位
+
+Tag 是 inline label，用於分類標籤、狀態標記、多選已選值。不是 overlay 通知圓點（那是 Badge / Notification indicator）。
+
+**實作基礎**：純視覺 atom——styled span + 可選 dismiss button，無 external primitive base。
+
+**Layout Family**：CLAUDE.md 4-Family Model **Family 3（Pill Layout）** 的 **data indicator sub-profile**。SSOT 在 `components/Button/button.spec.md`「Pill Layout」章節；Tag 是 indicator variant（見下「與 Button 的差異」）。
+
+## 與 Button 的差異（Family 3 indicator variant）
+
+同 Family 結構 `[startIcon?] [<span px-1>label</span>] [suffix dismiss]`,但以下值不同——因為 role 是 **data indicator 非 action trigger**：
+
+| 項目 | Button（action trigger） | Tag（data indicator） | 為什麼 |
+|------|-------------------------|--------------------|-------|
+| 外距 | `xs=px-2`, `sm+=px-3` | 全部 `px-1` | indicator 緊湊 passive,不搶焦點 |
+| 字重 | `font-medium` | `font-normal` | indicator 不強調 |
+| Cursor | `pointer` | `text` | indicator 非 action（dismiss button 內部仍 pointer）|
+| 字體 pairing | Button xs 是 standalone utility（text-caption 12px） | Tag md pair Field md（text-body 14px） | size 對應 Field, Tag 出現在 Field 內需視覺連續 |
+
+**不該把 Tag 改成 Button 樣式來「統一」**——這是 world-class DS（Polaris / Material / Atlassian / Ant / Carbon）共識：action 跟 indicator padding + typography 分開。
+
+---
+
+## 何時用
+
+- **分類標籤**：產品類別（Electronics / Food / Furniture）、文章 tag（React / Design / Tutorial）
+- **狀態標記**：訂單狀態（In stock / Shipped / Delivered）——用 variant 色彩加速掃視
+- **多選已選值**：Combobox / searchable 選擇後顯示的 tag 陣列
+- **user-generated label**：使用者自己建立的標籤（如 Notion labels）
+
+## 何時不用
+
+| 場景 | 改用 | 原因 |
+|------|------|------|
+| 通知計數 / 狀態紅點 | `Badge` | Badge 較小、適合 overlay、主要傳達數量或「有新東西」 |
+| 互動式 filter（可點擊切換）| `Chip` | Tag 是純顯示，Chip 是可點擊控件 |
+| Person 顯示（name + avatar）| `NameCard` / `Avatar + Text` | Tag 是單行 inline label，不承載人員資訊 |
+| 可搜尋的多選入口 | `Combobox`（內部會渲染 Tag 陣列）| Combobox 才是選擇器，Tag 是選擇後的結果 |
+
+---
+
+## Color
+
+以色名命名，語義由消費端決定。建議用法與色彩系統的語義定義對齊。Prop 命名 `color`（對齊 MUI Chip / Ant Tag / Atlaskit Tag world-class 多數派 idiom）。 <!-- @benchmark-unverified: see frontmatter benchmark list for canonical DS source URL -->
+
+| Color | 建議用法 |
+|---------|----------|
+| `neutral`（預設） | 通用分類、草稿、無特定語義 |
+| `blue` | 進行中、資訊提示、active 狀態（對應 `--info`） |
+| `red` | 錯誤、已封鎖、危險（對應 `--error`） |
+| `green` | 成功、已完成、已核准（對應 `--success`） |
+| `yellow` | 警告、待審核、注意（對應 `--warning`） |
+| `turquoise` | 分類色（無固定語義） |
+| `purple` | 分類色（無固定語義） |
+| `magenta` | 分類色（無固定語義） |
+| `indigo` | 分類色（無固定語義） |
+
+所有有色 variant 直接使用 primitive token（`--color-blue-*`、`--color-deep-orange-*` 等），不使用 semantic token（`--primary`、`--error`）。Tag 的「blue」代表藍色本身，不代表「主要操作」語義。
+
+**注意**：`red` variant 使用 primitive `deep-orange`（`--color-deep-orange-*`）。
+
+### 文字色
+
+所有有色 variant 的文字一律使用 primitive step-7（`--color-{hue}-7`），優先辨識度。Primitives 的相對色階公式在 dark mode 自動把 step-7 解析為高對比方向，確保文字在 subtle 底色上始終可讀。Tag 以呈現資訊為主，小面積色塊文字需要更高對比才能舒適閱讀。neutral variant 用 `text-foreground`（不適用此規則）。
+
+見 `color.spec.md` 的「文字色 Step 原則」。
+
+---
+
+## Solid 模式
+
+`solid` boolean prop，預設 false。開啟後使用 step-6 全色背景 + 白色前景，適合需要更強視覺權重的場景（狀態標記、重點標籤）。
+
+### Subtle vs Solid 色彩對照
+
+| Variant | Subtle 背景 | Subtle 文字 | Solid 背景 | Solid 文字 |
+|---|---|---|---|---|
+| neutral | `--muted` | `--foreground` | `--color-neutral-9` | `--inverse-fg` |
+| blue | `--color-blue-1` | `--color-blue-7` | `--color-blue-6` | white |
+| red | `--color-deep-orange-1` | `--color-deep-orange-7` | `--color-deep-orange-6` | white |
+| green | `--color-green-1` | `--color-green-7` | `--color-green-6` | white |
+| yellow | `--color-yellow-1` | `--color-yellow-7` | `--color-yellow-6` | **`--warning-foreground`** |
+| turquoise | `--color-turquoise-1` | `--color-turquoise-7` | `--color-turquoise-6` | white |
+| purple | `--color-purple-1` | `--color-purple-7` | `--color-purple-6` | white |
+| magenta | `--color-magenta-1` | `--color-magenta-7` | `--color-magenta-6` | white |
+| indigo | `--color-indigo-1` | `--color-indigo-7` | `--color-indigo-6` | white |
+
+**yellow 例外**：yellow solid 背景亮度高，白字對比不足，改用 `--warning-foreground`（深色文字）。
+
+### Dismiss 行為（Inline Action 客製）
+
+Dismiss 是 Inline Action，但 icon 色繼承 Tag 文字色（非 `fg-muted`），因為宿主有色彩：
+
+| 模式 | Icon 色 | Hover 背景 | Active 背景 |
+|---|---|---|---|
+| subtle | 繼承 Tag 文字色 | `--neutral-hover` | `--neutral-active` |
+| solid（有色） | 繼承 Tag 文字色 | `--{hue}-hover`（如 `--blue-hover`） | `--{hue}-active` |
+| solid neutral | `--inverse-fg` | `--inverse-neutral-hover` | `--inverse-neutral-active` |
+
+**Solid dismiss 採 solid color shade change**——跟 Button 等互動元件同視覺語言（hover 換較亮 step、active 換較暗 step），維持整個設計系統的互動一致性。這是我們選擇 Atlassian-style semantic state token 流派的具體體現（非 Material 3 的 state layer overlay）。
+
+#### 為什麼 Tag 同時用 primitive（靜態色）和 semantic（互動色）
+
+這是 **有意的職責分離**，非 code smell：
+
+| 概念 | 為什麼住這層 |
+|------|------------|
+| 靜態色（subtle bg、text、solid bg）→ **primitive** | 不需要 mode 翻轉知識——primitives 公式翻轉已自動處理 step-1 alpha、step-7 對比方向 |
+| 互動色（hover、active）→ **semantic `--{hue}-hover/active`** | 需要保證「hover 永遠較亮、active 永遠較暗」，dark mode swap 必須住 semantic 層 |
+
+兩個概念本來就不該綁同一層。Tailwind 也是同樣分離：`bg-blue-500`（靜態 scale step）vs `hover:bg-blue-600 dark:hover:bg-blue-400`（互動需 consumer 處理 mode）。差別只在於我們把 mode swap 封裝進 token，consumer 不需自己寫 dark variant。
+
+詳細流派討論見 `color.spec.md` 的「架構流派定位」段落。
+
+#### `--{hue}-hover/active` 的定位
+
+Semantic 互動 token，從 brand color (`--primary-hover`) 延伸到所有作為 bg 的色相。**刻意只有 hover/active 兩個 token**——base/subtle/text 用 primitive。沒有 `--blue` base 或 `--blue-subtle`，避免重新引入完整 categorical 層。
+
+#### Neutral 例外
+
+neutral solid 的 bg 是 `--color-neutral-9`，在 dark mode 反轉（近黑 → 近白），bg 本身會跨 mode 變色。所以 overlay 不能用 `--{hue}-hover/active`（這些針對「bg 不變」的飽和色），改用 `--inverse-neutral-hover` / `--inverse-neutral-active`（內部處理 mode 鏡射 swap）。
+
+Inline Action 的其他規則（尺寸、hover 背景 pattern）不變。
+
+---
+
+## 尺寸
+
+三種尺寸（子元件補齊原則），不隨 density 變化。尺寸在元件內定義，不引用 field-height token——Tag 和 Button 尺寸是獨立的設計決策。
+
+| Size | 高度 | 字體 | 字重 | Tag px | Text px | 配對 field |
+|------|------|------|------|----------|---------|-----------|
+| sm | 20px | text-caption (12px) | font-medium | 4px | 4px | field sm |
+| md（預設） | 24px | text-body (14px) | font-normal | 4px | 4px | field md |
+| lg | 24px | text-body (14px) | font-normal | 4px | 4px | field lg（與 md 同值，子元件補齊原則） |
+
+**Tag 內 icon 統一 16px**，不分 Tag 尺寸。
+
+## 內部結構
+
+```
+[tag-px] [icon? | avatar?] [text-px TEXT text-px] [dismiss?] [tag-px]
+```
+
+- tag-px：外層呼吸空間
+- text-px：文字自身 padding（固定 4px），同時作為與 icon/avatar 和 dismiss 的間距
+- 不用 gap——text padding 自然拉開
+- icon / dismiss 顏色繼承文字色
+
+### Props
+
+| Prop | 類型 | 說明 |
+|------|------|------|
+| `icon` | `LucideIcon` | 左側 icon，Tag 統一 16px。與 avatar 互斥 |
+| `avatar` | `ReactNode` | 左側 avatar。與 icon 互斥 |
+| `onDismiss` | `() => void` | 可移除——Tag 自動渲染 dismiss 按鈕並控制尺寸與互動樣式 |
+| `solid` | `boolean` | 深底白字模式（step-6 背景 + 白色前景，yellow 例外），預設 false |
+
+## 圓角
+
+統一 `rounded-md`（4px）。
+
+## Tag 間距
+
+tag 與 tag 之間：`gap-1`（4px）。
+
+## 包含 Tag 的 Field
+
+Field 內包含 Tag 時，Field 的 padding 改為 `(field-height - tag-height) / 2`，確保 tag 四邊等距。
+
+---
+
+## Dismiss（Inline Action）
+
+傳入 `onDismiss` callback 時，Tag 自動渲染 dismiss 按鈕。消費端不需要自行建構 dismiss 按鈕或知道 inline action 的尺寸規格。
+
+尺寸 / 互動規則共用 SSOT 見 `../../patterns/element-anatomy/item-anatomy.spec.md`「Inline Action 設計規格」段落。
+
+**Icon 色彩特例（colored host)**：Tag dismiss icon **繼承 Tag 文字色**（非 `fg-muted`）— Tag 屬「colored host」分類。完整兩支規則（neutral host vs colored host）見上述 item-anatomy.spec.md SSOT。詳細每 variant 的 icon 色 + hover 背景見上面「Dismiss 行為」表（92-100 行）。
+
+| Tag size | Icon | Hover 背景 | 上下呼吸空間 |
+|---|---|---|---|
+| sm (20px) | 16px | 18px | 1px |
+| md/lg (24px) | 16px | 18px | 3px |
+
+---
+
+## 禁止事項
+
+- ❌ Tag 尺寸不引用 field-height token——兩者獨立
+- ❌ 不用 gap 處理 icon/dismiss 間距——text padding 已拉開
+- ❌ 不用 Tag 做 overlay 通知圓點——那是不同元件（Badge）
+- ❌ 不用 color 名稱傳達語義（例：不靠 `red` = 錯誤）——color 是顏色，語義由消費端的內容和上下文決定
+- ❌ 不用 prefix/suffix 傳入 dismiss 按鈕——用 `onDismiss` callback，Tag 內部控制渲染
+
+---
+
+## 為何無 StateBehavior
+
+Tag 是**純顯示 indicator**(非互動 — 見「與 Button 的差異」段),本身**無互動狀態**:
+
+- 無 hover / focus / active / selected / disabled——Tag 是 Family 3 indicator variant(非 Pill button)。若要 hover / selected 語意,改用 `Chip`(可互動版本)。
+- 僅有的「行為」是 dismiss(`onDismiss` callback 觸發,Tag 本身不管 dismiss 動畫),close icon 的 hover 狀態屬 Inline Action pattern(item-anatomy.spec.md「Inline Action 設計規格」SSOT),非 Tag 自有。
+
+對應 anatomy story:保留 `Overview` + `Inspector` + `ColorMatrix`(variant solid/subtle) + `SizeMatrix`。互動狀態 → 改用 Chip(見「與 Button 的差異」段)。
+
+---
+
+## A11y 預設
+
+Tag 是**純視覺 indicator**(非互動 control,互動版本是 Chip),預設 ARIA 行為:
+
+- **靜態 Tag**(無 `onDismiss`):render 為 `<span>`,無 role(SR 讀文字內容,跟隨 inline flow)。若 Tag 表達狀態語意(「進行中」「已逾期」),consumer 應在父 region 用 `aria-label` 或視覺 prefix(icon)讓 SR 理解 context
+- **Dismissible Tag**(`onDismiss` 存在):inline X close 為 `<Button iconOnly dismiss size="xs" aria-label="移除 {tagLabel}" />` — 對齊 inline-action canonical(`patterns/element-anatomy/inline-action.spec.md`)
+- **Keyboard**:靜態 Tag 不取得 focus(無互動);dismissible 的 X 走 Button 鍵盤(Tab → focus → Enter/Space → dismiss)
+- **Color-only 語意警告**:Tag 用色相區分狀態時必有文字 label 或 prefix icon(色盲 user 友好);對齊 WCAG 1.4.1「不僅靠顏色傳達」
+- **驗證**:Storybook a11y addon panel 0 critical violation;WCAG AA contrast ≥ 4.5:1(text)/ 3:1(icon)
+
+## 相關
+
+- `../Badge/badge.spec.md` — 通知計數 / 狀態紅點（overlay 場景）
+- `../Chip/chip.spec.md` — 可互動 filter（Tag 的互動版本）
+- `../Combobox/combobox.spec.md` — 多選場景會渲染 Tag 陣列
+- `../NameCard/name-card.spec.md` — 人員資訊顯示
+
+## 被引用(auto-maintained,Dim 3 reciprocal audit)
+
+> 本節由 `scripts/add-reciprocal-pointers.mjs` 自動維護,列出在 SSOT 語境下指向本 spec 的其他 spec。若要手動補充,寫在本節之前。
+
+- `overflow-indicator.spec.md`

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

@@ -0,0 +1,151 @@
+---
+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 相同（fieldWrapper + startIcon + content + endAction，視覺對齊 Family 1），僅高度可隨 rows / auto-resize 擴展、不受 `--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)。autoResize 與兩模式都相容(內部 layoutEffect 量 scrollHeight,不影響 value source)。
+
+### Readonly 特例
+
+不同於 Input 的 readonly（同高度、緊湊底色），Textarea readonly **保留邊框與 padding**——多行內容需要明確的閱讀區域邊界訊號,移除邊框後無法與周圍純文字內容區分。
+
+---
+
+## 禁止事項
+
+- ❌ 把 Input 強制換行使用（撐高、ignore Enter 為 submit）——多行用 Textarea
+- ❌ Textarea 裡放 startIcon / endAction——textarea 慣例無 icon 框內
+- ❌ Textarea 啟用水平 resize（`resize-x` / `resize: both`）——破壞 form 佈局
+- ❌ 把 Textarea 當 code editor 用（無 syntax highlight / auto-complete）
+- ❌ Readonly 時移除邊框 + padding——多行內容需要閱讀區域邊界訊號
+
+---
+
+## 為何無 Inspector / StateBehavior
+
+Textarea 是 **Field Controls family 的多行變體**,共用規則由 `../Field/field-controls.spec.md` own:
+
+- **無 Inspector**:多行輸入的關鍵決策是「行數(rows)」與「resize 行為」,互動 Inspector 無法呈現「使用者輸入長文」的真實感——已由 `SizeMatrix`(各 size × rows 組合) + `RowsResizeMatrix`(auto-resize vs fixed rows vs resize-y)完整覆蓋。其他 prop(disabled / readonly / invalid)由 Field family 共用 pattern 管理。
+- **無 StateBehavior**:Textarea 的互動狀態(focus ring / invalid / disabled / readonly)完全繼承 Field Controls SSOT(`field-controls.spec.md`「Mode 狀態」),無 Textarea 特有的 state 行為。重寫 StateBehavior = 與 Field family 漂移風險。
+
+對應 anatomy story:保留 `Overview` + `SizeMatrix` + `ModeMatrix`(edit/readonly/disabled continuation of Field) + `ColorMatrix` + 元件特有 `RowsResizeMatrix`。
+
+---
+
+## 相關
+
+- `../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;Field wrapper 補 `aria-labelledby` / `aria-invalid` / `aria-describedby`。
+
+**Keyboard 行為**:
+
+- Tab — focus
+- 字母鍵 — 輸入
+- Esc — 清空(若 clearable + 有值)
+
+**Focus**:native input focus ring;DS focus-visible ring(`focus-visible:!border-primary`)由 Field wrapper 提供。
+
+**驗證**:Storybook a11y addon panel 應 0 critical violation;鍵盤完整可操作(無需滑鼠)。WCAG AA contrast ≥ 4.5:1(text)/ 3:1(UI)。
+