@seanyeh77/ui 0.0.0-stage → 0.3.0

package/docs/guidelines.md

@@ -0,0 +1,269 @@
+# 前端設計系統
+
+暖灰中性色、單一藍色強調，Inter 搭配思源黑體，等寬字 Geist Mono 只當點綴。淺色與深色兩套主題，主題可自動跟隨系統或手動切換，強調色可由使用者自訂。
+
+這份文件只記錄已經確認的選擇。
+
+## 色彩
+
+已確認的選擇：
+
+- 中性色調：暖灰。
+- 淺色主題底色：極淺灰。
+- 深色主題底色：深灰。
+- 卡片分層：陰影。
+- 卡片裡不放卡片，避免多層陰影。區塊用 `Card`；TreeList、KpiCard、Alert、SettingsSection 本身就是卡片，單獨使用時不要再包一層，放進 `Card` 時會自動拿掉自己的陰影。卡片裡要再分區時，用 `surface-sub` 底色或分隔線。
+- 強調色：預設 `#2457d6`，使用者可以自訂，不限定顏色。
+- 強調色用量：中量，用在主要按鈕、連結、圖示、標籤與選取狀態。
+- 語意色：配合強調色的飽和度。
+- Tailwind：只用設計系統的 token class（`bg-surface`、`text-ink-muted`、`rounded-md`、`shadow-card`）；Tailwind 內建的顏色、圓角和陰影（`text-gray-500`、`rounded-xl`、`shadow-lg`）由 ESLint 規則 `no-tailwind-defaults` 抓出來。
+
+主題設定有三個選項：自動（跟隨系統的 `prefers-color-scheme`）、淺色、深色。頁面根元素設 `data-theme="light"` 或 `"dark"`。
+
+| 用途 | Token |
+|---|---|
+| 頁面底色 | `bg` |
+| 卡片、面板、對話框 | `surface` + `shadow-card` |
+| 次要底色（斑馬紋、灰底元件、骨架） | `surface-sub` |
+| 頂部列、側邊欄、底部分頁列 | `surface-chrome` |
+| 主要文字、次要文字 | `ink`、`ink-muted` |
+| 分隔線、控制項邊框 | `line`、`line-strong` |
+| 強調色與它的滑過、按下 | `accent`、`accent-hover`、`accent-press` |
+| 強調文字、強調淺底、強調色上的文字 | `accent-text`、`accent-soft`、`on-accent` |
+| 語意色 | `success`、`warning`、`danger` 各有實色、`-text`、`-soft`；資訊用 `info-text`、`info-soft` |
+
+文字 token 在兩套主題都對它的底色達到 4.5:1；`line-strong` 對 `surface` 達到 3:1。
+
+### 自訂強調色的換算
+
+使用者換強調色時，其他強調相關 token 依下列方式重新計算：
+
+- `accent-hover`、`accent-press`：強調色混入 12% 與 22% 黑色。
+- `accent-soft`：淺色主題為白色混入 12% 強調色；深色主題為 `bg` 混入 22% 強調色。
+- `accent-text`：深色主題混入白色，直到對 `surface` 達 4.5:1。
+- `on-accent`：白色與 `ink` 中對比較高者。
+- 語意色：飽和度跟隨強調色。
+
+## 字體與排版
+
+已確認的選擇：
+
+- 搭配方式：無襯線為主，等寬字只用在標籤與數字。
+- 無襯線：Inter，中文用思源黑體（Noto Sans TC），對應 `sans`。
+- 等寬：Geist Mono，對應 `mono`。
+- 內文 16 px，字級比例 1.25，內文行高 1.65，標題字重 700，中文字距 0。
+- 表格數字：等寬數字。
+- 字型檔內附在 `dist/fonts.css`（Inter、Geist Mono、Noto Sans TC，字重 400 到 700），不從 Google Fonts 載入，離線或內網也能用；瀏覽器只下載頁面用到的字。
+
+## 間距、圓角與陰影
+
+- 密度：緊密。區塊間距 `space-8` 32 px。
+- 圓角：中圓角，`radius-sm` 6 px、`radius-md` 10 px、`radius-lg` 14 px。
+- 表面：柔和陰影，`shadow-card`。
+
+## 圖示
+
+- 圖示組：Phosphor（MIT 授權，可商用），平常用 Regular 線條版。
+- 選中時換成同一個圖示的實心版（Fill）並用強調色，例如側邊欄和手機底部分頁列的選中項目。
+- 線寬：Phosphor 的線寬固定，不另外調整；自訂的 24 × 24 線條圖示用 2 px（`icon-stroke`）。
+- 尺寸：按鈕、表格、輸入框裡 20 px；側邊欄與手機底部分頁列 22 px；選單與小標記 16 px。
+- 用法：`h(UI.Icon, { name: 'house' })`，加 `filled: true` 用實心版；名稱照 Phosphor，常用的 80 個已內建，`icons` 列出全部名稱（也接受 Lucide 的名稱，例如 `trash-2`）。
+- 目前沒有 logo：以文字名稱加一個 `accent` 色方塊暫代。
+
+## 元件
+
+已確認的選擇：
+
+- 主要按鈕：實心。
+- 次要按鈕：外框。
+- 按鈕與輸入框高度：40 px（`control-height`）。寬度小於 600 px 時，輸入框（文字、下拉、日期、密碼、多選）變成 48 px，整個框都是點擊範圍；按鈕外觀仍是 40 px。
+- 輸入框：外框。
+- Focus：外光暈。
+- 欄位錯誤：紅框加圖示。
+- 停用：灰底灰字。
+- 主要按鈕：每個區塊最多一個。
+- 危險按鈕：頁面上用實心紅色，按下後先跳確認對話框。
+- 觸控點擊範圍：48 px（`touch-target`）。觸控螢幕上每個按鈕、分頁、開關和連結的外觀不變，點擊範圍自動擴大到至少 48 × 48 px。
+  - 例外：句子裡的文字連結和名詞說明（句中的 `Term` 和 InlineCode 連結）。Term 會自己判斷：旁邊有文字就是句中；單獨出現時（例如 Tag 裡的關係標籤、圖例）照樣擴大到 48 px，照 WCAG 2.2 的行內例外，不擴大，以免蓋到上下行。
+- Badge：浮起 Chip，前置標記為進度圓圈，5 種狀態，高度 32 px（`chip-height`），文字用主要文字色。放在卡片上時改成圓點加文字（沒有底色和陰影，文字用狀態文字色）。
+- Alert：頂部色條（3 px，`alert-bar`），只有資訊與成功可以關閉，動作用外框按鈕。
+- 表格：灰底粗體表頭（捲動時固定）；列高 48 px；斑馬紋加格線；滑過列用強調淺底（`accent-soft`）；數字靠右；單位寫在每格數字後面；欄位標題不換行；排序箭頭滑過才顯示，點第三下還原；勾選框滑過才顯示，勾選後表頭換成批次操作列；換篩選、搜尋、檢視或摘要後看不到的已選列自動取消勾選，批次操作只處理畫面上的列；單筆操作滑過才顯示圖示；搜尋所有欄位並標示，「篩選」按鈕（按鈕上顯示條件數、勾選就生效、選項旁有筆數），右側顯示結果筆數，沒有結果時加「清除篩選」，條件寫進網址，可以隱藏欄位；合計列、固定第一欄、常用檢視、同一欄位多選依情況決定；頁碼分頁。手機寬度（小於 600 px）時，所有列放在同一張卡片裡用分隔線隔開；每列第一行是標題列（標題欄位加狀態），其他欄位名稱在上（12 px）、值在下並靠左，欄位之間 4 px；操作按鈕放在標題列最右邊；長文字最多 2 行加「顯示全部」；手機工具列不顯示「欄位」按鈕。
+- 結果清單：上方用分段控制當摘要（全部加各狀態，附筆數），點了就篩選；排序看情況，預設照資料原本的順序。
+- 載入：骨架，立即顯示（延遲 0 ms）。
+- 空狀態：引導步驟，下方放次要按鈕；搜尋沒有結果時只顯示一句話。
+- Toast：右下角，卡片樣式，3 s 後消失，附「復原」。
+- 對話框：置中，寬 400 px，背景模糊；可以點遮罩、按 Esc 或右上角 × 關閉；按鈕次要在左、主要在右；危險動作用紅色實心按鈕。Dialog 一定要給 `open`；只有文件裡的靜態預覽寫 `modal={false}`，兩個都沒寫時開發主控台警告。
+- DangerZone 沒給 `confirm` 時也先確認，標題是「<按鈕文字>？」。
+
+## 表單
+
+- 勾選框：小圓角（`radius-sm`），勾選後強調色實心，勾號用描繪動畫畫出來；所有勾選框（包括表格的欄位選單、篩選和多選的選項）都用同一個勾。
+- 單選：選中時外圈變強調色，中間出現圓點。
+- 開關：Material 3 樣式，滑動用水滴動畫，圓鈕裡放勾（開）與叉（關）。
+- 下拉選單：一律不用瀏覽器原生選單。依內容決定：選項超過 8 個時加上搜尋框（可搜尋選單），8 個以內用自訂選單；個別選單可以手動指定。選單向下展開。
+- 搜尋欄：外框，左邊放放大鏡圖示，有內容時右邊出現清除鈕（隱藏瀏覽器內建的清除鈕）。
+- 多行輸入：顯示字數（例如 `12 / 200`），隨內容自動長高，最多 8 行。
+- 標籤：放在欄位上方。
+- 必填：標籤後加紅色星號。
+- 欄位排列：依螢幕寬度決定，960 px 以上雙欄，以下單欄（`FormGrid`）；長欄位（例如多行輸入）跨滿兩欄。
+
+## 外觀
+
+- 主題與強調色放在設定頁的「外觀」，不放在頂部列。
+- 主題：自動、淺色、深色三張預覽卡片（`ThemePicker`）。
+- 強調色：8 個推薦色票，加上可以輸入任何色碼的欄位（`AccentPicker`）。
+- 切換主題時，所有顏色用 300 ms 漸變。
+
+## 通知
+
+- 頂部列的鈴鐺有紅色數字角標，超過 99 顯示 99+。
+- 點鈴鐺從下方彈出通知面板（360 px）；依時間分組（今天、更早）；未讀在左側有強調色圓點；「全部標為已讀」在面板標題列右側。
+
+## 頁面範本
+
+- 錯誤頁：大號錯誤碼（等寬字、強調色），標題加一句說明，「回上一頁」和「回首頁」兩個按鈕。
+- 登入頁：置中卡片；只有帳號密碼；密碼可以切換顯示；錯誤寫在欄位下方；「忘記密碼？」在密碼標籤右邊。
+- 設定頁：左側分類；改完自動儲存，右下角提示「已儲存」；危險操作放在最下方紅框區塊。
+
+## 格式規則
+
+- 日期 `2026/11/04（三）`：年份一律顯示，加星期；時間 24 小時制；一週內用相對時間（「2 小時前」、「昨天」）。
+- 大數字只有 KPI 卡片縮寫（萬、億）；金額 `NT$ 1,280`；負數用減號；小數位數依單位（金額 0、百分比 1、容量 1）。表格和 KPI 卡片的 `percent` 只決定一位小數，% 一律用 `unit: '%'` 加上。
+- 行內程式碼：句子裡的程式碼、檔案路徑和 ID 用淺灰底等寬字（`InlineCode`，底色 `surface-sub`）；指向檔案位置的（例如 `child.c:86`）是連結，強調文字色加底線。含反引號的文字用 `CodeText` 轉換，不顯示反引號。
+- 檔案大小 `format.fileSize()`：未滿 1 MB 寫整數 KB（「186 KB」），以上寫一位小數的 MB 或 GB（「54.9 MB」）。
+- 介面文字都經過 `t()` 可以翻譯；日期和數字都經過 `format`，其他語系自動用該語系的習慣。細節見元件「Format」。
+
+## 浮層
+
+- 提示：深色，在元素上方，有箭頭；滑過或 focus 立刻出現（0 ms）；從箭頭那一側放大出現。IconButton 的 `label` 會自動成為提示。
+- 「⋯」選單：右緣對齊按鈕；選項是圖示、文字加快捷鍵；危險選項紅字放最後，前面加分隔線；從按鈕的角落放大打開。
+- 彈出框：滑過打開（點擊和鍵盤也能打開）；點外面或按 Esc 關閉；有箭頭。
+- 側邊抽屜：寬 400 px，模糊遮罩，彈性滑入；按鈕固定在底部；有未儲存的修改時，關閉前先確認，底部的「取消」也一樣（`actions={(requestClose) => …}`）。
+- 出界時換方向：選單、彈出框和提示在預設方向放不下時，改用另一個方向（右緣對齊改左緣、下方改上方、上方改下方）。
+
+## 進階表單
+
+- 日期：輸入框可以直接打字（YYYY/MM/DD），右邊的圖示打開日曆；選中的日期是圓角方塊；今天下方有小圓點；一週從週日開始。
+- 日期範圍：單一月曆加快捷（今天、最近 7 天、最近 30 天、本月、上個月）。
+- 手機上（寬度小於 600 px）：日期格 48 px，期間選擇的快捷移到月曆上方。
+- 檔案上傳：一行拖放區，限制寫在拖放區裡；每個檔案有進度條；失敗時紅字寫原因並提供「重試」。
+- 多選：標籤放在框內，顯示前 2 個再加「+n」；能不能新增選項依情況決定：選項由使用者自由增加的（名稱、標籤）可以新增，固定清單（狀態、權限）只能從清單選。
+
+## 數據呈現
+
+- KPI 卡片：標籤、大數字、迷你折線（近期趨勢）、和上一期比的變化。數字 31 px、Geist Mono；單位放在數字後面。
+- 變化標示：箭頭加彩色文字，後面接灰色「較上週」。顏色看好壞、不看方向：例如回應時間下降是好事，用綠色。
+- 數字進場：從 0 數上來（900 ms）。
+- 圖表配色：多色，依序 `chart-1` 藍、`chart-2` 青、`chart-3` 橘；只有一組資料時用 `chart-1`。
+- 折線：平滑曲線，不填色。
+- 長條：頂部 4 px 圓角。
+- 格線：淡色虛線（`line`）；底線用實線。
+- 數值提示：滑過時出現浮起卡片（`surface` 加 `shadow-overlay`），折線圖同時顯示垂直參考線和各組的點。
+- 圖表進場：依序長出：折線一條接一條畫出（間隔 150 ms），長條一根接一根長高（間隔 40 ms）。
+- 進度條：8 px，百分比寫在條的下方；到 100% 時條變成功綠色，文字變「完成 ✓」。
+- 不知道要多久時：水滴載入條，前端先衝、後端跟上，和導覽動畫一致。
+- 達成率：圓環，中間放百分比。
+- 元件架構圖：`LayerGraph`，分層圖。
+  - 共用元件不畫線，放在圖的下方，寫「被 N 個元件呼叫 M 次」。
+  - 方框：淡灰底（`graph-node`），左側灰色色條；名稱加大小長條（例如函式數）。選取的方框用 `accent-soft` 底、強調色色條和外框。
+  - 線：直角、轉角是圓的；每條線接在方框上不同的位置；全部灰色（`graph-edge`），粗細依呼叫次數；推測的關係是細虛線。
+  - 標籤放在箭頭旁：推測的關係一直顯示；其他線只有選取時、和選取元件有關的才寫「N 次」。同一個方框收到多條有標籤的線時，左半邊的標籤放箭頭左側、右半邊的放右側，必要時往上疊一行，不超出圖的邊界。文字用一般字體，程式名稱、路徑和數字用 Geist Mono。
+  - 選取一個方框時，沒有關係的方框和線變淡到 40%，相關的線變強調色。
+  - 層與層之間 56 px。手機上和電腦一樣，圖比畫面寬時左右捲動。
+  - 圖例放在圖的下方一列。
+- 其他方框與箭頭的圖：用 `ui-graph-*` class 和 `GraphDefs`、`GraphLegend`，見 Graph 元件；外觀照上面的規則。
+- 程式碼檢視：`CodeView`。
+  - 行號：灰色等寬數字靠右，沒有底色和分隔線。
+  - 目標行：淡強調色底（`accent-soft`），左側 3 px 強調色細條，行號變粗。
+  - 太長的行自動換行，續行縮排 4 個字元寬。
+  - 語法上色低調：關鍵字 `code-keyword`、常數與字串 `code-constant`、註解灰色斜體，其他用文字顏色。
+  - 手機上（寬度小於 600 px）只顯示目標行前後 2 行，下方「顯示全部 N 行」。
+
+## 階層清單
+
+資料夾裡放檔案、可以一層層展開的清單（`TreeList`），例如課程教材、專案文件。
+
+- 層級：每層縮排 28 px，左側有一條細線（`line`）連起同一個資料夾裡的項目。子資料夾在同一個清單裡巢狀展開。
+- 資料夾一律排在檔案前面。
+- 排序看情況：預設新到舊，也可以舊到新（例如照上課順序）或依名稱。
+- 展開方式看情況：需要一次看到全部時，點資料夾展開或收合，標題列有「全部展開」；資料夾又多又雜時，一次只開一個，打開一個時同層的其他資料夾自動收合。
+- 展開動畫：子項目從資料夾下方往下長出，260 ms。
+- 檔案圖示：文件形狀加副檔名，副檔名寫在底部的色塊裡，例如 PDF 紅、MP4 紫、PPTX 橘、DOCX 藍。不只靠顏色分辨。
+- 日期與大小：清單寬 640 px 以上時，在右側排成欄；比較窄時，放在名稱下方，寫成「13 小時前 · 137.6 MB」。依照清單本身的寬度切換，不是看整個螢幕。日期照格式規則（一週內用相對時間）。
+- 資料夾的資訊有資料才顯示：檔案數（「4 個檔案」）和裡面最新檔案的時間。
+- 新檔案：使用者還沒打開或下載過的檔案算新。日期變成 `accent-text` 粗體，不另外加標籤；資料夾旁寫「2 個新」，展開時也看得到。打開或下載後就不再標示。
+- 下載按鈕一直顯示在每個檔案的最右邊。
+- 勾選看情況：需要時，勾選框滑過才顯示，和表格一致；勾了一個之後全部顯示。勾資料夾等於全選裡面的檔案，只勾一部分時資料夾顯示橫線。勾選後標題列換成「已選 3 個檔案 共 192.6 MB」，旁邊有「清除選取」和「下載」。
+- 鍵盤：↑ ↓ 移動，→ 展開，← 收合或回到上一層，Enter 打開，空白鍵勾選。
+- 手機上的縮排：清單寬度小於 600 px 時，每層縮 16 px，最多縮 3 層；更深的不再縮排，名稱前加層數（「L5」）。
+- 一般的樹（`kind="plain"`，例如呼叫關係）：沒有檔案圖示和大小；名稱下方放位置（Geist Mono、次要文字），長路徑保留頭尾、中間省略（「src/…/hooks/ops.c:58」，`format.path()`）；照資料原本的順序，不把有子項目的排前面；點一列是選取，點箭頭是展開。
+- 標籤只標例外：大部分列都一樣的屬性不標，只標需要留意的，用 Tag 包 Term；預設值在樹下方說明一次（例如程式碼地圖裡，沒有標示的關係都由編譯器確認，只標「推測（規則）」）。
+
+## 分類標籤
+
+- 說明「這是什麼」的標籤（例如「外部」、「範本」、「規則：經由指標」），用 `Tag`：只有小字（12 px、粗體、`ink-muted`），沒有框也沒有底，一律灰色，不用顏色表示類別。
+- 表示進度或結果的仍然用 Badge。
+
+## 詳細資訊與操作
+
+- 一個項目的詳細欄位用 `DetailList`：寬度 600 px 以上時欄位名稱在左、值在右；比較窄時名稱在上、值在下，和手機表格卡片一致。
+- 卡片上的多個操作用 `ActionBar`：寬度小於 600 px 時，最常用的一個是全寬的主要按鈕，其他收進右邊的「⋯」選單；比較寬時並排。
+
+## 文字語氣
+
+- 按鈕文字：只用動詞，例如「儲存」、「刪除」、「取消」。
+- 錯誤訊息：寫出原因加修正方式，例如「Email 格式不正確，例如 name@example.com」。
+- 介面文字只寫重點，規則來自教材風格：
+  - 一句話講一件事，寫成「名稱：做什麼」，例如「Ctrl K：搜尋」。說明最多 2 句，每句約 25 字以內。
+  - 畫面上已經看得出來的不寫：標題、圖示或按鈕已經說明的事，不再用文字重講；沒有重點要補充時就不放說明。
+  - 同一件事只說一次：不在說明、提示和標題重複同一句話。
+  - 正式的書面用語，不用口語，例如「查看依據」，不寫「點一下看原因」；「版本衝突」，不寫「版本會打架」。
+  - 標題和連結不用問句，例如「重看導覽」，不寫「第一次使用？重看導覽」；「忘記密碼」，不寫「忘記密碼？」。確認對話框的標題例外，例如「刪除這個專案？」。
+  - 技術名詞保留常見的英文（translation unit、LD_PRELOAD），不另造中文；第一次出現時用 `Term` 說明。
+  - 較長的解釋放到文件，介面上給連結。
+  - 使用者要做的事寫在畫面上，例如空狀態寫下一步。
+
+## 導覽
+
+- 側邊欄：選中用左側指示條（水滴方式移動）；滑過灰底；項目高度 40 px；組與組之間用分隔線；收合後滑過顯示名稱提示；子選單展開縮排。平板固定收合時，有子頁面的項目點了直接進第一個子頁面，其他子頁面在頁面內切換。
+- 頂部列：左邊頁面標題，右邊填色搜尋框（附 Ctrl K 提示，Mac 上寫 ⌘K）；麵包屑放在內容區最上方。
+- 麵包屑：箭頭「›」分隔，一般字。
+- 分頁切換：分段控制，水滴動畫，內容依序浮起。
+- 手機底部分頁列：只有圖示，選中時圖示後方出現膠囊，水滴動畫。放不下的頁面（沒有圖示、第 5 個以後、第二個以後的子頁面）放在最後一格「更多」，打開完整導覽；有子頁面的分頁打開第一個子頁面。
+- 專案狀態：頂部列右邊放 `ProjectSwitcher`，外框 Chip 寫「ibtrace · 即時」，前面的圓點表示資料狀態（即時綠、已過期橘、離線灰）；點了打開清單切換專案或環境，清單最下方可以放設定連結。
+
+- 頂部列在手機上（寬度小於 600 px）：搜尋框換成搜尋圖示，點了打開搜尋面板。
+
+## 搜尋、導覽與說明
+
+- 搜尋面板：`CommandPalette`，一個搜尋找全部（頁面、設定、指令、檔案，以及專案自己的種類，例如程式碼地圖的函式、環境變數）。
+  - 入口：電腦上是頂部列的填色搜尋框，手機上是頂部列的搜尋圖示；任何頁面按 Ctrl K（Mac 是 ⌘K）都能打開。
+  - 樣子：畫面中間浮起的面板，電腦寬 640 px，手機上也一樣置中浮起（左右各留 12 px，在頂部列下方）。
+  - 結果：所有種類混在一起，最相關的在最上面（名稱開頭符合的優先）；左邊是種類圖示；符合的字粗體。
+  - 鍵盤：↑ ↓ 選擇，Enter 打開，Esc 關閉；面板底部寫這三個按鍵，觸控裝置不顯示。
+- 第一次使用的導覽：`Tour`，用 `useTour(key)` 記住看過了沒有。
+  - 樣子：整頁變暗，只亮出要介紹的地方（外加強調色框），旁邊的說明卡寫「1 / 3」、標題和一兩句說明。
+  - 可以略過，看完或略過後不再自動出現；頁面上要有「重看導覽」能重新開始。
+- 修正建議：`Suggestion`，舊的和新的上下兩行，舊的前面「−」淡紅底，新的前面「+」淡綠底；右上角是複製圖示，按了複製修正後的整句，圖示變成勾，提示寫「已複製」。
+- 名詞與關係的說明：`Term`，用在讀者可能看不懂的名詞（例如「translation unit」）和關係標籤（例如「推測的關係」）。
+  - 記號：名詞後面加一個小問號。
+  - 點一次打開、再點一次關閉，右上角也有 ×，按 Esc 或點外面也會關閉。
+  - 寬度 600 px 以上：名詞下方浮起小卡；小於 600 px：從畫面下方打開。
+  - 關係的說明附上證據那一行程式碼和「看這一行」。
+
+版面見「版面架構」，動畫見「動畫」。
+
+## 教材主題（teaching preset）
+
+Slidev 教材投影片使用 `data-theme="teaching"`。投影片的 CSS 只讀 token 名稱，數值由這個 preset 提供。
+
+已確認的選擇：
+
+- 混合方案：中性色與字型沿用設計系統，強調色、直角與細線邊框沿用投影片風格。
+- 強調色：青綠 `#0f766e`。
+- 圓角：全部 0 px（`radius-sm`、`radius-chip`、`radius-md`、`radius-lg`）。
+- 陰影：不用（`shadow-*` 為 none），外框用 1.5 px 的 `line`。
+- 字型：標題與內文 Inter 加思源黑體，程式碼 Geist Mono。
+- 只有淺色。
+
+`accent-hover`、`accent-press`、`accent-soft` 依「自訂強調色的換算」由 `#0f766e` 算出。版面、字級與投影片規則見 `teaching-materials-style`。

