#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
  • Main theming file
    • Creating a new main theme
    • Run the Portal with a different theme
  • 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.

#Main theming file

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

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

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

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

#Creating a new main theme

First, duplicate or create a new SCSS file inside:

• dnb-eufemia/src/style/themes/theme-[YOUR-THEME]/dnb-theme-basis.scss
• dnb-eufemia/src/style/themes/theme-[YOUR-THEME]/dnb-theme-components.scss

Do the same with every component you want to customize, and run yarn build. All the related component theme file will then be included in that main theme file.

During package build, a CSS bundle will be created.

#Run the Portal with a different theme

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

• Change the theme name in the Plugin options (defaultTheme).
• In the Portal Tools you can switch to a different theme.
• You can also define a different theme in the url itself path/?dnb-theme=ui.
• Create a new /packages/dnb-design-system-portal/.env file that includes e.g. GATSBY_THEME_STYLE_DEV=eiendom and start the portal with $ yarn start.

#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'
import 'dnb-eufemia/style/components'

// See the "src" in the path?
import 'dnb-eufemia/src/style/themes/theme-ui/dnb-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.