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

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

@@ -0,0 +1,152 @@
+// @principles-rationale: Merged WhenToUse + WhenNotToUse + VsDatePicker into a single
+// `UsageGuidance` story (3 sections) per 2026-04-26 user mandate to consolidate
+// decision-related stories. ColorSemantic + MonthViewOnlyRule kept as separate principles.
+import type { Meta, StoryObj } from '@storybook/react'
+import LinkTo from '@storybook/addon-links/react'
+import { Calendar, type CalendarEvent } from './calendar'
+import { DatePicker } from '@/design-system/components/DatePicker/date-picker'
+import { Field, FieldLabel } from '@/design-system/components/Field/field'
+
+const meta: Meta = {
+  title: 'Design System/Components/Calendar/設計原則',
+  parameters: { layout: 'padded' },
+}
+export default meta
+type Story = StoryObj
+
+// 視覺基線同時釘住顯示月與 today SSOT，避免跨月/換日造成 snapshot 漂移。
+const now = new Date(2026, 6, 15)
+const thisMonth = now.getFullYear() + '-' + String(now.getMonth() + 1).padStart(2, '0')
+
+const Section = ({ title, children }: { title: string; children: React.ReactNode }) => (
+  <section className="mb-12">
+    <h2 className="text-body-lg font-semibold text-foreground mb-3 pb-1 border-b border-divider">{title}</h2>
+    <div>{children}</div>
+  </section>
+)
+
+const Rule: React.FC<{ title: string; note: string; children: React.ReactNode }> = ({ title, note, children }) => (
+  <div className="mb-8 max-w-5xl">
+    <div className="text-body-lg font-medium text-foreground mb-1">{title}</div>
+    <div className="text-body text-fg-secondary mb-3">{note}</div>
+    <div className="rounded-md border border-divider p-4 bg-surface">{children}</div>
+  </div>
+)
+
+export const UsageGuidance: Story = {
+  name: '使用指引',
+  render: () => (
+    <div>
+      <Section title="何時用">
+        <div className="prose prose-sm max-w-prose">
+          <p>適合 Calendar 的真實業務場景(點擊跳轉「展示」頁範例):</p>
+          <ul className="space-y-1">
+            <li>
+              <LinkTo kind="Design System/Components/Calendar/展示" name="團隊行事曆"><span className="text-primary hover:text-primary-hover font-medium cursor-pointer">團隊行事曆</span></LinkTo>
+            </li>
+            <li>
+              <LinkTo kind="Design System/Components/Calendar/展示" name="內容發佈月曆"><span className="text-primary hover:text-primary-hover font-medium cursor-pointer">內容發佈月曆</span></LinkTo>
+            </li>
+            <li>
+              <LinkTo kind="Design System/Components/Calendar/展示" name="空行事曆"><span className="text-primary hover:text-primary-hover font-medium cursor-pointer">空行事曆</span></LinkTo>
+            </li>
+          </ul>
+          <p className="text-fg-muted mt-3">判斷不確定時:對照 spec.md「何時用 / 何時不用」段;若仍不符,改用近親元件(見下方「vs 近親」)。</p>
+        </div>
+      </Section>
+
+      <Section title="何時不用 + 替代">
+        <div className="space-y-4 text-body text-fg-secondary max-w-3xl">
+          <ul className="list-disc pl-5 space-y-2">
+            <li><b>選單一日期</b>(Due date / Birthday)→ 用 <code>DatePicker</code></li>
+            <li><b>選日期範圍</b>(訂單 from-to)→ 用 <code>{'<DatePicker.Range>'}</code></li>
+            <li><b>任務看板</b>(非時間軸 view)→ 用 <code>DataTable</code> + status column</li>
+            <li><b>時段可用性</b>(會議訂房 slot picker)→ 獨立 time-slot picker(未來 primitive)</li>
+            <li><b>Mini month widget</b>(sidebar 小月曆)→ 用 <code>DateGrid</code>(不 fullscreen)</li>
+          </ul>
+        </div>
+      </Section>
+
+      <Section title="vs 近親 — Calendar vs DatePicker">
+        <Rule
+          title="Calendar 是「看事件」的 page canvas,DatePicker 是「選日期」的 form control"
+          note="名字相近,職責完全不同。Calendar 是月行事曆事件 canvas;DatePicker 是欄位,選單一日期寫入 form state。"
+        >
+          <div className="grid grid-cols-2 gap-4">
+            <div>
+              <div className="text-body font-medium mb-2">DatePicker(form control)</div>
+              <Field>
+                <FieldLabel>Due date</FieldLabel>
+                <DatePicker />
+              </Field>
+            </div>
+            <div>
+              <div className="text-body font-medium mb-2">Calendar(event canvas)</div>
+              <div className="h-80 border border-divider rounded-md overflow-hidden">
+                <Calendar
+                  defaultReferenceDate={now}
+                  today={now}
+                  events={[
+                    { id: 'a', title: 'Design review', start: `${thisMonth}-05`, end: `${thisMonth}-05`, color: 'blue' },
+                  ] as CalendarEvent[]}
+                />
+              </div>
+            </div>
+          </div>
+        </Rule>
+      </Section>
+    </div>
+  ),
+}
+
+// ── 原則 — Event color 是類別語意,不是 severity ─────────────────────────────
+export const ColorSemantic: Story = {
+  name: '事件顏色類別語意',
+  render: () => (
+    <div className="space-y-6">
+      <Rule
+        title="事件的 color 是「這是哪一類事件」(團隊 / 專案),不是嚴重度"
+        note="Calendar 的 color = 12 categorical 色相,與 Tag / Avatar 共用同一組 SSOT(blue / green / deep-orange / yellow / red / orange / amber / lime / turquoise / indigo / purple / magenta),色名 1:1 對 color token。色相本身無 severity 語義——紅色 ≠「緊急」、橙色 ≠「警告」,只是類別選擇。若要標示緊急,改用事件標題文字(例:「🚨 Release deadline」)。下例以藍 / 綠 / 橙 / 紫四種色相代表四個不同團隊或專案。"
+      >
+        <div className="h-80 border border-divider rounded-md overflow-hidden">
+          <Calendar
+            defaultReferenceDate={now}
+            today={now}
+            events={[
+              { id: '1', title: 'Design review', start: `${thisMonth}-05`, end: `${thisMonth}-05`, color: 'blue' },
+              { id: '2', title: 'Sprint planning', start: `${thisMonth}-08`, end: `${thisMonth}-08`, color: 'blue' },
+              { id: '3', title: 'Release deadline', start: `${thisMonth}-12`, end: `${thisMonth}-12`, color: 'orange' },
+              { id: '4', title: 'Q review', start: `${thisMonth}-18`, end: `${thisMonth}-18`, color: 'green' },
+              { id: '5', title: 'Marketing sync', start: `${thisMonth}-22`, end: `${thisMonth}-22`, color: 'purple' },
+            ] as CalendarEvent[]}
+          />
+        </div>
+      </Rule>
+    </div>
+  ),
+}
+
+// ── 原則 — 支援範圍:月 view only(2026-07-14 rename MvpScope → MonthViewOnlyRule
+//    per audit Dim 14 + category-templates.md「Canonical naming」:「MVP」為開發 roadmap
+//    內部用語,reader-facing name 必人話;component-specific {Topic}Rule idiom 保留)──────
+export const MonthViewOnlyRule: Story = {
+  name: '僅支援月檢視',
+  render: () => (
+    <div className="space-y-6">
+      <Rule
+        title="只支援月檢視;週 / 日檢視、拖拉新增事件尚未實作"
+        note="世界級行事曆(Google / Notion / Fantastical)最常用的是月檢視(8 成以上的使用情境是「看本月整體」)。本元件目前只實作月檢視,週 / 日檢視、拖拉新增事件、就地編輯都留待後續增量。若當下產品需要週檢視,可改用 DataTable(以橫向週為欄)搭配自訂事件樣式,不勉強套用 Calendar。"
+      >
+        <div className="h-80 border border-divider rounded-md overflow-hidden">
+          <Calendar
+            defaultReferenceDate={now}
+            today={now}
+            events={[
+              { id: '1', title: 'Sprint planning', start: `${thisMonth}-08`, end: `${thisMonth}-08`, color: 'blue' },
+            ] as CalendarEvent[]}
+          />
+        </div>
+      </Rule>
+    </div>
+  ),
+}

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

