SSaaS GuideAgent

速查表 · Agent

速查表

一頁覆蓋 80% SaaS 後台情境。給 AI 當 system context。本速查表僅作索引與摘要，衝突裁決見各章與下方「規則優先序」。

互動示範（與本規範網站人類閱讀版相同）：/docs/cheatsheet

延伸與補充

章節地圖

全站 34 章，分三組（架構／元件／頁面）。

架構

章slug標題
00cheatsheet速查表
01layout版面配置
02navigation導覽
18responsive-accessibility響應式與無障礙
19design-tokensDesign tokens
20dark-mode-i18n深色模式與 i18n
12notifications-onboarding通知與 onboarding
13settings設定頁
14permissions權限

元件

章slug標題
03data-table資料表格
09search-filter-sort搜尋/篩選/排序
10bulk-operations批次操作
15pagination分頁
31resource-views資源檢視
33charts-data-viz圖表與資料視覺化
04forms表單
05modals-overlaysModal 與覆層
06buttons按鈕
11confirmation-destructive確認與破壞性操作
07feedback回饋
08states狀態
16tags-badges-avatar標籤/徽章/頭像
17file-upload-date-picker上傳與日期選擇
30cards卡片
32dropdown-menus下拉與選單

頁面

章slug標題
21auth-pages登入/註冊
29error-pages錯誤頁 40x/50x
22dashboard-pageDashboard
23list-page列表頁
28detail-view-page詳情檢視
24content-form-page新增/編輯頁
25upload-flow-page上傳流程
26settings-screen-page設定頁範本
27roles-accounts-page角色與帳號

章節導覽

你在做 X → 必讀／選讀。

你在做必讀選讀
新列表頁23, 03, 0910, 15, 31
新增/編輯長表單24, 04, 0506, 07
設定區26, 13, 0211, 14
刪除/危險操作11, 0705, 06
Dashboard22, 0333, 30
換主題/深色19, 2018

設定主題分工 → 導覽行為看 02、內容/卡片看 13、完整版型看 26（三者勿混讀）。

規則優先序（precedence）

規則衝突時，依此順序裁決：

  1. 各章 MUST > 他章 SHOULD。
  2. 頁面章（21–29）> 元件章 > 架構章。例：列表頁 primary 以 23-list-page 為準，覆寫 03-data-table 的 toolbar 寫法。
  3. 決策樹章（05-modals-overlays modal/drawer、11-confirmation-destructive confirmation）> cheatsheet 摘要。
  4. 19-design-tokens 為色彩／間距／圖示的唯一真相，覆寫各章零散 hex。
  5. 本速查表僅索引與摘要，不作衝突裁決。

Page Templates（21–29）

  • Auth（21）：置中 card、Google + Email、忘記密碼單頁。
  • Error pages（29）：404/500 置中；403 可 in-shell。
  • Dashboard（22）：KPI + 圖表 + 近期列表。
  • List（23）：tabs + toolbar + table + pagination；唯一 primary 放 page header。
  • Detail view（28）：breadcrumb + tabs + 編輯 CTA。
  • Form page（24）：full page 編輯 + card sections + sticky save。
  • Upload flow（25）：上傳前／中／結果確認三態。
  • Settings screen（26）：sidebar drill-down（勿內容區再加 nav／設定 breadcrumb）。
  • Roles（27）：權限矩陣 tab + 帳號管理 tab。

Layout

  • 左側 sidebar（240px）+ 右側 content area，content max-width 1200–1440。
  • Sidebar collapse 時縮成 48–64px icon-only。
  • Topbar 放 global search、user menu、notifications。
  • Scroll：viewport 固定高度；sidebar 與主內容分離捲動；禁止整頁 + sidebar 共用 window scroll。
  • Breakpoints：xs <576 / sm 576 / md 768 / lg 992 / xl 1200 / xxl 1600。
  • Z-index：0 → 100 → 1000 → 1100 → 1200 → 1300 → 1400（見 01-layout.md）。
  • Mobile：sidebar → hamburger / off-canvas drawer。

Navigation

  • Sidebar 最多兩層，第三層改用 settings 頁的二級 nav 或 in-page tabs。
  • 設定頁等複雜區用「左側二級 nav + 右側 card section」結構。
  • Active item：圓角品牌淡底 + 字色／圖示（不用左側 border）。
  • Breadcrumb 用在 ≥ 3 層階層；放 page header 左上；最後一項 = H1；› 分隔。設定頁有二級 nav 時不用。
  • Tabs 三層：Underline（頁級）／Segmented（視圖）／Contained（面板內）；同一 context；勿跨情境。
  • 全域搜尋用 Cmd/Ctrl + K 開啟 command palette，搜資源 + 頁面 + 動作。

