Colors

Overview

Block properties that accept colors — like mainLabelColor, iconColor, bgColor, outlineColor, favoriteColor — support three forms of value:

CSS Tokens

Token strings map to CSS custom properties defined by the theme. Use them when the color should follow the design system.

{
  id: "entityItem",
  block: "ListItemBlock",
  iconColor: "accent",
  mainLabelColor: "foreground",
  thumbColor: "transparent",
}

Common tokens:

Hex Literals

Any string starting with # is used as a raw CSS color value.

{
  id: "categoryItem",
  block: "ListItemBlock",
  iconColor: "#e11d48",
}

Template Colors

The most powerful form. A template string — any value wrapped in \{...\} — is resolved at render time against the current item's data, using the same dot-notation path system used for text labels.

// Color comes from the item's own "color.hex" field
iconColor: "{color.hex}"

// Color comes from the joined "collection" object's "color.hex" field
iconColor: "{collection.color.hex}"

If the resolved value is a hex string (starts with #), it is used directly. Otherwise it is treated as a CSS token.

Fallback

Use | to provide a fallback for when the path resolves to nothing:

// Uses color.hex if present, falls back to the "accent" token
iconColor: "{color.hex | accent}"

// Uses collection's color, falls back to "foreground"
iconColor: "{collection.color.hex | foreground}"

Without a fallback, a missing value renders no color (the property is ignored).

Practical Examples

Items colored by their cluster

Each entity belongs to a collection (cluster). If the collection data carries a color object with a hex field, every item can display in its cluster's color automatically:

{
  id: "entityListItem",
  block: "ListItemBlock",
  mainLabel: "{title}",
  extraLabel: "{collection.label}",
  mainLabelColor: "{collection.color.hex | accent}",
  iconColor: "{collection.color.hex | foreground}",
  favoriteColor: "{collection.color.hex | accent}",
  flagColor: "{collection.color.hex | accent}",
}

The | accent fallback ensures items without a cluster color still render correctly.

Cards with per-item accent colors

{
  id: "entityCard",
  block: "CardItemBlock",
  mainLabel: "{title}",
  extraLabel: "{collection.label}",
  extraLabelColor: "{collection.color.hex | accent}",
  outlineColor: "{collection.color.hex | panel}",
  favoriteColor: "{collection.color.hex | accent}",
  bgColor: "panel",
}

Items colored by their own data

If entities carry their own color.hex field directly:

{
  id: "trendTitle",
  block: "ItemTitleBlock",
  mainLabel: "{label}",
  mainLabelColor: "{color.hex | accent}",
}

Decorative elements

Templates work on layout blocks too:

{
  id: "dash",
  block: "DashBlock",
  color: "{collection.color.hex | accent}",
  size: "lg",
  align: "left",
}

How It Works

When a block renders an item, it has access to that item's resolved data (the entity record plus any joined objects). Color props are processed through the same template engine used for text — the \{path\} is resolved against the local data, and the result is interpreted as:

• A hex color if it starts with #
• A CSS variable (var(--<token>)) otherwise

This means a single block definition automatically applies the right color for every item in a list, without any per-item configuration.