> ## Documentation Index
> Fetch the complete documentation index at: https://learn.workflow.dog/llms.txt
> Use this file to discover all available pages before exploring further.

# Organize the Canvas

> Select, arrange, label, highlight, and pin nodes as workflows grow.

A readable canvas makes execution order, data ownership, and failure paths
visible. WorkflowDog provides selection tools, automatic layout, comments,
highlights, and pinned actions for keeping large workflows navigable.

## Select the nodes you mean to change

| Action                               | Result                                           |
| ------------------------------------ | ------------------------------------------------ |
| Click a node                         | Selects that node.                               |
| Shift-click a node                   | Adds it to or removes it from the selection.     |
| Hold Option and drag on empty canvas | Selects nodes whose centers fall inside the box. |
| `⌘ A`                                | Selects every node.                              |
| `⇧ ←`                                | Adds the selected nodes' direct incomers.        |
| `⇧ →`                                | Adds the selected nodes' direct outgoers.        |
| Click empty canvas                   | Clears the selection.                            |

Dragging one selected node moves the whole selection. Once selected, the
floating toolbar provides layout, alignment, highlight, duplicate, copy, cut,
disable, extraction, and deletion actions.

<Note>
  Keyboard shortcuts above use macOS symbols. The corresponding modifier keys
  may differ on another operating system.
</Note>

## Lay out a selection

Select at least two nodes and choose **Auto Layout**, or press `⌘ ⇧ L`. The
layout follows graph connections and arranges the selected actions from left to
right.

Use the additional selection tools for smaller adjustments:

* **Auto align top/left** — `⌘ ⇧ A`
* **Auto align center** — `⌘ ⇧ S`
* **Auto align bottom/right** — `⌘ ⇧ D`

The editor chooses horizontal or vertical alignment based on the shape of the
selection and keeps at least a small gap between aligned nodes.

<Tip>
  Auto-layout the functional nodes first, then adjust comments and explanatory
  spacing. Repeated manual pixel adjustments are rarely worth preserving.
</Tip>

## Lay out the entire workflow

Choose **Auto Layout Entire Workflow** in the main toolbar or press `⌘ ⇧ G`.
The full layout uses the graph's dependencies and keeps visual groups together.

If a group includes a [Comment](/reference/actions/core/comment), the
upper-left comment acts as a heading above the group's functional nodes. This
makes a consistent pattern effective:

* Add a **Validate order** comment above the actions that parse input, validate
  the schema, and route valid and invalid data.
* Add a **Fulfill order** comment above the actions that create the shipment
  and notify the customer.

Automatic layout is deterministic from the graph and current groups, but it is
still a structural tool. Review long edge crossings and adjust the few places
where business meaning benefits from extra space.

## Add comments

[Comment](/reference/actions/core/comment) displays Markdown directly on the
canvas. It has no runtime output and never affects execution.

Use comments for:

* a section heading;
* the business rule behind a condition;
* the expected shape of a sub-workflow payload;
* an important external-system assumption; or
* a maintenance note that belongs with the graph.

Comments support left, center, or right alignment and small, medium, or large
text.

<Warning>
  Comments are visible to people who can view the workflow. Never place API
  keys, passwords, access tokens, or other secrets in them.
</Warning>

Write comments about intent rather than narrating an obvious node. **Orders
over \$500 require manual review before fulfillment** is more useful than
**Checks if amount is greater than 500** because it records the business rule,
not merely the comparison.

## Highlight related nodes

Select nodes and choose **Highlight Color** from the selection toolbar. Nearby
nodes with the same color form a dashed visual group.

Highlights are most useful when each color has a stable meaning within one
workflow, such as:

* blue for input normalization;
* violet for AI processing;
* green for successful side effects; and
* red for validation or failure handling.

Clicking a group border selects the group. Shift-clicking toggles it alongside
the current selection, and dragging the border moves the grouped nodes
together.

Auto-layout treats nearby groups as units, which helps preserve sections while
rearranging the full workflow.

<Note>
  Color is organizational metadata, not execution logic. Use connections,
  branching actions, and meta controls to define actual behavior.
</Note>

## Pin frequently used actions

Open action search with `/`, `⌘ K`, or `⌘ P`. In the search results, pin an
action to place it in the main toolbar. Pinned actions can be reordered with
the left and right controls in the search result.

From the toolbar:

* click a pinned action to add it at the center;
* drag it onto a specific canvas position; or
* press its slot number, from `1` through `9`, to add it at the pointer.

Pins are stored for the current browser, so they personalize the editor rather
than changing the workflow for collaborators.

Keep the set small and focused on the primitives you actually repeat. Text,
Number, Create Object, Comment, and the control actions you use most often are
good candidates.

## Refactor a dense section

When a section is internally coherent but makes the parent workflow hard to
scan:

1. Select its functional nodes.
2. Choose **Extract to Sub-Workflow**.
3. Inspect the new payload and result boundary.
4. Give the child a specific name.
5. Add a comment beside the caller describing the contract.

The extraction works most cleanly with one incoming and one outgoing boundary
connection. See [Build Sub-Workflows](/building/sub-workflows#extract-selected-nodes)
before extracting a selection with several independent inputs or outputs.

## A practical organization pass

For an existing workflow, use this order:

<Steps>
  <Step title="Follow the main data path">
    Identify the trigger data, primary transformations, and final side effect.
    Make that path easy to read from left to right.
  </Step>

  <Step title="Separate alternate paths">
    Place validation, fallback, and failure paths consistently above or below
    the main path.
  </Step>

  <Step title="Auto-layout sections">
    Select connected sections and use Auto Layout before arranging the entire
    workflow.
  </Step>

  <Step title="Label business boundaries">
    Add comments for rules and contracts that the node names cannot explain.
  </Step>

  <Step title="Apply restrained highlights">
    Group nodes by responsibility, not by package or arbitrary visual variety.
  </Step>

  <Step title="Extract real reuse">
    Move a sequence into a sub-workflow when it has a clear interface or is used
    from more than one place.
  </Step>
</Steps>

A well-organized canvas should let a reader answer three questions quickly:
what starts the workflow, what decisions it makes, and what external changes it
can perform.