@@ -10,19 +10,18 @@ benchmark:
   - MUI X Date Pickers: github.com/mui/mui-x/tree/master/packages/x-date-pickers
 ---
 
-<!-- @benchmark-cited: D5 retrofit 2026-05-18 — Notion/Google/Fantastical/macOS Calendar references retained as visual product references with per-claim @benchmark-unverified inline (closed-source, no canonical DS doc URL exists). Frontmatter benchmark URLs cover OSS Ant + MUI. -->
 
 # Calendar 設計原則
 
 ## 定位
 
-Calendar 是**事件檢視 canvas**,讓 user 以**月 / 週 / 日** 三種 view 瀏覽、定位、快速增減事件。對齊 Notion Calendar / Google Calendar / Fantastical / macOS Calendar 的事件檢視模型 <!-- @benchmark-unverified: closed-source product visual references, no public DS spec URL; visual sampling -->。
+Calendar 是**月事件檢視 canvas**,讓 user 瀏覽、定位、快速增減月份事件。週 / 日 timeline 不在本元件 API 中；若未來實作，需以真實行為與獨立規格重新提案，不先保留空 prop / variant。月檢視是本元件唯一已驗證、可維護的 interaction model。
 
 **Layout Family**:**非 4-Family,屬 page-composite**(見 `patterns/element-anatomy/element-anatomy.spec.md`「Page-composite」段)。多區塊 layout(Toolbar / Grid / EventTile / SidePanel),各自 own 自己的 anatomy。
 
 **實作基礎**:
 - 自建 composite(非 DayPicker)—— DayPicker 是「date picker 選日期」primitive,event calendar 是「頁面上看事件」的頁面 layout,兩者語意完全不同
