Build diagrams — visually or as code.

What is Gramit?

Gramit is a browser-based editor for hierarchical diagrams — flowcharts, system architecture, mind maps and more. Its defining feature is subflows: any node can contain an entire sub-diagram, so big systems break down into navigable levels. No account, no server — your work stays in your browser.

Two ways to build

You can create the same diagram in whichever way fits the moment — and switch freely, since both stay in sync.

Core concepts

On the canvas

1. Pick a shape from the toolbar at the top (or press a shortcut like N).
2. Click the canvas to drop a node, then double-click it to type a label.
3. Hover a node's edge and drag from a handle to another node to connect them.
4. Select a node to open the properties panel and restyle it.

With code

1. Open the ☰ Menu (top of the editor) and choose Code to Diagram.
2. A panel opens with the current diagram expressed as Gramit Code.
3. Edit the YAML — the canvas updates automatically after a short pause.
4. Mistakes are underlined in red, with autocomplete as you type.

Here is a complete, valid diagram — and exactly what it renders:

root:  nodes:    - name: start      text: Start    - name: build      text: Build the thing    - name: ship      type: circle      text: Ship it  edges:    - from: start      to: build    - from: build      to: ship      text: done

You don't have to write Gramit Code by hand. There's a plain-text version of this reference built for AI assistants. Hand the link to any chat AI (ChatGPT, Claude, Gemini, …) and it can read the language and generate diagrams for you.

The link below is an index: enough to write a diagram, plus four resources the assistant fetches when it needs them — the full language reference, a JSON Schema to check its own output against, a searchable index of the icon library, and complete worked documents to adapt.

How to use it

1. Copy the link above.
2. Paste it into your AI chat together with a description of the diagram you want.
3. The AI reads it and replies with Gramit Code (YAML), plus a link that opens the diagram.
4. Open the link — the board is there, saved to your gallery. Or paste the YAML into ☰ Menu → Code to Diagram yourself.

A prompt you can copy and adapt:

Read https://www.gramit.io/docs/ai — it is the index for Gramit Code,a YAML language for diagrams, and it links to the full reference,a JSON Schema and an icon search. Using only the rules it defines,generate a valid Gramit Code document for:   A signup flow: landing page -> signup form -> email verification ->  dashboard, with a decision node for "email valid?". Give me the YAML and the gramit.io/new#code= link that opens it.

The link an assistant hands back

An assistant can deliver a finished board as a URL: gramit.io/new#code=<base64 of the YAML>. Opening it renders the diagram and saves it to this browser's gallery. The document is base64 so the link survives being pasted through a chat client, and it rides in the fragment, which never reaches a server — the board stays between you and whoever sent it.

The editor is an infinite canvas. The toolbar sits at the top, your saved diagrams and assets open from the left, and settings live behind the ☰ Menu at the top-right.

Pan & zoom

• Pan — scroll, or drag an empty part of the canvas with the Pointer tool.
• Zoom — Ctrl/⌘ + scroll, or pinch on a trackpad.
• Zoom to fit — frame the whole diagram with Shift + 1.

Selecting

• Click a node or edge to select it; Shift-click to add to the selection.
• Drag on empty canvas to rubber-band a group of nodes.
• Press Esc to clear the selection and return to the Pointer tool.

Zoom controls

The zoom indicator sits at the bottom-left. Hover it to reveal zoom-in, zoom-out and zoom-to-fit actions. The current zoom percentage is always visible.

The top toolbar holds every creation tool. Pick one, then click the canvas to place it. Most tools have a one-key shortcut — pressing it selects the tool without touching the mouse.

Pointer & laser

• Pointer (V) — select, move and resize. The default tool.
• Laser (L) — a temporary pointer trail for presenting; it draws nothing permanent.

Shapes

Each shape tool drops a node you can immediately label and style. Frame is the exception — it's a background container, drawn by dragging.

Free arrow

