Theming & Styling
Relevant source files
The following files were used as context for generating this wiki page:
The styling architecture of Bolt is built on a multi-layered approach that combines CSS variables, Sass pre-processing, and the UnoCSS atomic CSS engine. The system is designed to support a seamless transition between Light and Dark modes by utilizing a theme-driven variable system. Theme state is persisted via local storage and synchronized across the application using a dedicated store, ensuring a consistent user experience.
The core of the styling logic resides in the definition of "Element Tokens," which map high-level UI components to specific color primitives. This abstraction allows for centralized theme management where changing a single primitive color can update multiple UI elements simultaneously.
Theme Management and Initialization
The application manages theme state through a combination of local storage persistence and a reactive store. During the initial page load, an inline script prevents "flash of unstyled content" (FOUC) by immediately applying the saved theme or defaulting to the system preference.
Initialization Flow
The app/root.tsx file contains the logic for both server-side injection of the theme script and client-side synchronization.
The diagram shows the logic used to determine and apply the initial theme to the HTML element.
Sources: app/root.tsx:37-47, app/root.tsx:61-65
Key Theme Logic
- Persistent Attribute: The theme is applied globally by setting the
data-themeattribute on the<html>element. Sources: app/root.tsx:46 - Store Integration: A
themeStore(managed via nanostores) provides reactive updates to components when the user toggles the theme. Sources: app/root.tsx:61-65
Color System and Primitive Definitions
The project utilizes a structured color palette defined in uno.config.ts. This configuration establishes the base primitives used throughout the CSS variable system.
Color Primitives
The BASE_COLORS object defines standardized hex values for common colors including:
- Gray: A 50-950 scale for backgrounds and text.
- Accent: Blue shades (50-950) used for primary actions and highlights.
- Status Colors: Specific scales for
green(success),orange(warning), andred(error/danger).
Sources: uno.config.ts:32-105
Alpha Palette Generation
A utility function generateAlphaPalette is used to create semi-transparent versions of hex colors by appending calculated alpha hex codes (from 1% to 100% opacity).
Sources: uno.config.ts:258-274
CSS Variable Architecture
Styling is driven by CSS variables defined in app/styles/variables.scss. These variables are scoped to :root and toggled based on the [data-theme] attribute.
Element Token Mapping
The system categorizes styles into functional "Element Tokens" to ensure semantic consistency across the UI.
| Category | Variables (Examples) | Description |
|---|---|---|
| Backgrounds | --bolt-elements-bg-depth-1 to 4 | Layered backgrounds for depth. |
| Text | --bolt-elements-textPrimary, Secondary, Tertiary | Hierarchy of text readability. |
| Buttons | --bolt-elements-button-primary-background, text | Styling for different button states (Primary, Secondary, Danger). |
| Components | --bolt-elements-artifacts-background, --bolt-elements-terminals-background | Component-specific surface colors. |
| Terminal | --bolt-terminal-black, red, green, etc. | Standard ANSI terminal colors mapped to theme variables. |
Sources: app/styles/variables.scss:1-248
UnoCSS and Atomic Styling
UnoCSS is configured to provide utility classes that integrate directly with the CSS variables defined in the SCSS files.
Shortcuts and Rules
Custom shortcuts allow for consistent application of complex transitions and component styles:
transition-theme: Applies transitions tobackground-color,border-color, andcolorwith a cubic-bezier easing.kdb: Styles keyboard shortcuts within the UI.max-w-chat: Standardizes the chat container width using the--chat-max-widthvariable.
Sources: uno.config.ts:121-125
Integration with Theme Attributes
The UnoCSS presetUno is configured to respect the data-theme attribute for dark mode resolution.
presetUno({
dark: {
light: '[data-theme="light"]',
dark: '[data-theme="dark"]',
},
})
Sources: uno.config.ts:241-247
Code Editor Styling
The code editor, based on CodeMirror, has its own specialized styling system that bridges JavaScript-based themes and CSS variables.
Theme Synchronization
The app/components/editor/codemirror/cm-theme.ts file uses a Compartment to dynamically reconfigure the editor's theme between vscodeLight and vscodeDark when the global application theme changes.
Sources: app/components/editor/codemirror/cm-theme.ts:9-20
Editor Variables
Detailed variables for the editor's UI (gutters, selection, search panels, and tooltips) are defined in app/styles/components/editor.scss. This allows the editor to visually blend with the rest of the application.
The editor's appearance is controlled by mapping SCSS variables to the CodeMirror internal theme engine.
Sources: app/styles/components/editor.scss:1-115, app/components/editor/codemirror/cm-theme.ts:24-65
Summary
Theming and styling in Bolt are implemented through a centralized, token-based system. By combining UnoCSS for utility-first layouts, SCSS for structured variable definitions, and a reactive theme store, the project achieves a highly customizable and consistent appearance across both light and dark modes. The integration of CodeMirror-specific styling ensures that the primary development interface remains cohesive with the broader application design.