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

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

@@ -0,0 +1,57 @@
+// @story-trait-rationale: isInputLike -> InField — InField 已同時渲染 invalid Field chrome 與 FieldError；另開 error-only story 會重複相同表單情境。
+// @story-history: 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',
+    docs: { description: { component: '多行文字輸入控制項，支援不同尺寸、驗證與表單 Field 組合。需要輸入描述、備註或段落內容時使用；短且單行的資料改用 Input。' } },
+  },
+}
+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-history: 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

@@ -2,24 +2,25 @@
 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'
+import type { FieldMode, FieldVariant, FieldVariantInternal } from '@/design-system/components/Field/field-types'
+import { useFieldContext, useResolvedFieldSize, useResolvedFieldMode, useResolvedFieldVariant, useResolvedFieldInvalid } from '@/design-system/components/Field/field-context'
+import { useFieldEmptyDisplay, fieldEmptyColorClass } from '@/design-system/components/Field/field-context'
+import { useControllable } from '@/design-system/hooks/use-controllable'
 
 /**
  * Textarea — 多行文字輸入
  *
  * ── 定位 ────────────────────────────────────────────────────────────────
- * 多行版本的 Input，edit / display / readonly / disabled 四態與 Input 邏輯一致(Phase B1 2026-05-05)。
+ * 多行版本的 Input，edit / view / 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 保留多行文本
+ *   - view 渲染 <div> + white-space:pre-wrap 保留多行文本
  *
  * ── Padding 規則 ───────────────────────────────────────────────────────
- * 多行內容必須有上下內距才能閱讀舒適。不沿用 Input 的 items-center，
- * 改用 py-2（8px）固定上下內距 + px-3 左右內距（與 Input 一致）。
+ * 多行內容必須有上下內距才能閱讀舒適。不沿用 Input 的 items-center；
+ * 上下內距使用 size 對應的 `--field-control-py-*` token，左右使用 `--field-px`，與同 size Input/Field family 幾何一致。
  *
  * ── Size ────────────────────────────────────────────────────────────────
  * sm / md → text-body（14px）
@@ -29,8 +30,8 @@ import { EMPTY_DISPLAY } from '@/design-system/components/Field/field-wrapper'
  * 預設 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)。
+// Phase B1(2026-05-05):chrome variant(default / naked;`bare` 2026-07-09 退役),mode×chrome 的
+// chrome 規則由 compoundVariants 決定,鏡射 fieldWrapperStyles 對齊 canonical(Phase D 將整併進 fieldWrapperStyles)。
 const textareaVariants = cva(
   [
     'w-full rounded-md',
@@ -40,27 +41,33 @@ 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)]',
     'transition-colors duration-150',
   ],
   {
     variants: {
       mode: {
         edit: '',
-        display: '',
+        view: '',
         readonly: '',
         disabled: '',
       },
-      // chrome 對齊 fieldWrapperStyles.variant(default / bare / naked)。
+      // chrome 對齊 fieldWrapperStyles.variant(default / naked;2026-07-09 `bare` 退役)。
       variant: {
         default: '',
-        bare: '',
         naked: '',
       },
+      // py 隨 size 走 --field-control-py-* 公式,讓單行 Textarea 與同 size Input 等高
+      // (uiSize.css SSOT;DataTable naked compound 以 !py-* 覆蓋,不受影響)
       size: {
-        sm: 'text-body',
-        md: 'text-body',
-        lg: 'text-body-lg',
+        sm: 'text-body py-[var(--field-control-py-sm)]',
+        md: 'text-body py-[var(--field-control-py-md)]',
+        lg: 'text-body-lg py-[var(--field-control-py-lg)]',
+      },
+      // error(2026-07-04 Q1,鏡射 fieldWrapperStyles error variant;Phase D 整併時一起收)
+      error: {
+        true: '',
+        false: '',
       },
     },
     compoundVariants: [
@@ -71,51 +78,39 @@ const textareaVariants = cva(
         className: [
           'bg-surface border border-border',
           'hover:border-border-hover',
-          'focus-visible:!border-primary focus-visible:hover:!border-primary',
         ],
       },
+      { mode: 'edit', variant: 'default', error: false, className: 'focus-within:!border-primary focus-within:hover:!border-primary' },
       {
-        mode: 'display',
+        // 2026-07-16 round16 Model A(user GO,推翻 2026-05-13 Path Ⅰ 的 `!px-0 !py-0`):
+        // Textarea view×default = **edit 幾何減 chrome** — 保留 base 的 field-px 與
+        // size 對應 field-control-py token(= edit 內距),只拔 border/bg。多行 read↔edit 零跳。跟 Field wrapper
+        // view×default 同 SSOT(field-wrapper.tsx)。
+        mode: 'view',
         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',
+        className: 'bg-transparent border border-transparent',
       },
       {
         mode: 'readonly',
         variant: 'default',
-        className: 'bg-disabled border border-transparent',
+        // 2026-07-13 a11y(WCAG 2.4.7):readonly 有值渲 native <textarea readOnly> 可鍵盤聚焦,base
+        //   outline-none + border-transparent 無焦點指示 → 鏡射 field-wrapper.tsx readonly ring idiom
+        //   (field-controls.spec.md「readonly focus ring」)。textarea 為裸 focusable element,直接用
+        //   focus-visible:(非 :has()),僅鍵盤聚焦顯示、滑鼠點擊不觸發。
+        className: 'bg-readonly border border-transparent focus-visible:ring-2 focus-visible:ring-ring focus-visible:ring-offset-1',
       },
       {
         mode: 'disabled',
         variant: 'default',
         className: 'bg-disabled border border-transparent cursor-not-allowed text-fg-disabled',
       },
-      // bare chrome × mode(對齊 fieldWrapperStyles bare 規則)
+      // (2026-07-09 `bare` chrome × mode compounds 退役已移除;error:true 為 variant-agnostic 保留)
       {
         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',
+        error: true,
+        className: 'border-error hover:border-error-hover focus-within:!border-error focus-within:hover:!border-error',
       },
+      // (2026-07-09 display×bare / readonly×bare / disabled×bare compounds 退役已移除)
       // 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)。
@@ -127,29 +122,28 @@ const textareaVariants = cva(
           '!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
+          // textarea UA stylesheet 預設 line-height: normal(1.2-1.5 不定),會跟 view
           // `<div>` text-body line-height: 1.5(21px @ 14px)不一致 → cell 進 edit 後 height
           // shift。顯式 leading 對齊 div 行為。
           '!leading-[1.5]',
         ],
       },
+      { mode: 'edit', variant: 'naked', error: false, className: 'focus-visible:!border-primary focus-visible:hover:!border-primary' },
       // 2026-05-13 Q1 R4 verify(per codex Q1 verdict 補 Textarea nuance):
-      // Textarea naked display/readonly/disabled 用 `!h-full`,**不**對齊 Field wrapper 的 `!h-auto`。
+      // Textarea view×naked 用 `!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]' },
+      { mode: 'view', variant: 'naked', className: 'bg-transparent !rounded-none !h-full !resize-none !px-0 !py-0 border border-transparent !leading-[1.5]' },
+      // 2026-07-16 round16:`readonly×naked` / `disabled×naked` 死格移除(鏡射 field-wrapper.tsx;
+      //   DataTable cell 廢 disabled 態 + readonly 從不入 naked,全庫 0 消費)。
     ],
     defaultVariants: {
       mode: 'edit',
       variant: 'default',
       size: 'md',
+      error: false,
     },
   }
 )
@@ -157,16 +151,26 @@ const textareaVariants = cva(
 export interface TextareaProps
   extends Omit<React.TextareaHTMLAttributes<HTMLTextAreaElement>, 'size'>,
     Omit<VariantProps<typeof textareaVariants>, 'mode' | 'variant'> {
-  /** Field display mode */
+  /** Field view 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)
+   * (2026-07-09 `bare` variant 退役;naked = cell-as-input substrate,@internal)
+   * - `'naked'` — 完全無 chrome,cell-as-input(host cell 提供 border + focus frame,對齊 Airtable / Notion / Excel cell editing)
    */
   variant?: FieldVariant
   /** Error 狀態（正交於 mode）。border-error + aria-invalid。 */
   error?: boolean
