@seanyeh77/ui 0.0.0-stage → 0.3.0

package/dist/tokens.css

@@ -0,0 +1,131 @@
+/* Generated from tokens.json by scripts/build.ts. Do not edit by hand. */
+:root {
+  --bg: #fcfbfb;
+  --surface: #ffffff;
+  --surface-sub: #f6f5f4;
+  --surface-chrome: #ffffff;
+  --surface-input: #ffffff;
+  --ink: #171512;
+  --ink-muted: #6d645a;
+  --line: #e2dfdc;
+  --line-strong: #8c8073;
+  --graph-edge: #8c8073;
+  --graph-node: #f6f5f4;
+  --code-keyword: #2457d6;
+  --code-constant: #0b7a6b;
+  --accent: #2457d6;
+  --accent-hover: #204dbc;
+  --accent-press: #1c44a7;
+  --accent-text: #2457d6;
+  --accent-soft: #e5ebfa;
+  --on-accent: #ffffff;
+  --focus-ring: rgba(36, 87, 214, 0.3);
+  --success: #1ca655;
+  --success-text: #14743b;
+  --success-soft: #e8f6ee;
+  --warning: #d68710;
+  --warning-text: #965f0b;
+  --warning-soft: #fbf3e7;
+  --danger: #cd2823;
+  --danger-text: #901c19;
+  --danger-soft: #faeae9;
+  --info-text: #193d96;
+  --info-soft: #e9eefb;
+  --neutral-0: #fcfbfb;
+  --neutral-50: #f6f5f4;
+  --neutral-100: #eeecea;
+  --neutral-200: #e1dedb;
+  --neutral-300: #cfcac4;
+  --neutral-400: #aca49a;
+  --neutral-500: #8c8073;
+  --neutral-600: #6d645a;
+  --neutral-700: #514a43;
+  --neutral-800: #39332d;
+  --neutral-900: #25211d;
+  --neutral-950: #171512;
+  --chart-1: #2457d6;
+  --chart-2: #0f9d8a;
+  --chart-3: #cf6a12;
+  --space-1: 4px;
+  --space-2: 8px;
+  --space-3: 12px;
+  --space-4: 16px;
+  --space-5: 20px;
+  --space-6: 24px;
+  --space-8: 32px;
+  --space-12: 48px;
+  --radius-sm: 6px;
+  --radius-chip: 8px;
+  --radius-md: 10px;
+  --radius-lg: 14px;
+  --radius-full: 9999px;
+  --shadow-sm: 0 1px 2px rgba(16, 24, 40, 0.12);
+  --shadow-chip: 0 1px 2px rgba(16, 24, 40, 0.14), 0 2px 6px rgba(16, 24, 40, 0.08);
+  --shadow-card: 0 1px 2px rgba(16, 24, 40, 0.06), 0 8px 24px rgba(16, 24, 40, 0.1);
+  --shadow-card-hover: 0 2px 4px rgba(16, 24, 40, 0.08), 0 16px 36px rgba(16, 24, 40, 0.14);
+  --shadow-overlay: 0 20px 48px rgba(0, 0, 0, 0.25);
+  --control-height: 40px;
+  --chip-height: 32px;
+  --touch-target: 48px;
+  --header-height: 64px;
+  --sidebar-width: 240px;
+  --sidebar-collapsed: 72px;
+  --tabbar-height: 68px;
+  --icon-stroke: 2px;
+  --alert-bar: 3px;
+  --bp-tablet: 600px;
+  --bp-desktop: 960px;
+  --bp-wide: 1280px;
+  --font-sans: Inter, "Noto Sans TC", system-ui, sans-serif;
+  --font-mono: "Geist Mono", "Noto Sans TC", ui-monospace, monospace;
+}
+[data-theme="dark"] {
+  --bg: #2f2a25;
+  --surface: #393530;
+  --surface-sub: #443f3b;
+  --surface-chrome: #35302c;
+  --surface-input: #26221e;
+  --ink: #f6f5f4;
+  --ink-muted: #b3aba2;
+  --line: #4c4844;
+  --graph-edge: #b3aba2;
+  --graph-node: #443f3b;
+  --code-keyword: #a3b7ee;
+  --code-constant: #3cc4ae;
+  --accent-text: #819ee7;
+  --accent-soft: #2d344c;
+  --focus-ring: rgba(124, 154, 230, 0.45);
+  --success-text: #82cea2;
+  --success-soft: #2c3e2d;
+  --warning-text: #e8bd7c;
+  --warning-soft: #4a3922;
+  --danger-text: #e48986;
+  --danger-soft: #482a25;
+  --info-text: #87a3e8;
+  --info-soft: #2d3141;
+  --chart-1: #819ee7;
+  --chart-2: #3cc4ae;
+  --chart-3: #f0a35e;
+  --shadow-sm: 0 1px 2px rgba(0, 0, 0, 0.5);
+  --shadow-chip: 0 1px 3px rgba(0, 0, 0, 0.6), 0 2px 6px rgba(0, 0, 0, 0.4);
+  --shadow-card: 0 1px 2px rgba(0, 0, 0, 0.6), 0 8px 24px rgba(0, 0, 0, 0.55);
+  --shadow-card-hover: 0 2px 4px rgba(0, 0, 0, 0.6), 0 16px 36px rgba(0, 0, 0, 0.6);
+  --shadow-overlay: 0 20px 48px rgba(0, 0, 0, 0.5);
+}
+[data-theme="teaching"] {
+  --accent: #0f766e;
+  --accent-hover: #0d6861;
+  --accent-press: #0c5c56;
+  --accent-text: #0f766e;
+  --accent-soft: #e2efee;
+  --focus-ring: rgba(15, 118, 110, 0.3);
+  --chart-1: #0f766e;
+  --radius-sm: 0px;
+  --radius-chip: 0px;
+  --radius-md: 0px;
+  --radius-lg: 0px;
+  --shadow-sm: none;
+  --shadow-chip: none;
+  --shadow-card: none;
+  --shadow-card-hover: none;
+}

