@qijenchen/design-system 0.1.0-beta.13 → 0.1.0-beta.130

package/src/components/Button/button.tsx

@@ -6,7 +6,7 @@ import { cva, type VariantProps } from 'class-variance-authority'
 import { CircularProgress } from '@/design-system/components/CircularProgress/circular-progress'
 import type { LucideIcon } from 'lucide-react'
 import { cn } from '@/lib/utils'
-import { useFieldContext } from '@/design-system/components/Field/field-context'
+import { useResolvedFieldSize } from '@/design-system/components/Field/field-context'
 import { Tooltip, TooltipContent, TooltipTrigger } from '@/design-system/components/Tooltip/tooltip'
 
 /**
@@ -20,7 +20,7 @@ import { Tooltip, TooltipContent, TooltipTrigger } from '@/design-system/compone
  *   link       外觀像連結的按鈕（本質仍是 button）
  *
  * ── danger prop ──
- *   danger     套用在任何 variant 上，將顏色改為危險色（紅色）
+ *   danger     套用危險色（紅色）；僅 primary / secondary / text 支援（tertiary / link 不支援，見 spec 禁止事項）
  *
  *   <Button variant="primary" danger>永久刪除</Button>        → 紅底白字（立即不可逆）
  *   <Button variant="secondary" danger>移至垃圾桶</Button>    → 紅框紅字（點下去還可反悔）
@@ -30,7 +30,7 @@ import { Tooltip, TooltipContent, TooltipTrigger } from '@/design-system/compone
  *   僅 secondary / tertiary / text 三個 variant 支援 toggle 視覺：
  *     - secondary + pressed → primary-subtle 底、primary 字、透明邊框
  *     - tertiary  + pressed → primary-subtle 底、primary 字、透明邊框（同 secondary 按下視覺）
- *     - text      + pressed → neutral-selected 底，hover 反向變淺，:active 深一階
+ *     - text      + pressed → primary-subtle 底、primary 字、透明邊框（預設 pressedTone='emphasis'，同 secondary/tertiary 按下視覺）；pressedTone='neutral' 時才走 neutral-selected 灰底
  *   primary / link 傳入 pressed 無視覺效果（語意不符）
  *
  * ── Sizes（預設 md）──
@@ -193,6 +193,8 @@ const buttonVariants = cva(
           // aria-pressed fallback(Radix overlay trigger override data-state 時仍生效)
           'aria-pressed:bg-primary-subtle aria-pressed:text-primary aria-pressed:border-transparent',
           'aria-pressed:hover:text-primary-hover',
+          // 2026-07-07 補齊第三階:fallback 分支與 data-[state=on] 分支同拼寫(選中之上按壓 = active 階)
+          'aria-pressed:active:text-primary-active',
         ],
       },
       // neutral tone:灰底(neutral-selected family)— sidebar/contextual nav pressed
@@ -211,7 +213,9 @@ const buttonVariants = cva(
       },
     ],
     defaultVariants: {
-      variant: 'primary',
+      // labeled 預設 = tertiary(2026-06-06 從 primary 改;iconOnly 預設 = text,由 resolvedVariant 注入)。
+      // 真正預設邏輯在元件內 resolvedVariant(相對指法,免行號漂移);此 cva default 供直接 buttonVariants() 呼叫者一致。
+      variant: 'tertiary',
       size: 'md',
       pressedTone: 'emphasis',
     },
@@ -219,11 +223,12 @@ const buttonVariants = cva(
 )
 
 // ── ButtonGroup Context ──────────────────────────────────────────────────────
-// ButtonGroup provides this context; Button reads it for fullWidth injection.
-// Context lives here (not in button-group.tsx) so there is no circular import.
+// ButtonGroup 提供此 context;Button 讀取它注入 fullWidth。
+// Context 放本檔(不放 button-group.tsx)以避免循環 import。
 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']
@@ -244,8 +249,8 @@ export interface ButtonProps
    * 按鈕視覺強調等級。
    * `destructive` / `ghost` 為 shadcn 內部 compat，請勿在應用程式碼中直接使用。
    */
-  variant?: 'primary' | 'secondary' | 'tertiary' | 'text' | 'link' | (string & {})
-  /** 套用危險色（紅色）。可與任何 variant 組合使用。 */
+  variant?: 'primary' | 'secondary' | 'tertiary' | 'text' | 'link'
+  /** 套用危險色（紅色）。僅 primary / secondary / text 支援（tertiary / link 不支援，見 spec 禁止事項）。 */
   danger?: boolean
   /**
    * Toggle 按下狀態（持續 on/off）。設定時 Button 變為 toggle：
@@ -291,7 +296,7 @@ export interface ButtonProps
    * 自動套用:
    * - `variant="text"`(強制 override 其他 variant)
    * - `iconOnly=true`(強制)
-   * - Icon 色 override:`fg-muted` → hover `foreground`(跟 Inline Action dismiss 視覺一致)
+   * - Icon 色 override:`fg-muted` → hover `fg-secondary`(跟 Inline Action dismiss 視覺一致)
    *
    * 典型 case:Dialog / Sheet / Popover / Alert / Toast / Coachmark 的 **chrome corner close X**
    * (action group region — corner 可多 action,close 左側加 Separator + refresh / share 等)。
@@ -301,7 +306,7 @@ export interface ButtonProps
    * - Clear → 欄位清空,用 Inline Action
    * - Remove → collection 移除,用一般 Button / Inline Action
    *
-   * 詳見 button.spec.md「Dismiss 視覺類」段 + patterns/element-anatomy/item-anatomy.spec.md
+   * 詳見 button.spec.md「Dismiss 視覺類」段 + patterns/element-anatomy/inline-action.spec.md
    * 「Dismiss canonical — X close only」段。
    */
   dismiss?: boolean
@@ -311,16 +316,6 @@ export interface ButtonProps
   fullWidth?: boolean
 }
 
-/**
- * Icon-only padding — calc `(field-height - icon-size) / 2` per size。
- *
- * 設計:startIcon 到左邊距離 = padding = `(height - icon) / 2`。
- * 純 icon-only 時 width = 2*padding + icon = height → **自然正方形**,不需要 aspect-square。
- * 有 suffix(badge / endIcon)時 width = 2*pad + icon + gap + suffix > height → **自然長方形**。
- * StartIcon 到左邊距離始終不變,形狀自動適應內容。
- *
- * 用 CSS var 讓 density 切換時 padding 自動跟著算(field-height 會變)。
- */
 // IconOnly 用 padding-free + aspect-square + flex-center 的 Polaris/Atlassian idiom
 // (M17 SSOT 必可傳播 — 取代 4 個 size 的 magic-number 公式):
 //   - aspect-square 鎖 width=height(來自 h-field-X)
