@qijenchen/design-system 0.1.0-beta.83 → 0.1.0-beta.85

package/src/components/Calendar/calendar.anatomy.stories.tsx

@@ -18,8 +18,11 @@ export default meta
 
 type Story = StoryObj<typeof Calendar>
 
-// 釘固定日期(2026-07-07 修 VR flake):真實 new Date() 讓 today 標記隨換日移格 → ubuntu
-// baseline 每隔幾天假 breach(0.07–0.5%)。釘死 = deterministic 渲染;月中讓事件分布自然。
+// 釘固定日期(2026-07-07 修 VR flake;2026-07-13 補傳 defaultReferenceDate 使 pin 真正生效):
+// 只把 now 用來組事件日期字串「不會」pin 顯示月 —— Calendar 顯示月預設取即時 new Date()(tsx),
+// 故必須把 now 傳給 defaultReferenceDate 才真正釘住顯示月(下方各 instance 已補),否則當前月非
+// 7 月時 7 月事件根本不顯示。註:today 標記仍取真實日期(tsx 內 new Date(),無 today override prop)
+// → 落在被釘的 7 月內時仍隨換日移格,屬已知殘留(需新增 today prop 才能完全釘死,SSOT 待拍板)。
 const now = new Date(2026, 6, 15)
 const thisMonth = now.getFullYear() + '-' + String(now.getMonth() + 1).padStart(2, '0')
 
@@ -36,7 +39,7 @@ export const Overview: Story = {
   name: '元件總覽',
   render: () => (
     <div className="h-screen p-4 bg-canvas">
-      <Calendar events={sampleEvents} />
+      <Calendar events={sampleEvents} defaultReferenceDate={now} />
     </div>
   ),
 }
@@ -63,13 +66,13 @@ export const Inspector: Story = {
   },
   render: (args) => (
     <div className="h-screen p-4 bg-canvas">
-      <Calendar {...args} />
+      <Calendar defaultReferenceDate={now} {...args} />
     </div>
   ),
 }
 
 // ── 3. 色彩對照表(事件 color 類別 + Cell / Event tile token)─────────────────────
