Skip to Content
Design

Cards and Surface Hierarchy

Guidelines for using content cards, workspace shells, overlays, shadows, and background blur.

Live componentCard layers

Content cards stay flat; the outer shell communicates workspace grouping.

Project overviewLaunch readiness
Content12 pages complete

A standard content Card does not use an outer shadow.

ChecksMobile ready

Selection and status are communicated through color and information hierarchy.

Card Material and Hierarchy Specifications

This document explains when shadows, transparency, gradients, and background blur are used in the Qokit interface. It applies to platform extensions, Builder, CMS, Dashboard, Studio, and Admin. Marketing pages and generated sites may be more expressive, but effects must belong to the current theme and ensure content readability.

Core Principles

Visual effects express structure, they do not decorate every block:

  • Content is distinguished by background color differences.
  • Containers express belonging through transparency or restrained gradients.
  • Overlays express hierarchy through shadows.
  • Interactions express state through colors and focus rings.

Standalone opaque cards and fields use a shared low elevation; internal Admin content cards, lists, nested surfaces, and transparent groups remain flat; only true overlays use pronounced shadows.

Decision Order

Before adding material effects, determine the role of the surface:

  1. Is it a standalone opaque card or field? Use the shared low surface or field shadow, except for internal Admin content cards, which stay flat.
  2. Is it a list row, nested card, repeated option, or transparent group? Keep it flat.
  3. Is it an overview Status / Priority semantic Object (site health, priority judgment)? Allow a toned wash with no content shadow and no decorative grid texture; do not nest elevated MetricCards inside, and do not treat it as an in-page Shell. See the management workbench Overview Panel Kit.
  4. Does a set of related Dense rows (secondary metrics, health rows, module entries) need a shared plate? Use an Inset Group: one light tint + --card-radius, no content shadow, separators via --list-border; do not nest elevated MetricCards inside. This is not a Shell.
  5. Are multiple Object cards sitting side by side on the management right rail? Keep them as sibling content cards separated by gap; Metric grids must not use a shared --list-surface plate. Page titles and section eyebrows stay on the Quiet Paper Attention ink layer. Overview pages follow the Panel Kit (Status → Priority → Action → Metric → Detail); the acquisition dashboard is the exemplar.
  6. Does it organize a persistent workspace (sidebar, editor chrome), not a right-rail section? Use a Shell.
  7. Does it cover page content or appear above the current plane? Use overlay shadows.
  8. Is it in a drag, scale, or temporary hover state? Use temporary shadows.
  9. Is it merely expressing hover, selection, or focus? Use the shared hover role, interactive background colors, and focus rings.

Do not stack shadows, transparency, gradients, and blur simultaneously unless the surface role truly requires it.

Scenario Matrix

Surface RoleShadowTransparency or GradientBackground Blur
Standalone opaque content cards and metric cards (outside Admin and overview Panel Kit)Shared low surface shadowSlight background color difference allowedNone
Internal Admin content cards across overview, list, detail, and settingsNoneUse surface color and spacing to separate contentNone
Overview Panel Kit Objects (Status / Priority / Action / Metric / Detail)NoneStatus/Priority may use a semantic wash; no decorative gridNone
List rows, nested cards, transparent groups, repeated optionsNoneSlight background color difference allowedNone
Inset Group (plate for related Dense rows)NoneRecommended light --list-surface mixNone
In-page grouping ShellNoneRecommended (avoid on the management right rail; separate Object cards with gap, Dense rows with Inset Group)Usually unnecessary
Sidebar or persistent workspace ShellLightweightRecommendedAllowed if visible content is behind it
Dialog, Popover, Dropdown, Context MenuDistinct overlay shadowBackground must be solid enough to ensure readabilityAllowed
Drag preview, scale state, hover previewTemporary strongerOptionalUsually not needed
HoverPreserve or slightly strengthen the low shadow outside Admin; keep Admin content cards flatMay change backgroundNo change
Selected or Active StateNoneAccent color background or restrained gradientNo change
Input fields and search boxesVery light field shadowUse control surface colorUsually not needed
Standalone primary actions, standalone pills, segmented-control shellsVery light control shadowUse control surface colorUsually not needed
Toolbars and transparent inner controlsNoneUse control surface color or transparencyUsually not needed
Marketing page or generated site visual cardsDetermined by themeAllowedUse with restraint

Component Mapping

  • <Card> defaults to layer="content": shared low shadow, no border, default 20px rounded corners. Muted, nested, list, and transparent variants remain flat.
  • Internal Admin content cards and in-page sections remain flat across all page templates; navigation shells, overlays, focus rings, and active drag or resize previews retain their distinct layers.
  • A regular Card uses 24px padding on desktop and 20px on mobile; management workspaces use 16px and nested muted cards use 12px. Cards with edge-to-edge media explicitly remove outer padding and pad their content region; mobile styles preserve these overrides.
  • Generated-site Card radius, padding, and shadow follow site theme tokens. Compact layouts scale the theme padding, and preview and published pages use the same resolved values.
  • <Card layer="shell">: Reserved for persistent workspace chrome (sidebar, editor). Do not use an in-page Shell on the management right rail to wrap Object cards; group with gap, ink eyebrows, and Inset Groups instead.
  • Status / Priority / Action / Metric (overview Panel Kit): no content shadow; Status/Priority may use a toned wash with no decorative grid; never nest elevated MetricCards inside. Shared implementation lives in workspace-page-surface and the acquisition dashboard CSS.
  • Inset Group (.qk-workspace-inset-group): light rounded plate for related Dense rows; no content shadow; never nest elevated MetricCards inside.
  • <Card shape="pill">: Used for compact single-line cards, with pill-shaped rounded corners.
  • SidebarNavigation: Independent workspace Shell, retaining distinct gradients, transparency, blur, and light shadows.
  • Studio's PromptPanel as a workspace container: uses --workspace-shell-shadow.
  • DialogPanel, dropdown menus, Popovers, context menus, and concept browsers: use overlay shadows.
  • Builder canvas, device previews, generated site previews, drag previews, and scale states: because they represent independent preview planes or temporary interaction layers, dedicated shadows can be retained.

