Map traits
Every map type in CardBoard is described by the same four characteristics — its traits. The traits are the input: pick values for the four, and you’ve described a map. The map types are the output: the named canvases you choose in the new-board modal. This is the layer that makes a map typed — it’s why an agent knows where a card is allowed to go, and why importing a Mermaid diagram restructures into a real map instead of a loose sketch.
The four traits
Section titled “The four traits”A trait is an observable characteristic of how a map carries meaning. Each takes a categorical value (a particular kind of grid, not “more or less grid”).
- Component — Does what a card looks like tell you what kind of thing it is? (shape, color, icon)
- Connection — Do the lines between cards carry meaning? (presence, direction, type)
- Position — Does where a card sits mean something, and in what coordinate system?
- Landscape — How many of the surface’s axes are forced into a shared frame: none, one, or both?
Why exactly these four
Section titled “Why exactly these four”The traits aren’t a flat list someone chose. They fall out of two orthogonal binary cuts:
- What is being structured: the Things (the nodes) vs. the Space (the field they sit in).
- What kind of meaning it carries: Intrinsic (exists alone) vs. Relational (needs another node or frame to mean anything).
| Intrinsic | Relational | |
|---|---|---|
| Things | Component — a node’s own attributes | Connection — a node’s links to other nodes |
| Space | Landscape — the surface’s alignment discipline | Position — a node’s coordinates within a frame |
Diagnostic for intrinsic vs. relational: can it exist with a single node and no other context? A red card is red alone (Component, intrinsic). A blank grid is still a grid (Landscape, intrinsic). A connection needs a second node (Connection, relational). A position needs a coordinate system (Position, relational).
There are exactly four because the two cuts are exhaustive, and every map engages all four — map types differ only in which values they take.
The Landscape values
Section titled “The Landscape values”Landscape — how many axes are forced onto a globally-shared frame — has exactly three values:
| Value | Axes forced | Means |
|---|---|---|
| freeform | zero | No snap. A card rests where it’s put. |
| lines | one | Every card shares a row or a column with its peers; the cross-axis is free. |
| grid | two | Shared rows and columns — a chessboard. |
The load-bearing word is globally-shared: a frame the whole map references, not a card-local convenience. Local nearest-neighbor snapping is not a weak grid — it’s not a Landscape value at all.
How the surface is drawn — blank / dotted / ruled / squared — is a cosmetic skin, not a trait.
From traits to map types
Section titled “From traits to map types”A map type is a set of trait values plus a set of labels. A story map and a swimlane kanban share the same trait profile — cards in lanes — and differ only in what the lanes are called. A Wardley map and a story map look like the same 2D layout but differ in one trait: a story map buckets (position is membership in a cell), while a Wardley map plots (position is a coordinate, so distance is meaningful).
Because the traits are the contract, the rest follows:
- Why maps are typed. A typed map declares, through its trait values, what placements are legal.
- Why an agent knows where to put a card. It reads the map’s traits and proposes against them — a cell where position is membership, coordinates where position is a plot, no constraint where the surface is freeform and connectors carry the meaning.
- Why Mermaid conversion restructures. The target trait profile is known, so an imported diagram is walked against the four traits and laid out as a real map.
- Why new map types are cheap. Most reuse an existing trait profile — relabel and ship.
To see the named canvases these traits produce, read Map types.