08.Theme Settings.md

Snow CLI User Guide - Theme Settings

Welcome to Snow CLI! Agentic coding in your terminal.

What is a Theme

A theme defines the appearance of the Snow CLI terminal interface, including color schemes, code highlighting styles, menu display effects, etc. Through theme settings, you can:

• Select preset theme schemes
• Customize colors to suit personal preferences
• Adjust interface display mode (Simple/Standard)
• Create and save your own theme colors

Accessing Theme Settings

1. Launch Snow CLI
2. Select "Theme Settings" option in main menu
3. Enter theme settings interface

Simple Mode

Simple mode is an independent interface display option that can simplify terminal interface display and reduce visual distractions.

Feature Description

• Standard Mode: Full display of all interface elements (borders, decorations, detailed information)
• Simple Mode: Simplified interface display, hiding non-essential elements, focusing on content itself

Operation Method

1. In the theme settings interface, the first option is "Simple Mode"
2. Press Enter key to toggle status after selection
3. Interface displays current status:
   • Simple Mode Enabled
   • Simple Mode Disabled
4. Simple mode toggle takes effect immediately

Use Cases

• Small screen terminals: Reduce space usage
• Focused work: Reduce visual distractions
• Performance optimization: Reduce rendering overhead
• Screenshot demos: Cleaner and clearer interface

Preset Themes

Snow CLI provides 6 carefully designed preset themes, each with a unique color scheme.

1. Dark Theme

Features: Snow CLI's default theme, classic dark color scheme

Use Cases:

• Long coding sessions
• Low-light environments
• Eye protection needs

Color Characteristics:

• Dark background
• Soft text colors
• Clear syntax highlighting
• Comfortable contrast

2. Light Theme

Features: Bright light theme, suitable for daytime use

Use Cases:

• Use in bright environments
• Daytime work hours
• Personal preference for light interfaces

Color Characteristics:

• Light background
• Dark text
• High contrast
• Clear and easy to read

3. GitHub Dark Theme

Features: Mimics GitHub's dark theme style

Use Cases:

• GitHub users
• Developers who like GitHub colors
• Need familiar visual experience

Color Characteristics:

• GitHub-style colors
• Professional code highlighting
• Comfortable dark background

4. Rainbow Theme

Features: Rich and colorful color scheme

Use Cases:

• Like bright colors
• Need to distinguish different types of information
• Personalization needs

Color Characteristics:

• Colorful highlighting
• Vivid visual effects
• Active atmosphere

5. Solarized Dark Theme

Features: Dark version of the famous Solarized color scheme

Use Cases:

• Solarized enthusiasts
• Need scientific color scheme
• Long reading of code

Color Characteristics:

• Scientifically designed colors
• Comfortable contrast
• Eye-friendly color scheme

6. Nord Theme

Features: Cool-toned theme inspired by Nord color scheme

Use Cases:

• Like cool tones
• Pursuing modern feel
• Unified color experience

Color Characteristics:

• Nordic-style colors
• Cool tones as main
• Elegant and modern

Theme Selection and Application

Browsing Themes

1. In the theme settings interface, use ↑/↓ arrow keys to browse theme list
2. When cursor moves to a theme, the interface immediately previews that theme's effects
3. Preview area displays code comparison examples, showing the theme's syntax highlighting effects
4. Bottom displays description information of currently selected theme

Preview Features:

• No need to press Enter, cursor movement provides preview
• Real-time display of theme effects
• Code Diff examples show syntax highlighting
• Helps quickly choose suitable theme

Applying Theme

1. Browse to the theme you want to use
2. Press Enter key to confirm application
3. Theme configuration automatically saves to ~/.snow/theme.json
4. Theme takes effect immediately and applies to entire interface

Cancel Changes

• Press ESC key: Cancel changes, restore theme from before entering settings
• Select "Return" option: Also restores original theme

Custom Theme

In addition to preset themes, you can create completely custom theme colors.

Entering Custom Editor

1. Select "Edit Custom Theme..." option in theme settings interface
2. Press Enter to enter custom theme editor
3. Editor displays all customizable color options

Customizable Colors

Custom theme includes 16 color options, divided into multiple categories:

Basic Colors (3 items)

1. background - Background color

   • Main interface background
   • Recommended to use dark or light base tone

2. text - Text color

   • Main text content color
   • Needs good contrast with background

3. border - Border color

   • UI borders and separators
   • Usually slightly lighter or darker than background

Diff Display Colors (3 items)

4. diffAdded - Added line background color

   • Background for code addition lines
   • Recommended to use green tones

5. diffRemoved - Deleted line background color

   • Background for code deletion lines
   • Recommended to use red tones

