@qijenchen/design-system 0.1.0-beta.6 → 0.1.0-beta.60

package/src/components/NumberInput/number-input.principles.stories.tsx

@@ -0,0 +1,221 @@
+// @principles-rationale: UsageGuidance merges WhenToUse + WhenNotToUse into single 使用指引 story per refactor task (2026-04-26)
+import React from 'react'
+import LinkTo from '@storybook/addon-links/react'
+import type { Meta, StoryObj } from '@storybook/react'
+import { createColumnHelper } from '@tanstack/react-table'
+import { NumberInput } from './number-input'
+import { Input } from '@/design-system/components/Input/input'
+import { DataTable } from '@/design-system/components/DataTable/data-table'
+import '@/design-system/components/DataTable/column-types'
+
+const meta: Meta = {
+  title: 'Design System/Components/NumberInput/設計原則',
+  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>
+)
+
+const Section = ({ title, children }: { title: string; children: React.ReactNode }) => (
+  <section className="mb-12">
+    <h2 className="text-heading-3 font-bold text-foreground mb-4 pb-2 border-b border-border">{title}</h2>
+    {children}
+  </section>
+)
+
+// ── Stories ───────────────────────────────────────────────────────────────────
+
+export const UsageGuidance: Story = {
+  name: '使用指引',
+  render: () => (
+    <div>
+      <Section title="何時用">
+        <div className="prose prose-sm max-w-prose mb-8">
+          <p>適合 NumberInput 的真實業務場景(點擊跳轉「展示」頁範例):</p>
+          <ul className="space-y-1">
+            <li><LinkTo kind="Design System/Components/NumberInput/展示" name="四模式"><span className="text-primary hover:underline font-medium cursor-pointer">四模式</span></LinkTo></li>
+            <li><LinkTo kind="Design System/Components/NumberInput/展示" name="尺寸與 Button 對齊"><span className="text-primary hover:underline font-medium cursor-pointer">尺寸與 Button 對齊</span></LinkTo></li>
+            <li><LinkTo kind="Design System/Components/NumberInput/展示" name="格式化選項"><span className="text-primary hover:underline font-medium cursor-pointer">格式化選項</span></LinkTo></li>
+            <li><LinkTo kind="Design System/Components/NumberInput/展示" name="DataTable 整合"><span className="text-primary hover:underline font-medium cursor-pointer">DataTable 整合</span></LinkTo></li>
+          </ul>
+          <p className="text-fg-muted mt-3">判斷不確定時:對照 spec.md「何時用 / 何時不用」段;若仍不符,改用近親元件(見下方 vs 近親 段)。</p>
+        </div>
+      </Section>
+
+      <Section title="何時不用 + 替代方案">
+        <Rule
+          title="❌ 不用 NumberInput 做 DataTable 列表展示"
+          note="Table cell 用 `mode='display'` 渲染,不用 edit 模式輸入元件。DataTable 的 currency 欄位自動消費 `<NumberInput mode='display'>`"
+        >
+          <Label warn>Table cell 顯示值 → `mode='display'` 渲染,不用 edit Input</Label>
+        </Rule>
+      </Section>
+
+      <Section title="vs 近親元件">
+        <Rule
+          title="❌ 不用 NumberInput 做電話號碼或郵遞區號 → Input"
+          note="電話不是算術數字。改用 Input + type='tel'。Stripe 的電話欄用 Input,不用 NumberInput(不該加千分位或用 step)"
+        >
+          <NumberInput mode="readonly" value={912345678} />
+          <Label warn>↑ 電話 0912-345-678 被當數值,顯示時加上千分位 912,345,678 → 數字意義錯誤(前導零也被吃掉)</Label>
+          <Input defaultValue="0912-345-678" />
+          <Label>↑ 電話用 Input(可自訂 type=tel 或 pattern),保留 dash / 前導零</Label>
+        </Rule>
+
+        <Rule
+          title="❌ 不用 NumberInput 做音量 / 亮度滑動調整 → Slider"
+          note="視覺調整用 Slider。NumberInput 是「輸入精確值」的 form field。Material 音量控制用 Slider"
+        >
+          <Label warn>音量 / 亮度 → Slider,使用者目標是「感受」而非「輸入精確值」</Label>
+        </Rule>
+
+        <Rule
+          title="✅ 數值資料一律 NumberInput,不用 Input type=number"
+          note="NumberInput 提供:千分位格式化、locale 切換、prefix/suffix、precision、edit 左 / table 右 對齊、DataTable 自動整合。原生 input type=number 這些都沒有"
+        >
+          <NumberInput mode="readonly" value={1234567} prefix="$" />
+          <NumberInput mode="readonly" value={85.5} suffix="%" precision={1} />
+          <NumberInput mode="readonly" value={12500} />
+        </Rule>
+      </Section>
+    </div>
+  ),
+}
+
+export const AlignmentRule: Story = {
+  name: '對齊原則',
+  render: () => {
+    const [value, setValue] = React.useState<number | null>(2490)
+    interface Row { product: string; price: number; stock: number }
+    const data: Row[] = [
+      { product: 'Headphones', price: 2490, stock: 12 },
+      { product: 'Chair', price: 890, stock: 3 },
+      { product: 'Green Tea', price: 35, stock: 120 },
+      { product: 'USB Hub', price: 1290, stock: 0 },
+    ]
+    const col = createColumnHelper<Row>()
+    const columns = [
+      col.accessor('product', { header: 'Product', meta: { type: 'string', width: 160 } }),
+      col.accessor('price', { header: 'Price', meta: { type: 'currency', prefix: '$', width: 120 } }),
+      col.accessor('stock', { header: 'Stock', meta: { type: 'number', width: 100 } }),
+    ]
+    return (
+      <div>
+        <Rule
+          title="Edit 模式 — 靠左(input 打字由左往右)"
+          note="使用者打字是由左到右的連續動作,數字從左邊出現最自然。Edit 模式不需要比較位數"
+        >
+          <NumberInput value={value} onChange={setValue} prefix="$" />
+        </Rule>
+
+        <Rule
+          title="Table cell — 靠右(縱向比較位數)"
+          note="表格中同欄的數字需要對齊小數點/個位數,右對齊讓使用者一眼比較大小。由 DataTable 的 column meta type=number / currency 自動套用,不需要手動設對齊"
+        >
+          <div className="w-full max-w-lg">
+            <DataTable columns={columns} data={data} height="auto" />
+          </div>
+          <Label>↑ price 和 stock 欄自動右對齊,小數點縱向對齊</Label>
+        </Rule>
+
+        <Rule
+          title="❌ 不要手動改動對齊方向"
+          note="edit 左、table 右是跨產業的共識(Excel、會計軟體、財務系統都是)。手動反向會讓使用者的掃視習慣被打破"
+        >
+          <NumberInput value={value} onChange={setValue} prefix="$" className="text-right" />
+          <Label warn>↑ Edit input 強制右對齊 → 打字時游標位置感變怪</Label>
+        </Rule>
+      </div>
+    )
+  },
+}
+
+export const FormatOptionsRule: Story = {
+  name: '格式化選項使用',
+  render: () => (
+    <div>
+      <Rule
+        title="prefix — 置於數字前的符號(貨幣是最常見場景)"
+        note="prefix 會同時出現在 edit、readonly、DataTable cell。使用者不需要自己輸入 $——打字就是純數字"
+      >
+        <NumberInput mode="readonly" value={2490} prefix="$" />
+        <NumberInput mode="readonly" value={12500} prefix="NT$" precision={0} />
+      </Rule>
+
+      <Rule
+        title="suffix — 置於數字後的單位(百分比、度量)"
+        note="suffix 標示「這個數字代表什麼」。%、°C、kg、ms 都是適合 suffix 的單位"
+      >
+        <NumberInput mode="readonly" value={85.5} suffix="%" precision={1} />
+        <NumberInput mode="readonly" value={36.5} suffix="°C" precision={1} />
+      </Rule>
+
+      <Rule
+        title="precision — 固定小數位數"
+        note="需要一致位數時才設——金融、科學、測量。整數欄位不需要 precision(預設就是不補零)"
+      >
+        <NumberInput mode="readonly" value={85} suffix="%" precision={2} />
+        <Label>↑ 85 → 85.00%(科學報告、金融報表場景)</Label>
+      </Rule>
+
+      <Rule
+        title="❌ 不要手動拼接格式化字串"
+        note="手動用 toLocaleString() 或字串模板格式化會導致 edit / readonly / table cell 不一致——三個地方都要各自寫一遍格式化邏輯,且 locale 切換時全部要改"
+      >
+        <Input defaultValue="$2,490.00" />
+        <Label warn>↑ 用 Input + 手動格式化字串 → 使用者打字時要 parse「$2,490.00」→ 脆且不 locale-aware</Label>
+      </Rule>
+    </div>
+  ),
+}
+
+export const DataTypeMatchRule: Story = {
+  name: '數字一律用 NumberInput',
+  render: () => (
+    <div>
+      <Rule
+        title="所有數值資料都用 NumberInput——不用 Input type=number"
+        note="NumberInput 提供:千分位格式化、locale 切換、prefix/suffix、precision、edit 左 / table 右 對齊、DataTable 自動整合。原生 input type=number 這些都沒有"
+      >
+        <NumberInput mode="readonly" value={1234567} prefix="$" />
+        <NumberInput mode="readonly" value={85.5} suffix="%" precision={1} />
+        <NumberInput mode="readonly" value={12500} />
+      </Rule>
+
+      <Rule
+        title="❌ 不用 Input 顯示數字"
+        note="即使值看起來「就是數字字串」,缺少格式化會讓大數字不可讀(1234567 vs 1,234,567)。Edit 與 Display 分離是 Field 設計的基本前提——用 NumberInput 兩者都得到"
+      >
+        <Input defaultValue="1234567" />
+        <Label warn>↑ 1234567 難讀、無貨幣前綴、無 locale、無右對齊</Label>
+      </Rule>
+
+      <Rule
+        title="❌ 看起來像數字但不是算術型的資料:用 Input"
+        note="電話、郵遞區號、身分證字號、產品代碼都「長得像數字」但不是算術型 value——不做加減、不做千分位、不做 step。用 NumberInput 會錯誤套用千分位(0912-345-678 變成「912,345,678」)、誤導 mobile 彈出數字鍵盤且關閉符號輸入"
+      >
+        <NumberInput mode="readonly" value={912345678} />
+        <Label warn>↑ 電話 0912-345-678 被當數值,顯示時加上千分位 912,345,678 → 數字意義錯誤(前導零也被吃掉)</Label>
+        <Input defaultValue="0912-345-678" />
+        <Label>↑ 電話用 Input(可自訂 type=tel 或 pattern),保留 dash / 前導零</Label>
+      </Rule>
+    </div>
+  ),
+}

