Colors

Labels, statuses, and smart labels support configurable colors via the EntityColor type. Colors can reference the theme’s design system (auto-adapting to light/dark mode) or specify explicit custom values.

EntityColor Type

The color field in entity configs accepts two forms:

System Colors

Reference one of 5 design system colors by name. These map to CSS variables defined by your theme, so they automatically adapt to light and dark mode.

{
  "color": "accent"
}

Available system color names:

Name	Default Appearance	Semantic Usage
accent	Purple	Brand, primary actions, Execute mode
info	Amber	Warnings, attention, Ask mode
success	Green	Completion, connected, confirmed
destructive	Red	Errors, failures, delete actions
foreground	Text color	Neutral, muted states

System Colors with Opacity

Append /{opacity} to any system color name, where opacity is 0-100:

{
  "color": "foreground/50"
}

This renders as a semi-transparent version of the system color. Useful for muted or secondary states.

More examples:

• "accent/80" — 80% opacity accent
• "destructive/60" — 60% opacity red
• "foreground/30" — very subtle text color

Custom Colors

Specify explicit CSS color values with an object containing light and optionally dark:

{
  "color": {
    "light": "#EF4444",
    "dark": "#F87171"
  }
}

If dark is omitted, it’s auto-derived from light:

• Hex colors: Brightened by blending 30% toward white
• Other formats (OKLCH, RGB, HSL): Used as-is — specify dark explicitly for best results

{
  "color": {
    "light": "#3B82F6"
  }
}

Color Formats

Custom colors accept any valid CSS color format:

Format	Example
Hex	#8b5cf6, #8b5cf6cc (with alpha)
RGB	rgb(139, 92, 246)
HSL	hsl(262, 83%, 58%)
OKLCH	oklch(0.58 0.22 293)

Note

Recommendation: Use OKLCH for perceptually uniform colors. For simple cases, hex with auto-derived dark variant works well.

Where Colors Are Used

Labels

Labels render as colored circles. The color field controls the circle color:

{
  "id": "bug",
  "name": "Bug",
  "color": "destructive"
}

{
  "id": "feature",
  "name": "Feature",
  "color": {
    "light": "#8B5CF6",
    "dark": "#A78BFA"
  }
}

Labels without a color field render as a muted foreground circle.

Statuses

Statuses use color for their icon and visual indicators:

{
  "id": "in-progress",
  "label": "In Progress",
  "color": "success",
  "category": "open"
}

Default status colors (applied when no color is specified):

Status ID	Default Color	Appearance
backlog	foreground/50	Muted
todo	foreground/50	Muted
in-progress	success	Green
needs-review	info	Amber
done	accent	Purple
cancelled	foreground/50	Muted

Smart Labels

Smart labels support the color field:

{
  "id": "smart-error",
  "name": "ERROR",
  "color": "destructive",
  "expression": "hasError == true"
}

Theme Relationship

System colors (accent, info, success, destructive, foreground) reference the same CSS variables that your theme defines. This means:

• Entity colors automatically adapt when you change themes
• A status with "color": "accent" will be purple with the default theme, but blue if you override accent to blue
• Custom colors ({ light, dark }) are independent of the theme

OKLCH Reference

For custom colors using OKLCH format: oklch(lightness chroma hue)

Component	Range	Description
Lightness	0–1	0 = black, 1 = white
Chroma	0–0.4	0 = gray, higher = more saturated
Hue	0–360	Color wheel angle

Common hues:

• Red: ~25
• Orange: ~70
• Yellow: ~100
• Green: ~145
• Cyan: ~195
• Blue: ~250
• Purple: ~293
• Pink: ~330

Examples

Minimal — system color

{ "color": "success" }

Muted state

{ "color": "foreground/40" }

Brand color with explicit dark variant

{
  "color": {
    "light": "oklch(0.55 0.20 250)",
    "dark": "oklch(0.70 0.18 250)"
  }
}

Hex with auto-derived dark mode

{
  "color": {
    "light": "#059669"
  }
}

Tips

Start with system colors

System colors are the simplest option — they adapt to themes and modes automatically. Only use custom colors when you need a specific brand color or shade not covered by the 5 system colors.

Use opacity for hierarchy

foreground/50 and foreground/30 are useful for muted, secondary, or disabled states without introducing new colors.

Test in both modes

If using custom colors, always verify appearance in both light and dark mode. Specify explicit dark values for best results with non-hex formats.

Color not applying?

• Ensure the color field is at the top level of the entity config (not nested)
• System color names are case-sensitive: use "accent" not "Accent"
• Opacity must be 0–100 (not 0–1): use "foreground/50" not "foreground/0.5"
• Custom color objects require at minimum a light field