Tokens, theming and white-labelling

To enable theming and white-labelling, NeUI comes with a set of tokens for most use-cases.

The base for all these is provided by open-props, which defines a relatively extensive amount of tokens for most cases where you could wish to use them.

Through stitches' API, all of the predefined tokens are available within the styled and css functions' autocomplete.

Using tokens, even without a predefined design system gives us multiple advantages, as it enables:

1. White-labelling
2. Theming (as in light and dark themes)

Since the latter is self-explanatory, we will take a look at how to do the former below.

White-labelling

Obviously, since we want to use NeUI for many different projects and customers, we don't want to keep the default styling. But, since we have a token system at the base of NeUI, it is easy to change the look and feel of an application.

Let's say, for our use-case of, for example a bank, we have a certain yellow color as a primary color, a certain text color and a certain background color for both light and dark modes.

We also have predefined text sizes and spacings for components that we want to use.

Because NeUI already comes with an extensive set of tokens which are baked into our components, we don't have to define an entire design system here (although we can!). All we need to do is override the values that are specifically different in our branding.

We could add the following code in our project to achieve this:

import { createTheme, light, dark } from "@neui/styling";

const color = {
    // Custom yellow color
    "yellow-1": "#FBF5B6",
    "yellow-2": "#FBF18A",
    "yellow-3": "#FBED5D",
    "yellow-4": "#FCEB2F",
    "yellow-5": "#FFE900",
    "yellow-6": "#F9D400",
    "yellow-7": "#F2BF00",
    "yellow-8": "#ECAC00",
    "yellow-9": "#E69900",

    // Custom petrol color
    "petrol-1": "#002622",
    "petrol-2": "#003839",
    "petrol-3": "#00414C",
    "petrol-4": "#1E5760",
    "petrol-5": "#3D6D75",
    "petrol-6": "#5B8389",
    "petrol-7": "#78999E",
    "petrol-8": "#96AFB3",
    "petrol-9": "#B4C5C8",
    
    // Make yellow color primary
    "primary-1": "$yellow-1",
    "primary-2": "$yellow-2",
    "primary-3": "$yellow-3",
    "primary-4": "$yellow-4",
    "primary-5": "$yellow-5",
    "primary-6": "$yellow-6",
    "primary-7": "$yellow-7",
    "primary-8": "$yellow-8",
    "primary-9": "$yellow-9",
    
    // Make petrol color neutral
    "neutral-1": "$petrol-1",
    "neutral-2": "$petrol-2",
    "neutral-3": "$petrol-3",
    "neutral-4": "$petrol-4",
    "neutral-5": "$petrol-5",
    "neutral-6": "$petrol-6",
    "neutral-7": "$petrol-7",
    "neutral-8": "$petrol-8",
    "neutral-9": "$petrol-9",
}

const fontFamily = {
    "sans": "'Gotham Medium', 'Helvetica Neue', 'Arial', sans-serif",
    "book": "'Gotham Book', 'Helvetica Neue', 'Arial', sans-serif",
};


export const commonTheme = {
  color,
  fontFamily
};

const lightThemeValues = {
    ...commonTheme,
    colors: {
        ...commonTheme.colors,
        ...light
    }
}

const darkThemeValues = {
    ...commonTheme,
    colors: {
        ...commonTheme.colors,
        ...dark
    }
}


export const lightTheme = createTheme(lightThemeValues);

export const darkTheme = createTheme(darkThemeValues);

Notice that we export both a light- and dark-theme. These exported constants can be used as a class to either set conditionally at the root of your page if we want a site-wide theme-switch or per section if we want a page with changing themes per content.

We can implement both of these like so:

Page-wide theme

import {defaultTheme, lightTheme, darkTheme} from 'your-theme';

function App() {
    const [theme, setTheme] = useState<"light" | "dark">("light");

    const usedTheme = theme === "light" ? lightTheme : darkTheme;

    return (
        <div className={`${defaultTheme} ${usedTheme}`}>
            {/* your page content */}
        </div>
    )
}

Section-wide theme

import {defaultTheme, lightTheme, darkTheme} from 'your-theme';

function App() {
    return (
        <div className={`${defaultTheme}`}>
            <section className={`${lightTheme}`}>
                {/* Light theme section content */}
            </section>
            <section className={`${darkTheme}`}>
                {/* Dark theme section content */}
            </section>
        </div>
    )
}

Notice that we always need to use the defaultTheme at the root of our page to expose all of NeUIs CSS variables for our themes to use.