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

package/src/components/Tag/tag.stories.tsx

@@ -0,0 +1,88 @@
+import React from 'react'
+import type { Meta, StoryObj } from '@storybook/react'
+import { within } from '@storybook/test'
+import { Tag } from './tag'
+
+const meta: Meta<typeof Tag> = {
+  title: 'Design System/Components/Tag/展示',
+  component: Tag,
+  tags: ['autodocs'],
+  parameters: {
+    docs: {
+      description: {
+        component: 'Inline label，用於分類標籤、狀態標記、多選已選值。以色名命名 variant，語義由消費端決定。',
+      },
+    },
+  },
+}
+
+export default meta
+type Story = StoryObj<typeof Tag>
+
+/* ── Avatar ── */
+export const WithAvatar: Story = {
+  name: '頭像',
+  render: () => (
+    <div className="flex flex-wrap gap-2">
+      <Tag color="neutral" avatar={
+        <img src="https://i.pravatar.cc/32?u=alice" alt="" className="rounded-full object-cover" />
+      }>
+        Alice Chen
+      </Tag>
+      <Tag color="neutral" avatar={
+        <img src="https://i.pravatar.cc/32?u=bob" alt="" className="rounded-full object-cover" />
+      }>
+        Bob Lin
+      </Tag>
+      <p className="w-full text-caption text-fg-muted">Tag 內部統一 avatar 為 16px（跟 icon 一致），消費端不用指定尺寸</p>
+    </div>
+  ),
+}
+
+/* ── Dismiss ── */
+export const Dismissable: Story = {
+  name: '可移除',
+  render: () => {
+    const [tags, setTags] = React.useState(['Electronics', 'Furniture', 'Food'])
+    return (
+      <div className="flex flex-col gap-3">
+        <div className="flex flex-wrap gap-1">
+          {tags.map(t => (
+            <Tag key={t} color="neutral" onRemove={() => setTags(prev => prev.filter(x => x !== t))}>{t}</Tag>
+          ))}
+        </div>
+        {tags.length === 0 && <p className="text-caption text-fg-muted">全部移除了，重新整理頁面可恢復</p>}
+      </div>
+    )
+  },
+}
+
+// neutral subtle Tag 是 beta.97 校正的 neutral host 分支:
+// remove action 應由 fg-muted 只前進一階到 fg-secondary。
+export const DismissHoverState: Story = {
+  name: '移除標籤懸停狀態',
+  tags: ['test-only'],
+  render: () => (
+    <div className="flex items-center gap-2">
+      <Tag color="neutral" onRemove={() => {}}>付款待確認</Tag>
+      <span className="text-caption text-fg-secondary">發票篩選條件</span>
+    </div>
+  ),
+  play: async ({ canvasElement }) => {
+    const canvas = within(canvasElement)
+    const dismiss = await canvas.findByRole('button', { name: '移除 付款待確認' })
+    dismiss.setAttribute('data-visual-hover-target', '')
+  },
+}
+
+/* ── 截斷 + Tooltip ── */
+export const Truncation: Story = {
+  name: '截斷 + Tooltip',
+  render: () => (
+    <div className="flex flex-col gap-3" style={{ maxWidth: 300 }}>
+      <Tag color="neutral">Bug</Tag>
+      <Tag color="blue">Q3 Checkout Funnel Redesign — Payment Step</Tag>
+      <p className="text-caption text-fg-muted">超過 160px 自動截斷，hover 顯示完整文字 tooltip</p>
+    </div>
+  ),
+}

package/src/components/Tag/tag.tsx

@@ -5,7 +5,9 @@ import type { LucideIcon } from "lucide-react"
 
 import { cn } from "@/lib/utils"
 import { Tooltip, TooltipTrigger, TooltipContent } from "@/design-system/components/Tooltip/tooltip"
+import { useTruncated } from "@/design-system/hooks/use-truncated"
 import { ItemInlineActionButton } from "@/design-system/patterns/element-anatomy/item-anatomy"
