Skip to content

themes.md

Latest commit

 

History

History
219 lines (159 loc) · 4.38 KB

themes.md

File metadata and controls

219 lines (159 loc) · 4.38 KB
Raw

Theme System

A.R.C. CLI includes a powerful theme system for customizing the visual appearance of banners and output.

Quick Start

# List all available themes
arc theme list

# Set a theme
arc theme set rainbow

# Preview current theme
arc theme show

Built-in Themes

Theme Style Description
cyan-purple Default Modern cyan to purple gradient
rainbow Vibrant Full spectrum rainbow colors
fire Energetic Yellow to red gradient
ocean Calm Light cyan to deep blue
matrix Retro Green gradient, hacker style
character-rainbow Special Rainbow on every character

Commands

arc theme list

Lists all themes with a marker showing your current selection:

Available Themes:

  character-rainbow - Rainbow gradient on every character
▶ cyan-purple - Cyan to Purple Gradient (default)
  fire - Fire - Yellow to Red gradient
  matrix - Matrix - Green gradient
  ocean - Ocean - Light cyan to deep blue
  rainbow - Rainbow - Full spectrum

arc theme set <name>

Sets and persists the theme:

arc theme set rainbow
# ✅ Theme set to: rainbow

arc theme show

Displays the current theme banner.

Theme Persistence

Themes are saved to ~/.arc/state.json and persist across:

  • Terminal sessions
  • System reboots
  • All arc commands

Reset to default:

arc theme set cyan-purple

Creating Custom Themes

Option 1: YAML Theme Files

Create a YAML file in ~/.config/arc/themes/:

name: cyberpunk
description: "Neon cyberpunk theme"
version: "1.0.0"
author: "Your Name"

colors:
  primary: "#FF00FF"
  secondary: "#00FFFF"
  success: "#00FF00"
  error: "#FF0066"
  warning: "#FFFF00"
  info: "#00FFFF"
  foreground: "#E0E0E0"
  background: "#0A0A0A"
  muted: "#808080"
  border: "#FF00FF"

  banner_gradient:
    - "#FF00FF"
    - "#FF33FF"
    - "#CC66FF"
    - "#9966FF"
    - "#6666FF"
    - "#3366FF"
    - "#0066FF"
    - "#0099FF"
    - "#00CCFF"
    - "#00FFFF"

styles:
  bold: true
  border_style: "rounded"  # normal, rounded, thick, double, hidden
  padding_top: 1
  padding_right: 2
  padding_bottom: 1
  padding_left: 2

symbols:
  success: "✓"
  error: "✗"
  warning: "⚠"
  info: "ℹ"
  bullet: "•"
  arrow: "→"
  spinner: ["⠋", "⠙", "⠹", "⠸", "⠼", "⠴", "⠦", "⠧"]

Install and use:

mkdir -p ~/.config/arc/themes
cp cyberpunk.yaml ~/.config/arc/themes/
arc theme set cyberpunk

Option 2: Go Code (Built-in Themes)

Add to pkg/cli/banner.go:

"my-custom": {
    Name:        "my-custom",
    Description: "My Custom Theme",
    Colors: []lipgloss.Color{
        lipgloss.Color("#COLOR1"),
        // ... 11 colors for banner gradient
    },
},

Then rebuild: make build

Color Guidelines

Hex Formats

  • Short: #RGB (e.g., #F00)
  • Standard: #RRGGBB (e.g., #FF0000)
  • With alpha: #RRGGBBAA (e.g., #FF0000FF)

Gradient Tips

  • Use 11 colors for the banner (one per line)
  • Smooth transitions look best
  • Test on both light and dark terminal backgrounds
  • Use gradient generators: coolors.co, cssgradient.io

Spinner Animations

Popular spinner styles:

# Braille dots (smooth)
spinner: ["⠋", "⠙", "⠹", "⠸", "⠼", "⠴", "⠦", "⠧", "⠇", "⠏"]

# Geometric
spinner: ["◐", "◓", "◑", "◒"]

# Arrows
spinner: ["←", "↖", "↑", "↗", "→", "↘", "↓", "↙"]

# Blocks
spinner: ["▁", "▂", "▃", "▄", "▅", "▆", "▇", "█"]

Disabling Colors

Use --no-color for plain output:

arc --no-color

Or set environment variable:

export NO_COLOR=1

Useful for CI/CD pipelines and log files.

Troubleshooting

Theme doesn't change

  1. Check state file: cat ~/.arc/state.json
  2. Verify theme name: arc theme list
  3. Rebuild if using custom Go theme: make build

Colors not showing

  1. Verify terminal supports true color: echo -e "\e[38;2;255;0;0mRed\e[0m"
  2. Check NO_COLOR environment variable
  3. Ensure --no-color flag isn't set

Custom theme not loading

  1. Check file location: ~/.config/arc/themes/yourtheme.yaml
  2. Validate YAML syntax
  3. Check logs: ~/.local/share/arc/logs/arc.log