package/docs/AccentPicker.md

@@ -0,0 +1,7 @@
+# AccentPicker
+
+強調色選擇：8 個推薦色票，下方可以輸入任何色碼。
+
+- 色票：藍、靛、紫、桃紅、紅、橘、綠、青；選中的色票外圍一圈同色外框並打勾。
+- 色碼欄位：輸入 # 加 6 碼就立即套用；格式不正確時框變紅並說明。
+- 不傳 `onChange` 時會直接呼叫 `UI.setAccent()`，依 README「自訂強調色的換算」重新算出 hover、按下、淺底、文字色與 focus 光暈，並存在 localStorage。

package/docs/ActionBar.md

@@ -0,0 +1,17 @@
+# ActionBar
+
+卡片底部的一組操作按鈕。
+
+- 寬度小於 600 px：最常用的一個（`primary: true`，沒有標示時用第一個）是全寬的主要按鈕，高度 44 px；其他收進右邊的「⋯」選單（外框，44 × 44 px）。
+- 比較寬時：全部並排，主要按鈕在最前面，其他是次要按鈕，放不下就換行。
+- 每個區塊最多一個主要按鈕。危險操作加 `danger: true` 和 `confirm`，在選單裡會放到最後，確認後才執行。
+
+```tsx
+<ActionBar
+  actions={[
+    { label: '部署', primary: true, onClick: deploy },
+    { label: '查看紀錄', onClick: openLogs },
+    { label: '刪除', danger: true, confirm: { title: '刪除這個環境？' }, onClick: remove },
+  ]}
+/>
+```

package/docs/Alert.md

@@ -0,0 +1,8 @@
+# Alert
+
+頁面或區塊內持續顯示的提示：白底卡片，上緣一條 3 px 狀態色條。
+
+- 外型：`surface` 底色、`shadow-card` 陰影、`radius-md` 圓角；上緣色條高度 `alert-bar` 3 px，圖示與色條同色。
+- 四種 `tone`：`info`（`accent`）、`success`、`warning`、`danger`。
+- 關閉：只有 `info` 與 `success` 會顯示右上角的關閉按鈕（需傳入 `onDismiss`）；`warning` 與 `danger` 不能關閉。
+- 動作：用外框按鈕放在右側（`actionLabel`、`onAction`），按鈕文字只用動詞。

package/docs/AppShell.md

@@ -0,0 +1,30 @@
+# AppShell
+
+Dashboard 類頁面的外框：側邊欄、頂部列和內容區。頁面都從這裡開始，不要自己排側邊欄。
+
+- 電腦（960 px 以上）：側邊欄 240 px，左下角的按鈕可以收合成 72 px，選擇會記在瀏覽器。
+- 平板（600 到 959 px）：側邊欄固定收合成 72 px 圖示；有第二層的項目點了直接進第一個子頁面，頁面內用 Tabs 切換其他子頁面。
+- 手機（小於 600 px）：沒有側邊欄，最上層有圖示的項目變成底部分頁列，有子頁面的項目開啟第一個子頁面。分頁列到不了的頁面（沒有圖示、第 5 個以後、第二個以後的子頁面）放在最後一格「更多」，開啟完整的導覽。
+- 頂部列：頁面標題（只出現一次，頁面裡不要再寫一次）或麵包屑，右邊放搜尋、NotificationBell、ProjectSwitcher。往下捲時隱藏，往上捲時出現。
+- 內容區自己捲動，四周留 24 px（手機 16 px）。裡面用 `Page` 和 `Grid` 排版。
+
+```tsx
+<AppShell
+  nav={[
+    {
+      items: [
+        { id: 'home', label: '總覽', icon: 'house' },
+        { id: 'projects', label: '專案', icon: 'folder' },
+      ],
+    },
+  ]}
+  value={page}
+  onNavigate={setPage}
+  brand="專案中心"
+  title="總覽"
+  onSearch={() => setSearchOpen(true)}
+  actions={<NotificationBell items={notifications} />}
+>
+  <Page>…</Page>
+</AppShell>
+```

package/docs/Badge.md

