feat(styles): add initial entrypoints and tests for styles (#8400)

* feat(styles): add updated motion package, docs, and tests

* chore(styles): add tests for colors

* feat(styles): add additional flags for config and add tests

* chore(styles): add snapshots

* docs(style): add testing style guide and recipes

* feat(styles): add additional entrypoints and tests

* docs(style): update README and package.json with description

* fix(styles): update entrypoint

* chore(grid): update tests for grid

Co-authored-by: kodiakhq[bot] <49736102+kodiakhq[bot]@users.noreply.github.com>

Author: joshblack

docs/migration/11.x-motion.md

@@ -4,8 +4,14 @@
 
 ## Changes
 
-| v10                        | v11        |
-| -------------------------- | ---------- |
-| `$carbon--easings`         | `$easings` |
-| `@function carbon--motion` | `motion`   |
-| `@mixin carbon--motion`    | `motion`   |
+| v10                        | v11                     |
+| -------------------------- | ----------------------- |
+| `$carbon--easings`         | `$easings`              |
+| `@function carbon--motion` | `@function motion`      |
+| `@mixin carbon--motion`    | `@mixin motion`         |
+|                            | `$duration-fast-01`     |
+|                            | `$duration-fast-02`     |
+|                            | `$duration-moderate-01` |
+|                            | `$duration-moderate-02` |
+|                            | `$duration-slow-01`     |
+|                            | `$duration-slow-02`     |

docs/style.md

@@ -729,3 +729,73 @@ When writing SassDoc comments, you should use three forward slashes:
   // ...
 }
 ```
+
+### Testing
+
+We use the `@carbon/test-utils` package to test our Sass styles in JavaScript.
+Inside of this package, there is a `SassRenderer` module that you can bring in
+that allows you to get values from Sass in JavaScript to be used in test
+assertions.
+
+The basic template for tests for Sass files will look like:
+
+```js
+/**
+ * <COPYRIGHT>
+ *
+ * @jest-environment node
+ */
+
+'use strict';
+
+const { SassRenderer } = require('@carbon/test-utils/scss');
+
+const { render } = SassRenderer.create(__dirname);
+
+describe('@carbon/styles/scss/config', () => {
+  test('Public API', async () => {
+    const { get } = await render(`
+      // You can bring in modules using the path from the test file
+      @use '../path/to/sass/module';
+
+      $test: true;
+
+      // The `get` helper will let you pass a value from Sass to JavaScript
+      $_: get('test', $test);
+    `);
+
+    // get('<key>') gives you both the JavaScript representation of a value
+    // along with the `nativeValue` which comes from Dart sass. Use `.value`
+    // to get the JavaScript value and make assertions
+    expect(get('test').value).toBe(true);
+  });
+});
+```
+
+#### Recipes
+
+##### Public API
+
+Sometimes it is useful to assert that a module's Public API matches what is
+expected or does not change between versions. To do this in a test file, you can
+use the `sass:meta` module along with several helpers for getting the variables
+and functions from a module. Unfortunately, mixins need to be checked by hand
+using the `mixin-exists` function from `sass:meta`.
+
+```js
+test('Public API', async () => {
+  await render(`
+    @use 'sass:meta';
+    @use '../path/to/module';
+
+    // Get the variables for the module under the namespace `module`
+    $_: get('variables', meta.module-variables('module'));
+
+    // Get the functions for the module under the namespace `module`
+    $_: get('variables', meta.module-functions('module'));
+
+    // Verify that a mixin exists, optionally within a module
+    $_: get('mixin-name', meta.mixin-exists('mixin-name', 'module');
+  `);
+});
+```

packages/grid/__tests__/scss-test.js

@@ -21,7 +21,7 @@ describe('@carbon/grid', () => {
 
       $_: get('variables', meta.module-variables('grid'));
       $_: get('mixins', (
-        grid: meta.mixin-exists('grid', 'grid'),
+        grid: meta.mixin-exists('css-grid', 'grid'),
       ));
     `);
 

packages/grid/index.scss

@@ -9,8 +9,4 @@
   $prefix: 'bx' !default,
 );
 @forward 'scss/modules/breakpoint';
-@forward 'scss/modules/mixins';
-
-@use 'scss/modules/mixins';
-
-@include mixins.grid();
+@forward 'scss/modules/css-grid';

packages/motion/index.scss

