@qijenchen/design-system 0.1.0-beta.10

package/src/components/Tag/tag.tsx

@@ -0,0 +1,246 @@
+import * as React from "react"
+import { cva, type VariantProps } from "class-variance-authority"
+import { X } from "lucide-react"
+import type { LucideIcon } from "lucide-react"
+
+import { cn } from "@/lib/utils"
+import { Tooltip, TooltipTrigger, TooltipContent } from "@/design-system/components/Tooltip/tooltip"
+import { ItemInlineActionButton } from "@/design-system/patterns/element-anatomy/item-anatomy"
+
+// ── Tag（inline label）─────────────────────────────────────────────────────
+// 用於分類標籤、狀態標記、多選已選值。
+//
+// 三種尺寸（子元件補齊原則——消費端直接透傳 size，不做 mapping）：
+//   sm — 20px 高, 12px 字, 4px tag-px, font-medium（配 field sm）
+//   md — 24px 高, 14px 字, 4px tag-px, font-normal（配 field md）— 預設
+//   lg — 24px = md alias（配 field lg，子元件補齊原則）
+//
+// 截斷：max-w-40（160px），超出時文字 truncate + 自動 tooltip。
+// 用 Canvas measureText 偵測截斷（scrollWidth 在 flex 內不可靠）。
+
+let _measureCtx: CanvasRenderingContext2D | null = null
+function getMeasureCtx() {
+  if (!_measureCtx) _measureCtx = document.createElement('canvas').getContext('2d')
+  return _measureCtx
+}
+
+const tagVariants = cva(
+  "inline-flex items-center rounded-md border border-transparent transition-colors cursor-text",
+  {
+    variants: {
+      color: {
+        // 直接引用 primitive（bg=step-1, text=step-7），不經過語義層
+        // step-1 在 dark mode 用 alpha 公式，step-7 用 lighter 公式——兩個 mode 都正確
+        neutral:   "bg-secondary text-foreground",
+        blue:      "bg-[var(--color-blue-1)] text-[var(--color-blue-7)]",
+        red:       "bg-[var(--color-deep-orange-1)] text-[var(--color-deep-orange-7)]",
+        green:     "bg-[var(--color-green-1)] text-[var(--color-green-7)]",
+        yellow:    "bg-[var(--color-yellow-1)] text-[var(--color-yellow-7)]",
+        turquoise: "bg-[var(--color-turquoise-1)] text-[var(--color-turquoise-7)]",
+        purple:    "bg-[var(--color-purple-1)] text-[var(--color-purple-7)]",
+        magenta:   "bg-[var(--color-magenta-1)] text-[var(--color-magenta-7)]",
+        indigo:    "bg-[var(--color-indigo-1)] text-[var(--color-indigo-7)]",
+      },
+      size: {
+        sm: "h-5 px-1 text-caption font-medium",
+        md: "h-6 px-1 text-body font-normal",
+        lg: "h-6 px-1 text-body font-normal",
+      },
+    },
+    defaultVariants: {
+      color: "neutral",
+      size: "md",
+    },
+  }
+)
+
+// ── Solid variant 色彩（step-6 底 + 白字，warning 用 --warning-foreground）──
+// 直接引用 primitive step-6，不經過語義層
+// neutral 用 neutral-9 + --inverse-fg（light=白字, dark=深字，自動反轉）
+const SOLID_CLASSES: Record<string, string> = {
+  neutral:   'bg-[var(--color-neutral-9)] text-inverse-fg',
+  blue:      'bg-[var(--color-blue-6)] text-on-emphasis',
+  red:       'bg-[var(--color-deep-orange-6)] text-on-emphasis',
+  green:     'bg-[var(--color-green-6)] text-on-emphasis',
+  yellow:    'bg-[var(--color-yellow-6)] text-[var(--warning-foreground)]',
+  turquoise: 'bg-[var(--color-turquoise-6)] text-on-emphasis',
+  purple:    'bg-[var(--color-purple-6)] text-on-emphasis',
+  magenta:   'bg-[var(--color-magenta-6)] text-on-emphasis',
+  indigo:    'bg-[var(--color-indigo-6)] text-on-emphasis',
+}
+
+export interface TagProps
+  extends Omit<React.HTMLAttributes<HTMLDivElement>, 'prefix' | 'color'>,
+    VariantProps<typeof tagVariants> {
+  /** 左側 icon（LucideIcon），由 Tag 統一 16px。與 avatar 互斥。 */
+  icon?: LucideIcon
+  /** 左側 avatar（ReactNode），與 icon 互斥。 */
+  avatar?: React.ReactNode
+  /** 可移除——Tag 自動渲染 dismiss 按鈕並控制尺寸與互動樣式 */
+  onDismiss?: () => void
+  /** 深底白字模式（step-6 背景 + 白色前景，warning 例外） */
+  solid?: boolean
+  /**
+   * 2026-05-15 Q3 真 SSOT fix(per user verbatim「同空間兩判斷點」+「不要冰山一角」):
+   * Tag 寬度由 parent constrain,不套預設 max-w-40(160px)。用於 cell-as-input narrow cell
+   * (< 160px)時 Tag fit cell 寬度 + truncate ellipsis,而非 160px 後被 cell `overflow-hidden`
+   * 硬切。對齊「同 cell width → 同 overflow 判斷」SSOT。Default false 保 backward compat
+   * (wrap layout / pill rail 等仍受 160px 保護)。
+   */
+  unbounded?: boolean
+}
+
+// ── Solid dismiss hover/active bg ──
+// 用 semantic --{hue}-hover/active token，跟 --primary-hover/active 同模式：
+// solid 色彩 shade change（hover 較亮 step、active 較暗 step），跟 Button 等
+// 互動元件視覺一致。在 semantic 層做 dark mode swap 確保方向跨 mode 一致。
+// neutral 特例：bg 是 neutral-9 隨 mode 反轉，用 --inverse-neutral-* 鏡射
+const SOLID_DISMISS_HOVER: Record<string, { hover: string; active: string }> = {
+  neutral:   { hover: 'var(--inverse-neutral-hover)', active: 'var(--inverse-neutral-active)' },
+  blue:      { hover: 'var(--blue-hover)',            active: 'var(--blue-active)' },
+  red:       { hover: 'var(--red-hover)',             active: 'var(--red-active)' },
+  green:     { hover: 'var(--green-hover)',           active: 'var(--green-active)' },
+  yellow:    { hover: 'var(--yellow-hover)',          active: 'var(--yellow-active)' },
+  turquoise: { hover: 'var(--turquoise-hover)',       active: 'var(--turquoise-active)' },
+  purple:    { hover: 'var(--purple-hover)',          active: 'var(--purple-active)' },
+  magenta:   { hover: 'var(--magenta-hover)',         active: 'var(--magenta-active)' },
+  indigo:    { hover: 'var(--indigo-hover)',          active: 'var(--indigo-active)' },
+}
+
+// ── Dismiss（internal）────────────────────────────────────────────────────
+// 走 `ItemInlineActionButton`(item-anatomy SSOT)+ `hoverBgClassName` override prop
+// (2026-05-01 整合,消除原 Tag 自刻 `<button>` 繞 DS infra 的 tech debt)。
+//
+// 視覺對齊:`size="md"` → icon 16 / hover-bg 18,跟 Tag 既有手刻幾何完全相等。
+// Solid variant(blue/green/red 等)透過 `hoverBgClassName` 套色相 override token;
+// Subtle variant 落用 ItemInlineActionButton 預設 neutral-hover。
+// 圖標色繼承 Tag 文字色 → `text-current` 三態覆寫。
+
+function TagDismiss({ onDismiss, label, solid, color }: { onDismiss: () => void; label: string; solid?: boolean; color?: string }) {
+  const solidColors = solid && color ? SOLID_DISMISS_HOVER[color] : undefined
+
+  return (
+    <ItemInlineActionButton
+      icon={X}
+      size="md"
+      onClick={(e) => { e.stopPropagation(); onDismiss() }}
+      aria-label={`移除 ${label}`}
+      style={solidColors ? ({ '--dismiss-hover': solidColors.hover, '--dismiss-active': solidColors.active } as React.CSSProperties) : undefined}
+      hoverBgClassName={
+        solidColors
+          ? 'group-hover/action:bg-[var(--dismiss-hover)] group-active/action:bg-[var(--dismiss-active)]'
+          : undefined
+      }
+      // Override default fg-muted → 繼承 Tag 文字色(label 同色)
+      className="text-current hover:text-current active:text-current"
+    />
+  )
+}
+
+function TagInner(
+  { className, color, size, icon: Icon, avatar, onDismiss, solid, unbounded = false, children, style, ...props }: TagProps,
+  forwardedRef: React.ForwardedRef<HTMLDivElement>,
+) {
+  const solidClass = solid ? SOLID_CLASSES[color ?? 'neutral'] : undefined
+  const ownRef = React.useRef<HTMLDivElement | null>(null)
+  const [isTruncated, setIsTruncated] = React.useState(false)
+
+  React.useLayoutEffect(() => {
+    const el = ownRef.current
+    if (!el) return
+    const ctx = getMeasureCtx()
+    const check = () => {
+      const textSpan = el.querySelector('[data-tag-text]')
+      if (!textSpan || !ctx) return
+      const text = textSpan.textContent || ''
+      const cs = getComputedStyle(textSpan)
+      ctx.font = `${cs.fontWeight} ${cs.fontSize} ${cs.fontFamily}`
+      const textWidth = ctx.measureText(text).width
+      const padL = parseFloat(cs.paddingLeft) || 0
+      const padR = parseFloat(cs.paddingRight) || 0
+      const needed = textWidth + padL + padR
+      setIsTruncated(needed > (textSpan as HTMLElement).clientWidth + 1)
+    }
+    check()
+    const obs = new ResizeObserver(check)
+    obs.observe(el)
+    return () => obs.disconnect()
+  }, [children])
+
+  const label = typeof children === 'string' ? children : ''
+
+  const tag = (
+    <div
+      ref={(el) => {
+        ownRef.current = el
+        if (typeof forwardedRef === 'function') forwardedRef(el)
+        else if (forwardedRef) (forwardedRef as React.MutableRefObject<HTMLDivElement | null>).current = el
+      }}
+      data-tag-root=""
+      className={cn(tagVariants({ color, size }), solidClass, 'w-fit min-w-0 overflow-hidden', className)}
+      // 2026-05-18 Round 5 fix(per Codex M31 Round 5 verdict + user 拍板「那就開始做」):
+      // 用 CSS var `--combobox-tag-area-inline-size`(由 Combobox useOverflowCount JS-injected)取代
+      // `min(100%, 10rem)` cyclic percentage。CSS Sizing 3 §5.2.1:percentage 在 indefinite containing
+      // block 退化為 initial value → Round 4 的 100% 沒 enforce。改 explicit px 值(JS measured)避此 trap。
+      // unbounded=true:cap = inject 寬(回 cell-as-input narrow cell 原 behavior)
+      // default:cap = min(inject 寬, 160px)— 兩 cap 取小。fallback(無 var,Form context 等)= 100% / 10rem。
+      style={{
+        maxWidth: unbounded
+          ? 'var(--combobox-tag-area-inline-size, 100%)'
+          : 'min(var(--combobox-tag-area-inline-size, 10rem), 10rem)',
+        ...style,
+      }}
+      {...props}
+    >
+      {Icon && <Icon size={16} aria-hidden />}
+      {avatar && <span className="shrink-0 w-4 h-4 rounded-full overflow-hidden inline-grid place-content-center [&>*]:w-full [&>*]:h-full">{avatar}</span>}
+      <span data-tag-text="" className="px-1 truncate min-w-0">{children}</span>
+      {onDismiss && <TagDismiss onDismiss={onDismiss} label={label} solid={solid} color={color ?? 'neutral'} />}
+    </div>
+  )
+
+  if (!isTruncated) return tag
+
+  return (
+    <Tooltip>
+      <TooltipTrigger asChild>{tag}</TooltipTrigger>
+      <TooltipContent>{children}</TooltipContent>
+    </Tooltip>
+  )
+}
+
+const Tag = React.forwardRef<HTMLDivElement, TagProps>(TagInner)
+Tag.displayName = 'Tag'
+
+// Story auto-compile metadata — Phase 1 mechanical migration(2026-04-24)
+// Phase 2 fill needed: purpose descriptions + when rationale + world-class refs
+export const tagMeta = {
+  component: 'Tag',
+  family: 3,
+  variants: {
+    neutral: { purpose: '通用分類、草稿、無特定語義' },
+    blue: { purpose: '進行中、資訊提示、active 狀態（對應 --info）' },
+    red: { purpose: '錯誤、已封鎖、危險（對應 --error）' },
+    green: { purpose: '成功、已完成、已核准（對應 --success）' },
+    yellow: { purpose: '警告、待審核、注意（對應 --warning）' },
+    turquoise: { purpose: '分類色（無固定語義）' },
+    purple: { purpose: '分類色（無固定語義）' },
+    magenta: { purpose: '分類色（無固定語義）' },
+    indigo: { purpose: '分類色（無固定語義）' },
+  },
+  sizes: {
+    sm: { fieldHeight: 28, iconSize: 16, typography: 'body' },
+    md: { fieldHeight: 32, iconSize: 16, typography: 'body' },
+    lg: { fieldHeight: 40, iconSize: 20, typography: 'body' },
+  },
+  states: ['default', 'hover', 'active', 'focus-visible', 'disabled'],
+  tokens: {
+    bg: ['bg-neutral-active', 'bg-neutral-hover', 'bg-secondary', 'bg-transparent'],
+    fg: ['text-foreground', 'text-inverse-fg'],
+    ring: [],
+  },
+  defaultVariant: 'neutral',
+  defaultSize: 'md',
+} as const
+
+export { Tag, tagVariants }