The Arrow tool (A) draws a standalone arrow that isn't bound to any node — handy for annotations and callouts. Click to place the start point, move the mouse, then click again to finish. Hold Ctrl/⌘ while clicking mid-draw to drop an elbow and keep extending the tip; press Esc to cancel the arrow you're drawing.

• Every point on a finished arrow — including its endpoints — stays reshapeable via a small drag handle.
• The properties panel offers the same styling as an edge: stroke, arrowheads, and an Arrow type of curved, smooth or step (orthogonal).

Text

The Text tool (T) drops a free-floating label with no border or fill. Resizing a text node scales its font size rather than wrapping the text.

Person, icons & images

• Person (P) — a person glyph for actors and users in context diagrams.
• Icons — open the icon picker, search thousands of provider/tech icons, and click one to drop it. See also the icon node in code.
• Images — open My Assets to upload and place images, or drag/paste an image straight onto the canvas.

Code nodes

The Code tool (C) drops a syntax-highlighted code block. Pick the language from the node's properties; supported languages are JSON, JavaScript, TypeScript, Python, HTML, CSS and Markdown.

Move & resize

• Drag a node to move it; drag a selection to move them together.
• Select a node to show resize handles at its corners and edges, then drag to resize.

Editing labels

Double-click a node to edit its text. Press Esc or click away to finish.

Properties panel

Selecting a node or edge opens the properties panel on the right. It adapts to what's selected — stroke and fill colors, stroke width and style, corner rounding, sketch roughness, opacity, and type-specific options like image size or code language.

Layers & order

When shapes overlap, use the panel's layer actions — send to back, send backward, bring forward, bring to front — to control stacking.

Copy, cut & paste

• Ctrl/⌘ + C / X / V to copy, cut and paste. Pasted copies are offset so they don't land exactly on the original.
• Duplicate a selection from the properties panel. Duplicating a node that has a subflow clones the whole nested tree.
• You can paste images and text copied from outside the app directly onto the canvas.

Drawing connections

Hover a node to reveal its connection handles on each side. Drag from a handle to another node to create an edge. Gramit picks the best entry and exit sides automatically and re-routes as you move nodes around.

Styling connections

Select an edge to restyle it in the properties panel: line color, width and style (solid / dashed), a straight or curved path, arrowheads, an optional label, and sketch roughness.

Bending a connection

Select an edge and a small dot appears at its center — drag it to bend the connection through that point. The source and target stay exactly where they are; only the middle moves. If the edge has a text label, the label itself is the handle, so there's nothing extra to grab.

Colors & fills

Every shape has a stroke (border) and a fill color. Set the fill to transparent to show a pattern instead — hatch, cross-hatch or dots. Colors accept hex and rgb/rgba values.

Sketch style

The sloppiness control gives shapes and edges a hand-drawn look, from clean and precise to loose and rough. It's purely visual and applies per node or edge.

Themes & style profiles

From the ☰ Menu you can switch:

Subflows are Gramit's signature feature: any node can hold an entire diagram inside it, letting you build layered, drillable systems.

Creating a subflow

Select a node and choose Create subflow in the properties panel. The node gets a small indicator showing it now contains a nested flow.

Navigating levels

• Drill in — open a node's subflow to edit it as its own canvas.
• Go up — return to the parent level with Alt + ↑.
• The breadcrumb at the bottom shows your path and lets you jump to any level.

Preview panels

Sliding panels show the parent level on the left and a child subflow on the right, so you can keep context while you work and expand a preview into the full canvas when you're ready.

The My Diagrams panel (the gallery, opened from the left) holds every diagram in this browser — or in your account when signed in.

Saving & loading

Your work autosaves as you go. Open My Diagrams to switch between diagrams or start a new one. Signed in, diagrams sync to your account and follow you across devices; otherwise they're stored locally in your browser.

Rename, clone, delete

Each entry can be renamed, duplicated (a full copy, including subflows) or deleted from the gallery.

Public sharing

Share publishes a read-only copy at a public link anyone can open — handy for reviews and docs. Turn sharing off at any time to revoke access.