package/src/components/NumberInput/number-input.spec.md

@@ -0,0 +1,125 @@
+---
+component: NumberInput
+family: 4
+variants: {}
+sizes: {}
+traits:
+  - hasInteractiveStates
+  - isInputLike
+benchmark:
+  - Ant Design InputNumber: github.com/ant-design/ant-design/tree/master/components/input-number
+  - MUI TextField (number): github.com/mui/material-ui/tree/master/packages/mui-material/src/TextField
+---
+
+# NumberInput 設計原則
+
+## 定位
+
+NumberInput 是**數值的**輸入與顯示元件。格式化邏輯：`toLocaleString()` + prefix/suffix + precision。
+
+共用規則見 `../Field/field-controls.spec.md`。本文件只記錄 NumberInput 特有的原則。
+
+**Layout Family**：CLAUDE.md 4-Family Model **Family 4（Field control layout）** 消費者。結構繼承 `components/Field/field-controls.spec.md` 的 `fieldWrapperStyles + [startIcon?] [<editable>] [endAction?]` 規格,視覺對齊 Family 1（Menu item）讓 SelectMenu trigger + options 連續一致。
+
+---
+
+## 何時用
+
+- **所有數值資料**：金額、數量、百分比、比率、測量值、年齡、計數
+- **需要格式化的 value**：千分位（`1,234,567`）、貨幣前綴（`$2,490`）、百分比後綴（`85.5%`）、小數精度（`0.00`）
+- **需要 locale-aware 顯示**（`toLocaleString()` 自動處理千分位分隔符、小數點形式）
+- **DataTable 的數值欄位**（right-aligned + 自動格式化）
+
+## 何時不用
+
+| 場景 | 改用 | 原因 |
+|------|------|------|
+| 純文字 / 看起來像數字的字串（電話、郵遞區號）| `Input` | 電話不是算術型數字，不需要千分位 / 不該用 step |
+| 日期 / 時間戳 | `DatePicker` | 需要日期語意和 picker 互動 |
+| 視覺調整數值（音量、亮度、滑動調整）| `Slider` | 使用者目標是「感受」而非「輸入精確值」 |
+| 大量帶小數的科學計算 | `Input` + 自訂驗證 | 極端精度需求超出 NumberInput 格式化能力 |
+
+---
+
+## 格式化選項
+
+| 選項 | 說明 | 範例 |
+|------|------|------|
+| `prefix` | 前綴字串（如貨幣符號） | `$2,490` |
+| `suffix` | 後綴字串（如百分比） | `85.5%` |
+| `precision` | 小數位數 | `85.50` |
+| `locale` | 數字格式 locale | 預設 `en-US` |
+
+## 對齊
+
+- **Edit 模式（input）**：靠左——input 內打字是左到右
+- **Table cell（Display）**：靠右——縱向比較位數需要右對齊（由 DataTable 的 column type `number` / `currency` 控制）
+
+## Display
+
+`<NumberInput mode="display">` 在 table cell 和 Form readonly 共用 `formatNumber()` 格式化函式。
+
+- 有值：格式化輸出（prefix + localized number + suffix）
+- null / undefined：`—`（em dash），`text-fg-muted`
+
+## DataTable 整合
+
+```tsx
+// 自動格式化——不需要手寫 cell
+col.accessor('price', {
+  header: 'Price',
+  meta: { type: 'currency', prefix: '$' },
+})
+```
+
+`currency` 類型預設 `prefix: '$'`，其餘等同 `number`。
+
+---
+
+## Mode / Validation / a11y
+
+詳見 `../Field/field-controls.spec.md`(Mode / Validation)+ `../Field/form-validation.spec.md`(驗證時機)。
+
+---
+
+## 禁止事項
+
+- ❌ 不要拿 NumberInput 顯示電話 / 郵遞區號 / 身分證號(非算術型數字)— 用 `Input`(電話千分位無意義 / step 不適用)
+- ❌ 不要把 `precision` 設超過 6(浮點精度雜訊)— 極端精度需求超出格式化能力,改用 `Input` + 自驗證
+- ❌ 不要在 DataTable cell 用左對齊 NumberInput(縱向比較位數需右對齊)— 走 DataTable column type `number` / `currency` 預設右對齊
+- ❌ 不要把 `prefix='$'` 跟 `suffix='元'` 同時用 — 貨幣語意衝突,擇一即可
+- ❌ 不要拿 NumberInput 做百分比但 value 存 0–1(`0.85` × 100 = 85%)— DS canonical 是 value 直接存百分比數值(85),`suffix='%'` 純顯示
+- ❌ 不要自加 step ↑↓ button — NumberInput 是純值輸入(`type="text" inputMode="decimal"`),不提供 step；需要加減互動請走 `endSlot` 放自訂 stepper button group
+
+---
+
+## 邊界案例
+
+- **Disabled**:由 Field SSOT own(`Field/field-controls.spec.md` State machine 段)。視覺:wrapper bg → `bg-disabled`(neutral-2,`semantic.css` `--bg-disabled`)、formatted text → `text-fg-disabled`(M24 state>emphasis)。Display mode + disabled 維持格式化輸出但 token 切 disabled。
+- **Loading**:NumberInput 不提供 loading state(`NumberInputProps` 無 `loading` prop、無 `CircularProgress` / `aria-busy` 邏輯)。數值輸入為同步操作,無 async fetch 語意;若需 async 場景(如遠端校驗)請走外層 Field validation + `endSlot` 自訂 spinner。
+- **Empty(null / undefined / 空字串)**:Display mode 渲 `—`(em dash + `text-fg-muted`);Edit mode placeholder 走 default placeholder color。
+- **Invalid input**(non-numeric):input 為 `type="text" inputMode="decimal"`,onChange 以 `Number(raw)` parse,NaN 時忽略不觸發 `onChange`(value 維持原值);搭配 Field validation 渲 error variant(`aria-invalid="true"` + `text-fg-error` border + 下方 error message)。
+- **Dark mode / density**:走 Field SSOT,不獨立 own。
+
+---
+
+## 相關
+
+- `../Input/input.spec.md` — 純文字（含電話 / 郵遞區號等「看起來像數字」的資料）
+- `../DatePicker/date-picker.spec.md` — 日期
+- `../Slider/slider.spec.md` — 視覺調整數值（音量、亮度）
+- `../Field/field-controls.spec.md` — Field Control 共用規則（mode / size / endAction / error）
+
+## A11y 預設
+
+**ARIA / Pattern**:ARIA / keyboard 機制**僅 edit mode 適用**——edit mode 渲染 native `<input>` element(預設 a11y),且把 `...props`(含 `aria-label` / `aria-describedby` 等)轉發到該 input,Field wrapper 另補 `aria-invalid` / `aria-required` / `aria-describedby` / `aria-errormessage`。`display` / `readonly` / `disabled` 三 mode 渲染的是無互動純展示文字(`<div>` + `<span>`,不轉發 `aria-*`),螢幕報讀僅得格式化後的靜態值(對齊 Carbon read-only / Stripe display 慣例)。
+
+**Keyboard 行為**:
+
+- Tab — focus
+- 數字鍵 — 輸入數值
+
+**Focus**:native input 為 `outline-none` 無自身 focus ring;藍框由 Field wrapper 的 `focus-within:!border-primary` 提供(input 取得 focus → wrapper `focus-within` fire → border 轉 primary)。
+
+**驗證**:Storybook a11y addon panel 應 0 critical violation;鍵盤完整可操作(無需滑鼠)。WCAG AA contrast ≥ 4.5:1(text)/ 3:1(UI)。
+

