Save the Dogs Design System

Surfaces

Every framed region in the app is a SURFACE. This page is two things: the composable <Surface> primitive — the keystone the whole taxonomy composes from — shown across all five of its variant axes; and the canonical surface taxonomy, an 11-category registry mapping every surface kind to what EXISTS today (the real component + import path), what's WIRED in @phauna/ds and waiting to be surfaced, and what's PLANNED. The registry is data (src/components/ds/surface/taxonomy.ts); this page renders entirely from it, so the docs can't drift. @phauna/ds stays UNFORKED — Surface is purely additive in our ds/ layer, and the existing DS surfaces (Card, Modal, DataGrid…) are MAPPED here, not rewritten.

elevation: flat · raised (default) · overlay · modal · sunken. The outer drop-shadow depth (sunken is the inset exception). LIGHT only — in DARK shadows resolve to none; depth comes from the ramp + border.
padding: none · xs · sm · md (default) · lg · xl. The inner gutter, mapped to the Tailwind spacing scale.
radius: none · sm · md · lg (default) · xl · pill. The corner radius, from the DS --radius-* scale.
tone: surface (default) · surface-2 · surface-3 · overlay · accent-soft · good · warn · bad. The fill; the status tones pair a soft -bg with matching ink.
bordered · interactive · inset: bordered (default true) the hairline edge; interactive a hover/focus affordance (paint a ring only when focusable, e.g. as="button"); inset the recessed-well treatment.
as: Polymorphic host element/component (default div). Server-safe (no state/effects), so Surface renders in server or client trees.

tsx

import { Surface } from "@/components/ds/surface";

<Surface elevation="raised" padding="md" radius="lg" tone="surface">
  Any framed region — composed from the one Surface keystone.
</Surface>

Anatomy — elevation

The five elevation keys on live Surface tiles, framed on the page canvas so the shadow (or, for sunken, the inset well) reads. raised is the default card lift; overlay and modal are the higher tiers (popovers, modals); flat sits on the page with no shadow; sunken carves a recessed well.

flat

raised

overlay

sunken

elevation — flat · raised · overlay · modal · sunken

Anatomy — padding

The padding ramp from none to xl. A dashed inner outline traces the content box so each inset is visible; the border, radius and elevation are identical across all six.

none

padding — none · xs · sm · md · lg · xl

Anatomy — radius

The corner-radius scale from square (none) through the DS --radius-* steps to a full pill. lg is the default surface corner.

none

pill

radius — none · sm · md · lg · xl · pill

Anatomy — tone

The fill tones — the surface ramp (surface → surface-2 → surface-3), the overlay fill, accent-soft, and the three status tones (good · warn · bad), which pair a soft -bg with matching ink. Flip the theme in the top bar to confirm each re-skins.

surface

surface-2

surface-3

overlay

accent-soft

good

warn

bad

tone — the ramp, accent-soft, overlay & the status tones

Anatomy — interactive & inset

Two modifiers. interactive adds a hover edge/fill shift plus a focus-visible ring (the ring only paints when the host is actually focusable — here as="button"); hover and tab to the middle tile to see both. inset (or elevation="sunken") replaces the drop-shadow with a recessed well.

static (default)

inset — recessed well

static vs interactive (as=button) vs inset

The surface taxonomy

The canonical registry, grouped by its 11 categories. Each surface is a card (rendered on the Surface primitive itself) showing its name, a status badge — Exists (shipped, with the real component + import path), Wired (in @phauna/ds, to be surfaced) or Planned (a reserved slot) — a one-line blurb, and what it composes from. The trivially-renderable 'exists' surfaces carry a small live example.

Base: The page-level frames everything else sits inside — the app shell, the content container, and the layout panes.
Container: Bordered surfaces that group related content and lift it off the canvas — the Surface keystone and its card family.
Navigation: Surfaces whose job is to move you somewhere — sidebars, headers, tabs, breadcrumbs and the bars that hold them.
Overlay: Surfaces that float above the page on a higher elevation tier — modals, drawers, popovers and floating panels.
Collection: Surfaces that lay out many items at once — tables, trees, grids, calendars and feeds.
Content: Surfaces built to read or author a single body of content — prose, rich-text, forms and record pages.
Status: Surfaces that report what happened, what's missing, or what's loading — banners, empty/error states and loaders.
Interactive: Rich, direct-manipulation canvases — maps, charts, documents and the heavier viewers/editors.
Utility: Persistent helper surfaces docked beside the main work — filters, search, inspectors and properties panels.
Temporary: Lightweight, transient surfaces summoned on demand and dismissed — tooltips, menus, peeks and sheets.
System: Whole-screen states owned by the app lifecycle — onboarding, auth, errors, locks and maintenance.