-- 消費 DS primitives:`<Button>` / `<Tabs>`(切換 view) / `<DropdownMenu>`(新增事件入口) / `<ScrollArea>`(垂直事件列表) / `<AspectRatio>`(月 view 的 cell 比例)
+- 消費 DS primitive:`<Button>`(prev / next / 今天 / 新事件 CTA);月 grid cell 與 event tile 為元件自身用 CSS grid + token 組合,不另外消費 primitive。日期運算用 `date-fns`
 - 日期運算用 `date-fns`(已有 dependency,輕量)——不自造 date math
 
 **與 DatePicker 的區分(重要)**:
@@ -30,8 +29,8 @@ Calendar 是**事件檢視 canvas**,讓 user 以**月 / 週 / 日** 三種 view
 | 元件 | 定位 | 互動模型 | 適用 Layout |
 |------|------|---------|------------|
 | `<DatePicker>` | **選日期**的 form control | 點 trigger → 浮層 Calendar → 選一個 → 回填 input | Field control(form 的一部分) |
-| `<Calendar>`(DayPicker 包裝) | DatePicker 的內部 calendar grid primitive | N/A(不直接消費) | Internal to DatePicker |
-| **`<Calendar>`**(本元件) | **看事件**的 page-level canvas | 在月/週/日 view 中瀏覽 event、點 event 看詳情、拖拉新增 | Page layout(整個檢視頁面) |
+| `<DateGrid>`(DayPicker 包裝,2026-04-21 自 Calendar 改名) | DatePicker 的內部 calendar grid primitive | N/A(不直接消費) | Internal to DatePicker |
+| **`<Calendar>`**(本元件) | **看事件**的 page-level canvas | 在月 view 中瀏覽 event、點 event 看詳情 | Page layout(整個檢視頁面) |
 
 「User 需要選日期」 → DatePicker。「User 需要看本月會議 / 行程 / 截止日」 → **Calendar**。
 
@@ -41,7 +40,7 @@ Calendar 是**事件檢視 canvas**,讓 user 以**月 / 週 / 日** 三種 view
 - **Fantastical**:月 + event tile 顏色強調
 - **macOS Calendar**:簡潔 month grid + 左側 mini month
 
-本元件 MVP 鎖定 **月 view**(最常用 ~80% 場景),週 / 日 view 列後續增量。
+本元件只承諾 **月 view**；未實作能力不預佔公開 API。
 
 ---
 
@@ -63,26 +62,39 @@ Calendar 是**事件檢視 canvas**,讓 user 以**月 / 週 / 日** 三種 view
 | 「選一個日期範圍」表單欄位 | `<DatePicker.Range>` | 同上 |
 | 時間 granularity 是時分秒的儀表板 | Timeline / Gantt chart | event calendar 的最小 granularity 是**時段**(15-60 分鐘),不是秒級 |
 | 單純事件**列表**(沒時間軸視覺需求) | `<DataTable>` / `<Empty>` | 列表是「linear」瀏覽,calendar 是「spatial」瀏覽 |
+| 跨日 span 排程視覺(bar 橫跨多欄) | Gantt / Timeline | 月 view 多日事件為每涵蓋日各一條 tile,非橫跨欄 span bar(見「Event tile 規則」) |
+
+## 常見誤解
+
+| 誤解 | 正解 |
+|------|------|
+| 「Calendar 是 DatePicker 的內部 grid」 | 那是 `DateGrid`(DayPicker 包裝);本元件是 page-level 事件 canvas(見「定位」分界表) |
+| 「多日事件渲染成橫跨多欄的長 bar」 | 月 view 為 per-cell 模型,每涵蓋日各一條 tile(見「Event tile 規則」) |
+| 「整月無事件要放 `<Empty>`」 | 空白即常態;需要提示由 consumer 外層自疊(見「狀態 > Empty」) |
+| 「可以傳 `view="week"` 預留週 view」 | 未實作能力不預佔 API；目前沒有 `view` prop |
 
 ---
 
