Theme System

NuvoUI's theme system provides a powerful yet simple way to create consistent, adaptable interfaces. Through CSS variables and semantic tokens, you can create themes that respond to user preferences and maintain design consistency.

Configuration

The theme system is built around a set of configurable SCSS variables that determine theme behavior:

Variable	Default	Description
`$generate-utility-classes`	`true`	Controls generation of utility classes for theme tokens
`$enable-dark-mode`	`true`	Controls whether dark theme support is enabled
`$theme-tokens`	map keys from `$light-theme`	List of theme token names to be generated as CSS variables
`$light-theme`	Theme map	Default light theme token values
`$dark-theme`	Theme map	Default dark theme token values

Theme Tokens

Theme tokens are semantic variables that represent design concepts rather than specific colors or values. They create an abstraction layer between your design intent and the specific implementation.

--bg-baseMain page background

--bg-surfaceCard/component surfaces

--bg-alternateContrast to background

--border-baseUI element borders

--text-colorMain text color

--text-mutedSecondary text color

Available Theme Tokens

NuvoUI provides the following core theme tokens:

Token Name	Purpose	Usage Example
`--bg-base`	Main page background color	`background-color: var(--bg-base);`
`--bg-alternate`	Primary contrast color to background	`background-color: var(--bg-alternate);`
`--bg-surface`	Card and element backgrounds	`background-color: var(--bg-surface);`
`--border-base`	Border colors for UI elements	`border: 1px solid var(--border-base);`
`--text-color`	Main text color	`color: var(--text-color);`
`--text-muted`	Secondary, less emphasized text	`color: var(--text-muted);`

Using Themes

Themes are applied using the data-theme attribute on the HTML or body element:

Create components that adapt to the current theme by using theme tokens:

Theme Switching

NuvoUI makes it easy to implement theme switching. Here's a simple implementation:

Respecting User Preferences

You can also detect and respect the user's system preferences:

Pro Tip

To avoid a flash of incorrect theme on page load, consider adding a script in the <head> that sets the theme before the page renders.

Creating Custom Themes

You can create custom themes by defining your own sets of theme tokens that match the required token schema:

Extending the Theme System

To extend the theme system with your own tokens, modify the $theme-tokens list and your theme maps:

Theme Utility Classes

NuvoUI automatically generates utility classes for all theme tokens when $generate-utility-classes is enabled. These classes follow a consistent naming pattern:

Class Pattern	Example	Description
`.{token-name}`	`.bg-base`	Applies the theme token to the appropriate CSS property
`.hover\:{token-name}:hover`	`.hover\:bg-base:hover`	Applies the token on hover
`.group:hover .group-hover\:{token-name}`	`.group:hover .group-hover\:bg-base`	For applying styles when parent has .group class and is hovered
`.inverted-{token-name}`	`.inverted-bg-base`	Applies the inverted theme token value

Token to CSS Property Mapping

The system automatically maps tokens to CSS properties based on their prefix:

Token Prefix	CSS Property
`bg-`	`background-color`
`text-`	`color`
`border-`	`border-color`

Advanced Theme Features

Theme Transition

Add smooth transitions between themes:

Enhanced Contrast Mode

Support users who prefer enhanced contrast:

Theme Mixins Example

Create mixins for common theme-aware patterns:

SCSS API Reference

Variables & Maps

Variable	Description
`$theme-tokens`	List of theme token names to be generated as CSS variables (extracted from `$light-theme` by default)
`$light-theme`	Map of token values for the light theme
`$dark-theme`	Map of token values for the dark theme
`$enable-dark-mode`	Controls whether dark theme support is enabled
`$generate-utility-classes`	Controls generation of utility classes for theme tokens
`$parent-selector`	Optional parent selector to scope theme styles (defaults to empty string)

Functions

Function	Description
`validate-theme-tokens($theme-map, $required-tokens)`	Validates that a theme map contains all required tokens

Best Practices

Theme Design Guidelines

Use semantic token names that describe their purpose, not their appearance (e.g., --bg-surface not --light-gray)
Maintain color relationships consistently between themes
Test themes for sufficient contrast and readability
Provide a consistent user experience across themes - layout shouldn't change dramatically
Consider adding support for high contrast mode and reduced motion preferences

Implementation Tips

Use CSS variables for all themeable properties
Avoid using colors directly in component styles
Provide sensible defaults for all theme tokens
Consider adding transitions for theme changes
Always respect user preferences saved in local storage

Configuration​

Theme Tokens​

Available Theme Tokens​

Using Themes​

Theme Switching​

Respecting User Preferences​

Creating Custom Themes​

Extending the Theme System​

Theme Utility Classes​

Token to CSS Property Mapping​

Advanced Theme Features​

Theme Transition​

Enhanced Contrast Mode​

Theme Mixins Example​

SCSS API Reference​

Variables & Maps​

Functions​

Best Practices​

Theme Design Guidelines​

Implementation Tips​