My Assets is your personal image library, opened from the toolbar's image tool. Upload once, then reuse images across diagrams.

Adding images

• Click Upload in My Assets, or drag an image file onto the panel.
• Drag or paste an image straight onto the canvas to add it and store it as an asset.

Renaming & storage

• Rename from the right-click menu (or double-click the name). Names allow letters, numbers and spaces — no special characters.
• Assets are cloud (synced to your account) or local (this browser only); the icon on each thumbnail shows which.

Placing on canvas

Double-click an asset, or drag it onto the canvas, to create an image node. The same image can be reused any number of times.

Export as image

Open Export as Image from the ☰ Menu (or press Ctrl/⌘ + P). A preview opens where you can pan and zoom before downloading.

Options

Single-key tool shortcuts work whenever you're not typing in a field.

A Gramit document is a YAML mapping with up to three kinds of top-level keys. Only root is required.

template:        # optional — diagram-level settings  name: My Flow  theme: dark  style: clean root:            # required — the main flow  nodes: [ ... ]  edges: [ ... ] my_subflow:      # optional — any other key is a subflow  nodes: [ ... ]  edges: [ ... ]

The optional template block sets diagram-wide defaults.

template:  name: User Onboarding  theme: dark  style: handmade  direction: LR  spacing: 120 root:  nodes:    - name: a      text: Sign up    - name: b      text: Verify email  edges:    - from: a      to: b

Every entry under nodes: needs a unique name. Everything else is optional and falls back to the active style.

root:  nodes:    - name: my_node       # required — unique id      type: simple        # optional — defaults to 'simple'      text: Hello World   # the label shown on the node      color: '#1e3a5f'      stroke: '#3b82f6'

The type field decides the shape and which properties apply. Omit it for a plain rectangle. Here are the geometric types side by side:

root:  nodes:    - name: rect      text: simple    - name: round      type: circle      text: circle    - name: dec      type: decision      text: decision    - name: label      type: text      text: text    - name: who      type: person      text: person  edges:    - from: rect      to: round    - from: round      to: dec

Each type accepts a different set of visual properties:

Any property you omit inherits from the active diagram style. Mix and match these on the node types that support them.

root:  nodes:    - name: highlight      text: Important      color: transparent     # no solid fill...      fill: hatch            # ...so show a hatch pattern      stroke: '#f59e0b'      stroke_width: 2      stroke_style: dashed      sloppiness: 2      edges: round

Property reference

Type-specific notes

• person — stroke can't be transparent; fill and stroke_style aren't supported.
• circle — edges has no effect (circles are always round).
• icon — only icon and opacity apply; colors are ignored.
• image — url, width, height, size, color, edges and opacity apply.
• code — text is the code content (not a label); language is required.

Fixed positions

A node with x and y sits exactly there, and the automatic layout leaves it alone even when the rest of the diagram is re-tidied. The pair names the node's center, so two nodes given the same y line up however differently sized they are. Both have to be present — x on its own is an error.

template:  direction: LR  spacing: 160 root:  nodes:    - name: clients      type: icon      text: Clients      icon: general/connectivity/smartphone      x: 140      y: 460    - name: chat      type: icon      text: Chat servers      icon: cloud/compute/aws/ec2      x: 880      y: 460  edges:    - from: clients      to: chat      text: connect

Four node types take extra fields beyond the visual properties above.

icon node

Shows an icon with a label underneath. The icon field is an icon id from the built-in library — the same ids you get from the icon picker (e.g. cloud/compute/aws/lambda).

root:  nodes:    - name: gateway      type: icon      text: API Gateway      icon: cloud/integration/aws/api-gateway    - name: fn      type: icon      text: Lambda      icon: cloud/compute/aws/lambda    - name: db      type: icon      text: DynamoDB      icon: cloud/databases/aws/dynamodb  edges:    - from: gateway      to: fn    - from: fn      to: db

image node

Embeds an image. url can be a full URL or a compact asset path (assets/…) — see Assets.