Base

The page-level frames everything else sits inside — the app shell, the content container, and the layout panes.

AppShell

Exists

The outermost app frame — header + sidebar + main region scaffolding that hosts a whole screen.

AppShell@savethemarshalldogs/design-system

AppMain

Exists

The main scrollable content region that lives inside AppShell.

AppMain@savethemarshalldogs/design-system

composes from AppShell

PageContainer

Exists

The max-width content well (size variants) that centres a page's content within AppMain.

PageContainer@/components/ds/primitives

Section

Exists

A titled content band — Section is the @phauna/ds wrapper, SectionHeader the STD titled rule used across the portal.

Section / SectionHeader@savethemarshalldogs/design-system · @/components/ds/primitives

Layout panes

Exists

Multi-pane page skeletons — the app frame (AppLayout) and the list↔detail master/detail split (ListDetailLayout).

AppLayout / ListDetailLayout@savethemarshalldogs/design-system · @phauna/ds/recipes

Box / Container

Exists

The unstyled layout atoms — a bare Box and a width-constrained Container to build bespoke frames from.

Box / Container@savethemarshalldogs/design-system

Canvas

Planned

An unbounded, pannable/zoomable free-form work area (for a map-like or diagram-like full-bleed page).

composes from Surface

Workspace

Planned

A multi-region work layout with resizable panes around the main content (the SplitView/PaneLayout family was removed unused — kernel-slim round 2, 2026-07-22; rebuild if a workspace surface returns).

composes from Surface

Container

Bordered surfaces that group related content and lift it off the canvas — the Surface keystone and its card family.

Surface

Exists

THE keystone. A composable, polymorphic, server-safe surface (elevation × padding × radius × tone × interactive). Every surface below is a Surface with locked-in variants.

Surface@/components/ds/surface

a live <Surface>

Card

Exists

The everyday elevated surface — bordered, raised, padded. Padding + accent variants; the portal's ground-floor container.

Card@savethemarshalldogs/design-system

composes from Surface

Card

The everyday elevated surface.

WidgetCard

Exists

A dashboard widget shell — a Card with a title/action header band over a body slot.

WidgetCard@savethemarshalldogs/design-system

composes from Card

Scorecard

Exists

A KPI tile — a Card framing a single big metric with a label/delta.

Scorecard@savethemarshalldogs/design-system

composes from Card

CompactCard

Exists

The grouped-list surface — a padding-less Card with an optional header band and a divide-y body of rows.

CompactCard@/components/ds/primitives

composes from Card

Go to

ActionCard

Exists

A single focused call-to-action card — accent icon + label + short desc + one action (href or cta).

ActionCard@/components/ds/primitives

composes from Card

Find your team

Match with a local community.

Panel

Exists

A flat, full-height region surface (no lift) for the body of a pane or a settings section.

Panel@/components/ds/surface

composes from Surface

Well

Exists

A recessed, inset surface (sunken elevation) for nesting content one layer down — code blocks, quoted input.

Well@/components/ds/surface

composes from Surface

Tile

Exists

A small, square-ish interactive surface for a grid of equal-weight choices (a launcher / picker cell).

Tile@/components/ds/surface

composes from Surface

Sheet

Exists

A large paper-like surface for a document or print-style layout (the canvas of a report).

Sheet@/components/ds/surface

composes from Surface

GroupBox

Exists

A bordered, captioned grouping of related controls (a fieldset-style enclosure within a form).

GroupBox@/components/ds/surface

composes from Surface

Surfaces whose job is to move you somewhere — sidebars, headers, tabs, breadcrumbs and the bars that hold them.

Sidebar

Exists

The primary vertical nav rail — grouped NavItems down the left edge.

Sidebar@savethemarshalldogs/design-system

AppHeader

Exists

The top app bar — brand, global actions and account, spanning the page.

