Introduction

nxds is a framework-agnostic theme engine that ships components, not a component library with a theme added on.

You copy the components into your app and own them. The engine, @nxds/core, produces every token those components use, from one appearance object. Change your brand color, density or corner style, and every component follows.

Our philosophy

nxds rests on six ideas. Each one links to the page that explains it.

You own the components

Every component is source code you paste into your app and edit like any other file. To update one, paste the newer version over yours. Install shows how.

One engine makes every token

You don't write token values by hand. One function builds every color, hover shade and dark-mode value from your appearance settings, so light and dark can't drift apart. Tokens shows the pipeline.

Every axis is a setting

Density, corners, shadows, border width, type and motion are settings, just like color. "Make this product denser" is a one-field change, not a refactor. Appearance lists every field.

Contrast is checked, not eyeballed

Every text and background pair has a minimum contrast score, and CI fails the build when one drops below it. Color lists the minimum for each pair.

nxds fits next to your app

nxds CSS defines only nx: classes and --nx- variables, so your own styles stay as they are. Tokens explains the prefix, and Integrations shows nxds next to MUI, shadcn/ui and five other libraries.

Conventions are enforced, for people and agents

ESLint rules turn nxds conventions into build errors. See lint rules.

Every docs page is also available as Markdown. See AI agents.

nxds and shadcn/ui

The idea that you should own your component source comes from shadcn/ui. nxds shares that philosophy, and we're grateful for the work that made it popular.

Both use copy-and-own components, Radix primitives, CVA for variants and asChild for composition. nxds has its own theme engine, tokens and conventions:

When to use something else

nxds pays off when you have several products, several brands, or an app that must be re-themed per customer. For a smaller project, a simpler tool may fit better:

• One app, one theme. A theme engine is overhead you won't get back. Use shadcn/ui.
• You want a large ecosystem. Most community blocks and registries target shadcn/ui's token names.
• You need a screen today. nxds asks you to adopt its token conventions first.

FAQ

Is nxds a component library? Not in the usual sense. The components are copy-and-own source. The part you install from npm is the theme engine.

Do I need Tailwind? Yes. nxds builds its classes with Tailwind 4. Your app also needs a reset that sets box-sizing: border-box, such as Tailwind's Preflight or MUI's CssBaseline.

Do I have to replace my UI library? No. Add one nxds component next to MUI, shadcn/ui or another library, and keep the rest. See Integrations.

Does nxds work outside React? The engine does. It has no framework code, so any app can call it. The components ship for React, and a growing set ships for Vue. Each component page has a tab per framework. Svelte, Angular and React Native bindings are planned.

Can I use the tokens in a native app? The tokens are DTCG JSON (the W3C design token format), so Style Dictionary can build Swift and Kotlin output. Live theme changes on native need a port of the engine.

Can I use my own brand colors? Yes. Set brandColor to any CSS color, and nxds builds the palette from it.

Acknowledgements

nxds uses and learns from these open-source projects. Thank you to everyone who builds and maintains them.

Next steps

• Install: set up your app and copy in your first component.
• Tokens: how tokens are named and made.
• Playground: try a theme on every component, then copy it into your app.