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 toolbar button. Some diagrams look cleaner without stereotypes; others need them for clarity.
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.