package/src/components/Textarea/textarea.tsx

@@ -0,0 +1,280 @@
+// @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 * 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 { EMPTY_DISPLAY } from '@/design-system/components/Field/field-wrapper'
+
+/**
+ * Textarea — 多行文字輸入
+ *
+ * ── 定位 ────────────────────────────────────────────────────────────────
+ * 多行版本的 Input，edit / display / readonly / disabled 四態與 Input 邏輯一致(Phase B1 2026-05-05)。
+ * 不同於 Input：
+ *   - 沒有固定 field-height（高度由 rows 或 min-h 決定）
+ *   - 沒有 startIcon / endAction（textarea 慣例不放 icon）
+ *   - readonly 呈現保留邊框與 padding，只改底色，讓多行文字有合理閱讀區
+ *   - display 渲染 <div> + white-space:pre-wrap 保留多行文本
+ *
+ * ── Padding 規則 ───────────────────────────────────────────────────────
+ * 多行內容必須有上下內距才能閱讀舒適。不沿用 Input 的 items-center，
+ * 改用 py-2（8px）固定上下內距 + px-3 左右內距（與 Input 一致）。
+ *
+ * ── Size ────────────────────────────────────────────────────────────────
+ * sm / md → text-body（14px）
+ * lg      → text-body-lg（16px）
+ *
+ * ── rows / min-h ───────────────────────────────────────────────────────
+ * 預設 rows={3}。消費者可透過 rows prop 調整，或透過 min-h-* className 覆寫。
+ */
+
+// Phase B1(2026-05-05):新增 chrome variant(default / bare),mode×chrome 的 chrome 規則由
+// compoundVariants 決定,鏡射 fieldWrapperStyles 對齊 canonical(Phase D 將整併進 fieldWrapperStyles)。
+const textareaVariants = cva(
+  [
+    'w-full rounded-md',
+    'text-foreground font-normal',
+    'outline-none resize-y',
+    'placeholder:text-fg-muted',
+    // 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',
+    'transition-colors duration-150',
+  ],
+  {
+    variants: {
+      mode: {
+        edit: '',
+        display: '',
+        readonly: '',
+        disabled: '',
+      },
+      // chrome 對齊 fieldWrapperStyles.variant(default / bare / naked)。
+      variant: {
+        default: '',
+        bare: '',
+        naked: '',
+      },
+      size: {
+        sm: 'text-body',
+        md: 'text-body',
+        lg: 'text-body-lg',
+      },
+    },
+    compoundVariants: [
+      // default chrome × mode
+      {
+        mode: 'edit',
+        variant: 'default',
+        className: [
+          'bg-surface border border-border',
+          'hover:border-border-hover',
+          'focus-visible:!border-primary focus-visible:hover:!border-primary',
+        ],
+      },
+      {
+        mode: 'display',
+        variant: 'default',
+        // 2026-05-13 Q3 Path Ⅰ:Textarea default display zero chrome,!px-0 !py-0 override base `px-3 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',
+      },
+      {
+        mode: 'disabled',
+        variant: 'default',
+        className: 'bg-disabled border border-transparent cursor-not-allowed text-fg-disabled',
+      },
+      // bare chrome × mode(對齊 fieldWrapperStyles bare 規則)
+      {
+        mode: 'edit',
+        variant: 'bare',
+        className: [
+          'bg-transparent border border-transparent',
+          'hover:border-border',
+          'focus-visible:!border-primary focus-visible:hover:!border-primary',
+        ],
+      },
+      {
+        mode: 'display',
+        variant: 'bare',
+        className: 'bg-transparent border border-transparent',
+      },
+      {
+        mode: 'readonly',
+        variant: 'bare',
+        className: 'bg-transparent border border-transparent',
+      },
+      {
+        mode: 'disabled',
+        variant: 'bare',
+        className: 'bg-transparent border border-transparent cursor-not-allowed opacity-disabled text-fg-disabled',
+      },
+      // naked chrome × mode — cell-as-input substrate(2026-05-06 v14 revert v12)。
+      //   v12 `!absolute -inset-px` autoRowHeight 不相容 → revert v9 baseline + 保留 v13.3
+      //   focus !important。focus-visible 用 textarea 自身 selector(focusable element)。
+      {
+        mode: 'edit',
+        variant: 'naked',
+        className: [
+          'bg-transparent !rounded-none !resize-none !h-full',
+          '!px-[var(--table-cell-px)] !py-[var(--table-cell-py)]',
+          'border border-border',
+          'hover:border-border-hover',
+          'focus-visible:!border-primary focus-visible:hover:!border-primary',
+          // textarea UA stylesheet 預設 line-height: normal(1.2-1.5 不定),會跟 display
+          // `<div>` text-body line-height: 1.5(21px @ 14px)不一致 → cell 進 edit 後 height
+          // shift。顯式 leading 對齊 div 行為。
+          '!leading-[1.5]',
+        ],
+      },
+      // 2026-05-13 Q1 R4 verify(per codex Q1 verdict 補 Textarea nuance):
+      // Textarea naked display/readonly/disabled 用 `!h-full`,**不**對齊 Field wrapper 的 `!h-auto`。
+      // Why divergence:textarea 是 native form element 帶 intrinsic rows-based height,且 cell 內
+      // multi-line text 需要撐滿 cell 而非依 line-height intrinsic。`!h-full` 讓 textarea 填滿 cell
+      // 高度,文字 anchored to cell.top + cell padding(同視覺結果 Field wrapper autoRow !h-auto)。
+      // 此 divergence intentional + documented;非 SSOT violation。
+      { mode: 'display', variant: 'naked', className: 'bg-transparent !rounded-none !h-full !resize-none !px-0 !py-0 border border-transparent !leading-[1.5]' },
+      { mode: 'readonly', variant: 'naked', className: 'bg-transparent !rounded-none !h-full !resize-none !px-0 !py-0 border border-transparent !leading-[1.5]' },
+      // 2026-05-13 codex V2 fix:移除 `opacity-disabled` blanket(對齊 field-wrapper.tsx naked R3 fix +
+      //   color.spec.md:729 逃生艙 rule)。Textarea 已用具體 `text-fg-disabled` token,不需要 wrapper opacity。
+      { mode: 'disabled', variant: 'naked', className: 'bg-transparent !rounded-none cursor-not-allowed text-fg-disabled !h-full !resize-none !px-0 !py-0 border border-transparent !leading-[1.5]' },
+    ],
+    defaultVariants: {
+      mode: 'edit',
+      variant: 'default',
+      size: 'md',
+    },
+  }
+)
+
+export interface TextareaProps
+  extends Omit<React.TextareaHTMLAttributes<HTMLTextAreaElement>, 'size'>,
+    Omit<VariantProps<typeof textareaVariants>, 'mode' | 'variant'> {
+  /** Field display mode */
+  mode?: FieldMode
+  /**
+   * 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)
+   */
+  variant?: FieldVariant
+  /** Error 狀態（正交於 mode）。border-error + aria-invalid。 */
+  error?: boolean
+}
+
+// code-quality-allow: long-function — Textarea forwardRef body 含 mode×size×variant×error 4 軸 prop + autoFocus + aria 完整覆蓋,拆 sub-fn 會把 useFieldContext / fieldWrapperStyles 跨檔 drilling
+const Textarea = React.forwardRef<HTMLTextAreaElement, TextareaProps>(
+  (
+    {
+      mode: modeProp,
+      variant: variantProp,
+      error: errorProp = false,
+      size: sizeProp,
+      className,
+      disabled,
+      readOnly,
+      rows = 3,
+      value,
+      id: idProp,
+      'aria-describedby': ariaDescribedByProp,
+      'aria-errormessage': ariaErrorMessageProp,
+      ...props
+    },
+    ref
+  ) => {
+    // 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 isEditable = resolvedMode === 'edit'
+    const isDisplay = resolvedMode === 'display'
+    const inputId = idProp ?? fieldCtx?.id
+    const ariaDescribedBy = ariaDescribedByProp ?? fieldCtx?.descriptionId
+    const ariaErrorMessage = ariaErrorMessageProp ?? (error ? fieldCtx?.errorId : undefined)
+
+    // ── display mode:純展示,渲染 <div> 取代 <textarea>(white-space:pre-wrap 保留多行) ──
+    // 對齊 Carbon read-only / Cloudscape display-mode
+    if (isDisplay) {
+      const displayValue = value != null && value !== '' ? String(value) : null
+      return (
+        <div
+          id={inputId}
+          data-field-mode="display"
+          aria-describedby={ariaDescribedBy}
+          className={cn(
+            textareaVariants({ mode: 'display', variant: variant, size }),
+            'whitespace-pre-wrap break-words',
+            displayValue == null && 'text-fg-muted',
+            className,
+          )}
+        >
+          {displayValue ?? EMPTY_DISPLAY}
+        </div>
+      )
+    }
+
+    return (
+      <textarea
+        ref={ref}
+        id={inputId}
+        rows={rows}
+        value={value as string | number | readonly string[] | undefined}
+        disabled={resolvedMode === 'disabled'}
+        readOnly={resolvedMode === 'readonly'}
+        aria-invalid={error || undefined}
+        aria-required={fieldCtx?.required || undefined}
+        aria-describedby={ariaDescribedBy}
+        aria-errormessage={ariaErrorMessage}
+        data-field-mode={resolvedMode}
+        data-error={isEditable && error ? '' : undefined}
+        className={cn(
+          textareaVariants({ mode: resolvedMode, variant: variant, size }),
+          isEditable && error && [
+            'border-error hover:border-error-hover',
+            'focus-visible:border-error focus-visible:hover:border-error',
+          ],
+          className
+        )}
+        {...props}
+      />
+    )
+  }
+)
+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
+export const textareaMeta = {
+  component: 'Textarea',
+  family: 4,
+  variants: {
+
+  },
+  sizes: {
+    sm: { fieldHeight: 28, iconSize: 16, typography: 'body' },
+    md: { fieldHeight: 32, iconSize: 16, typography: 'body' },
+    lg: { fieldHeight: 40, iconSize: 20, typography: 'body' },
+  },
+  states: ['default', 'hover', 'active', 'focus-visible', 'disabled'],
+  tokens: {
+    bg: ['bg-disabled', 'bg-surface'],
+    fg: ['text-fg-disabled', 'text-fg-muted', 'text-foreground'],
+    ring: [],
+  },
+  defaultSize: 'md',
+} as const
+
+export { Textarea, textareaVariants }