@@ -0,0 +1,17 @@
+# Badge
+
+項目的狀態標籤：浮起 Chip，左側以進度圓圈表示狀態。
+
+- 放在卡片上時用 `variant="dot"`：圓點加文字，沒有底色和陰影，文字用該狀態的文字色（`success-text`、`danger-text`、`warning-text`、`accent-text`、`ink-muted`），避免看起來像按鈕。DataTable 的手機卡片會自動使用。
+
+- 外型：`surface` 底色、`shadow-chip` 陰影、`radius-chip` 8 px 圓角、高度 `chip-height` 32 px。
+- 文字用主要文字色 `ink`，顏色只出現在進度圓圈上。
+- 5 種狀態與進度圓圈：
+
+| status   | 文字   | 進度圓圈 | 顏色          |
+| -------- | ------ | -------- | ------------- |
+| `draft`  | 草稿   | 空心     | `neutral-500` |
+| `doing`  | 進行中 | 半滿     | `accent`      |
+| `review` | 審核中 | 四分之一 | `warning`     |
+| `done`   | 完成   | 全滿     | `success`     |
+| `fail`   | 失敗   | 全滿     | `danger`      |

package/docs/BarChart.md

@@ -0,0 +1,7 @@
+# BarChart
+
+長條圖（單組資料）。
+
+- 顏色 `chart-1`，柱子頂部 4 px 圓角，間距 8 px。
+- 格線為淡色虛線；滑過時其他柱子變淡，上方出現浮起卡片顯示數值。
+- 進場時一根接一根長高，間隔 40 ms。

package/docs/Breadcrumb.md

@@ -0,0 +1,7 @@
+# Breadcrumb
+
+目前頁面在層級中的位置。
+
+- 一般字（Inter 與思源黑體），14 px，`ink-muted`。
+- 分隔符號用箭頭「›」。
+- 最後一層是目前頁面：`ink`、字重 600，帶 `aria-current="page"`。

package/docs/Button.md

@@ -0,0 +1,18 @@
+# Button
+
+按鈕觸發一個動作。
+
+- `primary`：實心 `accent`。每個區塊（例如一張卡片、一個表單）最多一個主要按鈕。
+- `secondary`（預設）：外框 `line-strong`。
+- `danger`：實心 `danger`，用在刪除等無法復原的動作。一定要確認：給 `confirm={{ title, body }}`，按下時先跳出 Dialog，按 Dialog 裡的紅色按鈕才執行 `onClick`；放在確認框裡的那顆按鈕本身改給 `confirmed`。兩者都沒給時型別檢查不會過。
+- 狀態：滑過變深（`accent-hover`）、按下下移 1 px（`accent-press`）、停用為 `surface-sub` 灰底加 `ink-muted` 灰字、`loading` 顯示轉圈並停用，文字改成進行式（「儲存中」）。
+- 高度 `control-height` 40 px；觸控點擊範圍 `touch-target` 48 px（按鈕外觀不變，外圍擴大可點範圍）。
+- 按鈕文字只用動詞，例如「儲存」、「刪除」。
+- `icon`：Phosphor 圖示名稱（例如 `'plus'`，拼錯時型別檢查不會過），或自訂圖示的 24 px path（`'M4 12h16'`）。
+
+```tsx
+<Button variant="primary" icon="plus" onClick={add}>新增</Button>
+<Button variant="danger" confirm={{ title: '刪除 api-gateway？', body: '設定和紀錄會一起刪除，無法復原。' }} onClick={remove}>
+  刪除
+</Button>
+```

package/docs/Calendar.md

@@ -0,0 +1,15 @@
+# Calendar
+
+固定顯示在頁面上的月曆，DatePicker 和 DateRangePicker 的下拉日曆也是它。要選日期時用 DatePicker 或 DateRangePicker；只有日曆要一直顯示在頁面上（例如排程頁的側欄）才直接用 Calendar。
+
+- 一週的第一天依語系決定；選中的日期是強調色圓角方塊，今天下方有一個小圓點。
+- 每一天的樣子由 `dayState` 決定：`selected`、`inRange`、`start`、`end`、`disabled`。
+- 點日期呼叫 `onPick`；`focus` 是一開始顯示的月份。
+
+```tsx
+const [day, setDay] = useState<Date | null>(null);
+
+<Card>
+  <Calendar focus={day} onPick={setDay} dayState={(d) => ({ selected: d.toDateString() === day?.toDateString() })} />
+</Card>;
+```

package/docs/Card.md

@@ -0,0 +1,14 @@
+# Card
+
+頁面上的區塊容器：`surface` 底、`shadow-card` 陰影、14 px 圓角，內距 16 px。
+
+- 卡片裡不再放卡片，避免一層層的陰影。TreeList、KpiCard、Alert、SettingsSection 本身就有卡片樣式：單獨使用時直接當成區塊，不要再包一層；放進 `UI.Card` 時會自動拿掉自己的陰影，TreeList 也拿掉底色。
+- 自己寫的區塊不要另外加陰影，改用 `UI.Card`；需要分出一塊時用 `surface-sub` 底色或分隔線。
+- `title` 和 `actions`：標題列，左邊標題，右邊按鈕。
+- `padding: false`：沒有內距，給整張卡片放表格或樹狀清單時用。
+
+```js
+h(UI.Card, { title: '流程', actions: h(UI.Button, { icon: 'magnifying-glass' }, '換起點函式') },
+  h(UI.Tabs, { … }),
+  h(UI.TreeList, { kind: 'plain', items, height: 640 }))   // 沒有自己的陰影
+```

