-
Notifications
You must be signed in to change notification settings - Fork 32
Commit
This commit does not belong to any branch on this repository, and may belong to a fork outside of the repository.
docs: add docs about how to maintain theming (#2097)
* docs: add docs about how to maintain theming + update docs on consuming a theme * Update packages/dnb-design-system-portal/src/docs/uilib/usage/customisation/theming.mdx Co-authored-by: Anders <anderslangseth@gmail.com> * Update packages/dnb-design-system-portal/src/docs/contribute/style-guides/theming.mdx Co-authored-by: Anders <anderslangseth@gmail.com> * Update packages/dnb-design-system-portal/src/docs/contribute/style-guides/theming.mdx Co-authored-by: Anders <anderslangseth@gmail.com> * Update packages/dnb-design-system-portal/src/docs/uilib/usage/customisation/theming.mdx Co-authored-by: Anders <anderslangseth@gmail.com> * Update packages/dnb-design-system-portal/src/docs/uilib/usage/customisation/theming.mdx Co-authored-by: Anders <anderslangseth@gmail.com> --------- Co-authored-by: Anders <anderslangseth@gmail.com>
- Loading branch information
1 parent
6f1a7d6
commit 36aed9a
Showing
2 changed files
with
159 additions
and
131 deletions.
There are no files selected for viewing
148 changes: 148 additions & 0 deletions
148
packages/dnb-design-system-portal/src/docs/contribute/style-guides/theming.mdx
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Original file line number | Diff line number | Diff line change |
---|---|---|
@@ -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 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_). | ||
|
||
```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 | ||
|
||
Whenever possible use 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). |
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters