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

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

@@ -141,27 +141,16 @@ Checkbox/Radio 控件本體不畫 label——label 由 `SelectionItem` 承載:
 
 **icon / avatar prefix(2026-06-12 M30 轉發)**:一級 `icon`(LucideIcon)/ `avatar`(AvatarData)props 直接轉發 `SelectionItem` 既有三槽 canonical 的 prefix 槽(互斥;尺寸與 inline/block 對齊規則 SSOT = `selection-item.spec.md`「3-slot 結構」+ selection-item.tsx jsDoc)。RadioGroupItem 同。
 
-對齊機制：
-1. 外層 `<div>` 設 `text-body` / `text-body-lg`（建立 line-height context）
-2. 控件包在 `h-[1lh]` 的容器內（容器高度 = 一行文字高度）
-3. `flex items-center`（控件在文字行高內垂直置中）
-4. 外層 `flex items-start`（多行時控件對齊第一行）
-
-`1lh` 在 `<div>` 上正常繼承，改字體自動重算。
+對齊機制(`text-body[-lg]` 建立 `1lh` context / 控件包 `h-[1lh]` 容器垂直置中 / 外層 `items-start` 多行對齊第一行)**SSOT → `../SelectionControl/selection-item.spec.md`「結構 / 字體」**,本 spec 不重述(2026-07-14 收斂原重述段,措辭已現 drift)。
 
 ---
 
 ## SelectionItem 佈局
 
-垂直排列和水平排列共用 `SelectionItem`。
-
-| | 垂直 | 水平 |
-|---|---|---|
-| Item 間距 | 0（padding 處理） | 16px（gap-4，見 Orientation 段） |
-| Item padding | `py = (field-height - 1lh) / 2` | 同左 |
-| Label ↔ Description | 2px（`--item-gap-label-desc-reading` / `-reading-lg`,size-aware） | 同左 |
-| 單行高度 | = field-height（對齊 Input） | 同左 |
-| 多行高度 | padding 維持不變，總高度 = `1lh × line-count + py × 2` | — |
+垂直排列和水平排列共用 `SelectionItem`,各值 SSOT 不重述:
+- **Item padding / 單行高度 = field-height / 多行撐高公式** → `selection-item.spec.md`「Padding 公式」(`py = (field-height - 1lh) / 2`)
+- **Label ↔ Description 2px gap** → `item-anatomy.spec.md`「Label ↔ Desc 間距」(`--item-gap-label-desc-reading[-lg]`,size-aware)
+- **Item 間距**(垂直 0 / 水平 `gap-4`)→ 下方「群組模式」zero-gap 鐵律 + Orientation 段
 
 ---
 
@@ -226,9 +215,9 @@ Checkbox / Radio 在 form 內承載的常常是:
 
 典型場景：SelectMenu 的「全選」checkbox——當部分選項被勾選時顯示 indeterminate。
 
-Indeterminate 是由父層邏輯控制的狀態，Checkbox 本身不會自動進入 indeterminate——必須明確傳入 `checked="indeterminate"`。**常見誤解**:「部分子項已選」不可用 disabled + checked 混搭表達——半選是可互動狀態,disabled 是鎖互動,語意不同。
+Indeterminate 是由父層邏輯控制的狀態，Checkbox 本身不會自動進入 indeterminate——必須明確傳入 `checked="indeterminate"`（controlled 與 uncontrolled `defaultChecked="indeterminate"` 皆正確渲染 Minus——圖示切換由 Radix `data-state` CSS 驅動,2026-07-14 修復原「只讀 `props.checked`」的 uncontrolled known-gap）。**常見誤解**:「部分子項已選」不可用 disabled + checked 混搭表達——半選是可互動狀態,disabled 是鎖互動,語意不同。
 
-**狀態切換視覺**(code 真值):unchecked ↔ checked / indeterminate 之間色彩走 `transition-colors` 150ms;Check ↔ Minus 圖示為條件渲染即時 swap,無過渡動畫。
+**狀態切換視覺**(code 真值):unchecked ↔ checked / indeterminate 之間色彩走 `transition-colors` 150ms;Check ↔ Minus 圖示由 `data-state` CSS 即時 swap,無過渡動畫。
 
 ### Radio
 
@@ -255,8 +244,8 @@ Indeterminate 是由父層邏輯控制的狀態，Checkbox 本身不會自動進
 
 `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 同名段):
 - `edit`(預設)— 可勾選的 Checkbox。
-- `display` — **純展示**:渲染 ✓(checked)/ —(其他),非互動、無 input chrome,供 DataTable boolean cell 非編輯態共用。
-- `readonly` — **Field 內(無 inline label)**= `fieldWrapperStyles` readonly 灰框 + ✓/—(與 Input readonly 同一視覺語言,2026-06-12 user 拍板;世界級:Salesforce output ✓ glyph / SAP 靜態文字);**standalone / 有 inline label**(SelectionItem row)= 正常色鎖互動(同下方 Read-only)。
+- `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 中性非紅 = 「否」值非「錯誤」)。
+- `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)。
 
 CheckboxGroup 是純 layout primitive — **不**持有 group-level selection state(無 `value` / `defaultValue` / `onValueChange`)。每個 `<Checkbox>` child 各自管自己的 `checked` / `defaultChecked` / `onCheckedChange`;CheckboxGroup 只透過 `CheckboxGroupContext` 告知 child「你在 group 裡」(保留各自 label)。
@@ -312,12 +301,6 @@ Horizontal 需 `gap-4` 因 row 的 py 不擴散到左右。
 ### 用法範例
 
 ```tsx
