docs: update docs about CSS formatting and styling (#1964)

* docs: update docs about CSS formatting and styling * Update packages/dnb-design-system-portal/src/docs/contribute/getting-started.md Co-authored-by: Anders <anderslangseth@gmail.com> * Update packages/dnb-design-system-portal/src/docs/contribute/getting-started.md Co-authored-by: Anders <anderslangseth@gmail.com> --------- Co-authored-by: Anders <anderslangseth@gmail.com>
dnbexperience · Feb 3, 2023 · 70c7665 · 70c7665
1 parent 1058e4f
commit 70c7665
Show file tree

Hide file tree

Showing 3 changed files with 51 additions and 27 deletions.
diff --git a/packages/dnb-design-system-portal/src/docs/contribute/getting-started.md b/packages/dnb-design-system-portal/src/docs/contribute/getting-started.md
@@ -85,12 +85,18 @@ All layout and position related styles go here:
 
 - `./packages/dnb-eufemia/src/components/button/style/dnb-button.scss`
 
-#### SCSS dependencies
+#### CSS packages
 
-SCSS file names staring with `dnb-` are later possible to get imported as individual packages:
+SCSS file names starting with `dnb-` are later possible to get imported as individual packages:
 
 - `./packages/dnb-eufemia/src/components/button/style/dnb-button.scss`
 
+#### Style dependencies
+
+In order to test related style dependencies of components, we add style imports in the `deps.scss` file, which again is used in Jest tests to perform a snapshot comparison:
+
+- `./packages/dnb-eufemia/src/components/button/style/deps.scss`
+
 #### SCSS Theming
 
 Styles that belong to a "theming footprint" – like colors or individual variants – can be put inside the `/themes` directory:
@@ -101,7 +107,7 @@ Theming file names ending with `-ui` will during the package release get packed
 
 #### SCSS utilities and properties
 
-Use the same sass setup as all the other components. You may re-use all the [helper classes](/uilib/helpers/classes):
+Use the same SASS setup as all the other components. You may re-use all the [helper classes](/uilib/helpers/classes):
 
 - `./packages/dnb-eufemia/src/style/core/utilities.scss`
 - `./packages/dnb-eufemia/src/style/core/properties.scss`

diff --git a/packages/dnb-design-system-portal/src/docs/contribute/style-guides/coding.md b/packages/dnb-design-system-portal/src/docs/contribute/style-guides/coding.md
@@ -49,3 +49,7 @@ yarn workspace @dnb/eufemia test:types
 ```
 
 Fix the resulted warnings and errors before you commit and merge.
+
+#### CSS code formatting
+
+Eufemia uses [CSS rational order](/uilib/usage/best-practices/for-styling/#styling-structure).
diff --git a/...ges/dnb-design-system-portal/src/docs/uilib/usage/best-practices/for-styling.md b/...ges/dnb-design-system-portal/src/docs/uilib/usage/best-practices/for-styling.md
@@ -14,44 +14,58 @@ Otherwise you will find yourself making a fix of a fix, and so on. Also, refacto
 
 ## Styling structure
 
-To write more structured and uniform CSS code, stick with the following approach:
+To write more structured and uniform CSS code, so both you and your coworker can more easily read and use your code. It even helps during development, because you always are aware of where and what you have used of CSS properties already.
 
-1. start the most influential and important properties first then work progressively toward aesthetics and motion effects.
-1. leave one empty line between these groups
+Using the same principles helps coworkers quickly find and understand the sentence and meaning of your CSS code.
 
-This helps coworkers quickly find and understand the sentence and meaning of the CSS code.
+### Rational CSS properties order
 
-### Example structure of CSS
+1. start the most influential and important properties first then work progressively toward aesthetics and animations.
+1. leave one empty line between these "logical" groups.
+
+For the "logical" groups we recommend the following rational order principle:
 
 ```css
 .my-selector {
-  /* -- 1. Layout -- */
-  position: relative;
-  z-index: 1;
-  display: block;
-
-  /* -- 2. Sizes & Spaces -- */
-  width: 0.5rem;
-  height: 0.5rem;
-  /* will be the same as our local font-size of 1.5rem */
+  /* Positioning */
+  position: absolute;
+  top: 0;
+  right: 0;
+  bottom: 0;
+  left: 0;
+  inset: 0;
+  z-index: 10;
+  display: flex;
+
+  /* Box Model */
+  width: 16rem;
+  height: 16rem;
+  margin: 2rem;
   padding: 1rem;
+  color: #111;
 
-  /* -- 3. Fonts & Typography -- */
-  font-family: var(--font-family-default);
-  font-weight: var(--font-weight-basis);
-  font-size: var(--font-size-large);
-  color: var(--color-sea-green);
+  /* Typography */
+  font: normal 1rem Helvetica, sans-serif;
+  line-height: 1.5rem;
+  text-align: left;
 
-  /* -- 4. Styling -- */
-  /* use Pixel for borders. They don't need to be dynamic */
-  border: 1px solid var(--color-mint-green);
+  /* Visual */
+  background-color: #eee;
+  border: 1px solid #888;
+  border-radius: 0.25rem;
   opacity: 1;
 
-  /* -- 5. Animations -- */
-  transition: opacity 0.2s linear;
+  /* Animation */
+  transition: all 1s;
+
+  /* Misc */
+  user-select: none;
+  cursor: pointer;
 }
 ```
 
+You may check out this [Prettier Plugin](https://www.npmjs.com/package/prettier-plugin-rational-order) for handling it automatic with [prettier](https://prettier.io/).
+
 ## CSS Units
 
 Here is a list of what we should use as layout and styling units to embrace the best possible accessibility experience and visual correctness.