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

package/src/components/Button/button.tsx

@@ -193,6 +193,8 @@ const buttonVariants = cva(
           // aria-pressed fallback(Radix overlay trigger override data-state 時仍生效)
           'aria-pressed:bg-primary-subtle aria-pressed:text-primary aria-pressed:border-transparent',
           'aria-pressed:hover:text-primary-hover',
+          // 2026-07-07 補齊第三階:fallback 分支與 data-[state=on] 分支同拼寫(選中之上按壓 = active 階)
+          'aria-pressed:active:text-primary-active',
         ],
       },
       // neutral tone:灰底(neutral-selected family)— sidebar/contextual nav pressed
@@ -212,7 +214,7 @@ const buttonVariants = cva(
     ],
     defaultVariants: {
       // labeled 預設 = tertiary(2026-06-06 從 primary 改;iconOnly 預設 = text,由 resolvedVariant 注入)。
-      // 真正預設邏輯在元件 resolvedVariant(L394);此 cva default 供直接 buttonVariants() 呼叫者一致。
+      // 真正預設邏輯在元件內 resolvedVariant(相對指法,免行號漂移);此 cva default 供直接 buttonVariants() 呼叫者一致。
       variant: 'tertiary',
       size: 'md',
       pressedTone: 'emphasis',
@@ -303,7 +305,7 @@ export interface ButtonProps
    * - Clear → 欄位清空,用 Inline Action
    * - Remove → collection 移除,用一般 Button / Inline Action
    *
-   * 詳見 button.spec.md「Dismiss 視覺類」段 + patterns/element-anatomy/item-anatomy.spec.md
+   * 詳見 button.spec.md「Dismiss 視覺類」段 + patterns/element-anatomy/inline-action.spec.md
    * 「Dismiss canonical — X close only」段。
    */
   dismiss?: boolean
@@ -370,7 +372,7 @@ const Button = React.forwardRef<HTMLButtonElement, ButtonProps>(
 
     // 2026-05-23 deep-audit Phase A.4 Decision 1(user verbatim「決策ㄧ照你建議做」):dev-warn `iconOnly + (endIcon|badge)` 並用。
     // Spec SSOT:button.spec.md「iconOnly 嚴格定義為『只有一個 icon,正方形』,不可與 endIcon 或 badge 並用」。
-    // 例外:overlayBadge 跟 iconOnly 並用 canonical(L372 反向 warn 已 cover)。
+    // 例外:overlayBadge 跟 iconOnly 並用 canonical(上方 overlayBadge 反向 warn 已 cover;相對指法,免行號漂移)。
     // 不擋 image canonical「icon + 下拉指示 = 不加 iconOnly + startIcon + endIcon + aria-label」(那 case iconOnly=false 不 trigger)。
     if (process.env.NODE_ENV !== 'production' && iconOnly && (EndIcon !== undefined || badge != null)) {
       // eslint-disable-next-line no-console
@@ -426,27 +428,13 @@ const Button = React.forwardRef<HTMLButtonElement, ButtonProps>(
     const unboundedAttr =
       resolvedVariant === 'text' || dismiss ? { 'data-unbounded': 'true' } : {}
 
-    const buttonEl = (
-      <Comp
-        className={cn(
-          buttonVariants({ variant: resolvedVariant, danger: resolvedDanger, size: resolvedSize, pressedTone, className }),
-          // iconOnly 鐵律:padding-free + aspect-square + flex-center (Polaris idiom)
-          // 0 magic-number 0 公式自動正方形。詳 ICON_ONLY_BASE rationale。
-          resolvedIconOnly && ICON_ONLY_BASE,
-          // Dismiss 視覺弱化:override Button text variant 預設 foreground 為 fg-muted → hover foreground
-          // 跟 Inline Action dismiss 視覺一致(cross-implementation dimming canonical)
-          dismiss && 'text-fg-muted hover:text-foreground',
-          resolvedFullWidth && 'w-full',
-        )}
-        ref={ref}
-        type="button"
-        disabled={disabled || loading}
-        aria-busy={loading || undefined}
-        aria-label={ariaLabel}
-        {...toggleAttrs}
-        {...unboundedAttr}
-        {...restProps}
-      >
+    // Native path 內部結構:[loading spinner | startIcon(+overlayBadge)] [label] [badge + endIcon]。
+    // asChild 時**不渲染**(2026-07-04 fix):Radix Slot 規範 children 必為單一 element
+    // (React.Children.only)— 內部多 expression children 變 array 必 runtime throw;
+    // asChild 分支只 render consumer child,內容由 consumer 自帶。
+    // 詳 CLAUDE.md 失敗記憶索引「asChild ? Slot : Native 內部 JSX 仍渲染多 children」條。
+    const nativeChildren = (
+      <>
         {loading ? (
           <CircularProgress size={iconSize} className="text-current" />
         ) : StartIcon ? (
@@ -478,6 +466,55 @@ const Button = React.forwardRef<HTMLButtonElement, ButtonProps>(
             {EndIcon && <EndIcon size={iconSize} aria-hidden />}
           </span>
         )}
+      </>
+    )
+
+    const sharedClassName = cn(
+      buttonVariants({ variant: resolvedVariant, danger: resolvedDanger, size: resolvedSize, pressedTone, className }),
+      // iconOnly 鐵律:padding-free + aspect-square + flex-center (Polaris idiom)
+      // 0 magic-number 0 公式自動正方形。詳 ICON_ONLY_BASE rationale。
+      resolvedIconOnly && ICON_ONLY_BASE,
+      // Dismiss 視覺弱化:override Button text variant 預設 foreground 為 fg-muted → hover foreground
+      // 跟 Inline Action dismiss 視覺一致(cross-implementation dimming canonical)
+      dismiss && 'text-fg-muted hover:text-foreground',
+      resolvedFullWidth && 'w-full',
+    )
+
+    // 2026-07-05 D4 修:asChild 原 silently drop loading/disabled 語意(無 aria-busy/aria-disabled/
+    // click guard → <a> loading 期間可重複點擊)。補 ARIA(任何 element 合法;aria-disabled 自動點亮
+    // cva 既有視覺)+ functional guard(APG aria-disabled 模式:語意+視覺由元件、功能阻斷由 guard)。
+    const { onClick: slotConsumerOnClick, ...slotRest } = restProps as typeof restProps & { onClick?: React.MouseEventHandler<HTMLElement> }
+    const buttonEl = asChild ? (
+      // Slot 分支:children 必為單一 consumer element(React.Children.only),
+      // 內部 slot(loading/startIcon/badge)不渲染;不硬塞 type/disabled(consumer child 可能是 <a>)。
+      <Comp
+        className={sharedClassName}
+        ref={ref}
+        aria-label={ariaLabel}
+        aria-busy={loading || undefined}
+        aria-disabled={disabled || loading || undefined}
+        onClick={disabled || loading
+          ? (e: React.MouseEvent<HTMLElement>) => { e.preventDefault(); e.stopPropagation() }
+          : slotConsumerOnClick}
+        {...toggleAttrs}
+        {...unboundedAttr}
+        {...slotRest}
+      >
+        {children}
+      </Comp>
+    ) : (
+      <Comp
+        className={sharedClassName}
+        ref={ref}
+        type="button"
+        disabled={disabled || loading}
+        aria-busy={loading || undefined}
+        aria-label={ariaLabel}
+        {...toggleAttrs}
+        {...unboundedAttr}
+        {...restProps}
+      >
+        {nativeChildren}
       </Comp>
     )
 
@@ -523,10 +560,13 @@ export const buttonMeta = {
     md: { fieldHeight: 32, iconSize: 16, typography: 'body' },
     lg: { fieldHeight: 36, iconSize: 20, typography: 'body-lg' },
   },
-  states: ['default', 'hover', 'active', 'focus-visible', 'disabled'],
+  // 'pressed' = toggle on 持續態(data-[state=on],emphasis 淡藍底/neutral 灰底;2026-07-07 meta 詞彙統一補列)
+  states: ['default', 'hover', 'active', 'pressed', 'focus-visible', 'disabled'],
   tokens: {
-    bg: ['--primary', '--primary-hover', '--primary-active', '--bg-disabled'],
-    fg: ['--on-emphasis', '--fg-disabled'],
+    // 2026-07-04 audit 補齊:原只列 primary variant 家族;按 buttonVariants cva 真實 class 補
+    // secondary/tertiary/text/link/danger 消費的 token(auto-compile token 矩陣依此)
+    bg: ['--primary', '--primary-hover', '--primary-active', '--primary-subtle', '--bg-disabled', '--surface', '--neutral-hover', '--neutral-active', '--neutral-selected'],
+    fg: ['--on-emphasis', '--fg-disabled', '--foreground', '--primary', '--error', '--error-hover', '--error-active'],
     ring: ['--ring'],
   },
   defaultVariant: 'tertiary',  // 2026-06-10 修 stale:對齊 cva defaultVariants(2026-06-06 labeled 預設改 tertiary,meta 漏同步)

package/src/components/Button/index.ts

@@ -3,3 +3,4 @@
 //   import { ... } from '@qijenchen/design-system/{components,patterns}/<Dir>'
 // Regenerate: node scripts/gen-component-indexes.mjs
 export * from './button'
+export * from './button-group'

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

@@ -18,7 +18,9 @@ export default meta
 
 type Story = StoryObj<typeof Calendar>
 
-const now = new Date()
+// 釘固定日期(2026-07-07 修 VR flake):真實 new Date() 讓 today 標記隨換日移格 → ubuntu
+// baseline 每隔幾天假 breach(0.07–0.5%)。釘死 = deterministic 渲染;月中讓事件分布自然。
+const now = new Date(2026, 6, 15)
 const thisMonth = now.getFullYear() + '-' + String(now.getMonth() + 1).padStart(2, '0')
 
 const sampleEvents: CalendarEvent[] = [
@@ -95,7 +97,7 @@ export const ColorMatrix: Story = {
 
         <div>
           <H3>Cell 視覺 token</H3>
-          <Desc>月 view cell 的狀態色彩。Cell 高度固定容納日期 header + 3 event tile;7 欄等分。</Desc>
+          <Desc>月 view cell 的狀態色彩。Cell 最小高度 min-h-28 容納日期 header + 3 event tile,隨容器高度伸縮;7 欄等分。</Desc>
           <div className="overflow-x-auto">
             <table className="text-caption border-collapse">
               <thead>
@@ -109,7 +111,7 @@ export const ColorMatrix: Story = {
                 <tr>
                   <Td>Cell 高度</Td>
                   <Td mono>min-h-28(112px)</Td>
-                  <Td>容納 header + 3 event tile,MVP 月 view 固定</Td>
+                  <Td>容納 header + 3 event tile 的下限,隨容器高度伸縮(root h-full + grid flex-1)</Td>
                 </tr>
                 <tr>
                   <Td>Cell 寬度</Td>

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

@@ -14,7 +14,9 @@ const meta: Meta = {
 export default meta
 type Story = StoryObj
 
-const now = new Date()
+// 釘固定日期(2026-07-07 修 VR flake):真實 new Date() 讓 today 標記隨換日移格 → ubuntu
+// baseline 每隔幾天假 breach(0.07–0.5%)。釘死 = deterministic 渲染;月中讓事件分布自然。
+const now = new Date(2026, 6, 15)
 const thisMonth = now.getFullYear() + '-' + String(now.getMonth() + 1).padStart(2, '0')
 
 const Section = ({ title, children }: { title: string; children: React.ReactNode }) => (

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

@@ -92,6 +92,13 @@ Calendar 是**事件檢視 canvas**,讓 user 以**月 / 週 / 日** 三種 view
   weekStartsOn={0 | 1}                      // 0=Sun, 1=Mon
   renderEventTile={(event) => ReactNode}    // 自訂 event tile 視覺
   size="md" | "lg"                          // cell 大小(MVP 只 md;lg 為 tech debt)
+  locale="en-US"                            // Intl 語系(月份標題 / 星期名;預設 'en-US')
+  prevAriaLabel="上個月"                    // i18n override:prev 導覽鈕 aria-label
+  nextAriaLabel="下個月"                    // i18n override:next 導覽鈕 aria-label
+  navAriaLabel="行事曆月份導覽"             // i18n override:月份導覽 <nav> landmark aria-label
+  viewToggleAriaLabel="檢視切換"            // i18n override:檢視切換 SegmentedControl aria-label
+  todayLabel="今天"                         // i18n override:「今天」按鈕文字
+  createLabel="新事件"                      // i18n override:「新事件」CTA 文字(僅在傳 onCreateEvent 時渲染)
   className
 />
 ```
@@ -134,7 +141,7 @@ interface CalendarEvent {
 
 ### Cell 規則
 
-- **Cell 尺寸**:MVP 月 view cell 高度固定,容納日期 header + 3 個 event tile;寬度 7 欄等分
+- **Cell 尺寸**:MVP 月 view cell 最小高度 `min-h-28`(112px),容納日期 header + 3 個 event tile,並隨容器高度伸縮(root `h-full` + grid `flex-1`);寬度 7 欄等分
 - **日期 header**:右上角數字(對齊 Google Calendar 視覺慣例)
 - **Today cell**:日期數字以 info-filled pill 強調(對齊 Google Calendar today pill)
 - **Outside day cell**:上/下月溢出日期弱化字色 + 背景略暗區分
@@ -159,7 +166,7 @@ interface CalendarEvent {
 - 左 Nav:`<Button iconOnly>` prev/next + `<Button>今天</Button>` 跳 today
 - 中央 title:`<h2 className="text-h3">` or `text-body-lg font-medium`
 - 右視圖切換:`<SegmentedControl>`(day/week/month)—— MVP 只啟用 month,其他 disabled
-- 右上 CTA:`<Button variant="primary" startIcon={Plus}>新事件</Button>`
+- 右上 CTA:`<Button variant="primary" startIcon={Plus}>新事件</Button>` — **條件渲染:僅在傳 `onCreateEvent` 回調時出現**(未傳 = 無 CTA,純瀏覽場景);文案由 `createLabel` prop override(對齊 `todayLabel` 等 chrome 文字 i18n override 慣例)
 
 對齊 `patterns/action-bar/action-bar.spec.md`(左 context / 中 focus / 右 CTA 的經典分組)。
 

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

@@ -21,7 +21,9 @@ type Story = StoryObj<typeof Calendar>
 
 // ── 真實業務情境 ─────────────────────────────────────────────────────
 
-const now = new Date()
+// 釘固定日期(2026-07-07 修 VR flake):真實 new Date() 讓 today 標記隨換日移格 → ubuntu
+// baseline 每隔幾天假 breach(0.07–0.5%)。釘死 = deterministic 渲染;月中讓事件分布自然。
+const now = new Date(2026, 6, 15)
 const thisMonth = now.getFullYear() + '-' + String(now.getMonth() + 1).padStart(2, '0')
 
 /**

package/src/components/Calendar/calendar.tsx

@@ -98,6 +98,8 @@ export interface CalendarProps extends Omit<React.HTMLAttributes<HTMLDivElement>
   navAriaLabel?: string
   viewToggleAriaLabel?: string
   todayLabel?: string
+  /** 「新事件」CTA 文字。Override for i18n。CTA 僅在傳 `onCreateEvent` 時渲染(spec Toolbar 段)。 */
+  createLabel?: string
 }
 
 // ── Event tile color tokens ─────────────────────────────────────────────────
@@ -114,17 +116,8 @@ function coerceDate(value: string | Date): Date {
   return value instanceof Date ? value : new Date(value)
 }
 
-function eventsOnDate(events: CalendarEvent[], date: Date): CalendarEvent[] {
-  return events.filter((e) => {
-    const start = coerceDate(e.start)
-    const end = coerceDate(e.end)
-    // 日期落在 [start, end] 範圍內(日精度)
-    const d = new Date(date.getFullYear(), date.getMonth(), date.getDate()).getTime()
-    const s = new Date(start.getFullYear(), start.getMonth(), start.getDate()).getTime()
-    const eEnd = new Date(end.getFullYear(), end.getMonth(), end.getDate()).getTime()
-    return d >= s && d <= eEnd
-  })
-}
+// eventsOnDate(per-cell 全 events 掃描)已由 eventsByDate bucketing memo 取代並移除
+// (2026-07-06 D3 perf;留著會觸發 noUnusedLocals TS6133)。
 
 // ── Component ──────────────────────────────────────────────────────────────
 
@@ -151,6 +144,7 @@ const Calendar = React.forwardRef<HTMLDivElement, CalendarProps>(function Calend
   navAriaLabel = '行事曆月份導覽', // i18n-allow: DS default; consumer override via navAriaLabel prop
   viewToggleAriaLabel = '檢視切換', // i18n-allow: DS default; consumer override via viewToggleAriaLabel prop
   todayLabel = '今天', // i18n-allow: DS default; consumer override via todayLabel prop
+  createLabel = '新事件', // i18n-allow: DS default; consumer override via createLabel prop
   ...props
 }, ref) {
   // Controlled / uncontrolled refDate
@@ -186,10 +180,13 @@ const Calendar = React.forwardRef<HTMLDivElement, CalendarProps>(function Calend
     return eachDayOfInterval({ start: gridStart, end: gridEnd })
   }, [refDate, weekStartsOn])
 
-  const monthTitle = new Intl.DateTimeFormat(locale, {
-    year: 'numeric',
-    month: 'long',
-  }).format(refDate)
+  // 2026-07-06 D3 perf:formatter 依 locale memo(對齊 weekdayNames 既有做法),避免每 render 重建
+  // Intl.DateTimeFormat(已知貴的 constructor);.format(refDate) 每 render 仍執行(cheap)。
+  const monthTitleFormatter = React.useMemo(
+    () => new Intl.DateTimeFormat(locale, { year: 'numeric', month: 'long' }),
+    [locale],
+  )
+  const monthTitle = monthTitleFormatter.format(refDate)
 
   const today = new Date()
 
@@ -200,6 +197,41 @@ const Calendar = React.forwardRef<HTMLDivElement, CalendarProps>(function Calend
     )
   }, [days, locale])
 
+  // 2026-07-06 D3 perf:原每 render 對 42 cells 各跑 eventsOnDate 全 events filter = O(42×N) +
+  // 每比較配 ~5 個 Date;數百-上千 events(行事曆真實規模)單次 render 數十 ms,且父層任何 re-render
+  // 全額重付。改 useMemo 單趟 bucket:每 event 只 parse 一次,展開 [start..end](clamp 到可見 grid,
+  // 避免長跨度 event 展開爆量)寫入 date→events Map,順便完成 allDay 排序。cell 內改 O(1) map.get。行為 Δ=0。
+  const eventsByDate = React.useMemo(() => {
+    const map = new Map<string, CalendarEvent[]>()
+    if (days.length === 0) return map
+    const first = days[0]
+    const last = days[days.length - 1]
+    const gridStart = new Date(first.getFullYear(), first.getMonth(), first.getDate()).getTime()
+    const gridEnd = new Date(last.getFullYear(), last.getMonth(), last.getDate()).getTime()
+    for (const e of events) {
+      const start = coerceDate(e.start)
+      const end = coerceDate(e.end)
+      const eEnd = new Date(end.getFullYear(), end.getMonth(), end.getDate()).getTime()
+      let sMs = new Date(start.getFullYear(), start.getMonth(), start.getDate()).getTime()
+      if (eEnd < gridStart || sMs > gridEnd) continue // 可見窗外對 42 cells 無貢獻
+      if (sMs < gridStart) sMs = gridStart
+      const lastMs = Math.min(eEnd, gridEnd)
+      const cursor = new Date(sMs)
+      while (cursor.getTime() <= lastMs) {
+        const key = `${cursor.getFullYear()}-${cursor.getMonth() + 1}-${cursor.getDate()}`
+        const bucket = map.get(key)
+        if (bucket) bucket.push(e)
+        else map.set(key, [e])
+        cursor.setDate(cursor.getDate() + 1)
+      }
+    }
+    // allDay 排前(對齊 Google Calendar 全天列在上;V8 stable sort 保 events 原序 → 與舊 per-cell 一致)
+    for (const bucket of map.values()) {
+      bucket.sort((a, b) => Number(b.allDay ?? false) - Number(a.allDay ?? false))
+    }
+    return map
+  }, [events, days])
+
   const handleToday = () => setRefDate(new Date())
   const handlePrev = () => setRefDate(subMonths(refDate, 1))
   const handleNext = () => setRefDate(addMonths(refDate, 1))
@@ -265,7 +297,7 @@ const Calendar = React.forwardRef<HTMLDivElement, CalendarProps>(function Calend
 
         {onCreateEvent && (
           <Button variant="primary" size="sm" startIcon={Plus} onClick={onCreateEvent}>
-            新事件
+            {createLabel}
           </Button>
         )}
       </div>
@@ -294,8 +326,9 @@ const Calendar = React.forwardRef<HTMLDivElement, CalendarProps>(function Calend
             {days.slice(rowIdx * 7, rowIdx * 7 + 7).map((date) => {
               const inMonth = isSameMonth(date, refDate)
               const isToday = isSameDay(date, today)
-              // 2026-06-01 allDay:全天事件排 cell 頂端(對齊 Google Calendar 全天列在上)
-              const dayEvents = eventsOnDate(events, date).slice().sort((a, b) => Number(b.allDay ?? false) - Number(a.allDay ?? false))
+              // 2026-06-01 allDay:全天事件排 cell 頂端(對齊 Google Calendar 全天列在上)——
+              // 排序已在 eventsByDate bucketing memo 內完成(D3 perf),cell 內 O(1) 查表
+              const dayEvents = eventsByDate.get(`${date.getFullYear()}-${date.getMonth() + 1}-${date.getDate()}`) ?? []
               const visibleEvents = dayEvents.slice(0, MAX_TILES_PER_CELL)
               const overflowCount = dayEvents.length - visibleEvents.length
 
@@ -414,7 +447,8 @@ export const calendarMeta = {
   sizes: {
 
   },
-  states: ['default', 'hover', 'active', 'focus-visible', 'disabled'],
+  // 'active' 移除 — 日期格按壓視覺屬 DateGrid(其 meta 已 −active);nav 按壓屬內嵌 Button(2026-07-07 詞彙統一 DS-wide 按壓訊號盤點:檔內 0 active: utility / 0 *-active token)。
+  states: ['default', 'hover', 'focus-visible', 'disabled'],
   tokens: {
     bg: ['bg-muted', 'bg-neutral-hover', 'bg-info', 'bg-surface'],
     fg: ['text-fg-disabled', 'text-fg-muted', 'text-foreground'],

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

@@ -41,7 +41,7 @@ const Label = ({ children, warn }: { children: React.ReactNode; warn?: boolean }
 
 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>
+    <h2 className="text-h3 font-bold text-foreground mb-4 pb-2 border-b border-border">{title}</h2>
     {children}
   </section>
 )

package/src/components/Carousel/carousel.tsx

@@ -271,6 +271,7 @@ const CarouselPrevious = React.forwardRef<HTMLButtonElement, ArrowProps>(
 )
 CarouselPrevious.displayName = 'CarouselPrevious'
 
+// code-quality-allow: long-function — 與 CarouselPrevious 結構對稱的 JSX-heavy arrow(方向/位置/邊界三態 className 組合),拆 helper 會破壞兩支對讀性
 const CarouselNext = React.forwardRef<HTMLButtonElement, ArrowProps>(
   ({ className, 'aria-label': ariaLabel = '下一張' /* i18n-allow: DS default; consumer override via aria-label prop */ }, ref) => {
     const { orientation, scrollNext, canScrollNext } = useCarousel()
@@ -371,7 +372,9 @@ export const carouselMeta = {
   sizes: {
 
   },
-  states: ['default', 'hover', 'active', 'focus-visible', 'disabled'],
+  // 'active' 移除 — 全檔無按壓視覺(prev/next 按壓屬內嵌 Button meta,同 Notice/Alert 排除慣例;
+  // 2026-07-07 詞彙統一 DS-wide 交叉掃補修)。dot hover 為自有 hover 態(bg-on-emphasis alpha 變體)。
+  states: ['default', 'hover', 'focus-visible', 'disabled'],
   tokens: {
     bg: [],
     fg: [],

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

@@ -162,7 +162,7 @@ Chart 是 **composite data-visualization** 元件,不是單一互動 primitive:
 ## A11y 預設
 
 - **顏色非唯一語義**：不只靠色彩區分類別,配合 icon / label / pattern（Recharts 的 `strokeDasharray` 等）讓色盲 / 黑白列印仍可辨識
-- **Tooltip 鍵盤可存取**：Recharts v3 的 `accessibilityLayer`(本 DS 所有 chart 範例皆已啟用)內建鍵盤導覽——圖表 SVG 自動取得 `tabIndex=0` + `role="application"`,使用者用方向鍵 ←/→ 沿軸刻度逐一瀏覽資料點,讀屏器朗讀當前資料點;無需 controlled `activeIndex` 手動接線
+- **Tooltip 鍵盤可存取**：Recharts v3 的 `accessibilityLayer`(Recharts 3.x 預設啟用;本 DS 長條 / 折線 / 面積範例另顯式標明此 prop 文件化依賴,圓餅 / 環圈走預設)內建鍵盤導覽——圖表 SVG 自動取得 `tabIndex=0` + `role="application"`,使用者用方向鍵 ←/→ 沿軸刻度逐一瀏覽資料點,讀屏器朗讀當前資料點;無需 controlled `activeIndex` 手動接線
 - **對比度**：`--chart-*` 在 light/dark 的 step 選擇已考量對 canvas bg 的對比（light=step-6 / dark=step-5）
 
 ---

package/src/components/Chart/chart.tsx

@@ -255,7 +255,8 @@ const ChartTooltipContent = React.forwardRef<HTMLDivElement, ChartTooltipContent
                         {nestLabel ? tooltipLabel : null}
                         <span className="text-fg-secondary">{itemConfig?.label || item.name}</span>
                       </div>
-                      {item.value && (
+                      {/* 2026-07-04 修:falsy check 會讓合法資料值 0 不渲染(shadcn 上游同病)→ null check */}
+                      {item.value != null && (
                         <span className="text-foreground font-mono font-medium tabular-nums">
                           {item.value.toLocaleString()}
                         </span>

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

@@ -209,7 +209,7 @@ export const ClampPolicyRule: Story = {
         title="Per-instance override：傳 'none' 不是 undefined"
         note="這組覆寫設定在 SelectionItem 上（Checkbox 內部用它組合 label）。React destructure default 會把 undefined 當「沒傳」→ fallback 到預設。要明確表達「不截」請傳 'none'"
       >
-        <Label>SelectionItem labelMaxLines='none' / labelMaxLines={1} / labelMaxLines={2}（1-10 的數字）</Label>
+        <Label>SelectionItem labelMaxLines='none' / labelMaxLines={1} / labelMaxLines={2}（1-6 的數字；7 以上無對應 line-clamp class，傳了不生效）</Label>
       </Rule>
     </div>
   ),

package/src/components/Checkbox/checkbox.spec.md

@@ -249,7 +249,7 @@ Indeterminate 是由父層邏輯控制的狀態，Checkbox 本身不會自動進
 
 - **Uncontrolled**:只傳 `defaultChecked`,DOM 自管 — 適合表單 native submit
 - **Controlled**:傳 `checked` + `onCheckedChange`,React state 主導 — 適合需即時聯動其他欄位
-- **Read-only**:用 `readOnly` prop(不是省略 `onCheckedChange`)。standalone:`readOnly` 設 `aria-readonly` / `data-readonly` / `tabIndex=-1` + cva `pointer-events-none`,鎖互動但保留 checked 視覺;**Field 內(無 inline label)改渲染 readonly 灰框 + ✓/—**(見上方 mode 段)。注意:只傳 `checked` 而不傳 `onCheckedChange` 僅讓 Radix 把值鎖在 prop(不會更新),控件仍可 focus / click、不會進 disabled state — 那不是 readonly
+- **Read-only**:用 `readOnly` prop(不是省略 `onCheckedChange`)。standalone:`readOnly` 設 `aria-readonly` / `data-readonly` / `tabIndex=-1` + cva `pointer-events-none` + onClick preventDefault guard(2026-07-05 D4 補:`<label htmlFor>` 的 synthetic click 非 pointer event,`pointer-events-none` 攔不到,需 guard 才真鎖),鎖互動但保留 checked 視覺;**Field 內(無 inline label)改渲染 readonly 灰框 + ✓/—**(見上方 mode 段)。注意:只傳 `checked` 而不傳 `onCheckedChange` 僅讓 Radix 把值鎖在 prop(不會更新),控件仍可 focus / click、不會進 disabled state — 那不是 readonly
 
 ### `mode` prop(Field mode,正交於 size)
 

package/src/components/Checkbox/checkbox.tsx

@@ -85,13 +85,16 @@ export interface CheckboxProps
   /**
    * Inline label。提供時 Checkbox 自動透過 SelectionItem 包裝，
    * 套用 text-body / text-foreground / disabled 色 的 codified 樣式。
-   * 在 <Field> context 內時此 prop 會被忽略（由 FieldLabel 接管）。
+   * 在 <Field> context 內且不在 CheckboxGroup 內時，此 prop 會被忽略（由 FieldLabel 接管）；
+   * CheckboxGroup 內每個 checkbox 的 label 是它自己的選項名，必保留
+   * （同檔 shouldSuppressLabel = insideField && !insideGroup，AR50 anchor）。
    */
   label?: React.ReactNode
   /**
    * Inline description（secondary 文字）。須與 label 搭配使用。
    * 套用 text-body / text-fg-secondary 樣式。
-   * 在 <Field> context 內時此 prop 會被忽略（由 FieldDescription 接管）。
+   * 在 <Field> context 內且不在 CheckboxGroup 內時，此 prop 會被忽略（由 FieldDescription 接管）；
+   * CheckboxGroup 內的 description 屬各選項自有，必保留（同 label 的 group 例外）。
    */
   description?: React.ReactNode
   /** 可選左側 icon(label 前)— 2026-06-12 M30 修:轉發 SelectionItem 既有 canonical 槽(selection-item.tsx jsDoc 為 SSOT;與 avatar 互斥)*/
@@ -188,13 +191,29 @@ const Checkbox = React.forwardRef<
     // readonly 灰框 size:走 SSOT resolver(prop > ctx > 'md',field-context.ts:150-161)
     const resolvedBoxSize = useResolvedFieldSize(size ?? undefined, 'md') as 'sm' | 'md' | 'lg'
 
+    // 2026-07-04 修:display / readonly-in-Field 分支的裸 span/div 原丟棄剩餘 props
+    // (id/data-*/aria-*)且不轉發 forwardRef ref → consumer 的 aria-label 等靜默失效。
+    // 抽出 Radix 專屬 non-DOM props,其餘 DOM props 於兩分支 spread 轉發(與 Switch/
+    // RadioGroup 同修);edit 主路徑不受影響(rootEl 仍 spread 完整 props)。
+    const {
+      checked: checkedProp,
+      defaultChecked: defaultCheckedProp,
+      onCheckedChange: _onCheckedChange,
+      required: _required,
+      name: _name,
+      value: _value,
+      asChild: _asChild,
+      children: _children,
+      ...restDomProps
+    } = props
+
     // ── mode='display'(下移至所有 hooks 之後,per #35 Rules of Hooks)──────────
     // 純展示模式:無互動 primitive、渲染 ✓ / —(checked=true → ✓ / 其他 → —)。取代 BooleanDisplay。
     if (resolvedMode === 'display') {
-      const isChecked = props.checked === true
+      const isChecked = checkedProp === true
       return isChecked
-        ? <span className="text-foreground">✓</span>
-        : <span className="text-fg-muted">—</span>
+        ? <span {...restDomProps} ref={ref as React.Ref<HTMLSpanElement>} className="text-foreground">✓</span>
+        : <span {...restDomProps} ref={ref as React.Ref<HTMLSpanElement>} className="text-fg-muted">—</span>
     }
 
     // ── mode='readonly' in Field(2026-06-12 user 拍板「灰框 + ✓/—」)─────────────
@@ -206,10 +225,12 @@ const Checkbox = React.forwardRef<
     // Scope:僅 Field 內且無 inline label(FieldLabel 接管 label 的表單欄位場景);
     // standalone readOnly(settings list / SelectionItem row)維持原樣鎖互動不變。
     if (effectiveReadOnly && insideField && effectiveLabel == null) {
-      const isChecked = (props.checked ?? props.defaultChecked) === true
+      const isChecked = (checkedProp ?? defaultCheckedProp) === true
       const boxSize = resolvedBoxSize
       return (
         <div
+          {...(restDomProps as React.HTMLAttributes<HTMLDivElement>)}
+          ref={ref as React.Ref<HTMLDivElement>}
           role="checkbox"
           aria-checked={isChecked}
           aria-readonly="true"
@@ -239,6 +260,18 @@ const Checkbox = React.forwardRef<
         aria-describedby={fieldCtx?.descriptionId}
         className={cn(checkboxVariants({ size }), className)}
         {...props}
+        // 2026-07-05 D4 修:readOnly 鎖互動補 label 繞道 — <label htmlFor> 的 synthetic click
+        // 不是 pointer event,cva pointer-events-none 攔不到,點 label 文字仍 toggle。
+        // preventDefault 讓 Radix composeEventHandlers(checkForDefaultPrevented)跳過內部 toggle;
+        // 必列在 {...props} 之後才不被 consumer onClick 覆蓋(readOnly 時 consumer onClick 一併鎖,
+        // 與 pointer-events-none 擋直接點擊的行為一致)。
+        onClick={(event) => {
+          if (effectiveReadOnly) {
+            event.preventDefault()
+            return
+          }
+          props.onClick?.(event)
+        }}
       >
         <CheckboxPrimitive.Indicator className="grid place-content-center text-current">
           {props.checked === 'indeterminate'
@@ -283,7 +316,8 @@ export const checkboxMeta = {
     md: { fieldHeight: 32, iconSize: 12, typography: 'body' },
     lg: { fieldHeight: 36, iconSize: 16, typography: 'body-lg' },
   },
-  states: ['default', 'hover', 'focus-visible', 'disabled'],
+  // 'checked' = 勾選持續態(bg-primary;2026-07-07 meta 詞彙統一補列,含 indeterminate 同族)
+  states: ['default', 'hover', 'checked', 'focus-visible', 'disabled'],
   tokens: {
     bg: ['bg-disabled', 'bg-primary', 'bg-primary-hover', 'bg-surface'],
     fg: ['text-fg-disabled', 'text-fg-secondary', 'text-foreground'],

package/src/components/Checkbox/index.ts

@@ -3,3 +3,4 @@
 //   import { ... } from '@qijenchen/design-system/{components,patterns}/<Dir>'
 // Regenerate: node scripts/gen-component-indexes.mjs
 export * from './checkbox'
+export * from './checkbox-group'

package/src/components/Chip/chip.anatomy.stories.tsx

@@ -134,7 +134,7 @@ export const ColorMatrix: Story = {
       <div>
         <H3>狀態 × 色彩 Token 矩陣</H3>
         <Desc>
-          Chip 採 pill-設計準則 選中規則(跟 SegmentedControl 共用):selected 時 `--primary-hover` 同時染 border 和 text,
+          Chip 採 pill-設計準則 選中規則(跟 SegmentedControl 共用;semantic.css SSOT,2026-07-06 拍板改 base):selected 時 `--primary` 同時染 border 和 text,
           **底色維持 `--surface` 不變**——不用 primary-subtle 底色(那是 Button subtle 的視覺語言,跟 filter chip 不同)。
           視覺輕量是 filter 語意必要條件,避免 chip 群組喧賓奪主壓過資料表格。
         </Desc>
@@ -167,8 +167,8 @@ export const ColorMatrix: Story = {
               <tr>
                 <Td mono>selected</Td>
                 <Td><span className="inline-flex items-center gap-1.5"><Swatch value="--surface" size="sm" /><span className="font-mono">--surface(不變)</span></span></Td>
-                <Td><span className="inline-flex items-center gap-1.5"><Swatch value="--primary-hover" size="sm" /><span className="font-mono">--primary-hover</span></span></Td>
-                <Td><span className="inline-flex items-center gap-1.5"><Swatch value="--primary-hover" size="sm" /><span className="font-mono">--primary-hover</span></span></Td>
+                <Td><span className="inline-flex items-center gap-1.5"><Swatch value="--primary" size="sm" /><span className="font-mono">--primary</span></span></Td>
+                <Td><span className="inline-flex items-center gap-1.5"><Swatch value="--primary" size="sm" /><span className="font-mono">--primary</span></span></Td>
                 <Td mono>currentColor</Td>
               </tr>
               <tr>
@@ -185,7 +185,7 @@ export const ColorMatrix: Story = {
 
       <div>
         <H3>視覺並列對照</H3>
-        <Desc>左 default / 中 selected / 右 disabled,觀察 border 同時升階到 primary-hover 的視覺變化(非 bg 變化)。</Desc>
+        <Desc>左 default / 中 selected / 右 disabled,觀察 border 同時染 primary(base)的視覺變化(非 bg 變化)。</Desc>
         <div className="flex items-center gap-8 px-6 py-5 rounded-lg bg-canvas border border-divider">
           <div className="flex flex-col gap-2 items-start">
             <span className="text-[11px] text-fg-muted font-mono">default</span>
@@ -301,7 +301,7 @@ export const StateBehavior: Story = {
         <H3>四種狀態 × 色彩 Token</H3>
         <Desc>
           選中態走 pill-設計準則 規則(跟 SegmentedControl 完全一致):
-          **primary-hover 同時染 border 和 text**,底色維持 bg-surface 不變——不用 primary-subtle
+          **primary base 同時染 border 和 text**,底色維持 bg-surface 不變——不用 primary-subtle
           底色(那是 Button subtle 的視覺語言,跟 chip 不同)。
         </Desc>
         <div className="overflow-x-auto mb-4">
@@ -323,8 +323,8 @@ export const StateBehavior: Story = {
               <tr>
                 <Td mono>selected (data-state=on)</Td>
                 <Td><TokenCell token="--surface" /></Td>
-                <Td><TokenCell token="--primary-hover" display="primary-hover" /></Td>
-                <Td><TokenCell token="--primary-hover" display="primary-hover" /></Td>
+                <Td><TokenCell token="--primary" display="primary" /></Td>
+                <Td><TokenCell token="--primary" display="primary" /></Td>
               </tr>
               <tr>
                 <Td mono>disabled</Td>
@@ -351,7 +351,7 @@ export const StateBehavior: Story = {
         <H3>Selected 色彩跟 SegmentedControl 完全一致</H3>
         <Desc>
           兩者都是 pill 選擇語意(filter / 單選 radio),選中態視覺語言統一:
-          primary-hover 染 border + text,底色不變。只有「連體 vs 獨立」的視覺差異,選中規則是同一套。
+          primary base 染 border + text,底色不變。只有「連體 vs 獨立」的視覺差異,選中規則是同一套。
         </Desc>
         <div className="border border-dashed border-divider rounded-md p-4">
           <div className="text-caption text-fg-muted mb-2">Chip(獨立 pill)</div>
@@ -416,7 +416,7 @@ export const Accessibility = {
   render: () => (
     <div className="max-w-3xl text-body text-fg-secondary">
       <h3 className="text-h5 text-foreground mb-2">無障礙設計</h3>
-      <p className="whitespace-pre-line">{"詳 「無障礙設計」段。摘要:\n\n  ARIA / Pattern  :繼承 Radix toggle-group 鍵盤模式(role / aria-* / 鍵盤導覽)。詳 [Radix Accessibility docs](https://www.radix-ui.com/primitives/docs/components/toggle-group#accessibility)。\n\n  Keyboard 行為  :\n\n- Tab — 進入整組 chip(只有一個 Tab 停留點)\n- ←/→ — 在組內 chip 之間移動焦點\n- Tab — 再按一次離開整組\n- Enter / Space — 切換選取\n\n  Focus  :焦點環為 2px 的 --ring 色描邊(focus-visible 才顯示)。整組 chip 用方向鍵移動焦點、Tab 進出整組——這不是 Dialog 那種把焦點鎖在裡面的行為。\n\n  驗證  :Storybook a11y addon panel 應 0 critical violation;鍵盤完整可操作(無需滑鼠)。WCAG AA 對比 ≥ 4.5:1(文字)"}</p>
+      <p className="whitespace-pre-line">{"詳 「無障礙設計」段。摘要:\n\n  ARIA / Pattern  :繼承 Radix toggle-group 鍵盤模式(role / aria-* / 鍵盤導覽)。詳 [Radix Accessibility docs](https://www.radix-ui.com/primitives/docs/components/toggle-group#accessibility)。\n\n  Keyboard 行為  :\n\n- Tab — 進入整組 chip(只有一個 Tab 停留點)\n- ←/→ — 在組內 chip 之間移動焦點\n- Tab — 再按一次離開整組\n- Enter / Space — 切換選取\n\n  Focus  :焦點環為 2px 的 --ring 色(ring-2 ring-ring ring-offset-1,以 box-shadow 實作並 outline-none;focus-visible 才顯示)。整組 chip 用方向鍵移動焦點、Tab 進出整組——這不是 Dialog 那種把焦點鎖在裡面的行為。\n\n  驗證  :Storybook a11y addon panel 應 0 critical violation;鍵盤完整可操作(無需滑鼠)。WCAG AA 對比 ≥ 4.5:1(文字)"}</p>
     </div>
   ),
 }

package/src/components/Chip/chip.principles.stories.tsx

@@ -197,8 +197,8 @@ export const SelectedStyleRule: Story = {
   render: () => (
     <div>
       <Rule
-        title="選中 = primary-hover text + border，底色不變"
-        note="對齊 SegmentedControl / Tabs / Input 的設計準則 選中規則(primary-hover 同時染文字和線條)。用 bg 強調會讓 chip 看起來變成「按鈕」,混淆多選濾鏡的語意"
+        title="選中 = primary text + border，底色不變"
+        note="對齊 SegmentedControl / Tabs 的選中 canonical(primary base 同時染文字和線條;semantic.css SSOT,2026-07-06 拍板自 hover 階改 base——瞬時弱、持續強)。用 bg 強調會讓 chip 看起來變成「按鈕」,混淆多選濾鏡的語意"
       >
         <ChipGroup type="multiple" defaultValue={['react', 'ts']}>
           <Chip value="react">React</Chip>
@@ -206,7 +206,7 @@ export const SelectedStyleRule: Story = {
           <Chip value="ts">TypeScript</Chip>
           <Chip value="js">JavaScript</Chip>
         </ChipGroup>
-        <Label>↑ 選中(React / TypeScript)= primary-hover 文字 + 邊框,底色仍 bg-surface</Label>
+        <Label>↑ 選中(React / TypeScript)= primary 文字 + 邊框,底色仍 bg-surface</Label>
       </Rule>
 
       <Rule