feat(themes): align CSS custom properties with Carbon (#948)

* feat(themes): normalise themes

* refactor(themes): update JavaScript theme

* refactor(reset): remove CSS output

* refactor(themes): add feature flag compatibility

* refactor(themes): add feature flag compatibility

* chore: merge `dev` into `spike/css-custom-properties`

* refactor(themes): add existing compatibility

* refactor(theme): add development warning

* feat(themes): align CSS custom properties with Carbon

* chore(release): 1.40.0-alpha.1 [skip ci]

# [1.40.0-alpha.1](v1.39.0...v1.40.0-alpha.1) (2021-04-14)

### Features

* **themes:** align CSS custom properties with Carbon ([df1e91a](df1e91a))
* **themes:** normalise themes ([b644f26](b644f26))

* chore(release): 1.40.0-alpha.2 [skip ci]

# [1.40.0-alpha.2](v1.40.0-alpha.1...v1.40.0-alpha.2) (2021-04-19)

### Bug Fixes

* **PanelV2:** change footer position to absolute ([#940](#940)) ([160293f](160293f))

### Features

* **telemetry:** add Carbon telemetry ([#894](#894)) ([1e0fa3a](1e0fa3a))

* docs(themes): add migration justification

* docs(themes): reduce warning messages

* feat(themes): add check for Carbon feature flag

* docs(themes): add explicit CSS custom property guidance

* chore: merge `dev` into `spike/css-custom-propereties`

* chore: merge `dev` into `spike/css-custom-properities`

* chore: merge `dev` into `sp[ike/css-custom-propereties`

Co-authored-by: semantic-release-bot <[email protected]>

.storybook/main.js

@@ -1,15 +1,13 @@
 /**
  * @file Configuration.
- * @copyright IBM Security 2020
+ * @copyright IBM Security 2020 - 2021
  */
 
-const { sync } = require('git-branch');
-const { merge } = require('webpack-merge');
-
 const { BRANCH, CIRCLE_BRANCH } = process.env;
 
 // Pass the branch name from Netlify, CircleCI, or the local branch.
-process.env.STORYBOOK_BRANCH = BRANCH || CIRCLE_BRANCH || sync();
+process.env.STORYBOOK_BRANCH =
+  BRANCH || CIRCLE_BRANCH || require('git-branch').sync();
 
 module.exports = {
   addons: [
@@ -26,7 +24,10 @@ module.exports = {
   ],
   stories: ['../src/**/*.stories.*'],
   webpackFinal: async configuration =>
-    merge(configuration, {
+    require('webpack-merge').merge(configuration, {
+      devServer: {
+        stats: 'errors-only',
+      },
       module: {
         rules: [
           {

docs/migration/2.x/themes.md

@@ -1,5 +1,13 @@
 # Themes
 
+To align with [Carbon's support for inline theming with CSS custom properties](https://medium.com/carbondesign/whats-coming-to-carbon-in-2021-39a4c7d1762a), theme-related feature flags and variables, instead of referencing Carbon for IBM Security-specific members, now directly reference underlying Carbon feature flags and members to provide consistency in accessing common variables.
+
+### Feature flags
+
+| `1.x`                                   | `2.x`                          |
+| --------------------------------------- | ------------------------------ |
+| `security--css-custom-property-theming` | `enable-css-custom-properties` |
+
 ### Functions
 
 | `1.x`   | `2.x`                            |
@@ -8,6 +16,7 @@
 
 ### Variables
 
-| `1.x`              | `2.x`                            |
-| ------------------ | -------------------------------- |
-| `$security--theme` | [Themes](../../themes/README.md) |
+| `1.x`                                               | `2.x`                                   |
+| --------------------------------------------------- | --------------------------------------- |
+| `$security--theme`                                  | [Themes](../../themes/README.md)        |
+| `var(--token)`, for example `var(--interactive-01)` | `$token`, for example `$interactive-01` |

docs/themes/README.md

@@ -4,7 +4,7 @@
 
 ## Usage
 
-Themes are used for applying color and offered by outputting Carbon for IBM Security-specific [CSS custom properties](https://developer.mozilla.org/en-US/docs/Web/CSS/--*) as theme tokens, independently of [Carbon's experimental `enable-css-custom-properties` feature flag](https://github.com/carbon-design-system/carbon/blob/main/packages/components/src/globals/scss/_feature-flags.scss).
+Themes are used for applying color and offered by outputting [CSS custom properties](https://developer.mozilla.org/en-US/docs/Web/CSS/--*) as theme tokens.
 
 Each theme is assigned universal color variables, which are determined by [common roles and usage](https://www.carbondesignsystem.com/guidelines/color/usage). This allows for uniform color application across themes while maintaining full styling flexibility.
 
@@ -22,15 +22,6 @@ Currently, only 2 themes are supported: **Gray 100**, activated by default, and
 | Gray 100 (default) | `security--theme--g100` |
 | Cool gray 10       | `security--theme--cg10` |
 
-#### Tokens
-
-All of the components' processed and minified styles automatically includes and initializes all tokens as CSS custom properties for use with CSS. For example:
-
-```css
-var(--interactive-01);
-var(--interactive-02);
-```
-
 ### Sass
 
 If your project is using Sass, you can include the following in your Sass file: