The SimpleDiagrams Documentation is a work in progress. Please feel free to email me if there's something not covered here and I'll reply directly (and probably update the docs right after).

SimpleDiagrams (Continually In-Progress) Documentation

Table of Contents

  1. Background
  2. Overview
  3. Making Diagrams
  4. Shapes
  5. Shape Data


The last thing you need is one more complicated tool vying for your time and precious brain cycles. SimpleDiagrams wants to help you make the sketches, diagrams and visualizations you need with the minimum amount of time spent learning how to use the interface.

There's nothing stopping you from just opening the app and going to town. However, if you're the cautious, sensitive type (aren't we all), you'd probably appreciate a quick introduction to how SD works and what kinds of neat things you can do with the app. These docs are for you.


SimpleDiagrams main purpose is to help you visualize things and then export those visuazliations to PDF or PNG format to use where you see fit. The app is split into a drawing board and a library:

Main UI

So your job is basically to take the shapes you like from the library, drag them onto the drawing board, and in the process make sense of the world. At this point I think you should stop reading and just start messing around with the program. But if you're still not ready, let's continue...

Making Diagrams

Adding Shapes

One of the main tasks in creating your diagrams will be moving shapes from the library into your drawing. The basic mechanism for doing this is either dragging and dropping the shape from the library, or double-clicking it, which causes SimpleDiagrams to add a new instance of the shape to the middle of the drawing board.

TIP: Double-click a library shape to add it directly to the middle of the drawing board

Remember that the shape in your library is called a "Library Shape" and the shape on your diagram is called an "instance" of the Library Shape. That'll be important later when we discuss Shape Data.

Connecting Shapes

Once you have some shapes in your diagram, you'll probably want to connect a few to show relationships. You can use the Line Tool in the Toolbar Line Tool. When you select the line tool and then roll over a shape, you'll see small blue x marks around the shape. These are called Connection Points.

Connection Points indicate where you can attach a line to a shape so that the line remains attached the shape when you reposition or resize the shape later. Below you can see that I rolled over the "Connect me" square with the line tool.

Connecting two shapes. First one selected.

Click on any of the blue x marks and then drag your line to any other shape. That shape's connection points will now become visible and you can use them to finish your connection.

Connecting two shapes. Connection complete.

TIP: When you don't have the line tool selected, hold down the ALT key to switch momentarily to line tool to connect shapes.

Changing Line Curves

Regardless of whether the line is connecting shapes or just floating off on its own, you can change the curve of a line by selecting the round green circle shown in the middle of the line when the line is selected.

Line curve.

I feel like that's enough control for the curve of a line, but maybe some of you want better control to make more complex curves. Email me if that's the case. I'm considering making lines more flexible.

Adding Text

You can add text to your diagram in two ways: using the Text Tool to add a text area, or adding text directly to a shape instance.

To add a text area, select the Text Tool from the Toolbar Text Tool. Click anywhere on the drawing board to add your text area. Then, either position the text area or double-click it to start adding text.

TIP: Use Ctrl-T to add a text area quickly.

Managing Colors

Controlling color is pretty easy in SimpleDiagrams, but there's a trick to doing it efficiently.

If you select a shape, you'll notice that there are two different sets of color "chips" you can use to control the shape's stroke color, fill color, text color and text background color. There's a set of controls in the Properties panel and a set of controls in the Toolbar panel.

Color controls

Either control will change your shape's color. For example, you can change the shape's stroke using the stroke color chip Stroke color chipin the Properties Panel or in the Toolbar. So why have two sets of controls then?

The Toolbar controls do a second job of setting the default colors that a shape gets when you drag it onto the stage. In the image above, since the Toolbar stroke chip is set to black, a shape dragged to the drawing board from the library will get its stroke set to black. And since the fill is orange, the shape's fill will default to orange.

TIP: You can turn the default color behavior off in the "Preferences" panel by selecting "Use library color." That will cause shapes to ignore the default colors in the Toolbar color chips when you drag out a shape.

Not all shapes will respond to color chips in the same way. We'll learn why in the next section about shapes.


SimpleDiagrams comes with a standard set of Shape Libraries, and each month I try to add new libraries to the online library. Drop me a note if there's a topic you'd like to see shapes for.

However, you probably have your own set of shapes you'd like to use. Luckily, adding shapes to SimpleDiagrams is pretty easy (well, as long as those shapes are .png, .jpg or .svg format). To add shapes, you'll use custom libraires.

Custom Libraries

A custom library allows you to add your own shapes to SimpleDiagrams, grouped into a library for convenience. To create a new custom library, select "New Custom Library" under the "Libraries" menu. You can create a library for shapes or for backgrounds (currently backgrounds don't support SVG and must be bitmaps). Give your custom library a name.

When your custom library is created, you'll see it in the library with the text "Drag an image from your desktop..." reminding you that you can just drag a bitmap or svg shape to your shape library, or just a bitmap to your background libraruy.

What's nice about using SVG shapes is that since they are vector format, they remain crisp regardless of what size you use. Bitmaps will get grainy as you increase their size. However, you will notice that regardless of whether you use an SVG or bitmap shape, your new shape doesn't respond to the color controls when you drag it to the drawing board. What's up with that?

If you import an SVG shape, you'd think that SimpleDiagarms would know how to update the stroke and fill colors of your shape. In fact, it can. But you have to give it a little help. You see, you might have only certain parts of your shape that you want colored. You might have a car svg and only want the body of the car to change color when the fill color is changed. You can do this in SimpleDiagrams by attaching simple "tags" to the names of your layers in your SVG file.

Attaching Fill and Stroke Tags to SVG Files

If you have access to a program that allows you to edit SVG files, you can include "tags" in the layers of your SVG shape as a way of indicating to SimpleDiagrams how the shape should work with the stroke and fill controls. To do this you must divide your SVG shape into separate layers and then attach to each layer a name with the text "_fill" if you want it to respond to the fill color chip and "_stroke" if you want it to respond to the stroke color chip.

Let's use our trusty "customer" shape. Say we want his shirt to respond to fill color changes in SimpleDigrams, but he always wears khaki pants a blue tie. To do this, we'll separate the black stroke lines into a top layer called "_stroke" and the orange fill for his shirt into a layer called "_fill". The parts of the shape that don't change can be in one or more layers called anything that doesn't use "_stroke" or "_fill" in the name.

Customer color example

Now when we use Illustrator to save this artwork as SVG, we can simply drag our .svg file into SimpleDiagrams and start coloring shirts, including using SimpleDiagrams great texture fills.

Customers with colored shirts

Shape Data

Shape data is a new feature in SimpleDiagrams that lets you attach 'meta-data' to each shape in the library. For eaxmple, if you have a library of computer parts, you can attach a name and a price to each computer shape. Or maybe you want to add a species name and plant size to your garden plant library. And so on.

So what good is that? Well, if you've used shapes with Shape Data in your diagram, once your done diagramming you can export the shape data separately (in xml, json or csv format) to get a more quantitative look at your diagram.

Defining data is easy. Just right-click a shape in your library and select "Edit Shape Properties." For example, let's add a name and a price to a computer. I've right-clicked the computer shape in the upper left of the library below:

Right-click to edit shape properties

This brings up the Library Shape Properties Window. Click the 'Shape Data' tab.

Library shape properties window

This is where you can enter as many shape data properties and default values as you'd like. These values will be applied to each shape instance you drag onto the drawing board. (Remember, each shape you drag out is an 'instance' of your library shape.)

You'll need to give each shape data property a field name, a type, a default value, and indicate whether the value can be edited or not on each instance. As of now there are only two kinds of properties, TEXT or NUMBER.

To add a new property, click the 'add' button Library shape data add button and then click any cell in the new row to start adding data.

For example, here I've added a product name and a price for my computer:

Library shape data example

You'll notice that I only set the price to editable since I want the name always to be the same but the price to be editable per instance.

Now, when I drag out this shape onto my diagram, it will immediately inherit these properties I've defined in the library shape. To try this yourself just drag out your computer shape and then right-click the shape on the drawing board, you'll see the Shape Data Properties Panel window and the two properties.

Shape Data Propeties Panel

Now, I can update the price for each instance I drag out. Each time you select a shape the Shape Data Properties Panel will update to show the selected shape's data.

Important point: remember that each instance does not maintain a link to the original library shape. So if you change shape data on a library shape, you'll need to 'sync' your instance shapes if you want them to update to the new data (and in the process lose any existing data they have).

So if you update your library shape's shape data, right click the library shape and select "Sync shape data" if you want to update all instances of that shape in your diagram.