+  /**
+   * Edit 態高度隨內容(`field-sizing: content`)。`{ maxRows }` 設上限,超過改捲動。
+   *
+   * 為何是能力而非預設:表單 Textarea 的 `rows={3}` 預留高度是刻意的(textarea.spec.md
+   * 「rows / min-h」);但 cell-as-input 與 InlineEdit 的 view 態高度由內容決定,edit 若固定
+   * rows 就會在 read↔edit 之間跳高。此 prop 讓兩種語境共用同一份實作,而非各自在呼叫端手刻
+   * (原本只有 DataTable cell-registry 有這段膠水,InlineEdit 因此漂移)。
+   */
+  autoSize?: boolean | { maxRows?: number }
 }
 
 // code-quality-allow: long-function — Textarea forwardRef body 含 mode×size×variant×error 4 軸 prop + autoFocus + aria 完整覆蓋,拆 sub-fn 會把 useFieldContext / fieldWrapperStyles 跨檔 drilling
@@ -180,8 +184,10 @@ const Textarea = React.forwardRef<HTMLTextAreaElement, TextareaProps>(
       className,
       disabled,
       readOnly,
-      rows = 3,
+      rows: rowsProp,
+      autoSize = false,
       value,
+      defaultValue,
       id: idProp,
       'aria-describedby': ariaDescribedByProp,
       'aria-errormessage': ariaErrorMessageProp,
@@ -192,46 +198,105 @@ 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: FieldVariantInternal = 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 emptyDisplay = useFieldEmptyDisplay()
     const isEditable = resolvedMode === 'edit'
-    const isDisplay = resolvedMode === 'display'
+    const isView = resolvedMode === 'view'
     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 保留多行) ──