package/docs/layout.md

@@ -0,0 +1,35 @@
+# 版面架構
+
+依使用情境選擇兩種架構之一。
+
+## Dashboard 類
+
+- 側邊欄加頂部列。
+- 側邊欄可收合：展開 240 px（`sidebar-width`），收合 72 px（`sidebar-collapsed`）。
+- 收合按鈕在側邊欄左下角，只有圖示、沒有文字。
+
+## 展示類
+
+- 只用頂部導覽。
+
+## 共通規則
+
+- 內容最大寬度：滿版。
+- 格線：12 欄。
+- 卡片排列：均等格線。
+- 區塊間距：緊密 32 px（`space-8`）。
+- 手機導覽：底部分頁列。
+- 頁首行為：往下捲時隱藏，往上捲時出現。
+- 頁尾：精簡一行。
+
+## 斷點
+
+| 名稱 | 寬度 (px) | Token |
+|---|---|---|
+| 手機 | 0 到 599 | 小於 `bp-tablet` |
+| 平板 | 600 到 959 | `bp-tablet` |
+| 桌面 | 960 到 1279 | `bp-desktop` |
+| 大螢幕 | 1280 以上 | `bp-wide` |
+
+- 平板寬度時，Dashboard 類的側邊欄收合成圖示（72 px）。
+- 表單欄位：`bp-desktop`（960 px）以上雙欄，以下單欄。

