@qijenchen/design-system 0.1.0-beta.8 → 0.1.0-beta.80

package/src/components/Chart/chart.principles.stories.tsx

@@ -0,0 +1,436 @@
+// @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 type { Meta, StoryObj } from '@storybook/react'
+import LinkTo from '@storybook/addon-links/react'
+import {
+  Bar,
+  BarChart,
+  CartesianGrid,
+  Line,
+  LineChart,
+  Pie,
+  PieChart,
+  XAxis,
+  YAxis,
+} from 'recharts'
+import {
+  ChartContainer,
+  ChartLegend,
+  ChartLegendContent,
+  ChartTooltip,
+  ChartTooltipContent,
+  type ChartConfig,
+} from './chart'
+
+const meta: Meta = {
+  title: 'Design System/Components/Chart/設計原則',
+  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-wrap gap-6 items-start">{children}</div>
+  </div>
+)
+
+const Label = ({ children, warn }: { children: React.ReactNode; warn?: boolean }) => (
+  <p
+    className={`text-footnote leading-normal mt-2 ${warn ? 'text-error font-medium' : 'text-fg-muted'}`}
+  >
+    {children}
+  </p>
+)
+
+// ── Sample data (reused across rules) ────────────────────────────────────────
+
+// Bar = 類別對比(各國銷量)
+const countrySalesData = [
+  { country: '美國', sales: 1240 },
+  { country: '日本', sales: 892 },
+  { country: '德國', sales: 684 },
+  { country: '英國', sales: 512 },
+  { country: '法國', sales: 428 },
+]
+const countrySalesConfig = {
+  sales: { label: '銷量', color: 'var(--chart-1)' },
+} satisfies ChartConfig
+
+// Line = 趨勢(7 天活躍使用者)
+const weeklyActiveData = [
+  { day: '一', users: 3420 },
+  { day: '二', users: 3680 },
+  { day: '三', users: 3540 },
+  { day: '四', users: 3920 },
+  { day: '五', users: 4180 },
+  { day: '六', users: 4520 },
+  { day: '日', users: 4840 },
+]
+const weeklyActiveConfig = {
+  users: { label: 'DAU', color: 'var(--chart-1)' },
+} satisfies ChartConfig
+
+// Pie = 比例(OS 分布)
+const osShareData = [
+  { os: 'ios', share: 52, fill: 'var(--color-ios)' },
+  { os: 'android', share: 38, fill: 'var(--color-android)' },
+  { os: 'other', share: 10, fill: 'var(--color-other)' },
+]
+const osShareConfig = {
+  ios: { label: 'iOS', color: 'var(--chart-1)' },
+  android: { label: 'Android', color: 'var(--chart-2)' },
+  other: { label: '其他', color: 'var(--chart-3)' },
+} satisfies ChartConfig
+
+// 超過 5 類(違規示範)
+const tooManyCategoriesData = [
+  { team: 'eng', count: 42, fill: 'var(--color-eng)' },
+  { team: 'design', count: 18, fill: 'var(--color-design)' },
+  { team: 'pm', count: 12, fill: 'var(--color-pm)' },
+  { team: 'sales', count: 28, fill: 'var(--color-sales)' },
+  { team: 'marketing', count: 22, fill: 'var(--color-marketing)' },
+  { team: 'support', count: 16, fill: 'var(--color-support)' },
+  { team: 'hr', count: 8, fill: 'var(--color-hr)' },
+]
+const tooManyCategoriesConfig = {
+  eng: { label: '工程', color: 'var(--chart-1)' },
+  design: { label: '設計', color: 'var(--chart-2)' },
+  pm: { label: 'PM', color: 'var(--chart-3)' },
+  sales: { label: '業務', color: 'var(--chart-4)' },
+  marketing: { label: '行銷', color: 'var(--chart-5)' },
+  // 第 6、7 類只能 reuse 既有 --chart-* → 視覺衝突
+  support: { label: '客服', color: 'var(--chart-1)' },
+  hr: { label: 'HR', color: 'var(--chart-2)' },
+} satisfies ChartConfig
+
+// 正確:grouping「其他」
+const groupedCategoriesData = [
+  { team: 'eng', count: 42, fill: 'var(--color-eng)' },
+  { team: 'sales', count: 28, fill: 'var(--color-sales)' },
+  { team: 'marketing', count: 22, fill: 'var(--color-marketing)' },
+  { team: 'design', count: 18, fill: 'var(--color-design)' },
+  { team: 'other', count: 36, fill: 'var(--color-other)' },
+]
+const groupedCategoriesConfig = {
+  eng: { label: '工程', color: 'var(--chart-1)' },
+  sales: { label: '業務', color: 'var(--chart-2)' },
+  marketing: { label: '行銷', color: 'var(--chart-3)' },
+  design: { label: '設計', color: 'var(--chart-4)' },
+  other: { label: '其他(PM / 客服 / HR)', color: 'var(--chart-5)' },
+} satisfies ChartConfig
+
+// Stories ─────────────────────────────────────────────────────────────────────
+
+// ── WhenToUse — 何時使用 Chart ──────────────────────
+
+// ── UsageGuidance — 整合何時用 / 何時不用 / vs 近親(Polaris/Material/Ant 共識)
+// 合併自舊 WhenToUse / WhenNotToUse(2026-04-26 v3 canonical)
+
+export const UsageGuidance: Story = {
+  name: '使用指引',
+  render: () => (
+    <div className="flex flex-col gap-12">
+      {/* 何時用 — 原 WhenToUse */}
+      <div className="prose prose-sm max-w-prose">
+      <p>適合 Chart 的真實業務場景(點擊跳轉「展示」頁範例):</p>
+      <ul className="space-y-1">
+        <li>
+          <LinkTo kind="Design System/Components/Chart/展示" name="長條 Chart — 月營收"><span className="text-primary hover:text-primary-hover font-medium cursor-pointer">長條 Chart — 月營收</span></LinkTo>
+        </li>
+        <li>
+          <LinkTo kind="Design System/Components/Chart/展示" name="折線 Chart — 伺服器回應時間"><span className="text-primary hover:text-primary-hover font-medium cursor-pointer">折線 Chart — 伺服器回應時間</span></LinkTo>
+        </li>
+        <li>
+          <LinkTo kind="Design System/Components/Chart/展示" name="環圈 Chart — 流量來源分布"><span className="text-primary hover:text-primary-hover font-medium cursor-pointer">環圈 Chart — 流量來源分布</span></LinkTo>
+        </li>
+        <li>
+          <LinkTo kind="Design System/Components/Chart/展示" name="堆疊 面積 — 部門支出"><span className="text-primary hover:text-primary-hover font-medium cursor-pointer">堆疊 面積 — 部門支出</span></LinkTo>
+        </li>
+      </ul>
+      <p className="text-fg-muted mt-3">不確定該不該用 Chart 時:先確認資料是否真的需要視覺化(單一數字、2-3 個小數字或可排序篩選的清單,通常用文字、描述清單或表格更清楚);若資料量夠多且要看趨勢、比例或分布,才用 Chart。</p>
+    </div>
+
+      {/* 何時不用 / 替代元件 — 原 WhenNotToUse */}
+      <div>
+      <Rule
+        title="❌ 硬寫色值:<Bar fill='#3b82f6' />"
+        note="繞過 ChartConfig + --chart-* token 系統,dark mode 切換時不跟著反轉,brand 色改動時也無法一次更新。"
+      >
+        <Label warn>
+          ✗ &lt;Bar fill="#3b82f6" /&gt; &nbsp;&nbsp; ✓ &lt;Bar fill="var(--color-{'{key}'})" /&gt; (搭配 ChartConfig)
+        </Label>
+      </Rule>
+
+      <Rule
+        title="❌ 自訂 Tooltip / Legend 視覺"
+        note="一律用 ChartTooltipContent / ChartLegendContent,確保跨圖表視覺一致。需要微調格式化(數字千分位、單位)時用 formatter prop,不要自己寫一份 tooltip 元件。"
+      >
+        <Label warn>
+          ✗ content={'{'}(props) ={'>'} &lt;div className="bg-white shadow-xl"&gt;...&lt;/div&gt;{'}'} &nbsp;&nbsp;
+          ✓ content={'{'}&lt;ChartTooltipContent formatter={'{'}(v) ={'>'} `${'$'}{'{'}v{'}'}`{'}'} /&gt;{'}'}
+        </Label>
+      </Rule>
+
+      <Rule
+        title="❌ 在 chart 裡放 Button / Input 等互動元件"
+        note="Chart 是 passive 視覺化層,互動(篩選、時間範圍切換)屬於 chart 外的 toolbar — 用 action-bar pattern + SegmentedControl / Select / DatePicker 建構。Chart 內部只有 tooltip / legend 這類 hover 級的 passive 互動。"
+      >
+        <Label warn>
+          ✗ 在 BarChart 裡疊加 &lt;Button&gt;篩選&lt;/Button&gt; &nbsp;&nbsp;
+          ✓ Chart 上方用 action-bar pattern 放置控制項
+        </Label>
+      </Rule>
+
+      <Rule
+        title="❌ 使用 shadcn 預設的 HSL chart token"
+        note="shadcn 預設的 --chart-1..5 用的是另一套色彩演算法,本 DS 改用與其他元件一致的色彩系統(blue-6 / purple-6 / green-6 / yellow-7 / deep-orange-6)。若沿用 shadcn 預設值會與本 DS 其他色彩不同調。"
+      >
+        <Label warn>
+          本 DS 的 --chart-1..5 定義在 tokens/color/semantic.css,不要覆寫為 shadcn 範例程式碼內的 HSL 值。
+        </Label>
+      </Rule>
+    </div>
+    </div>
+  ),
+}
+
+export const ChartTypeRule: Story = {
+  name: '何時用哪種 Chart',
+  render: () => (
+    <div>
+      <Rule
+        title="Bar — 類別之間的數值對比"
+        note="橫軸是離散類別(國家 / 產品 / 部門),縱軸是數值。觀看者想知道「誰最多、誰最少、差距多大」。Stripe / Linear 的『各地區銷量』『各類型 issue 數』都是這個場景。"
+      >
+        <div className="w-full max-w-xl">
+          <ChartContainer config={countrySalesConfig}>
+            <BarChart accessibilityLayer data={countrySalesData}>
+              <CartesianGrid vertical={false} />
+              <XAxis dataKey="country" tickLine={false} axisLine={false} tickMargin={8} />
+              <YAxis tickLine={false} axisLine={false} />
+              <ChartTooltip content={<ChartTooltipContent indicator="dashed" />} />
+              <Bar dataKey="sales" fill="var(--color-sales)" radius={4} />
+            </BarChart>
+          </ChartContainer>
+          <Label>各國銷量對比 — 觀看者一眼看出「美國最高、法國最低」</Label>
+        </div>
+      </Rule>
+
+      <Rule
+        title="Line — 時間序列的趨勢變化"
+        note="橫軸是時間(日 / 週 / 月),觀看者關心「方向」(上升 / 下降 / 震盪)而非個別點的數值。Datadog 的 latency、GitHub 的 contribution graph、Stripe 的 MRR 趨勢都是 Line 場景。"
+      >
+        <div className="w-full max-w-xl">
+          <ChartContainer config={weeklyActiveConfig}>
+            <LineChart accessibilityLayer data={weeklyActiveData}>
+              <CartesianGrid vertical={false} />
+              <XAxis dataKey="day" tickLine={false} axisLine={false} tickMargin={8} />
+              <YAxis tickLine={false} axisLine={false} />
+              <ChartTooltip content={<ChartTooltipContent indicator="line" />} />
+              <Line
+                dataKey="users"
+                type="monotone"
+                stroke="var(--color-users)"
+                strokeWidth={2}
+                dot={false}
+              />
+            </LineChart>
+          </ChartContainer>
+          <Label>一週日活躍使用者 — 觀看者看到「週末上升」的趨勢</Label>
+        </div>
+      </Rule>
+
+      <Rule
+        title="Pie / Donut — 整體的組成比例"
+        note="呈現『誰佔了整體的多少 %』,只適用 3-4 類。超過就改用 Bar(類別對比時比例已暗含在柱高裡)。Google Analytics 的流量來源、App Store 的 OS 分布。"
+      >
+        <div className="w-full max-w-sm">
+          <ChartContainer config={osShareConfig}>
+            <PieChart>
+              <ChartTooltip content={<ChartTooltipContent hideLabel nameKey="os" />} />
+              <Pie
+                data={osShareData}
+                dataKey="share"
+                nameKey="os"
+                innerRadius={40}
+                strokeWidth={2}
+              />
+              <ChartLegend content={<ChartLegendContent nameKey="os" />} />
+            </PieChart>
+          </ChartContainer>
+          <Label>使用者裝置 OS 分布 — 3 類,適合 Pie</Label>
+        </div>
+      </Rule>
+
+      <Rule
+        title="❌ 錯誤:時間序列用 Pie"
+        note="Pie 無法表達「隨時間變化」;想同時看趨勢 + 組成 → Stacked Area / Stacked Bar。"
+      >
+        <Label warn>「過去 12 個月每月營收用 Pie」→ 看不到成長曲線,改用 Line 或 Bar</Label>
+      </Rule>
+    </div>
+  ),
+}
+
+export const CategoryTokenRule: Story = {
+  name: 'ChartConfig + 類別色 設計變數',
+  render: () => (
+    <div>
+      <Rule
+        title="類別色固定用 --chart-1..5,不用會隨品牌色變動的色彩變數"
+        note="ChartConfig 把每個資料系列對應到一個 --chart-* 色彩變數,ChartContainer 自動轉成 --color-{系列名},Recharts 直接用 fill='var(--color-...)'。用這組固定色(而不是會跟著品牌主色變動的色彩變數)的原因:未來品牌主色改色時,圖表的類別色彩意義不會跟著漂移 — 『Desktop 永遠是 chart-1 藍色』跟品牌色是否改成綠色無關。"
+      >
+        <div className="w-full max-w-xl">
+          <ChartContainer config={countrySalesConfig}>
+            <BarChart accessibilityLayer data={countrySalesData}>
+              <CartesianGrid vertical={false} />
+              <XAxis dataKey="country" tickLine={false} axisLine={false} tickMargin={8} />
+              <YAxis tickLine={false} axisLine={false} />
+              <ChartTooltip content={<ChartTooltipContent indicator="dashed" />} />
+              <Bar dataKey="sales" fill="var(--color-sales)" radius={4} />
+            </BarChart>
+          </ChartContainer>
+          <Label>
+            ChartConfig:{'{ sales: { label: "銷量", color: "var(--chart-1)" } }'} →
+            Recharts Bar 用 fill="var(--color-sales)"
+          </Label>
+        </div>
+      </Rule>
+    </div>
+  ),
+}
+
+export const FiveCategoryLimitRule: Story = {
+  name: '最多 5 類別',
+  render: () => (
+    <div>
+      <Rule
+        title="原則:不超過 5 類別(Miller's law 的 data viz 應用)"
+        note="人類短期記憶容量約為 5-7 項;當分類超過 5 個,觀看者需要頻繁掃 legend 對照色彩,認知負擔陡增。本 DS 只定義 --chart-1..5 五色,強制此上限。"
+      >
+        <div />
+      </Rule>
+
+      <Rule
+        title="❌ 錯誤 — 7 類別,第 6、7 類只能 reuse 顏色導致視覺衝突"
+      >
+        <div className="w-full max-w-sm">
+          <ChartContainer config={tooManyCategoriesConfig}>
+            <PieChart>
+              <ChartTooltip content={<ChartTooltipContent hideLabel nameKey="team" />} />
+              <Pie
+                data={tooManyCategoriesData}
+                dataKey="count"
+                nameKey="team"
+                innerRadius={40}
+                strokeWidth={2}
+              />
+              <ChartLegend content={<ChartLegendContent nameKey="team" />} />
+            </PieChart>
+          </ChartContainer>
+          <Label warn>「客服」與「工程」同色 / 「HR」與「設計」同色 → 無法分辨</Label>
+        </div>
+      </Rule>
+
+      <Rule
+        title="✅ 正確 — 小類別合併為「其他」,保留 Top 4 + 其他 = 5"
+        note="排名靠後的類別聚合為「其他」;若使用者需要細分,用 drill-down(點擊「其他」展開)或切換 Bar chart(縱向排列容納更多類別)。"
+      >
+        <div className="w-full max-w-sm">
+          <ChartContainer config={groupedCategoriesConfig}>
+            <PieChart>
+              <ChartTooltip content={<ChartTooltipContent hideLabel nameKey="team" />} />
+              <Pie
+                data={groupedCategoriesData}
+                dataKey="count"
+                nameKey="team"
+                innerRadius={40}
+                strokeWidth={2}
+              />
+              <ChartLegend content={<ChartLegendContent nameKey="team" />} />
+            </PieChart>
+          </ChartContainer>
+          <Label>Top 4 部門 + 其他(PM / 客服 / HR)= 5 類,每類可辨</Label>
+        </div>
+      </Rule>
+    </div>
+  ),
+}
+
+export const A11yRule: Story = {
+  name: '顏色不是區分類別的唯一手段',
+  render: () => (
+    <div>
+      <Rule
+        title="原則:顏色不是區分類別的唯一手段"
+        note="約 8% 男性有色覺缺陷(紅綠色盲最常見),黑白列印時所有 --chart-* 變成灰階更難分辨。必須配合 label(legend + 軸標籤)、圖形變化(strokeDasharray 虛線 / 不同 shape)、直接文字標註(value label on bar)等方式,讓去色後仍能辨識。"
+      >
+        <div className="w-full max-w-xl">
+          <ChartContainer config={{
+            ios: { label: 'iOS', color: 'var(--chart-1)' },
+            android: { label: 'Android', color: 'var(--chart-2)' },
+          } satisfies ChartConfig}>
+            <LineChart
+              accessibilityLayer
+              data={[
+                { month: '1 月', ios: 42, android: 38 },
+                { month: '2 月', ios: 45, android: 40 },
+                { month: '3 月', ios: 48, android: 44 },
+                { month: '4 月', ios: 52, android: 46 },
+                { month: '5 月', ios: 55, android: 50 },
+                { month: '6 月', ios: 58, android: 54 },
+              ]}
+            >
+              <CartesianGrid vertical={false} />
+              <XAxis dataKey="month" tickLine={false} axisLine={false} tickMargin={8} />
+              <YAxis tickLine={false} axisLine={false} />
+              <ChartTooltip content={<ChartTooltipContent indicator="line" />} />
+              <ChartLegend content={<ChartLegendContent />} />
+              <Line
+                dataKey="ios"
+                type="monotone"
+                stroke="var(--color-ios)"
+                strokeWidth={2}
+                dot={false}
+              />
+              <Line
+                dataKey="android"
+                type="monotone"
+                stroke="var(--color-android)"
+                strokeWidth={2}
+                strokeDasharray="4 4"
+                dot={false}
+              />
+            </LineChart>
+          </ChartContainer>
+          <Label>
+            iOS 實線、Android 虛線(strokeDasharray="4 4")— 色盲 / 黑白列印仍可分辨
+          </Label>
+        </div>
+      </Rule>
+
+      <Rule
+        title="Recharts accessibilityLayer prop"
+        note="長條、折線、面積圖加上 accessibilityLayer,啟用鍵盤焦點與讀屏器朗讀。圓餅 / 環圈圖經 Recharts 預設一樣啟用 accessibilityLayer(可聚焦),但方向鍵導覽建立在軸刻度數值索引上,無數值軸的圓餅圖無法逐片導覽。"
+      >
+        <Label>
+          &lt;BarChart accessibilityLayer ...&gt; — 方向鍵可瀏覽資料點,讀屏器讀出當前值
+        </Label>
+      </Rule>
+    </div>
+  ),
+}