+    // ── view mode(+ readonly 空值)純展示,渲染 <div> 取代 <textarea>(white-space:pre-wrap 保留多行) ──
     // 對齊 Carbon read-only / Cloudscape display-mode
-    if (isDisplay) {
-      const displayValue = value != null && value !== '' ? String(value) : null
+    // 2026-07-08 user 拍板:readonly 空值也走 view-div 顯 '-'(readonly **有值** 仍走下方
+    // native <textarea readOnly> 保留選取/複製語意 — field-controls.spec.md「null / undefined 值」)。
+    // 2026-07-13 fix:空值判斷需認得 uncontrolled defaultValue — readonly / view 也要顯示內容,
+    //   不可誤判為空值渲 '-'(原為靜態 value ?? defaultValue)。
+    // 2026-07-14 R2(dual-model consensus,同 Input input.tsx):resolved value 改走 useControllable
+    // 內部 SSOT(Radix idiom)。原靜態版有 typing-stale gap:uncontrolled 打字後外部切
+    // view / readonly 仍顯示 stale defaultValue。uncontrolled 時 native textarea 由
+    // value={resolved} 內部驅動(defaultValue 只作初始值,不落 DOM attribute),同時修
+    // remount-stale(切 view 再回 edit 從 defaultValue attribute 重掛)+ form.reset() stale
+    // (HTML 標準 reset 不發 input event,下方 reset bridge 修)。controlled(傳 value)時
+    // useControllable 純 passthrough,行為與原本完全一致。consumer onChange 不接進 hook
+    // (保留 native event signature),於 <textarea> onChange 另行轉發。
+    const isControlled = value !== undefined
+    const [resolved, setResolved] = useControllable<string | number | readonly string[]>({
+      value: value as string | number | readonly string[] | undefined,
+      defaultValue: defaultValue ?? '',
+    })
+    const displayValue = resolved != null && resolved !== '' ? String(resolved) : null
+    const showDisplaySpan = isView || (resolvedMode === 'readonly' && displayValue == null)
+
+    // form.reset() bridge(uncontrolled only):reset 恢復 defaultValue 但不發 input event →
+    // 手動把 resolved 歸位 defaultValue。keyed on showDisplaySpan:view 分支不掛 native
+    // textarea,回 edit 重掛時 effect 重跑補掛 listener。
+    const innerRef = React.useRef<HTMLTextAreaElement | null>(null)
+    React.useEffect(() => {
+      if (isControlled || showDisplaySpan) return
+      const form = innerRef.current?.form
+      if (!form) return
+      const handleReset = () => setResolved(defaultValue ?? '')
+      form.addEventListener('reset', handleReset)
+      return () => form.removeEventListener('reset', handleReset)
+    }, [isControlled, showDisplaySpan, defaultValue, setResolved])
+    // Merge refs(LinkInput setRef idiom,link-input.tsx:138)
+    const setRef = React.useCallback((el: HTMLTextAreaElement | null) => {
+      innerRef.current = el
+      if (typeof ref === 'function') ref(el)
+      else if (ref) (ref as React.MutableRefObject<HTMLTextAreaElement | null>).current = el
+    }, [ref])
+
+    if (showDisplaySpan) {
+      const spanMode = isView ? 'view' : 'readonly'
       return (
         <div
           id={inputId}
-          data-field-mode="display"
+          data-field-mode={spanMode}
           aria-describedby={ariaDescribedBy}
           className={cn(
-            textareaVariants({ mode: 'display', variant: variant, size }),
+            textareaVariants({ mode: spanMode, variant: variant, size }),
             'whitespace-pre-wrap break-words',
-            displayValue == null && 'text-fg-muted',
+            displayValue == null && fieldEmptyColorClass(resolvedMode),
             className,
           )}
         >
-          {displayValue ?? EMPTY_DISPLAY}
+          {displayValue ?? emptyDisplay}
         </div>
       )
     }
 
+    // autoSize:`field-sizing: content` 讓 textarea 長到內容高度(Chrome 123+ / FF 122+ / Safari 17+)。
+    // rows 是舊瀏覽器 fallback——沿用 cell 既有的換行 + 折行估算,別讓不支援的環境退回單行。
+    const autoSizeMaxRows = typeof autoSize === 'object' ? autoSize.maxRows : undefined
+    const autoSizeRows = () => {
+      const text = String(resolved ?? '')
+      const newlineRows = (text.match(/\n/g) || []).length + 1
+      const wrapRows = Math.ceil(text.length / 40)
+      return Math.min(autoSizeMaxRows ?? 10, Math.max(1, newlineRows, wrapRows))
+    }
+    const rows = rowsProp ?? (autoSize ? autoSizeRows() : 3)
+    const autoSizeStyle: React.CSSProperties | undefined = autoSize
+      ? ({
+        // any-allow: CSS `field-sizing` 尚未進 TypeScript lib.dom,narrow 到 CSSProperties 仍需 cast
+        fieldSizing: 'content',
+        ...(autoSizeMaxRows === undefined
+          ? {}
+          : { maxHeight: `calc(${autoSizeMaxRows} * 1lh + 2 * var(--field-control-py-${size}) + 2px)` }),
+      } as React.CSSProperties)
+      : undefined
+
     return (
       <textarea
-        ref={ref}
+        ref={setRef}
         id={inputId}
         rows={rows}
-        value={value as string | number | readonly string[] | undefined}
+        style={autoSizeStyle ? { ...autoSizeStyle, ...props.style } : props.style}
+        value={resolved}
         disabled={resolvedMode === 'disabled'}
         readOnly={resolvedMode === 'readonly'}
         aria-invalid={error || undefined}
@@ -241,14 +306,15 @@ const Textarea = React.forwardRef<HTMLTextAreaElement, TextareaProps>(
         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',
-          ],
+          textareaVariants({ mode: resolvedMode, variant: variant, size, error }),
           className
         )}
         {...props}