-## API(MVP)
+## API
 
 ```tsx
 <Calendar
-  view="month" | "week" | "day"           // MVP 只支援 "month"
-  defaultView="month"
   referenceDate={Date}                      // 當前聚焦日期(月檢視的那個月)
-  onViewChange={(view) => ...}
+  defaultReferenceDate={Date}
   onReferenceDateChange={(date) => ...}
+  today={Date}                              // today highlight / Today button / default month 的同一時間來源;可釘 SSR/測試
   events={Event[]}                          // 事件資料
   onEventClick={(event) => ...}             // 點 event tile 回調
   onDateClick={(date) => ...}               // 點月 cell 回調(用於新增)
-  onRangeSelect={(from, to) => ...}         // 月 view 拖拉選一段 range(新增 multi-day)
+  onCreateEvent={() => ...}                 // 點「新事件」CTA 回調
   weekStartsOn={0 | 1}                      // 0=Sun, 1=Mon
   renderEventTile={(event) => ReactNode}    // 自訂 event tile 視覺
-  renderEmpty={() => ReactNode}             // 無事件狀態
-  size="md" | "lg"                          // cell 大小(MVP 兩尺寸)
+  locale="en-US"                            // Intl 語系(月份標題 / 星期名;預設 'en-US')
+  prevAriaLabel="上個月"                    // i18n override:prev 導覽鈕 aria-label
+  nextAriaLabel="下個月"                    // i18n override:next 導覽鈕 aria-label
+  navAriaLabel="行事曆月份導覽"             // i18n override:月份導覽 <nav> landmark aria-label
+  todayLabel="今天"                         // i18n override:「今天」按鈕文字
+  createLabel="新事件"                      // i18n override:「新事件」CTA 文字(僅在傳 onCreateEvent 時渲染)
   className
 />
 ```
@@ -95,62 +107,61 @@ interface CalendarEvent {
   title: string
   start: string | Date       // ISO "YYYY-MM-DDTHH:mm" 或 "YYYY-MM-DD"(all-day)
   end: string | Date
-  allDay?: boolean            // true = 跨整日,渲染為橫跨數欄的 tile
-  color?: string              // 事件類別色(來自 DS palette,consumer 自選)
+  allDay?: boolean            // true = 全天事件,渲染為頂端全天長條(淡底 + 左 accent 條);多日事件在每個涵蓋日各顯示一條
+  color?: CategoricalHue     // 12 categorical 色相(消費 categorical-color SSOT,與 Tag / Avatar 共用);色名 1:1 對 --color-{hue}-*
   metadata?: Record<string, unknown>   // 自由資料,renderEventTile 讀
 }
 ```
 
 ---
 
-## Anatomy(月 view,MVP)
+## Anatomy(月 view)
 
 ```
 ┌─────────────────────────────────────────────────────────────────┐
-│ Toolbar:[◀] 2026 年 4 月 [▶]        [< 日 週 月 >]  [+ 新事件] │
+│ Toolbar:[◀] [今天] [▶] 2026 年 4 月               [+ 新事件] │
 ├─────┬─────┬─────┬─────┬─────┬─────┬─────┬────────────────────┤
 │ 週日 │ 週一 │ 週二 │ 週三 │ 週四 │ 週五 │ 週六 │   ← 星期 header   │
 ├─────┼─────┼─────┼─────┼─────┼─────┼─────┼────────────────────┤
 │ 29* │ 30* │ 31* │  1  │  2  │  3  │  4  │   ← 月 grid row
 │     │     │     │event│event│     │event│
-│     │     │     │█mtg │█vac │     │█dl  │      event tile(橫跨)
+│     │     │     │█mtg │▌vac │     │█dl  │
 ├─────┼─────┼─────┼─────┼─────┼─────┼─────┤
 │  5  │  6  │  7  │  8  │  9  │ 10  │ 11  │
 │event│     │     │     │event│     │     │
 │█ret │     │     │     │█rev │     │     │
 └─────┴─────┴─────┴─────┴─────┴─────┴─────┴────────────────────┘