package/docs/Checkbox.md

@@ -0,0 +1,8 @@
+# Checkbox
+
+勾選框。
+
+- 方框 22 px，小圓角（`radius-sm`），未勾選時 2 px `line-strong` 邊框。
+- 勾選後強調色實心，白色勾號以描繪動畫（200 ms）畫出；`checked="mixed"` 顯示橫線。
+- 整列（框加文字）都可以點，高度 40 px。
+- 鍵盤 focus 時方框加 `focus-ring` 光暈。

package/docs/CodeView.md

@@ -0,0 +1,21 @@
+# CodeView
+
+有行號的程式碼檢視，用在詳細卡片的原始碼、檢查筆記的引用。
+
+- 行號：灰色等寬數字靠右，沒有底色和分隔線。可以選取複製程式碼，不會連行號一起複製。
+- 目標行（`target`，一行或 `[from, to]`）：淡強調色底，左側 3 px 強調色細條，行號變粗。有 `maxHeight` 時會自動捲到目標行。
+- 太長的行自動換行，續行縮排 4 個字元寬，不用橫向捲動。
+- 語法上色：關鍵字藍、常數與字串綠、註解灰色斜體，其他是文字顏色。語言看 `file` 的副檔名（c、h、cpp、js、ts、py、sh），或用 `language` 指定；`highlight={false}` 關掉。內建的上色只認這幾種語言；其他語言給 `tokenizer`，把每行切成 `[class, 文字]`（class 是 `is-keyword`、`is-constant`、`is-comment`、`is-string` 或空字串）。
+- 手機上（寬度小於 600 px）只顯示目標行前後 2 行（`context`），下方「顯示全部 N 行」。
+- 標題列：`file` 顯示路徑，給 `fileHref` 或 `onFile` 變成連結；右邊寫語言。沒有檔案時可以給 `title`。
+
+```js
+h(UI.CodeView, {
+  file: 'src/libibtrace/hooks/ops.c',
+  fileHref: '#/file/ops.c',
+  code: source,
+  start: 70,
+  target: 74,
+  maxHeight: '420px',
+});
+```

package/docs/CommandPalette.md

@@ -0,0 +1,30 @@
+# CommandPalette
+
+一個搜尋找全部：頁面、設定、指令、檔案，以及專案自己的種類。任何頁面按 Ctrl K（Mac 是 ⌘K）都能打開。
+
+- 入口：電腦上是 TopBar 的填色搜尋框，手機上（小於 600 px）TopBar 自動換成搜尋圖示。兩者都把 `onSearch` 接到打開面板。
+- 樣子：畫面中間浮起的面板，電腦寬 640 px；手機上也置中浮起，左右各留 12 px，在頂部列下方，高度最多 55% 螢幕，留位置給鍵盤。
+- 結果：所有種類混在一起，名稱開頭符合的排前面，再來是名稱中間符合，最後是說明或關鍵字符合；同分照資料原本的順序。最多顯示 50 筆。
+- 每一筆：左邊是種類圖示，名稱（符合的字粗體），下面一行次要文字的說明。名稱是程式碼（函式、路徑、變數）時給 `code: true`，改用 Geist Mono；說明裡的程式碼用反引號包起來。
+- 種類圖示：內建 `頁面` `file-text`、`設定` `gear`、`指令` `command`、`檔案` `file-code`；專案自己的種類用 `kinds` 指定（例如 `{ 函式: 'brackets-curly', 環境變數: 'terminal-window' }`），或每筆的 `icon`。`items` 的型別可以加自己的欄位，`onSelect` 收到的是同一個型別。
+- 還沒輸入時顯示 `recent`（「最近開啟」）；沒有就顯示提示。找不到時寫「找不到符合「x」的結果」。
+- 鍵盤：↑ ↓ 選擇，Enter 打開，Esc 或「取消」關閉；面板底部寫這三個按鍵，觸控裝置不顯示。關閉後 focus 回到原本的位置。
+- 資料要從伺服器搜尋時給 `filter: false`，在 `onQueryChange` 裡更新 `items`，等待時給 `loading`。
+
+```tsx
+const [open, setOpen] = React.useState(false);
+
+<TopBar title="專案" onSearch={() => setOpen(true)} />
+<CommandPalette
+  open={open}
+  onOpenChange={setOpen}
+  placeholder="搜尋頁面、專案、設定"
+  kinds={{ 專案: 'folder' }}
+  items={[
+    { id: 'p1', kind: '專案', label: 'api-gateway', detail: '最後部署 `v2.4.1`' },
+    { id: 's1', kind: '設定', label: '通知', detail: '部署失敗時寄 Email' },
+    { id: 'g1', kind: '頁面', label: '成本報表' },
+  ]}
+  onSelect={(item) => go(item.id)}
+/>
+```

package/docs/DangerZone.md