AppHeader@savethemarshalldogs/design-system

NavItem

Exists

A single nav link — icon + label + active/badge state — the atom Sidebars are built from.

NavItem@savethemarshalldogs/design-system

composes from Sidebar

Breadcrumbs

Exists

The hierarchical trail showing where the current page sits — an a11y build (aria-current on the last crumb, optional middle-collapse) in the workflow family.

Breadcrumbs@/components/ds/workflow

PageTabs

Exists

The STD in-page tab strip — switches between sibling views of one record/page.

PageTabs@/components/ds/primitives

Tabs

Exists

The headless @phauna/ds tab primitive (list + panels) for fully custom tabbed surfaces.

Tabs@/components/ds/overlays

Toolbar

Exists

A horizontal bar of grouped actions/controls pinned above a content region.

Toolbar@/components/ds/surface

composes from Surface

NavigationRail

Exists

A slim icon-only vertical rail (a collapsed Sidebar) for compact / dense apps.

NavigationRail@/components/ds/surface

composes from Surface

BottomBar

Exists

A bottom-anchored mobile tab bar — the primary nav on small screens.

BottomBar@/components/ds/surface

composes from Surface

CommandBar

Exists

A contextual action bar that appears for the current selection (bulk actions, edit mode).

CommandBar@/components/ds/surface

composes from Surface

Overlay

Surfaces that float above the page on a higher elevation tier — modals, drawers, popovers and floating panels.

Modal

Exists

A centred, focus-trapped dialog on the modal elevation tier with a backdrop scrim.

Modal@/components/ds/overlays

composes from Surface

Drawer

Exists

An edge-anchored sliding panel for secondary flows without leaving the page.

Drawer@/components/ds/overlays

composes from Surface

Popover

Exists

A small anchored floating surface for contextual controls or details.

Popover@/components/ds/overlays

composes from Surface

Tooltip

Exists

A tiny hover/focus label clarifying an element on the overlay tier.

Tooltip@/components/ds/overlays

ConfirmDialog

Exists

A pre-composed yes/no confirmation Modal for destructive or irreversible actions.

ConfirmDialog@/components/ds/overlays

composes from Modal

CommandPalette

Wired

The ⌘K fuzzy command/navigation launcher — available in @phauna/ds, to be wired through our ds/ layer.

CommandPalette@/components/ds/command

composes from Modal

Flyout

Exists

A larger anchored panel than a Popover — a rich mega-menu / detail flyout.

Flyout@/components/ds/surface

composes from Popover

FloatingPanel

Exists

A draggable, non-modal floating window that persists over the workspace.

FloatingPanel@/components/ds/surface

composes from Surface

InspectorPanel

Exists

A docked-or-floating overlay inspecting the current selection (overlay form of the Utility inspector).

InspectorPanel@/components/ds/surface

composes from Drawer

Collection

Surfaces that lay out many items at once — tables, trees, grids, calendars and feeds.

DataTable / DataGrid

Exists

The admin-table lingua franca — sortable columns, selection, sticky header, density, CSV export, virtualization.

DataTable / DataGrid@/components/ds/grid

Tree

Exists

A collapsible hierarchical list for nested data (megaregion → region → team) — the TreeView wrapper over the @phauna/ds Tree plus a composed FileBrowser.

TreeView / FileBrowser@/components/ds/tree

composes from Surface

List

Exists

A simple semantic list surface (ordered/unordered, marker variants) for plain enumerations.

List / ListItem@savethemarshalldogs/design-system

Confirm your address
Join a team

CardGrid / AutoGrid

Exists

Responsive grids of equal cards — fixed-column (CardGrid) or auto-fitting (AutoGrid).

CardGrid / AutoGrid@savethemarshalldogs/design-system

ActivityFeed

Exists

A reverse-chronological stream of activity entries (who did what, when).

ActivityFeed@savethemarshalldogs/design-system

Kanban

Exists

A column-of-cards board with drag-between-columns (status-pipeline view).

KanbanBoard@/components/ds/surface

composes from Surface

Masonry

Exists

A staggered, variable-height tile layout for mixed-size cards/media.

MasonryGrid@/components/ds/surface

composes from Surface

Gallery

Exists

A grid of media thumbnails with a lightbox/preview affordance.

