/board-design

A good board reads in three seconds: one place to start, one direction to follow, one thing that stands out. Everything here serves that. It is a whiteboard, not a slide deck: sparse, aligned and honest.

Principles

1. One idea per frame. If you cannot title it in four words, split it.
2. One reading direction. Flows run left to right; hierarchies run top to bottom. Pick one axis per diagram and hold it.
3. One focal point. At most one focus shape per frame. The eye should land there first.
4. Colour is meaning, never decoration. Use roles, not hex. Most shapes stay neutral.
5. Words are labels, not paragraphs. If it needs a sentence, it belongs in a say caption or the chat, not in a box.
6. Space is structure. Equal gaps and aligned edges beat borders and ornaments.
7. The shape is the meaning. Fan-out looks like fan-out, a loop looks like a loop. If the words were erased, the structure should still say something. A uniform grid of equal cards is right only for true peers with no order, hierarchy or dependency.
8. Same thing, same look. A kind of thing keeps its shape, role and rough position from the first frame to the last, and a role keeps one meaning for the whole board. When the viewer sees the queue again, it should be recognisably the queue. Change an object by evolving it, not by drawing a new one.
9. Quiet what is done. Emphasis moves with the explanation. Once a beat is finished, its focus goes back to neutral, so the current idea is the one that stands out.
10. A working sketch, not a slide. The board is hand-drawn on purpose: it says "this is thinking in progress". Clear and aligned is enough; do not chase pixel perfection.

Grid and size

• Snap positions to multiples of 20.
• Default box: 200×80. Wide label: 240×80. Small marker: 120×60. Note: 220×220 (a square sticky; keep its text to a few short lines). Frame (one slide): 720×520, or 760×560 for text-heavy frames.
• Gaps: 60–100px between related shapes, 80px between topics, 40px padding inside a frame.
• Rows: a 720-wide frame fits 3 boxes of 180×80 with 50px gaps (640 plus 40px padding each side), or 2 boxes of 200. On a free board, at most 5 across.
• Align centres in a row and left edges in a column. Same-size siblings: identical width and height.
• Group by distance: related shapes 60px apart, unrelated 120px or more.
• Connected shapes need room for the arrow: at least 80px between them, and 120px when the arrow has a label. Closer than that and the arrow disappears into the borders.

Sizing arithmetic

Excalidraw's hand-drawn text is about 12px per character at the default size, so a box that is too small for its label is the most common reason a board looks broken. Work the numbers out before you write them.

• Box width = max(160, characters × 12 + 20), rounded up to a multiple of 20. A label wider than 240 wraps onto a second line; each extra line adds 25px of height.
• Box height: 80 for one line, 100 for two, 120 for three. A diamond needs double both (its writing area is half the shape); an ellipse about 1.4×. Prefer a rect unless the shape itself means something.
• Frame = columns × box width + (columns − 1) × gap + 80 wide, and 48 + rows × (box height + gap) + 40 tall. Compute it from what is inside, never from a default; a frame that is too small is the other common break.
• Padding: 40–50px between a frame's edge and its contents, at least 48px at the top where its title sits. Nothing touches or crosses a frame edge.
• Caps: at most 7 shapes in a frame and 15 in a diagram. More than that is two drawings.

Coordinate recipes

Use the origin the board gives you and these patterns, so rows and columns line up without guessing.

• Row (flow): box i at x = x0 + i × (width + gap), all at the same y, gap 80 (120 when the arrows are labelled).
• Column: box i at y = y0 + i × (height + gap), all at the same x, gap at least 40 (80 with arrows).
• Compare / before-after: left frame at x0, right frame at x0 + frameWidth + 80, same y, same height, same internal coordinates in each, so row 2 of the left frame is level with row 2 of the right.
• Image with caption: put a text caption (fontSize 16) at y = image bottom + 12, the same x, and keep 40px clear below it before the next element. The image is 420px wide by default and about 315 tall (the board reads the real proportions, so use the height board_read reports).

Boxes versus plain text

Not every word needs a box. A box says "this is a distinct thing"; use it for that and nothing else.