@@ -0,0 +1,10 @@
+# DangerZone
+
+危險操作區塊：設定頁最下方的紅框區塊。
+
+- 紅色 1 px 外框，標題用 `danger-text`。
+- 左邊一句說明後果，右邊紅色實心按鈕；`confirm`（必填）是確認框的標題和說明，確認後才執行 `onAction`。
+
+```tsx
+<DangerZone description="刪除後，所有專案和資料都無法復原。" actionLabel="刪除帳號" confirm={{ title: '刪除帳號？' }} onAction={deleteAccount} />
+```

package/docs/DataTable.md

@@ -0,0 +1,77 @@
+# DataTable
+
+資料表格，有排序、勾選、篩選和分頁。
+
+## 外觀
+
+- 表頭：灰底（`surface-sub`）粗體 14 px，往下捲動時固定在上方。
+- 列高 48 px。
+- 分隔：斑馬紋加格線。偶數列用 `surface-sub`，每列之間有橫線，欄之間有直線，外圍有框，全部用 `line`。
+- 滑過列：整列變成強調淺底 `accent-soft`；勾選中的列也用 `accent-soft`。
+- 數字欄 `numeric: true`：Geist Mono、等寬數字、靠右對齊。
+- 單位寫在每格數字後面：欄位設定 `unit`，例如 `unit: 'GB'` 會顯示「3,480.3 GB」。表格裡的數字不縮寫。
+- 欄位格式 `format`：`money`（NT$ 1,280,000）、`date`（2026/11/04（三））、`datetime`、`relative`（一週內寫「2 小時前」）、`percent`（一位小數，% 用 `unit: '%'` 加上，和 KpiCard 一樣）。
+- 狀態欄使用 Badge。
+- 欄位標題不換行；欄寬至少要放得下標題和排序箭頭（`width` 設最小寬度），放不下時表格橫向捲動，底色延伸到最右邊。
+
+## 排序
+
+- 點欄位標題排序。第一下：文字欄從小到大，數字欄從大到小；第二下：反過來；第三下：還原成原本的順序。
+- 排序箭頭滑過標題才顯示；正在排序的欄位一直顯示箭頭，標題變成 `accent-text`。
+- 不能排序的欄位設 `sortable: false`；排序依據和顯示內容不同時用 `sortValue`。
+
+## 勾選與操作
+
+- `selectable`：勾選框平常隱藏，滑過列（或用鍵盤移到列上）才出現；勾了任一筆後所有列都顯示。觸控裝置一直顯示。
+- 勾選後，表頭換成批次操作列：全選框、「已選 n 筆」、`bulkActions` 的按鈕、取消選取 ×。
+- 篩選、搜尋、檢視或摘要改變後看不到的列會自動取消勾選，刪除的列也一樣，所以 `bulkActions` 只處理畫面上留下的列（換頁不影響）。
+- 單筆操作 `rowActions`：放 IconButton，滑過列時出現在最右邊（例如編輯、刪除）。刪除一樣要先跳確認對話框。
+
+## 搜尋與篩選
+
+- 搜尋框搜所有欄位，符合的文字用黃底標出（`mark`）。只想搜部分欄位時用 `search.keys`；用 `render` 的欄位提供 `searchText`。
+- 篩選：搜尋框旁邊的「篩選」按鈕，按鈕上顯示已套用的條件數。點開是彈出框，`filters` 裡的每個欄位一區：
+  - `type: 'list'`：勾選清單，每個選項後面寫套用後會剩幾筆；沒給 `options` 時從資料取出。
+  - `type: 'range'`：最低、最高兩個欄位；`scale` 是輸入單位（例如 10000 代表「萬」），`unitLabel` 寫在下方。
+- 勾選就生效，不需要「套用」按鈕。彈出框右上角有「清除全部」。
+- 搜尋框右邊顯示「10 / 24 筆」。
+- 沒有結果時顯示一句話，再加「清除篩選」按鈕。
+- 條件寫進網址（`?status=doing,review&q=…`），重新整理或分享連結時保留；同一頁有兩個表格時用 `urlKey` 分開；`urlSync={false}` 關掉。
+- 換成另一份資料（例如切換專案）時，給新的 `resetKey`：搜尋、篩選、排序、頁碼、勾選和摘要都回到預設。只換內容、條件要保留時不用給。
+- 分頁：頁碼，每頁 10 筆（`pageSize`），左下顯示「第 1–10 筆，共 24 筆」。
+
+## 看情況決定的功能
+
+這幾項沒有固定規定，依資料決定要不要開：
+
+- 同一欄位能不能選多個：預設可以（`multiple: true`），選項互斥時（例如「本月／上個月」）設 `multiple: false`。
+- 合計列 `totals`：有金額或數量需要加總時才開，例如 `{ budget: 'sum', progress: 'avg' }`；第一欄自動寫「合計 n 筆」。
+- 固定第一欄 `stickyFirst`：欄位多、常需要橫向捲動時才開。
+- 常用檢視 `views`：有幾組固定的看法（例如「我負責的」、「本週到期」）時才開，表格上方變成分頁，旁邊寫筆數。
+
+## 欄位顯示
+
+- 工具列右邊的「欄位」按鈕可以隱藏或顯示欄位，第一欄不能隱藏。`columnMenu={false}` 關掉。
+
+## 動畫
+
+- 排序：留在本頁的列由上往下依序滑到新位置，每列 320 ms，間隔 25 ms；底色跟著從舊位置的顏色轉成新位置的顏色。還原（第三下）用同樣的動畫。
+- 排序後被換到其他頁的列往下滑出並淡出，從其他頁換進來的列從下方滑上來並淡入。
+- 換頁：下一頁時整頁往上滑出、新的一頁從下方滑進來；上一頁相反。
+- 減少動態效果時不播放這些動畫。
+
+## 結果摘要
+
+- `summary={{ key, items: [{ value, label }] }}`：表格上方放一個分段控制（Tabs），「全部」加上每種狀態，各自附筆數，點了就只看那一種。用在檢查結果、審核清單這類有狀態的清單。
+- 排序看情況：結果清單預設照資料原本的順序（例如筆記的行號），不自動把錯誤排到前面；需要處理的項目用摘要篩選出來。
+
+## 手機
+
+- 寬度小於 600 px 時，所有列放在同一張卡片裡，列與列之間用分隔線。
+- 每一列：第一行是標題列，左邊是標題欄位，右邊是狀態欄位，最右邊是操作按鈕（`rowActions`）；其他欄位往下堆疊，欄位名稱在上（12 px 次要文字）、值在下，全部靠左，欄位之間 4 px。
+- 欄位用 `mobile` 指定：`'title'`（標題列左邊，預設是第一欄）、`'status'`（標題列右邊）、`'hide'`（手機不顯示）。
+- 長文字欄位設 `long: true`：卡片上最多 2 行，超過時下方出現「顯示全部」；桌機時一行，超過用「…」。
+- 卡片裡的 Badge 自動改成「圓點加文字」：沒有底色和陰影，文字用該狀態的文字色。
+- 勾選框在標題列最左邊，一直顯示；操作按鈕一直顯示，不用滑過。
+- 工具列維持一行：搜尋框佔剩下的寬度，接著「篩選」和筆數；「欄位」按鈕在手機上不顯示。
+- 筆數和頁碼文字只有數字用 Geist Mono，「筆」等文字用一般字體；有單位的數字欄也一樣（「1 層」）。

