From e573a11133672bf520e5741fc74a3217ec859fae Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Tobias=20H=C3=B8egh?= Date: Mon, 13 Mar 2023 14:20:22 +0100 Subject: [PATCH 1/6] docs: add docs about how to maintain theming + update docs on consuming a theme --- .../docs/contribute/style-guides/theming.mdx | 148 ++++++++++++++++++ .../uilib/usage/customisation/theming.mdx | 140 ++--------------- 2 files changed, 158 insertions(+), 130 deletions(-) create mode 100644 packages/dnb-design-system-portal/src/docs/contribute/style-guides/theming.mdx diff --git a/packages/dnb-design-system-portal/src/docs/contribute/style-guides/theming.mdx b/packages/dnb-design-system-portal/src/docs/contribute/style-guides/theming.mdx new file mode 100644 index 00000000000..188ba8797d6 --- /dev/null +++ b/packages/dnb-design-system-portal/src/docs/contribute/style-guides/theming.mdx @@ -0,0 +1,148 @@ +--- +title: 'Theming' +order: 6 +--- + +# 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](/uilib/usage/customisation/theming/). + +- [Maintaining themes](#maintaining-themes) + - [Basis information](#basis-information) + - [Main theming file](#main-theming-file) + - [Creating a new main theme](#creating-a-new-main-theme) + - [Run the Portal with a different theme](#run-the-portal-with-a-different-theme) + - [Component theming](#component-theming) + - [Button as an example](#button-as-an-example) + - [CSS custom properties and :root](#css-custom-properties-and-root) + - [Local Theming setup](#local-theming-setup) + - [yarn link and SASS](#yarn-link-and-sass) + - [Chrome Extension: Eufemia Theme Manager](#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 component themes, such as this one: `dnb-eufemia/src/style/themes/theme-ui/dnb-theme-ui.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-[YOUR-THEME].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 them 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_). + +```js +/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 + +Use when ever possible Eufemia Properties inside Eufemia components. + +When defining custom properties for a component, **prefer** to put them inside the component scope: + +```css +.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](https://yarnpkg.com/lang/en/docs/cli/link/). + +### yarn link and SASS + +Make sure your project can handle **\*.scss** files. + +**1.** make a copy of the [repository](https://github.com/dnbexperience/eufemia). 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: + +```bash +$ yarn install && yarn build && yarn link +``` + +**4.** on your application root directory, run: + +```bash +$ yarn link "@dnb/eufemia" +``` + +**5.** That's it. Now you can use (import/require) the NPM module in your application like: + +```js +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: + +```json + "dependencies": { + "@dnb/eufemia": "x", + "react": "x", + "react-dom": "x", + ... + } +``` + +## Chrome Extension: Eufemia Theme Manager + +Use the [Chrome Browser Extension](https://chrome.google.com/webstore/detail/eufemia-theme-manager/pijolaebmeacaekbhoefjmhogckdcclb) 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)](https://github.com/dnbexperience/eufemia-theme-manager/raw/main/eufemia-theme-manager-extension/web-ext-artifacts/eufemia_theme_manager-latest.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](https://github.com/dnbexperience/eufemia-theme-manager). diff --git a/packages/dnb-design-system-portal/src/docs/uilib/usage/customisation/theming.mdx b/packages/dnb-design-system-portal/src/docs/uilib/usage/customisation/theming.mdx index 97ca26a4c2f..e037cf32841 100644 --- a/packages/dnb-design-system-portal/src/docs/uilib/usage/customisation/theming.mdx +++ b/packages/dnb-design-system-portal/src/docs/uilib/usage/customisation/theming.mdx @@ -5,23 +5,18 @@ order: 7 # Theming -Read the [Styling examples](/uilib/usage/customisation/styling) on how to include styles and a theme. -This section is about how theming works and how to actually create a custom theme. +Theming is a umbrella term of a wide range of different ways and needs of customization. + +This section covers some of the needs out DNB productions has shown a need of. + +You may also check out the section in the contribution docs on [how to maintain and create a theme](/contribute/style-guides/theming/). - [Theming](#theming) - [Integrated theming](#integrated-theming) - [Brand theming](#brand-theming) - [Run your application with a different theme](#run-your-application-with-a-different-theme) - - [Run the portal with a different theme](#run-the-portal-with-a-different-theme) - - [Technical aspects](#technical-aspects) - - [Local Theming setup](#local-theming-setup) - - [_Method:_ yarn link and SASS](#method-yarn-link-and-sass) - [WIP: Ready to use themes](#wip-ready-to-use-themes) - - [Chrome Extension: Eufemia Theme Manager](#chrome-extension-eufemia-theme-manager) - - [Component theming](#component-theming) - - [Theming inside your application](#theming-inside-your-application) - [Using `postcss-replace`](#using-postcss-replace) - - [Using CSS (vars) Custom Properties](#using-css-vars-custom-properties) ## Integrated theming @@ -31,9 +26,9 @@ Themes are independent style packages, which should not be imported in parallel. ### Brand theming -Eufemia is design system that aims to help DNB brands unleash their power. +Eufemia is a design system that aims to help DNB brands unleash their power. -Eufemia is a system that is build on top of brand-assets. So means, it should be possible to swap out or extend these brand-assets. +Eufemia is a system that is build on top of brand-assets. This means, it should be possible to swap out or extend these brand-assets. Therefore, instead of overwriting Eufemia (DNB main brand) styles inside projects, it is beneficial to create additional brand themes – directly where the source of the original brand lives. @@ -50,80 +45,11 @@ import '@dnb/eufemia/style/components' + import '@dnb/eufemia/style/themes/eiendom' ``` -How ever, giving the user the ability to switch a theme during runtime, is a very much different challenge. - -The Eufemia Portal (documentation) uses [`gatsby-plugin-eufemia-theme-handler`](https://github.com/dnbexperience/eufemia/tree/main/packages/gatsby-plugin-eufemia-theme-handler) to handle it both in development and production mode. You may install it to use it in your application as well. - -### Run the portal with a different theme - -- 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`. -- 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. -- You can also define a different them in the url itself `path/?dnb-theme=ui`. - -### Technical aspects - -The included themes are built using SASS. Simply because we can reuse the _@mixin_'s and variables from SASS. - -We have the **Main Theming File**, which is located here: `dnb-eufemia/src/style/themes/dnb-theme-[THEME].scss` - -From here, we "can" reuse some default theming mechanism, just to have a fallback: - -```scss -@import '../theme-ui/dnb-theme-ui.scss'; -``` - -All the additional sub theming files (for every component) are automatically added to the **Main Theming File** by running `$ yarn build`. More on that further down. - -If we need a custom theming file for one or more components, we can do so by creating `dnb-eufemia/src/components/[COMPONENT]/style/dnb-button-theme-[THEME].scss`. - -**NB:** Every time you create a new theme file, you have to run `$ yarn build`. This way the new theme file gets added/bundled to the **Main Theming File**. - -### Local Theming setup - -There are several solutions to **create a new theme**. -One of which is by using the [linking feature of Yarn](https://yarnpkg.com/lang/en/docs/cli/link/). - -#### _Method:_ yarn link and SASS - -Make sure your project can handle **\*.scss** files. - -**1.** make a copy of the [repository](https://github.com/dnbexperience/eufemia). 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: - -```bash -$ yarn install && yarn build && yarn link -``` - -**4.** on your application root directory, run: - -```bash -$ yarn link "@dnb/eufemia" -``` - -**5.** That's it. Now you can use (import/require) the NPM module in your application like: - -```js -import { Button } from 'dnb-eufemia/components' -import 'dnb-eufemia/style/components' +Read more about [how to import styles](/uilib/usage/customisation/styling/consume-styles/#importing-the-css). -// See the "src" in the path? -import 'dnb-eufemia/src/style/themes/dnb-theme-[MY THEME].scss' -``` - -**6.** Don't forget to add `"@dnb/eufemia": "*"` with the respective version (alongside React) to your dependencies: +How ever, giving the user the ability to switch a theme during runtime, is a very much different challenge. -```json - "dependencies": { - "@dnb/eufemia": "*", - "react": "17", - "react-dom": "17", - ... - } -``` +The Eufemia Portal (documentation) uses [`gatsby-plugin-eufemia-theme-handler`](https://github.com/dnbexperience/eufemia/tree/main/packages/gatsby-plugin-eufemia-theme-handler) to handle it both in development and production mode. ## WIP: Ready to use themes @@ -131,48 +57,6 @@ Right now, theres work going on to create Eufemia Themes that utilize both color The plan is to extend the documentation here later on on how to select and use a theme inside an application. -### Chrome Extension: Eufemia Theme Manager - -Use the [Chrome Browser Extension](https://chrome.google.com/webstore/detail/eufemia-theme-manager/pijolaebmeacaekbhoefjmhogckdcclb) 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)](https://github.com/dnbexperience/eufemia-theme-manager/raw/main/eufemia-theme-manager-extension/web-ext-artifacts/eufemia_theme_manager-latest.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](https://github.com/dnbexperience/eufemia-theme-manager). - -## Component theming - -By default, all the HTML Elements (components) are built by separating the "visual styling" parts from the "functional layout" parts. This way we can create new custom visual styles: - -```js -/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 -``` - -- The main theme (`ui`) does contain mainly colorization and sizes. -- While all the raw positioning and layout related properties are in the main `.scss` file, starting with an underscore: `_button.scss` - -It's still possible to overwrite the _layout_ properties to customize our theme even further, if that is needed. - -### Theming inside your application - -You can skip to import the default theme `dnb-theme-ui` and create your own visual styles for every component you use in your App: - -```diff -import '@dnb/eufemia/style/core' // or /basis, when "dnb-core-style" is used -import '@dnb/eufemia/style/components' -- import '@dnb/eufemia/style/themes/ui' -``` - -This approach is fragile, because further Eufemia changes and updates will possibly misalign with your customization. - -Therefore, its probably a good idea to rather create theme styling files inside of the Eufemia repo itself. More on that topic in [integrated theming](#integrated-theming). - ### Using `postcss-replace` If your applications only need new colors or other CSS properties, you could simply replace all the properties with [postcss-replace](https://www.npmjs.com/package/postcss-replace) using this config scheme: @@ -192,7 +76,3 @@ If your applications only need new colors or other CSS properties, you could sim } } ``` - -### Using CSS (vars) Custom Properties - -This is a very nice and powerful solution. From 6e4fab07ab0a58de1b74f3e70ef679653c99bfff Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Tobias=20H=C3=B8egh?= Date: Tue, 14 Mar 2023 11:36:50 +0100 Subject: [PATCH 2/6] Update packages/dnb-design-system-portal/src/docs/uilib/usage/customisation/theming.mdx Co-authored-by: Anders --- .../src/docs/uilib/usage/customisation/theming.mdx | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/packages/dnb-design-system-portal/src/docs/uilib/usage/customisation/theming.mdx b/packages/dnb-design-system-portal/src/docs/uilib/usage/customisation/theming.mdx index e037cf32841..7e864ae5bb7 100644 --- a/packages/dnb-design-system-portal/src/docs/uilib/usage/customisation/theming.mdx +++ b/packages/dnb-design-system-portal/src/docs/uilib/usage/customisation/theming.mdx @@ -7,7 +7,7 @@ order: 7 Theming is a umbrella term of a wide range of different ways and needs of customization. -This section covers some of the needs out DNB productions has shown a need of. +This section covers some of the needs we've seen in DNB productions as of now. You may also check out the section in the contribution docs on [how to maintain and create a theme](/contribute/style-guides/theming/). From 6f91cb29218d400dd9da8d0ec90c836fb2c48872 Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Tobias=20H=C3=B8egh?= Date: Tue, 14 Mar 2023 11:37:35 +0100 Subject: [PATCH 3/6] Update packages/dnb-design-system-portal/src/docs/contribute/style-guides/theming.mdx Co-authored-by: Anders --- .../src/docs/contribute/style-guides/theming.mdx | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/packages/dnb-design-system-portal/src/docs/contribute/style-guides/theming.mdx b/packages/dnb-design-system-portal/src/docs/contribute/style-guides/theming.mdx index 188ba8797d6..bfc2ba13416 100644 --- a/packages/dnb-design-system-portal/src/docs/contribute/style-guides/theming.mdx +++ b/packages/dnb-design-system-portal/src/docs/contribute/style-guides/theming.mdx @@ -49,7 +49,7 @@ What theme gets imported is handled in the Gatsby Plugin `gatsby-plugin-eufemia- - 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 them in the url itself `path/?dnb-theme=ui`. +- 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 From 260249e5417b28111d6f54a0c8542d64214ff500 Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Tobias=20H=C3=B8egh?= Date: Tue, 14 Mar 2023 11:37:48 +0100 Subject: [PATCH 4/6] Update packages/dnb-design-system-portal/src/docs/contribute/style-guides/theming.mdx Co-authored-by: Anders --- .../src/docs/contribute/style-guides/theming.mdx | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/packages/dnb-design-system-portal/src/docs/contribute/style-guides/theming.mdx b/packages/dnb-design-system-portal/src/docs/contribute/style-guides/theming.mdx index bfc2ba13416..7045cfe5c7a 100644 --- a/packages/dnb-design-system-portal/src/docs/contribute/style-guides/theming.mdx +++ b/packages/dnb-design-system-portal/src/docs/contribute/style-guides/theming.mdx @@ -76,7 +76,7 @@ How `eiendom` is set up does not matter. It could either import parts from `ui` ### CSS custom properties and :root -Use when ever possible Eufemia Properties inside Eufemia components. +Whenever possible use Eufemia Properties inside Eufemia components. When defining custom properties for a component, **prefer** to put them inside the component scope: From 1e597b406e1e5ea7f2acf87f079cd49cd2faf02c Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Tobias=20H=C3=B8egh?= Date: Tue, 14 Mar 2023 11:37:58 +0100 Subject: [PATCH 5/6] Update packages/dnb-design-system-portal/src/docs/uilib/usage/customisation/theming.mdx Co-authored-by: Anders --- .../src/docs/uilib/usage/customisation/theming.mdx | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/packages/dnb-design-system-portal/src/docs/uilib/usage/customisation/theming.mdx b/packages/dnb-design-system-portal/src/docs/uilib/usage/customisation/theming.mdx index 7e864ae5bb7..6959a514c12 100644 --- a/packages/dnb-design-system-portal/src/docs/uilib/usage/customisation/theming.mdx +++ b/packages/dnb-design-system-portal/src/docs/uilib/usage/customisation/theming.mdx @@ -28,7 +28,7 @@ Themes are independent style packages, which should not be imported in parallel. Eufemia is a design system that aims to help DNB brands unleash their power. -Eufemia is a system that is build on top of brand-assets. This means, it should be possible to swap out or extend these brand-assets. +Eufemia is a system that is built on top of brand-assets. This means, it should be possible to swap out or extend these brand-assets. Therefore, instead of overwriting Eufemia (DNB main brand) styles inside projects, it is beneficial to create additional brand themes – directly where the source of the original brand lives. From ffa4070a7a969fbb2b5f47bf17b4f34617ca6d90 Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Tobias=20H=C3=B8egh?= Date: Tue, 14 Mar 2023 11:38:13 +0100 Subject: [PATCH 6/6] Update packages/dnb-design-system-portal/src/docs/uilib/usage/customisation/theming.mdx Co-authored-by: Anders --- .../src/docs/uilib/usage/customisation/theming.mdx | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/packages/dnb-design-system-portal/src/docs/uilib/usage/customisation/theming.mdx b/packages/dnb-design-system-portal/src/docs/uilib/usage/customisation/theming.mdx index 6959a514c12..913ed908607 100644 --- a/packages/dnb-design-system-portal/src/docs/uilib/usage/customisation/theming.mdx +++ b/packages/dnb-design-system-portal/src/docs/uilib/usage/customisation/theming.mdx @@ -55,7 +55,7 @@ The Eufemia Portal (documentation) uses [`gatsby-plugin-eufemia-theme-handler`]( Right now, theres work going on to create Eufemia Themes that utilize both color and spacing and the [Spatial system](/quickguide-designer/spatial-system). -The plan is to extend the documentation here later on on how to select and use a theme inside an application. +The plan is to extend the documentation here later on, with how to select and use a theme inside an application. ### Using `postcss-replace`