Your own colors
Set every nxds color yourself, in one CSS file, when your palette needs more than a brand color and a surface tone.
Create the colors file
init makes three changes:
| Change | File |
|---|---|
| Writes every nxds color, light and dark, from your theme | nxds-colors.css, beside nxds.css |
| Imports the colors file | nxds.css |
| Stops nxds deriving colors from your brand color | app/layout.tsx on Next.js, src/main.tsx and nxds.vite.ts on Vite |
init and update never change the colors file again. After an update,
doctor names each color the new release added, so you can set it.
If init can't find your provider, it lists the prop to add by hand.
Change a color
Each color has a light value under :root and a dark value under .dark:
Keep the @layer theme wrapper, so the density, corners and elevation settings
keep working.
Color says what each color is for.
nxds doesn't check the contrast of colors you set. Check each text color against its background.
Settings that keep working
| Appearance field | With your own colors |
|---|---|
mode | Works |
density, corners, elevation, stroke | Work |
uiScale, textSize and the fonts | Work |
brandColor, surfaceTone, contrast | No effect |
The provider saves the user's choices and applies them before the page paints.
NxdsAppearanceSettings and NxdsThemeQuickControl hide their brand color,
surface tone and contrast controls. In a settings screen of your own, hide them
when deriveColors from useNxdsAppearance is false.
Change shadows, corners or spacing
nxds.css sets these tokens once for each value of a setting, such as
[data-shadow='standard']. Redefine a value in the colors file, with the same
selector:
The other elevation values keep their nxds shadows.
| Tokens | Selector | Applies |
|---|---|---|
--nx-borderwidth-* | [data-borderwidth='normal'] | At every UI scale |
--nx-shadow-* | [data-shadow='standard'] and its two .dark forms | At every UI scale |
--nx-radius-* | [data-radius='subtle'] | At the Default UI scale only |
--nx-spacing-* | [data-density='default'] | At the Default UI scale only |
To set a token for every value of a setting, use :root. That setting then
stops changing the token.
Set it up by hand
Follow these steps for a Vue app, or when you don't use the CLI.
Add the colors file
Copy every --nx-color-* line from the :root and .dark blocks of nxds.css:
Import the colors file
Import the colors file after nxds.css:
Turn color derivation off
Pass deriveColors={false} to the script and the provider:
On Vite, pass deriveColors: false to createNxdsAppearance. In
vite.config.ts, pass { deriveColors: false } as the second argument of
createNxdsAppearanceSnapshotFromState.
Pass deriveColors: false to the plugin:
In vite.config.ts, pass { deriveColors: false } as the second argument of
createNxdsAppearanceSnapshotFromState.
Check your setup
-
npx nxds-cli@latest doctorprintsokforcolors - A color you change in
nxds-colors.csschanges on the page - Dark mode switches between your
:rootand.darkcolors
Next steps
- Material look: a Material-style settings screen, built this way.
- Ant Design look: an Ant Design-style admin page, built this way.
- Overrides: change the theme inside one element.
- Appearance: the settings that keep working.