Skip to Content
設計

Card 與表面層級

內容卡片、工作區 Shell、浮層、陰影與背景磨砂的使用規則。

即時元件卡片層級

內容卡片保持平坦;外殼用於傳達工作區群組。

專案概觀發布準備就緒
內容12 頁已完成

標準內容卡片不使用外陰影。

檢查項目行動裝置就緒

選擇與狀態透過色彩與資訊層級傳達。

卡片材質與層級規範

本文公開說明 Qokit 工作介面在什麼場景使用陰影、透明、漸層和背景磨砂。適用於平台擴充、Builder、CMS、Dashboard、Studio 和 Admin。行銷頁面與生成網站可以更有表現力,但效果必須歸屬於當前主題,並保證內容可讀。

核心原則

視覺效果用於表達結構,不用於裝飾每一個區塊:

  • 內容透過背景色差區分。
  • 容器透過透明或克制的漸層表達歸屬。
  • 浮層透過陰影表達層級。
  • 互動透過顏色和焦點環表達狀態。

獨立實色卡片與輸入框使用共享一級輕陰影;列表、巢狀表面和透明分組保持平整;真正的浮層才使用明顯陰影。

判斷順序

新增材質效果前,先判斷表面的角色:

  1. 是否是獨立實色卡片或輸入框?使用共享的一級表面或欄位陰影。
  2. 是否是列表行、巢狀卡片、重複選項或透明分組?保持平整。
  3. 是否把多個內部內容卡片組織成一個工作區?使用 Shell。
  4. 是否覆蓋頁面內容或出現在當前平面上方?使用浮層陰影。
  5. 是否處於拖曳、縮放或暫時懸浮狀態?使用暫時陰影。
  6. 是否只是為了表達 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 檢查通過。

本頁目錄