Theming System
Relevant source files
The following files were used as context for generating this wiki page:The Theming System in Endfield-Pomodoro provides a dynamic and extensible way to alter the application's visual appearance. It is built upon a foundation of CSS Variables, allowing for real-time theme switching without a page reload. The system is not limited to color changes; it also includes a modular architecture for theme-specific background and foreground visual effects, creating a deeply immersive user experience.
The core of the system involves a set of predefined theme presets, each with a unique color palette and optional special effects. Users can select their preferred theme through the settings interface, and the application will dynamically apply the corresponding styles and visual components. This modularity also simplifies the process of adding new themes.
Core Architecture
The theming architecture leverages CSS Variables (Custom Properties) for colors and a layered React component structure for visual effects.
- CSS Variables: A set of global CSS variables for colors is defined in the
:rootselector. These variables are used throughout the application's stylesheets to ensure consistency.
Sources: src/index.css:32-43 - Dynamic Application: The main
Appcomponent contains auseLayoutEffecthook. This hook listens for changes to thesettings.themestate. When the theme changes, it retrieves the corresponding color palette from theTHEMESconfiguration object and injects these colors as CSS variables on thedocument.documentElement, immediately updating the entire UI.
Sources: src/App.tsx:220-226 - Visual Effects Layers: The UI is composed of several layers. The main content resides on a central z-index, while dedicated
BackgroundLayerandForegroundLayercomponents render visual effects behind and in front of the content, respectively. A specialMikuDecorationscomponent demonstrates how themes can add unique elements outside the standard layers.
Sources: src/App.tsx:266-274, src/components/TerminalUI.tsx
The following diagram illustrates the flow of applying a theme change.
Theme Configuration
All theme-related definitions are centralized in src/types.ts and src/config/themes.ts.
Theme Presets (ThemePreset)
An enum-like object ThemePreset in src/types.ts defines the unique identifiers for all available themes.
| Preset Key | UI Label (EN) | UI Label (CN) |
|---|---|---|
ORIGIN | PRESET_01: ENDFIELD_PROTOCOL | 预设_01: 末端协议 |
AZURE | PRESET_02: AZURE_ARCHIVE | 预设_02: 蔚蓝档案 |
NEON | PRESET_03: NEON_CITY | 预设_03: 霓虹都市 |
MATRIX | PRESET_04: MATRIX_CODE | 预设_04: 矩阵代码 |
TACTICAL | PRESET_05: DESERT_OPS | 预设_05: 荒漠行动 |
ROYAL | PRESET_06: ROYAL_VIOLET | 预设_06: 皇家紫罗兰 |
INDUSTRIAL | PRESET_07: HEAVY_INDUSTRY (LIGHT) | 预设_07: 重工灰烬 (亮色) |
LABORATORY | PRESET_08: SCIENCE_LAB (LIGHT) | 预设_08: 科学实验 (亮色) |
MIKU | PRESET_09: MIKU | 预设_09: MIKU |
Sources: src/types.ts:23-33, src/utils/i18n.ts:44-53, 151-160
Color Variables
The THEMES object in src/config/themes.ts maps each ThemePreset key to a dictionary of CSS variable strings and their corresponding color values.
// src/config/themes.ts
export const THEMES: Record<ThemePreset, Record<string, string>> = {
[ThemePreset.INDUSTRIAL]: {
'--color-base': '#e5e5e5',
'--color-surface': '#d4d4d4',
'--color-highlight': '#a3a3a3',
'--color-primary': '#f97316',
'--color-secondary': '#f6ff00',
'--color-accent': '#ffd1f6',
'--color-text': '#141414',
'--color-dim': '#7a7a7a',
'--color-success': '#16a34a',
'--color-error': '#dc2626'
},
// ... other themes
};
Sources: src/config/themes.ts:6-113
These variables are defined in src/index.css and used by TailwindCSS to generate utility classes like bg-theme-primary and text-theme-text.
| Variable | Purpose |
|---|---|
--color-base | Main background color of the page. |
--color-surface | Background color for UI elements like panels. |
--color-highlight | Border colors, dividers, and subtle highlights. |
--color-primary | Main accent color for buttons, progress bars, and interactive elements. |
--color-secondary | Secondary accent color, often used for alternative states or effects. |
--color-accent | Tertiary accent color for special effects. |
--color-text | Primary text color. |
--color-dim | Secondary text color for labels and less important information. |
--color-success | Color for success states. |
--color-error | Color for error or warning states. |
| Sources: src/index.css:32-43 |
Theme Application Logic
The theme is managed as part of the global settings state in App.tsx. When a user changes the theme in the settings panel, a sequence of events is triggered to update the application's appearance.
This sequence diagram shows the interaction when a user changes the theme.
Sources: src/App.tsx:220-226, 472-485
Visual Effects Engine
Beyond colors, the theming system supports complex visual effects through a set of dedicated React components.
The TerminalUI.tsx file exports two main components, BackgroundLayer and ForegroundLayer, which act as routers. Based on the theme prop they receive, they use a switch statement to render the appropriate effect component.
This diagram shows the component hierarchy for rendering visual effects.
Background Effects
These components are rendered in the BackgroundLayer at z-index: 0 and are not interactive. They provide ambient visuals.
MatrixRain: Creates a "digital rain" effect with falling characters for theMATRIXtheme.
Sources: src/components/themes/BackgroundEffects.tsx:81-101IndustrialGrid: Renders a repeating diagonal line pattern for theINDUSTRIALtheme.
Sources: src/components/themes/BackgroundEffects.tsx:157-165RoyalParticles: Generates a soft, pulsing particle effect for theROYALtheme.
Sources: src/components/themes/BackgroundEffects.tsx:142-155
Foreground Effects
These components are rendered in the ForegroundLayer at z-index: 50 with pointer-events: none. Many of them react to mouse movement.
OriginForeground: Displays a radial gradient "halo" that follows the mouse cursor.
Sources: src/components/themes/ForegroundEffects.tsx:9-15TacticalForeground: Renders a crosshair that follows the mouse and displays its coordinates.
Sources: src/components/themes/ForegroundEffects.tsx:20-36AzureForeground: Shows a persistent vertical scanning line animation, independent of the mouse.
Sources: src/components/themes/ForegroundEffects.tsx:41-45
Specialized Theme: MIKU
The MIKU theme demonstrates the system's extensibility. In addition to its own background and foreground effects (MikuBackgroundLayer, MikuForegroundLayer), it uses a dedicated component, MikuDecorations, which is rendered directly in App.tsx. This component adds unique character and logo imagery to the UI, positioned relative to the footer. This special handling shows that themes can introduce entirely new UI elements, not just layered effects.
Sources: src/App.tsx:271, src/components/MikuDecorations.tsx:165-174