Tokens

Tokens are the named values every nxds component uses for color, spacing, radius, shadows, borders and motion.

Open the Token lab to browse every token in the current theme.

Token layers

Components use semantic tokens through utilities. A component that uses a primitive color fails the nxds lint rules.

The nx: prefix

Every nxds class starts with nx:, and every nxds variable starts with --nx-. nxds CSS defines nothing else, so it fits beside your own styles.

The prefix comes before every modifier:

Semantic names

A semantic name is a family, then a role, then an optional state:

Not every family has every role. The Token lab lists the ones that exist.

The primary button reads nx:bg-primary-background, then nx:hover:bg-primary-background-hover and nx:active:bg-primary-background-active. Every state has its own token, so there are no opacity modifiers like bg-primary/90.

Surfaces follow the same pattern:

The name always ends in a role. nx:bg-primary resolves to nothing.

One engine, two moments

deriveTheme() in @nxds/core produces every color token. It runs once at build time to write the default colors into nxds.css. It runs again in the browser whenever the appearance changes.

Same function, same inputs, same output. The page looks right with JavaScript off, and a live theme change needs no rebuild.

Spacing, radius, shadow, border and motion come straight from DTCG JSON (the W3C design token format). nxds.css holds every density, corner, shadow and border option, and the provider picks one with a data attribute. The appearance state is the object described in Appearance.

1. Token sources. DTCG JSON for color, spacing, radius, shadow, border and motion.

   Appearance state. Brand color, surface tone, mode, density and the other fields.

2. ↓

   deriveTheme() in @nxds/core. Builds the color palettes, picks each surface shade and checks contrast. No DOM, no framework.

3. ↓

   Build time. Default colors and every spacing, radius, shadow and border option written into nxds.css.

   Runtime. Color variables and data attributes the provider writes when the appearance changes.

4. ↓

   nx: utilities. One set of classes that reads whichever value is present.

5. ↓

   React components. Copy-and-own source built on the utilities.

Light and dark come from the same call, so dark mode can't drift from light.

Other frameworks

The engine has no framework or DOM code. Another framework needs three functions:

• createNxdsThemeContract() turns the appearance state into the engine's input.
• deriveTheme() returns the light and dark color token maps.
• themeToCss() turns those maps into CSS.

An app that styles itself without CSS, like a React Native app, reads the color token map and the DTCG files directly. Every framework gets the same values, so a React app and a Vue app in one product render the same gray.

The nxds components are React.

Next steps

• Color: how the palette is built and checked.
• Appearance: every field the engine reads.
• Token lab: every token in the current theme.