Diagram design system

Four primitives.
One clear grammar.

Proof diagrams should explain a customer journey before they explain the system behind it. Start with visible screens, connect them with actions, end with outcomes, and attach the evidence that makes each claim trustworthy.

01ScreenWhat the customer sees

02ActionWhat changes the journey

03OutcomeWhat matters at the end

04CheckHow Proof knows

00 / Source references

The visual target

These original mockups are the reference point for the system below. Keep them nearby while judging route clarity, screen recognizability, spacing, and the balance between blue structure and green proof.

Reference user-flow mockup combining a client dashboard tree, screen skeletons, action boxes, and routed arrows on a large white canvas — Whole-system composition
The broad reference: macro product hierarchy and detailed screen flows living on one airy canvas.
Open full size ↗

Close reference view of a branching client-admin product map with solid screen boxes, dashed action boxes, and fine blue connectors — Macro hierarchy
Orthogonal blue routes, dashed actions, restrained green milestones, and generous negative space.
Open full size ↗

Close reference view of a login journey using mobile screen skeletons, pale check regions, green actions, and routed blue arrows — Screen-level journey
Recognizable UI skeletons act as landmarks inside soft route regions, with actions and outcomes clearly separated.
Open full size ↗

01 / Vocabulary

The primitive set

If an element does not answer one of these four questions, it is probably syntax or metadata—not another primitive.

ScreenCheckoutOrder summary and payment form

Screen

What the customer sees

Use a recognizable skeleton, not a screenshot. Screens should be the largest objects in a flow.

UserSubmits paymentPrimary action

Action

What changes the journey

Write a short verb phrase. Actor is an attribute: user, system, or external service.

OutcomeOrder confirmedPurchase completed

Outcome

What matters at the end

Reserve outcomes for terminal results or meaningful milestones—not every intermediate state.

Check · PassedReceipt is visiblePassed · 4 min ago

Check

How Proof knows

Attach a check to the claim it proves. Keep status, freshness, and history as evidence metadata.

02 / Screen library

Five skeletons cover most projects

Choose the archetype by what the page helps a customer do—not by framework, industry, or visual style. Loading, empty, success, and error remain state modifiers that can be applied to any archetype.

ScreenLanding pageValue proposition and primary CTA

Landing

Orient and persuade

Hero message, supporting value, primary call to action, and a strong visual anchor.

ScreenCollectionFilters and repeating results

Collection

Find and compare

Search, filters, navigation, and a repeating set of rows, cards, records, or results.

ScreenDetail pageIdentity, context, and actions

Detail

Understand one thing

A selected object with identity, context, attributes, and one or more available actions.

ScreenForm or taskGuided input and submission

Form

Create or change

Inputs, choices, progressive disclosure, and a clear commit or submit action.

ScreenFeedback stateStatus, explanation, and next step

Feedback

Explain what happened

A success, error, empty, or loading state with a message and an obvious next step.

State modifiers

Default

Empty

Success

Error

State changes the content and accent, never the underlying page anatomy.

03 / Composition

Build the journey, then reveal the proof

The canvas uses screens as landmarks, actions as transitions, outcomes as destination signals, and checks as attached evidence. Toggle the route and inspect individual elements.

04 / Grammar

Everything else is syntax

A small vocabulary stays expressive when its connection rules carry structure.

Sequence

Arrows read in the direction a customer experiences the journey.

Topology

Branches, merges, and loops belong to connectors—not to new node types.

Regions

Soft boundaries group routes by check, phase, persona, or business goal.

Modifiers

Status, freshness, confidence, and coverage annotate a primitive without changing it.

ScreenActionScreenOutcome Check

05 / Reference

Use the library

The visual contract and the React API use the same four names. Compose them freely; do not create one-off node categories.

checkout-flow.tsxReact

<DiagramCanvas>
  <DiagramScreen
    title="Payment"
    anatomy="form"
  />

  <DiagramAction
    label="Submits payment"
    actor="user"
  />

  <DiagramOutcome
    label="Order confirmed"
    tone="success"
  />

  <DiagramCheck
    label="Receipt is visible"
    status="passed"
  />
</DiagramCanvas>

Visual hierarchyLight + dark

Route: Sky blue
Success: Proof green
Failure: Signal red
Canvas: Adaptive paper

Dark mode changes surface depth and contrast—not merely the background color. Route semantics stay stable across both themes.