The Terrastruct Blog

Designing the interface of a diagramming app

September 21, 2020
by Alexander

Phase 1: Idea

Two years ago, I was working at Stripe and brainstorming a software design proposal, which I'd then present. I wanted visuals, because it helps people pay more attention in presentations, but it was tough diagramming my design with the tools available. I used frequently for explanations, but when there's complexity, it became a mess with sprawling arrows trying to sequence events.

So I took a walk, and thought about what a diagramming tool that could show sequences — along with other interactive features — would look like. When I went home that night, I ran create-react-app, threw up an SVG canvas, and got to work on scoping how hard this might be. It only took a few hours to get a basic panel of shapes that I could drag and drop onto an SVG canvas.

Terrastruct interface

After evaluating that the tech portion of this project seemed quite tame (I was wrong, much of that wasn't apparent until much later), I started thinking about the design of the interface. It was early on, but it helped me think of what I really wanted it to do. At the time, my vision was that a diagram can have a timeline, and users could step through the timeline to see various stages of the system. This was very specific to what I wanted to do for my original use case.

Terrastruct interface

I experimented with different interfaces, even learning a little Sketch (Figma wasn't cool yet circa 2017) to iterate faster than I would writing CSS.

Terrastruct interface

For a while I was really into the idea of using animations to explain sequence. A diagram board would start at some initial state, and from one frame to another, only the board objects that are changed would have animations so that it'd be clearer to the viewer what was happening. I envisioned diagrams as an animated presentation that people could just observe and step through to understand the content.

Terrastruct interface

I remember that I genuinely thought this was a good interface at the time. I had spent a significant amount of time on it at this point and could not see it objectively anymore.

So, I consulted a designer, and I instantly saw how much better the result was. Much less wasted whitespace, maximizing the workspace. For every frame, an object has two states, a "base" and "animated" state. In presentation mode, frame 1 starts at base, transitions to "animated" state, pauses, and then moves onto frame 2, and continues like that.

Terrastruct interface

I started fleshing out more of the properties. The interface grew, and I adapted the sidebar to use separate tabs for "Base" and "Animated", instead of doing the vertical split panes. I started polishing: making colors consistent, using production-passable icons, basically zoning in on a design that beta users might actually see.

Terrastruct interface

Phase 2: Working product

After significant effort trying to make animations work smoothly, I was never satisfied. I came to the conclusion that the web is not ready for animations on DOM elements past small UI interactions. It's too susceptible to FPS drops on too many environments to be a pleasant experience. I probably would not have run into this limitation if I had started with HTML Canvas or WebGL, but maybe it's for the best, because even while building it, I had reservations in the back of my head on whether this is something that was actually useful instead of just cool.

So, I did a large rewrite. I went back to some core ideas of what I wanted: having multiple layers for a diagram, while still retaining the ability to explain steps of a sequence.

I tried to come up with the design for it many times, but got stuck. I was coding on Vim and a revelation came that the Vim airline bar looked like a perfect way to compactly represent this hierarchy of scenarios under views. I felt like Jony Ive.

Vim airline inspiration

Notice the bottom of the next screenshot.

Terrastruct inspired by Vim

I loved it, but after talking with early users, it turns out it was too confusing. Cleverness when it comes to designing intuitive interfaces, I learned, is not a good quality. I resigned to the boring but familiar sidebar.

I launched the beta publicly in this state. At the time, I defined it as "a diagramming tool for systems", apparently ignoring all advice I had read on how focusing on a niche yields a better product than trying to serve everyone. Still, people were interested.

I added pricing about a month after launch when I felt the product was good enough. Users could only pick from 4 shapes, there was no snapping so they had to eyeball alignments, lines could only be straight (the angled ones shown below are just two lines combined), there was a huge list of deficiencies. The diagramming foundations were severely lacking, but being able to seamlessly switch between views and step through scenarios was enough of a feature add that some people paid the $4.99 for it.

Terrastruct interface

I still held onto an artifact of that Vim interface. I thought the frames alone there showing left-to-right sequence was a good break from the two vertical lists.

Phase 3: Business

Over the past few months, the UI stayed this way while we did renovations on the internals. We paused working on new features, and our primary goal had been to make the experience of creating a single static image as good as industry-standards (, Omnigraffle, Visio, Lucidchart, Creately). We did deep dives into every diagramming tool we could find, and brought the best of what we found to Terrastruct, while innovating lightly where we thought appropriate. Here's what it looked like last month.

Terrastruct interface

I sought a designer to go through another round of UI revisions. The sum of many small design defects being patched resulted in a much more professional interface. I'm referring to the oddly squished, oddly spaced buttons of the right panel, misalignment of icons, unnecessary text, distracting contrast around the board, inconsistent font sizes, excessive borders/shadows, too little or too much padding. The new layout feels more breathable, because, in retrospect, I realized that the two dark-contrast bars at the top and bottom gave a sense of tightness in the middle.

In addition, what I found since release is that people use layers much more frequently than they use scenarios and frames. Even with the initial product tour, the examples highlighting this feature, and the tooltips, there is no substitute to UI failing. The frames being a detached section at the bottom of the page disconnects it from the scenario it's a part of. And, as a new concept, it didn't help that the word "Frame" is semantically ambiguous (the meaning I'm going for may not even be a familiar one unless you've worked in video). Instead of using "Frames are steps of a sequence" as the explanation, I cut out this indirection and just renamed it as "Step". Usage of this feature increased dramatically with this interface tweak.

Terrastruct interface now

This interface will be the look of Terrastruct 1.0, and I'm hoping for this design to last for the foreseeable future. The challenge now will be to fit all the features on the roadmap onto the interface without cluttering it.

What I learned

  • I'm a terrible judge of design when it comes to my own creations. It's very unintuitive because even now I believe I can be objective; I have to remind myself I'm dead wrong about these by looking at previous design decisions that I thought were good.
  • Similar to how writing helps you think, I found that designing interfaces helps me think about the product. I would've saved a ton of time hiring a designer from the get-go, but that's assuming I'd know what I wanted, which I didn't. The process of building the interface myself turned out to be a useful exercise.
  • The goal of good interface design is to not draw attention. I thought that because there were so many constraints (~90% of the space would just be covered by the board), that there's not much a designer could add vs doing it myself. I learned firsthand how much the details matter. People will perceive padding asymmetries and spacing issues easily and associate it with a shoddy product when it's not done right. When you get the details right, nobody notices -- it just feels good.

Want to learn more about software architecture?

We host a newsletter where we invite experts to do case studies on the architecture of popular open source software. We'll send you one email a month with high-quality diagrams that help you understand how the most used software around the world gets built, free.