Diagrams

Explaining the invisible

Our products are systems: desks, servers, models, agents and people, connected by rules about where data may go. Diagrams make those systems visible. They should be as calm and precise as the products.

Every North diagram, in a slide, a proposal, product documentation or a whiteboard export, uses the same small set of shapes, lines and colours. A reader who has seen one North diagram can read them all.

One message per diagram. Write the takeaway as the title. If you need two messages, draw two diagrams.
Flow in reading direction. Left to right (right to left in Arabic), or top to bottom. Never in all directions at once.
Twelve nodes at most. Group, or split into an overview and a detail.
Shapes mean things. A shape or colour is only used for its defined meaning, and every diagram with more than three element types carries a legend.
No decoration. No shadows, gradients, 3D, clip art or tilted perspective.

Elements

Ten node types cover almost everything. Shape tells the reader what something is; the accent tells them who acts.

Element	Shape	Use for
Service / step	Rectangle, 8px radius, white fill, 1.5px Midnight 60 border	Systems, services, components, process steps
External system	Rectangle, Dune 05 fill	Anything we don't own: customer systems, third-party services, cloud providers
Person / role	Pill, Dune 05 fill, person icon	Users, operators, analysts, organisations
Data store	Cylinder	Databases, file stores, knowledge indexes, archives
AI agent / model	Rectangle with a 3px Oasis 70 accent bar on the leading edge	Agents, models, anything where AI acts
Human approval	Rectangle with a 3px Dawn 60 accent bar	A step where a named person reviews, approves or decides
Decision	Diamond, label as a question	Branches in a flow. Label outgoing lines Yes / No
Start / end	Pill filled Midnight 90, white text	The single entry and exit of a flowchart
Instances	Up to three offset rectangles (6px)	Many of the same thing: desks, lens agents, replicas. Put the count in the subtitle: “× 6”
Note	Dune 10 shape with a folded corner, caption text	Context that is not part of the flow

Connectors

Lines carry meaning

Orthogonal routing only: horizontal and vertical segments with 8px rounded elbows. No diagonals, no curves.
Arrowheads: one filled 8px head at the receiving end. Two heads only for genuinely two-way exchanges; never on both ends “to be safe”.
Connect to the middle of a side. When two lines meet one side, offset them by 16–20px.
Avoid crossings. Move nodes first; if a crossing is unavoidable, let the less important line pass behind.
Labels: 12px caption colour, sentence case, on the line with a canvas-coloured halo. Use verbs or protocols: “Signs in”, “HTTPS”, “Every 15 min”.

Line	Means
Solid 1.5px	Request, call or data flow
Solid 2.5px Midnight 90	The primary path, the one to remember
Solid 2.5px Gulf 70	A highlighted flow (one per diagram)
Dashed 6 4	Asynchronous, optional or conditional
Dotted 1.5 4	Dependency, reference, configuration
Solid Oasis 70	An action taken by AI

Containers

Zones, groups and outlines

Zone: a trust or residency boundary, such as on-premises, a customer network or a classified enclave. Oasis 05 fill, Oasis 70 dashed border, 24px radius.
Group: things that belong together but share no boundary, such as modules or a team. Dune 10 fill, no border, 16px radius.
Outline: a set of external or optional things, such as approved cloud providers. No fill, dashed Midnight 60 border, 16px radius.
Label containers top left in 12px bold capitals (the microtitle style), 16px from the edges.
Nest at most two levels deep. Leave 24px between a container edge and the nodes inside it.

Colour in diagrams

Diagrams are mostly Midnight, white and Dune. Colour appears only with these four meanings, so readers learn them once:

Colour	Meaning	Token
Oasis	AI acts here: agent and model accents, AI connectors	`--n-diagram-ai`
Dawn	A person decides here: approval and review steps	`--n-diagram-human`
Gulf	The highlighted flow you want the reader to follow	`--n-diagram-flow`
Oasis zone	A trust or residency boundary	`--n-diagram-zone`

Status colours (red, amber, green) are only for state: a failed check, a blocked path. Always with a label. Every role has a light and a dark value; see the token list below.

Text, icons and logos

