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

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>

package/src/components/Checkbox/checkbox.tsx

@@ -7,6 +7,7 @@ import { cva, type VariantProps } from "class-variance-authority"
 import { cn } from "@/lib/utils"
 import type { FieldMode, FieldVariant } from "@/design-system/components/Field/field-types"
 import { useFieldContext, useResolvedFieldDisabled, useResolvedFieldMode, useResolvedFieldSize } from "@/design-system/components/Field/field-context"
+import { useControllable } from "@/design-system/hooks/use-controllable"
 import { fieldWrapperStyles } from "@/design-system/components/Field/field-wrapper"
 import { SelectionItem } from "@/design-system/components/SelectionControl/selection-item"
 import { BooleanValueIcon } from "@/design-system/components/SelectionControl/boolean-value"
@@ -80,8 +81,13 @@ const checkStrokeWidth: Record<string, number> = { sm: 3, md: 3, lg: 2.5 }
 
 // ── Types ───────────────────────────────────────────────────────────────────
 
+// asChild / children 從公開型別 Omit(2026-07-17 d9i6):Checkbox 有**固定 anatomy** —
+// 內部恆渲染 Indicator(Check / Minus 兩子節點),非 Slot host。若保留 Radix `asChild`,
+// consumer 傳入的元素會被 Radix Slot `React.Children.only` 因多子節點在執行期拋錯(失敗記憶索引
+// 已 codify 此 asChild 多子節點 bug class);`children` 同理會被固定 Indicator 覆蓋。需自訂佈局
+// 請用 `label` / `description` / `icon` / `avatar` 一級 props(內部自動包 SelectionItem)。
 export interface CheckboxProps
