# Venn diagrams

> Page: https://docs.plotwork.dev/venn-diagrams. Index of every page: https://docs.plotwork.dev/llms.txt

A Venn diagram draws two to four sets as overlapping shapes, so the reader sees what each set holds alone and what the sets share. Use it for team ownership, feature coverage across products or plans, overlapping skills, or audiences that use more than one channel. It is for anyone who has to show where groups meet, and for an agent asked to compare a few groups by what they have in common.

## TL;DR

| Question | Answer |
|---|---|
| What is it for? | A few groups and what they share: who owns what, which plan has which feature, who uses which app. |
| How do I start one? | Write `venn "Title"`, a `set` line for each group, an `overlap` line for each overlap worth naming, and an `item` line for each member. |
| How is an item placed? | `item fe be "GraphQL schema"` puts it in the region of exactly the sets named: in Frontend and Backend, and in no other set. |
| How many sets? | One to four. Four are drawn as ellipses, the only arrangement where all fifteen overlaps show. |
| What if text does not fit? | A region too small for its text shows a numbered badge, and its items are listed beside the diagram under the same number. Nothing overflows. |
| What does Mermaid convert? | `venn-beta` and `venn`: sets, unions, `text` lines, and sizes. See [From Mermaid](#from-mermaid). |
| How big can it be? | At most 4 sets and 80 items. Warnings start past 6 items in one region and 24 in all. |
| How is it drawn? | Each set a soft wash of its tone with an outline, so overlaps read darker. The set names sit in tabs outside the shapes, and each region's name and items are centred in it. |

## Ask your agent

```text
Use Plotwork to draw a Venn diagram of who owns what between the Frontend, Backend and Platform teams. Name the overlap of Frontend and Backend "API contracts" and the overlap of all three "On-call", and put each piece of work in the region of the teams that share it.
```

```text
Use Plotwork to draw a Venn diagram, to scale, of the users of our web app and our mobile app: 900 on the web, 500 on mobile, and 200 who use both.
```

## Example

Three teams, the work each owns alone, the two overlaps that have a name, and the work they share. Each set has a tone and an icon; without them the sets take blue, violet, aqua and orange in turn.

**Diagram source**

```diagram
venn "Who owns what" desc="Three teams and the work they share. Frontend and Backend share the API contracts, and all three take part in on-call."
set fe "Frontend" tone=blue icon=lucide:monitor
set be "Backend" tone=violet icon=lucide:server
set ops "Platform" tone=aqua icon=lucide:cloud
overlap fe be "API contracts"
overlap fe be ops "On-call"
item fe "Design system"
item fe "Accessibility"
item be "Billing logic"
item fe be "GraphQL schema"
item be ops "Database migrations"
item ops "Terraform"
item ops "Observability"
```

*Picture: Venn diagram "Who owns what": 3 sets, 2 named overlaps and 7 items. Three teams and the work they share. Frontend and Backend share the API contracts, and all three take part in on-call.*

**Text description**

**Frontend. Only in it: Design system, Accessibility.**

**Backend. Only in it: Billing logic.**

**Platform. Only in it: Terraform, Observability.**

**Frontend and Backend "API contracts": GraphQL schema.**

**Backend and Platform: Database migrations.**

**Frontend, Backend and Platform "On-call".**

### Two sets to scale

With `sizes=on`, two sets are drawn to scale: each circle's area is its set's `size=`, and the overlap's area is the overlap's `size=`. The numbers are written in the tabs and the overlap.

**Diagram source**

```diagram
venn "Who uses which app" sizes=on desc="Monthly active users, in thousands, of the web app and the mobile app, drawn to scale. Most mobile users also use the web app."
set web "Web app" size=900 tone=blue icon=lucide:globe
set mobile "Mobile app" size=500 tone=green icon=lucide:smartphone
overlap web mobile "Both apps" size=200
item web "Admins"
item web "Report builders"
item mobile "Field staff"
item web mobile "Approvers"
```

*Picture: Venn diagram "Who uses which app": 2 sets, 1 named overlap and 4 items. Monthly active users, in thousands, of the web app and the mobile app, drawn to scale. Most mobile users also use the web app.*

**Text description**

**Web app (size 900). Only in it: Admins, Report builders.**

**Mobile app (size 500). Only in it: Field staff.**

**Web app and Mobile app "Both apps" (size 200): Approvers.**

### Four sets

Four sets are drawn as four tilted ellipses, so every combination has a region. The smallest regions are small, so name only the overlaps that matter; a region that cannot hold its text shows a number, and the key beside the shapes lists it.

**Diagram source**

```diagram
venn "Skills on the platform team" desc="Four skills and the engineers who hold each combination."
set dev "Development" icon=lucide:code
set ops "Operations" icon=lucide:server
set sec "Security" icon=lucide:shield
set data "Data" icon=lucide:database
overlap dev ops "DevOps"
overlap dev sec "AppSec"
overlap ops sec "SecOps"
overlap sec data "Governance"
overlap dev ops sec data "Unicorns"
item dev "Ana"
item ops "Bo"
item sec "Chen"
item data "Dara"
item dev ops "Eli"
item ops data "Fay"
item dev sec data "Gus"
item dev ops sec "Hana"
```

*Picture: Venn diagram "Skills on the platform team": 4 sets, 5 named overlaps and 8 items. Four skills and the engineers who hold each combination.*

**Text description**

**Development. Only in it: Ana.**

**Operations. Only in it: Bo.**

**Security. Only in it: Chen.**

**Data. Only in it: Dara.**

**Development and Operations "DevOps": Eli.**

**Development and Security "AppSec".**

**Operations and Security "SecOps".**

**Operations and Data: Fay.**

**Security and Data "Governance".**

**Development, Operations and Security: Hana.**

**Development, Security and Data: Gus.**

**Development, Operations, Security and Data "Unicorns".**

## The language

One statement to a line. Text is always in double quotes, options are `key=value`, and `#` starts a comment.

### The header

`venn "Title" sizes=off desc="<text>"`. The title, `sizes=` and `desc=` are optional. `sizes=on` draws two sets to scale; with `sizes=off`, the default, the shapes are equal and any sizes are written as numbers.

### Statements

| Statement | Meaning | Example |
|---|---|---|
| `set <id> "<Label>" size=<n> tone=<tone> icon=<icon>` | A set. The label defaults to the id. | `set fe "Frontend" tone=blue icon=lucide:monitor` |
| `overlap <id> <id> "<Name>" size=<n>` | Names the region where two or more sets overlap. | `overlap fe be "API contracts"` |
| `item <id> "<Text>"` | A member of the region of exactly the sets named. | `item fe be "GraphQL schema"` |
| `desc "<text>"` | The plain-language description, the same as `desc=` on the header. | `desc "Three teams and the work they share."` |

### Sets

A set has an id, which overlaps and items name, and a label, which is drawn in a tab outside its shape. Give it a `tone=` for what it means and an `icon=` when a glyph helps; the tab shows the icon, the label and the size. One set is a circle, two are side by side, three sit on a triangle, and four are tilted ellipses. A fifth set is refused, because five shapes cannot show every overlap in a way a reader can follow: use a [matrix](https://docs.plotwork.dev/matrices.md) instead.

### Overlaps and items

An `overlap` names a region of two or more sets, and its name is drawn in that region. The order of the ids does not matter, and each region is named once. An `item` lives in the region of exactly the sets it names: `item fe "Design system"` is in Frontend and no other set, and `item fe be ops "Incident drills"` is in all three. An overlap or item may name a set declared further down.

Each region's text is centred in it and kept 8px from every outline. When a region cannot hold its items, its name stays if it fits, a numbered badge marks the region, and the items are listed in a key beside the shapes under that number. The key keeps the full text.

### Sizes

`size=` on a set or an overlap is a plain number, such as `30` or `2.5`. With `sizes=off` the number is written in the set's tab and under the overlap's name. With `sizes=on` and two sets that both have a size, the circles are drawn to scale; an overlap of `size=0` parts them, and its items go to the key. Three or four sets cannot be drawn to scale with circles, so they stay equal and lint says so. A set far smaller than the other is drawn at a third of the larger radius so its text has room, and lint says that too.

## Limits and warnings

| Limit | Value | What happens past it |
|---|---|---|
| Sets | 4 | `E140` at the fifth set, with the advice to use a matrix. |
| Items | 80 | `E140` before any layout. |
| Items in one region before the warning | 6 | `W200`, at the first item. |
| Items in all before the warning | 24 | `W200`. |
| Region text | 150px, then 112px, then 80px wide; 3 lines an item, 2 a name | Text that does not fit at any width goes to the key, with `W200`. |
| Set label | 240px | Cut with an ellipsis past that, with `W203`. |

Every mistake comes back as a result with a code, a line, a column, and a hint. Warnings never stop the drawing.

| Code | When it fires | Fix |
|---|---|---|
| `E100` | A set with no id, an overlap of fewer than two sets, an item in no set, a set named twice on one line, text with nothing in it, or a diagram with no sets. | Read the hint, which gives the form to write. |
| `E130` | A set id used twice, or a region named twice. | Give each set its own id, and name each region once. |
| `E131` | An overlap or item names an id no set has. | Use one of the ids the hint lists. |
| `E136` | A `size=` that is not a plain number, or a `sizes=` that is neither on nor off. | Write `size=30`, and `sizes=on` or `sizes=off`. |
| `E140` | More than 4 sets or 80 items. | Use a matrix, or keep the items that make the point. |
| `E110`, `E121`, `E135`, `W208` | The shared codes: an unknown statement (a line of Mermaid names the converter), an unknown tone, an unknown option, and an unknown icon. | Read the hint. |
| `W200` | A crowded region or diagram, a region listed in the key, an overlap larger than one of its sets, or what `sizes=on` could not draw to scale. | Shorten or move items, check the numbers, or use two sets. |
| `W202` | The picture is wider than a Markdown column and its text would shrink. | Shorten the items, or move the longest to the text around the diagram. |
| `W203` | Text was cut with an ellipsis: a set label past 240px, or one long word past 220px. | Shorten it. The outline keeps the full text. |

## From Mermaid

Mermaid's Venn diagram (`venn-beta`, and `venn`) converts to a Venn diagram. Ask your agent to convert it, or use the `convert_mermaid` tool. The [migration guide](https://docs.plotwork.dev/migrating-from-mermaid.md) covers the converter in full.

```mermaid-source
venn-beta
  title Team overlap
  set A["Frontend"]
    text A1["React"]
    text A2["Design Systems"]
  set B["Backend"]
    text B1["API"]
  union A,B["Shared"]
    text AB1["OpenAPI"]
```

It becomes:

```plotwork
venn "Team overlap"

set A "Frontend"
set B "Backend"

overlap A B "Shared"

item A "React"
item A "Design Systems"
item B "API"
item A B "OpenAPI"
```

| Mermaid | Plotwork | Reported |
|---|---|---|
| `venn-beta`, `venn` | `venn "<title>"` | |
| `set A["Label"]:30` | `set A "Label" size=30` | |
| `set "Foo Bar"` | `set foo_bar "Foo Bar"`, an id made from the name | `M206` |
| `union A,B["Label"]:8` | `overlap A B "Label" size=8` | |
| `union A,B` with no name | its `text` lines become `item A B` lines, and its size is dropped | `M203` for the size |
| `text T["Label"]` under a set or union | `item A "Label"`, or `item A B "Label"` | |
| Two sets that both have a size | `sizes=on`, since Mermaid draws sizes to scale | |
| `style A fill:...` | the nearest tone; anything else the line sets is dropped | `M204`, `M200` |
| `style` on a union or a text line | dropped | `M200` |
| A union of a set no line declares | dropped | `M203` |
| More than four sets | refused | `M102` |

A `text` line belongs to the latest set or union above it. Then give each set a tone and an icon, and name the overlaps that mean something.

## See also

| Doc | Why |
|---|---|
| [Writing diagrams](https://docs.plotwork.dev/writing-diagrams.md) | The flow, sequence and schema languages, and the rules every kind shares |
| [Matrices](https://docs.plotwork.dev/matrices.md) | More than four groups, or many items, as rows and columns |
| [Quadrant charts](https://docs.plotwork.dev/quadrant-charts.md) | Place items on two scales instead of in groups |
| [Migrating from Mermaid](https://docs.plotwork.dev/migrating-from-mermaid.md) | Convert existing Mermaid diagrams, and what is dropped |
| [Language reference](https://docs.plotwork.dev/reference/language.md) | Every kind, node type, option and diagnostic |
| [Diagram kinds](https://docs.plotwork.dev/reference/language/kinds.md) | The kinds Plotwork draws and the header of each |