package/docs/motion.md

@@ -0,0 +1,63 @@
+# 動畫
+
+動畫程度：Level 3（細緻回饋、轉場，以及吸睛的進場效果）。
+
+| 用途 | 時間 (ms) |
+|---|---|
+| hover、按下 | 150 |
+| 分頁、開關、提示 | 300 |
+| 主題切換 | 350 |
+| 進場（逐項間隔 90） | 700 |
+
+## 導覽切換
+
+| 項目 | 設定 |
+|---|---|
+| 動畫時間 | 200 ms |
+| 拉伸程度 | 明顯：後端比前端慢 2.2 倍（前端 120 ms、後端 440 ms） |
+| 停下來的形狀 | 圓角矩形（`radius-md` 10 px） |
+| 停下來的邊緣 | 清晰 |
+| 分頁指示 | 水滴：同一塊拉長再收回，移動中略為變細 |
+| 側邊欄選中 | 水滴：指示條拉長移動再收回 |
+| 內容切換 | 卡片依序浮起，間隔 40 ms |
+| 手機分頁切換 | 水滴膠囊 |
+
+## 數據呈現
+
+| 項目 | 設定 |
+|---|---|
+| KPI 數字 | 從 0 數上來，900 ms，ease-out |
+| 折線 | 依序畫出，每條 900 ms，間隔 150 ms |
+| 長條 | 依序由下長高，每根 500 ms，間隔 40 ms |
+| 達成率圓環 | 和數字一起從 0 跑到目標值，900 ms |
+| 不確定進度 | 水滴：1.4 s 一輪，前端用 ease-out、後端用 ease-in-out，所以中間會拉長 |
+
+## 浮層
+
+| 項目 | 設定 |
+|---|---|
+| 提示 | 0 ms 延遲；從箭頭那一側放大，220 ms，稍微回彈 |
+| 「⋯」選單 | 從按鈕所在的角落放大，180 ms |
+| 彈出框 | 淡入 150 ms；滑鼠移開 150 ms 後關閉 |
+| 側邊抽屜 | 彈性滑入 450 ms；滑出 300 ms；遮罩淡入 300 ms |
+
+## 外觀
+
+| 項目 | 設定 |
+|---|---|
+| 切換主題 | 所有顏色漸變 300 ms |
+
+## 表格
+
+| 項目 | 設定 |
+|---|---|
+| 排序 | 依序滑動：每列 320 ms，由上往下間隔 25 ms，ease-out |
+| 還原排序 | 和排序相同 |
+| 換到別頁的列 | 換出的往下滑出並淡出，換進的從下方滑入並淡入 |
+| 換頁 | 下一頁整頁往上滑出、新頁從下方滑入；上一頁相反 |
+
+## 減少動態效果
+
+使用者在系統開啟「減少動態效果」（`prefers-reduced-motion: reduce`）時，只保留淡入淡出，關閉位移與縮放。
+
+- 數據呈現：數字直接顯示最終值，圖表只淡入，水滴載入條改成靜止的半透明條。