-
-*= prev/next month outside days(text-fg-disabled)
 ```
 
+圖例:`*` = 上 / 下月 outside days(弱化字色);`█` = 一般 event tile;`▌` = 全天事件(左 accent 條)。
+
 ### Cell 規則
 
-- **Cell 尺寸**:MVP 月 view cell 高度固定,容納日期 header + 3 個 event tile;寬度 7 欄等分
+- **Cell 尺寸**:MVP 月 view cell 最小高度 `min-h-28`(112px),容納日期 header + 3 個 event tile,並隨容器高度伸縮(root `h-full` + grid `flex-1`);寬度 7 欄等分
 - **日期 header**:右上角數字(對齊 Google Calendar 視覺慣例)
-- **Today cell**:日期數字以 primary-filled pill 強調(對齊 Google Calendar today pill)
+- **Today cell**:日期數字以 info-filled pill 強調(對齊 Google Calendar today pill)
 - **Outside day cell**:上/下月溢出日期弱化字色 + 背景略暗區分
 - **Hover cell**:整 cell 帶 neutral-hover 提示可點擊新增入口
-- **Weekend cell**:可選弱化背景(對齊 Google;MVP 預設關閉)
+- **Weekend cell**:弱化背景(對齊 Google);MVP 未實作,列後續增量
 
 ### Event tile 規則
 
-- **一般 event(timed)**:`{color}-subtle` 底色 + `{color}-text` 文字,圓角 + 緊湊 padding + truncate(單行)
-- **All-day event**:同一般 tile 但橫跨多 cell(grid-column span)
-- **Hover tile**:用 `{color}-hover` 微暗化表示可點擊
-- **超出 tile 限制**:顯示「+N more」(對齊 Google Calendar),點擊展開 popover 列表
+- **一般 event(timed)**:事件色相 subtle 底 + 對應文字色(消費 categorical-color SSOT,與 Tag / Avatar 共用 12 色相),單行 truncate
+- **All-day event**(2026-06-01 補實作):淡底 tile + 左側實心 accent 條 + 字重略強,排在 cell 事件區頂端(`allDay` 事件排序在有時間事件之前);多日全天事件靠日期範圍 filter 在每個涵蓋日各顯示一條(非單一橫跨多欄的 grid-column span bar——month view per-cell 模型不做跨欄絕對定位)
+- **Hover tile**:hover 微暗化表示可點擊
+- **超出 tile 限制**:每格最多顯示 3 筆事件,超出顯示「+N more」弱化計數文字(對齊 Google Calendar),目前不可點擊(點擊展開 popover 列表為後續增量)
 
 完整 cell + event tile 的 class / token 對照見 anatomy `ColorMatrix` story。
 
 ### Toolbar
 
 ```
-[◀] [今天] [▶]    月份標題(2026 年 4 月)    [日 | 週 | 月]    [+ 新事件]
+[◀] [今天] [▶]    月份標題(2026 年 4 月)    [+ 新事件]
 ```
 
 - 左 Nav:`<Button iconOnly>` prev/next + `<Button>今天</Button>` 跳 today
 - 中央 title:`<h2 className="text-h3">` or `text-body-lg font-medium`
-- 右視圖切換:`<SegmentedControl>`(day/week/month)—— MVP 只啟用 month,其他 disabled
-- 右上 CTA:`<Button variant="primary" startIcon={Plus}>新事件</Button>`
+- 右上 CTA:`<Button variant="primary" startIcon={Plus}>新事件</Button>` — **條件渲染:僅在傳 `onCreateEvent` 回調時出現**(未傳 = 無 CTA,純瀏覽場景);文案由 `createLabel` prop override(對齊 `todayLabel` 等 chrome 文字 i18n override 慣例)
 
 對齊 `patterns/action-bar/action-bar.spec.md`(左 context / 中 focus / 右 CTA 的經典分組)。
 
@@ -161,43 +172,53 @@ interface CalendarEvent {
 ### Empty
 無事件時 cell 空白(不顯示 empty state)——calendar 本身是 canvas,空白 = 沒事件,語意自明。
 
-**不用 `<Empty>` 元件**——Empty 是「引導使用者做什麼」,月曆空白是常態不是引導目標。若整個月**零事件**可選擇顯示 subtle 提示(`<Empty icon={CalendarPlus} title="本月無事件" />`),由 consumer 在 `renderEmpty` 提供。
+**不用 `<Empty>` 元件**——Empty 是「引導使用者做什麼」,月曆空白是常態不是引導目標。若整個月**零事件**需要 subtle 提示(`<Empty icon={CalendarPlus} title="本月無事件" />`),由 consumer 自行疊在 Calendar 外層(MVP 無內建 `renderEmpty` hook,列後續增量)。
 
 ### Loading
-載入 events 時,cells 用 `<Skeleton>` placeholder tile(對齊其他非同步元件)。
+MVP 無內建 loading 狀態(無 `loading` prop / 無 Skeleton 分支)——events 由 consumer 取得,載入中時 consumer 自行決定是否在 Calendar 外層顯示 placeholder。後續增量擬以 `<Skeleton>` placeholder tile 對齊其他非同步元件(見「MVP vs 後續增量」)。
 
 ### Error
-載入失敗時,顯示 toolbar 內 inline error hint + retry button;不 block 整個 calendar 顯示。
+MVP 無內建 error 狀態(無 `error` / `onRetry` prop)——載入失敗由 consumer 在外層處理。後續增量擬在 toolbar 內顯示 inline error hint + retry button 且不 block 整個 calendar 顯示。
+
+### 邊界案例
+
+- **單格事件 > 3**:只渲染前 3 筆,其餘**不進 DOM**(鍵盤 / SR 不可達),以「+N more」弱化計數提示(不可點擊,展開 popover 為後續增量)
+- **極長事件標題**:tile 單行 truncate,不換行不撐高 cell;實際截斷時 hover / focus 顯完整標題 tooltip(僅實際截斷才顯——rule owner `components/Tooltip/tooltip.spec.md:32`「截斷文字 → tooltip」,SSOT `patterns/element-anatomy/truncated-text.spec.md`;tile 是 interactive host → `useTruncated` 自組、trigger = tile 本體、量測內層文字 span;toolbar 月份標題同規則,消費 `<TruncatedText>`)
+- **跨月多日事件**:依日期範圍 filter,在每個涵蓋日各顯示一條(含 outside days 與翻月後的新月份)
+- **載入失敗 / 舊資料**:無內建 error 狀態(見上)——Calendar 照常渲染 consumer 當下傳入的 `events`,互動不自動禁用;是否 block 由 consumer 決定
+- **週末**:目前無週末弱化，週末 cell 行為與平日一致(event tile 照常顯示)。**RTL 不支援**，全域 owner 見 `packages/design-system/README.md#compatibility-matrix`。
 
 ### a11y
