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

package/src/components/Button/button.principles.stories.tsx

@@ -351,7 +351,7 @@ export const OrderRule: Story = {
         note="使用者眼睛最先掃到最上方，最希望被點擊的動作放第一個。所有按鈕撐滿容器寬度"
       >
         <div className="w-[200px]">
-          <ButtonGroup direction="vertical">
+          <ButtonGroup orientation="vertical">
             <Button variant="primary">確認送出</Button>
             <Button variant="tertiary">取消</Button>
           </ButtonGroup>

package/src/components/Button/button.spec.md

@@ -273,7 +273,7 @@ const ICON_ONLY_BASE = 'aspect-square p-0 min-w-0 gap-0'
 
 完整 rationale(包含 2026-04-25 從 padding-formula 派切換的 bug origin)+ 4 家世界級對照 → **SSOT 在 `tokens/uiSize/uiSize.spec.md`「Icon-only 元件的 padding canonical」節**。本 spec 不重複,只 pointer。
 
-**icon-only 按鈕內建自動 tooltip：** 當 `iconOnly` 為 true 時，Button 自動以 `aria-label` 的值渲染 tooltip。開發者不需要額外包 `<Tooltip>`——tooltip 是元件保證的行為，不是開發者「記得要加」的外部組合。
+**icon-only 按鈕內建自動 tooltip：** 當 `iconOnly` 為 true 且非 `asChild` 時，Button 自動以 `aria-label` 的值渲染 tooltip（`asChild` 因 Radix Slot 單 child 限制不包 Tooltip，consumer 需自包）。開發者不需要額外包 `<Tooltip>`——tooltip 是元件保證的行為，不是開發者「記得要加」的外部組合。
 
 `aria-label` 是給螢幕閱讀器的，tooltip 是給所有人看的，兩者語意相同，由同一個值驅動。
 
@@ -434,7 +434,7 @@ N/A(action trigger,無資料層)。
 
 ## A11y 預設
 
-**ARIA / Pattern**:預設渲染原生 `<button>`,自動繼承瀏覽器原生按鈕語意(button role / Enter / Space 觸發 / Tab 聚焦),無需額外 ARIA。`asChild` 時改用 Radix `Slot` 把 props 合併到 consumer child element(Slot 為純 prop-merger,a11y 仍由該 child 自負)。icon-only 模式傳入 `aria-label` 描述用途並自動包 Tooltip。`pressed` 定義時自動寫 `aria-pressed` + `data-state`。
+**ARIA / Pattern**:預設渲染原生 `<button>`,自動繼承瀏覽器原生按鈕語意(button role / Enter / Space 觸發 / Tab 聚焦),無需額外 ARIA。`asChild` 時改用 Radix `Slot` 把 props 合併到 consumer child element(Slot 為純 prop-merger,a11y 仍由該 child 自負)。icon-only 模式傳入 `aria-label` 描述用途;**僅在非 `asChild` 時**自動包 Tooltip(`asChild` 因 Radix Slot 單 child 限制不包,consumer 需自管 child 的 `aria-label` 與 Tooltip)。`pressed` 定義時自動寫 `aria-pressed` + `data-state`。
 
 **Focus**:鍵盤聚焦時(`focus-visible`)顯示 focus ring(`focus-visible:ring-2 focus-visible:ring-ring focus-visible:ring-offset-1`,以 box-shadow 實作並 `outline-none`);滑鼠點擊不觸發。Button 為單一互動元件,**不含** focus trap / focus restoration(那是 Dialog / 浮層的概念)。
 

package/src/components/Button/button.stories.tsx

@@ -24,7 +24,7 @@ const meta: Meta<typeof Button> = {
     },
     danger: {
       control: 'boolean',
-      description: '套用危險色（紅色）。僅 `primary` / `secondary` / `text` 支援（`tertiary` 視覺與 secondary+danger 重複、`link` 語義矛盾，見 spec 禁止事項）。',
+      description: '套用危險色（紅色）。僅 `primary` / `secondary` / `text` 支援（`tertiary` 無 danger compound——會靜默渲染成一般 tertiary、並非等同 secondary+danger；`link` 語義矛盾。見 spec 禁止事項）。',
     },
     size: {
       control: 'select',
@@ -76,11 +76,11 @@ export const Default: Story = {
   name: '預設',
   render: () => (
     <div className="flex flex-wrap items-center gap-3">
-      <Button variant="primary">主要動作</Button>
-      <Button variant="secondary">次要動作</Button>
-      <Button variant="tertiary">第三動作</Button>
-      <Button variant="text">純文字</Button>
-      <Button variant="link">連結樣式</Button>
+      <Button variant="primary">送出申請</Button>
+      <Button variant="secondary">儲存草稿</Button>
+      <Button variant="tertiary">取消</Button>
+      <Button variant="text">重設表單</Button>
+      <Button variant="link">查看填寫說明</Button>
     </div>
   ),
 }
@@ -240,26 +240,20 @@ export const Loading: Story = {
     <div className="flex flex-col gap-6">
       {/* 行為對照 */}
       <div>
-        <p className="mb-2 text-caption text-fg-muted">行為對照：原始 → loading</p>
-        <div className="flex flex-col gap-3">
-          <div className="flex items-center gap-3">
-            <Button variant="primary" startIcon={Download}>匯出</Button>
-            <span className="text-caption text-fg-muted">→</span>
-            <Button variant="primary" startIcon={Download} loading>匯出中</Button>
-            <span className="text-caption text-fg-muted">startIcon 被 spinner 替換，位置不變</span>
-          </div>
-          <div className="flex items-center gap-3">
-            <Button variant="primary">儲存</Button>
-            <span className="text-caption text-fg-muted">→</span>
-            <Button variant="primary" loading>儲存中</Button>
-            <span className="text-caption text-fg-muted">spinner 出現在文字左側，按鈕略寬</span>
-          </div>
-          <div className="flex items-center gap-3">
-            <Button size="sm" iconOnly startIcon={Download} aria-label="下載" />
-            <span className="text-caption text-fg-muted">→</span>
-            <Button size="sm" iconOnly startIcon={Download} loading aria-label="下載中" />
-            <span className="text-caption text-fg-muted">icon-only：spinner 替換 icon</span>
-          </div>
+        <p className="mb-2 text-caption text-fg-muted">行為對照：操作前與載入中</p>
+        <div className="grid grid-cols-[auto_auto_1fr] items-center gap-x-6 gap-y-3">
+          <span className="text-caption text-fg-muted">操作前</span>
+          <span className="text-caption text-fg-muted">載入中</span>
+          <span />
+          <Button variant="primary" startIcon={Download}>匯出</Button>
+          <Button variant="primary" startIcon={Download} loading>匯出中</Button>
+          <span className="text-caption text-fg-muted">startIcon 被 spinner 替換，位置不變</span>
+          <Button variant="primary">儲存</Button>
+          <Button variant="primary" loading>儲存中</Button>
+          <span className="text-caption text-fg-muted">spinner 出現在文字左側，按鈕略寬</span>
+          <Button size="sm" iconOnly startIcon={Download} aria-label="下載" />
+          <Button size="sm" iconOnly startIcon={Download} loading aria-label="下載中" />
+          <span className="text-caption text-fg-muted">icon-only：spinner 替換 icon</span>
         </div>
       </div>
 
@@ -325,8 +319,8 @@ export const HoverFocusState: Story = {
   tags: ['!autodocs'],
   render: () => (
     <div className="flex gap-4">
-      <Button variant="primary" data-testid="hover-target">Hover 我</Button>
-      <Button variant="primary" data-testid="focus-target">Focus 我</Button>
+      <Button variant="primary" data-testid="hover-target">查看帳單</Button>
+      <Button variant="primary" data-testid="focus-target">下載明細</Button>
     </div>
   ),
   play: async ({ canvasElement }) => {

package/src/components/Button/button.tsx

@@ -228,6 +228,7 @@ const buttonVariants = cva(
 interface ButtonGroupContextValue {
   fullWidth?: boolean
 }
+/** @internal — ButtonGroup↔Button 私有 context(fullWidth 注入);consumer 不直接 import,經 <ButtonGroup> 消費。root barrel 排除(subpath 仍可 wrap 後用)。 */
 const ButtonGroupContext = React.createContext<ButtonGroupContextValue>({})
 
 type InternalVariant = VariantProps<typeof buttonVariants>['variant']
@@ -581,7 +582,7 @@ export const buttonMeta = {
     // 2026-07-14 deep-audit 二次補齊(掃 cva 全 bg-* class):+ neutral-selected-hover / neutral-selected-active
     // (neutral pressedTone compound 消費)+ error / error-hover / error-active(primary+danger bg-error 系)
     bg: ['--primary', '--primary-hover', '--primary-active', '--primary-subtle', '--bg-disabled', '--surface', '--neutral-hover', '--neutral-active', '--neutral-selected', '--neutral-selected-hover', '--neutral-selected-active', '--error', '--error-hover', '--error-active'],
-    fg: ['--on-emphasis', '--fg-disabled', '--foreground', '--primary', '--error', '--error-hover', '--error-active'],
+    fg: ['--on-emphasis', '--fg-disabled', '--foreground', '--primary', '--primary-hover', '--primary-active', '--error', '--error-hover', '--error-active'],
     ring: ['--ring'],
   },
   defaultVariant: 'tertiary',  // 2026-06-10 修 stale:對齊 cva defaultVariants(2026-06-06 labeled 預設改 tertiary,meta 漏同步)

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

@@ -216,7 +216,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">{"詳 `calendar.spec.md` 「A11y 預設」段。摘要:\n\n  Grid role  :月格容器 `role=\"grid\"` + `aria-label`(月份),每列 `role=\"row\"`(`display:contents` 保 CSS grid 佈局),每格 `role=\"gridcell\"`(非互動容器),日期數字按鈕帶 `aria-label`(日期 + 事件數)。事件 tile `role=\"button\"` + `aria-label`(事件標題)。\n\n  Keyboard 行為(MVP 實作現況)  :\n\n- Tab — 逐一 focus 每格的日期數字按鈕與其中的事件 tile(cell 為非互動 gridcell 容器,滑鼠點空白處等同點日期)\n- Enter / Space — 日期數字按鈕觸發 `onDateClick`;事件 tile 觸發 `onEventClick`\n- Toolbar 的 ◀ / 今天 / ▶ / 檢視切換為標準可聚焦控件,Tab 可達\n\n  Keyboard tech debt(尚未實作,見 spec.md「MVP vs 後續增量」)  :\n\n- ↑/↓/←/→ 在日期格間 roving 移動、PageUp/Down 切月、Shift+PageUp/Down 切年、Esc 關閉 — 隨週 / 日 view 增量一併補上 roving tabindex\n\n  Focus  :focus-visible ring 對齊 DS 設計準則( outline: 2px solid var(--ring) );日期數字按鈕與事件 tile 皆有 ring。\n\n  驗證  :Storybook a11y addon panel 應 0 critical violation。WCAG AA contrast ≥ 4.5:1(text)/ 3:1(UI)。"}</p>
+      <p className="whitespace-pre-line">{"詳 `calendar.spec.md` 「A11y 預設」段。摘要:\n\n  Grid role  :月格容器 `role=\"grid\"` + `aria-label`(月份),每列 `role=\"row\"`(`display:contents` 保 CSS grid 佈局),每格 `role=\"gridcell\"`(非互動容器),日期數字按鈕帶 `aria-label`(日期 + 事件數)。事件 tile `role=\"button\"` + `aria-label`(事件標題)。\n\n  Keyboard 行為(MVP 實作現況)  :\n\n- Tab — 逐一 focus 每格的日期數字按鈕與其中的事件 tile(cell 為非互動 gridcell 容器,滑鼠點空白處等同點日期)\n- Enter / Space — 日期數字按鈕觸發 `onDateClick`;事件 tile 觸發 `onEventClick`\n- Toolbar 的 ◀ / 今天 / ▶ / 檢視切換為標準可聚焦控件,Tab 可達\n\n  Keyboard tech debt(尚未實作,見 spec.md「MVP vs 後續增量」)  :\n\n- ↑/↓/←/→ 在日期格間 roving 移動、PageUp/Down 切月、Shift+PageUp/Down 切年、Esc 關閉 — 隨週 / 日 view 增量一併補上 roving tabindex\n\n  Focus  :focus-visible ring 對齊 DS 設計準則(ring-2 ring-ring,box-shadow 實作 + outline-none);日期數字按鈕與事件 tile 皆有 ring。\n\n  驗證  :Storybook a11y addon panel 應 0 critical violation。WCAG AA contrast ≥ 4.5:1(text)/ 3:1(UI)。"}</p>
     </div>
   ),
 }

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

@@ -267,6 +267,6 @@ MVP 無內建 error 狀態(無 `error` / `onRetry` prop)——載入失敗由 co
 - ↑/↓/←/→ 在日期格間 roving 移動、PageUp/Down 切月、Shift+PageUp/Down 切年、Esc 關閉 — 隨週 / 日 view 增量一併補上 roving tabindex
 - 此為**已知 a11y gap(非發佈 blocker)**:方向鍵 roving 是 APG grid pattern 建議;MVP 所有互動元素皆 Tab 可達(鍵盤可操作性已滿足),驗證基準見下方「驗證」
 
-**Focus**:focus-visible ring 對齊 DS canonical(`outline: 2px solid var(--ring)`);日期數字按鈕與事件 tile 皆有 ring。
+**Focus**:focus-visible ring 對齊 DS canonical(`ring-2 ring-ring`,box-shadow 實作 + `outline-none`,同 button.spec A11y 段);日期數字按鈕與事件 tile 皆有 ring。
 
 **驗證**:Storybook a11y addon panel 應 0 critical violation。WCAG AA contrast ≥ 4.5:1(text)/ 3:1(UI)。

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

@@ -128,7 +128,7 @@ Tabs 和 Carousel 都能「按順序切換下方內容」,但**語意與視覺
 
 ### 視覺規格
 
-- **基於 DS Button**:`<Button variant="tertiary" size="md" iconOnly />`——對齊 DS 規則,唯 shape 覆寫 `rounded-full`(media carousel documented 例外,見下一條「形狀 documented 例外」);其餘視覺全繼承 Button tertiary,不另自訂
+- **基於 DS Button**:`<Button variant="tertiary" size="md" iconOnly />`(variant/size 為 **default,可覆寫**——見「Arrow Props」)——對齊 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/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 有底色更搶焦點,均不合適
@@ -136,6 +136,22 @@ Tabs 和 Carousel 都能「按順序切換下方內容」,但**語意與視覺
 - 圖標:`startIcon={ChevronLeft}` / `startIcon={ChevronRight}`,尺寸由 Button 內部程式化決定
 - **絕對定位 wrapper**:Button 外層 `<div>` 負責 `absolute` 定位 + hover-only opacity(`group-hover/carousel:opacity-100` / `focus-within:opacity-100`);Button 本身不做任何定位或可見性邏輯(職責分離)
 
+### Arrow Props(API 契約,2026-07-18 決策14)
+
+`CarouselPrevious` / `CarouselNext` 開放**完整 Button props**——對齊 shadcn Carousel 的 `React.ComponentProps<typeof Button>` idiom(source `https://github.com/shadcn-ui/ui` `apps/www/registry/default/ui/carousel.tsx` CarouselPrevious/Next) <!-- @benchmark-unverified: shadcn Carousel arrow 轉發 Button props 為已知 pattern,確切行號未逐一 WebFetch 驗 -->。consumer 可換 `variant` / `size`、綁 analytics `onClick`、傳 `data-*` / `id`:
+
+| Prop | 指向 | 說明 |
+|------|------|------|
+| `className` | **箭頭按鈕本身** | 疊在 DS default(`rounded-full` 等)之後,可覆寫按鈕樣式(className 指按鈕,非 wrapper) |
+| `wrapperClassName` | **定位層 wrapper** | 絕對定位 + hover-only 顯示層的 className(換位置 / 顯示邏輯用) |
+| `variant` / `size` | 箭頭按鈕 | default `tertiary` / `md`,可覆寫 |
+| `startIcon` | 箭頭按鈕 | default `ChevronLeft` / `ChevronRight`,可覆寫圖標 |
+| `onClick` | 箭頭按鈕 | 與內部 `scrollPrev/Next` **compose**(先導覽再呼叫 consumer handler;analytics 用) |
+| `disabled` | 箭頭按鈕 | 與邊界態 **compose**(`!canScroll* \|\| disabled`;consumer 可強制 disable,不可強制在邊界 enable) |
+| `iconOnly` | — | 固定 `true`(箭頭恆 icon-only),不可覆寫 |
+
+**⚠️ BREAKING(決策14 遷移)**:`className` 語義由「定位 wrapper」改為「箭頭按鈕」。**原本用 `className` 做定位覆寫的 consumer → 改傳 `wrapperClassName`**。DS 內既有 consumer 全數 bare `<CarouselPrevious />`(無 className 傳入)= 0 遷移成本;fork consumer 若有覆寫定位,依本條遷移。
+
 ---
 
 ## Dots indicator

package/src/components/Carousel/carousel.tsx

@@ -187,8 +187,12 @@ Carousel.displayName = 'Carousel'
 const CarouselContent = React.forwardRef<
   HTMLDivElement,
   React.HTMLAttributes<HTMLDivElement>
->(({ className, ...props }, ref) => {
+>(({ className, children, ...props }, ref) => {
   const { carouselRef, orientation } = useCarousel()
+  // 2026-07-18 決策5:注入 slide index/total 給 CarouselItem 自動產生「第 N 張,共 M 張」a11y 位置名
+  //   (WAI-ARIA APG carousel「N of M」https://www.w3.org/WAI/ARIA/apg/patterns/carousel/)。count 取
+  //   React.Children.count(可靠,不依賴 embla init 後的 scrollSnaps)。
+  const total = React.Children.count(children)
   return (
     <div ref={carouselRef} className="overflow-hidden">
       <div
@@ -199,31 +203,46 @@ const CarouselContent = React.forwardRef<
           className,
         )}
         {...props}
-      />
+      >
+        {React.Children.map(children, (child, index) =>
+          React.isValidElement(child)
+            ? React.cloneElement(child as React.ReactElement<CarouselItemInternalProps>, { _slideIndex: index, _slideTotal: total })
+            : child,
+        )}
+      </div>
     </div>
   )
 })
 CarouselContent.displayName = 'CarouselContent'
 
-const CarouselItem = React.forwardRef<
-  HTMLDivElement,
-  React.HTMLAttributes<HTMLDivElement>
->(({ className, ...props }, ref) => {
-  const { orientation } = useCarousel()
-  return (
-    <div
-      ref={ref}
-      role="group"
-      aria-roledescription="slide"
-      className={cn(
-        'min-w-0 shrink-0 grow-0 basis-full',
-        orientation === 'horizontal' ? 'pl-4' : 'pt-4',
-        className,
-      )}
-      {...props}
-    />
-  )
-})
+interface CarouselItemInternalProps extends React.HTMLAttributes<HTMLDivElement> {
+  /** @internal CarouselContent 注入 —— 用於自動 slide 位置名。 */
+  _slideIndex?: number
+  _slideTotal?: number
+}
+
+const CarouselItem = React.forwardRef<HTMLDivElement, CarouselItemInternalProps>(
+  ({ className, _slideIndex, _slideTotal, 'aria-label': ariaLabel, ...props }, ref) => {
+    const { orientation } = useCarousel()
+    // 無 consumer aria-label 時自動位置名(第 N 張,共 M 張);consumer 傳 aria-label 優先(可自訂內容名)。
+    const autoLabel =
+      ariaLabel ?? (_slideIndex != null && _slideTotal != null ? `第 ${_slideIndex + 1} 張,共 ${_slideTotal} 張` : undefined)
+    return (
+      <div
+        ref={ref}
+        role="group"
+        aria-roledescription="slide"
+        aria-label={autoLabel}
+        className={cn(
+          'min-w-0 shrink-0 grow-0 basis-full',
+          orientation === 'horizontal' ? 'pl-4' : 'pt-4',
+          className,
+        )}
+        {...props}
+      />
+    )
+  },
+)
 CarouselItem.displayName = 'CarouselItem'
 
 // ── Arrow buttons(hover 才顯示)────────────────────────────────────────────
@@ -231,10 +250,15 @@ CarouselItem.displayName = 'CarouselItem'
 // opacity transition 控制(Button 本身不負責)。此 wrapper 存在僅為絕對定位 +
 // hover/focus 可見性,不再覆寫 Button 的視覺 token。
 
-type ArrowProps = {
-  className?: string
-  /** ARIA label. Override for i18n. Prev default: 「上一張」;Next default: 「下一張」 */
-  'aria-label'?: string
+// 2026-07-18 決策14(user 授權 B 案:開放完整 Button props + wrapperClassName):
+// 對齊 shadcn/Radix Carousel —— `className` 指**箭頭按鈕本身**(非定位 wrapper),
+// consumer 可換 variant/size、綁 analytics onClick、傳 data-* 等完整 Button props。
+// 定位層(絕對定位 + hover-only 顯示)的 className 走新 `wrapperClassName`。
+// **BREAKING**:`className` 語義由「定位 wrapper」改為「按鈕」(遷移:定位覆寫改傳 wrapperClassName)。
+// onClick/disabled 內部與 carousel 導覽 compose(scrollPrev/Next + 邊界 disable 保留,consumer 疊加)。
+type ArrowProps = Omit<React.ComponentPropsWithoutRef<typeof Button>, 'iconOnly'> & {
+  /** 定位層 wrapper 的 className(絕對定位 + hover-only 顯示層);箭頭按鈕樣式走 `className`。 */
+  wrapperClassName?: string
 }
 
 const arrowWrapperClass = cn(
@@ -247,7 +271,19 @@ const arrowWrapperClass = cn(
 
 // code-quality-allow: long-function — foundational composite main body — 拆 sub-fn 會複雜化 local state / ref / context binding
 const CarouselPrevious = React.forwardRef<HTMLButtonElement, ArrowProps>(
-  ({ className, 'aria-label': ariaLabel = '上一張' /* i18n-allow: DS default; consumer override via aria-label prop */ }, ref) => {
+  (
+    {
+      className,
+      wrapperClassName,
+      onClick,
+      disabled,
+      variant = 'tertiary',
+      size = 'md',
+      'aria-label': ariaLabel = '上一張' /* i18n-allow: DS default; consumer override via aria-label prop */,
+      ...props
+    },
+    ref,
+  ) => {
     const { orientation, scrollPrev, canScrollPrev } = useCarousel()
     return (
       <div
@@ -256,22 +292,24 @@ const CarouselPrevious = React.forwardRef<HTMLButtonElement, ArrowProps>(
           orientation === 'horizontal'
             ? 'left-3 top-1/2 -translate-y-1/2'
             : 'top-3 left-1/2 -translate-x-1/2 rotate-90',
-          className,
+          wrapperClassName,
         )}
       >
         <Button
           ref={ref}
-          variant="tertiary"
-          size="md"
-          iconOnly
+          variant={variant}
+          size={size}
           startIcon={ChevronLeft}
           aria-label={ariaLabel}
-          disabled={!canScrollPrev}
-          onClick={scrollPrev}
+          {...props}
+          iconOnly
+          disabled={!canScrollPrev || disabled}
+          onClick={(e) => { scrollPrev(); onClick?.(e) }}
           // documented exception:視覺取向的 media carousel 箭頭用 rounded-full 圓形,
           // 優於 DS default rounded-md。對齊 Instagram / Airbnb / Notion / Apple Photos
           // 世界級慣例 — media carousel 箭頭圓形減少視覺方塊感壓迫內容。spec「箭頭視覺規格」有明示。
-          className="rounded-full"
+          // consumer className 疊加在後可覆寫(決策14)。
+          className={cn('rounded-full', className)}
         />
       </div>
     )
@@ -281,7 +319,19 @@ 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) => {
+  (
+    {
+      className,
+      wrapperClassName,
+      onClick,
+      disabled,
+      variant = 'tertiary',
+      size = 'md',
+      'aria-label': ariaLabel = '下一張' /* i18n-allow: DS default; consumer override via aria-label prop */,
+      ...props
+    },
+    ref,
+  ) => {
     const { orientation, scrollNext, canScrollNext } = useCarousel()
     return (
       <div
@@ -290,20 +340,21 @@ const CarouselNext = React.forwardRef<HTMLButtonElement, ArrowProps>(
           orientation === 'horizontal'
             ? 'right-3 top-1/2 -translate-y-1/2'
             : 'bottom-3 left-1/2 -translate-x-1/2 rotate-90',
-          className,
+          wrapperClassName,
         )}
       >
         <Button
           ref={ref}
-          variant="tertiary"
-          size="md"
-          iconOnly
+          variant={variant}
+          size={size}
           startIcon={ChevronRight}
           aria-label={ariaLabel}
-          disabled={!canScrollNext}
-          onClick={scrollNext}
-          // documented exception:同 Previous,媒體導向 carousel 箭頭圓形
-          className="rounded-full"
+          {...props}
+          iconOnly
+          disabled={!canScrollNext || disabled}
+          onClick={(e) => { scrollNext(); onClick?.(e) }}
+          // documented exception:同 Previous,媒體導向 carousel 箭頭圓形;consumer className 疊加可覆寫。
+          className={cn('rounded-full', className)}
         />
       </div>
     )

package/src/components/Checkbox/checkbox-group.tsx

@@ -1,6 +1,7 @@
 // @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 * as React from 'react'
 import { cn } from '@/lib/utils'
+import { useFieldContext } from '@/design-system/components/Field/field-context'
 
 // ── CheckboxGroupContext ────────────────────────────────────────────────────
 // 讓內部 `<Checkbox>` 知道「我在 CheckboxGroup 裡」→ 即使 Field context 也存在,
@@ -71,21 +72,31 @@ export interface CheckboxGroupProps extends React.HTMLAttributes<HTMLDivElement>
 const CHECKBOX_GROUP_CTX_VALUE = { inGroup: true } as const
 
 const CheckboxGroup = React.forwardRef<HTMLDivElement, CheckboxGroupProps>(
-  ({ className, orientation = 'vertical', ...props }, ref) => (
-    <CheckboxGroupContext.Provider value={CHECKBOX_GROUP_CTX_VALUE}>
-      <div
-        ref={ref}
-        role="group"
-        className={cn(
-          // 垂直 CheckboxGroup:zero gap(間距由 SelectionItem py 獨家擁有,見 docblock canonical)
-          // 水平:短 label 並排需水平 gap-4(label 沒有 py 擴散,需要顯式 gap)
-          orientation === 'vertical' ? 'grid' : 'flex flex-wrap gap-4',
-          className
-        )}
-        {...props}
-      />
-    </CheckboxGroupContext.Provider>
-  )
+  ({ className, orientation = 'vertical', ...props }, ref) => {
+    // Field 整合 a11y(2026-07-17 d10i1):role="group" 的 <div> 無法被 <FieldLabel htmlFor> 命名 →
+    // 自讀 fieldCtx 接 aria-labelledby / aria-describedby / aria-invalid,讓群組在 accessibility tree
+    // 有名稱、描述與錯誤狀態(對齊 RadioGroup Root 的 fieldCtx 接線,radio-group.tsx L164-166)。
+    // standalone(無 Field)時皆 undefined,consumer 經 {...props} 傳的 aria-* 照舊生效(置於 spread 前故可被覆蓋)。
+    const fieldCtx = useFieldContext()
+    return (
+      <CheckboxGroupContext.Provider value={CHECKBOX_GROUP_CTX_VALUE}>
+        <div
+          ref={ref}
+          role="group"
+          aria-labelledby={fieldCtx?.labelId}
+          aria-describedby={fieldCtx?.descriptionId}
+          aria-invalid={fieldCtx?.invalid || undefined}
+          className={cn(
+            // 垂直 CheckboxGroup:zero gap(間距由 SelectionItem py 獨家擁有,見 docblock canonical)
+            // 水平:短 label 並排需水平 gap-4(label 沒有 py 擴散,需要顯式 gap)
+            orientation === 'vertical' ? 'grid' : 'flex flex-wrap gap-4',
+            className
+          )}
+          {...props}
+        />
+      </CheckboxGroupContext.Provider>
+    )
+  }
 )
 CheckboxGroup.displayName = 'CheckboxGroup'
 // Field layout declaration:block primitive(多項堆疊)——進入 <Field> 時

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

@@ -297,8 +297,8 @@ const InspectorInner = () => {
                 size={size}
                 checked={checkedState === 'checked' ? true : checkedState === 'indeterminate' ? 'indeterminate' : false}
                 disabled={interaction === 'disabled'}
-                label="Label text"
-                description={withDescription ? '次要說明文字,給使用者更多 context' : undefined}
+                label="接收每週專案摘要"
+                description={withDescription ? '每週一自動寄送專案進度與待辦事項摘要到你的信箱' : undefined}
               />
             ) : (
               <Checkbox
@@ -496,7 +496,7 @@ export const SizeMatrix = {
                   <Td><Checkbox size={sz} defaultChecked /></Td>
                   <Td>
                     {/* 公開 API:`<Checkbox label>` 內部自動包 SelectionItem + wire id/htmlFor(selection-item.spec.md 禁裸用) */}
-                    <Checkbox size={sz} defaultChecked label="Label text" />
+                    <Checkbox size={sz} defaultChecked label="接收通知" />
                   </Td>
                 </tr>
               ))}

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

@@ -232,6 +232,10 @@ Indeterminate 是由父層邏輯控制的狀態，Checkbox 本身不會自動進
 | disabled unchecked | transparent | bg-disabled | 無 |
 | disabled checked | transparent | bg-disabled | fg-disabled dot |
 
+### Loading（N/A）
+
+Checkbox / Radio **無 Loading 狀態**——選擇控件是同步 toggle,值隨 form submit 才套用(見「定位」),不承載非同步進度。提交進行中的 loading 狀態由**表單的 submit `Button` loading state** 擁有;提交期間若需鎖定選項,將 Checkbox 設 `disabled` 即可,不在控件本體加 spinner。（對齊 Switch spec「無 loading state」——async 進度不屬選擇控件本體。）
+
 ---
 
 ## Controlled / Uncontrolled API(M26)
@@ -244,14 +248,18 @@ Indeterminate 是由父層邏輯控制的狀態，Checkbox 本身不會自動進
 
 ### `mode` prop(Field mode,正交於 size)
 
-`mode?: 'edit' | 'display' | 'readonly' | 'disabled'`(默認 inherit Field context 或 `'edit'`),對齊 `field-types.ts` FieldMode(完整 4-mode canonical SSOT → `Field/field-controls.spec.md`;本段鏡像 switch.spec.md 同名段):
+`mode?: 'edit' | 'view' | 'readonly' | 'disabled'`(默認 inherit Field context 或 `'edit'`),對齊 `field-types.ts` FieldMode(完整 4-mode canonical SSOT → `Field/field-controls.spec.md`;本段鏡像 switch.spec.md 同名段):
 - `edit`(預設)— 可勾選的 Checkbox。
-- `display` — **純展示**:渲染 **Check icon(true=勾)/ X icon(false=叉)**,中性 `text-foreground` 色,非互動、無 input chrome,供 DataTable boolean cell 非編輯態共用。boolean 值符號 SSOT = `../SelectionControl/boolean-value.tsx`(勾/叉 icon + 中性色;M22 世界級:MUI X DataGrid Check/Close icon 中性色 / React-admin TrueIcon-FalseIcon;false 中性非紅 = 「否」值非「錯誤」)。
+- `view` — **純展示**:渲染 **Check icon(true=勾)/ X icon(false=叉)**,中性 `text-foreground` 色,非互動、無 input chrome,供 DataTable boolean cell 非編輯態共用。boolean 值符號 SSOT = `../SelectionControl/boolean-value.tsx`(勾/叉 icon + 中性色;M22 世界級:MUI X DataGrid Check/Close icon 中性色 / React-admin TrueIcon-FalseIcon;false 中性非紅 = 「否」值非「錯誤」)。
 - `readonly` — **Field 內(無 inline label)**= `fieldWrapperStyles` readonly 灰框 + 勾/叉 icon(與 Input readonly 同一視覺語言,2026-06-12 user 拍板;世界級:Salesforce output ✓ glyph / SAP 靜態文字);**standalone / 有 inline label**(SelectionItem row)= 正常色鎖互動(同下方 Read-only)。
-- `disabled` — 落到真 disabled chrome(`effectiveDisabled`,2026-06-12 修:mode='disabled' 直傳〔如 DataTable disabled cell〕與 `disabled` prop 等效,降色 + 不可 focus)。
+- `disabled` — 落到真 disabled chrome(`effectiveDisabled`,2026-06-12 修:mode='disabled' 直傳〔如 `<Field mode="disabled">` cascade〕與 `disabled` prop 等效,降色 + 不可 focus)。DataTable cell 無 disabled 態(已廢除);cell 非編輯態 = `view` 純展示。
 
 CheckboxGroup 是純 layout primitive — **不**持有 group-level selection state(無 `value` / `defaultValue` / `onValueChange`)。每個 `<Checkbox>` child 各自管自己的 `checked` / `defaultChecked` / `onCheckedChange`;CheckboxGroup 只透過 `CheckboxGroupContext` 告知 child「你在 group 裡」(保留各自 label)。
 
+### 表單驗證接線(useFormValidation v1 邊界)
+
+Checkbox 值走 `onCheckedChange`(非 value/onChange 型控件),接 `useFormValidation`(`../Field/form-validation.spec.md`)時用 **`setFieldValue` 自接、不經 `getInputProps`**。這是該 spec「v1 邊界」誠實記載的已知限制:**無自動 blur 驗證 / 邊改邊清 error**(該層 timing 只覆蓋 value/onChange 型控件)—— Checkbox 值變更後由 consumer 於 `setFieldValue` 後自行 re-validate,或隨 submit 全驗。**error 視覺不受此限制影響**:`Field invalid` context 是 engine-agnostic 的,紅框 + `FieldError` 照常呈現;`<Field>` 錯誤群組化見 field.spec.md。
+
 ---
 
 ## 群組模式(CheckboxGroup)
@@ -336,6 +344,7 @@ Horizontal 需 `gap-4` 因 row 的 py 不擴散到左右。
 - `../RadioGroup/radio-group.spec.md` — Radio 的 group 容器 + 結構對稱 reciprocal
 - `../SelectionControl/selection-item.spec.md` — Checkbox / Radio 共用的 SelectionItem 佈局 primitive（本 spec 的 Clamp 政策為其 SSOT）
 - `../Field/field-controls.spec.md` — Field Control 共用規則
+- `../Field/form-validation.spec.md` — 表單驗證引擎;Checkbox 用 `setFieldValue` 自接的 v1 邊界見「Controlled / Uncontrolled API → 表單驗證接線」
 
 ## A11y 預設
 

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

@@ -13,7 +13,7 @@ const meta: Meta<typeof Checkbox> = {
 export default meta
 type Story = StoryObj<typeof Checkbox>
 
-// @story-trait-rationale: pre-existing trait gaps tracked separately; this PR scope = add Modes story with display card.
+// @story-trait-rationale: pre-existing trait gaps tracked separately; this PR scope = add Modes story with view card.
 /* ── 四模式 ── */
 export const Modes: Story = {
   name: '四模式',
@@ -24,9 +24,9 @@ export const Modes: Story = {
         <Checkbox defaultChecked aria-label="同意條款(edit mode demo)" />
       </div>
       <div>
-        <h3 className="text-body font-bold text-foreground mb-2">display</h3>
-        <Checkbox mode="display" checked />
-        <p className="text-caption text-fg-muted mt-1">純視覺 glyph（勾/叉 icon，Check/X）；語意由 context（如 DataTable 表頭 + 行標籤）提供，display 不暴露獨立 aria-label。需螢幕報讀器可讀的勾選請用 edit / readonly 模式。</p>
+        <h3 className="text-body font-bold text-foreground mb-2">view</h3>
+        <Checkbox mode="view" checked />
+        <p className="text-caption text-fg-muted mt-1">純視覺 glyph（勾/叉 icon，Check/X）；語意由 context（如 DataTable 表頭 + 行標籤）提供，view 不暴露獨立 aria-label。需螢幕報讀器可讀的勾選請用 edit / readonly 模式。</p>
       </div>
       <div>
         <h3 className="text-body font-bold text-foreground mb-2">readonly</h3>