package/package.json

@@ -1,6 +1,62 @@
 {
   "name": "@seanyeh77/ui",
-  "version": "0.0.0-stage",
-  "stub": true,
-  "description": "Temporary package placeholder for staged publishing"
+  "version": "0.3.0",
+  "description": "SeanYeh's design system: typed React components on Base UI, styled with design tokens.",
+  "license": "MIT",
+  "author": "Hsiu-An Yeh",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/seanyeh77/ui-design-system.git",
+    "directory": "packages/ui"
+  },
+  "homepage": "https://seanyeh77.github.io/ui-design-system/",
+  "type": "module",
+  "sideEffects": [
+    "*.css"
+  ],
+  "exports": {
+    ".": {
+      "types": "./dist/index.d.ts",
+      "default": "./dist/index.js"
+    },
+    "./format": {
+      "types": "./dist/format.d.ts",
+      "default": "./dist/format.js"
+    },
+    "./styles.css": "./dist/styles.css",
+    "./tokens.css": "./dist/tokens.css",
+    "./fonts.css": "./dist/fonts.css",
+    "./bundle.js": "./dist/bundle.js",
+    "./docs/*": "./docs/*",
+    "./package.json": "./package.json"
+  },
+  "files": [
+    "dist",
+    "docs"
+  ],
+  "peerDependencies": {
+    "react": ">=19",
+    "react-dom": ">=19"
+  },
+  "devDependencies": {
+    "@testing-library/react": "^16.3.3",
+    "@testing-library/user-event": "^14.6.8",
+    "@types/react": "^19.3.0",
+    "@types/react-dom": "^19.3.0",
+    "@vitest/browser-playwright": "^5.1.0",
+    "playwright": "^1.65.0",
+    "react": "^19.3.1",
+    "react-dom": "^19.3.1",
+    "tsdown": "^0.23.7",
+    "vitest": "^5.1.0",
+    "@seanyeh77/tokens": "^0.3.0"
+  },
+  "dependencies": {
+    "@base-ui/react": "^1.9.0"
+  },
+  "scripts": {
+    "build": "tsdown && node scripts/postbuild.ts",
+    "typecheck": "tsc -p .",
+    "test": "vitest run"
+  }
 }

package/README.md

@@ -1,3 +0,0 @@
-# Temporary Holding Version
-
-This version is a temporary placeholder for this package. An operational version to replace this has been submitted for review and is awaiting a staged release.