6. diffModified - Modified content highlight color

   • Highlight for in-line modifications
   • Recommended to use yellow tones

Line Number Colors (2 items)

7. lineNumber - Line number text color

   • Color for code line numbers
   • Usually use gray tones

8. lineNumberBorder - Line number area border color

   • Border for line number area
   • Coordinate with line number color

Menu Colors (4 items)

9. menuSelected - Selected menu item color

   • Currently selected menu item
   • Needs to be prominent

10. menuNormal - Normal menu item color

    • Unselected menu items
    • Appropriate contrast with background

11. menuInfo - Info menu item color

    • Prompt information, description text
    • Usually use cyan tones

12. menuSecondary - Secondary menu item color

    • Secondary information, auxiliary text
    • Usually use gray tones

Status Colors (3 items)

13. error - Error prompt color

    • Error messages, warnings
    • Usually use red

14. warning - Warning prompt color

    • Warning messages, notes
    • Usually use yellow

15. success - Success prompt color

    • Success messages, confirmation information
    • Usually use green

Logo Gradient Colors (1 item)

16. logoGradient - Logo gradient colors
    • Gradient effect for Snow CLI Logo
    • Need to input 3 color values, separated by commas
    • Format: #color1, #color2, #color3
    • Example: #d3d3d3, #808080, #505050

Editing Colors

Selecting Color to Edit

1. Use ↑/↓ arrow keys to browse color list
2. Each line displays: Color name: Current value
3. Select color item to modify
4. Press Enter key to enter edit mode

Inputting Color Value

After entering edit mode:

1. Interface displays current color value

2. Provides input box for entering new value

3. Supports multiple color formats:

   • Hexadecimal: #RRGGBB (like #1e1e1e)
   • Color names: red, blue, green, cyan, yellow, etc.
   • RGB format: rgb(30, 30, 30)

4. Press Enter to confirm after input

5. Color immediately updates and displays effect in preview area

Cancel Editing

• In edit mode, press ESC key: Cancel current color modification
• Return to color list to continue editing other colors

The preview area at the bottom of the custom editor displays your color scheme effects in real-time:

• Display code comparison examples
• Show syntax highlighting effects
• Display Diff comparison effects
• Help you evaluate color scheme

Saving Custom Theme

After completing color editing:

1. Select "Save" option at bottom of color list
2. Press Enter to confirm save
3. Custom colors save to ~/.snow/theme.json
4. Theme automatically switches to "Custom" theme
5. Return to theme settings interface

Configuration File Format:

{
  "theme": "custom",
  "customColors": {
    "background": "#1e1e1e",
    "text": "#d4d4d4",
    "border": "#3e3e3e",
    "diffAdded": "#0d4d3d",
    "diffRemoved": "#5a1f1f",
    "diffModified": "#dcdcaa",
    "lineNumber": "#858585",
    "lineNumberBorder": "#3e3e3e",
    "menuSelected": "#5e0691ff",
    "menuNormal": "white",
    "menuInfo": "cyan",
    "menuSecondary": "gray",
    "error": "red",
    "warning": "yellow",
    "success": "green",
    "logoGradient": ["#d3d3d3", "#808080", "#505050"]
  },
  "simpleMode": false
}

Reset to Default Colors

If unsatisfied with custom colors, you can reset to default values:

1. Select "Reset to Default" option in custom editor
2. Press Enter to confirm
3. All colors restore to system default custom theme colors
4. Preview area immediately displays default color effects
5. Can start editing again

Note: Reset operation doesn't save immediately, need to select "Save" to write to configuration file

Keyboard Shortcuts

Theme Settings Interface

• ↑/↓: Navigate in theme list
• Enter: Apply selected theme or execute operation
• ESC: Cancel changes and return to main menu

Custom Editor

• ↑/↓: Navigate in color list
• Enter: Edit selected color or execute operation
• ESC: Return to theme settings (unsaved changes will be lost)

Color Edit Mode

• Enter: Confirm input color value
• ESC: Cancel current color editing

Theme Configuration Best Practices

1. Choose Appropriate Base Theme

Choose based on work environment:

• Low-light environment: Dark themes (Dark, GitHub Dark, Nord)
• Bright environment: Light theme (Light)
• Personal preference: Choose most comfortable color scheme

2. Custom Theme Color Suggestions

Contrast

• Ensure text has sufficient contrast with background
• Avoid overly harsh color combinations
• Test comfort for long-term use

Consistency

• Maintain consistency of color scheme
• Use similar tones for related functions
• Avoid too many colors causing confusion

Readability

• Code highlighting colors should be clearly distinguishable
• Diff colors should clearly distinguish added/deleted/modified
• Menu item colors should have clear hierarchy

3. Color Selection Techniques

Hexadecimal Colors

Format: #RRGGBB
Examples:
  #1e1e1e - Dark gray background
  #d4d4d4 - Light gray text
  #0d4d3d - Dark green (added lines)
  #5a1f1f - Dark red (deleted lines)

Named Colors

Basic colors:
  black, white, gray
  
Bright colors:
  red, green, blue
  cyan, magenta, yellow
  
Extended colors:
  Refer to list of color names supported by terminal

4. Logo Gradient Color Configuration

Logo gradient requires 3 colors to form gradient effect:

Light to dark:
  #ffffff, #808080, #000000
  
Blue tones:
  #5e9cff, #2e5c8f, #1e3c5f
  
Green tones:
  #90ee90, #50ae50, #306e30
  
Custom:
  Ensure three colors form smooth transition
  First brightest, third darkest

5. Testing Theme Effects

After creating custom theme, it's recommended to:

1. Test code highlighting effects
2. Check Diff comparison clarity
3. Verify menu readability
4. Confirm comfort for long-term use
5. Test compatibility in different terminals

6. Backup Custom Theme

Regularly backup configuration file:

# Backup theme configuration
cp ~/.snow/theme.json ~/.snow/theme.json.backup

# Restore backup
cp ~/.snow/theme.json.backup ~/.snow/theme.json

7. Multi-Environment Configuration

If using on different devices or environments:

• Choose theme based on screen characteristics
• Consider environment lighting differences
• Unify team color scheme (optional)

Frequently Asked Questions

Q: Do I need to restart Snow CLI after changing theme?

A: No. Theme changes take effect immediately and apply to current interface and all subsequent operations.

Q: Where is the custom theme configuration file?

A: Configuration file is located at ~/.snow/theme.json, can be manually edited or configured through interface.

Q: Can I import and export custom themes?

A: Yes. Simply copy the theme.json file to share theme configuration. Place the file in ~/.snow/ directory to use.

Q: What's the difference between simple mode and theme selection?

A: Simple mode controls interface display complexity, theme controls color scheme. They work independently and can be combined.

Q: What if interface displays abnormally after customizing colors?

A: Select "Reset to Default" in custom editor, or directly delete ~/.snow/theme.json file, Snow CLI will automatically use default configuration.

Q: Do all terminals support custom colors?

A: Most modern terminals support it, but some older terminals may only support 16 colors. It's recommended to use modern terminals like iTerm2, Windows Terminal, Hyper, etc.

Q: Can I use different themes for different projects?

A: Currently theme is global configuration, shared by all projects. If needed, can temporarily modify configuration file before launching Snow CLI.

Q: Can the preview area code examples be customized?

A: Preview code is fixed examples for showing theme effects. In actual use it will apply to your real code.

Q: Must logoGradient have 3 colors?

A: Yes. Logo gradient design requires 3 colors to form smooth gradient effect. Format must be [color1, color2, color3].

Q: How do I share my custom theme with the team?

A: Copy the customColors section from ~/.snow/theme.json file and share with team members. They can paste the content into their own configuration file.

Theme Configuration File Description

Theme configuration is stored in ~/.snow/theme.json file.

Complete Configuration Example

{
  "theme": "custom",
  "customColors": {
    "background": "#1e1e1e",
    "text": "#d4d4d4",
    "border": "#3e3e3e",
    "diffAdded": "#0d4d3d",
    "diffRemoved": "#5a1f1f",
    "diffModified": "#dcdcaa",
    "lineNumber": "#858585",
    "lineNumberBorder": "#3e3e3e",
    "menuSelected": "#5e0691ff",
    "menuNormal": "white",
    "menuInfo": "cyan",
    "menuSecondary": "gray",
    "error": "red",
    "warning": "yellow",
    "success": "green",
    "logoGradient": ["#d3d3d3", "#808080", "#505050"]
  },
  "simpleMode": false
}

Field Descriptions

• theme: Currently used theme type

  • Options: dark, light, github-dark, rainbow, solarized-dark, nord, custom

• customColors: Custom theme color configuration

  • Only used when theme is custom
  • Contains 16 color fields

• simpleMode: Simple mode switch

  • true: Enable simple mode
  • false: Use standard mode

Manual Editing Considerations

If choosing to manually edit configuration file:

1. Ensure JSON format is correct
2. logoGradient must be array format
3. Color values must be valid color formats
4. Restart Snow CLI after editing to load new configuration

It's recommended to use configuration interface for modifications to avoid format errors.