package/docs/DatePicker.md

@@ -0,0 +1,7 @@
+# DatePicker
+
+單一日期：可以直接輸入，也可以點右邊的日曆圖示選。
+
+- 格式 YYYY/MM/DD，等寬字；打錯時框變紅並寫出正確格式。
+- 日曆一週從週日開始；選中的日期是強調色圓角方塊，今天下方有一個小圓點。
+- 日曆下方有「今天」和「清除」；點外面或按 Esc 關閉。

package/docs/DateRangePicker.md

@@ -0,0 +1,7 @@
+# DateRangePicker
+
+日期範圍：一個月曆加上左側的快捷範圍。
+
+- 快捷：今天、最近 7 天、最近 30 天、本月、上個月。
+- 在月曆上先點開始日、再點結束日；中間的日期用強調淺底連起來。
+- 樣式和 DatePicker 相同：圓角方塊、今天下方圓點、週日開始。

package/docs/DetailList.md

@@ -0,0 +1,17 @@
+# DetailList
+
+一個項目的詳細欄位，例如選取的函式、訂單、使用者。
+
+- 寬度 600 px 以上：欄位名稱在左（13 px 次要文字，不換行）、值在右。
+- 比較窄時：名稱在上、值在下，全部靠左，和手機表格卡片一致。依照元件本身的寬度切換。
+- 值可以放任何元素：`UI.InlineCode` 連結、`UI.Tag`、`UI.Badge`。
+
+```js
+h(UI.DetailList, {
+  items: [
+    { label: '定義', value: h(UI.InlineCode, { href: '/code/ops.c#L55' }, 'src/libibtrace/hooks/ops.c:55') },
+    { label: '元件', value: 'src/libibtrace' },
+    { label: '關係', value: '1 個 caller · 呼叫 4 個函式' },
+  ],
+});
+```

package/docs/Dialog.md

@@ -0,0 +1,15 @@
+# Dialog
+
+需要使用者決定時跳出的視窗，置中顯示。
+
+- 寬 400 px，背景 20% 黑色加模糊。
+- 給 `open` 和 `onClose`：焦點鎖在框內，Esc、點背景、右上角 × 都會關閉，關閉後焦點回到原本的按鈕。一定要給 `open`，不要用 `{show && <Dialog …>}` 控制顯示。只要畫出框本身（文件和預覽用）時給 `modal={false}`。
+- 標題寫要決定的事，可以是問句：「刪除 api-gateway？」。內容最多兩句：會發生什麼、能不能復原。
+- 按鈕：給 `confirmLabel` 和 `onConfirm`，會自動排好「取消」（次要，左）和確認按鈕（右）；`tone="danger"` 時確認按鈕是紅色。要自己排按鈕時給 `actions`。
+- 刪除這類動作通常不用自己開 Dialog：Button、Menu、DangerZone 給 `confirm` 就會跳出這個框。
+
+```tsx
+<Dialog open={open} onClose={() => setOpen(false)} title="發布 v2.4.1？" confirmLabel="發布" onConfirm={publish} confirmLoading={publishing}>
+  發布後使用者會立刻看到新版本。
+</Dialog>
+```