Do not create nested floating content cards. Management overview follows the Quiet Paper Attention Panel Kit: ground --bg, ink page copy / toolbar, Status → Priority → Action → Metric → Detail; Metric grids have no shared plate. Except for true overlays, one DOM ancestry path may contain at most one ordinary content or control shadow.

Design Variable (Token) Usage

Prioritize shared Tokens; do not hardcode effects:

  • Content card shadow: --card-shadow: var(--qk-shadow-surface)
  • Content card hover shadow: --card-shadow-hover: var(--qk-shadow-surface-hover)
  • Field shadow: --input-shadow: var(--qk-shadow-field)
  • Active field shadow: --input-state-shadow: var(--qk-shadow-field-active)
  • Control shadow: --qk-shadow-control / --qk-shadow-control-hover
  • Primary control shadow: --qk-shadow-control-accent / --qk-shadow-control-accent-hover
  • Content card blur: --card-backdrop-filter: none
  • Shell surface: --card-shell-surface
  • Shell blur: --card-shell-backdrop-filter
  • Workspace Shell shadow: --workspace-shell-shadow
  • Dialog surface: --dialog-surface, providing restrained theme gradients
  • Dialog blur: --dialog-backdrop-filter
  • Dialog overlay shadow: --dialog-shadow
  • Dialog corner radius: Reuse --card-radius
  • Keyboard focus: --focus-ring
  • Overlay shadows: Use existing Dialog, Dropdown, Menu, or page-level overlay Tokens

Standard content cards and workspace panels must not use strong generic --shadow Tokens.

The global scale stays quiet: short offsets, low opacity, and gradual separation by placement. Routes must not deepen or enlarge shared Card, field, or control shadows; Popovers and Dialogs communicate detachment with wider offset and blur, not a darker grey cloud.

Interaction Rules

Hover

  • Do not escalate content cards beyond --qk-shadow-surface-hover.
  • Do not lift content cards via translateY.
  • Use slight background changes or clear control feedback.
  • Do not change shape to avoid inconsistent corner radii or shadow clipping.

Selection and Activation

  • Use accent color surfaces, icon states, semantic states, or restrained gradients.
  • Do not express state solely through shadows.

Keyboard Focus

  • Use shared focus-visible rules or --focus-ring.
  • Generic card shadows cannot replace focus indicators.
  • Must be clearly visible in both light and dark themes.

Drag and Scale

  • Stronger shadows are only allowed while layers are moving or resizing.
  • Temporary shadows must be removed after interaction ends.
  • Overflow containers must not clip the feedback effects of moving layers.

Transparency and Background Blur

Transparency expresses the belonging relationship between outer surfaces and workspaces. Background blur is only meaningful when there is actually visible content, color, or images behind the surface.

  • Do not use blur on solid color backgrounds; it only increases rendering cost and fails to express hierarchy.
  • Regardless of the background behind it, text, icons, and controls must remain clearly readable.
  • When the browser does not support background blur, an opaque or readable fallback background is required.
  • Blur intensity in dense work interfaces should be restrained.
  • Both light and dark themes must be verified.

Exceptions Where Shadows Are Retained

  • Workspace sidebar Shells
  • Dialogs, Popovers, Dropdowns, menus, and modal panels
  • Studio concept browsers and confirmation overlays
  • Builder canvas, device frames, and generated site preview planes
  • Drag previews, scale feedback, and temporary floating tools
  • Primary action buttons where shared button Tokens define shadows
  • Marketing pages and generated site visual elements controlled by the current theme

These exceptions must not affect standard content cards via broad selectors or shared Tokens.

Review Checklist

  • Standalone opaque content cards and fields use only the shared low elevation roles.
  • Standalone primary actions, standalone pills, and segmented-control shells use only the shared very-low control elevation.
  • In-page groups, list rows, nested cards, transparent groups, repeated tabs/pills, toolbars, and composite-control inner items remain flat.
  • Search, filter, sort, view, and inline primary actions remain flat inside toolbars; the low field elevation must not leak into a toolbar, except for the keyboard focus ring.
  • A Segmented control nested inside an already elevated card, dialog, or toolbar keeps both its shell and active item flat; pointer clicks do not display the keyboard focus ring.
  • Except for true overlays, an ancestry path does not stack multiple ordinary shadows.
  • Hover does not vertically move content cards.
  • Nested content cards have been removed, or the outer layer is explicitly defined as a Shell.
  • Only true Shells use --workspace-shell-shadow.
  • Only true overlays and temporary interaction layers use stronger shadows.
  • Visible content exists behind background blur, and a readable fallback background is present.
  • focus-visible uses a focus ring.
  • Sufficient contrast is maintained in both light and dark themes.
  • Rounded surfaces do not clip hover, focus, drag, or overlay feedback.
  • No new horizontal overflow occurs at desktop and mobile widths.
  • npm run ui:check-card-surfaces --workspace @qokit-ai/web check passed.

On this page