lexidraw-craft
Craft guidance for drawing Lexidraw scenes with the lexidraw_* tools — arrow geometry (edges, not centers), layout, dark-mode color behavior, text-width clipping, and a numeric self-review loop. Use w
SKILL.mdskills/lexidraw-craft/SKILL.md
GitHubexcalidraw, programmatically
Covers authoring scenes through the excalidraw MCP server (read_me,
create_view, and the lexidraw_* tools that read/write scenes as
app.lexidraw.scene records in your own atproto repo).
The lexidraw_* tools stay out of your tool list until you ask for them.
Call search_tools(keywords="lexidraw") to reveal them; they are callable
from your next step.
the loop
lexidraw_save— passrkeyto update a scene in place, omit it to create a new one. Returns theat://uri and ahttps://lexidraw.app/#atproto=<did>,<rkey>link.- HARD RULE: never emit more than ~10 elements in a single save call. This applies to revisions as much as creation — one giant save has killed entire runs twice by blowing the per-response output cap before anything landed. Create with the first ~10 elements, then update by rkey, passing the full element list so far plus the next batch, until done.
- You cannot render the scene, so review it numerically:
lexidraw_openthe saved scene and check the geometry (see "numeric self-review" below). - Name what's wrong concretely, fix via rkey update (in batches, same hard rule), repeat. Expect 2–3 passes.
arrows connect edges, not centers
The single ugliest failure: arrows drawn from box-center to box-center spear through both shapes and land their arrowheads on top of the label text.
- Compute the edge intersection: start the arrow at the source box's border nearest the target, end it at the target's border. For a box at (x, y, w, h) and a target to the right, the start is (x + w, y + h/2).
- An arrow's
x, yis its start;points: [[0,0],[dx,dy]]is the offset to the end. Both endpoints belong OUTSIDE both shapes' interiors. - Route around, not through: if a straight edge-to-edge line would cross a
third box, bend it (
pointswith a midpoint) or move the boxes. - Leave breathing room: arrowheads should stop at the border, never overlap a label.
numeric self-review (before posting the link)
After saving, lexidraw_open and check, for every arrow (x, y, points):
- neither endpoint lies inside any rectangle/ellipse's bounding box interior;
- the segment does not pass through a third shape's bounding box;
- no text element's bounding box overlaps another element's. If any check fails, the scene is not done — fix and re-save.
lexidraw_open pulls a scene's elements back out, so hand edits made in the app
can be picked up instead of clobbered. lexidraw_list <handle> enumerates
anyone's scenes — reading needs no auth; saving uses LEXIDRAW_HANDLE /
LEXIDRAW_APP_PASSWORD from the server environment.
Never hand over a draft you already know is broken, and always paste the URL — the reviewer is not watching your screen.
element format
Required on every element: type, id, x, y, width, height. Defaults
worth knowing: strokeColor #1e1e1e, backgroundColor transparent,
strokeWidth 2, roughness 1, opacity 100.
- Label sugar —
label: { text, fontSize }on a rectangle/ellipse/arrow auto-centers text inside it. Prefer this over a separate text element wherever the text lives inside a shape; it can't clip and it can't drift. - Standalone text needs an explicit
width≈chars × fontSize × 0.62. Too small and the tail of the line is silently cut off.xis the left edge; to center atcx, setx = cx - width/2. - Triangles / mountains: a
linewithpoints: [[0,0],[w/2,-h],[w,0],[0,0]]plusbackgroundColorandfillStyle: "solid". - Arrows:
pointsare offsets fromx,y;endArrowhead/startArrowheadarenull | "arrow" | "bar" | "dot" | "triangle". - Roundness is a deliberate style choice, not a rule. In the app it's the
"edges: sharp / round" control, and both are ordinary options — curved
polylines are right for organic shapes, river paths, cartoon tails; sharp is
right for geometry that should read as geometry.
null= sharp;{type: 2}curves a linear element;{type: 3}rounds rectangle corners. What matters is choosing: a multi-point polyline silently given roundness turns a triangle into an arc and an envelope flap into a handbag. (A two-point line is straight either way.) One published tip-list argues for sharp 90° corners as a default for clean technical diagrams — a taste, not a law. - z-order is array order. Draw items before the container meant to overlap them so they read as sitting inside/behind it.
cameraUpdateis a pseudo-element (create_viewonly; stripped on save) that pans/zooms the viewport as elements stream in. 4:3 sizes only — 400×300, 600×450, 800×600, 1200×900, 1600×1200.
dark mode
Lexidraw renders dark by default. The theme inverts luminance and keeps hue, so specify the opposite lightness of what you want on screen:
| you want on screen | specify |
|---|---|
| near-white frame | #212529 |
| light blue sky | #1864ab |
| bright green | #15803d |
| bright amber | #b45309 |
| dark disc / vinyl | #e9ecef |
Pastels (#a5d8ff, #ffd8a8, #d0bfff) therefore render as mid-dark muted
shapes — fine for furniture like a wooden table, bad for anything meant to pop.
Mid-greys (#868e96, #adb5bd) survive both themes.
- Don't use opacity for hierarchy. Low-opacity fills render as murk; keep
opacity: 100and express hierarchy through color, size and stroke weight. For "see through this", use a stroke-only shape with no fill. - Prefer
fillStyle: "solid"overhachure/cross-hatch— cleaner, and texture reads as noise at small sizes. roughness: 1is the hand-drawn look;roughness: 0reads clean/modern.- Gray reads as dead/disabled, dashed reads as not-yet-existing. Use hue to mark relationships so they're traceable without reading any text.
viewer quirks
- The Lexidraw viewer overlays a toolbar across the top of the canvas. Add an
invisible spacer (
opacity: 0, tiny) ~140px above your topmost content or the title sits under it. - The viewer zoom-to-fits the whole scene, so wide scenes shrink; keep body text ≥16, labels ≥20, titles ≥30.
- Public scenes load with no login, so the
#atproto=link is shareable and screenshot-able headlessly.
composition (from published Excalidraw diagram guidance)
- A diagram should argue, not display. Test: strip every word — does the structure alone still communicate the idea?
- Hierarchy through scale, roughly: hero 300×150, primary 180×90, secondary 120×60, small 60×40. The most important element wants ~200px of empty space around it; isolation signals importance.
- Flow direction: left→right or top→bottom for sequences, radial for hub-and-spoke. Pick one and hold it.
- Containers only when structural. Free-floating text is the default; one guide targets under ~30% of text elements sitting inside a shape.
- Shapes must carry meaning — diamonds for decisions, ellipses for start/end. Decorative icons are noise.
- Expect 2–4 render-and-look iterations to clear spacing, overlap and clipping problems. That's normal, not a sign of doing it wrong.
when the drawing has to explain something
Optional opinions, for diagrams aimed at people who don't write software:
- Comic panels beat system diagrams. Numbered arrows between boxes are a sequence diagram; lay readers don't read those. Frames, a person, and speech bubbles carry consent and negotiation far better than labelled edges.
- Continuity is the argument. Anything meant to be invariant must be pixel-identical across panels — same coordinates, same contents. Build from a strict template with fixed panel origins and shared furniture at fixed panel-relative offsets. If the thing that "never moves" is drawn differently each frame, the picture contradicts its own caption.
- Objects, not symbols. A music note is a symbol; a record in a sleeve is an object. Draw things that could plausibly sit in the scene.
- No invented metaphor objects. If a shape needs its own explanation ("the sign says where you keep things"), delete it — that's jargon in a costume.
- Captions advance; pictures describe. Never caption what's already visible.
- Concrete furniture over abstract nouns ("your table", not "your place").
Second person, no fictional personas (
@yourname, never@grandma.example).
before calling it done
- Did you run the numeric self-review, or only trust the save's success?
- Do any arrows cross a box or touch a label?
- Any text clipped, any shape overlapping another by accident?
- Is every word one the intended reader already uses?