package/docs/Drawer.md

@@ -0,0 +1,22 @@
+# Drawer
+
+側邊抽屜：從右邊滑出的編輯面板，用來編輯一筆資料而不離開列表。
+
+- 寬 400 px（和對話框同寬），滿版高度，底色 `surface`。
+- 背景：模糊遮罩，和對話框一致；點遮罩、按 Esc 或右上角 × 關閉。
+- 滑入：彈性滑入，450 ms，滑過頭一點再彈回；關閉時 300 ms 滑出。減少動態效果時只淡入淡出。
+- 按鈕固定在底部：次要（取消）在左、主要（儲存）在右；內容太長時只有中間捲動。
+- 有未儲存的修改（`dirty`）時關閉，先跳「放棄未儲存的變更？」，按鈕是「繼續編輯」和紅色「放棄」。
+- 底部的「取消」也要先確認：`actions` 寫成函式，拿到的 `requestClose` 和 × 走同一個確認。
+
+```tsx
+<Drawer open={open} dirty={dirty} onClose={close} title="編輯專案"
+  actions={(requestClose) => (
+    <>
+      <Button onClick={requestClose}>取消</Button>
+      <Button variant="primary" onClick={save}>儲存</Button>
+    </>
+  )}>
+```
+
+- 打開時焦點移到第一個欄位，關閉後回到打開它的按鈕。

package/docs/EmptyState.md

@@ -0,0 +1,6 @@
+# EmptyState
+
+沒有資料時的畫面，用引導步驟告訴使用者怎麼開始。
+
+- 步驟下方放一個次要按鈕（Button `secondary`）。
+- 搜尋沒有結果時只顯示一句話：只傳 `title`，不傳 `description` 與 `steps`。

package/docs/ErrorPage.md

@@ -0,0 +1,7 @@
+# ErrorPage
+
+錯誤頁：404、500、403。
+
+- 大號錯誤碼：等寬字 96 px，用強調文字色；下面是標題和一句說明。
+- 按鈕：「回上一頁」（次要）和「回首頁」（主要）。
+- 預設文字：404 找不到這個頁面；500 伺服器暫時無法回應；403 沒有權限查看這個頁面。可以用 `title`、`description` 改。

package/docs/FileUpload.md

@@ -0,0 +1,9 @@
+# FileUpload
+
+檔案上傳：一行拖放區，下方列出檔案與進度。
+
+- 拖放區是一行虛線框：「拖放檔案，或 選擇檔案」，限制（類型、大小）寫在拖放區右邊（`limitText`）。
+- 拖到上方時框變強調色、底色變淺。
+- 每個檔案：名稱、大小、8 px 進度條（百分比在下方），完成時變綠並顯示「完成 ✓」。
+- 失敗：檔案外框變紅，下方紅字寫原因加修正方式，旁邊有「重試」。
+- 上傳本身由你實作：用 `onAdd` 收到檔案，更新 `files` 裡的 `progress`、`status`（`uploading`、`done`、`error`）。

package/docs/FormGrid.md

@@ -0,0 +1,7 @@
+# FormGrid
+
+表單欄位排列。
+
+- 寬度 960 px（`bp-desktop`）以上雙欄，以下單欄。
+- 需要整行的欄位（例如多行輸入）加 `className="is-full"` 跨滿兩欄。
+- 標籤一律在欄位上方。

package/docs/Format.md

@@ -0,0 +1,27 @@
+# Format
+
+日期、時間、數字、金額的格式，以及介面文字的語系。所有元件都透過 `UI.format` 和 `UI.t` 輸出，不要自己拼字串。
+
+## 規則（zh-TW）
+
+- 日期：`2026/11/04（三）`，年份一律顯示，加星期。`UI.format.date(d)`；不要星期時傳 `{ weekday: false }`。
+- 時間：24 小時制 `15:57`。`UI.format.time(d)`、`UI.format.dateTime(d)`。
+- 相對時間：一週內用「2 小時前」、「昨天」、「3 天前」；超過一週寫完整日期時間。`UI.format.relative(d)`。
+- 大數字：只有 KPI 卡片縮寫，單位用萬、億（`1,284 萬`）；表格和明細寫完整數字。`UI.format.compact(v)`。
+- 金額：`NT$ 1,280`，負數用減號 `-NT$ 1,280`。`UI.format.money(v)`。
+- 小數位數依單位：金額 0 位、百分比 1 位、容量（GB、MB）1 位、數量 0 位。`UI.format.number(v, 'money' | 'percent' | 'size' | 'count')`。
+- 日期輸入框一律用 `YYYY/MM/DD`，不分語系，避免月日順序看錯。
+
+## 國際化（i18n）
+
+- 介面文字以繁體中文為原文，經過 `UI.t()` 輸出；其他語言用 `UI.addMessages(locale, { 原文: 譯文 })` 提供。已內建英文（`en`）。
+- 有變數的句子用整句加佔位符，不要把句子拆開拼：`UI.t('已選 {n} 筆', { n: 3 })`，英文是 `{n} selected`。不同語言的字序不同。
+- 切換語系：`UI.setLocale('en-US', { currency: 'USD' })`，會設定 `<html lang>`；之後重新渲染畫面。
+- 寫新元件時：按鈕、提示、`aria-label` 的文字都要經過 `UI.t()`。
+
+## 在地化（L10n）
+
+- 上面的格式規則是 zh-TW 的選擇。其他語系使用該語系自己的習慣（透過瀏覽器的 `Intl`）：英文是 `Wed, 11/04/2026`、`3:57 PM`、`12.8M`、`$486,000`；德文用 `04.11.2026`、`3.480,3`。
+- 一週的第一天：zh-TW 是週日；其他語系依瀏覽器提供的地區資訊（例如德文從週一開始）。
+- 幣別跟著資料走，不跟著語系：同一筆台幣金額，在英文介面顯示 `NT$486,000`。
+- 文字長度：英文、德文通常比中文長 1.5 到 2 倍，按鈕和欄位標題要留空間；標題不換行的規則不變，放不下就讓表格橫向捲動。

