System map

Pro

Services on three tiers, drawn as planes: edge, services, data. Pick one to see what it needs, or what breaks if it fails, across the tiers. Affected blocks turn danger-tinted, needed ones turn grey, and the summary lists them by name.

Installs components/ui/system-map.tsxDepends on @radix-ui/react-slot, lucide-reactMotion none in component source

pnpm dlx shadcn@latest add @caliper/system-map

Postgres fails.

4 services affected: CDN, Gateway, Auth, Billing.

Primary for auth and billing. Failover takes about two minutes.

When to use #

Use it for

Blast radius: what a change or an outage in one service reaches.
Explaining a layered architecture where the direction of dependency matters.

Skip it when

Hundreds of services or arbitrary graphs; use a graph view.
Showing live health; use the status board.

Decisions #

Why it is built this way, so you know what to keep when you change your copy.

Behaviour

The list is the interface: The planes answer a click, but the list of services is the keyboard and screen reader route, and it says failed, affected or needed in words.

Styling

Colour is never the only signal: Each state is also a word in the list and the summary, so the map reads the same in greyscale.

Usage

Links mean needs: A link from gateway to auth says the gateway needs auth. Failing auth then affects the gateway, and nothing else has to be declared.

Installation #

terminal

pnpm dlx shadcn@latest add @caliper/system-map

Adds its 7 files to components/ui/, each with its own stylesheet, and installs their packages. Pro installs with your access token, set up once per project. See Pro access. The first part also adds Caliper UI’s tokens; import them once as in Installation.

Usage #

Import it from your copy of the source. The example behind the preview comes with the source.

example.tsx

import { SystemMap } from "@/components/ui/system-map"

The worked example comes with Pro

The 30-line example behind the preview opens here with a Pro or Team licence.

Checking your licence…

API reference #

SystemMap

component

PropTypeDefaultDescription

labelstring"Services"Accessible name of the service list.

tiers *readonly SystemMapTier[]—The tiers, top first (usually edge, services, data).

services *readonly SystemMapService[]—

links *readonly SystemMapLink[]—

selectedstring | null—The chosen service id, or null for none. Controlled when set.

defaultSelectedstring | nullnull

onSelect((id: string | null) => void)—

modeSystemMapMode—`needs` shows what the service depends on; `breaks` shows what fails with it. Controlled when set.

defaultModeSystemMapMode"breaks"

onModeChange((mode: SystemMapMode) => void)—

statusDepthStatus"ready"

messagesDepthMessages—

onRetry(() => void)—

disabledboolean—

classNamestring—

Motion #

It declares no animation in its component source. Any transition comes from its stylesheet, which uses the duration tokens that collapse to instant under prefers-reduced-motion.