feat: alpha release of design tokens (#1770)

.eslintignore

@@ -7,3 +7,5 @@ dependent-usage-analyzer/
 build-scss.js
 component-generator/
 example/
+style-dictionary-build/
+build-tokens.js

.gitignore

@@ -7,6 +7,7 @@ jest*
 dist
 src/i18n/transifex_input.json
 src/i18n/temp
+style-dictionary-build
 
 # gatsby files
 www/.cache/

.releaserc

@@ -1,5 +1,10 @@
 {
-  "branches": ["master", "next"],
+  "branches": [
+    "master",
+    "next",
+    { "name": "alpha", "prerelease": true },
+    { "name": "beta", "prerelease": true }
+  ],
   "plugins": [
     "@semantic-release/commit-analyzer",
     "@semantic-release/release-notes-generator",

.stylelintrc.json

@@ -31,6 +31,9 @@
       "ignoreProperties": ["xs", "sm", "md", "lg", "xl", "xxl"]
     }],
     "alpha-value-notation": "number",
-    "color-function-notation": "legacy"
+    "color-function-notation": "legacy",
+    "value-keyword-case": ["lower", {
+      "ignoreProperties": ["/font-family/"]
+    }]
   }
 }

README.md

@@ -467,3 +467,21 @@ The assigned maintainers for this component and other project details may be fou
 Please do not report security issues in public. Please email [email protected].
 
 We tend to prioritize security issues which impact the published `@edx/paragon` NPM library more so than the [documentation website](https://paragon-openedx.netlify.app/) or example React application.
+
+## Design Tokens
+
+Design tokens are all the values needed to build and maintain a design system — spacing, color, typography, object styles, etc. They can represent anything defined by the design: color as an RGB value, opacity as a number, spacing as a REM value. They are used instead of hard-coded values to provide flexibility and uniformity across the application.
+
+### Design Tokens in Paragon
+
+Folder `tokens` in the project root contains split by categories `json` files. They consist of `JSON` objects that store information about the variable name and its value. Scripts that also reside in the `tokens` folder provide following facilities: build tokens into `css`, `scss` variables, map `scss` to `css` variables and replace old `scss` to new `css` variables.
+
+### Usage
+
+```
+cd tokens
+npm install
+npm run build-tokens # creates "build" folder with scss and css variables based on json tokens
+npm run build-scss-to-css-map # creats scss-to-css-core.json and scss-to-css-components.json 
+npm run replace-variables -- --path ../src # this will replace all scss variables in the project with the new css variables based on the "scss-to-css-core.json" and "scss-to-css-components.json" files
+```

docs/decisions/0018-design-tokens-style-dictionary.rst

@@ -0,0 +1,19 @@
+18. Design tokens with Style Dictionary
+---------------------------------------
+
+Status
+------
+
+Proposed
+
+Context
+-------
+
+Decision
+--------
+
+Consequences
+------------
+
+Resources
+---------

scss/core/_variables.scss

@@ -688,15 +688,13 @@ $embed-responsive-aspect-ratios: join(
 //
 // Font, line-height, and color for body text, headings, and more.
 
-// stylelint-disable value-keyword-case
 $font-family-sans-serif:      -apple-system, BlinkMacSystemFont, "Segoe UI",
   Roboto, "Helvetica Neue", Arial, "Noto Sans", sans-serif, "Apple Color Emoji",
   "Segoe UI Emoji", "Segoe UI Symbol", "Noto Color Emoji" !default;
 $font-family-serif:           serif !default;
 $font-family-monospace:       SFMono-Regular, Menlo, Monaco, Consolas, "Liberation Mono",
   "Courier New", monospace !default;
 $font-family-base:            $font-family-sans-serif !default;
-// stylelint-enable value-keyword-case
 
 $font-size-base:              1.125rem !default; // Assumes the browser default, typically `16px`
 $font-size-lg:                $font-size-base * 1.25 !default;
@@ -789,15 +787,15 @@ $table-th-font-weight:        null !default;
 // Warning: Avoid customizing these values. They're used for a bird's eye view
 // of components dependent on the z-axis and are designed to all work together.
 
-$zindex-dropdown:                   1000 !default;
-$zindex-sticky:                     1020 !default;
-$zindex-fixed:                      1030 !default;
-$zindex-sheet-backdrop:             1031 !default;
-$zindex-sheet:                      1032 !default;
-$zindex-modal-backdrop:             1040 !default;
-$zindex-modal:                      1050 !default;
-$zindex-popover:                    1060 !default;
-$zindex-tooltip:                    1070 !default;
+$zindex-dropdown:                   var(--pgn-dropdown-zindex) !default;
+$zindex-sticky:                     var(--pgn-zindex-sticky) !default;
+$zindex-fixed:                      var(--pgn-zindex-fixed) !default;
+$zindex-sheet-backdrop:             var(--pgn-sheet-zindex-backdrop) !default;
+$zindex-sheet:                      var(--pgn-sheet-zindex-main) !default;
+$zindex-modal-backdrop:             var(--pgn-modal-backdrop-zindex) !default;
+$zindex-modal:                      var(--pgn-modal-zindex) !default;
+$zindex-popover:                    var(--pgn-popover-zindex) !default;
+$zindex-tooltip:                    var(--pgn-tooltip-zindex) !default;
 
 // Buttons + Forms
 //

scss/core/core.scss

@@ -1,3 +1,4 @@
+@import "tokens";
 @import "functions";
 @import "variables";
 @import "~bootstrap/scss/mixins";