package/docs/Graph.md

@@ -0,0 +1,31 @@
+# Graph
+
+方框與箭頭的圖的樣式：自己畫 SVG，套用這些 class，再加 `UI.GraphDefs` 和 `UI.GraphLegend`。
+
+元件架構圖請直接用 `UI.LayerGraph`，它會自己排版和畫線。這裡的 class 給其他種類的圖用。
+
+- 外層加 `ui-graph`，`<svg>` 裡第一個放 `h(UI.GraphDefs)`，提供箭頭 `url(#ui-arrow)` 和強調色的 `url(#ui-arrow-accent)`。
+- 線：`<path class="ui-graph-edge">`，1.5 px、`graph-edge` 灰色，直角轉彎（`M x y V … H … V …`）。推測的關係加 `is-inferred`，變成虛線。
+- 方框：`<rect class="ui-graph-node" rx="10">`，名稱用 `<text class="ui-graph-name">`（Geist Mono 13 px）。外部的項目加 `is-external`（虛線外框、不填色），選取的加 `is-selected`。
+- 線上的標籤：`<text class="ui-graph-label">`（12 px 粗體，一般字體）。程式名稱、路徑和數字包在 `<tspan class="ui-graph-code">` 裡，用 Geist Mono，例如「`<tspan class="ui-graph-code">8</tspan> 次呼叫`」。外圍描一圈卡片底色，線從字後面穿過仍看得清楚。放在線的旁邊或轉角附近，不要蓋住箭頭。
+- 選取時：沒有關係的方框和線包在 `<g class="is-dim">` 裡（淡到 40%），相關的線加 `is-related`（強調色，箭頭改用 `#ui-arrow-accent`），標籤也加 `is-related`。
+- 圖例：`<GraphLegend />` 放在圖的下方，預設三項：確定的關係、推測的關係、外部項目。用 `items` 換成專案自己的說法（例如「呼叫」「推測的呼叫」「外部函式」），給 `text` 會變成可以點開說明的 Term。
+- 圖放在卡片（`surface`）上。直接放在頁面底色上時，外層加 `style: { '--ui-graph-bg': 'var(--bg)' }`，標籤的描邊才會和底色一致。
+- 深色模式的線和外框自動變亮。顏色只用 token：`graph-edge`、`graph-node`、`accent`、`accent-soft`。
+
+```js
+h(
+  'div',
+  { className: 'ui-graph' },
+  h(
+    'svg',
+    { viewBox: '0 0 640 300', width: 640, height: 300 },
+    h(UI.GraphDefs),
+    h('path', { d: 'M320 56 V80 H320 V118', className: 'ui-graph-edge is-inferred is-related', markerEnd: 'url(#ui-arrow-accent)' }),
+    h('text', { x: 320, y: 100, textAnchor: 'middle', className: 'ui-graph-label is-related' }, 'LD_PRELOAD'),
+    h('rect', { x: 230, y: 120, width: 180, height: 40, rx: 10, className: 'ui-graph-node is-selected' }),
+    h('text', { x: 320, y: 140, textAnchor: 'middle', dominantBaseline: 'central', className: 'ui-graph-name' }, 'trace_post_send'),
+  ),
+  h(UI.GraphLegend),
+);
+```

package/docs/Grid.md

@@ -0,0 +1,18 @@
+# Grid
+
+頁面內容的排版：`Page` 把區塊上下排開，`Grid` 把卡片排成等寬的欄。不要自己寫 CSS grid。
+
+- `Page`：區塊之間 32 px（`space-8`）。
+- `Grid`：卡片之間 24 px（`space-6`），手機 16 px。`columns` 是 1280 px 以上的欄數（1、2、3、4、6）；1280 px 以下 4 欄變 2 欄、6 欄變 3 欄；960 px 以下最多 2 欄；手機一欄。
+
+```tsx
+<Page>
+  <Grid columns={4}>
+    <KpiCard label="本月營收" value={12840000} format="money" />
+    <KpiCard label="進行中專案" value={18} unit="個" />
+  </Grid>
+  <Card title="專案" padding={false}>
+    <DataTable columns={columns} rows={rows} />
+  </Card>
+</Page>
+```