UI & Design System
Relevant source files
The following files were used as context for generating this wiki page:The Endfield-Pomodoro application features an immersive UI inspired by Cyber UI and the game Arknights: Endfield. The design system is built upon React, TypeScript, and TailwindCSS v4. Its core principles are modularity, dynamic theming through CSS Variables, and a layered architecture to create rich, animated visual effects without compromising the user experience. The system is designed to be easily extensible, allowing for new themes and components to be added with minimal effort.
The overall aesthetic is achieved through a combination of custom fonts, a specific color palette for each theme, and layered visual effects that respond to user interaction and application state.
Sources: README.md, src/index.css
Theming System
The theming system is the cornerstone of the application's visual identity. It uses CSS Custom Properties (Variables) to allow for real-time theme switching without a page reload.
Sources: README.md:80-95, src/App.tsx:220-226
Architecture
The theme architecture is straightforward:
- A set of predefined theme color palettes is stored in
src/config/themes.ts. Each theme is an object mapping CSS variable names to color values. - The main
Appcomponent holds the current theme state, which is persisted tolocalStorage. - A
useLayoutEffecthook inApp.tsxlistens for changes to the theme state. - When the theme changes, the hook iterates over the new theme's color object and applies each color to the corresponding CSS variable on the
:rootelement (document.documentElement). - All components use TailwindCSS utility classes (e.g.,
bg-theme-primary,text-theme-text) which are mapped to these CSS variables insrc/index.css.
This flow is visualized in the diagram below.
Sources: src/App.tsx:220-226, src/index.css:10-39
Theme Variables
The application uses a consistent set of CSS variables across all themes to define the color scheme.
| Variable Name | Tailwind Class | Description |
|---|---|---|
--color-base | bg-theme-base | The main background color of the application. |
--color-surface | bg-theme-surface | Background color for elevated surfaces like panels. |
--color-highlight | border-theme-highlight | Used for borders, dividers, and subtle highlights. |
--color-primary | bg-theme-primary | The primary accent color for buttons, icons, and key elements. |
--color-secondary | text-theme-secondary | A secondary accent color, often used for alternate states. |
--color-accent | text-theme-accent | A third accent color, used in specific components like the Pomodoro progress ring. |
--color-text | text-theme-text | The primary text color. |
--color-dim | text-theme-dim | A dimmed text color for secondary information or labels. |
--color-success | text-theme-success | Color for success states (e.g., "ONLINE" status). |
--color-error | text-theme-error | Color for error or warning states (e.g., "OFFLINE" status). |
Sources: src/index.css:10-39
Available Themes
The application includes several predefined themes, selectable in the settings view.
| Theme Name | ThemePreset Enum |
|---|---|
| ENDFIELD_PROTOCOL | ThemePreset.ORIGIN |
| AZURE_ARCHIVE | ThemePreset.AZURE |
| NEON_CITY | ThemePreset.NEON |
| MATRIX_CODE | ThemePreset.MATRIX |
| DESERT_OPS | ThemePreset.TACTICAL |
| ROYAL_VIOLET | ThemePreset.ROYAL |
| HEAVY_INDUSTRY (LIGHT) | ThemePreset.INDUSTRIAL |
| SCIENCE_LAB (LIGHT) | ThemePreset.LABORATORY |
| MIKU | ThemePreset.MIKU |
Sources: src/App.tsx:501-513, src/utils/i18n.ts:31-41
Layout and Layering
The UI is structured in a fixed-layer stack to create depth and manage complex visual effects. The main App component uses Flexbox to organize the header, main content, and footer. The z-index is used to control the stacking order of background effects, content, and foreground effects.
This diagram shows the visual stacking order of the main UI layers.
Sources: src/App.tsx:273-289, src/components/TerminalUI.tsx:48-83, src/components/MikuDecorations.tsx:143-146
Core UI Components (src/components/ui)
A small set of reusable, unstyled (or minimally styled) base components form the foundation of the UI. These are located in src/components/ui/ and exported via index.ts. They are styled in context using TailwindCSS.
| Component | Description | Key Props (inferred from usage) |
|---|---|---|
Panel | A container component with a title, used to frame modules like the Pomodoro timer and Task Manager. | title, className, children |
Button | A versatile button with different visual variants. | variant ('primary', 'ghost', 'secondary'), onClick, disabled, className, title |
Input | A styled text input field. | type, value, onChange, placeholder, disabled, onKeyDown |
Select | A styled select dropdown (wrapped by CustomSelect). | value, onChange, options |
Sources: src/components/ui/index.ts, src/App.tsx:439-445, 563-571, src/Pomodoro.tsx:372-386, src/TaskManager.tsx:69-78
Themed Visual Effects (TerminalUI.tsx)
The TerminalUI.tsx file is responsible for orchestrating the theme-specific background and foreground visual effects. It acts as a router, rendering different effect components based on the currently selected theme.
BackgroundLayer
This component renders at the lowest z-index (z-0) and is responsible for the ambient, non-interactive background visuals. It contains a switch statement that maps a ThemePreset to a specific background effect component (e.g., MatrixRain, AzureGrid).
// src/components/TerminalUI.tsx:31-45
export const BackgroundLayer: React.FC<{ theme?: ThemePreset }> = ({ theme = ThemePreset.ORIGIN }) => {
const renderContent = () => {
switch (theme) {
case ThemePreset.AZURE: return <AzureGrid />;
case ThemePreset.NEON: return <NeonGrid />;
case ThemePreset.MATRIX: return <MatrixRain />;
// ... other themes
case ThemePreset.MIKU: return <MikuBackgroundLayer />;
default: return <OriginGrid />;
}
};
return (
<div className="fixed inset-0 pointer-events-none z-0 overflow-hidden">
{renderContent()}
</div>
);
};
Sources: src/components/TerminalUI.tsx:31-45
ForegroundLayer
This component renders at the highest z-index (z-50) and is responsible for interactive or overlay effects, such as mouse-tracking halos or crosshairs. It tracks the mouse position and passes it down to the active effect component. To optimize performance, it is disabled entirely on mobile devices.
Like BackgroundLayer, it uses a switch statement to select the appropriate effect for the current theme.
// src/components/themes/ForegroundEffects.tsx:8-14
export const OriginForeground: React.FC<{ mousePos: MousePos }> = ({ mousePos }) => (
<div className="fixed inset-0 pointer-events-none z-50 mix-blend-screen">
<div className="absolute inset-0 transition-opacity duration-300"
style={{
background: `radial-gradient(circle 400px at ${mousePos.x}px ${mousePos.y}px, color-mix(in srgb, var(--color-primary) 15%, transparent), transparent 70%)`
}}></div>
</div>
);
Sources: src/components/TerminalUI.tsx:52-83, src/components/themes/ForegroundEffects.tsx:8-14
Special Case: MIKU Theme
The MIKU theme has more complex decorative elements that don't fit neatly into the background/foreground layers. It uses a dedicated MikuDecorations component which is rendered at z-5, between the background and the main content. This component is responsible for rendering the character and logo images at the bottom of the screen. The theme's background and foreground effects are also handled by specialized components (MikuBackgroundLayer, MikuForegroundLayer).
Sources: src/components/MikuDecorations.tsx:154-164, src/components/TerminalUI.tsx:40, 80
Styling with TailwindCSS
The project leverages TailwindCSS v4's @theme directive to create a design token system that integrates seamlessly with the CSS variable-based theming.
In src/index.css, custom fonts are imported, and CSS variables are mapped to Tailwind's theme configuration.
/* src/index.css:3-7 */
@theme {
/* 字体配置 */
--font-mono: "JetBrains Mono", monospace;
--font-sans: "Rajdhani", sans-serif;
}
/* src/index.css:10-20 */
/* 颜色配置 - 映射到CSS变量 */
/* 这会自动创建像bg-theme-primary、text-theme-base这样的类 */
--color-theme-base: var(--color-base);
--color-theme-surface: var(--color-surface);
--color-theme-highlight: var(--color-highlight);
--color-theme-primary: var(--color-primary);
--color-theme-secondary: var(--color-secondary);
--color-theme-accent: var(--color-accent);
--color-theme-text: var(--color-text);
--color-theme-dim: var(--color-dim);
--color-theme-success: var(--color-success);
--color-theme-error: var(--color-error);
The file also defines several custom utility classes and animations, such as .clip-path-slant for creating angled corners and .text-hover-fill for an animated text-fill effect on hover. These utilities contribute to the unique "cyber terminal" aesthetic.
Sources: src/index.css:3-20, 101-119
Summary
The UI & Design System of Endfield-Pomodoro is a well-architected system that effectively separates concerns. The dynamic theming powered by CSS Variables and React provides a high degree of customization. The layered architecture allows for rich, non-blocking visual effects, and the core set of UI components provides a consistent foundation for building features. The use of TailwindCSS with a custom theme configuration ensures that styling is both efficient and maintainable.