+        // 置於 {...props} 後:寫回 resolved SSOT(controlled 時 useControllable 內部為 no-op)再轉發 consumer onChange。
+        onChange={(e) => {
+          setResolved(e.target.value)
+          props.onChange?.(e)
+        }}
       />
     )
   }
@@ -256,7 +322,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,13 +331,17 @@ 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 共識)。
+  //   'focus-visible' 泛指 focus 態:default chrome 實為 focus-within(滑鼠+鍵盤皆亮),naked chrome
+  //   為 focus-visible(鍵盤限定),readonly 有值態為 focus-visible ring(見上方 compoundVariants)。
+  states: ['default', 'hover', 'focus-visible', 'readonly', 'disabled', 'error'],
   tokens: {
-    bg: ['bg-disabled', 'bg-surface'],
+    bg: ['bg-disabled', 'bg-readonly', 'bg-surface'], // 2026-07-04 補:readonly×default cva 實際消費(spec「Readonly 特例」主打 token)
     fg: ['text-fg-disabled', 'text-fg-muted', 'text-foreground'],
     ring: [],
   },

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>) => {
@@ -142,14 +147,19 @@ function TimeColumn({ values, selected, disabledSet, label, onSelect, withDivide
   //   - TimePicker:wrap in h-[216px] container(預設 ~7 items)
   //   - DatePicker showTime / Range:flex-row items-stretch + calendar 一起決定高度(自動同高)
   return (
-    <ScrollArea className={cn('flex-1 h-full', withDivider && 'border-r border-divider')}>
+    // viewportTabIndex=-1:焦點直接落 listbox(有 keydown),消除「Viewport+listbox 雙 tab stop
+    // + 焦點落 Viewport 時 ↑/↓ 觸發原生捲動非選值」a11y bug(axe 由 listbox tabIndex=0 滿足)
+    <ScrollArea viewportTabIndex={-1} className={cn('flex-1 h-full', withDivider && 'border-r border-divider')}>
       <div
         ref={listRef}
         role="listbox"
         aria-label={label}
+        // guard values.includes:off-step value(如 minuteStep=15 但分=07)的 option 未渲染,
+        // 指向未渲染 id = 懸空 ARIA 參照(AT 讀空);僅真實渲染的 option 才掛
+        aria-activedescendant={selected != null && values.includes(selected) ? `${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 +167,7 @@ function TimeColumn({ values, selected, disabledSet, label, onSelect, withDivide
           return (
             <button
               key={v}
+              id={`${baseId}-opt-${v}`}
               type="button"
               role="option"
               aria-selected={isSelected}
@@ -170,7 +181,8 @@ function TimeColumn({ values, selected, disabledSet, label, onSelect, withDivide
                 'flex items-center justify-center',
                 'cursor-pointer transition-colors',
                 'hover:bg-neutral-hover',
-                isSelected && 'bg-neutral-selected text-foreground hover:bg-neutral-selected',
+                // 2026-08-11(SSOT = item-anatomy「選中 × 互動疊加」):滑鼠釘住本就正確;補鍵盤焦點深一階。
+                isSelected && 'bg-neutral-selected text-foreground hover:bg-neutral-selected focus-visible:bg-neutral-selected-focus',
                 isDisabled && 'text-fg-disabled cursor-not-allowed hover:bg-transparent',
               )}
             >