Card 與表面層級
內容卡片、工作區 Shell、浮層、陰影與背景磨砂的使用規則。
即時元件卡片層級
內容卡片保持平坦;外殼用於傳達工作區群組。
專案概觀發布準備就緒
標準內容卡片不使用外陰影。
選擇與狀態透過色彩與資訊層級傳達。
卡片材質與層級規範
本文公開說明 Qokit 工作介面在什麼場景使用陰影、透明、漸層和背景磨砂。適用於平台擴充、Builder、CMS、Dashboard、Studio 和 Admin。行銷頁面與生成網站可以更有表現力,但效果必須歸屬於當前主題,並保證內容可讀。
核心原則
視覺效果用於表達結構,不用於裝飾每一個區塊:
- 內容透過背景色差區分。
- 容器透過透明或克制的漸層表達歸屬。
- 浮層透過陰影表達層級。
- 互動透過顏色和焦點環表達狀態。
獨立實色卡片與輸入框使用共享一級輕陰影;列表、巢狀表面和透明分組保持平整;真正的浮層才使用明顯陰影。
判斷順序
新增材質效果前,先判斷表面的角色:
- 是否是獨立實色卡片或輸入框?使用共享的一級表面或欄位陰影。
- 是否是列表行、巢狀卡片、重複選項或透明分組?保持平整。
- 是否把多個內部內容卡片組織成一個工作區?使用 Shell。
- 是否覆蓋頁面內容或出現在當前平面上方?使用浮層陰影。
- 是否處於拖曳、縮放或暫時懸浮狀態?使用暫時陰影。
- 是否只是為了表達 hover、選中或 focus?使用共享 hover 角色、互動背景色和焦點環。
除非表面角色確實需要,否則不要同時疊加陰影、透明、漸層和磨砂。
場景矩陣
| 表面角色 | 陰影 | 透明或漸層 | 背景磨砂 |
|---|---|---|---|
| 獨立實色內容卡片、指標卡片 | 共享一級輕陰影 | 允許輕微背景色差 | 無 |
| 列表行、巢狀卡片、透明分組、重複選項 | 無 | 允許輕微背景色差 | 無 |
| 頁面內分組 Shell | 無 | 推薦 | 通常不需要 |
| 側邊欄或常駐工作區 Shell | 輕量 | 推薦 | 背後有可見內容時允許 |
| Dialog、Popover、Dropdown、上下文選單 | 明確的浮層陰影 | 背景必須足夠實,保證可讀 | 允許 |
| 拖曳預覽、縮放狀態、懸浮預覽 | 暫時較強 | 可選 | 通常不需要 |
| Hover | 保持或輕微加強一級陰影 | 可改變背景 | 不變化 |
| 選中或啟用狀態 | 無 | 強調色背景或克制漸層 | 不變化 |
| 輸入框、搜尋框 | 極輕欄位陰影 | 使用控件表面色 | 通常不需要 |
| 獨立主操作、獨立膠囊、分段控件外殼 | 極輕控件陰影 | 使用控件表面色 | 通常不需要 |
| 工具欄與透明內層控件 | 無 | 使用控件表面色或透明 | 通常不需要 |
| 行銷頁或生成網站視覺卡片 | 由主題決定 | 允許 | 克制使用 |
元件映射
<Card>預設使用layer="content":共享一級輕陰影、無邊框、預設20px圓角;muted、巢狀、列表和透明變體保持平整。<Card layer="shell">:頁面內只負責分組,使用透明或輕漸層表面並保持平整;常駐工作區 Shell 由所屬模式單獨提供層級。<Card shape="pill">:用於緊湊的單行卡片,圓角為橢圓膠囊形。SidebarNavigation:獨立的工作區 Shell,保留明確的漸層、透明、磨砂和輕陰影。- Studio 的
PromptPanel作為工作區容器時:使用--workspace-shell-shadow。 DialogPanel、下拉選單、Popover、上下文選單和概念瀏覽器:使用浮層陰影。- Builder 畫布、裝置預覽、生成網站預覽、拖曳預覽和縮放狀態:因為代表獨立預覽平面或暫時互動層,可以保留專用陰影。
不要建立層層懸浮的內容卡片。如果確實需要外層分組,它必須是平整 Shell。除真實浮層外,同一 DOM 祖先鏈最多出現一個普通內容或控件陰影。
設計變數(Token)使用
優先使用共享 Token,不要硬編碼效果:
- 內容卡片陰影:
--card-shadow: var(--qk-shadow-surface) - 內容卡片 hover 陰影:
--card-shadow-hover: var(--qk-shadow-surface-hover) - 欄位陰影:
--input-shadow: var(--qk-shadow-field) - 欄位啟用陰影:
--input-state-shadow: var(--qk-shadow-field-active) - 控件陰影:
--qk-shadow-control/--qk-shadow-control-hover - 主操作控件陰影:
--qk-shadow-control-accent/--qk-shadow-control-accent-hover - 內容卡片磨砂:
--card-backdrop-filter: none - Shell 表面:
--card-shell-surface - Shell 磨砂:
--card-shell-backdrop-filter - 工作區 Shell 陰影:
--workspace-shell-shadow - Dialog 表面:
--dialog-surface,提供克制的主題漸層 - Dialog 磨砂:
--dialog-backdrop-filter - Dialog 浮層陰影:
--dialog-shadow - Dialog 圓角:複用
--card-radius - 鍵盤焦點:
--focus-ring - 浮層陰影:使用現有 Dialog、Dropdown、Menu 或頁面級浮層 Token
普通內容卡片和工作區面板不得使用較強的通用 --shadow Token。
全域陰影採用「短位移、低透明度、按放置層級遞增」的安靜刻度。普通 Card、欄位和控件不得在路由中加深或放大共享陰影;Popover 與 Dialog 透過更大的位移和模糊範圍表達脫離頁面,而不是疊加深色灰霧。
互動規則
懸停(Hover)
- 內容卡片不得提升到
--qk-shadow-surface-hover以上的層級。 - 不透過
translateY抬升內容卡片。 - 使用輕微背景變化或清晰的控件回饋。
- 不改變形狀,避免出現圓角不一致或陰影裁切。
選中與啟用
- 使用強調色表面、圖示狀態、語意狀態或克制漸層。
- 不得只透過陰影表達狀態。
鍵盤焦點
- 使用共享 focus-visible 規則或
--focus-ring。 - 通用卡片陰影不能代替焦點提示。
- 淺色和深色主題下都必須清晰可見。
拖曳與縮放
- 只有圖層正在移動或調整大小時,才允許使用較強陰影。
- 互動結束後必須移除暫時陰影。
- 溢出容器不能裁切移動圖層的回饋效果。
透明與背景磨砂
透明用於表達外層表面與工作區的歸屬關係。只有當表面後方確實有可見內容、顏色或影像時,背景磨砂才有意義。
- 不要在純色背景上使用磨砂,它只會增加渲染成本,無法表達層級。
- 無論背後經過什麼背景,文字、圖示和控件都必須清晰可讀。
- 瀏覽器不支援背景磨砂時,必須有不透明或可讀的回退背景。
- 密集型工作介面的模糊強度要克制。
- 必須同時驗證淺色和深色主題。
允許保留陰影的例外
- 工作區側邊欄 Shell
- Dialog、Popover、Dropdown、選單和模態面板
- Studio 概念瀏覽器與確認浮層
- Builder 畫布、裝置框架和生成網站預覽平面
- 拖曳預覽、縮放回饋和暫時懸浮工具
- 共享按鈕 Token 已定義陰影的主操作按鈕
- 當前主題控制的行銷頁面和生成網站視覺元素
這些例外不能透過寬泛選擇器或共享 Token 影響普通內容卡片。
審查清單
- 獨立實色內容卡片與輸入框只使用共享一級輕陰影角色。
- 獨立主操作、獨立膠囊與分段控件外殼只使用共享極輕控件陰影。
- 頁面分組、列表行、巢狀卡片、透明分組、重複 Tab/Pill、工具欄和複合控件內部項保持平整。
- 工具欄中的搜尋、篩選、排序、視圖與內聯主操作保持平面;普通輸入框的輕陰影不能洩漏到工具欄,鍵盤焦點環除外。
- Segmented 位於已有陰影的卡片、對話框或工具欄內部時,外殼與選中項都保持平面;滑鼠點擊不顯示鍵盤焦點環。
- 除真實浮層外,同一祖先鏈不疊加多個普通陰影。
- hover 不會讓內容卡片垂直移動。
- 已移除巢狀內容卡片,或明確把外層定義為 Shell。
- 只有真正的 Shell 使用
--workspace-shell-shadow。 - 只有真正的浮層和暫時互動圖層使用較強陰影。
- 背景磨砂後方存在可見內容,並且有可讀的回退背景。
- focus-visible 使用焦點環。
- 淺色和深色主題均保持足夠對比度。
- 圓角表面不會裁切 hover、focus、拖曳或浮層回饋。
- 桌面和行動裝置寬度不會出現新的橫向溢出。
npm run ui:check-card-surfaces --workspace @qokit-ai/web檢查通過。