+import { CAT_SUBTLE, CAT_SOLID, CAT_INTERACT } from "@/design-system/tokens/categorical-color"
 
 // ── Tag（inline label）─────────────────────────────────────────────────────
 // 用於分類標籤、狀態標記、多選已選值。
@@ -28,18 +30,13 @@ const tagVariants = cva(
   "inline-flex items-center rounded-md border border-transparent transition-colors cursor-text",
   {
     variants: {
+      // color：categorical 色相(裝飾性分類,非語意狀態)。**消費 categorical-color SSOT**——
+      // key X 一律對 `--color-X-*`(1:1,零 offset)。neutral 非色相(無 hue),用 secondary 底自處理。
+      // 2026-06-04 修:原 `red` 誤接 `--color-deep-orange-*`(red=品牌紅 hue-25 ≠ deep-orange hue-38
+      // ≠ 語意 --error〔= deep-orange〕);改消費 SSOT 後 red→`--color-red-*`,並補齊全 12 色相。
       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)]",
+        neutral: "bg-secondary text-foreground",
+        ...CAT_SUBTLE,
       },
       size: {
         sm: "h-5 px-1 text-caption font-medium",
@@ -54,19 +51,13 @@ const tagVariants = cva(
   }
 )
 
-// ── Solid variant 色彩（step-6 底 + 白字，warning 用 --warning-foreground）──
-// 直接引用 primitive step-6，不經過語義層
-// neutral 用 neutral-9 + --inverse-fg（light=白字, dark=深字，自動反轉）
+// ── Solid variant 色彩（step-6 底 + on-emphasis 配對文字,消費 categorical-color SSOT）──
+// 白字 --on-emphasis(夠深的 hue)/ 深字 --on-emphasis-dark(亮 hue:yellow/amber/orange/lime);green 白字例外。
+// **消費 categorical-color SSOT**(CAT_SOLID,1:1 色相)。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',
+  neutral: 'bg-[var(--color-neutral-9)] text-inverse-fg',
+  ...CAT_SOLID,
 }
 
 export interface TagProps
@@ -76,9 +67,13 @@ export interface TagProps
   icon?: LucideIcon
   /** 左側 avatar（ReactNode），與 icon 互斥。 */
   avatar?: React.ReactNode
