Theming

Learn how the color system works in ArchitectUI — from compile-time SCSS theme switching to runtime class swaps via the Theme Options drawer.

How Theming Works

ArchitectUI uses a two-layer theming model:

Compile-time themes — 9 baked-in SCSS theme directories under src/assets/themes/. Switching between them requires editing one @import line in base.scss and recompiling.
Runtime overrides — the Theme Options drawer applies CSS classes to .app-container via JavaScript, swapping header color, sidebar color, and content background instantly without recompiling.

For most use cases the compile-time approach gives you the polish (consistent palette across every component, smaller bundle), while the drawer is best for demos, multi-tenant skinning, or letting end-users pick a look.

Baked-in Themes

Nine pre-built themes live under src/assets/themes/:

Theme	Primary palette	Best for
`default`	Bootstrap blue (`#3f6ad8`)	General-purpose admin panels
`dark`	Dark surfaces with cool accents	Night-mode interfaces, monitoring dashboards
`blue-alt`	Deeper, cooler blue	Corporate / fintech
`green`	Mint-leaning primary	Health, wellness, eco-tech
`orange`	Warm orange primary	Marketing, creative tools
`red`	Vibrant red primary	Alerting dashboards, e-commerce
`purple`	Plum primary	SaaS, productivity
`purple-alt`	Lighter, lavender variant	SaaS with softer brand voice
`black`	High-contrast monochrome	Editorial, agency portfolios

Switching the Active Theme

Themes are selected by importing the matching _variables.scss in src/assets/base.scss. By default the layout-variables import handles theme resolution:

// src/assets/base.scss
                @import "themes/layout-variables";    // resolves to themes/default

To switch the active theme, edit src/assets/themes/_layout-variables.scss and update the theme path it imports from, or edit base.scss to point at a specific theme directly:

// Example: switch to the green theme
                @import "themes/green/variables";
                @import "themes/green/layout-variables";

Save and the dev server recompiles. Every component — buttons, links, focus rings, active sidebar items, badges, gradient backgrounds — updates simultaneously.

Theme Variables

Each theme directory contains two files:

src/assets/themes/default/
                ├── _variables.scss            # Brand palette, fonts, spacing, radii
                └── _layout-variables.scss     # Header, sidebar, footer color tokens

Brand Palette

_variables.scss overrides Bootstrap's defaults. The most commonly customized values:

