Skip to content
Home

Maintaining themes#

This section contains documentation about how to maintain and create a theme.

You may also check out the section about how to use a theme in your application.

Basis information#

The default DNB brand theme is called: ui which stands for universal identity.

The building blocks#

A theme consists of several files, which again includes SCSS import declarations to single component styles.

To include new or update component themes, run yarn build.

It will find all related theme styles and put it inside the main theme file so they can get compiled to one CSS bundle.

Defining a fallback#

Depending on the need of a theme, you can define a fallback to another theme.

It will use that fallback theme as a basis, but use your new theme styles instead – as soon as one exists with the same name.

Define a fallback inside a theme set:

  • dnb-eufemia/src/style/themes/sbanken/sbanken-theme-components.scss
/**
 * ATTENTION: This file is auto generated by using "themeFactory".
 * But you still can change the content of this file on the very top.
 */


$THEME_FALLBACK: 'ui';


/**
 * NB: The content below is auto generated by the "themeFactory".
 * You may want to update it by running "yarn build" locally.
 */


@use '<auto-generated>/dnb-button-theme-ui.scss';

and as soon as e.g. dnb-button-theme-sbanken.scss exists – it will be used instead of dnb-button-theme-ui.scss.

Main theming file#

There is one Main Theme File, that includes all properties and element styles:

  • dnb-eufemia/src/style/themes/ui/ui-theme-basis.scss

Creating a new main theme#

First, duplicate or create new SCSS files:

  • dnb-eufemia/src/style/themes/<YOUR-THEME>/<YOUR-THEME>-theme-basis.scss

Do the same with every component (button etc.) you want to customize:

  • dnb-eufemia/src/components/button/style/themes/dnb-button-theme-<YOUR-THEME>.scss

and run yarn build. All the related component theme file will then be created or updated.

Run the Portal with a different theme#

Theme switching in the Portal is handled by the Vite theme handler shim (vite/client/shims/theme-handler.ts) together with vite-plugin-eufemia-theme. Switching enables the selected theme's stylesheet and disables the others — each theme is a separate <style> (dev) or lazy-loaded <link data-eufemia-theme="<name>"> (production) element — and sets an eufemia-theme__<brand> class on <body>.

  • In the Portal Tools you can switch to a different theme (runtime).
  • You can also define a different theme in the URL itself path/?eufemia-theme=eiendom (runtime).

Component theming#

All components have a style separation of:

  • layout where positioning and raw shapes are defined.
  • skinning where colors and peculiarity are defined.

This way we can create more easily custom skinned themes.

Button as an example#

  • All the raw layout related CSS properties are in this one file dnb-button.scss.
  • While the theme file dnb-button-theme-ui.scss contains colorization and font sizes (skinning).
/button/style/dnb-button.scss // layout styles
/button/style/themes/dnb-button-theme-ui.scss // main theme styles
/button/style/themes/dnb-button-theme-eiendom.scss// additional theme styles

How eiendom is set up does not matter. It could either import parts from ui or be maintained independently.

CSS custom properties and :root#

Whenever possible use Eufemia Properties inside Eufemia components.

When defining custom properties for a component, prefer to put them inside the component scope:

.dnb-button {
  --text-size: var(--font-size-medium);
}

In some circumstances, you may make them share-able and place them inside :root. They should then contain the component-name as a prefix.

Local Theming setup#

There are several solutions to create a new theme. One of which is by using the linking feature of Yarn.

yarn link and SCSS#

Make sure your project can handle *.scss files.

1. make a copy of the repository. Place it somewhere locally on your machine

2. change your command line (Terminal) directory to the sub package @dnb/eufemia (eufemia/packages/eufemia)

3. make the package ready for development by running:

$ yarn install && yarn build && yarn link

4. on your application root directory, run:

$ yarn link "@dnb/eufemia"

5. That's it. Now you can use (import/require) the NPM module in your application like:

import { Button } from 'dnb-eufemia/components'


// See the "src" in the path?
import 'dnb-eufemia/src/style/themes/ui/ui-theme-[MY THEME].scss'

6. Don't forget to add "@dnb/eufemia": "*" with the respective version (alongside React) to your dependencies:

  "dependencies": {
    "@dnb/eufemia": "x",
    "react": "x",
    "react-dom": "x",
    ...
  }

Chrome Extension: Eufemia Theme Manager#

Use the Chrome Browser Extension to:

  • test themes on web applications
  • create new possible themes
  • look how the outcome would be if a theme would be used
  • and create areas where a different or a modified theme would make more sense

You can also download the Chrome Browser Extension (ZIP), and install it manually in your browser. To do so, go to chrome://extensions and drag & drop the downloaded ZIP file in the opened extensions tab.

Contributions are welcome. Here's the source code.

Suggest an edit