Theming System

Create brand-specific designs with MoonUI's powerful theming system. Easy customization with CSS variables, preset themes, and real-time preview.

CSS VARIABLES

Design Tokens

Customize with CSS variables

globals.css

--primary: 262.1 83.3% 57.8%

HSL Color System

Flexible opacity control

Dark Mode Support

Automatic theme switching

PRESET THEMES

6 Presets

Professional themes ready to use

terminal

$ moonui theme --set corporate

Default Theme

Clean and modern

Corporate, Creative

Business & design focused

Theme Configuration

Set up and customize your theme

1. Configure in moonui.config.js

Choose a preset theme or create a custom one:

moonui.config.js

module.exports = {
  theme: {
    preset: 'corporate',
    // Available: 'default' | 'corporate' | 'creative'
    // 'nature' | 'minimal' | 'ocean'
  }
}

2. Generate Theme CSS

Run the CLI command to generate your theme:

terminal

$ moonui theme --generate

3. Import Generated CSS

Import the generated theme in your global CSS:

globals.css

@import 'moonui-theme.css';
@tailwind base;
@tailwind components;
@tailwind utilities;

Pro Tip

Use the PostCSS or Vite plugin for automatic theme generation during build time.

Design Token System

Comprehensive CSS variables for theming

Color Tokens

Primary Colors

--primaryBrand color

--secondarySecondary actions

--accentHighlights

Semantic Colors

--destructiveErrors

--successConfirmations

--warningCautions

--infoNeutral notices

--mutedDisabled

--backgroundPage bg

Soft-Tint Semantic Surfaces

A plain semantic token like --destructive is meant for a solid fill with light text on top. Menu items, toasts and badges need the opposite: a gentle tint with dark text. That is what the --*-subtle pairs are for. Each pair ships a surface and a matching foreground, in both light and dark themes, and both are part of the theme contract — override them and every component that uses them follows.

--destructive-subtle--destructive-subtle-foreground

Delete, remove, irreversible

--success-subtle--success-subtle-foreground

Saved, completed, healthy

--warning-subtle--warning-subtle-foreground

Needs attention, degraded

--info-subtle--info-subtle-foreground

Tips, neutral status

In Tailwind they surface as bg-destructive-subtle, text-destructive-subtle-foreground, border-success-subtle-foreground/20 and so on — the usual utility families all work, including the opacity modifier.

Picking the Right Token

There is no single “the success token”. Which one you reach for depends on whether the color carries a surface, text, or neither.

What you are building	Use
Soft tinted surface (menu item, toast, badge)	`bg--subtle` + `text--subtle-foreground`
Text only, no background of its own (a +12% delta, a status label, a semantic icon)	`text-*-subtle-foreground`
Solid fill with no text on it (status dot, timeline marker)	`bg-*`
Solid fill with text on it (filled tooltip, filled button)	`bg-` + `text--foreground`

Do not use a plain fill token as text color

text-warning and text-info are surface colors. On a white background they land well below the WCAG AA threshold for body text, so a label written in them is unreadable for many users. Row two of the table above is the fix: reach for text-warning-subtle-foreground instead.

Usage Example

/* HSL channels only — no hsl() wrapper, so the
   opacity modifier keeps working */
--primary: 217.2 91.2% 51%;
--destructive: 0 84.2% 48%;
--info: 217 91% 50%;

/* Soft-tint pair: surface + its own foreground */
--destructive-subtle: 0 93% 94%;
--destructive-subtle-foreground: 0 63% 31%;

/* Usage in CSS */
color: hsl(var(--primary));
background: hsl(var(--primary) / 0.1);

CLI Commands

Manage themes with MoonUI CLI

Theme Management

moonui theme --set [name]

Set a preset theme

moonui theme --generate

Generate theme CSS

moonui theme --list

List available themes

Custom Themes

moonui theme --create

Create custom theme

moonui theme --export

Export current theme

moonui theme --import

Import theme file

Theme Builder

Create custom themes visually with our theme builder

Component Gallery

See how components look with different themes