@@ -350,18 +345,18 @@ const Button = React.forwardRef<HTMLButtonElement, ButtonProps>(
       loading = false,
       fullWidth = false,
       pressed,
+      pressedTone, // 2026-06-05 fix(deep-audit P0):原漏 destructure → 落入 ...props 噴到 DOM + 永遠用 cva default
       children,
       disabled,
       ...props
     },
     ref
   ) => {
-    // ── FieldContext：在 Field 內時自動讀 size，讓 Button 跟 Input 同高 ──
-    const fieldCtx = useFieldContext?.()
-    const resolvedSize = size ?? (fieldCtx?.size as typeof size) ?? 'md'
+    // ── FieldContext：在 Field 內自動讀 size，讓 Button 跟 Input 同高(SSOT:useResolvedFieldSize)──
+    const resolvedSize = useResolvedFieldSize(size, 'md')
 
     // ── Dismiss 視覺類 override(2026-04-22 cross-implementation dimming canonical) ──
-    // dismiss=true 強制:variant="text" + iconOnly=true + icon 色弱化(fg-muted → hover foreground)
+    // dismiss=true 強制:variant="text" + iconOnly=true + icon 色弱化(fg-muted → hover fg-secondary)
     // 跟 Inline Action dismiss 視覺一致。詳見 button.spec.md「Dismiss 視覺類」。
     const resolvedIconOnly = iconOnly || dismiss
 
@@ -378,7 +373,7 @@ const Button = React.forwardRef<HTMLButtonElement, ButtonProps>(
 
     // 2026-05-23 deep-audit Phase A.4 Decision 1(user verbatim「決策ㄧ照你建議做」):dev-warn `iconOnly + (endIcon|badge)` 並用。
     // Spec SSOT:button.spec.md「iconOnly 嚴格定義為『只有一個 icon,正方形』,不可與 endIcon 或 badge 並用」。
-    // 例外:overlayBadge 跟 iconOnly 並用 canonical(L372 反向 warn 已 cover)。
+    // 例外:overlayBadge 跟 iconOnly 並用 canonical(上方 overlayBadge 反向 warn 已 cover;相對指法,免行號漂移)。
     // 不擋 image canonical「icon + 下拉指示 = 不加 iconOnly + startIcon + endIcon + aria-label」(那 case iconOnly=false 不 trigger)。
     if (process.env.NODE_ENV !== 'production' && iconOnly && (EndIcon !== undefined || badge != null)) {
       // eslint-disable-next-line no-console
@@ -390,14 +385,29 @@ const Button = React.forwardRef<HTMLButtonElement, ButtonProps>(
     // shadcn compat:AlertDialog、Toast 等元件內部會傳入這些 alias,
     // 在此靜默轉換,不暴露到型別或自動完成。
     // dismiss=true 強制 variant=text(dismiss canonical);override 其他 variant 傳入。
+    // 2026-06-06 預設 emphasis 改低(對齊世界級:MUI 預設 text / Ant 預設 default / Polaris 低 emphasis —
+    // 預設 primary CTA 是 outlier)。labeled 無 variant → `tertiary`(中性外框,清楚可點性,再按重要程度升 primary);
+    // iconOnly 無 variant → `text`(toolbar ghost,對齊 action-bar.spec.md「純動作工具/低重量輔助 → text」+
+    // Material 3「icon-only = no fill」)。**CTA 必 explicit `variant="primary"`**(不靠預設)。dismiss 仍強制 text。
     const resolvedVariant: InternalVariant =
       dismiss ? 'text' :
       (variantProp as string) === 'destructive' ? 'primary' :
       (variantProp as string) === 'ghost'        ? 'text'    :
-      (variantProp as InternalVariant) ?? 'primary'
+      (variantProp as InternalVariant) ?? (iconOnly ? 'text' : 'tertiary')
 
     const resolvedDanger = dangerProp || (variantProp as string) === 'destructive'
 
+    // Dev-mode warning:danger 僅 primary / secondary / text 有 compoundVariant。
+    // tertiary / link + danger 無匹配 compound → **靜默渲染成一般 tertiary / link**(灰、無紅色
+    // danger 視覺)— consumer 可能出「不紅的刪除鍵」而不自知。Spec SSOT:button.spec.md
+    // 「禁止事項」danger 條(2026-07-14 deep-audit 補 warn,對齊既有 overlayBadge / iconOnly warn pattern)。
+    if (process.env.NODE_ENV !== 'production' && resolvedDanger && (resolvedVariant === 'tertiary' || resolvedVariant === 'link')) {
+      // eslint-disable-next-line no-console
+      console.warn(
+        `[DS Button] \`danger\` 不支援 variant="${resolvedVariant}"(無對應 compoundVariant,會靜默渲染成一般 ${resolvedVariant},無紅色 danger 視覺)。危險操作請改用 primary(立即不可逆)/ secondary(可反悔)/ text(低度)。SSOT:button.spec.md「禁止事項」danger 條。`
+      )
+    }
+
     // ButtonGroup context：vertical group 自動注入 fullWidth
     const groupCtx = React.useContext(ButtonGroupContext)
     const resolvedFullWidth = fullWidth || !!groupCtx.fullWidth
@@ -415,8 +425,9 @@ const Button = React.forwardRef<HTMLButtonElement, ButtonProps>(
 
     // Toggle 狀態：pressed 定義時自動寫入 aria-pressed + data-state。
     // 未定義時不寫入任何 toggle 屬性（按鈕為一般 action button）。
-    // 樣式由 cva 的 data-[state=on] 分支套用——secondary/tertiary 走 primary-subtle，
-    // text 走 neutral-selected family；primary/link 不定義 on 分支，傳入無效果。
+    // 樣式由 cva data-[state=on] compoundVariants（variant × pressedTone）套用——
+    // secondary/tertiary/text 預設 pressedTone='emphasis' 走 primary-subtle，
+    // pressedTone='neutral' 才走 neutral-selected family；primary/link 不定義 on 分支，傳入無效果。
     const toggleAttrs =
       pressed === undefined
         ? {}
@@ -429,27 +440,13 @@ const Button = React.forwardRef<HTMLButtonElement, ButtonProps>(
     const unboundedAttr =
       resolvedVariant === 'text' || dismiss ? { 'data-unbounded': 'true' } : {}
 
-    const buttonEl = (
-      <Comp
-        className={cn(
-          buttonVariants({ variant: resolvedVariant, danger: resolvedDanger, size: resolvedSize, className }),
-          // iconOnly 鐵律:padding-free + aspect-square + flex-center (Polaris idiom)
-          // 0 magic-number 0 公式自動正方形。詳 ICON_ONLY_BASE rationale。
-          resolvedIconOnly && ICON_ONLY_BASE,
-          // Dismiss 視覺弱化:override Button text variant 預設 foreground 為 fg-muted → hover foreground
-          // 跟 Inline Action dismiss 視覺一致(cross-implementation dimming canonical)
-          dismiss && 'text-fg-muted hover:text-foreground',
-          resolvedFullWidth && 'w-full',
-        )}
-        ref={ref}
-        type="button"
-        disabled={disabled || loading}
-        aria-busy={loading || undefined}
-        aria-label={ariaLabel}
-        {...toggleAttrs}
-        {...unboundedAttr}
-        {...restProps}
-      >
+    // Native path 內部結構:[loading spinner | startIcon(+overlayBadge)] [label] [badge + endIcon]。
+    // asChild 時**不渲染**(2026-07-04 fix):Radix Slot 規範 children 必為單一 element
+    // (React.Children.only)— 內部多 expression children 變 array 必 runtime throw;
+    // asChild 分支只 render consumer child,內容由 consumer 自帶。
+    // 詳 CLAUDE.md 失敗記憶索引「asChild ? Slot : Native 內部 JSX 仍渲染多 children」條。
+    const nativeChildren = (
+      <>
         {loading ? (
           <CircularProgress size={iconSize} className="text-current" />
         ) : StartIcon ? (
@@ -481,6 +478,56 @@ const Button = React.forwardRef<HTMLButtonElement, ButtonProps>(
             {EndIcon && <EndIcon size={iconSize} aria-hidden />}
           </span>
         )}
+      </>
+    )
+
+    const sharedClassName = cn(
+      buttonVariants({ variant: resolvedVariant, danger: resolvedDanger, size: resolvedSize, pressedTone, className }),
+      // iconOnly 鐵律:padding-free + aspect-square + flex-center (Polaris idiom)
+      // 0 magic-number 0 公式自動正方形。詳 ICON_ONLY_BASE rationale。
+      resolvedIconOnly && ICON_ONLY_BASE,
+      // Dismiss 視覺弱化:override Button text variant 預設 foreground 為 fg-muted → hover fg-secondary
+      // 跟 Inline Action dismiss 視覺一致(cross-implementation dimming canonical)
+      // 弱化 icon hover 一階(item-anatomy.tsx ItemInlineActionButton 同階梯 SSOT)
+      dismiss && 'text-fg-muted hover:text-fg-secondary',
+      resolvedFullWidth && 'w-full',
+    )
+
+    // 2026-07-05 D4 修:asChild 原 silently drop loading/disabled 語意(無 aria-busy/aria-disabled/
+    // click guard → <a> loading 期間可重複點擊)。補 ARIA(任何 element 合法;aria-disabled 自動點亮
+    // cva 既有視覺)+ functional guard(APG aria-disabled 模式:語意+視覺由元件、功能阻斷由 guard)。
+    const { onClick: slotConsumerOnClick, ...slotRest } = restProps as typeof restProps & { onClick?: React.MouseEventHandler<HTMLElement> }
+    const buttonEl = asChild ? (
+      // Slot 分支:children 必為單一 consumer element(React.Children.only),
+      // 內部 slot(loading/startIcon/badge)不渲染;不硬塞 type/disabled(consumer child 可能是 <a>)。
+      <Comp
+        className={sharedClassName}
+        ref={ref}
+        aria-label={ariaLabel}
+        aria-busy={loading || undefined}
+        aria-disabled={disabled || loading || undefined}
+        onClick={disabled || loading
+          ? (e: React.MouseEvent<HTMLElement>) => { e.preventDefault(); e.stopPropagation() }
+          : slotConsumerOnClick}
+        {...toggleAttrs}
+        {...unboundedAttr}
+        {...slotRest}
+      >
+        {children}
+      </Comp>
+    ) : (
+      <Comp
+        className={sharedClassName}
+        ref={ref}
+        type="button"
+        disabled={disabled || loading}
+        aria-busy={loading || undefined}
+        aria-label={ariaLabel}
+        {...toggleAttrs}
+        {...unboundedAttr}
+        {...restProps}
+      >
+        {nativeChildren}
       </Comp>
     )
 
@@ -521,18 +568,25 @@ export const buttonMeta = {
     link: { purpose: '內文連結(inline reading)' },
   },
   sizes: {
-    xs: { fieldHeight: 24, iconSize: 16, typography: 'body' },
+    xs: { fieldHeight: 24, iconSize: 16, typography: 'caption' },
     sm: { fieldHeight: 28, iconSize: 16, typography: 'body' },
     md: { fieldHeight: 32, iconSize: 16, typography: 'body' },
-    lg: { fieldHeight: 40, iconSize: 20, typography: 'body-lg' },
+    lg: { fieldHeight: 36, iconSize: 20, typography: 'body-lg' },
   },
-  states: ['default', 'hover', 'active', 'focus-visible', 'disabled'],
+  // 'pressed' = toggle on 持續態(data-[state=on],emphasis 淡藍底/neutral 灰底;2026-07-07 meta 詞彙統一補列)
+  // 'loading' = CircularProgress spinner 取代 startIcon + aria-busy + click guard(2026-07-14 deep-audit
+  // 補列,原漏 → auto-compile 生成矩陣缺 loading;對齊 anatomy StateBehavior Loading 行 + tsx loading 分支)
+  states: ['default', 'hover', 'active', 'pressed', 'loading', 'focus-visible', 'disabled'],
   tokens: {
-    bg: ['--primary', '--primary-hover', '--primary-active', '--bg-disabled'],
-    fg: ['--on-emphasis', '--fg-disabled'],
+    // 2026-07-04 audit 補齊:原只列 primary variant 家族;按 buttonVariants cva 真實 class 補
+    // secondary/tertiary/text/link/danger 消費的 token(auto-compile token 矩陣依此)。
+    // 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', '--primary-hover', '--primary-active', '--error', '--error-hover', '--error-active'],
     ring: ['--ring'],
   },
-  defaultVariant: 'primary',
+  defaultVariant: 'tertiary',  // 2026-06-10 修 stale:對齊 cva defaultVariants(2026-06-06 labeled 預設改 tertiary,meta 漏同步)
   defaultSize: 'md',
 } as const
 

package/src/components/Button/index.ts

@@ -0,0 +1,6 @@
+// AUTO-GENERATED by scripts/gen-component-indexes.mjs — DO NOT EDIT MANUALLY.
+// Re-export pattern enables package.json exports map subpath:
+//   import { ... } from '@qijenchen/design-system/{components,patterns}/<Dir>'
+// Regenerate: node scripts/gen-component-indexes.mjs
+export * from './button'
+export * from './button-group'

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

@@ -0,0 +1,237 @@
+// @anatomy-exempt: anatomy specs / token 對照表格用 raw <table>,非業務資料表。業務資料表才用 <DataTable>。
+// @anatomy-rationale:
+//   SizeMatrix N/A — Calendar 是單一 month canvas，沒有 size variant。
+//   StateBehavior 已存在(today / outside month / hover / event tile 等狀態
+//     已由 StateBehavior 5. 涵蓋)。
+import type { Meta, StoryObj } from '@storybook/react'
+import { expect, userEvent, within } from '@storybook/test'
+import { Calendar, type CalendarEvent } from './calendar'
+import { CATEGORICAL_HUES } from '@/design-system/tokens/categorical-color'
+import { H3, Desc, Td, Th } from '@/design-system/stories-helpers/anatomy/anatomy-utils'
+
+const meta: Meta<typeof Calendar> = {
+  title: 'Design System/Components/Calendar/設計規格',
+  component: Calendar,
+  parameters: { layout: 'fullscreen' },
+}
+export default meta
+
+type Story = StoryObj<typeof Calendar>
+
+// 視覺基線同時釘住顯示月與 today SSOT，避免跨月/換日造成 snapshot 漂移。
+const now = new Date(2026, 6, 15)
+const thisMonth = now.getFullYear() + '-' + String(now.getMonth() + 1).padStart(2, '0')
+
+const sampleEvents: CalendarEvent[] = [
+  { id: 'e1', title: 'Design review', start: `${thisMonth}-05`, end: `${thisMonth}-05`, color: 'blue' },
+  { id: 'e2', title: 'Sprint planning', start: `${thisMonth}-08`, end: `${thisMonth}-08`, color: 'blue' },
+  { id: 'e3', title: 'Release deadline', start: `${thisMonth}-12`, end: `${thisMonth}-12`, color: 'red' },
+  { id: 'e4', title: 'Q review', start: `${thisMonth}-18`, end: `${thisMonth}-18`, color: 'green' },
+  { id: 'e5', title: 'Alex vacation', start: `${thisMonth}-20`, end: `${thisMonth}-22`, color: 'yellow', allDay: true },
+]
+
+// Keep dynamic-token documentation readable without presenting Tailwind's
+// source scanner with an invalid literal arbitrary-value candidate.
+const TIMED_EVENT_CLASS_GUIDE = [
+  'bg-[var(--color-', '{color}', '-1)] · text-[var(--color-', '{color}',
+  '-7)] · rounded-md · px-1.5 py-0.5 · text-caption · truncate',
+].join('')
+const ALL_DAY_EVENT_CLASS_GUIDE = [
+  '同上 + border-l-[3px] border-[var(--color-', '{color}', '-6)] · font-medium',
+].join('')
+const HOVER_EVENT_CLASS_GUIDE = [
+  'hover:bg-[var(--color-', '{color}', '-2)]',
+].join('')
+
+// ── 1. 元件總覽 ────────────────────────────────────────────────────────────────
+export const Overview: Story = {
+  name: '元件總覽',
+  render: () => (
+    <div className="h-screen p-4 bg-canvas">
+      <Calendar events={sampleEvents} defaultReferenceDate={now} today={now} />
+    </div>
+  ),
+}
+
+// ── 2. 元件檢閱器 ────────────────────────────────────────────────────────────
+export const Inspector: Story = {
+  name: '元件檢閱器',
+  parameters: {
+    docs: { description: { story: '右側 Controls 切換 month canvas 的已實作 props；未實作的週/日與 size API 不暴露。' } },
+    layout: 'fullscreen',
+  },
+  args: {
+    weekStartsOn: 0,
+    locale: 'en-US',
+    events: sampleEvents,
+    today: now,
+  },
+  argTypes: {
+    weekStartsOn: { control: 'radio', options: [0, 1] },
+    locale: { control: 'select', options: ['en-US', 'zh-TW', 'ja-JP'] },
+    events: { control: 'object' },
+  },
+  render: (args) => (
+    <div className="h-screen p-4 bg-canvas">
+      <Calendar defaultReferenceDate={now} {...args} />
+    </div>
+  ),
+}
+
+// ── 3. 色彩對照表(事件 color 類別 + Cell / Event tile token)─────────────────────
+// 跳過 4. SizeMatrix：元件沒有 size API。
+export const ColorMatrix: Story = {
+  name: '色彩對照表',
+  render: () => {
+    const colorEvents: CalendarEvent[] = CATEGORICAL_HUES.map((c, i) => ({
+      id: `c-${c}`,
+      title: `${c} category`,
+      start: `${thisMonth}-${String(i + 2).padStart(2, '0')}`,
+      end: `${thisMonth}-${String(i + 2).padStart(2, '0')}`,
+      color: c,
+    }))
+    return (
+      <div className="p-4 bg-canvas flex flex-col gap-10">
+        <div>
+          <H3>事件類別色</H3>
+          <Desc>
+            事件顏色用 12 種類別色,和 Tag / Avatar 共用同一套色盤
+            (blue / green / deep-orange / yellow / red / orange / amber / lime / turquoise / indigo / purple / magenta)。
+            顏色代表「這是哪一類事件」(同一個團隊 / 同一個專案),不是嚴重程度。每個色名對應一個色相,紅與橘各自獨立、可清楚區分。
+          </Desc>
+          <div className="h-[560px]">
+            <Calendar events={colorEvents} defaultReferenceDate={now} today={now} />
+          </div>
+        </div>
+
+        <div>
+          <H3>Cell 視覺 token</H3>
+          <Desc>月 view cell 的狀態色彩。Cell 最小高度 min-h-28 容納日期 header + 3 event tile,隨容器高度伸縮;7 欄等分。</Desc>
+          <div className="overflow-x-auto">
+            <table className="text-caption border-collapse">
+              <thead>
+                <tr>
+                  <Th>區塊</Th>
+                  <Th>Token / Class</Th>
+                  <Th>說明</Th>
+                </tr>
+              </thead>
+              <tbody>
+                <tr>
+                  <Td>Cell 高度</Td>
+                  <Td mono>min-h-28(112px)</Td>
+                  <Td>容納 header + 3 event tile 的下限,隨容器高度伸縮(root h-full + grid flex-1)</Td>
+                </tr>
+                <tr>
+                  <Td>Cell 寬度</Td>
+                  <Td mono>1fr × 7</Td>
+                  <Td>週 7 欄等分</Td>
+                </tr>
+                <tr>
+                  <Td>日期 header</Td>
+                  <Td mono>flex items-start justify-end · text-body · font-medium</Td>
+                  <Td>右上角數字,wrapper 無固定高度(由內容 + cell min-h-28 決定),對齊 Google Calendar</Td>
+                </tr>
+                <tr>
+                  <Td>Today cell(日期數字)</Td>
+                  <Td mono>bg-info · text-on-emphasis · rounded-full · min-w-6 h-6 px-2 · text-body font-medium</Td>
+                  <Td>info-filled pill,固定 h-6 + min-w-6 做 pill badge(對齊 Google Calendar today pill)</Td>
+                </tr>
+                <tr>
+                  <Td>Outside day cell</Td>
+                  <Td mono>text-fg-disabled · bg-muted</Td>
+                  <Td>上/下月溢出日期弱化 + 背景略暗</Td>
+                </tr>
+                <tr>
+                  <Td>Hover cell</Td>
+                  <Td mono>hover:bg-neutral-hover</Td>
+                  <Td>提示可點擊新增入口</Td>
+                </tr>
+                <tr>
+                  <Td>Weekend cell(後續增量)</Td>
+                  <Td mono>bg-muted</Td>
+                  <Td>目前不提供 weekend prop / isWeekend 樣式；未實作能力不預佔 API</Td>
+                </tr>
+              </tbody>
+            </table>
+          </div>
+        </div>
+
+        <div>
+          <H3>Event tile 視覺 token</H3>
+          <Desc>事件 tile 的色彩由 event `color` 欄位決定,bg / text 走 subtle / text tier。</Desc>
+          <div className="overflow-x-auto">
+            <table className="text-caption border-collapse">
+              <thead>
+                <tr>
+                  <Th>情境</Th>
+                  <Th>Token / Class</Th>
+                  <Th>說明</Th>
+                </tr>
+              </thead>
+              <tbody>
+                <tr>
+                  <Td>一般 event(timed)</Td>
+                  <Td mono>{TIMED_EVENT_CLASS_GUIDE}</Td>
+                  <Td>單行 tile,color 依事件類別(12 categorical 色相,消費 categorical-color SSOT,與 Tag / Avatar 共用)。對齊 Tag 色階(step-1 淺底 / step-7 文字)。色名必須 1:1 對應 <code>--color-{'{hue}'}-*</code>,零 offset(2026-06-04 修:原 red / orange 都誤接 deep-orange,改後 red→`--color-red-*`、orange→`--color-orange-*` 各自獨立)</Td>
+                </tr>
+                <tr>
+                  <Td>All-day event</Td>
+                  <Td mono>{ALL_DAY_EVENT_CLASS_GUIDE}</Td>
+                  <Td>2026-06-01 補實作:淡底 + 左側實心 accent 條 + medium,排序在有時間事件之前(cell 頂端);多日全天事件以日精度 filter 在每個涵蓋日各顯示一條</Td>
+                </tr>
+                <tr>
+                  <Td>Hover tile</Td>
+                  <Td mono>{HOVER_EVENT_CLASS_GUIDE}</Td>
+                  <Td>同色深一階表示可點擊</Td>
+                </tr>
+                <tr>
+                  <Td>超出 tile 限制</Td>
+                  <Td mono>「+N more」純文字(text-fg-muted)</Td>
+                  <Td>每格最多顯示 3 筆事件,超出顯示「+N more」弱化計數文字,目前不可點擊(展開列表為後續增量)</Td>
+                </tr>
+              </tbody>
+            </table>
+          </div>
+        </div>
+      </div>
+    )
+  },
+}
+
+// ── 5. 狀態行為 ─────────────────────────────────────────────────────────────
+export const StateBehavior: Story = {
+  name: '狀態行為',
+  render: () => (
+    <div className="h-screen p-4 bg-canvas">
+      <div className="mb-2 text-body text-fg-muted space-y-1">
+        <div>• <b>today</b> cell:date 數字加 `bg-info text-on-emphasis rounded-full` 圓</div>
+        <div>• <b>outside month</b>:前後月日期數字走 `text-fg-disabled`,cell 底色 `bg-muted`</div>
+        <div>• <b>多事件 cell</b>:超出 3 則的 event 顯示「+N more」</div>
+        <div>• <b>event hover</b>:tile 切同色深一階 `hover:bg-{`{color}`}-2`(如 blue → `--color-blue-2`)+ `cursor-pointer`</div>
+        <div>• <b>empty cell</b>:無事件保持純底色,點擊觸發 onDateClick</div>
+      </div>
+      <Calendar events={sampleEvents} defaultReferenceDate={now} today={now} />
+    </div>
+  ),
+  play: async ({ canvasElement }) => {
+    const canvas = within(canvasElement)
+    await expect(canvas.getByRole('button', { name: /^2026-07-15,/ })).toHaveClass('bg-info')
+    await userEvent.click(canvas.getByRole('button', { name: '下個月' }))
+    await expect(canvas.getByRole('heading', { level: 2 })).toHaveTextContent('August 2026')
+    await userEvent.click(canvas.getByRole('button', { name: '今天' }))
+    await expect(canvas.getByRole('heading', { level: 2 })).toHaveTextContent('July 2026')
+  },
+}
+
+// ── Accessibility ─────────────────────────────────────────────────────────
+// 2026-05-17 ship per audit Dim 13(story-rules.md 6-canonical 含 Accessibility)
+export const Accessibility = {
+  name: '無障礙與鍵盤',
+  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 行為(實作現況)  :\n\n- Tab — 逐一 focus 每格的日期數字按鈕與其中的事件 tile(cell 為非互動 gridcell 容器,滑鼠點空白處等同點日期)\n- Enter / Space — 日期數字按鈕觸發 `onDateClick`;事件 tile 觸發 `onEventClick`\n- Toolbar 的 ◀ / 今天 / ▶ 為標準可聚焦控件,Tab 可達\n\n  Keyboard tech debt  :\n\n- ↑/↓/←/→ 在日期格間 roving 移動、PageUp/Down 切月、Shift+PageUp/Down 切年\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>
+  ),
+}