Card 与表面层级
内容卡片、工作区 Shell、浮层、阴影与背景磨砂的使用规则。
内容卡片保持扁平;外壳用于传达工作区分组。
标准内容卡片不使用外部阴影。
选择状态与信息层级通过颜色和层次结构传达。
卡片材质与层级规范
本文公开说明 Qokit 工作界面在什么场景使用阴影、透明、渐变和背景磨砂。适用于平台扩展、Builder、CMS、Dashboard、Studio 和 Admin。营销页面与生成站点可以更有表现力,但效果必须归属于当前主题,并保证内容可读。
核心原则
视觉效果用于表达结构,不用于装饰每一个区块:
- 内容通过背景色差区分。
- 容器通过透明或克制的渐变表达归属。
- 浮层通过阴影表达层级。
- 交互通过颜色和焦点环表达状态。
独立实色卡片与输入框使用共享一级轻阴影;内部 Admin 内容卡、列表、嵌套表面和透明分组保持平整;真正的浮层才使用明显阴影。
判断顺序
添加材质效果前,先判断表面的角色:
- 是否是独立实色卡片或输入框?使用共享的一级表面或字段阴影;内部 Admin 内容卡保持平整。
- 是否是列表行、嵌套卡片、重复选项或透明分组?保持平整。
- 是否 overview 的 Status / Priority 语义 Object(网站状态、优先判断)?允许 toned 浅洗底,无内容阴影、无装饰网格纹理;禁止内嵌 elevated MetricCard,也不是页面内 Shell。见管理工作台 Overview Panel Kit。
- 是否一组相关 Dense 行(次级指标、健康行、模块入口)需要底板?使用 Inset Group:单一浅底 +
--card-radius,无内容阴影,内部分隔用--list-border;禁止组内再套 elevated MetricCard。这不是 Shell。 - 是否多个 Object 卡并排出现在管理工作台右栏?保持为平级内容卡,用 gap 分隔;Metric 网格不得铺整组
--list-surface壳。页标题与分区眉题留在 Quiet Paper Attention 的 Ink 层;overview 服从 Panel Kit(Status → Priority → Action → Metric → Detail),范例为获客运营看板。 - 是否组织侧栏、编辑器等常驻工作区(而非右栏分组)?使用 Shell。
- 是否覆盖页面内容或出现在当前平面上方?使用浮层阴影。
- 是否处于拖拽、缩放或临时悬浮状态?使用临时阴影。
- 是否只是为了表达 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检查通过。