-- Toolbar navigation 用 `<nav aria-label="calendar navigation">`
-- Month grid 用 `role="grid"`,每 cell `role="gridcell"`,日期用 `aria-label="2026 年 4 月 3 日,3 個事件"`
-- Event tile `role="button"` + descriptive `aria-label`(title + time)
-- Keyboard:方向鍵移動 cell focus / Enter 打開事件 / PageUp/Down 切月
+- Toolbar navigation 用 `<nav aria-label>`(預設 `行事曆月份導覽`,consumer 可由 `navAriaLabel` prop override)
+- Month grid 用 `role="grid"`,每 cell `role="gridcell"`(非互動容器 — button 語義禁互動後代,cell 內含事件 tile 不可自身為 button);日期數字為 `<button>`,ISO 格式 `aria-label="2026-04-03,3 個事件"`
+- Event tile `role="button"` + `aria-label`(事件標題,格式 `事件:{title}`)
+- Keyboard:見文末「A11y 預設」(keyboard map SSOT,本節不重複)
 
 ---
 
 ## 禁止事項
 
 - ❌ 不用 `<DayPicker>` 為底層——DayPicker 是 form control 用,結構不適合 page-level event canvas
-- ❌ 不硬寫 month grid 為 `<table>`——用 CSS grid(月 view 可能跨 cell span event,table 不好 span)
+- ❌ 不硬寫 month grid 為 `<table>`——用 CSS grid(月 view 為 per-cell 模型不跨欄 span,見「Event tile 規則」;後續週 / 日 view 的 timeline / 拖拉增量需 grid 自由佈局,table 結構難擴充)
 - ❌ 不把 event 資料存在元件內部 state——event 是 consumer 責任,本元件是純 view
-- ❌ 不自動打開「新事件」表單——`onDateClick` / `onRangeSelect` 回調給 consumer 決定(避免強制開 Dialog UX)
-- ❌ 不重造 date math——用 `date-fns`
+- ❌ 不自動打開「新事件」表單——`onDateClick` / `onCreateEvent` 回調給 consumer 決定(避免強制開 Dialog UX)
+- ❌ 不重造 date math——月 / 週 grid 邊界運算(`startOfMonth` / `eachDayOfInterval` / `isSameMonth` 等)一律用 `date-fns`。**唯一例外(D3 perf,tsx `eventsByDate` memo 有註解)**:每 render 對 42 cells 分桶事件的 hot path 用原生 timestamp 迭代(`new Date(y, m, d).getTime()` + `setDate(+1)`)—— 避免 per-cell `isWithinInterval` 的 O(42×N) 重複掃描;此 raw-Date 迭代**限縮在** bucketing memo 內,不外溢為通則
 
 ---
 
-## MVP vs 後續增量
+## 已實作範圍
 
-### MVP(本次 session)
 - 月 view(完整)
 - Toolbar prev/next/today + title
 - Event tile render(單 line + color variant + truncate)
 - Today cell highlight
 - Outside days visual