root:  nodes:    - name: banner      type: image      text: Gramit      url: https://gramit.io/logo.png      edges: slight

Control the rendered size in one of two ways:

Use width + height for precise dimensions, or size to scale proportionally. A single width or height scales the other to keep the aspect ratio.

root:  nodes:    # exact dimensions    - name: hero      type: image      url: assets/picture-of-my      width: 320      height: 180    # scaled to 2× the default size    - name: thumb      type: image      url: assets/picture-of-my      size: 2

code node

Renders a syntax-highlighted code block. Both language and text are required; language: auto detects it from the text.

root:  nodes:    - name: api_call      type: code      language: typescript      text: |        const res = await fetch('/api/users');        return res.json();      stroke: '#6366f1'      color: '#1e1b4b'

table node

Rows and columns of plain values. rows is required: one list per row, each a list of cells. header picks the header: row (the default), column or none. Between two tables an edge can carry cardinality, read from:towith 1 for one, N for many and 0..N for zero or many, drawn as crow's foot ends.

root:  nodes:    - name: users      type: table      rows:        - [id, name, email]        - [1, Ana, ana@example.com]    - name: orders      type: table      rows:        - [id, user_id, total]        - [10, 1, 42]  edges:    - from: users      to: orders      cardinality: 1:N

person node

A person glyph for actors and users.

root:  nodes:    - name: user      type: person      text: Alice      stroke: '#16a34a'   # cannot be 'transparent'      color: '#bbf7d0'      sloppiness: 1

A frame is a container: a box drawn behind the diagram that groups the nodes belonging to it. Point a node at one with frame and the box appears around every node that names it. You never give it a size or a position.

The frame doesn't have to exist first. A name nothing else uses is the frame, and doubles as its title:

root:  nodes:    - name: api      text: API      frame: backend      # no 'backend' node anywhere, so this creates it    - name: worker      text: Worker      frame: backend     - name: client      text: Client  edges:    - from: client      to: api    - from: api      to: worker

Declaring a frame

Write the frame out as a node when you want a title of your own or any styling on the box. Everything pointing at that name lands inside it, exactly as before.

root:  nodes:    - name: backend      type: frame      text: Backend Services      stroke: '#3b82f6'      color: 'rgba(59,130,246,0.06)'     - name: api      text: API      frame: backend    - name: worker      text: Worker      frame: backend     - name: client      text: Client  edges:    - from: client      to: api    - from: api      to: worker

Nesting

A frame can name another frame, putting one box inside the other. The outer frame grows to hold the inner one and its contents. Only a declared frame can sit inside another, since it needs a frame of its own. A frame that ends up inside itself is an error.

root:  nodes:    - name: cloud      type: frame      text: Cloud     - name: cluster      type: frame      text: Cluster      frame: cloud     - name: pod_a      text: Pod A      frame: cluster    - name: pod_b      text: Pod B      frame: cluster

Notes

• An undeclared name creates the frame and titles it with that name. Declaring it with type: frame replaces that title with your text.
• frame can't point at a node that already exists and isn't a frame. That's an error, not a new box.
• A frame takes the same visual properties as a simple node; its outline is dashed unless you set stroke_style.
• text is the frame's title and sits at the top left corner, not centered.
• Edges can't attach to a frame. Connect the nodes inside it instead.
• The frame's box is sized around its contents. A frame you widened on the canvas keeps that size; it grows to fit new members but never shrinks on its own.
• A frame nobody names is just an empty box, the same one the Q tool draws.
• Moving a node on the canvas writes the code back with every frame spelled out as a node, so a frame you left implicit comes back declared.

Edges connect two nodes by name. Both from and to must reference existing nodes.

root:  nodes:    - name: node_a      text: Request    - name: node_b      text: Response  edges:    - from: node_a      to: node_b      text: Submit      type: curved      style: dashed      arrow: open      width: 2      stroke: '#ef4444'

Any top-level key other than template and root defines a subflow — a nested diagram you can open from the editor. Use them to break a big flow into drillable levels.

