Skip to Content
设计

Card 与表面层级

内容卡片、工作区 Shell、浮层、阴影与背景磨砂的使用规则。

实时组件卡片层级

内容卡片保持扁平;外壳用于传达工作区分组。

项目概览上线就绪度
内容12 个页面已完成

标准内容卡片不使用外部阴影。

检查项移动端就绪

选择状态与信息层级通过颜色和层次结构传达。

卡片材质与层级规范

本文公开说明 Qokit 工作界面在什么场景使用阴影、透明、渐变和背景磨砂。适用于平台扩展、Builder、CMS、Dashboard、Studio 和 Admin。营销页面与生成站点可以更有表现力,但效果必须归属于当前主题,并保证内容可读。

核心原则

视觉效果用于表达结构,不用于装饰每一个区块:

  • 内容通过背景色差区分。
  • 容器通过透明或克制的渐变表达归属。
  • 浮层通过阴影表达层级。
  • 交互通过颜色和焦点环表达状态。

独立实色卡片与输入框使用共享一级轻阴影;内部 Admin 内容卡、列表、嵌套表面和透明分组保持平整;真正的浮层才使用明显阴影。

判断顺序

添加材质效果前,先判断表面的角色:

  1. 是否是独立实色卡片或输入框?使用共享的一级表面或字段阴影;内部 Admin 内容卡保持平整。
  2. 是否是列表行、嵌套卡片、重复选项或透明分组?保持平整。
  3. 是否 overview 的 Status / Priority 语义 Object(网站状态、优先判断)?允许 toned 浅洗底,无内容阴影、无装饰网格纹理;禁止内嵌 elevated MetricCard,也不是页面内 Shell。见管理工作台 Overview Panel Kit。
  4. 是否一组相关 Dense 行(次级指标、健康行、模块入口)需要底板?使用 Inset Group:单一浅底 + --card-radius,无内容阴影,内部分隔用 --list-border;禁止组内再套 elevated MetricCard。这不是 Shell。
  5. 是否多个 Object 卡并排出现在管理工作台右栏?保持为平级内容卡,用 gap 分隔;Metric 网格不得铺整组 --list-surface 壳。页标题与分区眉题留在 Quiet Paper Attention 的 Ink 层;overview 服从 Panel Kit(Status → Priority → Action → Metric → Detail),范例为获客运营看板。
  6. 是否组织侧栏、编辑器等常驻工作区(而非右栏分组)?使用 Shell。
  7. 是否覆盖页面内容或出现在当前平面上方?使用浮层阴影。
  8. 是否处于拖拽、缩放或临时悬浮状态?使用临时阴影。
  9. 是否只是为了表达 hover、选中或 focus?使用共享 hover 角色、交互背景色和焦点环。

除非表面角色确实需要,否则不要同时叠加阴影、透明、渐变和磨砂。

场景矩阵

表面角色阴影透明或渐变背景磨砂
独立实色内容卡片、指标卡片(非内部 Admin、非 overview Panel Kit)共享一级轻阴影允许轻微背景色差无
内部 Admin 各类页面的主内容卡片无用表面色差与间距区分内容无
overview Panel Kit Object(Status / Priority / Action / Metric / Detail)无Status/Priority 允许语义浅洗;禁止装饰网格无
列表行、嵌套卡片、透明分组、重复选项无允许轻微背景色差无
Inset Group(相关 Dense 行底板)无推荐浅底 --list-surface 混色无
页面内分组 Shell无推荐(管理右栏默认不用;并列 Object 用 gap,Dense 行用 Inset Group)通常不需要
侧边栏或常驻工作区 Shell轻量推荐背后有可见内容时允许
Dialog、Popover、Dropdown、上下文菜单明确的浮层阴影背景必须足够实,保证可读允许
拖拽预览、缩放状态、悬浮预览临时较强可选通常不需要
Hover非 Admin 表面保持或轻微加强一级阴影;Admin 内容卡继续无阴影可改变背景不变化
选中或激活状态无强调色背景或克制渐变不变化
输入框、搜索框极轻字段阴影使用控件表面色通常不需要
独立主操作、独立胶囊、分段控件外壳极轻控件阴影使用控件表面色通常不需要
工具栏与透明内层控件无使用控件表面色或透明通常不需要
营销页或生成站点视觉卡片由主题决定允许克制使用

组件映射

  • <Card> 默认使用 layer="content":共享一级轻阴影、无边框、默认 20px 圆角;muted、嵌套、列表和透明变体保持平整。
  • 内部 Admin 的内容卡片与页面内分区在 overview、list、detail、settings 中统一平整;导航 Shell、真实浮层、键盘焦点环和正在拖拽或缩放的预览保留各自层级。
  • 普通 Card 桌面默认内距为 24px、手机为 20px;管理工作区使用 16px,内嵌 muted 卡使用 12px。媒体贴边的卡片显式设置零外层内距,并在内容区设置内距;手机布局保留这些覆盖值。
  • 生成站点的 Card 圆角、内距和阴影由站点主题 Token 控制;紧凑布局按主题内距缩减,预览和发布保持一致。
  • <Card layer="shell">:留给侧栏、编辑器等常驻工作区。管理右栏不要用页面内 Shell 包 Object 卡;用 gap、Ink 眉题与 Inset Group 分组。
  • Status / Priority / Action / Metric(overview Panel Kit):无内容阴影;Status/Priority 允许浅洗底、禁止装饰网格;禁止内嵌 elevated MetricCard。共享实现见 workspace-page-surface 与获客看板 CSS。
  • Inset Group(.qk-workspace-inset-group):相关 Dense 行的浅底圆角底板;无内容阴影;禁止组内 elevated MetricCard。
  • <Card shape="pill">:用于紧凑的单行卡片,圆角为椭圆胶囊形。
  • SidebarNavigation:独立的工作区 Shell,保留明确的渐变、透明、磨砂和轻阴影。
  • Studio 的 PromptPanel 作为工作区容器时:使用 --workspace-shell-shadow。
  • DialogPanel、下拉菜单、Popover、上下文菜单和概念浏览器:使用浮层阴影。
  • Builder 画布、设备预览、生成站点预览、拖拽预览和缩放状态:因为代表独立预览平面或临时交互层,可以保留专用阴影。

不要创建层层悬浮的内容卡片。管理右栏 overview 遵循 Quiet Paper Attention Panel Kit:Ground --bg、Ink 页说明/工具栏、Status → Priority → Action → Metric → Detail;Metric 网格无底板壳。除真实浮层外,同一 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 检查通过。

本页目录