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

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

@@ -0,0 +1,310 @@
+// @anatomy-rationale:
+//   StateBehavior covered by ColorMatrix「四種 mode / state × 色彩 Token」段
+//     (5 state:edit default / edit focus / readonly / disabled / error)
+//     + ModeMatrix(6.)edit / readonly / disabled / error 視覺對照。Textarea
+//     的狀態本質就是 mode × state 的色彩 token 組合,集中於 ColorMatrix 比拆
+//     5. 更直觀。
+import type { Meta, StoryObj } from '@storybook/react'
+import { Textarea } from './textarea'
+import { H3, Desc, Td, Th, TokenCell } from '@/design-system/stories-helpers/anatomy/anatomy-utils'
+
+const meta: Meta = {
+  title: 'Design System/Components/Textarea/設計規格',
+  parameters: { layout: 'padded' },
+}
+export default meta
+type Story = StoryObj
+
+export const Overview: Story = {
+  name: '元件總覽',
+  render: () => (
+    <div className="flex flex-col gap-10">
+      <div>
+        <H3>Anatomy</H3>
+        <Desc>Textarea 是多行 Input——native `&lt;textarea&gt;` + 橋接 DS token。不同於 Input:沒有 field-height(高度由 rows / min-h 決定)、沒有 startIcon / endAction。</Desc>
+        <div className="border border-border rounded-lg p-4 max-w-md">
+          <Textarea rows={3} placeholder="請輸入留言..." aria-label="留言" />
+        </div>
+      </div>
+
+      <div>
+        <H3>Props 速查</H3>
+        <div className="overflow-x-auto">
+          <table className="text-caption border-collapse">
+            <thead><tr><Th>Prop</Th><Th>Type</Th><Th>Default</Th><Th>說明</Th></tr></thead>
+            <tbody>
+              {[
+                ['mode', "'edit' | 'view' | 'readonly' | 'disabled'", "'edit'", 'Field mode(view 渲染純文字 div;readonly 用底色 + padding 標示閱讀區)'],
+                ['size', "'sm' | 'md' | 'lg'", "'md'", 'sm/md text-body,lg text-body-lg'],
+                ['rows', 'number', '3', '預設可見行數'],
+                ['placeholder', 'string', '—', '空值提示'],
+                ['error', 'boolean', 'false', 'error 視覺(border-error + aria-invalid)'],
+                ['...props', 'HTMLTextareaAttributes', '—', 'spread 到 native textarea'],
+              ].map(([p, t, d, desc]) => (
+                <tr key={p}><Td mono>{p}</Td><Td mono>{t}</Td><Td mono>{d}</Td><Td>{desc}</Td></tr>
+              ))}
+            </tbody>
+          </table>
+        </div>
+      </div>
+
+      <div>
+        <H3>與 Input 的差異 table</H3>
+        <div className="overflow-x-auto">
+          <table className="text-caption border-collapse">
+            <thead><tr><Th></Th><Th>Input</Th><Th>Textarea</Th></tr></thead>
+            <tbody>
+              <tr><Td>行數</Td><Td>單行</Td><Td>多行(rows 控制)</Td></tr>
+              <tr><Td>高度</Td><Td mono>固定 h-field-*</Td><Td>由 rows / min-h 決定 + resize-y</Td></tr>
+              <tr><Td>Padding</Td><Td mono>items-center(垂直置中)</Td><Td mono>py-2(上下固定內距)</Td></tr>
+              <tr><Td>startIcon / endAction</Td><Td>✓ 支援</Td><Td>❌ 不支援(textarea 慣例無 icon)</Td></tr>
+              <tr><Td>Enter 鍵</Td><Td>觸發 form submit</Td><Td>換行</Td></tr>
+              <tr><Td>Readonly 呈現</Td><Td>同高度、緊湊底色</Td><Td>保留 padding，改用底色標示閱讀區(多行需閱讀區)</Td></tr>
+            </tbody>
+          </table>
+        </div>
+      </div>
+    </div>
+  ),
+}
+
+export const Inspector: Story = {
+  name: '元件檢閱器',
+  parameters: {
+    docs: { description: { story: '右側 Controls 切 props 即時 render,取代 Figma inspect。切 `mode` 看 edit / readonly / disabled 外觀差異,調 `rows` 看高度、切 `error` 看錯誤邊框。' } },
+  },
+  args: {
+    mode: 'edit',
+    size: 'md',
+    rows: 3,
+    error: false,
+    placeholder: '寫下您對這個 PR 的 review 意見…',
+    defaultValue: '',
+    'aria-label': 'PR review 意見（互動檢閱器）',
+  },
+  argTypes: {
+    mode: { control: 'radio', options: ['edit', 'view', 'readonly', 'disabled'] },
+    size: { control: 'radio', options: ['sm', 'md', 'lg'] },
+    rows: { control: { type: 'number', min: 1, max: 20 } },
+    error: { control: 'boolean', description: 'error 視覺(border-error + aria-invalid)' },
+    placeholder: { control: 'text' },
+    defaultValue: { control: 'text' },
+  },
+  render: (args) => (
+    <div className="max-w-md">
+      <Textarea {...args} />
+    </div>
+  ),
+}
+
+export const SizeMatrix: Story = {
+  name: '尺寸對照表',
+  render: () => (
+    <div className="flex flex-col gap-6 max-w-md">
+      <div>
+        <H3>Size = sm / md</H3>
+        <Desc>`text-body`(14px)。常見 form / comment 場景。</Desc>
+        <Textarea size="sm" rows={3} placeholder="寫下您的意見..." aria-label="意見（小尺寸）" />
+      </div>
+      <div>
+        <H3>Size = lg</H3>
+        <Desc>`text-body-lg`(16px)。長篇閱讀場景(bio editor、article body)。</Desc>
+        <Textarea size="lg" rows={3} placeholder="介紹您自己..." aria-label="自我介紹（大尺寸）" />
+      </div>
+    </div>
+  ),
+}
+
+export const ModeMatrix: Story = {
+  name: '模式 對照（編輯 / 展示 / 唯讀 / 停用）',
+  render: () => (
+    <div className="flex flex-col gap-6 max-w-md">
+      <div>
+        <H3>edit(預設)</H3>
+        <Textarea
+          rows={3}
+          defaultValue="我覺得這個專案非常有潛力,建議加強 onboarding 的引導流程..."
+          aria-label="專案意見（可編輯）"
+        />
+      </div>
+      <div>
+        <H3>view — 純展示(渲 div 取代 textarea,whitespace-pre-wrap 保留多行)</H3>
+        <Desc>對齊 Carbon read-only / Cloudscape display mode。常見於檢視已提交的留言 / 評論。</Desc>
+        <Textarea
+          mode="view"
+          rows={3}
+          value="我覺得這個專案非常有潛力,建議加強 onboarding 的引導流程..."
+          aria-label="專案意見（展示）"
+        />
+      </div>
+      <div>
+        <H3>readonly — 保留 padding，用底色標示閱讀區(多行需閱讀區邊界)</H3>
+        <Desc>不同於 Input 的 readonly(同高度、緊湊底色)。多行內容扁平化會讓使用者誤以為可編輯或混入純文字內容——必須用填色 + 內距標示出明確的閱讀區域。</Desc>
+        <Textarea
+          mode="readonly"
+          rows={3}
+          defaultValue="我覺得這個專案非常有潛力,建議加強 onboarding 的引導流程..."
+          aria-label="專案意見（唯讀）"
+        />
+      </div>
+      <div>
+        <H3>disabled</H3>
+        <Textarea
+          mode="disabled"
+          rows={3}
+          defaultValue="尚未開放編輯"
+          aria-label="專案意見（停用）"
+        />
+      </div>
+      <div>
+        <H3>Error state</H3>
+        <Textarea
+          error
+          rows={3}
+          defaultValue="留言內容不能為空"
+          aria-label="留言（錯誤狀態）"
+        />
+      </div>
+    </div>
+  ),
+}
+
+export const ColorMatrix: Story = {
+  name: '色彩對照表',
+  render: () => (
+    <div className="flex flex-col gap-10">
+      <div>
+        <H3>四種 mode / state × 色彩 Token</H3>
+        <Desc>
+          Textarea 作為 Field Control,mode 規則對齊 Input 但 readonly 呈現不同
+          (Textarea readonly 保留 padding,用 bg-readonly 底色標示閱讀區;Input readonly 是緊湊底色)。Error border 跟其他
+          Field Controls 共用 `--error` 語意色。
+        </Desc>
+        <div className="overflow-x-auto mb-4">
+          <table className="text-caption border-collapse">
+            <thead>
+              <tr>
+                <Th>狀態</Th>
+                <Th>Background</Th>
+                <Th>Border</Th>
+                <Th>Text</Th>
+                <Th>Placeholder</Th>
+              </tr>
+            </thead>
+            <tbody>
+              <tr>
+                <Td mono>edit default</Td>
+                <Td><TokenCell token="--surface" display="surface" /></Td>
+                <Td><TokenCell token="--border" display="border" /></Td>
+                <Td><TokenCell token="--foreground" display="foreground" /></Td>
+                <Td><TokenCell token="--fg-muted" display="fg-muted" /></Td>
+              </tr>
+              <tr>
+                <Td mono>edit focus</Td>
+                <Td><TokenCell token="--surface" display="surface" /></Td>
+                <Td><TokenCell token="--primary" display="primary(邊框換色，非額外 ring)" /></Td>
+                <Td><TokenCell token="--foreground" display="foreground" /></Td>
+                <Td><TokenCell token="--fg-muted" display="fg-muted" /></Td>
+              </tr>
+              <tr>
+                <Td mono>view</Td>
+                <Td>透明（zero-chrome，host context 提供邊界）</Td>
+                <Td>透明（無邊框）</Td>
+                <Td><TokenCell token="--foreground" display="foreground" /></Td>
+                <Td>—（view 無 placeholder；空值顯半形 -(hyphen)foreground）</Td>
+              </tr>
+              <tr>
+                <Td mono>readonly</Td>
+                <Td><TokenCell token="--bg-readonly" display="bg-readonly(填色標示閱讀區)" /></Td>
+                <Td>透明（無可見邊框，靠填色 + padding 區隔）</Td>
+                <Td><TokenCell token="--foreground" display="foreground" /></Td>
+                <Td>—</Td>
+              </tr>
+              <tr>
+                <Td mono>disabled</Td>
+                <Td><TokenCell token="--bg-disabled" display="bg-disabled" /></Td>
+                <Td>透明（無可見邊框，靠填色區隔）</Td>
+                <Td><TokenCell token="--fg-disabled" display="fg-disabled" /></Td>
+                <Td><TokenCell token="--fg-disabled" display="fg-disabled" /></Td>
+              </tr>
+              <tr>
+                <Td mono>error(invalid)</Td>
+                <Td><TokenCell token="--surface" display="surface" /></Td>
+                <Td><TokenCell token="--error" display="error" /></Td>
+                <Td><TokenCell token="--foreground" display="foreground" /></Td>
+                <Td><TokenCell token="--fg-muted" display="fg-muted" /></Td>
+              </tr>
+            </tbody>
+          </table>
+        </div>
+      </div>
+
+      <div>
+        <H3>所有色彩狀態並排</H3>
+        <Desc>直接對照五種 state 的視覺差異。</Desc>
+        <div className="grid grid-cols-1 gap-4 max-w-md">
+          <div>
+            <div className="text-caption text-fg-muted mb-1 font-mono">edit default</div>
+            <Textarea rows={2} placeholder="開始輸入..." aria-label="意見（預設狀態）" />
+          </div>
+          <div>
+            <div className="text-caption text-fg-muted mb-1 font-mono">readonly(底色標示閱讀區)</div>
+            <Textarea mode="readonly" rows={2} defaultValue="已送出的意見 — 謝謝您的回饋" aria-label="意見（唯讀狀態）" />
+          </div>
+          <div>
+            <div className="text-caption text-fg-muted mb-1 font-mono">disabled</div>
+            <Textarea mode="disabled" rows={2} defaultValue="尚未開放編輯" aria-label="意見（停用狀態）" />
+          </div>
+          <div>
+            <div className="text-caption text-fg-muted mb-1 font-mono">error(invalid)</div>
+            <Textarea error rows={2} defaultValue="評論內容違反社群規範" aria-label="評論（錯誤狀態）" />
+          </div>
+        </div>
+      </div>
+    </div>
+  ),
+}
+
+export const RowsResizeMatrix: Story = {
+  name: 'Rows 與 縮放',
+  render: () => (
+    <div className="flex flex-col gap-6 max-w-md">
+      <div>
+        <H3>rows 控制預設可見行數</H3>
+        <Desc>`rows` 決定初始高度——使用者可透過右下角 `resize-y` handle 垂直拖拉調整。</Desc>
+        <div className="flex flex-col gap-3">
+          <div>
+            <div className="text-caption text-fg-muted mb-1 font-mono">rows=2</div>
+            <Textarea rows={2} placeholder="短留言..." aria-label="短留言（兩行）" />
+          </div>
+          <div>
+            <div className="text-caption text-fg-muted mb-1 font-mono">rows=3(預設)</div>
+            <Textarea rows={3} placeholder="詳細描述..." aria-label="詳細描述（三行）" />
+          </div>
+        </div>
+      </div>
+
+      <div>
+        <H3>resize-y 垂直可調,水平禁止</H3>
+        <Desc>永遠 `resize-y`(使用者可垂直拖大 / 拖小)。禁止 `resize-x` 或 `resize: both`——水平 resize 破壞 form 佈局。</Desc>
+      </div>
+
+      <div>
+        <H3>min-h-* 覆寫最小高度</H3>
+        <Desc>Consumer 可透過 Tailwind utility 覆寫最小高度(如 `min-h-[120px]`)。</Desc>
+      </div>
+    </div>
+  ),
+}
+
+// ── Accessibility ─────────────────────────────────────────────────────────
+// 2026-05-17 ship per audit Dim 13(story-rules.md 6-canonical 含 Accessibility)
+export const Accessibility = {
+  name: '無障礙與鍵盤',
+  render: () => (
+    <div className="max-w-3xl text-body text-fg-secondary">
+      <h3 className="text-h5 text-foreground mb-2">無障礙設計</h3>
+      <p className="whitespace-pre-line">{"ARIA / 語意:採用原生 <textarea> 元素,自帶完整無障礙語意;搭配 Field 使用時,標籤透過原生 <label for> 與欄位關聯,並補上 aria-invalid / aria-describedby 連到對應的錯誤與說明文字。\n\n鍵盤操作:\n\n- Tab — 聚焦進出欄位\n- 字母鍵 — 輸入文字\n- Enter — 換行(不送出表單,與 Input 不同)\n\n聚焦:聚焦時邊框換成主色,清楚標示目前作用中的欄位。\n\n對比要求:文字對背景對比至少 4.5:1,邊框等介面元素至少 3:1,確保弱視使用者也能辨識。整個欄位不靠滑鼠也能完整操作。"}</p>
+    </div>
+  ),
+}

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

