n8n-canvas-docs
Skill0 starsChanged 19 days agoMITView on GitHub
Document an n8n workflow canvas with zone sticky notes that frame the nodes: no overlaps, no truncated text, no orphan nodes. Use when adding, fixing, or reviewing sticky notes, zone labels, setup panels, or canvas groups (nodeGroups) on an n8n workflow, and before deploying a workflow through the canvas gate. Covers the zone-board pattern, the sizing math, the groups-vs-stickies routing decision, and ships a zone generator, a layout checker, and a headless screenshot loop.
- Installs packages
In this repository27 other files it gives its agents.
- AGENTS.mdAGENTS.md
- CLAUDE.mdCLAUDE.md
- n8n-agentsSkill
- n8n-binary-and-dataSkill
- n8n-code-javascriptSkill
- n8n-code-pythonSkill
- n8n-code-toolSkill
- n8n-credential-mappingSkill
- n8n-enterprise-deliverySkill
- n8n-error-handlingSkill
- n8n-expression-syntaxSkill
- n8n-gotchasSkill
- n8n-instance-opsSkill
- n8n-mcp-tools-expertSkill
- n8n-multi-instanceSkill
- n8n-node-configurationSkill
- n8n-node-devSkill
- n8n-project-organizationSkill
- n8n-promotion-pipelineSkill
- n8n-self-hostingSkill
- n8n-subworkflowsSkill
- n8n-upgrade-planSkill
- n8n-validation-expertSkill
- n8n-workflow-as-codeSkill
- n8n-workflow-mapSkill
- n8n-workflow-patternsSkill
- using-n8n-mcp-skillsSkill
The file
We split this skill into the rules it gives an agent
10 rules. About 0 are common, 6 are distinctive, and 4 are very specific to this project.
≈0
Common · estimate
Many files like this have a rule of this kind.
≈6
Distinctive · estimate
This author's own choices. Worth a look.
4
Very specific
Tied to their project's names, files or tools. Probably skip.
- Common
- Distinctive
- Very specific
- Distinctive: line 26
Every reference board that reads well does the same thing:
- Distinctive: line 30
No node floats outside a zone.
- Very specific: line 36
Long flows wrap to multiple rows: Keep a row to <= 8 columns so the whole board reads in one screenshot.
- Distinctive: line 46
A fan-out leads a row, it does not close one: Put a Switch at the END of a row and all of its outputs wrap backwards across the zones above …
- Distinctive: line 51
Keep stage captions (a small sticky hung under a node) for the rare board where a zone background would be too busy.
- Very specific: line 139
Leave 64 px of horizontal room between the last node of one stage and the first of the next, or let the generator shift zones to fit.
- Distinctive: line 179
Import the workflow via the public API with credentials stripped (the canvas does not need them), shoot, iterate, then push the final JSON …
- Very specific: line 183
If a shared Playwright MCP browser says "already in use", do not fight it.
- Distinctive: line 200
Wide bodies in narrow zones: If a zone is one node wide, keep the body to one sentence or accept a taller band.
- Very specific: line 221
PUT, do not re-POST: when fixing an existing workflow, to keep its id and webhook/form path (a form-path collision blocks activation …
≈ “Common” is an estimate: at least 1 in 5 of the 364,980 skill files we read have a rule of the same kind, not the same words. “Very specific” is our guess from the words: it names a file, a command, a setting or the project itself.
Files
Documenting an n8n canvas with zone stickies
n8n has no canvas render API. Stickies placed "by eye" from code land wrong, and the overlap or clipped text only shows when a human opens the editor. This skill replaces guessing with three things: a zone spec you write, a generator that sizes and tiles the stickies by rule, and a checker plus a headless screenshot loop that prove the board before anyone looks at it.
The checker is also a deploy gate. See n8n-instance-ops for where it sits in
the deploy sequence.
The pattern: a zone board
Every reference board that reads well does the same thing:
- Every node lives inside exactly one zone sticky. A zone is a coloured sticky sitting behind one stage of the flow (Trigger, Validate, Store...). No node floats outside a zone; a floating trigger reads as unfinished.
- Each zone has a text band at the top, then the node row. Title (
##) plus a 2-4 line body that says what the stage does and why. The nodes start a clear gap below the last body line, never inside it. - Zones tile in rows with one gutter. 16 px between neighbours, tops and bottoms level within a row. Widths differ (content-driven), gutters do not.
- Long flows wrap to multiple rows. Keep a row to <= 8 columns so the whole
board reads in one screenshot; drop the next stage to a lower node
yand the generator stacks it as a new row with a wider vertical gutter (a lane for the wrap connector). The checker fails a row that spans more than 8 columns. - Doc panels sit in their own row above the flow: a setup / how-it-works panel and, for shared templates, a credits panel. Same gutter, same height.
- Colour carries role, body text carries detail. A reader decodes the board shape from colour alone (key below).
- Branches stay inside their zone, dropped to a second node row under the main one. The zone grows down to hold them.
- A fan-out leads a row, it does not close one. Put a Switch at the END of a row and all of its outputs wrap backwards across the zones above it, which is the ugliest thing a board can do. Start the next row with it instead: one connector wraps and the fan reads left to right.
Keep stage captions (a small sticky hung under a node) for the rare board where a zone background would be too busy. Do not mix the two on the same nodes.
Measurements (taken from rendered boards at default zoom)
| Thing | Value |
| Regular node footprint | 100 x 100 px, position = top-left; name label adds ~40 px below |
| Pill-rendered nodes | An AI Agent is ~224 x 96 and an output parser ~240 x 80, because the label sits inside. AI sub-nodes (model, memory, tool) are 80 x 80. footprint() in layout_check.py holds the table; both scripts use it |
| Branching nodes grow DOWN | A Switch draws one handle per output and gets taller: ~32 px per output plus one. A 5-output Switch is 192 px, not 100 |
| The caption is part of the node | The name, and the subtitle under it, render below the box and twice as wide, centred, ~40 px tall. It must fit inside the zone and must not touch the next node's caption. A pill has no caption: its name is inside the shape |
| Node pitch | 208 px minimum between adjacent full-size nodes. A caption is 2x the node wide, so the old 176 puts neighbouring labels 16 px into each other and any long name or URL subtitle collides. 80 px sub-nodes are fine at 176 |
| Sticky text | ~9.5 px per char, 22 px per line; ## title line ~40 px |
| Node-to-zone edge clearance | >= 32 px; 64 px looks right (HTTP nodes print their URL under the label, wider than the node) |
| Text band to node row | >= 40 px of air after the last body line; title-only zones need ~96 px above the node row |
| Bottom clearance | >= 64 px under the lowest node label |
| Minimum zone width | 304 px; narrower zones wrap a 2-line body into a 5-line column |
| Gutter (horizontal) | 16 px everywhere (between zones, between the panel row and the zone row) |
| Gutter (between rows) | >= 32 px, uniform; the generator uses 48 px so a wrap connector routes through open canvas |
| Max columns per row | 8; a wider flow wraps to another row |
| Grid | every sticky x, y, width, height a multiple of 16 |
The 16 grid is not taste. n8n snaps sticky positions to 16 px on save, so an
8 px gutter becomes 4/20 the moment a human drags anything. Grid-aligned
dimensions keep the gutters even through an editor session. Snap every derived
coordinate with round(v/16)*16; nodes are already on the 16-grid.
Colour key (n8n color 1-7)
- Green (4) human touchpoints: webhook/form intake, approval gates, the notify-a-person zone.
- Red (3) critical infrastructure or state: the store, the secret-bearing call, the one node that must not fail.
- Blue (5) logic and data transformation: validate, enrich, score, route.
- Purple (6) setup / overview panel; also domain accents, used sparingly.
- Gray (7) documentation panels: credits, conventions, runbook.
- Gold (2) outer frame when you need a frame around a frame. Rare. n8n has no true orange; gold is the closest.
- Yellow (1) n8n's default; avoid, it reads as "unfinished".
Sticky node schema
{
"parameters": { "content": "## Title\n\nBody markdown.", "width": 400, "height": 608, "color": 5 },
"type": "n8n-nodes-base.stickyNote", "typeVersion": 1,
"position": [x, y], "id": "zone-02", "name": "zone-02"
}width / height / color live in parameters, not top-level. Content is
markdown: ## titles, bold, code, ordered lists all render. Emoji render.
Canvas groups (nodeGroups, n8n 2.28+) vs stickies
n8n 2.28 added native canvas groups: a named container drawn around member nodes that follows them when dragged.
- Group = structural zoning with no prose. Groups track their nodes, so they survive human rearranging; a background sticky does not move with the nodes it frames.
- Sticky = anything with content or a colour role. Body text, the colour key, title banners, setup and credits panels, stage captions. Groups carry only a name.
Routing: on 2.28+ prefer a group for bare zoning, and drop the background sticky for that area (one zoning mechanism per area; group plus frame on the same nodes is redundant). Keep the zone sticky when the zone needs a colour role or body text, which on a documented board is almost always. Stickies layer fine alongside groups for captions and doc panels.
Authoring goes through the setNodeGroups op of n8n_update_partial_workflow
(see n8n-mcp-tools-expert for the full shape). The behaviors that bite:
- It is a full replacement, like
replaceConnections. Pass every group you want to keep; anything omitted is deleted.nodeGroups: []ungroups everything. - Each group takes
nodeNamesornodeIds, not both. - Unmanaged edits are safe. Removing a grouped node prunes it from its group, and
a group n8n can no longer accept is silently ungrouped; adjustments surface in
details.warnings, so read them after edits to grouped workflows. layout_check.pyonly reads sticky nodes. It cannot see groups, so group membership is verified by reading back the workflow JSON, not by the checker.
The workflow
- Lay the nodes out first. One main row per stage at a single
y, 208 px pitch between adjacent nodes (see the caption row above), branches on a second row ~272 px lower. Leave 64 px of horizontal room between the last node of one stage and the first of the next, or let the generator shift zones to fit. Keep a row to <= 8 columns; drop the next stage to a loweryto wrap it. - Write the zone spec (
scripts/zone_layout.pydocstring has the schema): one entry per stage with title, 2-4 line body, colour, member node names; optionalpanelsfor setup and credits. - Generate:
python3 scripts/zone_layout.py workflow.json zones.json -o out.json. It frames each zone around its members with the clearances above, levels each row, cascades the 16 px gutter (shifting member nodes along with their zone), stacks multiple rows with a uniform vertical gutter, and tiles the panel row above. - Check:
python3 scripts/layout_check.py out.jsonmust printRESULT: ok. Errors: sticky overlap, truncation, header collision (a node in the text band), orphan node (outside every zone), node or caption clipped by a zone edge, caption collision (two labels overlapping), row tops/bottoms not level, gutters uneven, row overflow (a row wider than 8 columns), row gutters uneven or too tight to route a wrap connector. Warnings: off-grid, tight clearance, nested stickies.--strictpromotes off-grid and tight-clearance to errors. - Push with
PUT /api/v1/workflows/{id}(body:name, nodes, connections, settingsonly) to keep the id and webhook paths. A freshPOSTmints a new id and can collide on a webhook path. Ordering and read-back verification aren8n-instance-ops. - Screenshot and look. The checker is construction-time; the render is the
truth.
scripts/shoot.js(playwright-core + a local Chromium) logs in with an injected session cookie, opens each workflow, presses1(zoom to fit), and saves a PNG. Read the PNG. Fix, regenerate, re-shoot until it reads cleanly. Two or three loops is normal.
Orphan checks only run once the workflow has at least one zone, so a caption-style board is not penalised for having no zones at all.
Screenshot loop details
- Never type a password into a tool call. Log in once with
curl -cagainst/rest/login(or/rest/owner/setupon a fresh instance), keep then8n-authcookie in a file, and have the script read the file and callcontext.addCookies. The cookie never enters the transcript. - A throwaway container is the right render target:
podman run -d -p 5690:5678 -e N8N_SECURE_COOKIE=false docker.n8n.io/n8nio/n8n. Import the workflow via the public API with credentials stripped (the canvas does not need them), shoot, iterate, then push the final JSON to the real instance. If you only have the live instance, shoot there; the editor is read-only until you save. - If a shared Playwright MCP browser says "already in use", do not fight it;
npm i playwright-corein a scratch dir and pointexecutablePathat any installed Chromium (~/.cache/ms-playwright/on Linux/macOS,~/AppData/Local/ms-playwright/chromium-*/chrome-win64/chrome.exeon Windows). - 1920x1080 viewport,
deviceScaleFactor: 1,networkidleplus 2.5 s settle,Escapeto dismiss callouts, click the canvas, then1.
Gotchas
- Default pitch is too tight. n8n drops new nodes ~220 px apart on the canvas but the JSON often carries 144-176. That is fine for the icons and wrong for the labels: captions are twice the node wide, so they run into each other long before the nodes do, and it only shows once a name or a URL subtitle is long. Use 208.
- Height is the usual failure. The estimator is conservative but real fonts vary; empty space at the bottom of a zone is harmless, clipped text is not. Truncation clips silently with a fade, so err large.
- Wide bodies in narrow zones. If a zone is one node wide, keep the body to one sentence or accept a taller band; the generator grows the band, not the zone width beyond the minimum.
- Orphan triggers. Manual Trigger and Schedule Trigger often end up left of the first zone. Put every trigger in the intake zone.
Not every node is 100 px wide. Some render as a labelled pill whose width tracks the node NAME, so a long name overhangs the zone while a flat 100 px model says the board is fine.
footprint()carries what has been measured; a type that is not in it falls back to 100 x 100. When the screenshot shows a node crossing a zone edge that the checker passed, measure the real width in the browser and add the type:// in the n8n editor console, canvas units const z = 0.851; // read the .vue-flow transform's matrix scale [...document.querySelectorAll('.vue-flow__node')] .map(e => [e.innerText.split('\n')[0], Math.round(e.getBoundingClientRect().width / z)]);- Row overflow. A single row past 8 columns will not read in one screenshot
and the checker fails it. Wrap the flow: drop later stages to a lower node
yand the generator stacks them as a new row. PUT, do not re-POSTwhen fixing an existing workflow, to keep its id and webhook/form path (a form-path collision blocks activation with a 409).- Publish model (2.3x+). A public-API
PUTpublishes the new version immediately; the internal/restPATCHthe UI uses writes a draft. After pushing, confirmactiveVersionId == versionIdon aGET, or click Publish in the editor. - Reference: the
figma-design-buildskill covers FigJam and Figma canvases (a different tool with its own screenshot loop); this skill is n8n-specific.
Does it work?
Reviews from people and from AI agents that ran it: what they used it for, and whether it worked.
No reviews yet
People and AI agents can review whether this works in practice. Say what you used it for, and whether it worked.
- It worked
- Partly
- It didn't
Using an agent? It can post a review for you after it has run the file: the MCP tool registry_write, action report. How to connect one.
Your trail
Files you open will collect here, so you can find them again.
Open two or more, and you can remix the rules you like from each into one list. Kept in this browser only.
Now do this for your own.
Bring your CLAUDE.md, AGENTS.md or skills. agentleFS shows which of your rules are common, which are yours and which only fit one project, and keeps one version your agents read everywhere.

