Theming Overview

Use this page to identify which theming layer you need to touch in Nuvex UI: base themes, runtime, tokens, CSS variables, or custom themes.

Open Light and Dark ThemesOpen Runtime Theme API

What Theming covers

Theming starts once the library is already installed and rendering correctly, and now you need to adapt the appearance, control the active theme, or extend the system with new variants.

Base themes

Explains what already exists in light and dark before you try to redefine the system.

Runtime control

Lets you read, change, or persist the active theme from application code.

Design tokens

Help you decide which semantic value should change when you adjust color, surface, or brand intent.

CSS variables

Handle cascade overrides when the adjustment does not require a new theme.

Custom themes

Apply when the product needs an additional named variant beyond light and dark.

How to think about the theme system

The right way to understand Theming is not as isolated features, but as layers: first the baseline, then active-theme selection, then customization.

1. Start from the baseline

Nuvex UI already includes light and dark. That is the initial contract of the system.

2. Resolve the active theme

The initial theme can come from a stored preference, the system, or a configured default.

3. Decide whether the change is operational or visual

If you need to switch or persist the theme, you are in runtime. If you need to change how it looks, you are probably in tokens or CSS variables.

4. Adjust the right layer

Not every visual change needs a new theme. Sometimes tokens are enough; sometimes CSS variables are enough.

5. Create a new theme only when needed

A custom theme makes sense when the product needs another variant with its own identity, not when you are only refining the baseline.

Default behavior

Before you customize anything, it helps to know which behavior already exists without additional configuration.

  • Nuvex UI already includes light and dark themes out of the box.
  • The initial theme can resolve from storage, system preference, or a configured default theme depending on what is available.
  • Runtime theming is optional. A project can stay on the built-in baseline and still be fully valid.

Choose the next guide

Continue according to the kind of change you need to make.

I want to understand light and dark

Go to Light and Dark Themes if you first need to adopt the built-in baseline correctly.

I want to change the theme from code

Go to Runtime Theme API if you need a toggle, a selector, or runtime persistence.

I want to choose the right semantic layer

Go to Design Tokens if the change involves color, surfaces, or brand intent.

I want to override in CSS

Go to CSS Variables if the change belongs in the cascade rather than in theme registration.

I want to add a new variant

Go to Custom Themes if the product needs an additional named theme.

Build-time vs runtime

Most theming mistakes happen when you solve a real problem in the wrong layer. If the change modifies the default visual identity, think build-time. If it changes which theme is active during use, think runtime.

Build-time customization

Use this layer when you want to define the visual baseline before the app runs: Sass variables, token seeds, and stylesheet ordering.

Runtime customization

Use this layer when the app needs to select, change, or persist the active theme while users interact with the interface.

Mistakes worth avoiding

These mistakes usually come from mixing layers or using the wrong page to solve the problem.

  • Changing CSS variables first when the real decision should have been made at the token level.
  • Creating a brand-new theme when the product only needed to adjust light and dark.
  • Treating runtime and build-time as if they solved the same kind of problem.