-// 跳過 4. SizeMatrix(rationale 見 calendar.spec.md「MVP vs 後續增量」,MVP 只 md;lg 為 tech debt)
+// 跳過 4. SizeMatrix(rationale 見 calendar.spec.md「MVP vs 後續增量」,roadmap:lg 尚未實作、視覺同 md)
 export const ColorMatrix: Story = {
   name: '色彩對照表',
   render: () => {
@@ -85,13 +88,12 @@ export const ColorMatrix: Story = {
         <div>
           <H3>事件類別色</H3>
           <Desc>
-            event color = 12 categorical 色相,**消費 categorical-color SSOT**,與 Tag / Avatar 共用同一組
+            事件顏色用 12 種類別色,和 Tag / Avatar 共用同一套色盤
             (blue / green / deep-orange / yellow / red / orange / amber / lime / turquoise / indigo / purple / magenta)。
-            color 是**類別語意**(同 team / 同 project),非 severity。色名 1:1 對該色相的 `--color-*` primitive(零 offset);
-            2026-06-04 修正前 red 與 orange 都誤接 deep-orange,現各自獨立可區分。
+            顏色代表「這是哪一類事件」(同一個團隊 / 同一個專案),不是嚴重程度。每個色名對應一個色相,紅與橘各自獨立、可清楚區分。
           </Desc>
           <div className="h-[560px]">
-            <Calendar events={colorEvents} />
+            <Calendar events={colorEvents} defaultReferenceDate={now} />
           </div>
         </div>
 
@@ -202,7 +204,7 @@ export const StateBehavior: Story = {
         <div>• <b>event hover</b>:tile 切同色深一階 `hover:bg-{`{color}`}-2`(如 blue → `--color-blue-2`)+ `cursor-pointer`</div>
         <div>• <b>empty cell</b>:無事件保持純底色,點擊觸發 onDateClick</div>
       </div>
-      <Calendar events={sampleEvents} />
+      <Calendar events={sampleEvents} defaultReferenceDate={now} />
     </div>
   ),
 }

package/src/components/Calendar/calendar.principles.stories.tsx

@@ -1,6 +1,6 @@
 // @principles-rationale: Merged WhenToUse + WhenNotToUse + VsDatePicker into a single
 // `UsageGuidance` story (3 sections) per 2026-04-26 user mandate to consolidate
-// decision-related stories. ColorSemantic + MvpScope kept as separate principles.
+// decision-related stories. ColorSemantic + MonthViewOnlyRule kept as separate principles.
 import type { Meta, StoryObj } from '@storybook/react'
 import LinkTo from '@storybook/addon-links/react'
 import { Calendar, type CalendarEvent } from './calendar'
@@ -14,8 +14,11 @@ const meta: Meta = {
 export default meta
 type Story = StoryObj
 
-// 釘固定日期(2026-07-07 修 VR flake):真實 new Date() 讓 today 標記隨換日移格 → ubuntu
-// baseline 每隔幾天假 breach(0.07–0.5%)。釘死 = deterministic 渲染;月中讓事件分布自然。
+// 釘固定日期(2026-07-07 修 VR flake;2026-07-13 補傳 defaultReferenceDate 使 pin 真正生效):
+// 只把 now 用來組事件日期字串「不會」pin 顯示月 —— Calendar 顯示月預設取即時 new Date()(tsx),
+// 故必須把 now 傳給 defaultReferenceDate 才真正釘住顯示月(下方各 instance 已補),否則當前月非
+// 7 月時 7 月事件根本不顯示。註:today 標記仍取真實日期(tsx 內 new Date(),無 today override prop)
+// → 落在被釘的 7 月內時仍隨換日移格,屬已知殘留(需新增 today prop 才能完全釘死,SSOT 待拍板)。
 const now = new Date(2026, 6, 15)
 const thisMonth = now.getFullYear() + '-' + String(now.getMonth() + 1).padStart(2, '0')
 
@@ -85,6 +88,7 @@ export const UsageGuidance: Story = {
               <div className="text-body font-medium mb-2">Calendar(event canvas)</div>
               <div className="h-80 border border-divider rounded-md overflow-hidden">
                 <Calendar
+                  defaultReferenceDate={now}
                   events={[
                     { id: 'a', title: 'Design review', start: `${thisMonth}-05`, end: `${thisMonth}-05`, color: 'blue' },
                   ] as CalendarEvent[]}
@@ -109,6 +113,7 @@ export const ColorSemantic: Story = {
       >
         <div className="h-80 border border-divider rounded-md overflow-hidden">
           <Calendar
+            defaultReferenceDate={now}
             events={[
               { id: '1', title: 'Design review', start: `${thisMonth}-05`, end: `${thisMonth}-05`, color: 'blue' },
               { id: '2', title: 'Sprint planning', start: `${thisMonth}-08`, end: `${thisMonth}-08`, color: 'blue' },
@@ -123,9 +128,11 @@ export const ColorSemantic: Story = {
   ),
 }
 
-// ── 原則 — MVP scope:月 view only ─────────────────────────────────────────
-export const MvpScope: Story = {
-  name: 'MVP 範圍',
+// ── 原則 — 支援範圍:月 view only(2026-07-14 rename MvpScope → MonthViewOnlyRule
+//    per audit Dim 14 + category-templates.md「Canonical naming」:「MVP」為開發 roadmap
+//    內部用語,reader-facing name 必人話;component-specific {Topic}Rule idiom 保留)──────
+export const MonthViewOnlyRule: Story = {
+  name: '僅支援月檢視',
   render: () => (
     <div className="space-y-6">
       <Rule
@@ -134,6 +141,7 @@ export const MvpScope: Story = {
       >
         <div className="h-80 border border-divider rounded-md overflow-hidden">
           <Calendar
+            defaultReferenceDate={now}
             events={[
               { id: '1', title: 'Sprint planning', start: `${thisMonth}-08`, end: `${thisMonth}-08`, color: 'blue' },
             ] as CalendarEvent[]}

package/src/components/Calendar/calendar.spec.md

@@ -80,7 +80,7 @@ Calendar 是**事件檢視 canvas**,讓 user 以**月 / 週 / 日** 三種 view
 
 ```tsx
 <Calendar
-  view="month" | "week" | "day"           // MVP 只支援 "month"
+  view="month" | "week" | "day"           // roadmap:week / day 尚未實作,目前只渲染月檢視(誠實 API,傳入不報錯,見「狀態 > 邊界案例」)
   defaultView="month"
   referenceDate={Date}                      // 當前聚焦日期(月檢視的那個月)
   onViewChange={(view) => ...}
@@ -91,7 +91,7 @@ Calendar 是**事件檢視 canvas**,讓 user 以**月 / 週 / 日** 三種 view
   onCreateEvent={() => ...}                 // 點「新事件」CTA 回調
   weekStartsOn={0 | 1}                      // 0=Sun, 1=Mon
   renderEventTile={(event) => ReactNode}    // 自訂 event tile 視覺
-  size="md" | "lg"                          // cell 大小(MVP 只 md;lg 為 tech debt)
+  size="md" | "lg"                          // cell 大小(roadmap:lg 尚未實作,視覺同 md——僅設 data-size,無 CSS 消費)
   locale="en-US"                            // Intl 語系(月份標題 / 星期名;預設 'en-US')
   prevAriaLabel="上個月"                    // i18n override:prev 導覽鈕 aria-label
   nextAriaLabel="下個月"                    // i18n override:next 導覽鈕 aria-label
@@ -208,7 +208,7 @@ MVP 無內建 error 狀態(無 `error` / `onRetry` prop)——載入失敗由 co
 - ❌ 不硬寫 month grid 為 `<table>`——用 CSS grid(月 view 為 per-cell 模型不跨欄 span,見「Event tile 規則」;後續週 / 日 view 的 timeline / 拖拉增量需 grid 自由佈局,table 結構難擴充)
 - ❌ 不把 event 資料存在元件內部 state——event 是 consumer 責任,本元件是純 view
 - ❌ 不自動打開「新事件」表單——`onDateClick` / `onCreateEvent` 回調給 consumer 決定(避免強制開 Dialog UX)
-- ❌ 不重造 date math——用 `date-fns`
+- ❌ 不重造 date math——月 / 週 grid 邊界運算(`startOfMonth` / `eachDayOfInterval` / `isSameMonth` 等)一律用 `date-fns`。**唯一例外(D3 perf,tsx `eventsByDate` memo 有註解)**:每 render 對 42 cells 分桶事件的 hot path 用原生 timestamp 迭代(`new Date(y, m, d).getTime()` + `setDate(+1)`)—— 避免 per-cell `isWithinInterval` 的 O(42×N) 重複掃描;此 raw-Date 迭代**限縮在** bucketing memo 內,不外溢為通則
 
 ---
 
@@ -222,9 +222,10 @@ MVP 無內建 error 狀態(無 `error` / `onRetry` prop)——載入失敗由 co
 - Outside days visual
 - Empty 為常態空白(無內建 empty/loading/error UI)
 
-### 後續(tech debt)
+### 後續 roadmap(尚未實作;2026-07-14 user 拍板 props 保留——`view="week"/"day"` + `size="lg"` 傳入不報錯,目前只渲染月檢視,誠實 API 明標於 tsx JSDoc)
 - 週 view(timeline 24 小時縱軸)
 - 日 view(single-day timeline)
+- `size="lg"` cell 密度(prop 已保留,目前視覺同 md)
 - 拖拉新增 event(from 月 cell → range select)
 - 拖拉移動 event(cross-day drag)
 - 「+N more」展開 popover

package/src/components/Calendar/calendar.stories.tsx

@@ -21,8 +21,10 @@ type Story = StoryObj<typeof Calendar>
 
 // ── 真實業務情境 ─────────────────────────────────────────────────────
 
-// 釘固定日期(2026-07-07 修 VR flake):真實 new Date() 讓 today 標記隨換日移格 → ubuntu
-// baseline 每隔幾天假 breach(0.07–0.5%)。釘死 = deterministic 渲染;月中讓事件分布自然。
+// 釘固定日期(2026-07-07 修 VR flake;2026-07-13 補傳 defaultReferenceDate 使 pin 真正生效):
+// 只把 now 用來組事件日期字串「不會」pin 顯示月 —— Calendar 顯示月預設取即時 new Date()(tsx),
+// 故必須把 now 傳給 defaultReferenceDate 才真正釘住顯示月(下方各 instance 已補)。
+// 註:today 標記仍取真實日期(tsx 內 new Date(),無 today override prop)→ 落在被釘 7 月內時仍隨換日移格,屬已知殘留。
 const now = new Date(2026, 6, 15)
 const thisMonth = now.getFullYear() + '-' + String(now.getMonth() + 1).padStart(2, '0')
 
@@ -46,6 +48,7 @@ export const TeamCalendar: Story = {
     return (
       <div className="h-screen p-4 bg-canvas">
         <Calendar
+          defaultReferenceDate={now}
           events={events}
           onEventClick={(e) => alert(`點了事件:${e.title}`)}
           onDateClick={(d) => console.log('點 date cell:', d)}
@@ -71,7 +74,7 @@ export const ContentPublishingSchedule: Story = {
     ]
     return (
       <div className="h-screen p-4 bg-canvas">
-        <Calendar events={events} onCreateEvent={() => alert('排內容')} />
+        <Calendar events={events} defaultReferenceDate={now} onCreateEvent={() => alert('排內容')} />
       </div>
     )
   },
@@ -84,7 +87,7 @@ export const EmptyCalendar: Story = {
   name: '空行事曆',
   render: () => (
     <div className="h-screen p-4 bg-canvas">
-      <Calendar events={[]} onCreateEvent={() => alert('加第一個事件')} />
+      <Calendar events={[]} defaultReferenceDate={now} onCreateEvent={() => alert('加第一個事件')} />
     </div>
   ),
 }

package/src/components/Calendar/calendar.tsx

@@ -27,10 +27,11 @@ import { SegmentedControl, SegmentedControlItem } from '@/design-system/componen
  * ── Layout Family ──
  * 非 4-Family,屬 page-composite(多區塊 Toolbar + Grid + EventTile)。
  *
- * ── MVP scope(本次 session)──
+ * ── MVP scope ──
  * - 月 view 完整(toolbar / grid / event tile / today highlight / outside days)
- * - 週 / 日 view 是 tech debt
- * - 拖拉增刪 event 是 tech debt
+ * - 週 / 日 view + size lg = **roadmap:尚未實作,目前只渲染月檢視**(誠實 API,
+ *   props 保留給未來增量,2026-07-14 user 拍板;行為明細見 spec「狀態 > 邊界案例」)
+ * - 拖拉增刪 event 是 roadmap(見 spec「MVP vs 後續增量」)
  *
  * ── 與 DatePicker 的區分 ──
  * DatePicker 是「選日期」form control;Calendar 是「看事件」page canvas。
@@ -58,7 +59,11 @@ export interface CalendarEvent {
 export type CalendarView = 'month' | 'week' | 'day'
 
 export interface CalendarProps extends Omit<React.HTMLAttributes<HTMLDivElement>, 'onSelect'> {
-  /** 當前 view(MVP 只 'month',其餘 view tech debt) */
+  /**
+   * 當前 view。**roadmap:`'week'` / `'day'` 尚未實作,目前只渲染月檢視**——
+   * 傳入不報錯:grid 仍為月檢視,僅 `data-view` 同步 + SegmentedControl 週/日項 disabled
+   * (誠實 API;見 calendar.spec.md「狀態 > 邊界案例」+「MVP vs 後續增量」)。
+   */
   view?: CalendarView
   defaultView?: CalendarView
   onViewChange?: (view: CalendarView) => void
@@ -84,7 +89,10 @@ export interface CalendarProps extends Omit<React.HTMLAttributes<HTMLDivElement>
   /** 自訂 event tile 渲染 */
   renderEventTile?: (event: CalendarEvent) => React.ReactNode
 
-  /** size(MVP 只 md;lg 為 tech debt) */
+  /**
+   * size。**roadmap:`'lg'` 尚未實作,視覺與 `'md'` 相同**——傳入不報錯,
+   * 僅設 `data-size` attribute,無任何 CSS 消費(誠實 API;prop 保留給未來 cell 密度增量)。
+   */
   size?: 'md' | 'lg'
   className?: string
 
@@ -113,7 +121,18 @@ const EVENT_ALLDAY_ACCENT = CAT_ACCENT
 // ── Helpers ────────────────────────────────────────────────────────────────
 
 function coerceDate(value: string | Date): Date {
-  return value instanceof Date ? value : new Date(value)
+  if (value instanceof Date) return value
+  // date-only ISO("YYYY-MM-DD")用本地午夜建構,不走 new Date(str)。
+  // 原因:`new Date('2026-06-15')` 按 UTC 午夜解析,而 eventsByDate 分桶以本地
+  // getFullYear/Month/Date 讀取 → 負 UTC 時區(西半球)的 all-day 事件被移到前一天
+  // (真實 timezone bug)。手動 split 建本地 Date,與分桶的本地讀取一致。
+  // 含時間的字串(YYYY-MM-DDTHH:mm,無 offset)ES 規範本就以本地解析,走原生 new Date()。
+  const dateOnly = /^\d{4}-\d{2}-\d{2}$/.exec(value)
+  if (dateOnly) {
+    const [y, m, d] = value.split('-').map(Number)
+    return new Date(y, m - 1, d)
+  }
+  return new Date(value)
 }
 
 // eventsOnDate(per-cell 全 events 掃描)已由 eventsByDate bucketing memo 取代並移除
@@ -160,7 +179,7 @@ const Calendar = React.forwardRef<HTMLDivElement, CalendarProps>(function Calend
     [referenceDateProp, onReferenceDateChange],
   )
 
-  // View state(MVP 只用 month,其他 tech debt)
+  // View state(roadmap:week/day 尚未實作,受控值照收但 grid 恆為月檢視)
   const [internalView, setInternalView] = React.useState<CalendarView>(defaultView)
   const currentView = viewProp ?? internalView
   const setView = React.useCallback(

package/src/components/Carousel/carousel.anatomy.stories.tsx

@@ -18,9 +18,10 @@ export default meta
 type Story = StoryObj
 
 // ── Sample slides ────────────────────────────────────────────────────────────
-// 2026-05-16 audit Round 6:三層(展示 / 設計規格 / 設計原則)一致用真實 picsum seeded photo
+// 2026-05-16 audit Round 6:展示 + 設計規格 兩層用真實 picsum seeded photo
 // 取代 gradient 色塊 — gradient 抽象 block 教不到真實裁切 / 內容裁切 / 視覺層次,
-// 且要與主展示頁(carousel.stories.tsx)同源,讓設計師看到的 slide 內容跨三層一致。
+// 且與主展示頁(carousel.stories.tsx)同源。設計原則(principles)層刻意用輕量 gradient
+// placeholder(聚焦「何時用 / 何時不用」決策規則,不搶真實照片視覺),故 media 來源與此二層不同。
 // Picsum.photos 提供 stable seeded photos(免登入 / 免 API key / 跨環境一致)。
 // 註:ColorMatrix「視覺樣本」cell 刻意保留純色 swatch(bg-foreground)——那是 token 色票
 // 非 slide 內容,用純色才能精準標 dot 的 bg-on-emphasis/60 · /80 · 全(--on-emphasis = white)token。
@@ -185,7 +186,7 @@ const InspectorInner = () => {
             </div>
           </div>
           <p className="text-[10px] text-fg-muted font-mono">
-            Arrow:size="md"(h-field-md,default 32px / loose 36px,iconOnly 方形)· left/right-3 · top-1/2 · opacity 0 → hover/focus-within 100%<br />
+            Arrow:size="md"(h-field-md,default/md 32px / lg 36px,iconOnly 方形)· left/right-3 · top-1/2 · opacity 0 → hover/focus-within 100%<br />
             Dots:bottom-3 · gap-1.5 · inactive 6px × 6px / active 24px × 6px
           </p>
         </div>
@@ -374,7 +375,7 @@ export const SizeMatrix: Story = {
             <tbody>
               <tr>
                 <Td mono>Arrow button</Td>
-                <Td mono>size="md"(h-field-md,default 32px / loose 36px)</Td>
+                <Td mono>size="md"(h-field-md,default/md 32px / lg 36px)</Td>
                 <Td>iconOnly 方形,繼承 Button md 尺寸;rounded-full 圓形於照片 overlay 上的世界級慣例(Airbnb / Instagram / Netflix)</Td>
               </tr>
               <tr>

package/src/components/Carousel/carousel.spec.md

@@ -128,9 +128,9 @@ Tabs 和 Carousel 都能「按順序切換下方內容」,但**語意與視覺
 
 ### 視覺規格
 
-- **基於 DS Button**:`<Button variant="tertiary" size="md" iconOnly />`——完全對齊 DS 規則,不自訂視覺
+- **基於 DS Button**:`<Button variant="tertiary" size="md" iconOnly />`——對齊 DS 規則,唯 shape 覆寫 `rounded-full`(media carousel documented 例外,見下一條「形狀 documented 例外」);其餘視覺全繼承 Button tertiary,不另自訂
 - **形狀 documented 例外**:override `rounded-md` → **`rounded-full`**(圓形)。理由:media carousel 視覺取向,圓形箭頭減少方塊感、不壓迫媒體內容(對齊 **Instagram / Airbnb / Notion Gallery / Apple Photos / Google Photos lightbox 世界級慣例** — 媒體 overlay 控制器圓形)。本 DS 內 Button default 是 `rounded-md`,這裡是唯一文明 override,documented 例外記錄即為本段(同步 `carousel.tsx` Button `className="rounded-full"` 旁 inline 註解)。**不傳染**:其他元件的 Button 仍走 rounded-md <!-- @benchmark-unverified: see frontmatter benchmark list for canonical DS source URL -->
-- 尺寸:`size="md"` 對應 `--field-height-md`(default 32px / loose 36px),iconOnly 正方形;形狀 **`rounded-full`**(documented 例外,見上一條)
+- 尺寸:`size="md"` 對應 `--field-height-md`(default/md 32px / lg 36px),iconOnly 正方形;形狀 **`rounded-full`**(documented 例外,見上一條)
 - 為什麼 tertiary:`bg-surface` + `border-border`,hover 僅改 text/border 為 `primary-hover`——無 bg-hover tint,視覺最輕,不搶 media 權重;secondary 有 neutral 邊框+hover 較重,primary 有底色更搶焦點,均不合適
 - 背景 / 邊框 / hover / focus-visible:全部繼承 Button tertiary variant 的 token,不自訂
 - 圖標:`startIcon={ChevronLeft}` / `startIcon={ChevronRight}`,尺寸由 Button 內部程式化決定

package/src/components/Carousel/carousel.tsx

@@ -97,6 +97,14 @@ const Carousel = React.forwardRef<
       setSelectedIndex(a.selectedScrollSnap())
     }, [])
 
+    // reInit(動態 slide 增減 / options 變更)必刷新 scrollSnaps —— onSelect 只讀 select
+    // 狀態不含 scrollSnapList;若不在此補,dots 數量 stale(舊 dots 殘留 / 縮減不更新)。
+    const onReInit = React.useCallback((a: CarouselApi) => {
+      if (!a) return
+      setScrollSnaps(a.scrollSnapList())
+      onSelect(a)
+    }, [onSelect])
+
     const scrollPrev = React.useCallback(() => api?.scrollPrev(), [api])
     const scrollNext = React.useCallback(() => api?.scrollNext(), [api])
     const scrollTo = React.useCallback((i: number) => api?.scrollTo(i), [api])
@@ -110,13 +118,13 @@ const Carousel = React.forwardRef<
       if (!api) return
       setScrollSnaps(api.scrollSnapList())
       onSelect(api)
-      api.on('reInit', onSelect)
+      api.on('reInit', onReInit)
       api.on('select', onSelect)
       return () => {
         api?.off('select', onSelect)
-        api?.off('reInit', onSelect) // D3 fix: previously leaked — stale closure on remount
+        api?.off('reInit', onReInit) // D3 fix: previously leaked — stale closure on remount
       }
-    }, [api, onSelect])
+    }, [api, onSelect, onReInit])
 
     const handleKeyDown = (e: React.KeyboardEvent<HTMLDivElement>) => {
       // 鍵盤方向對齊內容捲動方向(APG 建議):horizontal → ←/→;vertical → ↑/↓

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

@@ -56,10 +56,13 @@ const visitorConfig = {
 
 // 訂閱方案分布(對標 Stripe dashboard)
 const subscriptionData = [
-  { tier: 'Free',    users: 820, fill: 'var(--color-free)' },
-  { tier: 'Pro',     users: 340, fill: 'var(--color-pro)' },
-  { tier: 'Team',    users: 180, fill: 'var(--color-team)' },
-  { tier: 'Enterprise', users: 42, fill: 'var(--color-enterprise)' },
+  // nameKey='tier' 的值必須等於 subscriptionConfig 的 key(小寫);顯示標籤由 config.label 提供
+  //   (shadcn pie canonical:data 的 nameKey 欄位 = 小寫 config key,如 { browser: 'chrome' })。
+  //   曾用大寫 'Free' → getPayloadConfig 以 'Free' 查 config 落空 → 圖例標籤全空(2026-07-13 修)。
+  { tier: 'free',       users: 820, fill: 'var(--color-free)' },
+  { tier: 'pro',        users: 340, fill: 'var(--color-pro)' },
+  { tier: 'team',       users: 180, fill: 'var(--color-team)' },
+  { tier: 'enterprise', users: 42,  fill: 'var(--color-enterprise)' },
 ]
 
 const subscriptionConfig = {

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

@@ -256,7 +256,7 @@ export const ChartTypeRule: Story = {
 
       <Rule
         title="Pie / Donut — 整體的組成比例"
-        note="呈現『誰佔了整體的多少 %』,只適用 3-4 類。超過就改用 Bar(類別對比時比例已暗含在柱高裡)。Google Analytics 的流量來源、App Store 的 OS 分布。"
+        note="呈現『誰佔了整體的多少 %』,最多 5 類(類別配色上限,見「最多 5 類別」)。超過先合併「其他」;仍不夠改用 Bar(類別對比時比例已暗含在柱高裡)。Google Analytics 的流量來源、App Store 的 OS 分布。"
       >
         <div className="w-full max-w-sm">
           <ChartContainer config={osShareConfig}>

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

@@ -124,10 +124,7 @@ export const BarChartRevenue: Story = {
             />
             <ChartTooltip
               content={
-                <ChartTooltipContent
-                  indicator="dashed"
-                  formatter={(value) => `$${Number(value).toLocaleString()}`}
-                />
+                <ChartTooltipContent indicator="dashed" />
               }
             />
             <Bar dataKey="revenue" fill="var(--color-revenue)" radius={4} />
@@ -159,10 +156,7 @@ export const LineChartResponseTime: Story = {
             />
             <ChartTooltip
               content={
-                <ChartTooltipContent
-                  indicator="line"
-                  formatter={(value) => `${Number(value)}ms`}
-                />
+                <ChartTooltipContent indicator="line" />
               }
             />
             <ChartLegend content={<ChartLegendContent />} />

package/src/components/Chart/chart.tsx

@@ -59,6 +59,9 @@ const ChartContainer = React.forwardRef<HTMLDivElement, ChartContainerProps>(
       <ChartContext.Provider value={ctxValue}>
         <div
           ref={ref}
+          // 2026-07-14 audit Dim 9(passthrough 完整度):id 原被 destructure 只拿去組 data-chart,
+          // native id attr 靜默吞掉 —— consumer 傳 id 期待 DOM id(anchor / aria 參照)必須落地。
+          id={id}
           data-chart={chartId}
           className={cn(
             // 整體視覺套用本 DS typography + token

package/src/components/Checkbox/checkbox.anatomy.stories.tsx

@@ -1,7 +1,7 @@
 import type { Meta } from '@storybook/react'
 import { useState } from 'react'
 import { Checkbox } from './checkbox'
-import { SelectionItem } from '@/design-system/components/SelectionControl/selection-item'
+import { CheckboxGroup } from './checkbox-group'
 
 const meta: Meta = {
   title: 'Design System/Components/Checkbox/設計規格',
@@ -159,7 +159,7 @@ export const Overview = {
       <div className="flex flex-col gap-4">
         <div className="flex flex-col gap-1">
           <H3>結構（Anatomy）</H3>
-          <Desc>Checkbox 由兩層組成：indicator（方框 + check icon）和 label（透過 SelectionItem 組合）。Checkbox 本身不內建 label。</Desc>
+          <Desc>Checkbox 由兩層組成：indicator（方框 + check icon）和 label（`label` prop 提供，內部自動透過 SelectionItem 組合）。</Desc>
         </div>
         <div className="flex gap-8">
           {/* Standalone checkbox */}
@@ -173,16 +173,16 @@ export const Overview = {
               </div>
             </div>
           </div>
-          {/* With SelectionItem */}
+          {/* With label prop */}
           <div className="flex flex-col gap-2 items-start">
-            <span className="text-[11px] text-fg-muted font-medium">搭配 SelectionItem</span>
+            <span className="text-[11px] text-fg-muted font-medium">傳 label prop</span>
             <div className="inline-flex items-center border-2 border-dashed border-primary/30 rounded-md p-3 gap-2">
-              {[{ name: 'control （Checkbox）', color: 'info' }, { name: 'control （Checkbox）', color: 'success' }].map((s) => (
+              {[{ name: 'control （Checkbox）', color: 'info' }, { name: 'label / content', color: 'success' }].map((s) => (
                 <span key={s.name} className="rounded px-2 py-1 text-[11px] font-mono border border-dashed"
                   style={{ borderColor: `var(--${s.color})`, backgroundColor: `var(--${s.color}-subtle)`, color: `var(--${s.color})` }}>{s.name}</span>
               ))}
             </div>
-            <span className="text-[10px] text-fg-muted font-mono">SelectionItem 處理 label 對齊與 padding</span>
+            <span className="text-[10px] text-fg-muted font-mono">內部 SelectionItem 處理 label 對齊與 padding</span>
           </div>
         </div>
       </div>
@@ -272,7 +272,7 @@ const InspectorInner = () => {
             <Tab active={!withLabel} onClick={() => setWithLabel(false)}>off</Tab>
             <Tab active={withLabel} onClick={() => setWithLabel(true)}>on</Tab>
           </div>
-          <span className="text-[11px] text-fg-muted">搭配 SelectionItem</span>
+          <span className="text-[11px] text-fg-muted">label prop（內部 SelectionItem 組合）</span>
         </div>
         {withLabel && (
           <div className="flex items-center gap-2">
@@ -292,20 +292,13 @@ const InspectorInner = () => {
         <div className="flex flex-col gap-5 min-w-[340px]">
           <div className="px-10 py-8 rounded-lg bg-canvas border border-divider flex items-center justify-center">
             {withLabel ? (
-              <SelectionItem
+              /* 公開 API:`<Checkbox label>` 內部自動包 SelectionItem + wire id/htmlFor(selection-item.spec.md 禁裸用) */
+              <Checkbox
                 size={size}
-                control={
-                  <Checkbox
-                    id="inspector-cb"
-                    size={size}
-                    checked={checkedState === 'checked' ? true : checkedState === 'indeterminate' ? 'indeterminate' : false}
-                    disabled={interaction === 'disabled'}
-                  />
-                }
+                checked={checkedState === 'checked' ? true : checkedState === 'indeterminate' ? 'indeterminate' : false}
+                disabled={interaction === 'disabled'}
                 label="Label text"
                 description={withDescription ? '次要說明文字,給使用者更多 context' : undefined}
-                htmlFor="inspector-cb"
-                disabled={interaction === 'disabled'}
               />
             ) : (
               <Checkbox
@@ -493,7 +486,7 @@ export const SizeMatrix = {
               <Th>Size</Th>
               <Th>Unchecked</Th>
               <Th>Checked</Th>
-              <Th>搭配 SelectionItem</Th>
+              <Th>label prop</Th>
             </tr></thead>
             <tbody>
               {SIZES.map((sz) => (
@@ -502,12 +495,8 @@ export const SizeMatrix = {
                   <Td><Checkbox size={sz} /></Td>
                   <Td><Checkbox size={sz} defaultChecked /></Td>
                   <Td>
-                    <SelectionItem
-                      size={sz}
-                      control={<Checkbox id={`sz-${sz}`} size={sz} defaultChecked />}
-                      label="Label text"
-                      htmlFor={`sz-${sz}`}
-                    />
+                    {/* 公開 API:`<Checkbox label>` 內部自動包 SelectionItem + wire id/htmlFor(selection-item.spec.md 禁裸用) */}
+                    <Checkbox size={sz} defaultChecked label="Label text" />
                   </Td>
                 </tr>
               ))}
@@ -561,16 +550,16 @@ export const StateBehavior = {
       {/* Vertical Group */}
       <div className="flex flex-col gap-3">
         <span className="text-caption font-medium text-fg-secondary">垂直排列 — Item 間距由 padding 處理，不加 gap</span>
-        <Desc>每個 SelectionItem 的 py = (field-height − 一行文字高度) / 2，單行高度剛好等於同 size 的 Input，多行時 padding 不變自然撐高。</Desc>
+        <Desc>每個 item（內部 SelectionItem）的 py = (field-height − 一行文字高度) / 2，單行高度剛好等於同 size 的 Input，多行時 padding 不變自然撐高。</Desc>
         <div className="flex gap-8">
           {(['md', 'lg'] as const).map((sz) => (
             <div key={sz} className="flex flex-col gap-1">
               <span className="text-[11px] text-fg-muted font-medium">size="{sz}"</span>
-              <div className="grid border border-dashed border-divider rounded-md p-2">
-                <SelectionItem size={sz} control={<Checkbox id={`vg-${sz}-a`} size={sz} />} label="Email 通知" htmlFor={`vg-${sz}-a`} />
-                <SelectionItem size={sz} control={<Checkbox id={`vg-${sz}-b`} size={sz} />} label="SMS 通知" description="每則訊息可能有費用" htmlFor={`vg-${sz}-b`} />
-                <SelectionItem size={sz} control={<Checkbox id={`vg-${sz}-c`} size={sz} />} label="Push 通知" htmlFor={`vg-${sz}-c`} />
-              </div>
+              <CheckboxGroup className="border border-dashed border-divider rounded-md p-2">
+                <Checkbox size={sz} label="Email 通知" />
+                <Checkbox size={sz} label="SMS 通知" description="每則訊息可能有費用" />
+                <Checkbox size={sz} label="Push 通知" />
+              </CheckboxGroup>
             </div>
           ))}
         </div>
@@ -580,9 +569,9 @@ export const StateBehavior = {
       <div className="flex flex-col gap-3">
         <span className="text-caption font-medium text-fg-secondary">水平排列 — Item 之間 gap-4（16px）</span>
         <div className="flex gap-4 border border-dashed border-divider rounded-md p-2">
-          <SelectionItem control={<Checkbox id="hg-a" />} label="Email" htmlFor="hg-a" />
-          <SelectionItem control={<Checkbox id="hg-b" />} label="SMS" htmlFor="hg-b" />
-          <SelectionItem control={<Checkbox id="hg-c" />} label="Push" htmlFor="hg-c" />
+          <Checkbox label="Email" />
+          <Checkbox label="SMS" />
+          <Checkbox label="Push" />
         </div>
       </div>
 
@@ -590,24 +579,14 @@ export const StateBehavior = {
       <div className="flex flex-col gap-3">
         <span className="text-caption font-medium text-fg-secondary">多行對齊 — 控件對齊第一行文字中心</span>
         <Desc>控件包在一行文字高度的容器內，外層 flex items-start 確保多行時控件對齊第一行。字體改變時高度自動重算。</Desc>
-        <div className="max-w-sm grid border border-dashed border-divider rounded-md">
-          <SelectionItem
-            control={<Checkbox id="ml-a" />}
-            label="短標籤"
-            htmlFor="ml-a"
-          />
-          <SelectionItem
-            control={<Checkbox id="ml-b" />}
-            label="這是一個比較長的標籤文字，會自動換行到第二行，控件始終對齊第一行的垂直中心"
-            htmlFor="ml-b"
-          />
-          <SelectionItem
-            control={<Checkbox id="ml-c" />}
+        <CheckboxGroup className="max-w-sm border border-dashed border-divider rounded-md">
+          <Checkbox label="短標籤" />
+          <Checkbox label="這是一個比較長的標籤文字，會自動換行到第二行，控件始終對齊第一行的垂直中心" />
+          <Checkbox
             label="附帶說明"
             description="說明文字用 fg-secondary 色彩，排在 label 下方"
-            htmlFor="ml-c"
           />
-        </div>
+        </CheckboxGroup>
       </div>
     </div>
   ),

package/src/components/Checkbox/checkbox.principles.stories.tsx

@@ -147,7 +147,7 @@ export const UsageGuidance: Story = {
 
         <Rule
           title="Radio — 互斥單選（必須在 RadioGroup 內）"
-          note="N 個選項中只能選一個，其他自動變 unchecked。必須有 default value（radio 的語意不允許「都沒選」）"
+          note="N 個選項中只能選一個，其他自動變 unchecked。通常可預選常用項；需要使用者主動表態（如付款方式）時可從未選開始（radio-group.spec.md：value=null 為合法初始態），配 required 驗證兜底"
         >
           <RadioGroup value={selected} onValueChange={setSelected}>
             <RadioGroupItem value="credit" label="信用卡" description="手續費 2.5%，即時" />