Notation and Visual Language
One of Farkitect’s core design principles is the separation of model semantics from visual representation. What something is (its type, properties, relationships) is separate from what it looks like on a diagram (its shape, colour, icon). The notation system bridges the two.
How Notation Works
Section titled “How Notation Works”Every M2 element type includes a notation definition that specifies:
| Property | What it controls | Example |
|---|---|---|
| Shape | The geometric form of the node | rectangle, rounded, pill, chamfered, chevron, ellipse, diamond |
| Colours | Fill, border, text and fold colours, each with a light and a dark value | Fill #81D4FA (light blue) in both themes |
| Icon | An SVG icon displayed on the node and in the Explorer | A user silhouette, a database cylinder |
| Default width/height | The initial size when placed on a diagram | 180 x 82 pixels |
| Stereotype | A label showing the type name (e.g., <<Application Component>>) |
Can be shown or hidden per diagram |
| Compartments | Sections within the node for name, properties, owned elements | Name compartment, properties compartment |
When you create an M1 instance of this type and place it on a diagram, Farkitect renders it using the M2 notation. A “Person” element appears as a rounded blue node with a user icon because the Person element type’s notation says so.
Shapes
Section titled “Shapes”Farkitect supports several node shapes:
| Shape | Appearance | Typical use |
|---|---|---|
| rectangle | Standard box with square corners | Most element types |
| rounded | Box with rounded corners | Active elements, processes |
| pill | Fully rounded ends | Tags, states |
| chamfered | Box with cut corners | Motivation elements, artifacts |
| chevron | Box with a point on the right | Process steps, value chains |
| ellipse | Ellipse or circle | Events, start and end nodes |
| diamond | Diamond | Gateways, decisions |
Other looks are combinations: a note is a rectangle with a folded corner, a boundary is a dashed border with no fill, and a text label has no border and no fill. See the Notation System Reference.
The shape is set at the M2 level. All instances of a type share the same shape.
Colours
Section titled “Colours”Each element type defines its colours in the M2 notation: fill, border, text and fold. This creates visual consistency — all Application Components are the same colour, all Business Processes are the same colour, making diagrams scannable at a glance.
Diagrams can be viewed in a light or a dark theme, so every colour has two values, one per theme. Most fills are light pastels that read well on both canvases and use the same colour for both. Borders and lines usually differ: a line that shows up on a white canvas can disappear on a near-black one. Any side can be left on Auto, which adapts by itself — borders and lines are charcoal in light mode and off-white in dark, text picks black or white to suit its fill, and a folded corner is a shade of the fill. See How colours work in light and dark mode.
Users can override colours on individual diagram nodes and edges in the Properties panel’s Appearance section (see How to change a node’s or edge’s appearance on one diagram). Overrides apply per element, per diagram — the same element can have different colours on different diagrams. The M2 colours remain the fallback.
Element types can include an SVG icon that appears:
- On the diagram node (typically in the top-left or as part of the notation)
- In the Explorer tree next to the element name
- In the Palette
Icons make element types immediately recognisable even before reading the name. Farkitect uses SVG markup so icons are crisp at any zoom level. Lucide is a good source of consistent, clean icons for custom metamodels.
Compartments
Section titled “Compartments”Compartments are sections within a node that display different kinds of content. A typical element node has:
- Name compartment — shows the element’s name, usually bold
- Properties compartment — shows property values (if configured)
- Subordinate compartments — shows owned elements (e.g., attributes inside an entity)
Compartments are defined in the M2 notation using a list of compartment definitions, each specifying:
- What content to display (name, properties, subordinates)
- Style overrides (font weight, alignment)
- Whether to show a label (e.g., “Attributes”)
Not all element types need compartments. A simple type might have just a name compartment. A complex type like an Entity in a data model might have name + attributes + operations.
Stereotypes
Section titled “Stereotypes”A stereotype is a label that shows the M2 type name on the diagram node — for example, <<Application Component>> or <<Business Process>>. Stereotypes help identify types when the shape and colour alone aren’t sufficient (especially on busy diagrams).
Stereotype visibility is a per-diagram toggle — you can show or hide stereotypes for the entire diagram using the diagram toolbar button. Some diagrams look cleaner without stereotypes; others need them for clarity.
Symbol Anatomy: Inside vs Outside Labels
Section titled “Symbol Anatomy: Inside vs Outside Labels”Different notations arrange the name and icon differently. Farkitect captures this with label placement, set per element type:
- Inside (the default, and the ArchiMate/UML convention) — the name sits inside the box, with a small type icon in the top-right corner.
- Outside (the BPMN convention for events, gateways, and data objects) — the icon is the symbol: it renders large and centred in the shape, and the name floats beneath the node as a separate label. That external label behaves like an edge label — you can drag it, resize it, and its position is remembered per diagram.
This is why a BPMN start event can be a plain circle with its name below it, while an ArchiMate component is a labelled box — same underlying model, different symbol anatomy.
Image and Link Bodies
Section titled “Image and Link Bodies”A node’s body doesn’t have to be its name. An element type can specify what fills the body:
- Name — the usual case.
- Notes — the element’s notes text, for annotation-style elements.
- Image — the element’s attached image becomes the body itself, letterboxed to fit. This is how the common Image element works.
Similarly, any property marked as a URL renders as a live, clickable link on the node — the mechanism behind the common Hyperlink element.
Showing and Hiding Labels
Section titled “Showing and Hiding Labels”Whether a type places its label inside or outside is an M2 (author) decision. Whether a particular label shows on a particular diagram is an M1 (per-diagram) decision. You can hide an individual node’s or edge’s label from its context menu, or hide all relationship labels on a diagram from the diagram toolbar. Hiding is treated as a content choice, so it survives “Revert Appearance to Default”.
Relationship Notation
Section titled “Relationship Notation”Relationship types also have notation definitions:
| Property | What it controls |
|---|---|
| Line pattern | solid, dashed, or dotted |
| Source marker / Target marker | none, arrow, triangle, diamond, circle or bar; triangle, diamond and circle can be filled or hollow |
| Line colour | A light and a dark value; Auto is charcoal in light mode, off-white in dark |
| Label colour | The name, role names and multiplicities, with a light and a dark value |
| Source-to-target verb | How to describe the relationship in the forward direction |
| Target-to-source verb | How to describe the relationship in the reverse direction |
| Show multiplicities | Whether to display source/target multiplicity labels |
| Show role names | Whether to display role name labels |
Why Separate Notation from Semantics?
Section titled “Why Separate Notation from Semantics?”This separation is what enables multi-notation support. The same underlying model concepts (types, properties, relationships) can be rendered with different visual rules depending on the metamodel. ArchiMate has its own colour scheme and shapes; UML has different ones; your custom metamodel has whatever you define.
It also means the model is portable. A .farki export captures both the model data and the notation definitions. When someone imports it, the visual rendering is reproduced exactly — because the notation rules travel with the model.
And it enables AI interaction. When an LLM reads a .farki file, it works with the semantic model (types, properties, relationships) without needing to understand visual rendering. The notation is metadata, not the model itself.