-  extends React.ComponentPropsWithoutRef<typeof CheckboxPrimitive.Root>,
+  extends Omit<React.ComponentPropsWithoutRef<typeof CheckboxPrimitive.Root>, 'asChild' | 'children'>,
     VariantProps<typeof checkboxVariants> {
   /**
    * Inline label。提供時 Checkbox 自動透過 SelectionItem 包裝，
@@ -111,7 +117,7 @@ export interface CheckboxProps
   /**
    * Field mode(2026-05-05 Phase B3 align):
    *   edit     — 一般可互動 checkbox(預設)
-   *   display  — **純展示**:渲染 Check / X icon(true=勾 / false=叉,無互動 primitive、無 input chrome);
+   *   view     — **純展示**:渲染 Check / X icon(true=勾 / false=叉,無互動 primitive、無 input chrome);
    *              對齊 Carbon read-only / DataTable boolean cell 場景。取代既有 BooleanDisplay。
    *   readonly — 同 readOnly prop:checkbox 視覺保留 + 鎖互動 + a11y readonly signal
    *   disabled — 同 disabled prop:降色 + 鎖互動
@@ -143,6 +149,13 @@ const Checkbox = React.forwardRef<
       mode,
       // chrome 對 Checkbox 主體無視覺影響(無 input wrapper)— 接收純為 prop 一致性;destructure 防 leak 到 DOM。
       variant: _chrome,
+      // controllable checked triplet(2026-07-17 d26i0):於 wrapper 層取出,交由 useControllable 持有
+      // resolved 值,供 edit / view / readonly 三分支共用。原本 view / readonly 分支各自讀 raw prop →
+      // uncontrolled(只傳 defaultChecked)在 edit 態 toggle 後切 mode 會丟失目前值(Radix 內部狀態
+      // wrapper 讀不到)。移出 props 後 edit 主路徑改由 checked={resolvedChecked} 受控(見下方 rootEl)。
+      checked: checkedProp,
+      defaultChecked: defaultCheckedProp,
+      onCheckedChange,
       id: idProp,
       ...props
     },
@@ -154,7 +167,7 @@ const Checkbox = React.forwardRef<
 
     // Field context:Checkbox 單獨塞進 Field(binary toggle)時,忽略自己的 label 讓 FieldLabel 接管
     // 2026-05-31 #35:hooks(useFieldContext / useContext / useId)必在任何 conditional return 前呼叫(Rules of Hooks)。
-    // 原 mode='display' early return 寫在 hooks 之上 → runtime 切 mode 會 hook count 不一致 crash;已下移至 hooks 後。
+    // 原 mode='view' early return 寫在 hooks 之上 → runtime 切 mode 會 hook count 不一致 crash;已下移至 hooks 後。
     //
     // **例外**:Checkbox 是 CheckboxGroup 的 child 時(multi-select 情境),**每個 checkbox
     // 的 label 是它自己的選項名**,FieldLabel 只是群組名稱 — 此時 label **必須保留**,
@@ -181,7 +194,7 @@ const Checkbox = React.forwardRef<
     const generatedId = React.useId()
     const inputId = idProp ?? (insideGroup ? generatedId : (fieldCtx?.id ?? generatedId))
 
-    // 2026-06-08 SSOT cascade:disabled + mode 經 resolver hook(原 raw prop → <Field disabled>/<Field mode="display"> 漏 cascade)
+    // 2026-06-08 SSOT cascade:disabled + mode 經 resolver hook(原 raw prop → <Field disabled>/<Field mode="view"> 漏 cascade)
     const resolvedDisabled = useResolvedFieldDisabled(disabled)
     const resolvedMode = useResolvedFieldMode({ mode, disabled, readOnly })
     const effectiveReadOnly = readOnly || resolvedMode === 'readonly'
@@ -192,36 +205,74 @@ 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
+    // 2026-07-04 修:view / 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)。
+    // 抽出 Radix 專屬 form props(required/name/value 不可落到裸 span/div),其餘 DOM props 於兩分支
+    // spread 轉發(與 Switch/RadioGroup 同修);edit 主路徑不受影響(rootEl 仍 spread 完整 props)。
+    // (checked/defaultChecked/onCheckedChange 已於上方 top-level destructure 取出交 useControllable;
+    //  asChild/children 已從 CheckboxProps 型別 Omit — 固定 anatomy 非 Slot host,見型別註解。)
     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)──────────
+    // ── Resolved checked SSOT(controlled / uncontrolled dual-mode,2026-07-17 d26i0)──────────
+    // 對齊 Input / Textarea 既有 canonical(field-controls.spec.md「有值判定」:useControllable 內部
+    // resolved value + form.reset bridge)。修 view / readonly 分支原各自讀 raw prop 導致「uncontrolled
+    // 切 mode 丟失目前值」的 dual-mode 缺口。controlled(傳 checked)時 useControllable 純 passthrough,
+    // edit 行為 Δ=0。
+    const isControlled = checkedProp !== undefined
+    const [resolvedChecked, setResolvedChecked] = useControllable<boolean | 'indeterminate'>({
+      value: checkedProp,
+      defaultValue: defaultCheckedProp ?? false,
+    })
+
+    // form.reset() bridge(uncontrolled only):wrapper 取得 controllable 主導後,HTML 標準 reset 不發
+    // 變更事件 → 手動把 resolvedChecked 歸位 defaultChecked(對齊 input.tsx 同名 bridge)。keyed on
+    // resolvedMode:切回 edit 重掛 native Root 時 effect 重跑補掛 listener;view / readonly(Root
+    // unmount)時 innerRef 為 null → early return 不掛。
+    const innerRef = React.useRef<HTMLButtonElement | null>(null)
+    React.useEffect(() => {
+      if (isControlled) return
+      const form = innerRef.current?.form
+      if (!form) return
+      const handleReset = () => setResolvedChecked(defaultCheckedProp ?? false)
+      form.addEventListener('reset', handleReset)
+      return () => form.removeEventListener('reset', handleReset)
+    }, [isControlled, resolvedMode, defaultCheckedProp, setResolvedChecked])
+    // Merge refs(input.tsx setRef idiom):innerRef 供 reset bridge 取 form,同時轉發 forwardRef ref。
+    const setRef = React.useCallback((el: HTMLButtonElement | null) => {
+      innerRef.current = el
+      if (typeof ref === 'function') ref(el)
+      else if (ref) (ref as React.MutableRefObject<HTMLButtonElement | null>).current = el
+    }, [ref])
+
+    // ── mode='view'(下移至所有 hooks 之後,per #35 Rules of Hooks)──────────
     // 純展示模式:無互動 primitive、渲染 Check / X icon(true=勾 / false=叉,中性 foreground 色)。
     // boolean 值展示符號 SSOT = SelectionControl/boolean-value.tsx(勾/叉 icon + 中性色 + M22 世界級對照)。取代 BooleanDisplay。
-    if (resolvedMode === 'display') {
-      const isChecked = checkedProp === true
+    if (resolvedMode === 'view') {
+      const isChecked = resolvedChecked === true
+      // a11y(2026-07-17 d10i2):BooleanValueIcon 帶 aria-hidden → 裸 span 在 a11y tree 無名,
+      // 布林值對螢幕閱讀器完全消失。給 view 容器 role="img" + aria-label 承載值語意(對齊 MUI X
+      // DataGrid boolean cell 的 icon role/label 世界級做法);consumer 若自帶 aria-label 則優先。
+      const viewAriaLabel = (restDomProps as { 'aria-label'?: string })['aria-label'] ?? (isChecked ? '是' : '否')
       return (
-        <span {...restDomProps} ref={ref as React.Ref<HTMLSpanElement>} className="inline-flex">
+        <span
+          {...restDomProps}
+          ref={ref as React.Ref<HTMLSpanElement>}
+          role="img"
+          aria-label={viewAriaLabel}
+          className="inline-flex"
+        >
           <BooleanValueIcon checked={isChecked} size={resolvedBoxSize} />
         </span>
       )
     }
 
     // ── mode='readonly' in Field(2026-06-12 拍板「灰框 + 勾/叉」;2026-07-09 ✓/— glyph → Check/X icon)─
-    // Field 內 readonly boolean = readonly 灰框 chrome + display 同款值語言(勾/叉 icon)。
+    // Field 內 readonly boolean = readonly 灰框 chrome + view 同款值語言(勾/叉 icon)。
     // 灰框消費 fieldWrapperStyles 同一 cva = 與 Input readonly 字面同源(SSOT,改一處全動)。
     // 理由:同一張 readonly 表單裡文字控件有 bg-readonly 灰框鎖定訊號,boolean 保留全彩
     // 控件會誤導「仍可操作」(世界級 0/4 用原樣鎖互動:Salesforce=✓ 靜態 glyph /
@@ -229,7 +280,7 @@ const Checkbox = React.forwardRef<
     // Scope:僅 Field 內且無 inline label(FieldLabel 接管 label 的表單欄位場景);
     // standalone readOnly(settings list / SelectionItem row)維持原樣鎖互動不變。
     if (effectiveReadOnly && insideField && effectiveLabel == null) {
-      const isChecked = (checkedProp ?? defaultCheckedProp) === true
+      const isChecked = resolvedChecked === true
       const boxSize = resolvedBoxSize
       return (
         <div
@@ -256,8 +307,17 @@ const Checkbox = React.forwardRef<
     const rootEl = (
       <CheckboxPrimitive.Root
         id={inputId}
-        ref={ref}
+        ref={setRef}
         disabled={effectiveDisabled}
+        // controllable checked SSOT(2026-07-17 d26i0):Root 受 wrapper resolvedChecked 主導,
+        // onCheckedChange 先同步 wrapper 內部 state 再 forward consumer → uncontrolled(只傳
+        // defaultChecked)toggle 後切 mode(view / readonly)仍保留目前值。controlled(傳 checked)
+        // 時 useControllable 純 passthrough,edit 行為 Δ=0。
+        checked={resolvedChecked}
+        onCheckedChange={(next) => {
+          setResolvedChecked(next)
+          onCheckedChange?.(next)
+        }}
         aria-readonly={effectiveReadOnly || undefined}
         data-readonly={effectiveReadOnly || undefined}
         tabIndex={effectiveReadOnly ? -1 : undefined}