package/src/components/Chart/chart.spec.md

@@ -0,0 +1,174 @@
+---
+component: Chart
+family: composite
+variants: {}
+sizes: {}
+traits:
+  - isStructural
+benchmark:
+  - Recharts: github.com/recharts/recharts
+  - MUI X Charts: github.com/mui/mui-x/tree/master/packages/x-charts
+  - Ant Design Charts: github.com/ant-design/ant-design-charts
+---
+
+# Chart 設計原則
+
+## 定位
+
+Chart 是**資料視覺化**元件——把數列(時間、類別、比例)畫成折線 / 柱狀 / 圓餅 / 雷達等圖形。不是裝飾視覺效果。
+
+**實作基礎**：shadcn chart 結構 + Recharts v3 engine。本 DS 保留 shadcn 的 API 形狀(`ChartContainer` / `ChartTooltipContent` / `ChartLegendContent` / `ChartConfig`),但把 tooltip、legend、grid、axis 的視覺全改用本 DS token。
+
+**Layout Family**：非上述 family — composite / multi-section（canvas + tooltip + legend 多區塊組合，自 own layout）。
+
+**高度決定**:`ChartContainer` **預設 `aspect-video`(16:9)**——dashboard card / analytics 面板世界級慣例(Stripe / Vercel Analytics / Datadog)。Recharts ResponsiveContainer 需 parent 有高度,不給 fallback 會坍塌。
+
+**覆寫為其他 ratio**:consumer 包 `AspectRatio` primitive,其 `padding-bottom` 高度會蓋過 ChartContainer 的 aspect-video:
+
+```tsx
+{/* 2:1 寬 stat tile */}
+<AspectRatio ratio={2}>
+  <ChartContainer config={config}>...</ChartContainer>
+</AspectRatio>
+
+{/* 3:1 hero banner chart */}
+<AspectRatio ratio={3}>
+  <ChartContainer config={config}>...</ChartContainer>
+</AspectRatio>
+```
+
+理由:不強制 consumer 寫 AspectRatio(80% 情境 16/9 剛好),但留覆寫門路給特殊 ratio 場景。與 AspectRatio primitive 保持 ownership 清晰:chart = 資料視覺化,ratio = layout primitive 職責。
+
+---
+
+## 何時用
+
+- **趨勢**：時間序列數據（月營收、使用者增長、系統錯誤率變化）→ Line / Area chart
+- **比較**：類別間數值對比（各部門預算、產品銷量、地區表現）→ Bar chart
+- **比例**：整體的組成比例（流量來源、訂閱方案分布）→ Pie / Donut chart
+- **多維**：多變量比較（產品特性雷達、員工技能圖）→ Radar chart
+- **分布**：數據分散情況（交易金額分布、回應時間）→ Histogram / Scatter
+
+## 何時不用
+
+| 場景 | 改用 | 原因 |
+|------|------|------|
+| 單一大數字 KPI（今日營收 $12,345）| `Badge` / 純文字 | 單值不需要視覺化 |
+| 2-3 個小數字對照 | `DescriptionList` / table | 數字本身就夠清晰,chart 反而多餘 |
+| 列表式資料 | `DataTable` | 可排序篩選,chart 看不細節 |
+| 即時系統狀態指示(online/offline) | `Badge` / `CircularProgress` | 狀態非數據 |
+
+## 近親元件分界
+
+| vs | 差異軸 | 何時用 Chart |
+|---|---|---|
+| **DataTable** | DataTable 是 row-level scanning + sort/filter;Chart 是 aggregate pattern recognition | 看趨勢 / 分布 / 比例,非個別 row |
+| **ProgressBar / CircularProgress** | Progress 是單值 0–100%;Chart 是 multi-series / 多時點 | 跨時間或跨類別比較 |
+| **DescriptionList** | DL 是離散 label-value;Chart 是 visual encoding(position / length / angle) | 數據量 ≥ 5 點且需 pattern |
+| **Badge / Tag** | Badge 是單值 indicator;Chart 是 data viz | 多點數據 |
+
+對齊 Polaris Charts / Material X-Charts / Ant Statistic / Recharts 共識:chart 為 multi-point visual encoding,單值用 Badge / KPI block。
+
+## 常見誤解
+
+| 誤解 | 正解 |
+|------|------|
+| 「chart 可當裝飾背景 / 氛圍圖」 | Chart 是資料視覺化,不是裝飾視覺效果(見「定位」) |
+| 「單一 KPI 數字也畫成 chart」 | 單值用 Badge / 純文字(見「何時不用」) |
+| 「要看個別 row 細節也用 chart」 | row-level scanning 用 DataTable(見「近親元件分界」) |
+| 「類別超過 5 個就加 `--chart-6`」 | 5 色是上限——改 grouping 或切換視覺化類型(見「類別配色規則」) |
+
+---
+
+## ChartConfig — 類別配色規則
+
+每個 dataKey 透過 `ChartConfig` 對應 label + color：
+
+```tsx
+const config = {
+  desktop: { label: 'Desktop', color: 'var(--chart-1)' },
+  mobile:  { label: 'Mobile',  color: 'var(--chart-2)' },
+} satisfies ChartConfig
+```
+
+`ChartContainer` 自動把每個 key 注入 scoped CSS variable `--color-{key}`,Recharts 直接消費 `fill="var(--color-desktop)"` 即可。
+
+### 類別色 token（本 DS 5 色）
+
+| Token | Light mode | Dark mode | 建議 |
+|-------|-----------|-----------|------|
+| `--chart-1` | `blue-6` | `blue-5` | 第一類別（主要） |
+| `--chart-2` | `purple-6` | `purple-5` | 第二類別 |
+| `--chart-3` | `green-6` | `green-5` | 第三類別 |
+| `--chart-4` | `yellow-7` | `yellow-5` | 第四類別（yellow-7 在 light mode 提升對 white bg 的對比） |
+| `--chart-5` | `deep-orange-6` | `deep-orange-5` | 第五類別 |
+
+**為什麼固定到 primitive 而非 semantic token**：避免未來 brand swap（primary 改色）時 chart-1 跟著漂移——data viz 的色彩意義是「類別」,不應被品牌色變動污染。
+
+**超過 5 類別時**：不應再加 `--chart-6+`,改用 grouping（「其他」分類）或切換 visualization（pie → bar / stacked）。5 色是人類短期記憶上限，超過即難區分。
+
+---
+
+## 視覺 token
+
+| 區塊 | Token |
+|------|-------|
+| Chart canvas 內文字 | `text-caption` |
+| Tooltip bg | `bg-surface-raised` |
+| Tooltip border | `border-border` |
+| Tooltip shadow | `shadow-[var(--elevation-200)]` |
+| Tooltip label（上方） | `font-medium` |
+| Tooltip 值文字 | `text-foreground`（數字以 mono + tabular-nums 等寬對齊，utility 細節見 `chart.tsx` tooltip） |
+| Tooltip 類別文字 | `text-fg-secondary` |
+| Legend 文字 | `text-fg-secondary` |
+| Cartesian grid line | `stroke-divider` |
+| Axis tick | `text-fg-muted`（填 `fill-fg-muted`） |
+| Dot fill | 依 series color |
+
+---
+
+## 邊界案例
+
+- **空資料 / 空 series**:`ChartContainer` 照常渲染(`aspect-video` 高度保留,不坍塌);無內建 empty state——「無資料」提示由 consumer 外層處理(見 `Empty` 元件)
+- **Loading(資料抓取中)**:本 wrapper 無內建 loading state——與空資料同模式,由 consumer 外層處理
+- **Tooltip / Legend 無 payload**:不渲染(return null),不留空殼
+- **ChartConfig 項目缺 `color` / `theme`**:不注入該 key 的 `--color-{key}` variable(`ChartStyle` 過濾)
+- **單一資料點 / 大資料量 / RTL**:由 Recharts engine 處理,本 wrapper 無額外行為;大資料量的取樣 / 聚合屬 consumer 職責
+
+---
+
+## 禁止事項
+
+- ❌ **不硬寫色值**：`<Bar fill="#3b82f6" />` 違規,改用 `fill="var(--color-{key})"` 搭配 ChartConfig
+- ❌ **不用 shadcn chart color token**（`--chart-1`..`--chart-5` 我們有自己的定義,shadcn 預設走 HSL 會與我們 oklch palette 漂移）
+- ❌ **不自訂 Tooltip / Legend 視覺**（一律用 `ChartTooltipContent` / `ChartLegendContent`,確保跨圖表視覺一致）
+- ❌ **不超過 5 類別**（見上節;改用 grouping 或切視覺化類型）
+- ❌ **不在 chart 裡放互動元件**（Button / Input）——chart 是 passive 視覺化層,互動走 toolbar / filter（action-bar pattern）
+
+---
+
+## 為何無 SizeMatrix / StateBehavior(Inspector 改 chart-type playground）
+
+Chart 是 **composite data-visualization** 元件,不是單一互動 primitive:
+
+- **有 Inspector(chart-type + 視覺選項 playground)**:chart 的「決定性 props」是資料(`data`)與配色(`ChartConfig`),不是單一 variant/size 切換,所以 Inspector 不是 variant 切換器,而是 chart 類型 playground——右側 Controls 即時切 `type`(bar / line / area / pie)、`showLegend`、`showGrid`、`tooltipIndicator`(dot / line / dashed),觀察同一份 `ChartConfig` 在不同圖表類型下的色彩與指示器應用,取代 SizeMatrix / StateBehavior。
+- **無 SizeMatrix**:chart 無 sm/md/lg size prop,高度由 `aspect-video`(預設)或 consumer 包 `AspectRatio` 覆寫決定(見本 spec「定位」段)。尺寸屬 container 職責,不是 chart 的變體維度。
+- **無 StateBehavior**:chart 是 passive 視覺化層,本身無 hover / focus / active / selected / disabled 互動狀態——資料點 hover 由 Recharts tooltip 處理(色彩規則已在 `ColorMatrix` 覆蓋),非 chart 元件層級的 state。
+
+對應 anatomy story:`Overview`(多種 chart 類型實例)+ `Inspector`(chart-type playground)+ `CategoryTokens`(元件特有 5 色 categorical token)+ `ColorMatrix`(tooltip/legend/grid 視覺 token)+ `Accessibility`(無障礙)。
+
+---
+
+## A11y 預設
+
+- **顏色非唯一語義**：不只靠色彩區分類別,配合 icon / label / pattern（Recharts 的 `strokeDasharray` 等）讓色盲 / 黑白列印仍可辨識
+- **Tooltip 鍵盤可存取**：Recharts v3 的 `accessibilityLayer`(本 DS 所有 chart 範例皆已啟用)內建鍵盤導覽——圖表 SVG 自動取得 `tabIndex=0` + `role="application"`,使用者用方向鍵 ←/→ 沿軸刻度逐一瀏覽資料點,讀屏器朗讀當前資料點;無需 controlled `activeIndex` 手動接線
+- **對比度**：`--chart-*` 在 light/dark 的 step 選擇已考量對 canvas bg 的對比（light=step-6 / dark=step-5）
+
+---
+
+## 相關
+
+- `../../tokens/color/color.spec.md` — `--chart-1..5` semantic token 定義
+- Recharts v3 官方文件 — `https://recharts.org`
+- shadcn chart 原始參考 — `https://ui.shadcn.com/docs/components/chart`