Gallery@/components/ds/surface

composes from Surface

Feed

Exists

A rich, infinitely-paged content stream of heterogeneous post cards.

Feed@/components/ds/surface

composes from Surface

Timeline

Exists

A time-ordered vertical track of dated events (built on the @phauna/ds TimelineItem atom).

Timeline@/components/ds/surface

composes from Surface

Content

Surfaces built to read or author a single body of content — prose, rich-text, forms and record pages.

Prose / Article

Exists

The long-form reading surface — typographic defaults for rendered markdown/HTML article bodies.

Prose@savethemarshalldogs/design-system

RichTextEditor

Exists

The Tiptap authoring surface — formatting toolbar with markdown/HTML output.

RichTextEditor@/components/ds/editor

Form

Exists

The form surface — Field wrappers (label/help/error) composing the STD input controls.

Field (+ Input/Select/…)@/components/ds/primitives

RecordPage / DashboardLayout

Exists

Pre-composed page recipes — a single-record detail page and a widget dashboard.

RecordPage / DashboardLayout@savethemarshalldogs/design-system/recipes

DocumentViewer

Wired

A rich PDF/document viewer with highlights and critical-facts overlays — in @phauna/ds (the local ds/document barrel was removed unused, kernel-slim round 2; re-wire from the DS package if needed).

DocumentViewer@savethemarshalldogs/design-system/document

CodeEditor

Planned

A syntax-highlighted code editing surface (deferred — no current app need).

composes from Surface

Status

Surfaces that report what happened, what's missing, or what's loading — banners, empty/error states and loaders.

Banner

Exists

A full-width page-level notice bar (toned) for a standing message at the top of a region.

Banner@savethemarshalldogs/design-system

Callout

Exists

An inline highlighted aside within content — a tip / note block set off from the prose.

Callout@savethemarshalldogs/design-system

An inline aside set off from the surrounding prose.

EmptyState

Exists

The calm 'nothing here yet' block — icon + title + description + an optional action.

EmptyState@savethemarshalldogs/design-system

You're all caught up

No notifications right now.

Skeleton

Exists

Pulsing placeholders that hold a region's shape while its content loads.

Skeleton / SkeletonText@savethemarshalldogs/design-system

Spinner

Exists

An indeterminate loading indicator for an in-flight action.

Spinner@savethemarshalldogs/design-system

InlineMessage

Exists

A small toned inline note (icon + text) attached to a field or row — sub-Alert weight.

InlineMessage@savethemarshalldogs/design-system

Saved just now.

Alert

Exists

The STD inline banner — four semantic tones with sensible role/aria-live defaults.

Alert@/components/ds/primitives

Heads up — the roster sync runs every 10 minutes.

ErrorState

Exists

The failure counterpart to EmptyState — a danger glyph, plain reason, and a retry control.

ErrorState@/components/ds/primitives

Something went wrong

We couldn't load your teams.

Toast

Exists

Transient corner notifications fired imperatively via useToast through a mounted Toaster.

Toaster / useToast@/components/ds/overlays

Interactive

Rich, direct-manipulation canvases — maps, charts, documents and the heavier viewers/editors.

MapView

Exists

The maplibre map surface — markers, territory/district polygons and member clusters.

MapView@/components/ds/maps

Charts

Exists

The recharts data-viz surfaces for trends, comparisons and breakdowns.

LineChart / AreaChart / BarChart / DonutChart@/components/ds/charts

DocumentViewer

Wired

The interactive PDF/document canvas (highlights, thumbnails) — in @phauna/ds (local barrel removed unused, kernel-slim round 2).

DocumentViewer@savethemarshalldogs/design-system/document

Canvas / Whiteboard

Planned

A free-form drawing/diagramming surface (deferred — niche, no current need).

composes from Surface

Graph

Planned

A node/edge network visualization with pan/zoom (deferred — niche).

composes from Surface

Spreadsheet

Planned

An editable cell-grid with formulas (deferred — DataGrid covers tabular needs today).

composes from DataGrid

Terminal

Planned

A console/log surface with a command line (deferred — niche).

composes from Surface

ImageViewer

Planned

A zoom/pan single-image viewer with a lightbox (niche — pairs with Gallery).

composes from Surface

VideoPlayer

Planned