@@ -54,3 +54,33 @@ $easings: (
 @mixin motion($name, $mode) {
   transition-timing-function: motion($name, $mode);
 }
+
+/// @access public
+/// @type Duration
+/// @group @carbon/motion
+$duration-fast-01: 70ms;
+
+/// @access public
+/// @type Duration
+/// @group @carbon/motion
+$duration-fast-02: 110ms;
+
+/// @access public
+/// @type Duration
+/// @group @carbon/motion
+$duration-moderate-01: 150ms;
+
+/// @access public
+/// @type Duration
+/// @group @carbon/motion
+$duration-moderate-02: 240ms;
+
+/// @access public
+/// @type Duration
+/// @group @carbon/motion
+$duration-slow-01: 400ms;
+
+/// @access public
+/// @type Duration
+/// @group @carbon/motion
+$duration-slow-02: 700ms;

packages/styles/README.md

@@ -0,0 +1,73 @@
+# @carbon/styles
+
+> Styles for the Carbon Design System
+
+## Getting started
+
+To install `@carbon/styles` in your project, you will need to run the following
+command using [npm](https://www.npmjs.com/):
+
+```bash
+npm install -S @carbon/styles
+```
+
+If you prefer [Yarn](https://yarnpkg.com/en/), use the following command
+instead:
+
+```bash
+yarn add @carbon/styles
+```
+
+## Usage
+
+### Sass entrypoints
+
+| Entrypoint                   | Description                                                                                                  |
+| ---------------------------- | ------------------------------------------------------------------------------------------------------------ |
+| `index.scss`                 | Entrypoint that brings in all of the CSS for the Carbon Design System                                        |
+| `scss/_breakpoint.scss`      | Use helpers to easily create breakpoints in your product that align to the 16 column grid                    |
+| `scss/_colors.scss`          | Provides access to colors from the IBM Design Language                                                       |
+| `scss/_config.scss`          | Allows you to configure various behaviors of Carbon                                                          |
+| `scss/_feature-flags.scss`   | Enable or disable various feature flags to try out experiments within Carbon                                 |
+| `scss/_grid.scss`            | Provides access to grid mixins and helpers for working with the 16 column grid                               |
+| `scss/_motion.scss`          | Provides access to motion easing curves and durations from the IBM Design Language                           |
+| `scss/_reset.scss`           | Brings in a CSS reset to enable consistent styles across browsers                                            |
+| `scss/_themes.scss`          | Provides access to the default themes used with Carbon                                                       |
+| `scss/_theme.scss`           | Provides access to the current theme and theme helpers to use in your project                                |
+| `scss/_type.scss`            | Provides access to type tokens configured for use with IBM Plex                                              |
+| `scss/components/*`          | Bring in a single component, or several that you need for your project. Great for optimizing CSS bundle size |
+| `scss/components/index.scss` | Bring in all component styles                                                                                |
+
+### Optimizing CSS bundle size
+
+When you bring in `@carbon/styles` directly, it will include all of the styles
+available for the Carbon Design System. If you would like to bring in only the
+styles that you use, then we recommend structuring your imports in the following
+way:
+
+```scss
+// Bring in top-level / global styles
+@use '@carbon/styles/reset';
+
+// Bring in each component that you use
+@use '@carbon/styles/scss/components/<component>';
+```
+
+For example, if your project is only using the Accordion and Breadcrumb
+components then you would do the following:
+
+```scss
+@use '@carbon/styles/reset';
+@use '@carbon/styles/scss/components/accordion';
+@use '@carbon/styles/scss/components/breadcrumb';
+```
+
+## 🙌 Contributing
+
+We're always looking for contributors to help us fix bugs, build new features,
+or help us improve the project documentation. If you're interested, definitely
+check out our [Contributing Guide](/.github/CONTRIBUTING.md)! 👀
+
+## 📝 License
+
+Licensed under the [Apache 2.0 License](/LICENSE).

packages/styles/index.scss

@@ -8,12 +8,12 @@
 @forward 'scss/config' with (
   $prefix: 'bx' !default,
 );
-@forward '@carbon/colors';
-@forward '@carbon/grid' hide $prefix;
-@forward '@carbon/layout' hide map-deep-get, key-by-index, last-map-item;
-@forward '@carbon/motion';
-@forward '@carbon/themes' hide $white;
-@forward '@carbon/type' hide $prefix;
+@forward 'scss/colors' hide $white;
+@forward 'scss/grid';
+@forward 'scss/motion';
+@forward 'scss/type';
+@forward 'scss/themes';
+@forward 'scss/theme';
 
 @use 'scss/reset';
 @use 'scss/components';

packages/styles/package.json

@@ -1,6 +1,7 @@
 {
   "name": "@carbon/styles",
   "private": true,
+  "description": "Styles for the Carbon Design System",
   "version": "0.4.0",
   "license": "Apache-2.0",
   "repository": {
@@ -18,6 +19,7 @@
   ],
   "dependencies": {
     "@carbon/colors": "^10.23.0",
+    "@carbon/feature-flags": "^0.3.0",
     "@carbon/grid": "^10.25.0",
     "@carbon/layout": "^10.23.0",
     "@carbon/motion": "^10.16.0",