@@ -0,0 +1,192 @@
+// @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'
+import { Button } from '@/design-system/components/Button/button'
+
+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="描述這個問題的發生步驟、預期行為、實際行為..."
+              aria-label="Issue 留言"
+              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="輸入專案名稱"
+              aria-label="專案名稱"
+            />
+          </div>
+          <div>
+            <Label warn>❌ 錯用:把單行標題做成 Textarea</Label>
+            <Textarea rows={1} placeholder="輸入專案名稱" aria-label="專案名稱（Textarea 誤用）" />
+            <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}
+          aria-label="可垂直縮放的留言"
+        />
+        <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}
+          aria-label="已送出的留言（唯讀）"
+        />
+        <Label>↑ 對照 Slack 已編輯留言 / Notion 嵌入文字塊的 readonly 呈現</Label>
+      </Rule>
+
+      <Rule
+        title="對比:Input readonly(無邊框、緊湊)"
+        note="單行內容跟文字段落視覺可分,移除邊框不會混淆。兩者的 readonly 策略差異源自「單行 vs 多行」的閱讀需求"
+      >
+        <Input
+          mode="readonly"
+          value="已送出的單行 URL:https://github.com/user/repo"
+          onChange={() => {}}
+          aria-label="已送出的網址（唯讀）"
+        />
+      </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 請放 Textarea 外部(例如 Field 的標題 FieldLabel 旁)"
+      >
+        <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} aria-label="評論" />
+          <div className="flex justify-end">
+            <Button variant="primary" size="sm">送出</Button>
+          </div>
+        </div>
+        <Label>↑ 按鈕在 Textarea 下方,不塞進框內</Label>
+      </Rule>
+    </div>
+  ),
+}

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

@@ -19,15 +19,13 @@ benchmark:
   - 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-*` 約束。
+**Layout Family**：Family 4（Field control）— multi-line variant。**繼承** Family 4 的 token（字體 / padding / border / state 色彩），但**結構簡化為單一 native `<textarea>`**（edit 態裸 `<textarea>`、view 態裸 `<div>`）——無 fieldWrapper composite、無 startIcon / content / endAction 多 slot anatomy（見下方「與 Input 的差異」表與「禁止事項」）。高度可隨 rows / resize-y 擴展、不受 `--field-height-*` 約束。
 
 **實作基礎**：native `<textarea>` + 橋接 DS token，無 external primitive base。shadcn 同類做法。
 
@@ -63,7 +61,7 @@ Textarea 是**多行文字**的輸入與顯示元件——Input 的多行版本
 | Padding | `items-center`（單行垂直置中）| `py-2`（上下固定內距，多行需閱讀空間）|
 | startIcon / endAction | 支援 | ❌ 不支援（textarea 慣例無 icon 框內）|
 | Enter 鍵 | 觸發 form submit | 換行 |
-| Readonly 呈現 | 同高度、灰底 | 保留邊框 + padding（讓多行文字有閱讀區）|
+| Readonly 呈現 | 同高度、灰底 | 保留 padding，用底色標示閱讀區（讓多行文字有閱讀區）|
 
 ---
 
@@ -71,6 +69,7 @@ Textarea 是**多行文字**的輸入與顯示元件——Input 的多行版本
 
 - **`rows` prop**：預設 `3`，控制初始可見行數
 - **`resize-y`**：使用者可手動拖拉下邊緣垂直 resize
+- **`variant="naked"` 例外**：cell-as-input substrate（DataTable cell）naked 僅 edit/view 兩 mode（readonly/disabled×naked 死格 2026-07-16 移除），一律 `!resize-none` 覆蓋 `resize-y`，並以 `!h-full` 撐滿 cell——cell 內手動 resize 會破壞表格佈局（`textarea.tsx` naked compoundVariants，intentional divergence）
 - **`min-h-*` className**：消費者可透過 Tailwind utility 覆寫最小高度
 - **禁止 `resize: horizontal` 或 `both`**：水平 resize 破壞 form 佈局
 
@@ -87,9 +86,18 @@ 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 風格,**不控高度**
+- **現況**:Textarea 總高度由 `rows`(或 `autoSize` 的內容)+ `resize-y` 決定,**不綁 `--field-height-*`**;`size` 控字體(sm/md = text-body 14px / lg = text-body-lg 16px)**與垂直 padding**
+
+### 垂直 padding 公式(2026-07-28 SSOT)
+
+`py = var(--field-control-py-{size})` = `calc((var(--field-height-{size}) − 1lh) / 2 − 1px)`(token 住 `tokens/uiSize/uiSize.css`)。
+
+- **目的**:單行內容時,Textarea 總高 **精確等於**同 size 的 Input(sm/md/lg = 28/32/36px),並排不再高低差。舊的固定 `py-2` 讓單行 Textarea 是 39/39/42px(比 Input 高 11/7/6px)。
+- **為何有 `− 1px`**:Textarea 兩態都在 border-box 內帶 1px 邊框(edit `border-border` / view `border-transparent`),少了這一項三個 size 都會**各高 2px**。同一常數對三 size 與 lg density 皆成立,無 per-size 特例。
+- **為何不與 `--table-cell-py` 同式**:DataTable cell 的 padding 載體是**無邊框**的 cell(且 edit 以 `!h-full` 釘高),故其公式合法地不帶 `− 1px`;兩式並存、各有載體,不可互抄。
+- **機械鎖**:`scripts/inline-edit-view-geometry-invariant.mjs` 逐 size 驗「Textarea edit py == fieldViewGeometry 多行 view py == 該 token」,並驗 token 公式本身未漂移。
 - **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 -->
+- **契約邊界**:Textarea 的 container 高度獨立於 field-height，只繼承字體 / padding / border token；rows 與內容高度才是多行 control 的垂直尺寸來源
 
 ---
 
@@ -99,11 +107,17 @@ sm 與 md 視覺相同（純命名 mapping，對齊 Field family）。
 
 ### 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)。
+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（同高度、緊湊底色），Textarea readonly **保留邊框與 padding**——多行內容需要明確的閱讀區域邊界訊號,移除邊框後無法與周圍純文字內容區分。
+不同於 Input 的 readonly（同高度、緊湊底色），`variant="default"` 的 Textarea readonly **保留 padding，並填上 `bg-readonly` 底色標示閱讀區**——多行內容需要明確的閱讀區域邊界訊號,沒有這塊填色區會無法與周圍純文字內容區分。`variant="naked"`(cell-as-input substrate)view 態透明且 `!px-0 !py-0`——邊界訊號由 host context(table cell)提供(`textarea.tsx` compoundVariants,intentional divergence;readonly/disabled×naked 死格 2026-07-16 移除;`bare` variant 2026-07-09 退役)。
+
+### 邊界案例
+
+- **空值**:edit 態顯示 placeholder;view / readonly 態 value 為空(`null` / `''`)時渲染半形 `-`(`EMPTY_DISPLAY`)+ `text-foreground`(disabled → fg-disabled)
+- **極長文字**:edit 態高度固定於 rows / resize 結果,內容超出時 native 內部捲動;view 態 `<div>` 隨內容增高(`whitespace-pre-wrap break-words`),無截斷
+- **resize 上限**:`resize-y` 預設無上限;需限制時 consumer 傳 `max-h-*` className(native resize 受 max-height 約束)
 
 ---
 
@@ -113,18 +127,17 @@ native `<textarea>` 自帶 `value` / `defaultValue` / `onChange` triplet — Tex
 - ❌ Textarea 裡放 startIcon / endAction——textarea 慣例無 icon 框內
 - ❌ Textarea 啟用水平 resize（`resize-x` / `resize: both`）——破壞 form 佈局
 - ❌ 把 Textarea 當 code editor 用（無 syntax highlight / auto-complete）
-- ❌ Readonly 時移除邊框 + padding——多行內容需要閱讀區域邊界訊號
+- ❌ `variant="default"` readonly 移除底色填充 + padding——多行內容需要閱讀區域邊界訊號(naked 變體本就透明、邊界由 host context 提供,不在此限)
 
 ---
 
-## 為何無 Inspector / StateBehavior
+## 為何無 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 漂移風險。
+- **無 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` + `SizeMatrix` + `ModeMatrix`(edit/readonly/disabled continuation of Field) + `ColorMatrix` + 元件特有 `RowsResizeMatrix`。
+對應 anatomy story:`Overview` + `Inspector` + `SizeMatrix` + `ModeMatrix`(edit/readonly/disabled continuation of Field) + `ColorMatrix` + 元件特有 `RowsResizeMatrix` + `Accessibility`。
 
 ---
 