root:  nodes:    - name: onboarding      text: Onboarding    - name: dashboard      text: Dashboard  edges:    - from: onboarding      to: dashboard # A subflow — opened as its own level in the editoronboarding:  nodes:    - name: welcome      text: Welcome Screen    - name: setup      text: Account Setup  edges:    - from: welcome      to: setup

My Assets is your personal image library — open it from the toolbar (the image icon). Upload images once, then reuse them across diagrams. When signed in, assets sync to your account; otherwise they're kept locally in your browser.

Using assets in code

An image node's url can be a full URL or a compact asset path. Assets you own are written in the short form assets/<name> instead of the long storage URL, so the code stays readable.

root:  nodes:    - name: logo      type: image      url: assets/picture-of-my   # an asset from My Assets      size: 1.5

Naming assets

Rename an asset in My Assets (right-click → Rename, or double-click its name). Names may contain letters, numbers and spaces — no special characters. In code, spaces become hyphens: an asset named picture of my is referenced as assets/picture-of-my.

Every color field — node stroke, color, and edge stroke — accepts:

root:  nodes:    - name: hex      text: '#3b82f6'      stroke: '#3b82f6'    - name: rgb      text: rgb()      stroke: rgb(34, 197, 94)    - name: ghost      text: transparent      color: transparent      stroke: '#f59e0b'  edges:    - from: hex      to: rgb    - from: rgb      to: ghost

When a visual property is omitted, it inherits from the active diagram style:

The editor validates as you type and only re-renders the canvas when the whole document is valid. The main rules:

Nodes

• name is required, non-empty, and unique (within its flow and globally).
• type must be one of the supported types.
• Properties outside a type's allowed set are flagged.
• sloppiness ∈ {1,2,3,4}; stroke_width ∈ {0.5,1,2,4}; opacity ∈ 0–100.
• color / stroke must be valid color strings.
• code nodes require language and text; image nodes need a url (a full URL or an assets/… path).
• image width, height and size must be positive numbers.
• frame either names a frame node in the same flow or a name nothing else uses (which creates the frame). Pointing at a node that isn't a frame is an error, and no frame may end up inside itself.

Edges

• from and to are required and must reference existing node names, and neither can be a frame.
• width ∈ {1,2,3,4}; sloppiness ∈ {1,2,3,4}.

Template

• theme must be light or dark; style must be handmade or clean.
• Unknown keys (in the template or a flow) are flagged.

A complete diagram using a template, multiple node types, styled edges, a frame grouping the sign up steps, and a subflow. The preview renders the root flow.

template:  name: User Registration Flow  theme: dark  style: handmade root:  nodes:    - name: signup      type: frame      text: Sign up      stroke: '#3b82f6'     - name: start      text: Start      color: '#1e293b'      stroke: '#94a3b8'    - name: form      text: Fill Registration Form      color: '#1e3a5f'      stroke: '#3b82f6'      stroke_width: 2      frame: signup    - name: validate      type: decision      text: Valid?      stroke: '#f59e0b'      color: transparent      fill: hatch      frame: signup    - name: error_msg      text: Show Errors      color: '#fee2e2'      stroke: '#ef4444'      frame: signup    - name: done      type: circle      text: Done      color: '#dcfce7'      stroke: '#16a34a'    - name: new_user      type: person      text: New User      stroke: '#3b82f6'      color: '#dbeafe'  edges:    - from: start      to: form      type: curved    - from: form      to: validate      text: Submit      type: curved    - from: validate      to: error_msg      text: "No"      style: dashed      stroke: '#ef4444'      arrow: open    - from: validate      to: done      text: "Yes"      stroke: '#16a34a'      width: 2    - from: done      to: new_user      type: curved      stroke: '#16a34a'      arrow: closed notifications:  nodes:    - name: email_sent      text: Send Welcome Email      color: '#fef9c3'      stroke: '#ca8a04'    - name: sms      text: Send SMS Verification      color: '#fef9c3'      stroke: '#ca8a04'  edges:    - from: email_sent      to: sms