• Box (rect, ellipse, diamond) when it is a component, step or actor, when arrows connect to it, or when the shape itself carries meaning (a decision).
• Plain text for headings, captions, annotations, column or lane titles and timeline labels. Size and weight make hierarchy; a heading does not need a rectangle.
• frame to group a topic. Give it a short label for the title rather than a text box on top of a big rectangle.
• Never a big rect as a zone with a centred label. Its label lands in the middle of the zone, on top of what is inside it. Group with a frame, or put the zone name in a text at the zone's top-left. A rect that contains other shapes is reported as an overlap.
• Test each boxed label: would it read just as well as plain text? If yes, drop the box. A diagram where every word is boxed looks like a wireframe.
• Trees and timelines are a line plus plain labels, not a stack of rectangles.

Hierarchy and shape meaning

Shape	Use for
rect	a component, step, module or service
ellipse	an actor, start / end, or outside party
diamond	a decision with two labelled exits
note	an aside, caveat or human comment (never in the main flow)
text	a heading, caption or annotation with no box
frame	one topic or one step; contains its shapes

Size signals importance: the focal shape may be 1.25× the others, never more. Do not use more than two sizes in a drawing.

Roles (colour)

Role	Means
neutral	default; most shapes
input	where data or a request enters
process	the work being done
store	state that persists (database, cache, file)
external	something outside the system (third party, user)
focus	the thing this frame is about
warn	risk, bug, pitfall, or failure path
ok	the healthy or finished outcome

Rules: aim for roughly 60% empty space, 30% neutral shapes and 10% accent. At most three roles in one frame besides neutral. If you use two or more accent roles, add a small legend in a corner: one tiny shape per role, labelled with what that role means here, so nobody has to guess. Same meaning, same role everywhere on the board. warn is rare; if everything is a warning, nothing is. Never rely on colour alone; the label must also say it. Role colours are contrast-checked in both light and dark appearance, so never pass raw hex or a custom colour: it bypasses that check.

Typography

• Frame title: the frame label, 2–5 words, sentence case.
• Shape labels: 1–3 words ideal, 30 characters at most. Widen the box (see the width formula) rather than shrinking text.
• Headings (text, fontSize 28), body text (18–20), captions and annotations (16). Never below 16: the board raises anything smaller and tells you.
• A frame title is one size larger than the text inside it. Use size and weight for hierarchy before you reach for a box or a colour.
• Keep to one font and a handful of sizes. Text sits centred in its shape.
• Sentence case everywhere. No ALL CAPS, no trailing punctuation on labels.
• Name things as the code names them (SessionRunner, POST /prompt) when it is the real thing; plain words otherwise.

Arrows

• Connect by from / to ids. Label with a short verb or noun, about 12 characters at most ("validates", "events"), and only where the meaning is not obvious. Most arrows need no label.
• No arrow across a frame boundary. If two topics are related, say so in a text between them or put them in one frame.
• Solid = direct, synchronous, or the main path. dashed = async, optional, indirect or return path.
• Straight and short. Avoid crossings; if two arrows must cross, reorder the shapes before accepting it.
• One arrow per relationship. No arrow when proximity and alignment already make the relation obvious.
• Give an arrow at least 60px of length so its label fits.

Patterns

Flow / pipeline. Left to right, one row, 3–6 steps, equal boxes, arrows labelled with what moves. Put the failure path below the row, dashed, role warn.

Architecture (layers). Top to bottom: clients, API, services, stores. One row per layer, boxes aligned, store role for persistence, external for third parties. Arrows only between adjacent layers where possible.

Sequence of events. Use board_mermaid sequenceDiagram unless you are teaching; then draw actors as ellipse across the top and messages as horizontal arrows down the page in order, each with explicit points and no from / to (a message between lifelines is not attached to the actor boxes).

State machine. States as rect, the initial one focus, transitions as labelled arrows, terminal states ok or warn.

Compare / before-after / second case. Two frames side by side with identical structure, so differences are what the eye finds. For before/after, the old way on the left (warn only on the problem) and the new way on the right (ok on the improvement).

Concept map. One focus shape in the middle, 3–6 satellites evenly spaced around it, short labelled arrows outward.

Walkthrough. One frame per step, step numbered, frames left to right; each frame shows the same layout with the active shape focus.

Fan-out. One source on the left or in the middle, arrows spreading to 2–5 outputs ("one thing triggers many").

Convergence. 2–5 inputs on one side, arrows visibly merging into one shape ("many things feed one result").

Cycle / feedback. Shapes in a loop with one dashed return arrow back to the start.

Tree / ownership. Parent on top, children in a row below, joined by short lines; plain text labels below the first level. A timeline is the same idea on one horizontal line.

Summary plus detail (zoom levels). A one-row summary flow along the top (input → work → output), then one frame per stage below it with that stage's detail. The summary tells the reader where each frame belongs.