$primary:        #3f6ad8;     // Main brand color
                $secondary:      #6c757d;
                $success:        #3ac47d;
                $info:           #16aaff;
                $warning:        #f7b924;
                $danger:         #d92550;
                $light:          #eeeeee;
                $dark:           #343a40;
                $focus:          #444054;
                $alternate:      #794c8a;
                
                // Gradient palette (used in ThemeOptions drawer swatches)
                $bg-vicious-stance:   linear-gradient(to right, #29323c, #485563);
                $bg-midnight-bloom:   linear-gradient(-20deg, #2b5876 0%, #4e4376 100%);
                $bg-night-sky:        linear-gradient(-20deg, #2b5876 0%, #4e4376 100%);
                // ...and 25 more gradient tokens

Layout Tokens

_layout-variables.scss defines the colors specific to layout chrome:

// Header
                $app-header-bg:           #ffffff;
                $app-header-text:         #495057;
                $app-header-height:       60px;
                
                // Sidebar
                $app-sidebar-bg:          #ffffff;
                $app-sidebar-text:        #495057;
                $app-sidebar-width:       260px;
                $app-sidebar-width-collapsed: 80px;
                
                // Main content
                $app-main-bg:             #f4f5f9;
                $app-main-padding:        30px;

Customizing the Primary Color

The fastest way to rebrand: change $primary in the active theme's _variables.scss. Every component that uses Bootstrap's theme-color() function or the --bs-primary CSS variable updates automatically.

// src/assets/themes/default/_variables.scss
                
                $primary: #ff6b35;   // Pick your brand color
                // (re-derived values like $primary-hover, $primary-active update too)

Save and the dev server recompiles. Affected: buttons, badge backgrounds, link colors, focus rings, active sidebar items, switch knobs, range slider handles, chart accent colors, gradient mixes that include $primary.

Creating a Custom Theme

To create a completely new theme without modifying any existing one:

# 1. Copy the default theme as a starting point
                cp -r src/assets/themes/default src/assets/themes/my-theme
                
                # 2. Edit the new theme's variables
                # src/assets/themes/my-theme/_variables.scss
                # src/assets/themes/my-theme/_layout-variables.scss
                
                # 3. Import the new theme in base.scss
                # (or update _layout-variables.scss to resolve to it)

The benefit of copying default/ is you start with every variable already declared. You can then incrementally override only what's brand-specific.

Theme Options Drawer (Runtime)

Every dashboard page includes a slide-out gear panel anchored to the right edge. The drawer toggles CSS classes on the .app-container root element to remix the look without recompiling:

Layout switches — Fixed Header, Fixed Sidebar, Fixed Footer
Header color schemes — 30+ swatches (solid Bootstrap colors plus gradients: bg-vicious-stance, bg-midnight-bloom, bg-sunny-morning, bg-plum-plate, etc.)
Sidebar color schemes — Light and dark variants with matching text-tone classes (sidebar-text-light, sidebar-text-dark)
Main content theme — app-theme-white, app-theme-gray, app-theme-dark
Page tabs theme — Restyle in-page tab navigation

Drawer state is not persisted between page loads by default. To make a particular skin the page's default, hard-code the relevant classes directly on .app-container in src/layout/base.hbs:

<div class="app-container app-theme-white body-tabs-shadow fixed-header fixed-sidebar">
                    {{!-- ...layout content... --}}
                </div>

Drawer-applied classes always include the bg-* background class plus a matching header-text-* or sidebar-text-* tone class. When hard-coding, copy both from the swatch's data-class attribute.

Dark Mode

ArchitectUI ships a complete dark theme at src/assets/themes/dark/. To set dark mode as the default:

// src/assets/themes/_layout-variables.scss
                @import "dark/layout-variables";

For OS-preference-aware dark mode, add a prefers-color-scheme media query in base.scss that imports the dark theme variables inside it. Note that SCSS cannot conditionally @import based on runtime media queries — you would compile two separate stylesheets and serve them via <link rel="stylesheet" media="...">:

<link rel="stylesheet" href="assets/styles/main.[hash].css">
                <link rel="stylesheet" href="assets/styles/main-dark.[hash].css"
                      media="(prefers-color-scheme: dark)">

To produce the second bundle, add a second SCSS entry point to webpack.config.js that imports the dark theme.

Gradient Backgrounds

ArchitectUI defines ~30 named gradients used across stat cards, dropdown headers, and the theme drawer. They live in src/assets/themes/default/_variables.scss and follow the naming pattern $bg-{name}:

Variable	Class	Visual
`$bg-vicious-stance`	`bg-vicious-stance`	Charcoal → steel
`$bg-midnight-bloom`	`bg-midnight-bloom`	Midnight blue gradient
`$bg-sunny-morning`	`bg-sunny-morning`	Yellow → orange
`$bg-plum-plate`	`bg-plum-plate`	Deep plum gradient
`$bg-mean-fruit`	`bg-mean-fruit`	Pink → coral
`$bg-night-fade`	`bg-night-fade`	Soft pink → lavender
`$bg-malibu-beach`	`bg-malibu-beach`	Teal → blue

Use any gradient as a background class in markup: <div class="bg-sunny-morning">. To add a new gradient, define $bg-my-name in _variables.scss and add a matching .bg-my-name rule in a partial like src/assets/elements/_utilities.scss.

Icon Gradient Backgrounds

Stat-card icons throughout ArchitectUI use .icon-gradient combined with a gradient class. The pattern:

<i class="pe-7s-car icon-gradient bg-mean-fruit"></i>

.icon-gradient applies a background-clip: text mask so the icon takes the gradient's colors. Combine with any bg-* gradient class.

Next Steps

See Adding Pages to wire a custom theme into a new page, or Handlebars Partials to learn how the template chrome composes.