Skip to content

Documentation

Page Shells

How AdminPageShell and AdminCard divide an (app) page: title, theme canvas, card elevation, and the slots you fill.

10/25/2026
9 min read Edit on GitHub

Every (app) page is one AdminPageShell and one or more AdminCard blocks. The shell owns the canvas, the title, and the header actions. The card owns elevation. Controls inside the card come from the native UI.

<script lang="ts">
  import AdminPageShell from '@components/admin-page-shell.svelte';
  import AdminCard from '@components/admin-card.svelte';
  import Button from '@components/ui/button.svelte';
</script>

<AdminPageShell title="Webhooks" icon="mdi:webhook" description="Outbound events for this tenant.">
  {#snippet actions()}
    <Button variant="primary" leadingIcon="mdi:plus">New webhook</Button>
  {/snippet}

  <AdminCard class="p-4">
    <!-- fields, tables, empty states -->
  </AdminCard>
</AdminPageShell>

PageTitle (src/components/page-title.svelte) is the header inside the shell. Pass title, icon, description, back link, and the actions snippet through AdminPageShell. A second <h1> in the page body duplicates that header.

What the shell renders

AdminPageShell (src/components/admin-page-shell.svelte) fills the route’s <main>:

  1. A root with class admin-theme-container, background-color: var(--admin-bg-page), and color: var(--admin-text-body). Theme CSS is scoped to this container, so the page, portalled overlays, and scrollbars repaint together.
  2. PageTitle, sticky to the top of the shell. titleBorderless defaults to true, so the header has no bottom rule until you set titleCompact or titleBorderless={false}.
  3. An AdminZone named content-header, then the children snippet in a padded column (px-2 pb-2 pt-4), then an AdminZone named content-footer. Plugins inject those zones. Page content goes in children.
  4. Vertical rhythm between children is space-y-4, space-y-6 (the default), or space-y-8.

fullHeight switches the root to a column that does not scroll, and the content area becomes flex-1 min-h-0. Use it for an editor that scrolls an inner pane.

flushContent is for the rare full-height workspace whose first row is its own sub-header (the media gallery’s breadcrumb and toolbar bands): it removes pt-4, pb-2 and the space-y rhythm so that row sits directly under PageTitle and the card reaches the bottom edge. The horizontal px-2 inset stays. Leave it off for editor layouts that need the normal breathing room.

Motion

Two transitions run, and both drop to 0ms when the user prefers reduced motion or the theme turns reduced motion on (src/utils/admin-transitions.ts):

Transition Owner What you see
adminPage (app)/+layout.svelte, keyed on page.url.pathname 240ms fade and a small rise. Duration is 0 while a browser View Transition is running, so the route does not animate twice. Query changes (?edit, filters) keep the same pathname and do not replay it.
adminFade AdminPageShell when animate is true (the default) 200ms opacity fade as the shell mounts.

Leave animate on. Add in:adminStagger on a grid of cards when a list should cascade. Skip per-page in:fly and in:scale. The shared helpers are the GUI styling guide.

Shell props

Prop Type Default Role
title string — Required. Becomes PageTitle’s name and the visible heading.
icon string — Iconify name beside the title (mdi:cog).
description string — Subtitle under the title.
highlight string '' Substring of title drawn in the accent color.
showBackButton boolean false Back control in the title row.
backUrl string '' Target of that control.
actions snippet — Trailing header controls. One primary Button, supporting actions as tertiary or ghost.
subtitle snippet — Extra line under the description when a string is not enough.
spaceY '4' \| '6' \| '8' '6' Gap between top-level children.
titleCompact boolean false Tighter title row.
titleBorderless boolean true Hides the title-row border.
fullHeight boolean false Editor layout: the shell does not scroll.
flushContent boolean false Full-height workspace: no pt-4/pb-2/space-y, content flush under the title and bottom.
animate boolean true Plays adminFade on mount.
navColor favorite color theme default Tailwind background class for this route’s FloatingNav spoke when a user favorites it.
children snippet — The page body.

Anatomy of a data page

A page with tabs and a table reads top to bottom as one column, and the rule does the separating:

  1. PageTitle from the shell. The description belongs here; an intro paragraph inside the card pushes the tab row down and makes the page look unlike its siblings.
  2. Tab row — tabs plus the trailing action, with the rule spanning the whole row (TAB_ROW) or the strip (TAB_STRIP). The active tab owns a 2px accent underline; pages do not declare their own tab classes. Props and tokens: Tabs.
  3. Toolbar band — search, filter, column picker, saved views, metrics, facet chips, and the row action in one SMART_TABLE_TOOLBAR row (my-4, justify-between).
  4. Table — SmartTableShell is the only scroller. With fullHeight on the shell the page never scrolls; the table body does.

/user (management), /config/queue, /config/access-management, and /config/design-system follow this order. A change to one that does not is a layout bug, not a variant — fix the page instead of adding a fourth tab dialect or a second scroller.

AdminCard

AdminCard (src/components/admin-card.svelte) is the content surface. It reads getThemeContext() and paints the card role, which sits above the page canvas.

On the default path (no variant, no preset) the root is div.card.rounded with inline style:

Property Token Theme variant effect
Background --admin-bg-card Follows light and dark.
Text --admin-text-body Follows light and dark.
Radius --radius (--admin-radius-input) The rounded utility keeps the compact card radius token-driven and density-aware.
Border color --admin-border-default —
Border width theme.cardBorder 0 when the theme variant is flat. Otherwise --admin-border-width.
Shadow theme.cardShadow none when flat. A soft elevation shadow when bordered (the default). A larger shadow when elevated.

A flat theme therefore has no shadow and no border. hover:shadow-lg on the card paints a shadow the theme just removed. Put padding on the card with class (class="p-4"). Nest a second AdminCard when a block inside the page needs its own surface.

Preset path

Set variant or preset only when the block is a status surface (a success summary, an error panel) and should use the same recipes as Card:

Prop Values
variant 'primary' \| 'secondary' \| 'tertiary' \| 'success' \| 'warning' \| 'error' \| 'surface'
preset 'filled' \| 'tonal' \| 'outlined'

That path renders Card from @components/ui/card.svelte and does not apply the inline --admin-* styles above. class is forwarded. Other attributes (id, data-testid, role) are forwarded only on the default token path. Put test ids on a token card, or on an element inside a preset card.

Card itself also accepts header and footer snippets and a color override. Page sections stay on AdminCard so flat, bordered, and elevated themes keep working. Use Card directly for a small preset tile that is not a page section.

Card props

Prop Type Role
class string Extra classes. Padding, grids, and overflow belong here.
children snippet Card body.
variant theme hue Switches to the preset Card. Omit for a normal section.
preset 'filled' \| 'tonal' \| 'outlined' Switches to the preset Card. Omit for a normal section.
other attributes HTMLAttributes<HTMLDivElement> Applied on the token path: id, data-testid, aria-*.

A full page

<script lang="ts">
  import AdminPageShell from '@components/admin-page-shell.svelte';
  import AdminCard from '@components/admin-card.svelte';
  import Button from '@components/ui/button.svelte';
  import Input from '@components/ui/input.svelte';

  let name = $state('');
</script>

<AdminPageShell
  title="General"
  icon="mdi:cog"
  description="Site name shown in the admin header."
  showBackButton
  backUrl="/config/system-settings"
>
  {#snippet actions()}
    <Button variant="tertiary" href="/config/system-settings">Cancel</Button>
    <Button variant="primary" type="submit" form="general-form">Save</Button>
  {/snippet}

  <AdminCard class="p-4">
    <form id="general-form" class="space-y-4">
      <Input label="Site name" bind:value={name} />
    </form>
  </AdminCard>
</AdminPageShell>

The header Button with href is a link. The save Button is a submit control associated with the form by form="general-form", because the action sits outside the <form>.

Wide tables inside the card need class="overflow-x-auto" on a wrapper. Touch targets on actions stay at least 40px: Button size md (the default) is 40px tall; sm is 32px and is for dense toolbars.

Plugin workspaces

A plugin that declares a plugin_workspace slot (Smart Importer, Unified Data Hub) is rendered by PluginWorkspaceOverlay inside the shell’s <main>, not over the viewport:

  • The overlay is absolute inset-0 z-30 against the relative <main>, so the left and right sidebars stay visible and usable — the same contract as Media Gallery and the Collection Builder.
  • While a workspace is open, the underlying page content and the sticky action bar are unmounted, so the workspace title is the only <h1> on screen and nothing behind it is focusable.
  • ?plugin=<id> is the source of truth: the overlay syncs the store with page.url on navigation, which is what makes the shell’s back button (goto('/config')) actually close it.

Don’t wrap a plugin workspace in a second AdminPageShell that also owns the page title — pick one owner. See src/components/system/plugin-workspace-overlay.svelte and src/routes/(app)/+layout.svelte.

Next steps

  • Props and accessibility for Button, fields, and Modal: Native controls.
  • Tokens, shade steps, and RTL: GUI styling guide.
  • Try the same card under flat, bordered, and elevated: /config/design-system?tab=preview.
uiadmin-page-shelladmin-cardlayout
Was this page helpful?