Skip to main content
Craft Agent features a powerful theme system built on a 6-color semantic palette that adapts to both light and dark modes. Themes control the appearance of the entire application, from backgrounds to UI components.

​
Architecture

The theme system uses a cascading configuration model where themes can be defined at the app level and customized per workspace.
Theme configuration is stored in ~/.craft-agent/theme.json for app-level customization.

​
6-Color Semantic System

Every theme is built around six core semantic colors that provide consistent meaning across the UI:

background

Main application background color

foreground

Primary text and content color

accent

Brand color (purple #8B5CF6) - used for Execute mode and primary actions

info

Amber color for Ask mode, warnings, and informational states

success

Green color for successful operations

destructive

Red color for errors and destructive actions

​
Color Formats

Craft Agent supports all modern CSS color formats: 
{
  "accent": "#8b5cf6",
  "background": "#faf9fb"
}
OKLCH is recommended for perceptually uniform color manipulation and better color mixing in CSS.

​
Surface Colors

In addition to semantic colors, themes can define surface colors for specific UI regions. All surface colors are optional and fall back to background if not specified:
​
paper
CSSColor
AI messages, cards, and elevated content backgrounds
​
navigator
CSSColor
Left sidebar background color
​
input
CSSColor
Input field background color
​
popover
CSSColor
Dropdowns, modals, and context menus (always solid, no transparency)
​
popoverSolid
CSSColor
Guaranteed 100% opaque popover background (required for scenic mode)

​
Dark Mode Support

Themes support optional dark mode overrides. When the system is in dark mode, colors from the dark object override the light mode values:
theme.json
{
  "background": "oklch(0.98 0.003 265)",
  "foreground": "oklch(0.185 0.01 270)",
  "accent": "oklch(0.58 0.22 293)",
  "dark": {
    "background": "oklch(0.145 0.015 270)",
    "foreground": "oklch(0.95 0.01 270)",
    "accent": "oklch(0.65 0.22 293)"
  }
}

​
Theme Modes

Craft Agent supports two visual modes:

​
Solid Mode (Default)

Traditional solid color backgrounds throughout the application.
theme.json
{
  "mode": "solid",
  "background": "oklch(0.98 0.003 265)"
}

​
Scenic Mode

Full-window background image with glass panel effects for UI elements.
theme.json
{
  "mode": "scenic",
  "backgroundImage": "https://example.com/background.jpg",
  "paper": "rgba(250, 249, 251, 0.8)",
  "popoverSolid": "#faf9fb"
}
When using scenic mode, ensure popoverSolid is defined as a fully opaque color for proper rendering of dropdowns and modals.

​
Storage Locations

Themes are stored in specific locations in the Craft Agent configuration directory:
LocationPurpose
~/.craft-agent/theme.jsonApp-level theme overrides
~/.craft-agent/themes/*.jsonPreset themes library

​
Default Theme

Craft Agent ships with a carefully designed default theme: 
const DEFAULT_THEME = {
  background: 'oklch(0.98 0.003 265)',
  foreground: 'oklch(0.185 0.01 270)',
  accent: 'oklch(0.58 0.22 293)',
  info: 'oklch(0.75 0.16 70)',
  success: 'oklch(0.55 0.17 145)',
  destructive: 'oklch(0.58 0.24 28)',
}

​
Next Steps

Customize Themes

Learn how to create and customize your own themes

Theme API

Explore the complete theme configuration API

Build docs developers (and LLMs) love

Get started for freeTalk to us