-  /** 可移除——Tag 自動渲染 dismiss 按鈕並控制尺寸與互動樣式 */
-  onDismiss?: () => void
-  /** 深底白字模式（step-6 背景 + 白色前景，warning 例外） */
+  /** 可移除——Tag 自動渲染 remove 按鈕並控制尺寸與互動樣式(從集合移除 item) */
+  onRemove?: () => void
+  /** remove 按鈕的 aria-label 目標名(a11y)。children 為非字串 ReactNode 時建議傳,否則 SR 讀不出移除哪個 tag。預設取 string children。對齊 FileUpload `removeAriaLabel`(同「移除集合項目」場景 + DS `<動作>AriaLabel` 命名慣例)。 */
+  removeAriaLabel?: string
+  /** @deprecated 2026-07-17 改名為 `removeAriaLabel`(對齊 FileUpload + onRemove callback 語意;dismiss 保留給 Alert/Notice/Toast「通知被忽略」)。舊名過渡一版後移除。 */
+  dismissLabel?: string
+  /** 深底模式（step-6 背景 + on-emphasis 配對前景;亮色 hue yellow/amber/orange/lime 用深字 --on-emphasis-dark,green 白字例外） */
   solid?: boolean
   /**
    * 2026-05-15 Q3 真 SSOT fix(per user verbatim「同空間兩判斷點」+「不要冰山一角」):
@@ -91,20 +86,13 @@ export interface TagProps
 }
 
 // ── 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-* 鏡射
+// **消費 categorical-color SSOT**(CAT_INTERACT,semantic --{hue}-hover/active token),
+// 跟 --primary-hover/active 同模式:solid 色彩 shade change(hover 較亮 step、active 較暗 step),
+// 在 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)' },
+  neutral: { hover: 'var(--inverse-neutral-hover)', active: 'var(--inverse-neutral-active)' },
+  ...CAT_INTERACT,
 }
 
 // ── Dismiss（internal）────────────────────────────────────────────────────
@@ -114,44 +102,54 @@ const SOLID_DISMISS_HOVER: Record<string, { hover: string; active: string }> = {
 // 視覺對齊:`size="md"` → icon 16 / hover-bg 18,跟 Tag 既有手刻幾何完全相等。
 // Solid variant(blue/green/red 等)透過 `hoverBgClassName` 套色相 override token;
 // Subtle variant 落用 ItemInlineActionButton 預設 neutral-hover。
-// 圖標色繼承 Tag 文字色 → `text-current` 三態覆寫。
+// 圖標色依 host 分兩支(inline-action.spec.md「Icon 色彩」判斷法):
+// **colored host**(12 色相任一,或 solid neutral 的 neutral-9 深底)→ `text-current` 三態覆寫,
+//   繼承 Tag 文字色維持「一個整體視覺單元」。
+// **neutral subtle**(`bg-secondary` 中性宿主)→ **不 override**,落回 primitive 預設
+//   `fg-muted` → hover `fg-secondary`。2026-07-30 user 拍板修正 97e62a80 的過度泛化:
+//   該 commit 自陳病症「fg-muted breaks on colored Tags」只發生在有色宿主,卻 unified 全 variant,
+//   把中性宿主也拖走(且未經 user 拍板改 UI/UX SSOT)。
 
-function TagDismiss({ onDismiss, label, solid, color }: { onDismiss: () => void; label: string; solid?: boolean; color?: string }) {
+function TagDismiss({ onRemove, label, solid, color }: { onRemove: () => void; label: string; solid?: boolean; color?: string }) {
   const solidColors = solid && color ? SOLID_DISMISS_HOVER[color] : undefined
+  // colored host 判定:有色相 → 是;solid neutral(neutral-9 深底 + text-inverse-fg)→ 也是。
+  const inheritsHostColor = solid === true || (color ?? 'neutral') !== 'neutral'
 
   return (
     <ItemInlineActionButton
       icon={X}
       size="md"
-      onClick={(e) => { e.stopPropagation(); onDismiss() }}
-      aria-label={`移除 ${label}`}
+      onClick={(e) => { e.stopPropagation(); onRemove() }}
+      data-collection-remove
+      aria-label={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"
+      // colored host 才 override primitive 預設(繼承 Tag 文字色,label 同色);
+      // neutral subtle 留給 primitive 的 fg-muted → hover fg-secondary 階梯。
+      className={inheritsHostColor ? 'text-current hover:text-current active:text-current' : undefined}
     />
   )
 }
 
 function TagInner(
-  { className, color, size, icon: Icon, avatar, onDismiss, solid, unbounded = false, children, style, ...props }: TagProps,
+  { className, color, size, icon: Icon, avatar, onRemove, removeAriaLabel, dismissLabel, 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 = () => {
+  // 截斷偵測用 SSOT 引擎 `useTruncated`(patterns/element-anatomy 的 hook)。Tag 走**變異型**:
+  //   - measure = Canvas measureText(flex 內 scrollWidth 不可靠,line 20)：observe root、量測內層
+  //     `[data-tag-text]` span(trigger≠量測元素);回 undefined = 無法量測時保留前一 state。
+  //   - timing='layoutEffect'(避免 paint flash)/ deps=[children](children 變重量)/ recheckAfterPaint=false
+  //     (Tag 原本即無 rAF/timeout 二次量)—— 三處變異全走 options,行為零漂移。
+  const { ref: ownRef, isTruncated } = useTruncated<HTMLDivElement>({
+    measure: (el) => {
       const textSpan = el.querySelector('[data-tag-text]')
-      if (!textSpan || !ctx) return
+      const ctx = getMeasureCtx()
+      if (!textSpan || !ctx) return undefined
       const text = textSpan.textContent || ''
       const cs = getComputedStyle(textSpan)
       ctx.font = `${cs.fontWeight} ${cs.fontSize} ${cs.fontFamily}`
@@ -159,16 +157,26 @@ function TagInner(
       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])
+      return needed > (textSpan as HTMLElement).clientWidth + 1
+    },
+    deps: [children],
+    timing: 'layoutEffect',
+    recheckAfterPaint: false,
+  })
 
   const label = typeof children === 'string' ? children : ''
 
+  // ── Dev-mode warning:icon 與 avatar 互斥 ──
+  // 兩者同為 prefix slot(tag.spec.md Props 表「與 avatar 互斥」),同時傳會並列渲染破壞 Tag
+  // 內部結構;原僅 jsdoc/spec 約束會靜默通過 → 2026-07-05 對齊 Button overlayBadge dev-warn
+  // 先例(button.tsx「Dev-mode warning」段)補齊家族一致 runtime 防線。
+  if (process.env.NODE_ENV !== 'production' && Icon && avatar) {
+    // eslint-disable-next-line no-console
+    console.warn(
+      '[DS Tag] `icon` 與 `avatar` 互斥(同為 prefix slot),同時傳會並列渲染破壞 Tag 內部結構,請只擇一。SSOT:tag.spec.md Props 表 + tag.principles.stories.tsx IconRule。'
+    )
+  }
+
   const tag = (
     <div
       ref={(el) => {
@@ -177,7 +185,18 @@ function TagInner(
         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)}
+      // 截斷時條件性可 focus(2026-07-06 user 拍板「確認世界級有這樣做就做」——APG Tooltip
+      // pattern 原文:tooltip 在元素「收到鍵盤焦點」或 hover 時顯示,trigger 可 focus 是
+      // W3C 官方 pattern 前提;Radix Tooltip focus-open 自動生效 → 鍵盤 Tab 到即見全文。
+      // 未截斷不入 tab 序(維持 tag.spec「靜態 Tag 不取得 focus」預設,不汙染 tab order)。
+      tabIndex={isTruncated ? 0 : undefined}
+      className={cn(
+        tagVariants({ color, size }),
+        solidClass,
+        'w-fit min-w-0 overflow-hidden',
+        isTruncated && 'focus-visible:outline-none focus-visible:ring-2 focus-visible:ring-ring focus-visible:ring-offset-1',
+        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
@@ -195,14 +214,18 @@ function TagInner(
       {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'} />}
+      {onRemove && <TagDismiss onRemove={onRemove} label={removeAriaLabel ?? dismissLabel ?? label} solid={solid} color={color ?? 'neutral'} />}
     </div>
   )
 
-  if (!isTruncated) return tag
-
+  // 永遠 wrap Tooltip、以 open 控制可見(對齊 truncated-text.spec.md:49「永遠 wrap」+ :55「❌ 條件 wrap」canonical
+  // + useTruncated 家族;tooltip.principles.stories.tsx:190「沒被截斷就不該顯示 tooltip」由 open={false} 機械保證)。
+  // 未截斷 open={false} → tooltip 靜默(TooltipTrigger asChild 只把 handler/data-state 合併到 tag div,零多餘 DOM、
+  // 視覺與裸 tag 等價,pixel-identical)。always-wrap 保 tag div 生命週期穩定 → isTruncated false→true 不 remount:
+  // 先前條件-wrap(未截斷回裸 tag / 截斷才 wrap)切換 JSX 樹會 remount tag div,但 useTruncated deps=[children] 未變
+  // → effect 不重跑重新 observe 新 div → shared RO 卡在舊 detached div → isTruncated 卡 true(未截斷仍顯示 tooltip)。
   return (
-    <Tooltip>
+    <Tooltip open={isTruncated ? undefined : false}>
       <TooltipTrigger asChild>{tag}</TooltipTrigger>
       <TooltipContent>{children}</TooltipContent>
     </Tooltip>
@@ -217,24 +240,41 @@ Tag.displayName = 'Tag'
 export const tagMeta = {
   component: 'Tag',
   family: 3,
+  // categorical 色相(裝飾性分類,非語意狀態)。色名 1:1 對 primitive hue family,零 offset。
+  // 不對應語意 token——語意狀態(error/info/success/warning)走 Notice / Alert 等狀態元件,
+  // 不是 Tag 色相。2026-06-04 修:移除原「red 對應 --error / blue 對應 --info ...」誤導框架
+  // (red = 品牌紅 hue-25,跟語意 --error〔= deep-orange〕無關)。
   variants: {
-    neutral: { purpose: '通用分類、草稿、無特定語義' },
-    blue: { purpose: '進行中、資訊提示、active 狀態（對應 --info）' },
-    red: { purpose: '錯誤、已封鎖、危險（對應 --error）' },
-    green: { purpose: '成功、已完成、已核准（對應 --success）' },
-    yellow: { purpose: '警告、待審核、注意（對應 --warning）' },
-    turquoise: { purpose: '分類色（無固定語義）' },
-    purple: { purpose: '分類色（無固定語義）' },
-    magenta: { purpose: '分類色（無固定語義）' },
-    indigo: { purpose: '分類色（無固定語義）' },
+    neutral: { purpose: '通用分類、草稿、無特定語義(secondary 底)' },
+    blue: { purpose: 'categorical 色相(--color-blue-*)' },
+    green: { purpose: 'categorical 色相(--color-green-*)' },
+    'deep-orange': { purpose: 'categorical 色相(--color-deep-orange-*,hue 38)' },
+    yellow: { purpose: 'categorical 色相(--color-yellow-*,淺底深字)' },
+    red: { purpose: 'categorical 色相(--color-red-*,品牌紅家族 hue 25;≠ 語意 --error)' },
+    orange: { purpose: 'categorical 色相(--color-orange-*)' },
+    amber: { purpose: 'categorical 色相(--color-amber-*,淺底深字)' },
+    lime: { purpose: 'categorical 色相(--color-lime-*)' },
+    turquoise: { purpose: 'categorical 色相(--color-turquoise-*)' },
+    indigo: { purpose: 'categorical 色相(--color-indigo-*)' },
+    purple: { purpose: 'categorical 色相(--color-purple-*)' },
+    magenta: { purpose: 'categorical 色相(--color-magenta-*)' },
   },
   sizes: {
-    sm: { fieldHeight: 28, iconSize: 16, typography: 'body' },
-    md: { fieldHeight: 32, iconSize: 16, typography: 'body' },
-    lg: { fieldHeight: 40, iconSize: 20, typography: 'body' },
+    // Tag 尺寸不引用 field-height token（spec「尺寸」段——Tag 與 Field 尺寸獨立;段名指法免行號漂移）。
+    // height = Tag 自身高度（cva h-5/h-6/h-6 = 20/24/24，lg = md alias）。
+    // iconSize 全尺寸統一 16（本檔 CAT icon render 硬寫 size={16}）。
+    sm: { height: 20, iconSize: 16, typography: 'caption' },
+    md: { height: 24, iconSize: 16, typography: 'body' },
+    lg: { height: 24, iconSize: 16, typography: 'body' },
   },
-  states: ['default', 'hover', 'active', 'focus-visible', 'disabled'],
+  // Tag 為純展示 indicator，無互動 state（spec「為何無 StateBehavior」段;段名指法免行號漂移）。
+  // 唯一行為 dismiss 屬 Inline Action pattern，非 Tag 自有 state。
+  states: ['default'],
   tokens: {
+    // 2026-07-04 audit 註記:另有動態色相家族不逐一列 — CAT_SUBTLE 12 色相
+    // subtle background + step-7 深字、CAT_SOLID step-6 底 + --on-emphasis(-dark) 配字、
+    // neutral solid bg-[var(--color-neutral-9)] — 全由 categorical-color.ts SSOT 衍生
+    //(anatomy TOKEN_MAP 以 stripVar 機械衍生,零漂移)。
     bg: ['bg-neutral-active', 'bg-neutral-hover', 'bg-secondary', 'bg-transparent'],
     fg: ['text-foreground', 'text-inverse-fg'],
     ring: [],

package/src/components/Textarea/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 './textarea'