Skip to content

Labels in depth

A card’s labels are a list under labels in its frontmatter, drawn as chips on the card. Every label belongs to a kind. A board defines its own kinds in config.labels, and text is the one built-in kind, used for free labels (a plain tag such as bug). Priority and component are not special: they are ordinary kinds that a board defines like any other.

This page covers the whole story: the label on a card, the kind stamped inside it, the kind definition on the board, and how to write one by hand. For the card file as a whole see Card, for lane settings see Lane, and for the board’s config.labels see Configuration.

One entry in a card’s labels list.

KeyTypeDescription
text text The label's identity within its kind, compared case-insensitively; the spelling you write is the one shown. An entry with no readable text is not a label.
rank integer A whole number that a ranked kind sorts and groups by; a lower rank is a higher priority. Leave it out for a value of an open kind.
color text The value's own colour, as a palette name or #RRGGBB[AA] hex. Write the value's colour if its definition has one, otherwise the kind's.
icon icon The value's own glyph and color mapping. A value never inherits its kind's glyph, so leave icon out if the definition gives the value none.
kind label kind The kind this label belongs to, written out in full inline. Every entry in a card's labels list carries one, including free labels (kind text).

Each entry carries its full value: its own rank, color and icon, and its whole kind. Nothing that draws, sorts, filters or groups a card looks anything up in the board’s configuration. This is deliberate. A card file copied to another board keeps its meaning even if that board has no matching kind defined.

The order of keys is text, rank, color, icon, kind. A free label on a board that configures nothing looks like this:

labels:
- text: bug
kind:
type: text
text: Text
icon:
glyph: tag

Two entries are the same label when their kind and their text match case-insensitively, so a card carries Bug or bug, never both. If a card has no labels left, remove the labels key rather than writing an empty list.

The kind object stamped inside each label.

KeyTypeDescription
type text The kind's identity: kebab-case, matched case-insensitively. text is the built-in kind for free labels.
text text The kind's display name. If you leave it out, the type is shown instead.
color text The kind's own colour, as a palette name or #RRGGBB[AA] hex. It is separate from the colour of any value.
icon icon The kind's own glyph and color mapping. In compact presentation it stands in for the kind's name.

The kind is repeated in full on every entry of that kind. The repetition is what lets each entry be read, and removed, on its own.

An entry in the board’s config.labels list.

KeyTypeDescription
type text The kind's identity: kebab-case, matched case-insensitively. Labels on cards refer to the kind by this name.
text text The kind's display name. Optional.
color text The kind's own colour, as a palette name or #RRGGBB[AA] hex. A value without a colour of its own takes this one when it is stamped.
icon icon The kind's own glyph and color mapping.
single boolean Set to true (a YAML boolean, not a quoted word) so that a card carries at most one value of this kind. It constrains whoever writes labels, not how existing cards are read.
values list of labels The list of allowed values, each with its own text, rank, color and icon. Leaving values out makes the kind open (free text); including it, even empty, makes the kind closed to exactly the values listed.

A definition is a palette for writers. It is what an editor picks from and then stamps, in full, onto a card. It is never consulted when a card is displayed. Changing a definition changes what is written from then on and leaves every card already written exactly as it was. To bring existing cards forward, edit their files.

The effective set of kinds on a board is its own config.labels plus the built-in text kind. You can recolour text or give it another icon or name by listing it in config.labels, but you cannot remove it.

Open and closed kinds. A definition with no values key is open: any text is a valid value. A definition with a values key, even an empty list, is closed: its values are exactly the ones listed, and each one stamps its rank onto the card.

Rank. rank is the number a ranked kind sorts by, and the exact key sections are grouped on. A lower rank is a higher priority. Values of an open kind have no rank.

Single. single: true means a card carries at most one value of the kind. It constrains whoever writes labels: a picker in the app replaces the value instead of adding another. It does not stop a hand-edited card from holding several, and a card that has several draws all of them. Where a kind groups or filters by a single value, the lowest rank is used.

A full config.labels with a priority kind, a component kind and one custom kind:

labels:
- type: priority
text: Priority
icon:
glyph: flag
single: true
values:
- text: Urgent
rank: 0
color: "#C8283C"
icon:
glyph: exclamationmark.2
- text: High
rank: 1
color: "#E07A1F"
icon:
glyph: exclamationmark
- text: Medium
rank: 2
- text: Low
rank: 3
icon:
glyph: arrow.down
- type: component
text: Component
color: aluminum
icon:
glyph: puzzlepiece
single: true
- type: status
text: Status
single: true
values:
- text: Open
rank: 1
color: fern
- text: Closed
rank: 2

Here priority and status are closed kinds, while component is open: any component name is valid and it has no ranks.

A card’s priority and component are entries in its labels list, of kind priority and kind component. They are never keys at the root of the card. Do not write priority: or component: at the top level of a card file.

A priority entry stamps its value in full:

labels:
- text: High
rank: 1
color: "#E07A1F"
icon:
glyph: exclamationmark
kind:
type: priority
text: Priority
icon:
glyph: flag

Rank is what makes priority work. Lanes grouped by priority section on the exact rank, with every rank 1 card in the top section, rank 2 next, and each section named after the text of its first card. A lower rank is a higher priority, which is why Urgent sits at 0 in the suggested scale. Nothing looks the scale up, so a priority scale the board has never defined sorts and groups just the same. A board changes its scale by editing the priority kind in config.labels, which affects only what is written afterwards.

How the app shows them: a priority with a stamped color draws as a tinted capsule (in the suggested scale, Urgent and High); one without a colour draws as a bare mark with its own glyph (Low’s arrow); the suggested Medium draws nothing on the card face. In a lane grouped by priority the chip is hidden, since the section heading already says it.

A component is the same idea for the other kind. The suggested component kind is open, so its values carry their own text, the kind’s colour and no rank. If a board gives component a values list, it becomes closed and its values stamp a rank like priority’s. Components always draw untinted, whatever color they carry. In a lane grouped by component the chip is hidden.

For grouping by priority, component or any other kind, and for filtering on them, see Grouping and filtering.

A lane can give new cards labels to start with, in its card-defaults.labels:

card-defaults:
labels:
- feature-idea
- text: Idea
kind:
type: type
text: Type

Each item is either a bare name, which is a free label (the normal way to write one), or a full label entry of one of the board’s kinds. When the app creates a card in the lane it adds these labels. A kinded entry is re-stamped against the board’s current definition of its kind, and for a single kind only one value is kept.

The defaults are applied once, when the card is created. They are never applied when a card is moved, pasted or duplicated, and editing the lane’s defaults later does not reach back into cards that already exist.

The app applies them only to cards it creates. If you write a card file by hand, add the lane’s default labels to its labels yourself, alongside whatever else you write, without duplicates (compared case-insensitively). Write a bare name as a free label, and a kinded entry with the board’s current stamps for its value. If your card names its own value of a single kind, yours wins and the lane’s default of that kind is left out.

See Lane for the lane file.

Say you want to mark a card as High priority on a board whose config.labels is the example above.

  1. Find the kind in the board’s config.labels. Here it is the entry with type: priority.
  2. Find the value you want in that kind’s values: High.
  3. Copy the value’s rank (1), color ("#E07A1F") and icon (glyph: exclamationmark). If the value has no colour of its own, use the kind’s colour. If it has no icon, write none: a value never takes its kind’s glyph.
  4. Stamp the kind: copy the kind’s type, text and icon (and its color, if it has one) into a kind mapping on the entry.
  5. Add the entry to the card’s labels, in the key order text, rank, color, icon, kind.

The card’s frontmatter then reads:

labels:
- text: High
rank: 1
color: "#E07A1F"
icon:
glyph: exclamationmark
kind:
type: priority
text: Priority
icon:
glyph: flag

A value of the open component kind needs no rank, and takes the kind’s colour:

labels:
- text: Sync
color: aluminum
kind:
type: component
text: Component
color: aluminum
icon:
glyph: puzzlepiece