# Frames, tones, lines, and symbols

> Page: https://docs.plotwork.dev/cloud-architecture/lines-and-symbols. Index of every page: https://docs.plotwork.dev/llms.txt

Every frame style, tone, edge style, arrowhead, label, and mark the language draws, each shown as the renderer draws it, with the exact source that makes it. It is for anyone who wants to know what a line or a color means before using it, human or AI agent.

## TL;DR

| Question | Answer |
|---|---|
| What does a dashed frame mean? | A boundary: what is inside is isolated or checked differently. Solid is a container, and dotted is a side of a line. |
| Which tones are there? | Eight: `neutral`, `blue`, `violet`, `aqua`, `orange`, `green`, `amber`, `red`. A type sets one, and `tone=` overrides it. |
| Can I write a color? | No. Colors are not accepted. The theme maps each tone to light and dark colors that keep text readable. |
| Which arrows are there? | Six: `->`, `-->`, `..>`, `--`, `<->`, `<-->`. Solid is a call, dashed is a reply or a looser link, and dotted is an event. |
| How do I label a line? | `a -> b : "label"`. The labels `yes` and `no` get a status icon on their own. |
| What can a node or a group carry? | `sub=` for a second line, `stack=` for up to three technology marks, `icon=` to change the icon, and `icon=none` to remove it. |
| How do I show a set that spans two zones? | An `overlay`, a dashed frame drawn around the members. See [Marks, second lines, and overlays](https://docs.plotwork.dev/cloud-architecture/marks-and-overlays.md). |

Every picture on this page is drawn by the renderer from the source beside it, so the page cannot disagree with the renderer. Each picture follows the theme of the page, light or dark.

## 1. Frame styles

A group draws a frame with a corner tab that holds its icon and its name. The frame style tells a reader what kind of boundary it is. A group type sets the style, and no option changes it, so pick the type that says what the group is.

| Picture | Frame | Types | Reads as |
|---|---|---|---|
|  | Dashed | `region`, `zone`, `network`, `identity-boundary`, `trust-boundary` | A boundary: what is inside is isolated or checked differently |
|  | Solid | `cloud`, `account`, `subnet`, `public-subnet`, `private-subnet`, `management-subnet`, `isolated-subnet`, `resource-group`, `cluster`, `scale-group`, `service-plan`, `web-tier`, `app-tier`, `data-tier`, `storage-account`, `messaging`, `edge`, `security`, `observability`, `ci-cd`, `environment` | A logical container: things that belong together |
|  | Dotted | `cloud-boundary`, `on-premises`, `client-side`, `external-systems` | A side of a line: outside the system you are drawing, or the cloud side of a cloud boundary |

## 2. Tones

A tone is a color family. Each tone has a fill and an outline for a group, a chip color for the corner tab, and an ink color for text and icons, tuned for light and for dark. The picture shows an untyped group of that tone. The last column lists the group types that take the tone by default.

Every picture is drawn from this source, with the tone replaced:

```plotwork
flow "Blue tone" direction=down
group g "Blue" tone=blue {
  node n step "Resource"
}
```

| Picture | Tone | The default of |
|---|---|---|
|  | `tone=neutral` | `cloud`, `account`, `region`, `zone`, `subnet`, `resource-group`, `trust-boundary`, `on-premises`, `client-side`, `external-systems` |
|  | `tone=blue` | `network`, `web-tier`, `edge`, `cloud-boundary` |
|  | `tone=violet` | `private-subnet`, `cluster`, `service-plan`, `app-tier`, `identity-boundary`, `ci-cd` |
|  | `tone=aqua` | `scale-group`, `data-tier`, `observability` |
|  | `tone=orange` | `messaging` |
|  | `tone=green` | `public-subnet` |
|  | `tone=amber` | `management-subnet`, `storage-account`, `environment` |
|  | `tone=red` | `isolated-subnet`, `security` |

## 3. Nesting depth

A group nested in another is shaded one step stronger than the one around it, in light and in dark, up to four levels. An account, a region, a network, and a subnet read as four levels, and a neutral group deepens toward the ink color in the same way. Depth is automatic; there is nothing to write.

**Diagram source**

```diagram
flow "Four nested levels" desc="An account holds a region, which holds a network, which holds a subnet with one service." direction=down
group acct "Account" type=account {
  group reg "eu-west-1" type=region {
    group net "Application VPC" type=network {
      group sub "Private subnet" type=private-subnet {
        node app service "Orders API"
      }
    }
  }
}
```

*Picture: Four nested levels: 1 node, 0 connections. An account holds a region, which holds a network, which holds a subnet with one service.*

**Text description**

**Nodes:**

- Account: Account
  - Region: eu-west-1
    - Virtual network: Application VPC
      - Private subnet: Private subnet
        - Orders API, service

**Connections:**

## 4. Edge styles and arrowheads

An edge joins two nodes. The token sets the line style and where the arrowheads go. Use `->` for a call that waits, `-->` for a response or a looser dependency, and `..>` for a call that is not waited for, such as a webhook, an event, a pull, or a push.

Every picture is drawn from this source, with the last line replaced by the statement in the table:

```plotwork
flow "Edge" direction=right
node a step "A"
node b step "B"
a -> b
```

| Picture | Source | Line | Arrowheads | Use it for |
|---|---|---|---|---|
|  | `a -> b` | solid | at the end | A call or a flow of data. |
|  | `a --> b` | dashed | at the end | A reply, a read, or a link that is optional or indirect. |
|  | `a ..> b` | dotted | at the end | An asynchronous call: a webhook, an event, a pull, or a push that is not waited for. |
|  | `a -- b` | solid | none | An association with no direction. |
|  | `a <-> b` | solid | at both ends | A two-way call or sync. |
|  | `a <--> b` | dashed | at both ends | A two-way link that is optional or indirect. |

### Labels and icons on an edge

| Picture | Source | What it does |
|---|---|---|
|  | `a -> b : "HTTPS"` | A label sits on the line. Keep it to a few words. |
|  | `a ..> b : "event"` | A dotted line with a label is an event or a webhook. |
|  | `a -> b : "yes"` | The labels `yes`, `no`, `true`, and `false` get a status icon without being asked: here `status:yes`, a green tick. |
|  | `a -> b : "no"` | The label `no` gets `status:no`, a red cross. |
|  | `a -> b : "retry" icon=status:retry` | An explicit `icon=` on the edge wins. It needs a label. |
|  | `a -> b : "yes" icon=none` | `icon=none` removes the automatic icon. |

An edge between two nodes that sit side by side, such as a primary and a replica database, is drawn straight across, so the two columns stay level. Give it `..>` and a label such as `"replication"`. Keep to one such pair in a diagram.

**Diagram source**

```diagram
flow "Level edge between zones" desc="A primary database in one zone replicates to a replica in the other, on a straight line." direction=right
group a "Zone a" type=zone {
  node primary database "Primary"
}
group b "Zone b" type=zone {
  node replica database "Replica"
}
primary ..> replica : "replication"
```

*Picture: Level edge between zones: 2 nodes, 1 connection. A primary database in one zone replicates to a replica in the other, on a straight line.*

**Text description**

**Nodes:**

- Availability zone: Zone a
  - Primary, database
- Availability zone: Zone b
  - Replica, database

**Connections:**

- Primary to Replica (dotted): replication

## 5. Marks and second lines

A node card and a group tab hold more than a name. These options add to them, and the card or tab grows to hold them without ever covering the icon or the text.

### On a node

| Picture | Source | What it does |
|---|---|---|
|  | `node a service "Orders API"` | A node has a type, which sets its tone and icon, and a label. |
|  | `node a service "Orders API" sub="Validates credentials"` | `sub=` adds a second line under the label. |
|  | `node a storage "Web app" icon=azure:blob-storage stack=simple:angular,simple:typescript` | `stack=` adds up to three small technology marks under the text. The card grows to hold them. |
|  | `node a external "Partner API"` | The type `external` has a dashed outline: a system you call but do not run. |
|  | `node a service "Orders API" tone=violet` | `tone=` overrides the tone the type sets. |
|  | `node a database "orders-db" icon=aws:rds change=update` | `change=` marks a planned change with a corner badge and a coloured outline: `create`, `update`, `replace`, or `destroy`. |
|  | `node a service "Orders API" icon=none` | `icon=none` removes the icon. |

### On a group

Every picture is drawn from this source, with the first group line replaced by the statement in the table:

```plotwork
flow "Group" direction=down
group g "Web tier" type=web-tier {
  node n step "Resource"
}
```

| Picture | Source | What it does |
|---|---|---|
|  | `group g "Web tier" type=web-tier {` | The type sets the icon in the tab, the tone, and the frame style. |
|  | `group g "Web tier" type=web-tier sub="10.0.1.0/24" {` | `sub=` adds a second line to the tab, such as an address range or a plan. |
|  | `group g "Plan" type=service-plan stack=simple:dotnet {` | `stack=` adds up to three small marks to the tab, written like the marks of a node. |
|  | `group g "Network" type=network provider=azure {` | `provider=` makes the type draw that provider's own icon where it has one. |
|  | `group g "Web tier" type=web-tier icon=lucide:rocket {` | `icon=` replaces the icon in the tab. |
|  | `group g "Web tier" type=web-tier icon=none {` | `icon=none` removes the icon. |
|  | `group g "Web tier" type=web-tier tone=amber {` | `tone=` overrides the tone the type sets. Prefer the type that says what the group is. |

### An overlay

An overlay is a dashed frame drawn around nodes or groups that it does not own, wherever layout put them. It is one line after the members. Here two machines in two zones form one scaling group, and the frame crosses the zone frames on purpose.

**Diagram source**

```diagram
flow "Scaling group across two zones" desc="Two web machines, one in each zone, are framed together as one scaling group." direction=right
group a "Zone a" type=zone {
  node w1 service "Web 1"
}
group b "Zone b" type=zone {
  node w2 service "Web 2"
}
overlay set "Web machines" type=scale-group sub="At least 2" members=w1,w2
```

*Picture: Scaling group across two zones: 2 nodes, 0 connections. Two web machines, one in each zone, are framed together as one scaling group.*

**Text description**

**Nodes:**

- Availability zone: Zone a
  - Web 1, service
- Availability zone: Zone b
  - Web 2, service

**Overlays:**

- Scale group overlay: Web machines (At least 2), around Web 1, Web 2

**Connections:**

## See also

| Doc | Why |
|---|---|
| [Group types](https://docs.plotwork.dev/cloud-architecture/group-types.md) | The 30 types of group, each drawn |
| [Marks, second lines, and overlays](https://docs.plotwork.dev/cloud-architecture/marks-and-overlays.md) | The rules for `stack=`, `sub=`, and `overlay`, with the warning each can raise |
| [Writing diagrams](https://docs.plotwork.dev/writing-diagrams.md) | The whole language, kind by kind |
| [Language reference](https://docs.plotwork.dev/reference/language.md) | Every arrow, tone, option, and diagnostic code |
| [Cloud architecture](https://docs.plotwork.dev/cloud-architecture.md) | The recipe for a cloud diagram |