新增 / 編輯 / 查看 的流程慣例

  • 新增（Create）：開 lightbox（modal）或 side panel 填短表單，欄位 < 8 個首選 modal。
  • 編輯（Edit）詳細：開 full page，URL 變化、可分享。
  • 查看（View）詳情：開 full page，URL 變化、有 breadcrumb。
  • 快速編輯單欄：inline edit（限簡單欄位、無關聯邏輯）。

Data Table

  • Toolbar 上方：search input、filter button、display settings。Primary CTA 不放 toolbar，放在 page header（以 23-list-page 為準）。
  • Row hover 時顯示 checkbox 與 row actions，平常不常駐。
  • 點 row checkbox → 上方滑出 bulk action bar：「已選 N 筆 + Clear + 動作按鈕」。
  • Select all：部分選取用 indeterminate；要區分「本頁全選 vs 跨頁全選」。
  • Sort 在 column header 點擊；預設單欄 sort。
  • Filter 用 chip 顯示在 toolbar，每個可 ✕ 移除 + "Clear all"。
  • Filter / sort / page 寫入 URL query string（可分享、可回上一頁）。
  • Saved view：常用 filter 組合存成 view，可個人/團隊共用。
  • Pagination 預設 offset + 每頁 10/25/50/100，預設 25。
  • Sticky table header + sticky first column（mobile）。
  • Loading 用 skeleton row；不要整頁 spinner。
  • Empty 分兩種：
    • 從未有資料 → 插圖 + 說明 + 強 CTA「Create your first…」
    • Filter 無結果 → 「No results, Clear filters」
  • 非 table 呈現：Grid / Kanban / List / Calendar / Gantt → 31-resource-views.md（toolbar 共用）。

Cards

  • 邊框 + 圓角 + 內距；KPI、互動、媒體、列表項、Header/Body/Footer → 30-cards.md。
  • Grid 資源卡 = 媒體卡樣式；Kanban 卡 = 精簡卡。

Forms

  • Label 放欄位上方（top-aligned）→ 填寫最快。
  • Required 用紅 *；若大多必填，反過來標 (optional)。
  • Inline validation 在 blur 時觸發（不要 onChange 邊打邊紅）。
  • Error message 在欄位下方，寫「為什麼錯 + 怎麼修」，不要只說 "Invalid"。
  • Help text 永遠可見，放 label 與 input 之間；不要用 placeholder 當 help。
  • Disabled 欄位/按鈕要附 tooltip 解釋「為什麼 disabled」。
  • Autosave 用在文件、settings toggle；表單送出型仍用 Save button。
  • Autosave 不適用於密碼、付款、權限變更等高風險欄位。

Modal / Drawer / Side Panel / Full Page

情境用什麼
新增（短表單）、簡單編輯、destructive 確認Modal
顯示 row detail、輔助編輯、不打斷主流程Drawer / Side panel
長表單、wizard、複雜編輯、查看詳情Full page（URL 變化）
  • Modal size：small 400、medium 560–640、large 800、x-large/full-screen。
  • 必備行為：focus trap、ESC 關閉、點 backdrop 關閉、開啟 focus 第一個可操作元素。
  • Default focus 落在「安全按鈕」（Cancel），不要落在 destructive 按鈕。
  • Mobile：modal → full-screen 或 bottom sheet。

Buttons

  • Hierarchy：Primary / Secondary / Tertiary / Danger / Icon-only。
  • 一個 view 只放一個 Primary。列表頁的唯一 primary 在 page header，toolbar 不放 primary（見 23-list-page.md）。
  • Modal 內按鈕順序（西方語系）：Cancel 在左 / Primary 在右。
  • Destructive button：紅色 + icon + 明確文字（「Delete project」而非「Confirm」）。
  • 危險與安全按鈕「不要相鄰」+「同 weight」，防誤觸。
  • Loading：保留寬度，換成 spinner + "Saving..."，期間 disabled。
  • Icon-only button 必有 aria-label + tooltip。

Feedback：Toast / Banner / Inline

類型用途位置持續
Toast / Snackbar暫時性回饋（新增/編輯/刪除完成）top-right 或 bottom-center一般 3–5s、含 action 至少 10s
Banner系統級持續訊息（quota、帳號驗證）page/section 頂部手動關閉
Inline alert跟欄位/section 相關的錯誤該欄位/section 旁直到問題修正
  • 新增/編輯/刪除完成 → 跳 toast。
  • 刪除 toast 含「復原」按鈕，持續 10 秒。
  • 一般 toast 3 秒自動消失。
  • Toast 一律可手動關閉。
  • 不用 toast 放關鍵錯誤（會被忽略）。
  • Destructive 動作優先用 Undo toast 取代事前 confirmation（Polaris/Material 哲學）。

