Theme

The template already includes a theme: shared colors, surfaces and styles for controls such as buttons and inputs. Using shared values keeps those elements consistent when you change the design.

Light and dark mode are two color schemes for that design. The app's default mode and text direction are configured separately from its visual styles.

Adjust colors

For a small change, edit the --nui-* values in the light and dark sections of src/styles/base.css. These are shared CSS variables, often called design tokens: each name describes a role rather than one specific screen.

For example, the primary color is used by primary actions. A different primary palette could use:

--nui-primary: #0f766e;
--nui-primary-foreground: #ffffff;
--nui-primary-hover: #115e59;
--nui-primary-active: #134e4a;
--nui-primary-soft: rgb(15 118 110 / 10%);

The foreground value is the text color on that primary background. Update the related hover, active and soft values together so the interaction states still belong to the same palette.

Adjust the light and dark sections as needed; add a value in the dark block when it should differ from the shared value.

Use classes such as bg-background, text-foreground and bg-primary in new UI so it follows the theme. Fixed color values in a page will keep their own colors. The Theming reference explains the other color roles and component options.

Mode and direction

Set the starting appearance under theme.default in src/configs/app.config.ts:

These are defaults: a user's saved appearance choices take precedence.

For custom UI, use Tailwind's dark variant when an element needs an additional dark-mode style. For right-to-left support, use logical margin and padding classes such as ms-*, me-*, ps-* and pe-*, which follow the start and end edges of the layout. Changing direction does not translate your text.

Start with Theme Workbench

If you want a different starting theme, visit Theme Workbench. Choose a design and adjust it in the preview, then open Code and Download your choices.

The download contains three files:

Update the stylesheet

Copy the exported base.css to src/styles/base.css. The template already imports this stylesheet. If you have added your own CSS, carry those changes forward when replacing it. For later color edits, use the final light and dark blocks at the end of the exported stylesheet.

Apply the component settings

The template already has a ThemeProvider in src/app/layout.tsx. Copy the classNames and componentDefaults objects from the downloaded file's config object into its themeValue prop.

classNames adds styling to named parts of components. componentDefaults supplies default props, such as a button variant, when a component does not set its own value.

This small example shows where those settings go. Replace its two objects with the complete objects from your download:

<ThemeProvider
  theme={theme}
  onThemeChange={setTheme}
  themeValue={{
    classNames: {
      button: { root: 'tracking-tight' },
    },
    componentDefaults: {
      button: { variant: 'solid' },
    },
  }}
>
  {children}
</ThemeProvider>

Keep the existing theme and onThemeChange props so the app's appearance controls continue to work. Copying only the stylesheet leaves out the component settings from the export.

If you changed direction in the preview, set the app default as described in Mode and direction above. Load any newly chosen font as described in App settings.

Keep the downloaded files together as a reference. Record the relevant visual rules from the exported DESIGN.md in your project's root DESIGN.md, preserving any existing project instructions. See Using with AI for how the agent uses that guidance.