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.
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
Dark
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.
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
| Token | Where it is used |
|---|---|
--nui-background | Application or themed container background. |
--nui-surface | Secondary background for grouping content. |
--nui-foreground | Default text color. |
--nui-muted-foreground | Color for secondary text and descriptions. |
--nui-muted | Subtle highlight. Defaults to the primary tone’s soft background. |
--nui-border | Dividers and surface borders. |
--nui-control-border | Default border for fields and controls. |
--nui-control-border-hover | Control border on hover. |
--nui-disabled-background | Background for disabled controls. |
--nui-disabled-foreground | Text and icons in disabled controls. |
--nui-disabled-border | Border 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.
| Token | Where it is used |
|---|---|
--nui-{tone} | Solid background for an action or status. |
--nui-{tone}-hover | Solid background on hover. |
--nui-{tone}-soft | Soft background for elements such as badges and notices. |
--nui-{tone}-soft-hover | Soft background on hover. |
--nui-{tone}-soft-active | Soft background when pressed or selected. |
--nui-{tone}-border | Tinted border, such as an outline button border. |
--nui-{tone}-border-hover | Tinted border on hover. |
--nui-{tone}-text | Tinted text and icons on soft or neutral backgrounds. |
--nui-{tone}-text-strong | Stronger tinted text. |
--nui-{tone}-focus | Focus color for the tone. |
--nui-on-{tone} | Text and icons on the tone’s solid background. |
--nui-{tone}-1 … --nui-{tone}-12 | Twelve-step scale used by the tone’s state tokens. |
--nui-chart-1 … --nui-chart-5 | Chart 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
| Token | Where it is used |
|---|---|
--nui-font-sans | Default font family for text and inheriting controls. |
--nui-font-mono | Monospace 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-tight | Letter spacing for compact headings. Defaults to −0.025em. |
Spacing and geometry
| Token | Where it is used |
|---|---|
--nui-space-unit | Base 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-gap | Space between title and description in compact headers such as Card and Dialog. |
--nui-resizable-handle-size | Thickness of the draggable Resizable separator. |
--nui-toast-width / --nui-popover-width / --nui-hover-card-width | Reference widths for Toast, Popover, and HoverCard. |
Focus, motion, and elevation
| Token | Where it is used |
|---|---|
--nui-focus-ring / --nui-focus-width / --nui-focus-offset | Color, thickness, and offset of the focus outline. |
--nui-motion-duration / --nui-motion-easing | Default transition duration and easing, 150ms and cubic-bezier(0.4, 0, 0.2, 1). |
--nui-elevated-border / --nui-elevated-shadow | Border and shadow for elevated surfaces such as Card. |
--nui-overlay-backdrop / --nui-overlay-shadow | Backdrop behind modals and shadow around the panel. |
--nui-popover-shadow / --nui-tooltip-shadow / --nui-hover-card-shadow / --nui-toast-shadow | Shadows for each type of overlay. |
--nui-tooltip-background / --nui-tooltip-foreground | Tooltip background and text. |
--nui-z-overlay / --nui-z-popover / --nui-z-hover-card / --nui-z-tooltip | Stacking order of overlays. |
--nui-loading-track / --nui-progress-track | Track backgrounds for loading and progress indicators. |