Studio reference

Every panel, gesture and shortcut in the browser app. Start it with diagc studio (pnpm dev in a checkout of this repository).

Modes

A diagram compiled from .diagram.ts shows a read-only chip and cannot enter edit mode. Only .diagram.json sources are browser-editable.

New diagram (＋, beside the diagram picker) is always available while the dev server runs — it creates an empty .diagram.json and opens it for editing.

Navigation

Editing

New nodes are typeless — just a label — so quick sketches stay clean. Give a node a type in its panel to get the registry's shape and icon.

Keyboard

Every action below can be given a different key, a second key, or none: open Keyboard shortcuts with the ⚙ in the top bar or ? — see Change keyboard shortcuts. These are the defaults; Ctrl is Cmd on a Mac. Button tooltips always show the key an action has now.

Bindable, no default: New / Duplicate / Eject diagram, Re-layout, Auto-layout, open/close all threat notes, pen width (thin / medium / thick), dim unconnected, show/hide drawings, show/hide loop badges, Freeze layout, Save positions, Auto-arrange, align left / centre / right / top / middle / bottom, distribute horizontally / vertically, inspector tab (Properties / Library).

Fixed — gestures and cancels, not rebindable:

A shortcut acts only while its button would: Pen does nothing while you are drilled into a group, Save positions nothing when nothing moved. Shortcuts are ignored while you are typing in a field and, in the Obsidian pane, while focus is anywhere outside the studio. A held key repeats only for Undo, Redo and zoom. Letters and digits work under a non-Latin keyboard layout (the physical key is read); a symbol follows the character your layout types. History is capped at 100 steps.

Panels

