Themes and tokens

Learn how NewUI uses CSS variables to define colors, sizing, and typography.

What are themes and tokens?

Tokens are CSS variables that store design decisions such as an action color, a button radius, or a font. A theme sets those values for an entire interface or for one section.

Token names describe what a value does. A button with tone="primary" reads the primary action tokens. When the palette changes, components keep their meaning and pick up the new colors.

Token reference

Light, dark, and system

Use data-nui-theme="light", data-nui-theme="dark", or data-nui-theme="system". On the root, the attribute applies to the document. On a section, it applies to that section and its descendants. NewUI follows the system preference by default.

<html data-nui-theme="system">
  <body>
    <section data-nui-theme="dark">...</section>
  </body>
</html>

Apply your product’s visual identity

Use createTheme to select a palette and override tokens. The function returns a CSS variable object. Apply it with style on a container to scope the effect to that section.

The same palette in two modes

Light

In progress

Dark

In progress
import { Badge, Button } from "@egcs/newui";
import { createTheme } from "@egcs/newui/theme";

const theme = createTheme({
  "primary": "green",
  "tokens": {
    "radiusMd": "0.75rem"
  }
});

export default function ThemedSection() {
  return (
    <section style={theme}>
      <Button tone="primary">Continue</Button>
      <Badge variant="soft" tone="primary">In progress</Badge>
    </section>
  );
}

A palette sets color roles together, including solid background, hover, borders, and text. For custom colors, adjust related states and check contrast. Changing the primary color alone affects the components and states that read that token.

Set tokens in global CSS

Place overrides on :root after loading NewUI’s styles. When choosing a font, load the font family in your project. The token tells the application which font to use.

:root {
  --nui-radius-md: 0.75rem;
  --nui-space-unit: 0.25rem;
  --nui-font-sans: "Inter", system-ui, sans-serif;
}

With the optional Tailwind preset, utilities such as bg-surface and rounded-md read the same tokens. Components already read these values with the compiled CSS.

Try the theme editor

Token reference

Use names prefixed with --nui- in CSS. In createTheme({ tokens: … }), API names use camelCase, such as radiusMd and primarySoft. Component tokens such as popover shadows and chart series colors can be set directly in CSS.

Surfaces and text

TokenWhere it is used
--nui-backgroundApplication or themed container background.
--nui-surfaceSecondary background for grouping content.
--nui-foregroundDefault text color.
--nui-muted-foregroundColor for secondary text and descriptions.
--nui-mutedSubtle highlight. Defaults to the primary tone’s soft background.
--nui-borderDividers and surface borders.
--nui-control-borderDefault border for fields and controls.
--nui-control-border-hoverControl border on hover.
--nui-disabled-backgroundBackground for disabled controls.
--nui-disabled-foregroundText and icons in disabled controls.
--nui-disabled-borderBorder for disabled controls.

Semantic colors

In the table, {tone} can be primary (primary action), neutral (neutral action), info (information), success (success), warning (attention), or danger (error or destructive action). For example, --nui-danger-soft is the soft background for the danger tone.

TokenWhere it is used
--nui-{tone}Solid background for an action or status.
--nui-{tone}-hoverSolid background on hover.
--nui-{tone}-softSoft background for elements such as badges and notices.
--nui-{tone}-soft-hoverSoft background on hover.
--nui-{tone}-soft-activeSoft background when pressed or selected.
--nui-{tone}-borderTinted border, such as an outline button border.
--nui-{tone}-border-hoverTinted border on hover.
--nui-{tone}-textTinted text and icons on soft or neutral backgrounds.
--nui-{tone}-text-strongStronger tinted text.
--nui-{tone}-focusFocus color for the tone.
--nui-on-{tone}Text and icons on the tone’s solid background.
--nui-{tone}-1 … --nui-{tone}-12Twelve-step scale used by the tone’s state tokens.
--nui-chart-1 … --nui-chart-5Chart series colors in display order.

Steps 1 through 12 range from subtle backgrounds to high-contrast text. Use state tokens to style components. They already pick the step for the role and color mode.

Typography

TokenWhere it is used
--nui-font-sansDefault font family for text and inheriting controls.
--nui-font-monoMonospace family for code and other technical text.
--nui-font-size-{xs, sm, base, lg, xl, 2xl, 3xl, 4xl, 5xl}General text scale, from 0.75rem to 3rem.
--nui-font-size-{display-sm, display-md}Display headings. Defaults are 2rem and 2.5rem.
--nui-font-weight-{normal, medium, semibold}Default weights of 400, 500, and 600.
--nui-leading-{tight, snug, normal, relaxed}Default line heights of 1.25, 1.375, 1.5, and 1.625.
--nui-tracking-tightLetter spacing for compact headings. Defaults to −0.025em.

Spacing and geometry

TokenWhere it is used
--nui-space-unitBase of 0.25rem for numeric spacing and sizing. Changing it also affects widths and heights that use the scale.
--nui-radius-{xs, sm, md, lg, xl, 2xl, 3xl, 4xl}Corner radius, from 0.125rem to 2rem. Button defaults to md and Card to xl.
--nui-control-height-{xs, sm, md, lg}Control heights by size. Defaults are 1.5rem, 2rem, 2.5rem, and 3rem.
--nui-header-gapSpace between title and description in compact headers such as Card and Dialog.
--nui-resizable-handle-sizeThickness of the draggable Resizable separator.
--nui-toast-width / --nui-popover-width / --nui-hover-card-widthReference widths for Toast, Popover, and HoverCard.

Focus, motion, and elevation

TokenWhere it is used
--nui-focus-ring / --nui-focus-width / --nui-focus-offsetColor, thickness, and offset of the focus outline.
--nui-motion-duration / --nui-motion-easingDefault transition duration and easing, 150ms and cubic-bezier(0.4, 0, 0.2, 1).
--nui-elevated-border / --nui-elevated-shadowBorder and shadow for elevated surfaces such as Card.
--nui-overlay-backdrop / --nui-overlay-shadowBackdrop behind modals and shadow around the panel.
--nui-popover-shadow / --nui-tooltip-shadow / --nui-hover-card-shadow / --nui-toast-shadowShadows for each type of overlay.
--nui-tooltip-background / --nui-tooltip-foregroundTooltip background and text.
--nui-z-overlay / --nui-z-popover / --nui-z-hover-card / --nui-z-tooltipStacking order of overlays.
--nui-loading-track / --nui-progress-trackTrack backgrounds for loading and progress indicators.