feat(themes): add experimental sass modules for themes (#7703)

* refactor(layout): update scale from a list to map

* feat(themes): add experimental sass modules for themes

* chore(themes): add sass modules example

* chore(themes): add example to sass-modules

* docs(themes): add early docs for v11 migrations

* chore(layout): fix workspace dependency

docs/migration/11.x-themes.md

@@ -0,0 +1,21 @@
+# Motion
+
+**Note: everything in this file is a work-in-progress and will be changed.**
+
+## Changes
+
+| Filename           | v10                     | v11                                        |
+| ------------------ | ----------------------- | ------------------------------------------ |
+| `_tokens.scss`     |                         | Deprecated, use Custom Properties directly |
+| `_theme-maps.scss` |                         | Removed, use `_themes.scss` instead        |
+| `_theme-maps.scss` | `$carbon--theme--white` | `$white`                                   |
+|                    | `$carbon--theme--g10`   | `$g10`                                     |
+|                    | `$carbon--theme--g90`   | `$g90`                                     |
+|                    | `$carbon--theme--g100`  | `$g100`                                    |
+| `_mixins.scss`     |                         | Removed, use `_theme.scss` instead         |
+| `_mixins.scss`     | `carbon--theme`         | `theme`                                    |
+
+- Theme maps are now available in `scss/_themes.scss` and no longer require a
+  namespace
+- Theme mixin has been simplified, it now emits the given theme as Custom
+  Properties for the parent selector

packages/layout/package.json

@@ -29,6 +29,7 @@
     "clean": "rimraf es lib umd scss/generated scss/modules/generated"
   },
   "devDependencies": {
+    "@carbon/cli": "^10.19.0-rc.0",
     "@carbon/cli-reporter": "^10.4.0",
     "@carbon/scss-generator": "^10.12.0",
     "@carbon/test-utils": "^10.14.0",

packages/layout/tasks/build.js

@@ -207,15 +207,18 @@ function buildModulesTokenFile(tokenScale, group) {
     return [comment, assignment, t.Newline()];
   });
 
-  const list = [
-    t.Comment(`/ @type List
+  const map = [
+    t.Comment(`/ @type Map
 / @access public
 / @group @carbon/layout`),
     t.Assignment({
       id: t.Identifier(group),
-      init: t.SassList({
-        elements: values.map(([_name, _shorthand, id]) => {
-          return id;
+      init: t.SassMap({
+        properties: values.map(([name, _shorthand, id]) => {
+          return t.SassMapProperty({
+            key: id,
+            value: t.SassValue(`$${name}`),
+          });
         }),
       }),
     }),
@@ -225,7 +228,7 @@ function buildModulesTokenFile(tokenScale, group) {
     FILE_BANNER,
     t.Newline(),
     ...variables,
-    ...list,
+    ...map,
     t.Newline(),
   ]);
 }

packages/scss-generator/src/types/definitions.js

@@ -316,6 +316,7 @@ const SassFunctionCall = defineType('SassFunctionCall', {
             assertType(SassMap),
             assertType(SassNumber),
             assertType(SassString),
+            assertType(SassValue),
           ])
         ),
     },
@@ -629,6 +630,34 @@ const SassImport = defineType('SassImport', {
   },
 });
 
+const SassModule = defineType('SassModule', {
+  fields: {
+    path: {
+      validate: assertValueType('string'),
+    },
+  },
+  generate(printer, node) {
+    printer.token('@use');
+    printer.space();
+    printer.token(`'${node.path}'`);
+    printer.token(';');
+  },
+});
+
+const SassForward = defineType('SassForward', {
+  fields: {
+    path: {
+      validate: assertValueType('string'),
+    },
+  },
+  generate(printer, node) {
+    printer.token('@forward');
+    printer.space();
+    printer.token(`'${node.path}'`);
+    printer.token(';');
+  },
+});
+
 //-------------------------------------------------------------------------------
 // Control structures
 //-------------------------------------------------------------------------------
@@ -779,6 +808,7 @@ module.exports = {
   Rule,
   SassBoolean,
   SassColor,
+  SassForward,
   SassFunction,
   SassFunctionCall,
   SassImport,
@@ -787,6 +817,7 @@ module.exports = {
   SassList,
   SassMap,
   SassMapProperty,
+  SassModule,
   SassValue,
   SassMixin,
   SassMixinCall,

packages/themes/.gitignore

@@ -1 +1 @@
-scss/generated
+generated

packages/themes/examples/sass-modules/.yarnrc.yml

@@ -0,0 +1,2 @@
+enableGlobalCache: true
+nodeLinker: node-modules

packages/themes/examples/sass-modules/README.md

@@ -0,0 +1 @@
+# sass-modules

packages/themes/examples/sass-modules/package.json

@@ -0,0 +1,13 @@
+{
+  "name": "sass-modules",
+  "scripts": {
+    "develop": "next"
+  },
+  "dependencies": {
+    "@carbon/themes": "link:../../",
+    "next": "^10.0.6",
+    "react": "^17.0.1",
+    "react-dom": "^17.0.1",
+    "sass": "^1.32.5"
+  }
+}

packages/themes/examples/sass-modules/src/pages/_app.js

@@ -0,0 +1,12 @@
+/**
+ * Copyright IBM Corp. 2018, 2018
+ *
+ * This source code is licensed under the Apache-2.0 license found in the
+ * LICENSE file in the root directory of this source tree.
+ */
+
+import '../styles.scss';
+
+export default function App({ Component, pageProps }) {
+  return <Component {...pageProps} />;
+}

packages/themes/examples/sass-modules/src/pages/index.js

@@ -0,0 +1,18 @@
+export default function IndexPage() {
+  return (
+    <div className="container">
+      <section className="white">
+        white
+      </section>
+      <section className="g10">
+        g10
+      </section>
+      <section className="g90">
+        g90
+      </section>
+      <section className="g100">
+        g100
+      </section>
+    </div>
+  );
+}

packages/themes/examples/sass-modules/src/styles.scss

@@ -0,0 +1,57 @@
+//
+// Copyright IBM Corp. 2018, 2018
+//
+// This source code is licensed under the Apache-2.0 license found in the
+// LICENSE file in the root directory of this source tree.
+//
+
+@use '@carbon/themes';
+
+@include themes.set(themes.$g100);
+
+html {
+  box-sizing: border-box;
+}
+
+*, *::before, *::after {
+  box-sizing: inherit;
+}
+
+html, body, #__next, .container {
+  width: 100%;
+  height: 100%;
+}
+
+body {
+  margin: 0;
+}
+
+body {
+  @include themes.theme();
+}
+
+.container {
+  display: grid;
+  grid-template-rows: repeat(4, 1fr);
+}
+
+.white {
+  @include themes.theme(themes.$white);
+}
+
+.g10 {
+  @include themes.theme(themes.$g10);
+}
+
+.g90 {
+  @include themes.theme(themes.$g90);
+}
+
+.g100 {
+  @include themes.theme(themes.$g100);
+}
+
+section {
+  background: var(--cds-ui-background);
+  color: var(--cds-text-01);
+}