docs(elements): update usage to v11 usage guidance (#2779)

* docs(motion): update duration token names * feat(color): update the code page for colos * fix: v11 audit design bugs (#2742) * fix: checkbox style tab bug * fix: code snippet style tab bug * fix: pagiantion style tab bug * fix: select style tab bug Co-authored-by: kodiakhq[bot] <49736102+kodiakhq[bot]@users.noreply.github.com> * docs(website): update motion usage docs * docs(website): add spacing usage docs * docs(website): update themes usage docs * docs(Typography): update usage documentation * fix v11 audit bugs: Progress indicator and Structured list (#2757) * docs(Motion/Type): update usage documenatation * docs(Spacing): add linebreak before table * docs(Motion): add linebreak * docs(Motion): add manual linebreak * chore(website): update yarn lock after merge conflicts * docs(Usage): move line break to own line Co-authored-by: Josh Black <josh@josh.black> Co-authored-by: Lauren Rice <43969356+laurenmrice@users.noreply.github.com> Co-authored-by: kodiakhq[bot] <49736102+kodiakhq[bot]@users.noreply.github.com> Co-authored-by: DAK <dakahn@users.noreply.github.com> Co-authored-by: thyhmdo <77697351+thyhmdo@users.noreply.github.com>
carbon-design-system · Mar 24, 2022 · fbe5f3a · fbe5f3a
1 parent 0331a85
commit fbe5f3a
Show file tree

Hide file tree

Showing 6 changed files with 152 additions and 179 deletions.
diff --git a/src/pages/guidelines/color/code.mdx b/src/pages/guidelines/color/code.mdx
@@ -15,7 +15,7 @@ consistent application of color.
 
 <InlineNotification>
 
-If you’re using carbon-components there’s no reason to install the color package
+If you’re using `@carbon/react` there’s no reason to install the color package
 separately. See our [get started](/get-started/develop/react) guide to start
 building.
 
@@ -47,100 +47,57 @@ yarn add @carbon/colors
 
 ## Usage
 
-You can use the `@carbon/colors` module in your JavaScript, in addition to your
-Sass.
-
 ### Sass
 
-In Sass, you can import the files individual by doing:
-
-```scss
-@import '@carbon/colors/scss/colors';
-```
-
-This file automatically includes the `colors` mixin which initializes all the
-color variables for the IBM Design Language.
-
-These color variables follow the naming convention: `$<swatch>-<grade>`. For
-example:
+The `@carbon/colors` package enables you to access colors from the IBM Design
+Language in Sass. You can access a color directly from the package by writing
+the following:
 
 ```scss
-$blue-50;
-$cool-gray-10;
-$black-100;
-$white-0;
-```
-
-You can also use the shorthand form of these colors by dropping the ``
-namespace:
+@use '@carbon/colors';
 
-```scss
-$blue-50;
-$cool-gray-10;
-$black-100;
-$white-0;
+.selector {
+  background: colors.$blue-50;
+}
 ```
 
-_Note: the shorthand variables require that you do not have any other
-conflicting variables in your setup. Namespaced variables are always preferred
-for this reason, unless you are confident that no collisions will occur._
+For a full list of colors exported, refer to the
+[API](https://github.com/carbon-design-system/carbon/blob/main/packages/colors/docs/sass.md#api)
+section in the package's Sass Documentation.
 
-If you would like you choose when these variables are defined, then you can call
-the `colors` mixin directly by importing the following file:
+In addition to individual colors, you can access all colors in a `Map` using the
+`$colors` variable.
 
 ```scss
-@import '@carbon/colors/scss/mixins';
-
-// ...
-@include colors();
+@use '@carbon/colors';
+@each $swatch, $grades in colors.$colors {
+  @each $grade in $grades {
+    //
+  }
+}
 ```
 
-Alongside the color variables detailed above, we also provide a map of colors so
-that you can programmatically use these values. This map is called `$colors` and
-each key is the name of a swatch. The value of these swatches is also a map, but
-each key is now the grade. In code, this looks like the following:
-
-<!-- prettier-ignore-start -->
+Each key in the `$colors` map is the name of a group of colors, also known as a
+swatch. The value of each entry is a `Map` where the keys are the color grade
+and the values are the hex codes for the color at that grade. For example:
 
 ```scss
 $colors: (
-  'blue': (
-    10: #edf4ff,
-    // ...
-  )
+  blue: (
+    10: #edf5ff,
+    20: #d0e2ff,
+    30: #a6c8ff,
+    40: #78a9ff,
+    50: #4589ff,
+    60: #0f62fe,
+    70: #0043ce,
+    80: #002d9c,
+    90: #001d6c,
+    100: #001141,
+  ),
 );
 ```
 
-<!-- prettier-ignore-end -->
-
-You can include this variable by including `@carbon/colors/scss/colors` or
-calling the `colors()` mixin directly.
-
-#### Migrating from previous versions
-
-If you were originally using a project that had color variables defined as
-`$ibm-color__<swatch>-<grade>`, or are relying on `$ibm-color-map`, you can also
-use the entrypoint described above to access these colors. They are meant as an
-easier way to help adopt these packages. However, these variables will be
-removed in the next release of Carbon.
-
-Similar to previous efforts, we also provide colors in the formats mentioned
-above. For example:
-
-```scss
-$ibm-color__blue-50;
-$ibm-color__warm-gray-100;
-```
-
-If you would like a mixin to conditionally include these variables, you can
-include the mixin by using:
-
-```scss
-@import '@carbon/colors/scss/mixins';
-
-@include ibm--colors();
-```
-
 ### JavaScript
 
 For JavaScript, you can import and use this module by doing the following in

diff --git a/src/pages/guidelines/motion/code.mdx b/src/pages/guidelines/motion/code.mdx
@@ -16,9 +16,9 @@ across digital experiences.
 
 <InlineNotification>
 
-If you’re using carbon-components there’s no reason to install the motion
-package separately. See our [get started](/get-started/develop/react) guide to
-start building.
+If you’re using `@carbon/react` there’s no reason to install the motion package
+separately. See our [get started](/get-started/develop/react) guide to start
+building.
 
 </InlineNotification>
 
@@ -48,34 +48,32 @@ yarn add @carbon/motion
 
 ## Usage
 
-`@carbon/motion` supports standard, entrance, and exit easing curves in two
-motion modes: productive and expressive. You can access these curves using
-either Sass or JavaScript.
-
-### Sass
-
-`@carbon/motion` exports a `motion` function and `motion` mixin that you can use
-to access the value of a motion curve or include that curve as the
-`transition-timing-function` for a selector. To use these helpers, you can do
-the following in your project:
+The `@carbon/motion` package enables you to access motion curves and durations
+built for the IBM Design Language in Sass. You can access these values directly
+from the package by writing the following:
 
 ```scss
-@import '@carbon/motion/scss/motion.scss';
+@use '@carbon/motion';
+.selector {
+  // Set `transition-timing-function` directly
+  @include motion.motion(standard, productive);
 
-.my-custom-selector {
-  // Supplies the standard easing curve, using the productive mode by default
-  transition-timing-function: motion(standard);
-}
+  // Alternatively
+  transition: opacity motion.motion(standard, productive);
 
-.my-custom-selector-v2 {
-  // Supplies the standard easing curve, but with the expressive mode, on the
-  // transition-timing-function property for this selector
-  @include motion(standard, expressive);
+  // Or use a duration
+  transition: opacity motion.$duration-fast-01;
 }
 ```
 
-Both the `motion` function and mixin support passing in the name of the motion
-curve and the mode you want to work in.
+#### API
+
+<br />
+| Name | Type | | :---------------------- | :------- | | `$duration-fast-01`
+| Duration | | `$duration-fast-02` | Duration | | `$duration-moderate-01` | Duration
+| | `$duration-moderate-02` | Duration | | `$duration-slow-01` | Duration | | `$duration-slow-02`
+| Duration | | `$easings` | Map | | `@mixin motion` | Mixin | | `@function motion`
+| Mixin |
 
 ### JavaScript
 
@@ -96,6 +94,21 @@ import { easings, motion } from '@carbon/motion';
 motion('standard', 'productive'); // Returns a string `cubic-bezier()` function
 ```
 
+### Configuration
+
+You can configure parts of the `@carbon/motion` package with Sass Modules. For
+example, you can change the `$prefix` used by writing the following:
+
+```scss
+@use '@carbon/motion' with ($prefix: 'custom-prefix');
+```
+
+For a full list of options that you can configure, check out the table below.
+
+| Option    | Description                                                       | Default |
+| :-------- | :---------------------------------------------------------------- | :------ |
+| `$prefix` | The prefix that is used in selectors, CSS Custom Properties, etc. | `'cds'` |
+
 ## Resources
 
 <Row className="resource-card-group">

diff --git a/src/pages/guidelines/spacing/code.mdx b/src/pages/guidelines/spacing/code.mdx
@@ -20,9 +20,9 @@ spacing and alignment.
 
 <InlineNotification>
 
-If you’re using carbon-components there’s no reason to install the layout
-package separately. See our [get started](/get-started/develop/react) guide to
-start building.
+If you’re using `@carbon/react` there’s no reason to install the layout package
+separately. See our [get started](/get-started/develop/react) guide to start
+building.
 
 </InlineNotification>
 
@@ -52,25 +52,41 @@ yarn add @carbon/layout
 
 ## Usage
 
-`@carbon/layout` provides a couple of useful utilities alongside the
-specification for the grid system for the IBM Design Language. This package
-includes:
-
-| Feature         | Description                                                                                                                             |
-| --------------- | --------------------------------------------------------------------------------------------------------------------------------------- |
-| Breakpoints     | Variables and settings for the IBM Design Grid, including gutter and breakpoints. It also includes helpers for working with breakpoints |
-| Unit conversion | Helpers for converting from `px` to `rem` or `em`.                                                                                      |
-| Key heights     | Helpers for working with key heights at different breakpoints                                                                           |
-| Mini unit       | Helpers for working in multiples of the mini-unit                                                                                       |
-| Spacing         | Provides a spacing scale and helper for using steps in the scale                                                                        |
-
-One important thing to remember is that `@carbon/layout` is not responsible for
-the grid itself. If you are looking for a grid implementation to use, definitely
-checkout the [`@carbon/grid`](../grid) package.
-
-`@carbon/layout` provides the above features in both Sass and JavaScript. If
-you're looking for support in a different language, feel free to file an issue
-proposing the new addition!
+The `@carbon/layout` package provides spacing tokens and conversion utilities
+for the Carbon Design System. You can access these tokens and helpers by writing
+the following:
+
+```scss
+@use '@carbon/layout';
+
+.selector {
+  margin-bottom: layout.$spacing-05;
+  width: layout.rem(24px);
+  height: layout.rem(24px);
+}
+```
+
+#### API
+
+<br />
+| Export | Description | !default | | :------------------ | :---------- | :-------
+| | `$spacing-01` | | ✅ | | `$spacing-02` | | ✅ | | `$spacing-03` | | ✅ | | `$spacing-04`
+| | ✅ | | `$spacing-05` | | ✅ | | `$spacing-06` | | ✅ | | `$spacing-07` | | ✅
+| | `$spacing-08` | | ✅ | | `$spacing-09` | | ✅ | | `$spacing-10` | | ✅ | | `$spacing-11`
+| | ✅ | | `$spacing-12` | | ✅ | | `$spacing-13` | | ✅ | | `$spacing ` | | | |
+`$fluid-spacing-01` | | ✅ | | `$fluid-spacing-02` | | ✅ | | `$fluid-spacing-03`
+| | ✅ | | `$fluid-spacing-04` | | ✅ | | `$fluid-spacing ` | | | | `@function em`
+| | | | `@function rem` | | | | `$base-font-size` | | ✅ |
+
+### Configuration
+
+You can configure parts of the `@carbon/layout` package that are `!default` with
+Sass Modules. For example, you can change the `$base-font-size` by writing the
+following:
+
+```scss
+@use '@carbon/layout' with ($base-font-size: 18px);
+```
 
 ## Resources
 

diff --git a/src/pages/guidelines/themes/code.mdx b/src/pages/guidelines/themes/code.mdx
@@ -17,9 +17,9 @@ Use the themes package to customize your product while maintaining consistency.
 
 <InlineNotification>
 
-If you’re using carbon-components there’s no reason to install the themes
-package separately. See our [get started](/get-started/develop/react) guide to
-start building.
+If you’re using `@carbon/react` there’s no reason to install the themes package
+separately. See our [get started](/get-started/develop/react) guide to start
+building.
 
 </InlineNotification>