package/src/components/NumberInput/number-input.stories.tsx

@@ -0,0 +1,142 @@
+// @story-trait-rationale: D3 mechanical migration (size:N → meta.width) — preexisting Default/WithError trait gap unrelated to this edit; tracked separately
+// @story-baseline: packages/design-system/src/components/DataTable/data-table.stories.tsx#WithBulkActions
+// (per .claude/references/story-baseline-registry.json#DataTable)
+import React from 'react'
+import type { Meta, StoryObj } from '@storybook/react'
+import { createColumnHelper } from '@tanstack/react-table'
+import { NumberInput } from './number-input'
+import { Button } from '@/design-system/components/Button/button'
+import { DataTable } from '@/design-system/components/DataTable/data-table'
+import '@/design-system/components/DataTable/column-types'
+
+const meta: Meta<typeof NumberInput> = {
+  title: 'Design System/Components/NumberInput/展示',
+  component: NumberInput,
+  tags: ['autodocs'],
+}
+
+export default meta
+type Story = StoryObj<typeof NumberInput>
+
+// @story-trait-rationale: pre-existing trait gaps (Default/WithError) tracked separately; this PR scope = add display mode card to Modes story only.
+/* ── 四模式 ── */
+export const Modes: Story = {
+  name: '四模式',
+  render: () => {
+    const [value, setValue] = React.useState<number | null>(2490)
+    return (
+      <div className="flex flex-col gap-6 max-w-xs">
+        <div>
+          <h3 className="text-body font-bold text-foreground mb-2">edit</h3>
+          <NumberInput value={value} onChange={setValue} prefix="$" aria-label="價格(edit mode demo)" />
+        </div>
+        <div>
+          <h3 className="text-body font-bold text-foreground mb-2">display</h3>
+          <NumberInput mode="display" value={value} prefix="$" aria-label="價格(display mode demo)" />
+        </div>
+        <div>
+          <h3 className="text-body font-bold text-foreground mb-2">readonly</h3>
+          <NumberInput mode="readonly" value={value} prefix="$" aria-label="價格(readonly mode demo)" />
+        </div>
+        <div>
+          <h3 className="text-body font-bold text-foreground mb-2">disabled</h3>
+          <NumberInput mode="disabled" value={value} prefix="$" aria-label="價格(disabled mode demo)" />
+        </div>
+      </div>
+    )
+  },
+}
+
+/* ── 尺寸與 Button 對齊 ── */
+export const SizeAlignment: Story = {
+  name: '尺寸與 Button 對齊',
+  render: () => {
+    const [sm, setSm] = React.useState<number | null>(2490)
+    const [md, setMd] = React.useState<number | null>(2490)
+    const [lg, setLg] = React.useState<number | null>(2490)
+    const states: Record<string, [number | null, (v: number | null) => void]> = { sm: [sm, setSm], md: [md, setMd], lg: [lg, setLg] }
+    return (
+      <div className="flex flex-col gap-4">
+        {(['sm', 'md', 'lg'] as const).map(size => (
+          <div key={size} className="flex items-center gap-3">
+            <NumberInput size={size} value={states[size][0]} onChange={states[size][1]} prefix="$" className="max-w-xs" />
+            <Button variant="primary" size={size}>送出</Button>
+            <span className="text-caption text-fg-muted">size="{size}"</span>
+          </div>
+        ))}
+      </div>
+    )
+  },
+}
+
+/* ── 格式化選項 ── */
+export const FormatOptions: Story = {
+  name: '格式化選項',
+  render: () => (
+    <div className="flex flex-col gap-4 max-w-xs">
+      <div>
+        <p className="text-caption text-fg-muted mb-1">prefix="$"</p>
+        <NumberInput mode="readonly" value={2490} prefix="$" />
+      </div>
+      <div>
+        <p className="text-caption text-fg-muted mb-1">suffix="%" precision={1}</p>
+        <NumberInput mode="readonly" value={85.5} suffix="%" precision={1} />
+      </div>
+      <div>
+        <p className="text-caption text-fg-muted mb-1">prefix="NT$" precision={0}</p>
+        <NumberInput mode="readonly" value={12500} prefix="NT$" precision={0} />
+      </div>
+      <div>
+        <p className="text-caption text-fg-muted mb-1">null value</p>
+        <NumberInput mode="readonly" value={null} prefix="$" />
+      </div>
+    </div>
+  ),
+}
+
+/* ── Display in DataTable ── */
+export const InDataTable: Story = {
+  name: 'DataTable 整合',
+  render: () => {
+    interface Product {
+      name: string
+      price: number
+      stock: number
+      discount: number
+    }
+
+    const data: Product[] = [
+      { name: 'Wireless Headphones', price: 2490, stock: 142, discount: 15 },
+      { name: 'Office Chair', price: 8900, stock: 38, discount: 0 },
+      { name: 'Green Tea 100 Bags', price: 350, stock: 520, discount: 10.5 },
+      { name: 'USB-C Hub', price: 1290, stock: 0, discount: 20 },
+    ]
+
+    const col = createColumnHelper<Product>()
+
+    const columns = [
+      col.accessor('name', { header: 'Product', meta: { type: 'string', width: 200 } }),
+      col.accessor('price', {
+        header: 'Price',
+        meta: { type: 'currency', prefix: '$', width: 120 },
+      }),
+      col.accessor('stock', {
+        header: 'Stock',
+        meta: { type: 'number', width: 100 },
+      }),
+      col.accessor('discount', {
+        header: 'Discount',
+        meta: { type: 'number', suffix: '%', width: 100 },
+      }),
+    ]
+
+    return (
+      <div>
+        <p className="text-caption text-fg-muted mb-3">
+          不需要手寫 cell renderer——meta.type + 格式化參數自動套用 Display 元件
+        </p>
+        <DataTable columns={columns} data={data} height="auto" />
+      </div>
+    )
+  },
+}

package/src/components/NumberInput/number-input.tsx

@@ -117,7 +117,8 @@ const NumberInput = React.forwardRef<HTMLInputElement, NumberInputProps>(
             className={cn(
               'flex-1 min-w-0',
               resolvedMode === 'disabled' && 'text-fg-disabled cursor-not-allowed',
-              value == null && 'text-fg-muted',
+              // 2026-05-31 M24:disabled > muted。disabled 時不可再套 muted(否則 neutral-7 蓋過 disabled neutral-6)
+              value == null && resolvedMode !== 'disabled' && 'text-fg-muted',
             )}
           >
             {value == null ? EMPTY_DISPLAY : formatNumber(value, { precision, prefix, suffix, locale })}

package/src/components/OverflowIndicator/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 './overflow-indicator'