Properties (node selected) — name, type, icon, colour swatches, Technology, description, free-form metadata rows, Threats (below), memberships (which parents contain it, per plane), Position (X/Y in parent-relative px — pinned values editable, unpinned nodes show where they sit; Clear hands the node back to the algorithm; on a plan plane a top-level zone's X belongs to the layout, which re-derives it from start, so only Y is yours to set and the X shown here is inert), delete.

Properties (relation selected) — kind, label, Threats (below), layer, delete, plus a Style section: line shape (curved / straight / step), colour, thickness, line (solid / dashed / dotted), arrow end (arrow / dot / square / diamond / none), from/to side, animated. Anything left at default falls back to the kind's registry style and the layer tint. On a causal-loop plane the panel adds Polarity (∅, +, −) and Delay rows, and Style gains Curvature and Flip curve.

Threats — a section of both Properties panels, shown on a threat-model diagram, and on any element that already carries threats whatever the notation (so turning the notation off never strands them). The header counts open / total; on a relation, a Crosses: from → to line names the two trust boundaries its ends sit in (outside where there is none), derived from containment. The add row is a STRIDE category select — the categories that apply to this element's type first, then the rest behind a separator — a threat title, and Add (disabled while the title is blank; Enter adds). Each existing threat is a row: category, title (commits on blur or Enter), severity (—, low, medium, high, critical), status (open, mitigated, accepted, not-applicable), a ▸ details disclosure holding description and mitigation, and Remove. Every commit is one undo step, and a commit that changes nothing lands none. See Draw a threat model.

Plan — the right dock's own panel on a plan plane: zones listed in tree order with their start/end dates and Owner / Executor / Checker pickers, events with their date, and Add zone, Add event, Add person / Add team to grow the schedule. Properties gains a matching Plan section, shown on a plan plane, or anywhere a zone or event already carries dates: a zone's start, end and role pickers, or an event's date. + on a selected zone or event adds its successor — the next zone starting the day after this one ends and running the same length, the next event a week later, both clamped inside the parent and linked back with a dependency arrow. Selecting an actor or a zone (both modes, and on a published page) lights up the other side of its roles — the connected zones or actors keep a coloured outline and a solid chip while the rest of the chart dims — the same connected-neighbourhood focus every notation offers, extended here past the role relations that never draw as arrows. Dragging a person or team from the roster onto a zone makes it the zone's executor instead of picking it in the panel (a no-op if it already holds a role on that zone); dragging any other node onto a zone re-homes it under that zone. Clicking one of the bar's own role chips opens a menu to change the actor's role or remove it, in edit mode. See Draw a plan.

Comments (any node or relation) and Links (nodes) edit the lists the canvas bubble shows; the badge at the element's bottom-right corner opens that bubble in both modes. See Comment on a diagram.

Library — the palette. See Library reference and Use the icon library.

The left dock keeps the tab you chose: selecting on the canvas never switches it. Add node in the Library opens Properties for the name; a placed stencil names in place on the canvas.

Leverage — on a plane with the causal-loop notation, in view mode, selecting a variable turns the left dock into this panel: the feedback loops the variable sits in, the upstream drivers that reach it with the net sign of each shortest path, and the variables that recur across its loops. Ctrl/Cmd + click a second variable adds a Dependency section. ↻ in the corner controls shows and hides the R/B loop badges; click a badge to light its loop. See Draw a causal-loop diagram.

The right dock stacks its panels — the notation's own panel (Git, Activity, And then what?, Fishbone, Threat model or Plan), then Layout & style, then Layers & planes — in one scrolling column. Click a panel's heading to fold it down to that heading; the others stay open. Which panels are folded is a viewer preference, remembered across reloads and never saved to the diagram. The dock's own chevron still hides the whole column.

Layout & style — how the active plane is arranged and drawn, in both modes. One row per setting: Algorithm, Direction, Wrap (off / square / screen / wide — folds a long layered chain onto several rows), Spacing, Edges (rounded / square corners) and Style (clean, sketch, hand-drawn, pencil, blueprint, marker). View mode previews the layout settings (Reset layout drops the preview); edit mode saves them to the layout file. Style is a viewer preference in view mode, remembered across reloads and independent of light/dark; in edit mode the same row pins a style into the diagram. The hatched presets (hand-drawn, pencil, marker) hatch boxes only: an open group takes a plain wash, since its area is where its children and their edges are drawn, and an outline boundary (C4 boundary, AWS region) stays a line in every preset. Under the rows sit the mode's layout commands: Auto-arrange and Freeze layout in view mode (see Place boxes on a generated diagram), Re-layout and Auto-layout in edit mode. Their shortcuts work whether or not the section is folded.

Layers & planes — add, edit and remove layers (id, name, tint) and planes (id, name, containment borrowing, preset layers, its own Notation). In edit mode it also carries a model-level Notation selector (default look, then each notation by name: Causal loop, Git graph, C4, Second-order thinking, Fishbone (cause and effect), Threat model (STRIDE), Plan (schedule), Deployment — a plane's own notation wins where set) and a Legend checkbox, which adds or removes the diagram's legend declaration; its title, position, sections and items are authored in the file. See Draw a C4 diagram and Add a legend.

Git — on a plane with the git-graph notation, in edit mode: add lanes and commits, branch the selected commit into another lane, merge it into one, set its gap. Each action is one undo step. Add commit is the same action as the + on a selected lane or tip commit. See Draw a git branching diagram.

Activity — when an activity-frame, activity-lane or activity-region is selected, in edit mode. On a frame or a lane: name a lane, pick a colour, Add lane (it goes to the bottom of the frame; the + on a lane's edge inserts one right above or below it). On a lane or region: an optional name field plus one quick-add button per leaf type (action, decision, fork/join bar, start, end, send signal, receive signal, object, note), and, on a lane only, Add region. Every add parents the new node in the selected scope and places it at a deterministic spot, sidestepping drag-and-drop entirely — the model never passes through a state validation would refuse. See Draw an activity diagram.

Second-order thinking — on a diagram with the second-order notation, in edit mode: "And then what?" with Good consequence / Bad consequence / Neutral consequence, enabled once a decision or consequence is selected, plus Add a decision, always offered. Each add is one undo step for the box and its arrow together; it also opens the new node's name for typing, which is a separate, later undo step once committed. Lists the notation's validation issues (an unreachable consequence, a cycle), each clickable to select the offending node. See Draw a second-order thinking diagram.

Fishbone — on a diagram with the fishbone notation, in edit mode: Add an effect until there is one; then Software / 6M / 4S while the effect has no bones; then Add a category (nothing or the effect selected) or Add a cause (a bone or a cause selected — disabled on a sub-cause, which takes nothing). Each add is one undo step for the node and its arrow together; it also opens the new node's name for typing, which is a separate, later undo step once committed. Lists the notation's validation issues, node ones clickable to select. The arrangement is the notation's own, so the layout controls are absent and a node on the fish cannot be dragged, nudged or aligned. See Draw a fishbone diagram.

Threat model — on a diagram with the threat-model notation, in both modes: this panel only reads, so a read-only .diagram.ts threat model gets its register too. Crossings to review lists every flow whose two ends sit in different trust boundaries and that carries no threat yet — the flow's two elements on one line, the two boundaries (outside where there is none) underneath — each clickable to select it. Register lists every threat in the diagram grouped by the element that carries it, in model order (elements first, then relations), each element's row clickable to select it and showing its own open / total. Threat and threat-model validation issues follow under Issues, clickable where they name an element. Every element with threats wears a badge that opens its bubble on the canvas — see the Editing table. Title, status, description and mitigation can be written there; category and severity live in the Threats section of the Properties panel. See Draw a threat model.

Top bar

One row, in both modes. Layout and style are not here: they are the right dock's Layout & style section (above).

In a narrow pane the app name gives way first, then the diagram's folder and name shorten; the buttons never wrap or leave the window.

In edit mode a tool row sits under the top bar: Done, Select / Pen / Eraser (with the pen's colour and width while it is active), Undo / Redo / Save, and the selection's colour.

The plane switcher is in Layers & planes, present when the diagram declares planes. Switching planes keeps your place — the groups containing what you were looking at open automatically in the new plane.

Saving

Save validates first and refuses to write an invalid model, surfacing the same issues the compiler would. On success it writes these files next to your other sources:

• .diagrams/src/<name>.diagram.json — the model
• .diagrams/src/<name>.layout.json — positions, sizes, and which planes have automatic layout switched off
• .diagrams/src/<name>.drawings.json — freehand strokes, only when there are any

The layout file is paired by name alone, so a diagram compiled from TypeScript can have one too — see Place boxes on a generated diagram.

Subfolders are preserved. All are pretty-printed JSON that reviews like any other source.

An unsaved dot sits next to Save while the session is dirty; edits autosave a moment after you stop and Done flushes a final save, so nothing is discarded on the way out — undo is how you take a change back.

Gotchas

• A TypeScript diagram shows its last compile. The studio reads a .diagram.json straight from its source, but a .diagram.ts only through its compiled artifact. diagc studio keeps that current by running the compile watcher.
• Pins, theme and style preset are viewer state. They are not written to the diagram file — except the style preset, which a diagram may pin via its style field.
• JSON diagrams that declare include show their raw source. Composed content is only visible for compiled, read-only diagrams.
• Library saves are best-effort. A failed write to library.json is currently swallowed silently.
• A folded group shows no notes for what it hides. Only its own; unfold it for the notes inside.
• On a git-graph, fishbone or plan plane the layout pickers (algorithm, direction, wrap, spacing, edges) are hidden, in both modes: the notation owns the arrangement. Style, Auto-layout on/off and Re-layout still work.
• On a causal-loop plane the Algorithm picker defaults to Stress (overlap-free), which is otherwise not offered; choosing Layered there saves layered by name.
• On a second-order diagram only the layout algorithm picker is hidden — it is pinned to layered so the order bands can use elk's partitioning. Direction, spacing and edge routing stay adjustable.

See also

• Tutorial 2 — Draw one in the browser
• Use planes and layers
• Organise a large diagram