Working in the three editors

Every editor in CRAYON-C4 uses the same three-pane design: a tree or list on the left showing all elements, a canvas in the middle where you position things visually, and a details form on the right where you configure the selected item. This page covers the shared mechanics that work the same way across all three diagram types.

The three-pane layout

The left pane shows a hierarchical tree or flat list of all elements in the diagram. Click an element in the tree to select it — its details appear on the right pane, ready to edit. Click an element on the canvas (or an empty area) to select it — the right pane updates to match.

The middle pane is the interactive canvas. You can position elements by dragging them around, click to select, and right-click on nodes to access context menus (varies by diagram type).

The right pane is a form that appears only when something is selected. It holds all the editable properties: name, description, type, relationships, and more. Close it by clicking the X, or it auto-hides when nothing is selected.

How the details pane is organized

Every element has a lot of fields and you use only a few of them often, so the pane is in three parts — the same shape in all three editors:

  • Essentials, at the top. The fields you set on nearly every element: an element's name, type and short description; a connection's label and technology; a swimlane's name and the C4 element it stands for.
  • Named sections below. Everything else — appearance, structure, routing — folded away until you open it.
  • One action rail at the foot. Whatever affects the whole element: add, copy, save as template, delete.

A closed section tells you what is in it. Each folded head shows its current value on its own line — in my system, Curved lines, Routed by hand, ×3, the opening words of a description, or how many members a boundary has. Nothing is hidden, only summarised; a dot marks a section holding something you've set, and a section shows — rather than nothing when it is genuinely empty.

Your folds follow you. Open Appearance once and it stays open as you click from element to element, across every editor and every project, until you close it again. The preference is about how you work, so it isn't part of the project — opening a fold never counts as an edit and never shows up as an unsaved change.

A few sections start open on purpose: the ones that are the element (a group's members, a boundary event's interrupts, where a connection attaches and how it runs), and any section holding a problem you should see — an element whose parent has been deleted, for instance.

Fields commit when you finish, not while you type. A text field saves shortly after you stop typing, but tidying — trimming stray spaces, dropping an empty value — happens only when you leave the field. So a space you type mid-sentence stays where you put it.

Canvas controls

At the top-right of every canvas, four buttons let you control the view:

  • Zoom in (+ icon) — zoom in a step around the canvas center
  • Zoom out (− icon) — zoom out a step around the canvas center
  • Fit to screen (frame icon) — fit the entire diagram into view
  • Export (when available) — open the diagram export dialog

You can also zoom by scrolling with your mouse wheel, and pan by dragging any empty part of the canvas.

In the C4 editor, dragging a node to reposition it is remembered — your layout is saved with the project. If you want to start over, the Reset to auto-layout button (the circular-arrow icon by the zoom controls) discards your manual positions and re-runs the automatic layout.

Jump to anything: the search modal

Every viewer and editor has a search button (magnifier icon). It opens a modal that searches the whole diagram tree at once — in C4 by layer name or by any element inside a layer, in F4 across every process and diagram — and jumps you straight there. It's the fastest way to move around a large model without clicking through the tree.

Panels and collapse

The three panes are resizable: drag the divider between the left and canvas to widen or narrow the tree pane, or between the canvas and right form to resize the details panel. The right pane can be pinned open (click the pin icon in the top-right of the form to keep it visible even when nothing is selected), or allowed to auto-hide when you click away.

On mobile or narrow screens, the three-pane layout collapses. Use the collapse button (⌃ or ⌄ chevron) in the top-right corner of the header to fold up the topbar and give more screen space to the canvas. The NavMenu and project name stay accessible via the hamburger icon.

Tree and list operations

The left pane tree shows every element, often grouped by type. You can switch between tree view and a flat list using the view toggle at the top of the left pane (icon showing a tree or lines).

Search and expand/collapse

Type into the search box at the top to filter the tree in real time. Use the buttons next to the search box to expand all or collapse all branches at once.

Reorder sections

The left pane may show multiple sections (for example, "Nodes" and "Diagrams" in the C4 editor). Drag a section header to reorder the sections — your preference is saved automatically.

Inline rename

Double-click any element's name in the tree to rename it in place. Press Enter to confirm the new name, or Escape to cancel.

Drag to reparent

In the C4 and F4 editors, you can drag a row up or down the tree to move an element to a different parent. The left pane shows which targets are valid (the drop zone highlights in green). Release to drop; invalid drops snap back.

