Theming System
Relevant source files
The following files were used as context for generating this wiki page:
The Theming System in Autohand provides a robust framework for managing terminal aesthetics through high-level color tokens, multi-modal color support (Truecolor, 256-color, 16-color), and customizable theme definitions. It enables consistent styling across UI components, including syntax highlighting, git diffs, and agent status indicators.
The system is designed to be extensible, supporting built-in themes such as dark, light, dracula, sandy, and tui, while allowing users to define custom themes via JSON files stored in the local environment.
Sources: src/ui/theme/index.ts:11-20, src/ui/theme/themes.ts:13-300
Architecture and Components
The system architecture separates theme definitions (raw data) from the operational Theme class (logic). The process involves loading a definition, resolving variable references into hex or ANSI values, and instantiating a global theme object used by the CLI.
Core Components
| Component | Description |
|---|---|
Theme Class | Encapsulates theme logic, handles ANSI code generation, and manages color mode detection. |
ThemeLoader | Responsible for fetching definitions from built-in maps or the filesystem (~/.autohand/themes). |
ThemeDefinition | A structural interface containing vars (reusable colors) and colors (token mappings). |
ResolvedColors | The final state of a theme where all variable references are resolved to direct color values. |
Sources: src/ui/theme/Theme.ts:25-50, src/ui/theme/loader.ts:35-60, src/ui/theme/index.ts:55-80
Initialization Flow
The following diagram illustrates how the system detects the environment and initializes the appropriate theme.
The system uses detectTerminalBackground() to check environment variables like COLORFGBG or terminal-specific signatures to choose a default theme.
Sources: src/ui/theme/loader.ts:192-225, src/ui/theme/loader.ts:46-60
Theme Logic and ANSI Generation
The Theme class handles the translation of color tokens into terminal-compatible escape sequences. It detects the terminal's color capabilities using detectColorMode() and falls back gracefully from truecolor to 256 or 16 colors if necessary.
Color Resolution Logic
- Hex to RGB: Hex strings (e.g.,
#4caf50) are parsed into RGB components. - Downsampling:
- If the mode is
256, RGB is converted to a 256-color index usingrgbTo256. - If the mode is
16, it is further reduced to a basic ANSI 16-color index.
- If the mode is
- Caching: ANSI escape sequences are cached within the
Themeinstance to minimize computation during frequent UI updates.
Built-in Themes and Customization
The system provides several predefined themes and allows for user-defined overrides. Themes are defined using a two-tier structure: vars for base palette definition and colors for mapping semantic tokens to those palette entries.
Available Tokens
The system uses approximately 40 semantic tokens, including:
- Core UI:
accent,success,error,warning,muted. - Git/Diff:
diffAdded,diffRemoved,diffContext. - Syntax:
syntaxKeyword,syntaxFunction,syntaxString,syntaxComment.
Custom Theme Loading
Users can add .json files to ~/.autohand/themes/. The loader validates these files and merges them with the dark theme to ensure all required tokens are present.
{
"name": "my-custom-theme",
"vars": {
"brand": "#ff00ff"
},
"colors": {
"accent": "brand"
}
}
Sources: src/ui/theme/themes.ts:13-75, src/ui/theme/loader.ts:77-110
User Interaction and Commands
Users can interact with the theming system through the /theme slash command. This command provides an interactive selection menu and a preview of the changes.
Theme Command Workflow
The /theme command utilizes enquirer for selection and saveConfig to persist user preferences. It also provides a themeInfo utility to display the current color mode and path to custom themes.
Sources: src/commands/theme.ts:16-55, src/commands/theme.ts:67-95
Implementation in UI Features
The theming system is heavily utilized by core CLI features like the ActionExecutor to style complex outputs.
Git Diff Styling
When displaying diffs, the ActionExecutor retrieves colors for diffAdded and diffRemoved from the active theme. It calculates dim background colors by scaling the RGB values (e.g., 15-25% of original brightness) to create "hunk" backgrounds.
const addedColor = theme?.getColor('diffAdded') || '#4caf50';
const addedRgb = hexToRgb(addedColor);
const bgR = addedRgb ? Math.floor(addedRgb.r * 0.15) : 30;
// ... creates stylized diff lines
Sources: src/core/actionExecutor.ts:1010-1040, src/core/actionExecutor.ts:1145-1165
Summary
The Autohand Theming System centralizes visual configuration through a semantic token-based architecture. By decoupling color definitions from UI logic and providing a robust resolution engine for various terminal capabilities, it ensures high accessibility and personalization. The inclusion of auto-detection for terminal backgrounds and support for custom JSON themes allows the CLI to integrate seamlessly into diverse developer environments.