Confirmation Dialog

  • 只用於不可復原或後果嚴重的動作。
  • 文案重述「會發生什麼」，不要只寫 "Are you sure?"。
  • 高風險（刪除 workspace、刪除 production）：要 type-to-confirm（輸入專案名才能 enable 按鈕）。
  • Default focus 落在 Cancel。
  • 一般刪除：用 Undo toast 就好，不要彈 modal。

Empty / Error / Loading

  • Empty：插圖 + 說明 + CTA。永遠不要真的空白。
  • Error：說明「發生什麼 + 怎麼復原」+ Retry。
  • Loading：
    • < 1.5 秒：spinner
    • ≥ 1.5 秒、有結構：skeleton（table row、card list）
    • ≥ 10 秒：progress bar + 預估時間 + 可離開不卡。
  • 不要 skeleton + spinner 同時出現。

Search / Filter / Sort

  • Global search：Cmd/Ctrl + K command palette，跨資源 + 頁面 + 動作。
  • In-page search：toolbar 上的 search input。
  • Filter chip 可單獨 ✕、有 "Clear all"。
  • Saved view 命名儲存，可個人/團隊共用。
  • 結果 highlight 關鍵字、顯示總筆數、「無結果」狀態。

Bulk Operations

  • 觸發：點任一 row checkbox。
  • Bar 顯示：已選 N 筆 + Clear + 動作按鈕。
  • 跨頁全選提示：「已選 25 筆，選取全部 1,240 筆？」。
  • Bulk destructive：必跳 confirmation，明示「即將影響 N 筆」。

Tags / Badges / Status Chip

  • Badge：純展示，小（unread count、status dot）。
  • Tag：分類用，可有 ✕ 可移除。
  • Chip：互動性最強（filter chip、input chip）。
  • 顏色語義：success 綠 / warning 黃橙 / error 紅 / info 藍 / neutral 灰；不可只靠顏色，要配 icon 或文字。
  • 同產品內 tag palette 限 8–12 色。

Avatar / Presence

  • 人 → circle；組織 → rounded square。
  • Fallback：首字母 + 系統色背景。
  • Presence dot 在右下：綠 online / 灰 offline / 黃 away / 紅 DND。
  • Avatar stack 上限 3–5 + "+N"。

Pagination

  • 後台 table 預設 offset + 每頁 25。
  • Cursor 用於即時更新、無限大資料；offset 用於需跳頁的後台表格。
  • Infinite scroll 適合 feed/discovery，不適合後台 table。

  • 100 頁要提供 jump-to-page。

Accessibility

  • 所有 interactive 元素鍵盤可達 + 可見 focus ring（對比 ≥ 3:1）。
  • 文字對比 normal ≥ 4.5:1，large ≥ 3:1。
  • 顏色不能是唯一傳達方式（要配 icon/文字）。
  • Modal role="dialog" aria-modal="true"；toast role="status"；error role="alert"。
  • Form field 必有 label，error 用 aria-describedby 關聯。
  • Tab order 跟視覺順序一致，不用 tabindex > 0。
  • Touch target ≥ 44×44pt（iOS）/ 48dp（Material）。

Design Tokens

  • Color token：bg-default / bg-subtle / text-default / text-muted / border-default / interactive-primary（品牌主色 #4F46E5 indigo，見 19-design-tokens.md）。
  • Spacing scale（4px base）：4 / 8 / 12 / 16 / 24 / 32 / 48 / 64。
  • Typography：Inter；H1 24–32 / H2 20 / H3 16 / Body 14 / Caption 12。
  • Line-height：body 1.5 / heading 1.2–1.3。
  • Icon：僅 SVG 向量圖（禁止 emoji 當圖示）；size 16 / 20 / 24 / 32，stroke 1.5–2px；本指南示範用 Untitled UI Icons。
  • Radius：4（input）/ 8（card/modal）/ 999（pill/avatar）。

Dark Mode

  • 不用純黑 #000、不用純白 #FFFFFF（改用淺灰文字如 #E2E8F0）。
  • Dark-mode 各色階 hex 以 19-design-tokens.md 的 Color token 表（語意色票，含 light / dark）為唯一真相（引用，不在此重列數值）。
  • Elevation 越高越亮（不靠 shadow，用 surface tone）。
  • 飽和色降 saturation 10–20%。
  • 維持 WCAG 4.5:1 對比。

i18n / 字串

  • UI 預留文字 30–40% 延伸空間（德文常超英文 35%）。
  • 不寫死 button/nav item/label 寬度。
  • 支援 RTL：mirror layout、icon、padding。
  • 日期、時間、數字、貨幣用 locale formatter。
  • 不串接字串，用 ICU message format。