feat(styles): add support for a compat theme (#9235)

* feat(themes): add support for a compat theme * feat(styles): add support for a compat theme * refactor(styles): add support for compat theme * chore(themes): update builder to ensure filepath * chore(themes): ignore compat directory * chore(cli): update cli to ignore compat dirs * fix(styles): add support for compat in stylesheets * test: update test for custom properties
carbon-design-system · Jul 28, 2021 · 5214919 · 5214919
1 parent c9ce0fc
commit 5214919
Show file tree

Hide file tree

Showing 35 changed files with 571 additions and 89 deletions.
diff --git a/.github/workflows/ci.yml b/.github/workflows/ci.yml
@@ -67,7 +67,7 @@ jobs:
         run: yarn build --ignore '@carbon/sketch'
       - name: Check generated styles
         run: |
-          yarn carbon-cli check --ignore '**/@(node_modules|examples|components|react|fixtures)/**' 'packages/**/*.scss'
+          yarn carbon-cli check --ignore '**/@(node_modules|examples|components|react|fixtures|compat)/**' 'packages/**/*.scss'
       - name: Run tests
         run: yarn test --ci
 

diff --git a/packages/carbon-react/.storybook/Welcome/welcome.scss b/packages/carbon-react/.storybook/Welcome/welcome.scss
@@ -1,5 +1,4 @@
-// @import '~carbon-components/scss/globals/scss/typography';
-@use '@carbon/styles/scss/theme' as *;
+@use '@carbon/styles/scss/theme';
 @use '@carbon/styles/scss/type';
 
 .container-welcome {
@@ -19,7 +18,7 @@
 .welcome__heading {
   @include type.type-style('productive-heading-07');
 
-  color: $text-inverse;
+  color: theme.$text-inverse;
 }
 
 .welcome__heading--subtitle {

diff --git a/packages/cli/src/commands/ci-check.js b/packages/cli/src/commands/ci-check.js
@@ -21,7 +21,7 @@ async function check(args, env) {
     stdio: 'inherit',
   };
   const tasks = [
-    `yarn carbon-cli check --ignore '**/@(node_modules|examples|components|react|fixtures)/**' 'packages/**/*.scss'`,
+    `yarn carbon-cli check --ignore '**/@(node_modules|examples|components|react|fixtures|compat)/**' 'packages/**/*.scss'`,
     `cross-env BABEL_ENV=test yarn test --ci --maxWorkers 2 --reporters=default --reporters=jest-junit`,
     `cross-env BABEL_ENV=test yarn test:e2e --ci --maxWorkers 2 --reporters=default --reporters=jest-junit`,
     `cross-env PERCY_TOKEN=dd3392142006a6483c8f524697f39f052755fa9dc087ff4437cac3d64227abdd yarn run percy exec -- yarn workspace carbon-components-react test:e2e`,

diff --git a/packages/styles/__tests__/compat-test.js b/packages/styles/__tests__/compat-test.js
@@ -0,0 +1,67 @@
+/**
+ * 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.
+ *
+ * @jest-environment node
+ */
+
+'use strict';
+
+const { SassRenderer } = require('@carbon/test-utils/scss');
+
+const { render } = SassRenderer.create(__dirname);
+
+describe('@carbon/styles/scss/compat', () => {
+  it('should export white, g10, g90, and g100 themes', async () => {
+    const { unwrap } = await render(`
+      @use 'sass:map';
+      @use 'sass:meta';
+      @use '../scss/compat/themes';
+
+      $_: get('variables', map.keys(meta.module-variables('themes')));
+    `);
+    const themes = unwrap('variables').sort();
+    expect(themes).toEqual(['white', 'g10', 'g90', 'g100'].sort());
+  });
+
+  it('should export v10 tokens as Sass Variables', async () => {
+    const { unwrap } = await render(`
+      @use '../scss/config' with ( $prefix: 'cds' );
+      @use '../scss/compat/themes';
+      @use '../scss/compat/theme' with (
+        $theme: themes.$white,
+      );
+
+      $_: get('theme', themes.$white);
+      $_: get('variable', theme.$interactive-01);
+    `);
+    const theme = unwrap('theme');
+    const variable = unwrap('variable');
+
+    expect(variable).toEqual(
+      `var(--cds-interactive-01, ${theme['interactive-01']})`
+    );
+  });
+
+  it('should export v11 tokens that match the fallback theme', async () => {
+    const { unwrap } = await render(`
+      @use '../scss/config' with ( $prefix: 'cds' );
+      @use '../scss/themes';
+      @use '../scss/compat/themes' as compat;
+      @use '../scss/compat/theme' with (
+        $fallback: themes.$g100,
+        $theme: compat.$g100,
+      );
+
+      $_: get('theme', themes.$g100);
+      $_: get('variable', theme.$background);
+    `);
+
+    const theme = unwrap('theme');
+    const variable = unwrap('variable');
+
+    expect(variable).toEqual(`var(--cds-background, ${theme['background']})`);
+  });
+});
diff --git a/packages/styles/docs/sass.md b/packages/styles/docs/sass.md
@@ -48,6 +48,7 @@ between version updates.
 | :------------------------------------- | :--------------------------------------------------------- |
 | [`scss/breakpoint`](#breakpoint)       | Helper functions and mixins for working with breakpoints   |
 | [`scss/colors`](#colors)               | Access colors from every swatch in the IBM Design Language |
+| [`scss/compat/`](#compatibility)       | Helper themes and tokens for migrating from v10 to v11     |
 | [`scss/config`](#config)               | Configure various options for the package                  |
 | [`scss/feature-flags`](#feature-flags) | Configure various feature flags for experiments            |
 | [`scss/grid`](#grid)                   | Access and use the CSS Grid built-in to Carbon             |
@@ -331,6 +332,48 @@ like to see changed. For example, if you wanted to change the component token
 | :---------------------------------------------------- | :---------- |
 | `@use '@carbon/styles/scss/utilities/focus-outline';` |             |
 
+## Compatibility
+
+| Import                                      | Filepath                   |
+| :------------------------------------------ | :------------------------- |
+| `@use '@carbon/styles/scss/compat/themes';` | `scss/compat/_themes.scss` |
+| `@use '@carbon/styles/scss/compat/theme';`  | `scss/compat/_theme.scss`  |
+
+The compatibility entrypoints for themes and theme provide access to the v10
+tokens along with the v11 tokens. To make sure that the tokens that you're using
+from v10 have the correct value in v11, you will need to include the theme that
+you're using from `scss/compat/themes` and set that as your theme.
+
+```scss
+@use '@carbon/styles/scss/compat/themes' as compat;
+@use '@carbon/styles/scss/themes';
+@use '@carbon/styles/scss/compat/theme' with (
+  $fallback: themes.$g100,
+  $theme: compat.$g100,
+);
+```
+
+It's important that you specify the `$fallback` theme as a value from the
+`scss/themes` entrypoint. This will guarantee that all tokens that you are using
+from v11 will match the theme of the tokens that you are using from v10.
+
+You can directly reference a token from the `scss/compat/theme` entrypoint. This
+entrypoint will also re-export all available v11 tokens and mixins from
+`scss/theme`.
+
+```scss
+@use '@carbon/styles/scss/compat/theme';
+
+body {
+  // You can use both v10 and v11 tokens
+  background: theme.$background;
+  color: theme.$text-01;
+}
+```
+
+_Note: all tokens from v10 are deprecated in v11. They will be removed in the
+next major release of Carbon_
+
 ## Configuration
 
 You will need to configure Sass to be able to lookup packages from your

diff --git a/packages/styles/scss/__tests__/theme-test.js b/packages/styles/scss/__tests__/theme-test.js
@@ -36,7 +36,6 @@ describe('@carbon/styles/scss/theme', () => {
 Array [
   "fallback",
   "theme",
-  "use-fallback-value",
   "background",
   "background-active",
   "background-selected",
@@ -145,28 +144,6 @@ Array [
   "border-subtle",
   "border-subtle-selected",
   "border-strong",
-  "interactive-01",
-  "interactive-04",
-  "decorative-01",
-  "hover-row",
-  "ui-01",
-  "ui-02",
-  "ui-05",
-  "disabled-01",
-  "disabled-02",
-  "hover-field",
-  "hover-ui",
-  "selected-ui",
-  "hover-selected-ui",
-  "hover-light-ui",
-  "active-light-ui",
-  "text-01",
-  "text-02",
-  "text-04",
-  "text-05",
-  "icon-01",
-  "icon-02",
-  "link-01",
 ]
 `);
   });

diff --git a/packages/styles/scss/_theme.scss b/packages/styles/scss/_theme.scss
@@ -9,9 +9,15 @@
 @use '@carbon/themes/scss/modules/config' with (
   $prefix: $prefix,
 );
-@use '@carbon/themes/scss/modules/tokens';
-@forward '@carbon/themes/scss/modules/theme';
+@use './compat/themes' as compat;
+@use './themes';
+
+@forward '@carbon/themes/scss/modules/theme' with (
+  $fallback: themes.$white !default,
+  $theme: compat.$white !default,
+);
 @forward '@carbon/themes/scss/modules/tokens';
+@use '@carbon/themes/scss/modules/tokens';
 @use './utilities/custom-property';
 @use './utilities/layer-set' with (
   $layer-sets: (
@@ -99,27 +105,3 @@ $field-hover: custom-property.get-var('field-hover');
 $border-subtle: custom-property.get-var('border-subtle');
 $border-subtle-selected: custom-property.get-var('border-subtle-selected');
 $border-strong: custom-property.get-var('border-strong');
-
-// TODO remove
-$interactive-01: #0f62fe;
-$interactive-04: #0f62fe;
-$decorative-01: #e0e0e0;
-$hover-row: #636363;
-$ui-01: #f4f4f4;
-$ui-02: #ffffff;
-$ui-05: #161616;
-$disabled-01: #f4f4f4;
-$disabled-02: #c6c6c6;
-$hover-field: #e5e5e5;
-$hover-ui: #e5e5e5;
-$selected-ui: #e0e0e0;
-$hover-selected-ui: #cacaca;
-$hover-light-ui: #e5e5e5;
-$active-light-ui: #c6c6c6;
-$text-01: #161616;
-$text-02: #525252;
-$text-04: #ffffff;
-$text-05: #6f6f6f;
-$icon-01: #f4f4f4;
-$icon-02: #525252;
-$link-01: #0f62fe;
diff --git a/packages/styles/scss/compat/_theme.scss b/packages/styles/scss/compat/_theme.scss
@@ -0,0 +1,9 @@
+//
+// 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.
+//
+
+@forward '../theme';
+@forward '@carbon/themes/scss/compat/tokens';
diff --git a/packages/styles/scss/compat/_themes.scss b/packages/styles/scss/compat/_themes.scss
@@ -0,0 +1,8 @@
+//
+// 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.
+//
+
+@forward '@carbon/themes/scss/compat/themes' show $white, $g10, $g90, $g100;
diff --git a/packages/styles/scss/components/code-snippet/_code-snippet.scss b/packages/styles/scss/components/code-snippet/_code-snippet.scss
@@ -5,20 +5,20 @@
 // LICENSE file in the root directory of this source tree.
 //
 
-@use 'mixins' as *;
-@use '../copy-button';
 @use '../../config' as *;
 @use '../../motion' as *;
 @use '../../spacing' as *;
-@use '../../theme' as *;
+@use '../../compat/theme' as *;
 @use '../../type' as *;
+@use '../copy-button';
 @use '../../utilities/convert' as *;
 @use '../../utilities/focus-outline' as *;
 @use '../../utilities/high-contrast-mode' as *;
 @use '../../utilities/keyframes' as *;
 @use '../../utilities/skeleton' as *;
 @use '../../utilities/tooltip' as *;
 @use '../../utilities/z-index' as *;
+@use 'mixins' as *;
 
 /// @type Color
 /// @access public

diff --git a/packages/styles/scss/components/data-table/expandable/_data-table-expandable.scss b/packages/styles/scss/components/data-table/expandable/_data-table-expandable.scss
@@ -8,7 +8,7 @@
 @use '../../../config' as *;
 @use '../../../motion' as *;
 @use '../../../spacing' as *;
-@use '../../../theme' as *;
+@use '../../../compat/theme' as *;
 @use '../../../utilities/button-reset';
 @use '../../../utilities/convert' as *;
 @use '../../../utilities/focus-outline' as *;

diff --git a/packages/styles/scss/components/date-picker/_date-picker.scss b/packages/styles/scss/components/date-picker/_date-picker.scss
@@ -8,7 +8,7 @@
 @use '../../colors' as *;
 @use '../../config' as *;
 @use '../../motion' as *;
-@use '../../theme' as *;
+@use '../../compat/theme' as *;
 @use '../../spacing' as *;
 @use '../../type' as *;
 @use '../form/form';

diff --git a/packages/styles/scss/components/date-picker/_flatpickr.scss b/packages/styles/scss/components/date-picker/_flatpickr.scss
@@ -7,7 +7,7 @@
 
 // @use '../../config' as *;
 @use '../../motion' as *;
-@use '../../theme' as *;
+@use '../../compat/theme' as *;
 @use '../../spacing' as *;
 @use '../../type' as *;
 @use '../../utilities/box-shadow' as *;

diff --git a/packages/styles/scss/components/dropdown/_dropdown.scss b/packages/styles/scss/components/dropdown/_dropdown.scss
@@ -9,7 +9,7 @@
 @use '../../config' as *;
 @use '../../motion' as *;
 @use '../../spacing' as *;
-@use '../../theme' as *;
+@use '../../compat/theme' as *;
 @use '../../type' as *;
 @use '../../utilities/box-shadow' as *;
 @use '../../utilities/convert' as *;

diff --git a/packages/styles/scss/components/list-box/_list-box.scss b/packages/styles/scss/components/list-box/_list-box.scss
@@ -11,7 +11,7 @@
 @use '../tag/mixins' as *;
 @use '../../config' as *;
 @use '../../colors' as *;
-@use '../../theme' as *;
+@use '../../compat/theme' as *;
 @use '../../type' as *;
 @use '../../spacing' as *;
 @use '../../motion' as *;

diff --git a/packages/styles/scss/components/number-input/_number-input.scss b/packages/styles/scss/components/number-input/_number-input.scss
@@ -9,7 +9,7 @@
 @use '../../config' as *;
 @use '../../motion' as *;
 @use '../../spacing' as *;
-@use '../../theme' as *;
+@use '../../compat/theme' as *;
 @use '../../type' as *;
 @use '../../utilities/skeleton' as *;
 @use '../../utilities/button-reset';

diff --git a/packages/styles/scss/components/overflow-menu/_overflow-menu.scss b/packages/styles/scss/components/overflow-menu/_overflow-menu.scss
@@ -8,7 +8,7 @@
 @use '../../config' as *;
 @use '../../motion' as *;
 @use '../../spacing' as *;
-@use '../../theme' as *;
+@use '../../compat/theme' as *;
 @use '../../type' as *;
 @use '../button/tokens' as button;
 @use '../../utilities/box-shadow' as *;

diff --git a/packages/styles/scss/components/radio-button/_radio-button.scss b/packages/styles/scss/components/radio-button/_radio-button.scss
@@ -9,7 +9,7 @@
 // Radio
 //-----------------------------
 
-@use '../../theme' as *;
+@use '../../compat/theme' as *;
 @use '../../type';
 @use '../form';
 @use '../../utilities/focus-outline' as *;

diff --git a/packages/styles/scss/components/search/_search.scss b/packages/styles/scss/components/search/_search.scss
@@ -9,7 +9,7 @@
 // Search
 //-----------------------------
 
-@use '../../theme' as *;
+@use '../../compat/theme' as *;
 @use '../../config' as *;
 @use '../../type';
 @use '../../motion' as *;

diff --git a/packages/styles/scss/components/structured-list/_structured-list.scss b/packages/styles/scss/components/structured-list/_structured-list.scss
@@ -9,7 +9,7 @@
 @use '../../feature-flags' as *;
 @use "../../type" as *;
 @use '../../motion';
-@use '../../theme' as *;
+@use '../../compat/theme' as *;
 @use "../../utilities/focus-outline" as *;
 @use "../../utilities/skeleton" as *;
 @use "../../utilities/high-contrast-mode" as *;

diff --git a/packages/styles/scss/components/tile/_tile.scss b/packages/styles/scss/components/tile/_tile.scss
@@ -8,7 +8,7 @@
 @use '../../config' as *;
 @use '../../motion' as *;
 @use '../../spacing' as *;
-@use '../../theme' as *;
+@use '../../compat/theme' as *;
 @use '../../type' as *;
 @use '../button/tokens' as button;
 @use '../../utilities/focus-outline' as *;

diff --git a/packages/styles/scss/components/treeview/_treeview.scss b/packages/styles/scss/components/treeview/_treeview.scss
@@ -8,7 +8,7 @@
 @use '../../config' as *;
 @use '../../motion' as *;
 @use '../../spacing' as *;
-@use '../../theme' as *;
+@use '../../compat/theme' as *;
 @use '../../type' as *;
 @use '../../utilities/convert' as *;
 @use '../../utilities/focus-outline' as *;