A framed video player surface with controls (niche).

composes from Surface

Utility

Persistent helper surfaces docked beside the main work — filters, search, inspectors and properties panels.

FilterBar / FacetRail

Exists

The faceted-filter surfaces — a horizontal FilterBar and a vertical FacetRail driving a DataGrid.

FilterBar / FacetRail@/components/ds/grid

GlobalSearch

Wired

An app-wide search surface — in @phauna/ds (alongside the command palette), to be wired.

GlobalSearch@/components/ds/command

ActivityFeed

Exists

An activity stream docked as a side rail — recent changes/audit alongside the main view.

ActivityFeed@savethemarshalldogs/design-system

Inspector panel

Exists

A docked side panel showing/editing the properties of the current selection.

InspectorPanel@/components/ds/surface

composes from Surface

Properties panel

Exists

A grouped key/value editing surface for an object's attributes (form-dense inspector).

PropertiesPanel@/components/ds/surface

composes from Surface

Settings panel

Exists

A sectioned preferences surface — toggles and fields grouped by area.

SettingsPanel@/components/ds/surface

composes from Surface

History panel

Exists

A docked audit/revision trail for the current record — who changed what, when.

HistoryPanel@/components/ds/surface

composes from Surface

AIAssistant panel

Exists

A docked conversational assistant rail beside the main work area.

AIAssistantPanel@/components/ds/surface

composes from Surface

Temporary

Lightweight, transient surfaces summoned on demand and dismissed — tooltips, menus, peeks and sheets.

Tooltip

Exists

A transient hover/focus label — summoned on demand, dismissed on blur.

Tooltip@/components/ds/overlays

DropdownMenu

Exists

An anchored action list (kebab / row-actions / context menu) — a roving-tabindex role=menu over the Popover; degrades to ActionSheet on mobile.

DropdownMenu@/components/ds/surface

composes from Popover

Popover

Exists

A transient anchored panel for quick context, dismissed on outside-click.

Popover@/components/ds/overlays

Spotlight

Planned

A centred spotlight/quick-switch summoned by hotkey — a planned thin preset over CommandPalette (no dedicated @phauna/ds export today).

composes from CommandPalette

HoverCard

Exists

A rich preview card shown on hover-intent over a link/entity (more than a Tooltip).

HoverCard@/components/ds/surface

composes from Popover

PeekPreview

Exists

A quick inline peek at a record without navigating away from the list.

PeekPreview@/components/ds/surface

composes from Popover

BottomSheet

Exists

A bottom-anchored sliding sheet for mobile secondary content/actions.

BottomSheet@/components/ds/surface

composes from Drawer

ActionSheet

Exists

A mobile bottom sheet of large action choices (the touch context menu).

ActionSheet@/components/ds/surface

composes from BottomSheet

FabMenu

Exists

A floating-action-button that expands into a radial/stacked menu of quick actions.

FabMenu@/components/ds/surface

composes from Menu

System

Whole-screen states owned by the app lifecycle — onboarding, auth, errors, locks and maintenance.

WelcomeWizard

Exists

The onboarding surface — a multi-step wizard that captures a new volunteer's profile.

WelcomeWizard@/components/portal/WelcomeWizard

Login

Exists

The auth surface — the passwordless-first sign-in screen (portal & admin variants).

NotFound

Exists

The error surface — the friendly 404 screen for an unknown route.

not-foundapp/not-found.tsx

Lock screen

Exists

A whole-screen lock prompting re-authentication after an idle timeout.

LockScreen@/components/ds/surface

composes from Surface

Splash

Exists

A branded initial-load screen shown while the app boots.

SplashScreen@/components/ds/surface

composes from Surface

Permission

Exists

A 403/no-access screen explaining why a page is gated and how to gain access.

PermissionPrompt@/components/ds/surface

composes from Surface

Maintenance

Exists

A whole-screen 'down for maintenance' notice with an ETA.

MaintenanceScreen@/components/ds/surface

composes from Surface

Auth layout

Exists

A formalized centred auth shell (brand + card) shared by login/verify/reset screens.

AuthScreen@/components/ds/surface

composes from Surface

Error layout

Exists

A formalized whole-screen error shell shared by 404/500/permission/maintenance.

ErrorScreen@/components/ds/surface

composes from Surface