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, note, boundary, text |
| Colour | The default fill colour | #81D4FA (light blue) |
| 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 | 160 x 80 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 |
| note | Box with a folded corner | Notes and annotations |
| boundary | Dashed-border region | Grouping and containment |
| text | No background or border, just text | Labels and headings |
The shape is set at the M2 level. All instances of a type share the same shape.
Colours
Section titled “Colours”Each element type has a default colour defined in the M2 notation. This creates visual consistency — all Application Components are the same colour, all Business Processes are the same colour, making diagrams scannable at a glance.
Users can override colours on individual diagram nodes (see How to format nodes and edges). Overrides apply per-element, per-diagram — the same element can have different colours on different diagrams. The M2 default remains 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 Format to Default”.
Relationship Notation
Section titled “Relationship Notation”Relationship types also have notation definitions:
| Property | What it controls |
|---|---|
| Line style | solid, dashed, or dotted |
| Source marker | none, arrow, hollowArrow |
| Target marker | none, arrow, hollowArrow |
| Colour | Edge line colour |
| 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.