Skip to content

DiagramsPhilosophy

Diagrams are arguments, not decorations.

Every diagram in the system makes a specific argument. The diagram is a compressed, visual form of a sentence the page could have written instead. The argument is the test; if a diagram doesn't make a specific argument, it's a decoration, and it gets cut.

3 diagram kinds8 in production1 in flight

The three diagram kinds

The system has three diagram kinds. Each makes a different argument.

  1. Sequence: the argument is the order. Used for participant flows, request lifecycles, the cognitive steps in the study.
  2. Structure: the argument is the parts. Used for the architecture of the system, the layout of a dashboard, the data model.
  3. Comparison: the argument is the difference. Used for the before/after, the tradeoff table, the metric comparison.

Three principles

  1. HTML, not SVG. Every diagram in the system is rendered with semantic HTML elements and CSS. The reason: an HTML diagram is responsive for free, accessible for free, and copy-paste-able for free. An SVG diagram is none of those.
  2. Tokens, not values. A diagram is built from the same color, type, and spacing tokens as the rest of the page. A diagram that uses a different palette is a different page.
  3. One idea per diagram. A diagram is a single argument. If the diagram is making two arguments, it's two diagrams. The 5-step participant funnel is one diagram; the participant funnel and the metric block are not.

Anti-patterns

  • Decorative shapes. An arrow that points to nothing. A circle that doesn't represent a step. A gradient that doesn't mean anything. Cut it.
  • 3D effects. A diagram in 3D reads as a render, not as an argument. The system is 2D only.
  • Custom fonts. A diagram that uses a font the rest of the page doesn't use is a typo. The diagram must use DM Sans, in the same sizes as the rest of the page.
  • Arrows without labels. An arrow that points from A to B without saying what flows through the arrow is a mystery. The label is the argument.

A diagram, the right way

The 5-step participant funnel. One diagram, one argument: "Here is the order in which a participant moves through the protocol."

participant-funnel.tsx
import { DiagramPanel } from "./diagram-panel"

const steps = [
  { label: "Welcome", note: "Informed consent, language", tone: "light" },
  { label: "Tasks", note: "Banking + medical, randomized", tone: "light" },
  { label: "Assignment", note: "Silent, balanced, server-side", tone: "dark" },
  { label: "Walkthrough", note: "Step-by-step, 12 to 18 minutes", tone: "light" },
  { label: "Scales", note: "NASA-TLX, SUS, post-task", tone: "light" },
] as const

export function ParticipantFunnel() {
  return (
    <div className="study-diagram__steps">
      {steps.map((s, i) => (
        <div key={s.label} className="study-diagram__step">
          <DiagramPanel
            tone={s.tone}
            eyebrow={`Step 0${i + 1}`}
            title={s.label}
          />
          <p className="study-diagram__step-note">{s.note}</p>
        </div>
      ))}
    </div>
  )
}

Why this restraint

A diagram is one of the few elements on a page that the reader actually has to look at. It is competing for the same attention budget as the prose. A diagram that doesn't make a specific argument is taking attention away from the prose without giving anything back.