Node titles: Helvetica Now Text Medium 14px. Subtitles and captions: Text Regular 12px in the caption colour. One line each; two lines at most.
Use exact product names: “NorthStar Admiral Server”, never “Admiral srv” or “NS”.
Icons: one 20px icon from the North library per node, on the leading edge. Icons support the label; they never replace it.
Third-party logos: only inside external-system nodes, 20px high, one-colour Midnight (Snow on dark) unless the owner requires full colour. Never stretch or recolour them.
North logos don't go inside diagrams. Our products are named in text; the slide or page already carries the logo.
Numbered steps: 20px Midnight circles with white numbers, only when the order really matters.

Flowcharts

A flowchart has one start, one end, questions in diamonds and labelled branches. Loops return along the top or bottom, dashed when they are the exception.

Sequence diagrams with Mermaid

Diagrams as code

For documentation, write diagrams as code with Mermaid and the North theme. They version with the docs, render in the NorthStar Help Center (Docusaurus) and stay on brand automatically.

This diagram is rendered live with the theme below, and follows the hub's light or dark mode.

sequenceDiagram
  autonumber
  participant D as NorthStar Desktop
  participant A as NorthStar Admiral Server
  participant M as On-premises model
  D->>A: Sign in (Admiral URL, username, password)
  A-->>D: Session and signed licence
  loop Every 15 minutes
    D->>A: Licence check
    A-->>D: Valid
  end
  D->>A: Model request + gateway key
  A->>M: Forward (residency: on-premises only)
  M-->>A: Completion
  A-->>D: Response

%%{init: {"theme":"base","themeVariables":{"fontFamily":"\"Helvetica Now Text\", Helvetica, Arial, sans-serif","fontSize":"14px","background":"#FFFFFF","primaryColor":"#FFFFFF","primaryBorderColor":"#3D4870","primaryTextColor":"#1B223D","secondaryColor":"#FFF9F3","secondaryBorderColor":"#3D4870","secondaryTextColor":"#1B223D","tertiaryColor":"#FAF2E8","tertiaryBorderColor":"#3D4870","tertiaryTextColor":"#1B223D","lineColor":"#3D4870","textColor":"#1B223D","mainBkg":"#FFFFFF","nodeBorder":"#3D4870","clusterBkg":"#F0FDFD","clusterBorder":"#1A98B3","titleColor":"#1B223D","edgeLabelBackground":"#FFFFFF","noteBkgColor":"#FAF2E8","noteBorderColor":"#FAF2E8","noteTextColor":"#1B223D","actorBkg":"#FFF9F3","actorBorder":"#3D4870","actorTextColor":"#1B223D","actorLineColor":"#3D4870","signalColor":"#1B223D","signalTextColor":"#1B223D","labelBoxBkgColor":"#FAF2E8","labelBoxBorderColor":"#3D4870","labelTextColor":"#1B223D","loopTextColor":"#58628A","activationBkgColor":"#F0FDFD","activationBorderColor":"#1A98B3","sequenceNumberColor":"#FFFFFF"},"themeCSS":".node rect, .node .label-container { rx: 8px; ry: 8px; } .cluster rect { rx: 16px; ry: 16px; stroke-dasharray: 6 4; stroke-width: 1.5px; } .edgePath .path, .flowchart-link { stroke-width: 1.5px; } .edgeLabel { font-size: 12px; } .node .label { font-weight: 500; }"} }%%
flowchart LR
  start([Start]) --> plan[Plan]
  plan --> ok{Approved?}
  ok -- Yes --> spec[[Specialists run]]
  ok -. No .-> plan
  spec --> val[Validate] --> rev[Human review] --> done([Deliver])
  subgraph perimeter [On-premises]
    val
    rev
  end

In Docusaurus, set the theme once in docusaurus.config.ts instead of in every diagram:

themeConfig: {
  mermaid: {
    theme: { light: 'base', dark: 'base' },
    options: {
      "themeVariables": {
        "fontFamily": "\"Helvetica Now Text\", Helvetica, Arial, sans-serif",
        "fontSize": "14px",
        "background": "#FFFFFF",
        "primaryColor": "#FFFFFF",
        "primaryBorderColor": "#3D4870",
        "primaryTextColor": "#1B223D",
        "secondaryColor": "#FFF9F3",
        "secondaryBorderColor": "#3D4870",
        "secondaryTextColor": "#1B223D",
        "tertiaryColor": "#FAF2E8",
        "tertiaryBorderColor": "#3D4870",
        "tertiaryTextColor": "#1B223D",
        "lineColor": "#3D4870",
        "textColor": "#1B223D",
        "mainBkg": "#FFFFFF",
        "nodeBorder": "#3D4870",
        "clusterBkg": "#F0FDFD",
        "clusterBorder": "#1A98B3",
        "titleColor": "#1B223D",
        "edgeLabelBackground": "#FFFFFF",
        "noteBkgColor": "#FAF2E8",
        "noteBorderColor": "#FAF2E8",
        "noteTextColor": "#1B223D",
        "actorBkg": "#FFF9F3",
        "actorBorder": "#3D4870",
        "actorTextColor": "#1B223D",
        "actorLineColor": "#3D4870",
        "signalColor": "#1B223D",
        "signalTextColor": "#1B223D",
        "labelBoxBkgColor": "#FAF2E8",
        "labelBoxBorderColor": "#3D4870",
        "labelTextColor": "#1B223D",
        "loopTextColor": "#58628A",
        "activationBkgColor": "#F0FDFD",
        "activationBorderColor": "#1A98B3",
        "sequenceNumberColor": "#FFFFFF"
      },
      "themeCSS": ".node rect, .node .label-container { rx: 8px; ry: 8px; } .cluster rect { rx: 16px; ry: 16px; stroke-dasharray: 6 4; stroke-width: 1.5px; } .edgePath .path, .flowchart-link { stroke-width: 1.5px; } .edgeLabel { font-size: 12px; } .node .label { font-weight: 500; }"
    },
  },
},

Tools and downloads

Tool	What to use	File
diagrams.net (draw.io)	North shape library: every node, container and connector, styled. File → Open library from → Device.	north-diagrams.drawio.xml
Mermaid	Theme variables and CSS for light and dark.	north-mermaid-theme.json
Slides, Figma, Illustrator	Reference diagrams as SVG to copy from, in light and dark.	Elements · Architecture · Flowchart
Code and agents	Diagram tokens (below) and the `diagram-*` colour roles in the token files.	north-tokens.css

draw.io library Mermaid theme

Diagram tokens

Token	Value	Use
`--n-diagram-grid`	8px	Snap every node and connector to an 8px grid.
`--n-diagram-stroke`	1.5px	Node borders and connectors.
`--n-diagram-stroke-strong`	2.5px	Primary path and emphasised connectors.
`--n-diagram-node-radius`	8px	Nodes (boxes).
`--n-diagram-group-radius`	16px	Group containers.
`--n-diagram-zone-radius`	24px	Zones and trust boundaries.
`--n-diagram-node-min-width`	144px	Minimum node width.
`--n-diagram-node-height`	56px	Default single-line node height (two lines: 72px).
`--n-diagram-node-padding`	12px 16px	Inner padding of a node.
`--n-diagram-gap`	48px	Minimum gap between nodes along a flow.
`--n-diagram-dash`	6 4	Dashed line pattern (async, optional, boundaries).
`--n-diagram-dot`	1.5 4	Dotted line pattern (dependency, reference).
`--n-diagram-arrow-size`	8px	Arrowhead length.
`--n-diagram-label-size`	14px	Node title (Helvetica Now Text Medium).
`--n-diagram-caption-size`	12px	Edge labels and captions (Helvetica Now Text Regular).
`--n-diagram-icon-size`	20px	Icon inside a node.

Dos and don'ts

Do

State the takeaway in the title.
Use the ten element types and their meanings.
Route lines orthogonally with labelled connectors.
Show trust boundaries as zones.
Add a legend when there are more than three element types.

Don't

Colour nodes by taste or by team.
Use shadows, gradients, 3D or isometric clip art.
Draw diagonal or curved spaghetti lines.
Cram more than 12 nodes into one view.
Put North logos or decorative icons inside nodes.

Don't colour nodes for decoration

Don't draw diagonal spaghetti

Don't add shadows and 3D

Last updated on 14 October 2026