NNexusDocumentation
Live demo
GuideCustomize

Theme & Styling

Know when to edit page CSS, shared design-system CSS, tokens, dark mode, and the optional UI release.

12 min readCustomizeUpdated for Nexus 0.1
On this page 5

What you will learn

  • Choose the correct stylesheet.
  • Change theme tokens safely.
  • Avoid unnecessary CDN releases.

Two CSS layers

app/globals.css is the canonical shared Nexus UI design system. It contains tokens and reusable primitives used across pages.

app/template.css is loaded afterward and contains template-specific page layouts and targeted overrides. New page styling normally belongs here.

text
app/globals.css   -> shared tokens and reusable UI primitives
app/template.css  -> application pages and local layout rules

Use existing tokens

Build new surfaces from semantic variables so light mode, dark mode, and custom primary colors continue to work.

css
.report-card {
  border: 1px solid var(--border);
  background: var(--surface);
  color: var(--text);
}

.report-card p {
  color: var(--muted);
}

Change a shared primitive

A change to global buttons, dialogs, inputs, typography, colors, or reusable surface tokens is a design-system change.

  1. Edit app/globals.css.
  2. Increment the version in nexus-ui.config.json.
  3. Run pnpm ui:build for local verification.
  4. Run pnpm check.
  5. Authorized maintainers may then run pnpm ui:release and update the demo environment.

Theme persistence

Theme and layout preferences are bootstrapped in app/layout.tsx before the page paints, then managed by the application shell. Storage failures fall back to safe defaults.

  • Test light, dark, and system modes.
  • Test every supported primary color.
  • Confirm no light flash before dark mode loads.
  • Keep focus indicators visible in every theme.

Continue learning