ARCANA
Back to Blog

Customization

Theming Arcana: 10 Built-In Themes and Custom Token Configuration

Jul 25, 2026 Customization

Arcana's TUI is not just functional, it is personal. The v0.4.0 release shipped 10 built-in themes and a custom theme system that gives you control over every color in the interface.

You spend hours looking at your terminal. The colors, the contrast, the overall feel of the interface directly affect how long you can work comfortably and how quickly you can parse information. Arcana treats theming as a first-class feature, not an afterthought.

The theme system is built on a token architecture. Every visual element in the TUI, from the spine background to the code block border, maps to a named token. Themes define values for these tokens. When you switch themes, the entire interface updates atomically. There is no partial state, no flickering, no elements stuck in the old theme.

Built-In Themes

List available themes with:

arcana theme list

The built-in themes range from dark minimal to high-contrast accessible. Each theme defines colors for the spine, input area, tool output, code blocks, diff views, and status indicators.

Switching Themes

# Switch immediately
arcana theme set --name dracula

# Preview current theme
arcana theme list

Custom Themes

Create a custom theme by copying an existing one and editing the token file:

# Create a custom theme (copy from an existing one)
# Themes are stored in ~/.arcana/themes/ on Linux/macOS
# or %USERPROFILE%\.arcana\themes\ on Windows
# Copy a built-in theme JSON and modify it

Custom themes support approximately 75 tokens covering every visual element in the TUI. The token file is plain JSON, making it easy to version control and share.

Contrast Floor

Arcana enforces a minimum contrast ratio for text elements. If your custom theme has insufficient contrast between text and background, the theme system warns you on load. This prevents you from accidentally creating an unreadable interface.

The contrast check follows WCAG AA guidelines: 4.5:1 for normal text, 3:1 for large text. You can override this with "contrastCheck": false in your theme file, but the system will warn you.

Theme Tokens

The key token categories, with examples of what each controls:

  • bg, bg2, bg3: Background layers. bg is the main terminal background. bg2 is for panels and sidebars. bg3 is for elevated elements like popups.
  • text, textMuted, textDim: Text hierarchy. text is primary content. textMuted is secondary information. textDim is for hints and placeholders.
  • accent, accentDim: Primary accent colors. Used for active states, selection highlights, and interactive elements.
  • success, warning, error: Status colors. These power the file-edit guard, approval prompts, and error messages.
  • border, borderDim: Structural borders. border is for active elements. borderDim is for subtle separators.
  • code, codeBg: Code block styling. The code text color and the background behind code snippets.

You do not need to define every token. Themes inherit missing tokens from the default theme. This means you can create a theme that only changes the colors you care about and let the rest fall through to sensible defaults.

Creating a Theme from Scratch

If you want to build a theme without starting from an existing one, the token file is just JSON:

{
  "name": "my-custom",
  "bg": "#1a1b26",
  "bg2": "#24283b",
  "text": "#c0caf5",
  "textMuted": "#565f89",
  "accent": "#7aa2f7",
  "accentDim": "#3d59a1",
  "success": "#9ece6a",
  "warning": "#e0af68",
  "error": "#f7768e",
  "border": "#3b4261",
  "borderDim": "#292e42",
  "code": "#c0caf5",
  "codeBg": "#1f2335"
}

Save this to the themes directory in your Arcana home folder:

  • Linux / macOS: ~/.arcana/themes/my-custom.json
  • Windows: %USERPROFILE%\.arcana\themes\my-custom.json

Then switch to it with arcana theme set --name my-custom. The theme system validates your tokens on load and warns about any that are missing or malformed.

File-Edit Guard

Themes work alongside the file-edit guard system. When the guard is active, file edits show a visual confirmation prompt styled by your theme. The guard colors inherit from your theme's warning palette, so the safety system always looks integrated rather than bolted on.

This integration means your theme choices affect not just aesthetics but usability. A high-contrast theme makes the file-edit guard prompts more visible, which improves safety. A low-contrast theme might make them harder to spot, which is a tradeoff worth considering.

Related Reading