-- Empty / loading 基礎
+- Empty 為常態空白(無內建 empty/loading/error UI)
+
+### 非本 API 的未實作構想
+
+下列能力不以空 prop / disabled control 預佔公開 surface；未來若有真實 consumer，需重新做需求、行為、a11y 與視覺設計：
 
-### 後續(tech debt)
 - 週 view(timeline 24 小時縱軸)
 - 日 view(single-day timeline)
 - 拖拉新增 event(from 月 cell → range select)
@@ -205,14 +226,16 @@ interface CalendarEvent {
 - 「+N more」展開 popover
 - 左側 mini month + filter sidebar
 - 多曆疊加(multi-calendar sources)
+- 內建 loading(Skeleton)/ error(inline hint + retry)/ renderEmpty hook
+- 拖拉選 range(`onRangeSelect`)
 - Print view / iCal export
 
 ---
 
 ## Anatomy N/A rationale(偏離 canonical 5 的說明)
 
-- **無 `SizeMatrix`**:MVP 只支援 `view="month"` + 固定 `size="md"`,無多 size tier 可 matrix 對照。後續擴充 week / day view 時再補 SizeMatrix
-- **無 `StateBehavior`**:Calendar 是 page-composite canvas,本身無 `hover / focus / disabled` 狀態;互動狀態屬於內部 primitive(event tile / date cell),由 `<Button>` / `<DropdownMenu>` 等消費元件自己的 StateBehavior 負責
+- **無 `SizeMatrix`**:Calendar 沒有 size variant；禁止為未實作視覺保留空 `size` prop。
+- **`StateBehavior` 已存在**(today / outside month / 多事件 / event hover / empty cell):Calendar 本身無 `hover / focus / disabled` 互動 prop,但 cell / event tile 的視覺狀態由 anatomy `StateBehavior` story 列舉(對齊 calendar.anatomy.stories.tsx 檔頭 @anatomy-rationale)
 
 ---
 
@@ -227,16 +250,18 @@ interface CalendarEvent {
 
 **ARIA / Pattern**:對齊 [W3C ARIA Authoring Practices Guide](https://www.w3.org/WAI/ARIA/apg/patterns/) 對應 pattern。
 
-**Keyboard 行為**:
+**Keyboard 行為(實作現況)**:
+
+- Tab — 逐一 focus 每格的日期數字按鈕與其中的事件 tile(cell 為非互動 `role="gridcell"` 容器;滑鼠點 cell 空白處等同點日期,keyboard 走日期數字按鈕,功能等價。對齊 Google Calendar)
+- Enter / Space — 啟用目前 focus 的元素:日期數字按鈕觸發 `onDateClick`(native button activation),事件 tile 觸發 `onEventClick`
+- Toolbar 的 prev / 今天 / next 為標準可聚焦控件,Tab 可達
+- `renderEventTile` 自訂 tile:外層 wrapper 統一 own `role="button"`、`tabIndex=0`、focus ring 與 Enter/Space activation，確保自訂視覺不會把 keyboard parity 推給 consumer。Consumer 回傳內容必為 presentational（不可再巢狀 button/link）；互動由 `onEventClick` 單一 owner 承接。
 
-- Tab — focus calendar
-- ↑/↓/←/→ — 切 day
-- PageUp/Down — 切月
-- Shift+PageUp/Down — 切年
-- Enter — 選 date
-- Esc — 取消 / 關閉
+**Keyboard 後續增量**:
 
-**Focus**:focus-visible ring 對齊 DS canonical(`outline: 2px solid var(--ring)`);focus management 由元件 own。
+- ↑/↓/←/→ 在日期格間 roving 移動、PageUp/Down 切月、Shift+PageUp/Down 切年。
+- 此為已知 a11y gap:方向鍵 roving 是 APG grid pattern 建議；目前所有互動元素皆 Tab 可達。
 
-**驗證**:Storybook a11y addon panel 應 0 critical violation;鍵盤完整可操作(無需滑鼠)。WCAG AA contrast ≥ 4.5:1(text)/ 3:1(UI)。
+**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/Calendar/calendar.stories.tsx

@@ -0,0 +1,108 @@
+// @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 type { Meta, StoryObj } from '@storybook/react'
+import { expect, fn, userEvent, within } from '@storybook/test'
+import { Calendar, type CalendarEvent } from './calendar'
+
+const meta: Meta<typeof Calendar> = {
+  title: 'Design System/Components/Calendar/展示',
+  tags: ['autodocs'],
+  component: Calendar,
+  parameters: {
+    layout: 'fullscreen',
+    docs: {
+      description: {
+        component:
+          '以月檢視瀏覽與安排多筆事件，適合團隊行程、內容排程與資源規劃。若使用者只需在表單中選一個日期，應使用 DatePicker；Calendar 不是日期輸入欄位。',
+      },
+    },
+  },
+}
+export default meta
+
+type Story = StoryObj<typeof Calendar>
+const customTileActivated = fn()
+
+// ── 真實業務情境 ─────────────────────────────────────────────────────
+
+// 視覺基線同時釘住顯示月與 today SSOT，避免跨月/換日造成 snapshot 漂移。
+const now = new Date(2026, 6, 15)
+const thisMonth = now.getFullYear() + '-' + String(now.getMonth() + 1).padStart(2, '0')
+
+/**
+ * 團隊行事曆 — Notion / Google Calendar 替代品情境
+ * 本月會議 / deadline / 休假,多事件類型用 color 區隔。
+ */
+export const TeamCalendar: Story = {
+  name: '團隊行事曆',
+  render: () => {
+    const events: CalendarEvent[] = [
+      { id: '1', title: 'Design review', start: `${thisMonth}-05`, end: `${thisMonth}-05`, color: 'blue' },
+      { id: '2', title: 'Sprint planning', start: `${thisMonth}-08`, end: `${thisMonth}-08`, color: 'blue' },
+      { id: '3', title: 'Project Orion deadline', start: `${thisMonth}-12`, end: `${thisMonth}-12`, color: 'red' },
+      { id: '4', title: '1:1 w/ Sarah', start: `${thisMonth}-12`, end: `${thisMonth}-12`, color: 'purple' },
+      { id: '5', title: 'Standup', start: `${thisMonth}-15`, end: `${thisMonth}-15`, color: 'blue' },
+      { id: '6', title: 'Q2 OKR review', start: `${thisMonth}-18`, end: `${thisMonth}-18`, color: 'green' },
+      { id: '7', title: 'Alex vacation', start: `${thisMonth}-20`, end: `${thisMonth}-22`, color: 'yellow', allDay: true },
+      { id: '8', title: 'Customer meeting', start: `${thisMonth}-25`, end: `${thisMonth}-25`, color: 'orange' },
+    ]
+    return (
+      <div className="h-screen p-4 bg-canvas">
+        <Calendar
+          defaultReferenceDate={now}
+          today={now}
+          events={events}
+          onEventClick={(e) => alert(`點了事件:${e.title}`)}
+          onDateClick={() => { /* demo:實際 app 在此開「當日新增事件」面板 */ }}
+          onCreateEvent={() => alert('開啟新事件對話框')}
+        />
+      </div>
+    )
+  },
+}
+
+/**
+ * 內容發佈排程 — Blog / 影片發布月曆
+ */
+export const ContentPublishingSchedule: Story = {
+  name: '內容發佈月曆',
+  render: () => {
+    const events: CalendarEvent[] = [
+      { id: 'p1', title: '週五 newsletter', start: `${thisMonth}-02`, end: `${thisMonth}-02`, color: 'blue' },
+      { id: 'p2', title: 'Blog: 設計系統 v2', start: `${thisMonth}-07`, end: `${thisMonth}-07`, color: 'purple' },
+      { id: 'p3', title: 'YouTube: tutorial ep 3', start: `${thisMonth}-10`, end: `${thisMonth}-10`, color: 'red' },
+      { id: 'p4', title: 'Podcast: interview', start: `${thisMonth}-17`, end: `${thisMonth}-17`, color: 'green' },
+      { id: 'p5', title: 'Product announcement', start: `${thisMonth}-28`, end: `${thisMonth}-28`, color: 'orange' },
+    ]
+    return (
+      <div className="h-screen p-4 bg-canvas">
+        <Calendar
+          events={events}
+          defaultReferenceDate={now}
+          today={now}
+          renderEventTile={(event) => <span className="block truncate rounded-md bg-secondary px-1.5 py-0.5 text-caption text-foreground">{event.title}</span>}
+          onEventClick={customTileActivated}
+          onCreateEvent={() => alert('排內容')}
+        />
+      </div>
+    )
+  },
+  play: async ({ canvasElement }) => {
+    customTileActivated.mockClear()
+    const tile = await within(canvasElement).findByRole('button', { name: '事件:週五 newsletter' })
+    tile.focus()
+    await userEvent.keyboard('{Enter}')
+    await expect(customTileActivated).toHaveBeenCalledTimes(1)
+  },
+}
+
+/**
+ * 空行事曆 — 無事件時 calendar 本身是空 canvas,不強制顯示 empty state
+ */
+export const EmptyCalendar: Story = {
+  name: '空行事曆',
+  render: () => (
+    <div className="h-screen p-4 bg-canvas">
+      <Calendar events={[]} defaultReferenceDate={now} today={now} onCreateEvent={() => alert('加第一個事件')} />
+    </div>
+  ),
+}