#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.

• Maintaining themes
  • Basis information
  • The building blocks
    • Defining a fallback
  • Main theming file
    • Creating a new main theme
    • Run the Portal with a different theme
    • Show theme tag in Portal
  • Component theming
    • Button as an example
    • CSS custom properties and :root
  • Local Theming setup
    • yarn link and SASS
  • Chrome Extension: Eufemia Theme Manager

#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 SASS 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/theme-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.
 */

@import '<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/theme-ui/ui-theme-basis.scss

#Creating a new main theme

First, duplicate or create new SCSS files:

• dnb-eufemia/src/style/themes/theme-<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

What theme gets imported is handled in the Gatsby Plugin gatsby-plugin-eufemia-theme-handler.

• 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).
• Change the theme defaultTheme name in the plugin options inside gatsby-config (build-time).
• Create a new /packages/dnb-design-system-portal/.env file that includes e.g. GATSBY_EUFEMIA_THEME=eiendom (build-time).

#Show theme tag in Portal

Add the property theme: 'sbanken' to the main .mdx file for a Portal page to show a tag next to it when that theme is selected. This is currently mainly intended for Sbanken.

Example: /docs/components/button.mdx

---
title: 'Button'
description: 'The Button component should be used as the primary call-to-action in a form, or as a user interaction mechanism.'
showTabs: true
theme: 'sbanken'
---

#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 SASS

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/theme-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. Heres the source code.