-<CheckboxGroup>
-  <Checkbox label="待處理" defaultChecked />
-  <Checkbox label="進行中" defaultChecked />
-  <Checkbox label="已完成" />
-</CheckboxGroup>
-
 <Field orientation="horizontal">
   <FieldLabel>通知方式</FieldLabel>
   <CheckboxGroup orientation="horizontal">
@@ -328,6 +311,8 @@ Horizontal 需 `gap-4` 因 row 的 py 不擴散到左右。
 </Field>
 ```
 
+（垂直 group / defaultChecked 等更多場景 → `checkbox.stories.tsx`）
+
 ---
 
 ## 禁止事項

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

@@ -1,6 +1,8 @@
+// @story-trait-rationale: hasSizes/hasInteractiveStates 由 anatomy.stories.tsx SizeMatrix + StateBehavior
+// owns 完整 trait grid;展示層 States 保留為 compact all-states overview(對齊 Switch 同 Family 檔頭豁免,
+// 2026-07-14 audit Dim 46 補),跟 anatomy focused subsection 不同教學,不另開抽象 Default/AllSizes。
 import type { Meta, StoryObj } from '@storybook/react'
 import { Checkbox } from './checkbox'
-import { SelectionItem } from '@/design-system/components/SelectionControl/selection-item'
 
 const meta: Meta<typeof Checkbox> = {
   title: 'Design System/Components/Checkbox/展示',
@@ -24,7 +26,7 @@ export const Modes: Story = {
       <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（✓ / —）；語意由 context（如 DataTable 表頭 + 行標籤）提供，display 不暴露獨立 aria-label。需螢幕報讀器可讀的勾選請用 edit / readonly 模式。</p>
+        <p className="text-caption text-fg-muted mt-1">純視覺 glyph（勾/叉 icon，Check/X）；語意由 context（如 DataTable 表頭 + 行標籤）提供，display 不暴露獨立 aria-label。需螢幕報讀器可讀的勾選請用 edit / readonly 模式。</p>
       </div>
       <div>
         <h3 className="text-body font-bold text-foreground mb-2">readonly</h3>
@@ -86,9 +88,10 @@ export const VerticalGroup: Story = {
         <div key={size}>
           <p className="text-caption text-fg-muted mb-1">size="{size}"</p>
           <div className="grid">
-            <SelectionItem size={size} control={<Checkbox id={`${size}-a`} size={size} />} label="Electronics" htmlFor={`${size}-a`} />
-            <SelectionItem size={size} control={<Checkbox id={`${size}-b`} size={size} />} label="Furniture" description="桌椅、收納、辦公家具" htmlFor={`${size}-b`} />
-            <SelectionItem size={size} control={<Checkbox id={`${size}-c`} size={size} />} label="Food & Beverage" htmlFor={`${size}-c`} />
+            {/* 公開 API:`<Checkbox label>` 自動包 SelectionItem + wire id/htmlFor(selection-item.spec.md 禁裸用) */}
+            <Checkbox size={size} label="Electronics" />
+            <Checkbox size={size} label="Furniture" description="桌椅、收納、辦公家具" />
+            <Checkbox size={size} label="Food & Beverage" />
           </div>
         </div>
       ))}
@@ -101,9 +104,9 @@ export const Horizontal: Story = {
   name: '水平排列',
   render: () => (
     <div className="flex gap-4 max-w-md">
-      <SelectionItem control={<Checkbox id="h-a" />} label="Electronics" htmlFor="h-a" />
-      <SelectionItem control={<Checkbox id="h-b" />} label="Furniture" htmlFor="h-b" />
-      <SelectionItem control={<Checkbox id="h-c" />} label="Food" htmlFor="h-c" />
+      <Checkbox label="Electronics" />
+      <Checkbox label="Furniture" />
+      <Checkbox label="Food" />
     </div>
   ),
 }

package/src/components/Checkbox/checkbox.tsx

@@ -9,6 +9,7 @@ import type { FieldMode, FieldVariant } from "@/design-system/components/Field/f
 import { useFieldContext, useResolvedFieldDisabled, useResolvedFieldMode, useResolvedFieldSize } from "@/design-system/components/Field/field-context"
 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"
 import type { LucideIcon } from "lucide-react"
 import type { AvatarData } from "@/design-system/components/Avatar/avatar"
 import { CheckboxGroupContext } from "./checkbox-group"
@@ -110,7 +111,7 @@ export interface CheckboxProps
   /**
    * Field mode(2026-05-05 Phase B3 align):
    *   edit     — 一般可互動 checkbox(預設)
-   *   display  — **純展示**:渲染 ✓ / —(無互動 primitive、無 input chrome);
+   *   display  — **純展示**:渲染 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:降色 + 鎖互動
@@ -208,16 +209,19 @@ const Checkbox = React.forwardRef<
     } = props
 
     // ── mode='display'(下移至所有 hooks 之後,per #35 Rules of Hooks)──────────
-    // 純展示模式:無互動 primitive、渲染 ✓ / —(checked=true → ✓ / 其他 → —)。取代 BooleanDisplay。
+    // 純展示模式:無互動 primitive、渲染 Check / X icon(true=勾 / false=叉,中性 foreground 色)。
+    // boolean 值展示符號 SSOT = SelectionControl/boolean-value.tsx(勾/叉 icon + 中性色 + M22 世界級對照)。取代 BooleanDisplay。
     if (resolvedMode === 'display') {
       const isChecked = checkedProp === true
-      return isChecked
-        ? <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>
+      return (
+        <span {...restDomProps} ref={ref as React.Ref<HTMLSpanElement>} className="inline-flex">
+          <BooleanValueIcon checked={isChecked} size={resolvedBoxSize} />
+        </span>
+      )
     }
 
-    // ── mode='readonly' in Field(2026-06-12 user 拍板「灰框 + ✓/—」)─────────────
-    // Field 內 readonly boolean = readonly 灰框 chrome + display 同款值語言 ✓/—。
+    // ── mode='readonly' in Field(2026-06-12 拍板「灰框 + 勾/叉」;2026-07-09 ✓/— glyph → Check/X icon)─
+    // Field 內 readonly boolean = readonly 灰框 chrome + display 同款值語言(勾/叉 icon)。
     // 灰框消費 fieldWrapperStyles 同一 cva = 與 Input readonly 字面同源(SSOT,改一處全動)。
     // 理由:同一張 readonly 表單裡文字控件有 bg-readonly 灰框鎖定訊號,boolean 保留全彩
     // 控件會誤導「仍可操作」(世界級 0/4 用原樣鎖互動:Salesforce=✓ 靜態 glyph /
@@ -244,7 +248,7 @@ const Checkbox = React.forwardRef<
             className,
           )}
         >
-          {isChecked ? <span className="text-foreground">✓</span> : <span className="text-fg-muted">—</span>}
+          <BooleanValueIcon checked={isChecked} size={boxSize} />
         </div>
       )
     }
@@ -273,11 +277,12 @@ const Checkbox = React.forwardRef<
           props.onClick?.(event)
         }}
       >
-        <CheckboxPrimitive.Indicator className="grid place-content-center text-current">
-          {props.checked === 'indeterminate'
-            ? <Minus style={{ width: iconPx, height: iconPx }} strokeWidth={iconStrokeWidth} />
-            : <Check style={{ width: iconPx, height: iconPx }} strokeWidth={iconStrokeWidth} />
-          }
+        {/* 圖示切換走 Radix data-state(CSS),非 props.checked(JS)—— uncontrolled
+            defaultChecked="indeterminate" 時 props.checked=undefined,JS 判斷會錯渲 Check;
+            data-state 涵蓋 controlled/uncontrolled 全部轉換(Radix 為 SSOT)。 */}
+        <CheckboxPrimitive.Indicator className="group/indicator grid place-content-center text-current">
+          <Minus className="hidden group-data-[state=indeterminate]/indicator:block" style={{ width: iconPx, height: iconPx }} strokeWidth={iconStrokeWidth} />
+          <Check className="hidden group-data-[state=checked]/indicator:block" style={{ width: iconPx, height: iconPx }} strokeWidth={iconStrokeWidth} />
         </CheckboxPrimitive.Indicator>
       </CheckboxPrimitive.Root>
     )

package/src/components/Chip/chip.anatomy.stories.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.
 // @anatomy-exempt: anatomy specs / token 對照表格用 raw <table>,非業務資料表。業務資料表才用 <DataTable>。
 import type { Meta, StoryObj } from '@storybook/react'
+import { useState } from 'react'
 import { Star, Tag as TagIcon } from 'lucide-react'
 import { Chip, ChipGroup } from './chip'
 import { H3, Desc, Td, Th, TokenCell, Swatch } from '@/design-system/stories-helpers/anatomy/anatomy-utils'
@@ -108,23 +109,31 @@ export const Inspector: InspectorStory = {
       description: 'overflow 行為:wrap(換行,預設)/ scroll(fade mask)/ menu(收入 Dropdown)',
     },
   },
-  render: (args) => {
-    const groupProps =
-      args.type === 'multiple'
-        ? ({ type: 'multiple' as const, defaultValue: args.selected ? ['featured'] : [] })
-        : ({ type: 'single' as const, defaultValue: args.selected ? 'featured' : '' })
-    return (
-      <div className="max-w-md border border-border rounded-md p-3">
-        <ChipGroup layout={args.layout} {...groupProps}>
-          <Chip value="featured" startIcon={args.withStartIcon ? Star : undefined}>精選</Chip>
-          <Chip value="new" startIcon={args.withStartIcon ? TagIcon : undefined}>新品</Chip>
-          <Chip value="sale">特價</Chip>
-          <Chip value="limited">限量</Chip>
-          <Chip value="discontinued" disabled={args.disabled}>下架</Chip>
-        </ChipGroup>
-      </div>
-    )
-  },
+  // 2026-07-14 dim-26 修:原 mount-only defaultValue — Controls 切 selected 不生效,且
+  // layout=menu 違反 chip.spec.md:190「menu 模式需要 controlled ChipGroup(value + onValueChange)」
+  // (chip.tsx:298 runtime warn)。改 controlled inner(repo anatomy 慣例 useState Inner)+
+  // key remount 讓 Controls 切換 type / selected 即時反映。
+  render: (args) => <InspectorControlled key={`${args.type}-${args.selected}`} {...args} />,
+}
+
+const InspectorControlled = (args: InspectorArgs) => {
+  const [multiValue, setMultiValue] = useState<string[]>(args.selected ? ['featured'] : [])
+  const [singleValue, setSingleValue] = useState<string>(args.selected ? 'featured' : '')
+  const groupProps =
+    args.type === 'multiple'
+      ? ({ type: 'multiple' as const, value: multiValue, onValueChange: setMultiValue })
+      : ({ type: 'single' as const, value: singleValue, onValueChange: setSingleValue })
+  return (
+    <div className="max-w-md border border-border rounded-md p-3">
+      <ChipGroup layout={args.layout} {...groupProps}>
+        <Chip value="featured" startIcon={args.withStartIcon ? Star : undefined}>精選</Chip>
+        <Chip value="new" startIcon={args.withStartIcon ? TagIcon : undefined}>新品</Chip>
+        <Chip value="sale">特價</Chip>
+        <Chip value="limited">限量</Chip>
+        <Chip value="discontinued" disabled={args.disabled}>下架</Chip>
+      </ChipGroup>
+    </div>
+  )
 }
 
 export const ColorMatrix: Story = {
@@ -366,6 +375,19 @@ export const StateBehavior: Story = {
   ),
 }
 
+// menu layout 必為 controlled(spec 禁止事項:uncontrolled menu 無法同步狀態);故獨立成元件用 useState
+const MENU_LAYOUT_OPTIONS = ['電子產品', '家具', '食品', '服飾', '書籍', '運動', '玩具', '美妝', '家電']
+function MenuLayoutExample() {
+  const [value, setValue] = useState<string[]>(['電子產品'])
+  return (
+    <ChipGroup type="multiple" layout="menu" value={value} onValueChange={(v) => setValue(v as string[])}>
+      {MENU_LAYOUT_OPTIONS.map((label) => (
+        <Chip key={label} value={label}>{label}</Chip>
+      ))}
+    </ChipGroup>
+  )
+}
+
 export const LayoutMatrix: Story = {
   name: '排版（換行 vs 捲動 vs 選單）',
   render: () => (
@@ -374,7 +396,8 @@ export const LayoutMatrix: Story = {
         <H3>wrap(預設)</H3>
         <Desc>超出容器自然換行。適合空間充裕的 filter panel。</Desc>
         <div className="max-w-md border border-border rounded-md p-3">
-          <ChipGroup type="multiple" defaultValue={['a']}>
+          {/* defaultValue 必對應真實 chip value(chip value=中文 label);原 'a' 無對應 → 初始 0 選取的死示範 */}
+          <ChipGroup type="multiple" defaultValue={['電子產品']}>
             {['電子產品', '家具', '食品', '服飾', '書籍', '運動', '玩具', '美妝', '家電'].map(label => (
               <Chip key={label} value={label}>{label}</Chip>
             ))}
@@ -386,7 +409,8 @@ export const LayoutMatrix: Story = {
         <H3>scroll</H3>
         <Desc>水平捲動 + fade mask(共用 `horizontal-overflow` pattern,跟 Tabs 一致)。適合空間受限但希望保留 chip 視覺的場景。</Desc>
         <div className="max-w-md border border-border rounded-md p-3">
-          <ChipGroup type="multiple" layout="scroll" defaultValue={['a']}>
+          {/* defaultValue 必對應真實 chip value(chip value=中文 label);原 'a' 無對應 → 初始 0 選取的死示範 */}
+          <ChipGroup type="multiple" layout="scroll" defaultValue={['電子產品']}>
             {['電子產品', '家具', '食品', '服飾', '書籍', '運動', '玩具', '美妝', '家電'].map(label => (
               <Chip key={label} value={label}>{label}</Chip>
             ))}
@@ -398,11 +422,7 @@ export const LayoutMatrix: Story = {
         <H3>menu(show-all navigator dropdown)</H3>
         <Desc>所有 chip 留在單行水平捲動容器,全部可見可點(不隱藏);dropdown 永遠列出全部 chip 供快速勾選(對齊 Chrome tab dropdown / VS Code editor tabs)。適合 chip 很多但使用者不常切後面的場景。</Desc>
         <div className="max-w-md border border-border rounded-md p-3">
-          <ChipGroup type="multiple" layout="menu" defaultValue={['a']}>
-            {['電子產品', '家具', '食品', '服飾', '書籍', '運動', '玩具', '美妝', '家電'].map(label => (
-              <Chip key={label} value={label}>{label}</Chip>
-            ))}
-          </ChipGroup>
+          <MenuLayoutExample />
         </div>
       </div>
     </div>

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

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

package/src/components/Chip/chip.spec.md

@@ -2,7 +2,8 @@
 component: Chip
 family: 3
 variants: {}
-sizes: {}
+sizes:
+  sm: { when: "單一尺寸(h-field-sm 28/32 依 density、icon 16、text-body)— 對齊 chip.tsx componentMeta" }
 traits:
   - hasInteractiveStates
 benchmark:
@@ -201,11 +202,11 @@ Chip 的 overflow 處理有三種模式：
 - ❌ 把 Chip 塞進 Field 當 form control——規模語意不對，用 SegmentedControl
 - ❌ Menu 模式搭配 uncontrolled（只給 `defaultValue`）——menu items 無法同步狀態，TS 不擋但 runtime 會看到 menu 勾選失效
 
-## 為何無 Inspector
+## 設計規格 story 結構
 
-Chip 決策維度是「selection 行為(single / multi / menu)」× layout(連體 / 間隔)× overflow——已在 `SelectionMatrix` / `LayoutMatrix` 兩張結構矩陣覆蓋。互動 Inspector 無法呈現 selection model 的差異(需要 side-by-side 對照)。
+Chip 決策維度是「selection type(`single` / `multiple`)」×「layout(`wrap` / `scroll` / `menu`)」× overflow——由 `Inspector`(互動切換 type / selected / disabled / startIcon / layout)、`SelectionMatrix`、`LayoutMatrix` 三者覆蓋。
 
-ColorMatrix 已建:展示 default / hover / selected / disabled 四狀態的 bg / border / text / icon token 對照,採 pill-canonical 規則(`--primary-hover` 同步染 border + text,bg 維持 surface 不染色),對齊 SegmentedControl / Tabs 未選 hover。
+ColorMatrix:展示 default / hover / selected / disabled 四狀態的 bg / border / text / icon token 對照,採 pill-設計準則:selected 時 `--primary` 同時染 border + text(selected × hover 深化為 `--primary-hover`),底色維持 `--surface` 不染色,對齊 SegmentedControl / Tabs。
 
 ---
 

package/src/components/Chip/chip.tsx

@@ -80,7 +80,11 @@ const chipVariants = cva(
 )
 
 export interface ChipProps
-  extends React.ComponentPropsWithoutRef<typeof ToggleGroupPrimitive.Item> {
+  // 2026-07-14 dim-9 修:Omit 'asChild' — chip.spec.md 禁止事項明載「❌ 用 asChild——不支援」,
+  // 且內部固定渲染 {icon}{label}{suffix} 多 children 結構,asChild(Radix Slot 要求單一
+  // element child)會 runtime throw(CLAUDE.md 失敗記憶「asChild ? Slot : Native」條)。
+  // 型別層 Omit 讓誤用在編譯期失敗,對齊 spec-vs-type 一致。
+  extends Omit<React.ComponentPropsWithoutRef<typeof ToggleGroupPrimitive.Item>, 'asChild'> {
   /** 左側 icon（LucideIcon），最多一個 */
   startIcon?: LucideIcon
   /** 右側 badge（通常是計數指示器）*/

package/src/components/CircularProgress/circular-progress.principles.stories.tsx

@@ -1,6 +1,6 @@
 // @principles-rationale: Merged WhenNotToUse + CircularVsSkeletonRule into a single
 // `UsageGuidance` story (3 sections — 何時用 / 何時不用 / vs 近親) per 2026-04-26 user
-// mandate. IndeterminateVsDeterminateRule / UsageScenarioRule / SizeMatchContextRule
+// mandate. IndeterminateVsDeterminateRule / ConsumptionScenarioRule / SizeMatchContextRule
 // kept as separate principles.
 import React from 'react'
 import type { Meta, StoryObj } from '@storybook/react'
@@ -52,7 +52,7 @@ export const UsageGuidance: Story = {
       <Section title="何時用">
         <p className="text-caption text-fg-muted max-w-[720px] leading-relaxed mb-6">
           CircularProgress 用於「使用者觸發 async 動作後的即時回饋」與「全頁 / 浮層的 loading 訊號」。
-          詳細情境 → UsageScenarioRule(Button loading / Inline 表單驗證 / Empty 全頁 overlay)。
+          詳細情境 → 「常見消費場景」story(Button loading / Inline 表單驗證 / Empty 全頁 overlay)。
         </p>
       </Section>
 
@@ -184,8 +184,11 @@ export const IndeterminateVsDeterminateRule: Story = {
   ),
 }
 
-export const UsageScenarioRule: Story = {
-  name: '使用情境',
+// 2026-07-14 rename per audit Dim 14:原 name「使用情境」與同檔 UsageGuidance「使用指引」/
+// SizeMatchContextRule「尺寸對應使用情境」語意撞名,讀者難分。本 story 教的是「CircularProgress
+// 內嵌於 Button / Input / Empty 的常見消費場景」,name 改為可區辨的人話。
+export const ConsumptionScenarioRule: Story = {
+  name: '常見消費場景（內嵌於 Button / Input / Empty）',
   render: () => (
     <div>
       <Rule

package/src/components/CircularProgress/circular-progress.spec.md

@@ -191,7 +191,7 @@ Track 色鎖 `var(--secondary)`(= neutral-3,與 ProgressBar track 一致)。
 
 ## 視覺與幾何鐵律
 
-- **正方形不可妥協**:`style={{ width: size, height: size }}` 強制。本體絕不加 margin / padding
+- **正方形**:外層 span `style={{ width: size, height: size }}` + 內層 `<svg width height>` 雙重鎖尺寸——svg 顯式 width / height 兜底,即使 consumer 傳 `style` 覆寫外層 span,圓形圖形仍維持正方比例。本體絕不加 margin / padding
 - **SVG 雙 circle**:track(`var(--secondary)`) + arc(`currentColor`),stroke-linecap round,rotate -90deg 從 12 點起始
 - **strokeWidth 動態 scale**:`Math.max(2, Math.round(size / 10))` 維持跨尺寸視覺比例(逐值結果由公式推導,不另列舉)
 - **Indeterminate arc**:固定 25%(`INDETERMINATE_ARC_RATIO=0.25`),外層 `animate-spin` 旋轉整個 span(Material 流派)
@@ -223,8 +223,8 @@ CircularProgress 是**最薄的 circular progress primitive**,刻意避免多維
 
 - **無 Inspector**:variant 只有 value 有無(indeterminate / determinate 兩態),互動切換式 Inspector 可展的決策點少。`UsageInButton` / `UsageInline` 已覆蓋真實 consumer context
 - **ColorMatrix N/A**:arc 預設固定 `text-info`(consumer 傳 `className="text-current"` 才繼承 host,見上方「顏色策略」),track 固定 `var(--secondary)`,無 own variant × state 色彩組合可 matrix 對照。色彩不隨狀態變色(完成 / 失敗由 consumer swap 整個元件),`UsageInButton` / `UsageInline` 真實 context 已示範,獨立 ColorMatrix story 會是冗餘
-- **SizeMatrix N/A — 無 separate SizeMatrix story**:size 是自由 number(非 sm/md/lg tier),由 Button / Input 等 consumer 容器內部依規則程式化縮放,`UsageInButton` / `UsageInline` 真實 context 已涵蓋 16 / 24 / 32 / 48 等常用值的行為差異,比靜態 matrix 更貼近消費情境
-- **無 StateBehavior**:無 hover / focus / active,唯一「狀態」是 value 變化(已在 Determinate story 動態演示)
+- **SizeMatrix N/A — 無 separate SizeMatrix story**:size 是自由 number(非 sm/md/lg tier),由 Button / Input 等 consumer 容器內部依規則程式化縮放,`UsageInButton` / `UsageInline` 真實 context 已涵蓋 16(cell / upload row)/ 20(Input lg)/ 24(inline 預設)等常用值的行為差異,比靜態 matrix 更貼近消費情境(48 的全頁 overlay 尺寸見展示層 `FullScreenOverlay`)
+- **無 StateBehavior**:無 hover / focus / active,唯一「狀態」是 value 變化(determinate 靜態值示範於 `UsageInline`「Determinate inline」段;元件不含 timer / RAF 動態演示,進度值由 consumer 傳入驅動)
 
 對應 anatomy story:`Overview` + `UsageInButton` + `UsageInline` + `Accessibility`(2026-05-17 per story-rules 6-canonical)。缺 canonical 5 多數項的 rationale 即本段。
 

package/src/components/CircularProgress/circular-progress.stories.tsx

@@ -15,8 +15,8 @@ import { DataTable } from '@/design-system/components/DataTable/data-table'
  * - 無 value → indeterminate 旋轉(取代舊 Spinner 用法)
  * - 有 value → determinate arc + track(可量化進度,如 inline 上傳 %)
  *
- * 範例均對標世界級產品的真實使用場景(Stripe 付款送出、GitHub PR merging、
- * Figma 雲端同步、Notion workspace loading、Google Drive 上傳)。
+ * 範例均對標世界級產品的真實使用場景(GitHub 儲存庫搜尋、檔案上傳佇列、
+ * 雲端同步狀態表格、workspace 切換載入)。
  * 設計規則詳見 `circular-progress.spec.md`。
  */
 

package/src/components/Coachmark/coachmark.anatomy.stories.tsx

@@ -335,7 +335,7 @@ export const StateBehavior: Story = {
         <div>
           <H3>Focus / Esc / Click-outside(繼承 Popover)</H3>
           <Desc>
-            Coachmark 大部分行為繼承 Popover(Radix),但刻意抑制 CTA 自動 focus(onOpenAutoFocus preventDefault 後 focus content 容器本身)——避免使用者還在讀 body 時 CTA 被 auto-focus 偷觸發,Tab 第一下即達第一個 CTA(焦點不停 trigger,否則 non-modal focus-outside dismiss 會誤關閉浮層;2026-07-05 D4 修);關閉時 return to trigger;Esc 關閉浮層(透過 Radix onOpenChange,效果等同退出,但不觸發 onSkip callback);預設 non-modal,使用者可忽略繼續主流程。
+            Coachmark 大部分互動行為繼承 Popover。開啟時焦點落在內容區、不會自動跳到按鈕,避免你還在讀內容時就誤觸推進——按 Tab 才移到按鈕(單步、無標題列時一下即達推進鍵;有標題列會先到右上的關閉 X,多步則先經「上一步 / 略過」)。關閉後焦點回到觸發元素;按 Esc 關閉(效果等同退出,但不會觸發 onSkip);預設不鎖背景,你可以忽略它繼續原本的操作。技術細節(Radix API 名稱與修正紀錄)見 `coachmark.spec.md`「A11y 預設」段與 coachmark.tsx。
           </Desc>
         </div>
       </div>
@@ -350,7 +350,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">{"詳 `coachmark.spec.md` 「A11y 預設」段。摘要:\n\n-   焦點管理  :刻意抑制 CTA 自動 focus(onOpenAutoFocus preventDefault 後 focus content 容器本身)——避免 user 還在讀 body 時 CTA 被偷觸發;Tab 第一下即達第一個 CTA(焦點不停 trigger,否則 non-modal focus-outside dismiss 會誤關閉;2026-07-05 D4 修);關閉時 return to trigger\n-   Esc 關閉  :預設啟用——user 按 Esc 透過 Radix onOpenChange 關閉浮層(效果等同退出),但不觸發 onSkip callback(Esc 是「關閉浮層」非「明確 skip」)\n-   ARIA  :trigger 自動  aria-expanded  /  aria-controls ,content  role=\"dialog\" (Radix 預設)\n-   Step 計數 tabular-nums  :螢幕閱讀器讀「2 of 3」語意清楚"}</p>
+      <p className="whitespace-pre-line">{"詳 `coachmark.spec.md` 「A11y 預設」段。摘要:\n\n-   焦點管理  :開啟時焦點落在內容區、不自動跳到按鈕,避免你還在讀內容時誤觸;按 Tab 才移到按鈕(單步、無標題列時一下即達推進鍵;有標題列 / 多步會先到關閉 X / 上一步 / 略過);關閉後焦點回到觸發元素\n-   Esc 關閉  :預設啟用——user 按 Esc 透過 Radix onOpenChange 關閉浮層(效果等同退出),但不觸發 onSkip callback(Esc 是「關閉浮層」非「明確 skip」)\n-   ARIA  :trigger 自動  aria-expanded  /  aria-controls ,content  role=\"dialog\" (Radix 預設)\n-   Step 計數 tabular-nums  :螢幕閱讀器讀「2 of 3」語意清楚"}</p>
     </div>
   ),
 }

package/src/components/Coachmark/coachmark.principles.stories.tsx

@@ -279,7 +279,8 @@ export const MultiStepBestPracticesRule: Story = {
       >
         <Coachmark
           open
-          image={<MediaGradient from="var(--color-blue-6)" to="var(--color-cyan-6)" icon={FolderPlus} label="Workspace" />}
+          // 2026-07-14 Dim 55:--color-cyan-6 不存在(12 hue 無 cyan)→ 改既有 turquoise
+          image={<MediaGradient from="var(--color-blue-6)" to="var(--color-turquoise-6)" icon={FolderPlus} label="Workspace" />}
           title="建立你的第一個 Workspace"
           description="Workspace 是團隊協作的主要空間,所有專案、文件、成員都在這裡集中管理。"
           step={{ current: 1, total: 3 }}

package/src/components/Coachmark/coachmark.spec.md

@@ -100,7 +100,7 @@ SSOT 規則:**Coachmark 不重寫 Popover 的任何視覺 token**,只加自己
 
 ## Props 結構
 
-- `children` — trigger anchor(用 Popover asChild 定位)
+- `children` — trigger anchor(用 Popover asChild 定位)。**必為單一 anchor element**(型別 `ReactElement`;asChild Slot 契約,對齊 Popover / Tooltip / HoverCard——多元素 / fragment / string 會 `React.Children.only` runtime 炸,型別收緊讓錯誤提前到 compile 期)
 - `kind` — `'tips' | 'new-features' | ReactNode`;有值則渲染 Header(tour-level title)
 - `image` — ReactNode 媒體區;不傳則不渲染
 - `mediaRatio` — Media 長寬比(預設 `16/9`,見「Media 區規則」)
@@ -153,7 +153,7 @@ const steps = [
 
 **設計建議**:
 - **≤ 5 步**——超過使用者疲勞,改用靜態 onboarding 頁面
-- **Skip 只在第一步提供**——進到 step 2+ 後 Skip 自動隱藏(canonical,見上方「CTA 語義表」);想退出走 Esc / header Close 按鈕
+- **Skip 在傳 `onPrev` 時隱藏**——由 `onPrev` 是否存在決定(非讀 `step.current`):有 `onPrev`(通常為第 2+ 步)即自動隱藏 Skip;單步驟也不顯示(canonical,見上方「CTA 語義表」)。想退出走 Esc / header Close 按鈕
 - **最後一步 `isLastStep`**——Next → Done 語意切換,讓使用者知道「這是最後一步」
 - **每步 anchor 到對應 feature**——不 anchor 或 anchor 到無關元素 = 失去「教 X 怎麼用」的精準性
 - **Multi-step 建議傳 `kind="tips"` 或 `"new-features"`**——header 讓使用者一眼看出 tour 性質 / 何時結束的預期
@@ -165,8 +165,8 @@ const steps = [
 Previous(可選)→ Skip(可選)→ Next / Done。對齊 Ant Tour / Intercom convention: <!-- @benchmark-unverified: see frontmatter benchmark list for canonical DS source URL -->
 
 - **Previous 最左**——回到上一步(負方向,視覺權重低)
-- **Skip 中間**——exit escape hatch,tertiary 不搶焦點;**僅第一步顯示**(見 CTA 語義表)
-- **Next / Done 最右**——推進主動線(正方向,primary 視覺權重高);**Coachmark 抑制 CTA 自動 focus**(`onOpenAutoFocus` preventDefault 後 focus content 容器本身,非第一個 CTA),避免使用者還在讀 body 時按 Enter 誤推進;想推進者按一下 Tab 即達 CTA 再 Enter(焦點已在 content 內,不觸發 non-modal focus-outside dismiss;2026-07-05 D4 修)
+- **Skip 中間**——exit escape hatch,tertiary 不搶焦點;**未傳 `onPrev` 時顯示**(有 `onPrev` 或單步則隱藏,見 CTA 語義表)
+- **Next / Done 最右**——推進主動線(正方向,primary 視覺權重高);**Coachmark 抑制 CTA 自動 focus**(`onOpenAutoFocus` preventDefault 後 focus content 容器本身,非第一個 CTA),避免使用者還在讀 body 時按 Enter 誤推進;想推進者按 Tab 即達 CTA 再 Enter(單步無 header 一下即達;有 header 或多步時 Close X / Previous / Skip 在推進 CTA 前,需多按幾下;焦點已在 content 內,不觸發 non-modal focus-outside dismiss;2026-07-05 D4 修)
 
 第 1 步通常無 Previous;最後步 Next 改 Done(由 `isLastStep` 控制)。單步驟 CTA 改 `'知道了'`。
 
@@ -203,7 +203,7 @@ Previous(可選)→ Skip(可選)→ Next / Done。對齊 Ant Tour / Intercom con
 
 ## A11y 預設
 
-- **焦點管理**:Coachmark **刻意抑制 CTA 自動 focus**(`onOpenAutoFocus` preventDefault 後 focus content 容器本身,對齊 `dialog.tsx` 的 `?? content` fallback canonical)——避免使用者還在讀 body 時 CTA 被 auto-focus 偷觸發(焦點在容器上按 Enter 無動作);Tab 第一下即達 content 內第一個 CTA。焦點**不**停在 trigger:non-modal Popover 焦點在 content 樹外時按 Tab 會觸發 focus-outside dismiss 誤關閉浮層,CTA 鍵盤永遠到不了(2026-07-05 D4 修;dismiss 機制詳 `popover.spec.md` A11y 段)。關閉時焦點 return to trigger(Radix 預設 `onCloseAutoFocus`,未 override)
+- **焦點管理**:Coachmark **刻意抑制 CTA 自動 focus**(`onOpenAutoFocus` preventDefault 後 focus content 容器本身,對齊 `dialog.tsx` 的 `?? content` fallback canonical)——避免使用者還在讀 body 時 CTA 被 auto-focus 偷觸發(焦點在容器上按 Enter 無動作);按 Tab 移到 content 內第一個 tabbable(單步無 header 即推進 CTA;有 header 會先到 PopoverHeader 右上 Close X,多步則先經 Previous / Skip)。焦點**不**停在 trigger:non-modal Popover 焦點在 content 樹外時按 Tab 會觸發 focus-outside dismiss 誤關閉浮層,CTA 鍵盤永遠到不了(2026-07-05 D4 修;dismiss 機制詳 `popover.spec.md` A11y 段)。關閉時焦點 return to trigger(Radix 預設 `onCloseAutoFocus`,未 override)
 - **Esc 關閉**:預設啟用——user 按 Esc 透過 Radix `onOpenChange` 關閉浮層(效果等同退出),**不觸發 `onSkip` callback**(Esc 是「關閉浮層」非「明確 skip」;若需區分 Esc-退出 vs Skip-按鈕 的追蹤事件,consumer 在 Skip 按鈕的 `onSkip` 處理)
 - **ARIA**:trigger 自動 `aria-expanded` / `aria-controls`,content `role="dialog"`(Radix 預設)
 - **Step 計數 tabular-nums**:螢幕閱讀器讀「2 of 3」語意清楚

package/src/components/Coachmark/coachmark.stories.tsx

@@ -46,7 +46,9 @@ const tourSteps = [
   {
     anchor: '建立 Workspace',
     icon: FolderPlus,
-    media: { from: 'var(--color-blue-6)', to: 'var(--color-cyan-6)', label: 'Workspace' },
+    // 2026-07-14 audit Dim 55:原 `--color-cyan-6` 不存在(primitive 12 hue 無 cyan)→ 漸層
+    // 靜默斷掉。改用既有 turquoise(oklch hue 196,最接近 cyan 的 primitive)。
+    media: { from: 'var(--color-blue-6)', to: 'var(--color-turquoise-6)', label: 'Workspace' },
     title: '建立你的第一個 Workspace',
     description: 'Workspace 是團隊協作的主要空間,所有專案、文件、成員都在這裡集中管理。',
   },

package/src/components/Coachmark/coachmark.tsx

@@ -36,7 +36,9 @@ import { OVERLAY_SIDE_OFFSET } from '@/design-system/tokens/elevation/overlay-ge
  *      同樣規則)。CTA = `isLastStep ? 'Done' : 'Next'`
  *   4. **抑制 CTA 自動 focus,焦點落在 content 容器** — `onOpenAutoFocus` preventDefault
  *      後 focus content 容器本身(非第一個 CTA),避免使用者還在讀 body 時按 Enter 誤推進;
- *      Tab 第一下即達 content 內第一個 CTA。焦點不可停在 trigger:non-modal Popover 下
+ *      按 Tab 才移到 content 內按鈕:**單步無 header** 時第一個 tabbable 即推進 CTA;**有 header
+ *      (kind / headerTitle 會渲 PopoverHeader 右上 Close X)或多步** 時 DOM 順序上 Close X /
+ *      Previous / Skip 在推進 CTA 之前,需多按幾下 Tab。焦點不可停在 trigger:non-modal Popover 下
  *      焦點在 DismissableLayer 外按 Tab 會觸發 focus-outside dismiss 誤關閉
  *      (2026-07-05 D4;對齊 dialog.tsx handleOpenAutoFocus `?? content` fallback,見 spec「A11y 預設」)。
  *
@@ -56,8 +58,13 @@ export interface CoachmarkProps extends Omit<React.HTMLAttributes<HTMLDivElement
   /** 預設打開(uncontrolled initial state)— 2026-05-15 audit Dim 26 V1 fix per user verbatim「A:1」approval */
   defaultOpen?: boolean
   onOpenChange?: (open: boolean) => void
-  /** 觸發 anchor 元素。通常傳 trigger element;Coachmark 浮層會定位於此 */
-  children: React.ReactNode
+  /**
+   * 觸發 anchor 元素——**必為單一 React element**(內部走 `<PopoverTrigger asChild>` =
+   * Radix Slot 契約;傳 string / fragment / 多元素會 `React.Children.only` runtime 炸,
+   * 見 CLAUDE.md 失敗記憶索引「asChild + Slot」條)。與 Popover / Tooltip / HoverCard
+   * 同一錨點契約;型別收緊為 ReactElement 讓契約在 compile 期顯現。
+   */
+  children: React.ReactElement
   /** 頂部 media 區(圖片 / illustration / video 等);不傳則無 media */
   image?: React.ReactNode
   /**

package/src/components/Combobox/combobox.anatomy.stories.tsx

@@ -291,9 +291,9 @@ export const Overview = {
             <span className="text-[11px] text-fg-secondary font-medium">空值</span>
             <div className="inline-flex items-center border-2 border-dashed border-primary/30 rounded-md px-3 py-2.5 gap-2">
               <span className="rounded px-2 py-1 text-[11px] font-mono border border-dashed"
-                style={{ borderColor: 'var(--info)', backgroundColor: 'var(--info-subtle)', color: 'var(--info)' }}>— (em dash)</span>
+                style={{ borderColor: 'var(--info)', backgroundColor: 'var(--info-subtle)', color: 'var(--info)' }}>- (hyphen)</span>
             </div>
-            <span className="text-[10px] text-fg-muted font-mono">text-fg-muted</span>
+            <span className="text-[10px] text-fg-muted font-mono">text-foreground</span>
           </div>
         </div>
       </div>