Drag from tree onto canvas

Drag a node from the tree and drop it on the canvas to add it to the current diagram at that position. This is useful for laying out elements manually or bringing in existing nodes you defined elsewhere.

Description editing

Most elements — nodes, layers, swimlanes, activities — have two description fields:

  • Short description — a plain-text phrase shown under the element's name on the diagram card itself (one line only)
  • Description — markdown-formatted text that appears in the side panel when readers click the element

Edit / Split / Preview modes

The description field has three mode buttons:

  • Edit (pencil icon) — write markdown source code only
  • Split (vertical-split icon) — see the source on the left and a live preview on the right side by side
  • Preview (eye icon) — read-only view of the rendered markdown

Switch modes freely as you work — your choice isn't saved, so you can edit and preview in whatever order feels natural.

Table builder

While in Edit or Split mode, a Table button appears above the source area. Click it to open a visual table editor. You can:

  • Insert a new table at the current cursor position
  • Edit an existing table by placing your cursor inside it and clicking Table again
  • Build a GitHub Flavored Markdown (GFM) table visually without writing the syntax by hand

The table is inserted into your markdown as a properly formatted GFM table.

Markdown features

The description field supports standard markdown: bold, italic, code, links, lists, code blocks, and more. Mermaid diagrams work too — embed a mermaid code block (```mermaid ... ```) and it renders as a live diagram inside the panel.

Icon picker

Nodes and some other elements can have a Material Symbol icon displayed on their card. Click the icon picker field (or the current icon thumbnail) to open an icon search panel. Type to filter by name (e.g., "database", "server"), or browse the curated starter grid. Select one to apply it, or click a clear (✕) button if one appears to remove the icon.

Searchable pickers

Many fields use a SearchableSelect dropdown — for example, when choosing an element type, a parent node, or a target for a relationship. You can:

  • Type to filter the list in real time
  • Click or press arrow keys to navigate
  • Press Enter to select, or Escape to cancel
  • Select — None — (top of the list if enabled) to clear the choice

Options are often grouped by category. Group headers appear inline above related options.

Global header chrome

The top of every page carries:

  • Hamburger menu (top-left) — jump to any screen (C4 Viewer, C4 Editor, Deployment, F4, Docs, Give feedback, Support) or take the product tour. Under Projects it also lists your three most recent projects — click one to switch to it (a "+N more…" row opens the full hub)
  • CRAYON-C4 mark — click to return home
  • Editor name (on editor screens only) — shows "C4", "D4" (Deployment), or "F4"
  • Back/Forward buttons — navigate through your screen history within this session
  • Active project name — click to open the project detail page
  • Diagram type dropdown (on the six diagram screens) — switch between C4, D4 (Deployment) and F4 without leaving view or edit mode: picking D4 from the C4 editor opens the deployment editor, and picking it from the C4 viewer opens the deployment viewer
  • View / Edit toggle (on the six diagram screens) — flip between the viewer and the editor of the diagram you are on, keeping your place. Together with the dropdown beside it, the two controls set the two halves of "which diagram, and how" independently
  • Save to cloud (editor screens, cloud projects only) — pushes your local edits to the cloud; it pulses when you have unsaved changes. A Load latest or Review & save button appears beside it when the cloud copy is newer. Local projects autosave and show no save button
  • Profile menu (top-right) — shows your avatar; click to see your profile settings or log out
  • Version info — in the hamburger menu, shows your current build version

Keyboard shortcuts

A few shortcuts work across all editors:

  • Delete or Backspace — delete the selected element (with confirmation if it has children or relationships)
  • Escape — cancel an inline rename, clear a selection, or close an open modal
  • Enter — confirm an inline rename

No other keyboard shortcuts are built in; mouse and menu interactions are primary.

Empty states

When you have no project at all — a first visit, or after deleting your last project — every diagram screen shows a Create a project card that opens the same New Project dialog as the projects hub (Blank, Demo, From file, or From code).

When a project exists but you open an editor with no diagram yet, or create a new diagram with no elements, you'll see an empty-state overlay instead. It explains what to do next and often includes:

  • An explanation of what goes in this diagram type
  • A Show me how button that launches the product tour, walking through the relevant features step by step

The overlay fades when you add your first element, and you can always access the tour again from the hamburger menu.

Where next