Worked example (trace). One small marker for the concrete case (a request, a value, a file) enters at the left and moves stage by stage along the flow. Redraw it at each stage under the same id so it visibly travels, and change its label as it changes (req {id: 42} → job 42 queued → result ok). Stages stay put; only the marker and its annotations change. Use it for "what happens when…" and for any code walkthrough.

Naive, then fixed. Two rows with the same layout. The top row is the obvious design with warn on the exact point where it breaks and the failing path dashed; the bottom row is the fix with ok on the new part. Only the added or changed shapes differ, so the fix reads as a small, earned change.

Concrete detail. For a real system, show what things look like: a sample request or payload, a short snippet, the actual event or endpoint names, as a note or text beside the shape it belongs to. Real names beat placeholders ("POST /sessions", not "API call"). Look them up in the code first.

Icons (Lucide)

For the kind of thing a shape stands for (a user, a server, a database, a lock, a cloud, a file), place a Lucide icon with board_image and source: { icon: "database" }. Names are kebab-case (server, users, key-round, git-branch, file-text, shield-check, cpu, hard-drive, globe, bug); browse them at lucide.dev/icons.

• Size width 48–96, placed beside the label or inside the empty top-left of a card, with a text label. An icon never replaces the label.
• One icon per kind of thing, the same one every time; do not mix icons and hand drawn pictograms for the same idea.
• A name that does not exist returns an error; pick a near neighbour (database for "db", server for "backend") instead of retrying many guesses.
• Product logos are not in Lucide: use the name in a rect, or an image the brief gives you a URL for.

Drawing a picture (reference illustrations)

Sometimes the reference is a picture, not a diagram: what a device, a screen, a part of a system or a physical thing looks like. First choose how to get it:

• A real picture exists (screenshot, doc figure, photo) → board_image. Do not redraw what you can show.
• A generic symbol of a thing (user, server, database, lock) → a Lucide icon, see "Icons (Lucide)".
• A realistic illustration is needed and an image model is available → board_image with generate.
• A simple, annotatable, schematic picture (a UI mock, a device outline, anatomy, a floor plan, a data shape) → draw it with shapes, line and freedraw, as below. A sketch can be labelled, pointed at and edited by the user, which a photo cannot.

How to draw it, the way an artist builds a drawing: large to small.

1. Simplify the subject into basic forms. Name the 2–6 biggest masses in your head: a phone is a rounded rectangle plus a circle and a bar; a server rack is stacked rectangles; a person is a circle over a tapered body. Say it to yourself in words before any coordinates.
2. Fix a local frame. Pick a canvas for the picture (for example 400×300) at the free origin. Place every form relative to it and to the forms already placed ("the screen is inset 20 inside the body", "the button sits centred under the screen"). Think in relations (touching, aligned, centred, half the width) more than raw numbers, and keep numbers on a 10 or 20 grid.
3. Build the masses with the real shapes first: rect, ellipse and diamond with sensible sizes. They are exact and editable. Use frame only to group the whole picture.
4. Add structure with line: straight line ops for edges, dividers, axes and polygons. First point is [0,0]; the rest are offsets from x,y.
5. Add curves with freedraw: it draws a smooth curve through your points, so give 6–20 points along the curve, evenly spaced, and let it round them. Dense jittery points make a wobble. Use it for a cable, a leaf, a cloud, a profile, a hand-drawn circle around something.
6. Close a shape by repeating its first point as the last point. A closed line or freedraw is filled with its role colour; an open one is not. neutral has no fill (outline only), so give a shape that should be filled a role such as process (light grey) or input, which keeps the fill contrast-checked. Overlapping filled shapes hide each other, so draw back to front.
7. Layer in drawing order: big forms (back) → medium forms → details (front). Anything on top comes later in the ops. Details come last: screws, highlights, labels.
8. Look as you go. Take a board_look after the big forms and again after the details, not only at the end, and fix proportions and alignment before adding more. For a picture you may look up to four times in total; when a part is wrong, redraw that part under the same id rather than the whole picture.
9. Name the parts. Give every form a meaningful id (screen, body, button) so you can fix one part, point at it and describe it. Label the parts that matter with plain text, with leader lines only if proximity is not enough.
10. Keep it a sketch. Simple forms, 2–3 roles at most, no shading or texture. If you cannot make the forms recognisable in two looks, switch to board_image or a labelled diagram of the parts.

Annotatio

…