@@ -137,15 +150,21 @@ Textarea 是 **Field Controls family 的多行變體**,共用規則由 `../Field
 
 ## A11y 預設
 
-**ARIA / Pattern**:native `<textarea>` element 預設 a11y;Field wrapper 補 `aria-labelledby` / `aria-invalid` / `aria-describedby`。
+**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
 - 字母鍵 — 輸入
-- Esc — 清空(若 clearable + 有值)
+- Enter — 換行（不觸發 form submit，與 Input 不同）
 
-**Focus**:native input focus ring;DS focus-visible ring(`focus-visible:!border-primary`)由 Field wrapper 提供。
+**Focus**:DS focus 邊框由 `<textarea>` 自身的 cva compoundVariants 直接套用,無 fieldWrapper composite——Textarea 是裸 native textarea(見「定位」L30)。兩種 chrome 的 focus 觸發不同:**default chrome** 用 `focus-within:!border-primary`(滑鼠點擊或鍵盤聚焦皆亮主色邊框,對齊 form 場景);**naked chrome**(cell-as-input)用 `focus-visible:!border-primary`(僅鍵盤聚焦亮,滑鼠由 host cell 提供 frame)。readonly 有值態另用 ring idiom(`focus-visible:ring-2 ring-ring ring-offset-1`,鍵盤限定;見 `../Field/field-controls.spec.md`「readonly focus ring」)。standalone 使用即取得對應 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`