[NOJIRA]: Migrate to sass-embedded

.gitignore

@@ -14,3 +14,8 @@ npm-debug.*
 yarn.lock
 /packages/*/changelog.md
 .storybook/__image_snapshots__/__diff_output__
+
+# Ignore css assets as these should be built on demand from sass
+*.css
+!packages/bpk-stylesheets/base.css
+/packages/unstable__bpk-mixins

.storybook/webpack.config.js

@@ -21,7 +21,6 @@ const path = require('path');
 
 const MiniCssExtractPlugin = require("mini-css-extract-plugin");
 
-const sassFunctions = require('../packages/bpk-mixins/sass-functions');
 const postCssPlugins = require('../scripts/webpack/postCssPlugins');
 
 const { BPK_TOKENS } = process.env;
@@ -120,9 +119,6 @@ module.exports = ({ config }) => {
                 ),
               )
             : '',
-          sassOptions: {
-            functions: sassFunctions,
-          },
         },
       },
     ],

.stylelintignore

@@ -1 +1,3 @@
 node_modules
+packages/unstable__bpk-mixins
+**/*.css

.stylelintrc.json

@@ -7,6 +7,7 @@
         "resolveNestedSelectors": true
       }
     ],
+    "at-rule-disallowed-list": ["import"],
     "unit-disallowed-list": [["px"], {
       "ignoreProperties": {
         "px": ["box-shadow"]

CONTRIBUTING.md

@@ -59,9 +59,13 @@ git checkout -b {BRANCH_NAME}
 npm install --registry="https://registry.npmjs.org/"
 ```
 
-If you receive an error about `ValueError: invalid mode: 'rU' while trying to load binding.gyp`, try downgrading the default python version for your shell to python 3.9
+3. Build a modern version of mixins for local development
 
-3. Build SVGs
+```sh
+npm run build:unstable__bpk-mixins
+```
+
+4. Build SVGs
 
 ```sh
 npm run build
@@ -105,6 +109,18 @@ We use [CSS Modules](https://github.com/css-modules/css-modules) along with [BEM
 
 When creating (S)CSS files, follow the CSS Module naming convention by using the `.module.(s)css` extension.
 
+When creating or modifying SCSS files, follow these rules
+
+1. Use Modern SASS API
+   * Prefer `@use` instead of `@import`
+   * Prefer `math.div($a, $b)` instead of `$a / $b`. Add `@use sass:math` statement to the top of your file to make this function available
+   * Read more about [@use rule](https://sass-lang.com/documentation/at-rules/use/) and [SASS math functions](https://sass-lang.com/documentation/modules/math/)
+2. Use only what you need
+   * Instead of blank import of all mixins, import them on demand. E.g. if you need only colour tokens, add `@use '../unstable__bpk-mixins/tokens'` statement only
+3. Use `unstable__bpk-mixins` for Backpack components development
+   * If you need to add or modify a mixin, do it in `packages/bpk-mixins`, then execute `npm run unstable__bpk-mixins` command to make it available for Modern API
+   * Import mixins from `packages/unstable__bpk-mixins` only. Otherwise your code will break because Modern SASS API doesn't support `~` import syntax or slash division
+
 #### Adding a new component
 
 If you want to add a new component:

decisions/modern-sass-api.md

@@ -0,0 +1,59 @@
+# Transition to modern SASS API
+
+## Decision
+Backpack is transforming the way it works with SASS to align with modern SASS API used in
+dart-sass and sass-embedded. Old API remains the default option, but at some point of time
+in the future we will switch the default API to the new one
+
+* Backpack is shipped with two versions of `bpk-mixins` package
+  * `packages/bpk-mixins` that remains the stable option. It uses old SASS API and `@import` syntax
+  * `packages/unstable__bpk-mixins` is a modern SASS API version compatible with `sass` and `sass-embedded` packages, but not with `node-sass`
+* In the future the package using Old API will be deprecated and removed and the one using New API will be promoted to stable
+* For our own components we use `unstable__bpk-mixins`
+  * These mixins must be imported with `@use` at-rule
+  * Mixins partials must be used in a granular way (use only those partials that you need to build a particular component, see "Wrong" and "Correct" examples below)
+* If you need to add or modify a mixin, do it in `packages/bpk-mixins`. Then run `npm run unstable__bpk-mixins` to generate a new modern version of the package
+
+## Examples
+
+**Wrong (1)**
+```
+// BpkAwesomeComponent.module.scss
+
+@use '../unstable__bpk-mixins' as mixins;
+
+.bpk-awesome-component {
+  margin-right: mixins.bpk-spacing-md();
+}
+```
+
+**Wrong (2)**
+```
+// BpkAwesomeComponent.module.scss
+
+@import '../bpk-mixins';
+
+.bpk-awesome-component {
+  margin-right: bpk-spacing-md();
+}
+```
+
+**Correct**
+```
+// BpkAwesomeComponent.module.scss
+
+@use '../unstable__bpk-mixins/tokens';
+
+.bpk-awesome-component {
+  margin-right: tokens.bpk-spacing-md();
+}
+```
+
+## Thinking
+
+The main reason behind such a change is to deliver modern API to consumers in a non-breaking manner. Using `unstable` prefix
+means that we can't guarantee that this package structure won't change before becoming stable.
+
+## Anything Else
+
+https://sass-lang.com/documentation/at-rules/use/#differences-from-import

examples/bpk-component-aria-live/examples.module.scss

@@ -16,23 +16,25 @@
  * limitations under the License.
  */
 
-@import '../../packages/bpk-mixins/index.scss';
+@use '../../packages/unstable__bpk-mixins/tokens';
+@use '../../packages/unstable__bpk-mixins/borders';
+@use '../../packages/unstable__bpk-mixins/radii';
 
 .bpk-storybook-aria-live-demo {
-  padding: bpk-spacing-base();
-  background: $bpk-canvas-contrast-day;
-  color: $bpk-text-primary-day;
+  padding: tokens.bpk-spacing-base();
+  background: tokens.$bpk-canvas-contrast-day;
+  color: tokens.$bpk-text-primary-day;
 
-  @include bpk-border-sm($bpk-line-day);
-  @include bpk-border-radius-sm;
+  @include borders.bpk-border-sm(tokens.$bpk-line-day);
+  @include radii.bpk-border-radius-sm;
 
   &__chips-wrapper {
-    margin-bottom: bpk-spacing-base();
+    margin-bottom: tokens.bpk-spacing-base();
   }
 
   &__select-wrapper {
     display: flex;
-    margin-bottom: bpk-spacing-base();
+    margin-bottom: tokens.bpk-spacing-base();
     justify-content: space-between;
     align-items: center;
   }
@@ -46,16 +48,16 @@
   }
 
   &__chip {
-    margin-right: bpk-spacing-base();
-    margin-bottom: bpk-spacing-base();
+    margin-right: tokens.bpk-spacing-base();
+    margin-bottom: tokens.bpk-spacing-base();
   }
 
   &__aria-live {
-    margin-top: bpk-spacing-base();
+    margin-top: tokens.bpk-spacing-base();
   }
 
   > p {
-    margin-top: $bpk-spacing-none;
-    margin-bottom: bpk-spacing-base();
+    margin-top: tokens.$bpk-spacing-none;
+    margin-bottom: tokens.bpk-spacing-base();
   }
 }

examples/bpk-component-badge/BpkBadgeLayout.module.scss

@@ -16,19 +16,20 @@
  * limitations under the License.
  */
 
-@import '../../packages/bpk-mixins/index.scss';
+@use '../../packages/unstable__bpk-mixins/tokens';
+@use '../../packages/unstable__bpk-mixins/radii';
 
 .bpk-badge-layout {
   &__container {
     position: relative;
     display: flex;
-    min-height: bpk-spacing-xxl();
-    padding: bpk-spacing-lg();
+    min-height: tokens.bpk-spacing-xxl();
+    padding: tokens.bpk-spacing-lg();
 
     &--light {
-      background-color: $bpk-canvas-contrast-day;
+      background-color: tokens.$bpk-canvas-contrast-day;
 
-      @include bpk-border-radius-xs;
+      @include radii.bpk-border-radius-xs;
     }
   }
 }

examples/bpk-component-banner-alert/examples.module.scss

@@ -16,10 +16,10 @@
  * limitations under the License.
  */
 
-@import '../../packages/bpk-mixins/index.scss';
+@use '../../packages/unstable__bpk-mixins/tokens';
 
 .bpk-banner-alert-examples {
   &__component {
-    margin-top: bpk-spacing-base();
+    margin-top: tokens.bpk-spacing-base();
   }
 }

examples/bpk-component-barchart/examples.module.scss

@@ -16,22 +16,23 @@
  * limitations under the License.
  */
 
-@import '../../packages/bpk-mixins/index.scss';
+@use '../../packages/unstable__bpk-mixins/tokens';
+@use '../../packages/unstable__bpk-mixins/scroll-indicators';
 
 .bpk-heading {
-  margin-bottom: bpk-spacing-base();
+  margin-bottom: tokens.bpk-spacing-base();
 }
 
-$custom-color: $bpk-canvas-contrast-day;
+$custom-color: tokens.$bpk-canvas-contrast-day;
 
 .bpk-barchart-custom-scrollers {
   background: $custom-color;
 
   &--leading {
-    @include bpk-scroll-indicator-left($custom-color);
+    @include scroll-indicators.bpk-scroll-indicator-left($custom-color);
   }
 
   &--trailing {
-    @include bpk-scroll-indicator-right($custom-color);
+    @include scroll-indicators.bpk-scroll-indicator-right($custom-color);
   }
 }

examples/bpk-component-bottom-sheet/examples.module.scss

@@ -16,8 +16,8 @@
  * limitations under the License.
  */
 
-@import '../../packages/bpk-mixins/index.scss';
+@use '../../packages/unstable__bpk-mixins/tokens';
 
 .bpk-bottom-sheet-paragraph {
-  margin-bottom: bpk-spacing-md();
+  margin-bottom: tokens.bpk-spacing-md();
 }

examples/bpk-component-breakpoint/examples.module.scss

@@ -16,21 +16,22 @@
  * limitations under the License.
  */
 
-@import '../../packages/bpk-mixins/index.scss';
+@use '../../packages/unstable__bpk-mixins/tokens';
+@use '../../packages/unstable__bpk-mixins/utils';
 
 .bpk-breakpoints-demo {
-  border-radius: $bpk-border-radius-xs;
+  border-radius: tokens.$bpk-border-radius-xs;
   overflow: hidden;
 
   &--active {
-    padding: bpk-spacing-lg();
-    color: $bpk-text-primary-inverse-day;
+    padding: tokens.bpk-spacing-lg();
+    color: tokens.$bpk-text-primary-inverse-day;
 
-    @include bpk-apply-primary-color-to(background-color);
+    @include utils.bpk-apply-primary-color-to(background-color);
   }
 
   &--inactive {
-    padding: bpk-spacing-lg();
-    background-color: $bpk-surface-highlight-day;
+    padding: tokens.bpk-spacing-lg();
+    background-color: tokens.$bpk-surface-highlight-day;
   }
 }