docs(Theme): update Theme docs with new guidance/usage (#2998)

* docs(Theme): update Theme docs with new guidance/usage * Update src/pages/guidelines/themes/code.mdx Co-authored-by: Anna Gonzales <agonz@us.ibm.com> * Update src/pages/guidelines/themes/code.mdx Co-authored-by: Anna Gonzales <agonz@us.ibm.com> * docs(Themes): update docs with PR changes * chore(number-input): run prettier * docs(theme): update theme docs for v11 * docs(themes): update overview page for v11 * docs(theme): update overview page, remove tokens * docs(theme): rephrase notification for elements packages Co-authored-by: Anna Gonzales <agonz@us.ibm.com> Co-authored-by: Taylor Jones <tay1orjones@users.noreply.github.com> Co-authored-by: Taylor Jones <taylor.jones826@gmail.com> Co-authored-by: kodiakhq[bot] <49736102+kodiakhq[bot]@users.noreply.github.com>
carbon-design-system · Sep 26, 2022 · 85db97a · 85db97a · vercel · Sep 26, 2022
1 parent 34f3b22
commit 85db97a
Show file tree

Hide file tree

Showing 8 changed files with 95 additions and 791 deletions.
diff --git a/src/pages/designing/kits/figma.mdx b/src/pages/designing/kits/figma.mdx
@@ -49,6 +49,10 @@ There are four Carbon v11 theme libraries, two light (White and Gray 10) and two
 dark (Gray 90 and Gray 100). Each theme lives in its own Figma library. You can
 turn on as many libraries as you’d like.
 
+If you are using Carbon v11, the `(v11 BETA) White Theme` library and
+`v11 Text Styles` library are now available. The other v11 theme libraries will
+be available in Figma at the end of July 2022.
+
 Inside of a design file, navigate to the **Main menu** panel in the top left of
 the toolbar (A). Open the menu and select **Libraries** from the list (B).
 

diff --git a/src/pages/guidelines/2x-grid/implementation.mdx b/src/pages/guidelines/2x-grid/implementation.mdx
@@ -15,8 +15,8 @@ with five default breakpoints and dozens of predefined classes.
 
 <InlineNotification>
 
-If you’re using `@carbon/styles` or `@carbon/react` there’s no reason to install
-the grid package separately. See our [get started](/developing/get-started/)
+If you're using `@carbon/react`, you probably don't need need to install the
+grid package separately. See our [Carbon React](/developing/frameworks/react/)
 guide to start building.
 
 </InlineNotification>

diff --git a/src/pages/guidelines/color/code.mdx b/src/pages/guidelines/color/code.mdx
@@ -15,9 +15,9 @@ consistent application of color.
 
 <InlineNotification>
 
-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.
+If you're using `@carbon/react`, you probably don't need need to install the
+color package separately. See our [Carbon React](/developing/frameworks/react/)
+guide to start building.
 
 </InlineNotification>
 

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/react` 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`, you probably don't need need to install the
+motion package separately. See our [Carbon React](/developing/frameworks/react/)
+guide to start building.
 
 </InlineNotification>
 

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/react` 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`, you probably don't need need to install the
+layout package separately. See our [Carbon React](/developing/frameworks/react/)
+guide to start building.
 
 </InlineNotification>
 

diff --git a/src/pages/guidelines/themes/code.mdx b/src/pages/guidelines/themes/code.mdx
@@ -17,16 +17,15 @@ Use the themes package to customize your product while maintaining consistency.
 
 <InlineNotification>
 
-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.
+If you're using `@carbon/react`, you probably don't need need to install the
+themes package separately. See our [Carbon React](/developing/frameworks/react/)
+guide to start building.
 
 </InlineNotification>
 
 <AnchorLinks>
 
-<AnchorLink>Get started</AnchorLink>
-<AnchorLink>Usage</AnchorLink>
+<AnchorLink>Get started</AnchorLink> <AnchorLink>Usage</AnchorLink>
 <AnchorLink>Resources</AnchorLink>
 
 </AnchorLinks>
@@ -52,69 +51,78 @@ yarn add @carbon/themes
 You can use `@carbon/themes` in JavaScript or Sass by including this package in
 your project. By default, `@carbon/themes` provides a set of color tokens that
 are pre-defined for a specific theme. Currently, we offer the following color
-themes: white, gray 10, gray 90, gray 100 .
+themes: white, gray 10, gray 90, gray 100.
 
 You can preview all of the token values for this on the
-[Carbon Design System website](https://www.carbondesignsystem.com/guidelines/color/usage)
-.
+[color guidelines](/guidelines/color/usage) page.
 
 ### Sass
 
 If your project is using Sass, you can include this package and the
 corresponding default theme by writing the following in your Sass file:
 
 ```scss
-@import '@carbon/themes/scss/themes';
-```
-
-By default, the white theme will be initialized. If you would like to include
-another theme, you can do so by calling our mixin. For example:
-
-```scss
-@import '@carbon/themes/scss/themes';
+@use '@carbon/themes';
 
-// Use the gray 10 theme
-@include theme($theme--g10);
+.my-component {
+  // Use tokens from the theme, this will map to a CSS Custom Property
+  color: themes.$token-01;
+}
 
-// Use the gray 90 theme
-@include theme($theme--g90);
+:root {
+  // Emit CSS Custom Properties for the current theme
+  @include themes.theme();
+}
 
-// Use the gray 100 theme
-@include theme($theme--g100);
+// Get the value of a specific token
+$custom-variable: rgba(themes.get('token-01'), 0.25);
 ```
 
-Alternatively, you can set the global theme variable then call the mixin without
-passing in a theme name.
+By default, the white theme will be initialized. If you would like to include
+another theme, you can do so by configuring the sass module using `with`. For
+example:
 
 ```scss
-@import '@carbon/themes/scss/themes';
-
-$theme: $theme--g10;
-
-// Use the gray 10 theme
-@include theme();
+@use '@carbon/themes/scss/themes' as *;
+@use '@carbon/themes' with ($theme: $g100);
 ```
 
-Inline theming can be done by using the mixin. For example:
+Inline theming of theme switching can be done by using the mixin. For example:
 
 ```scss
-@import '@carbon/themes/scss/themes';
+@use '@carbon/themes/scss/themes' as *;
+@use '@carbon/themes';
+
+:root {
+  @include themes.theme($white);
+}
 
-// Use the default white theme here
+[data-carbon-theme='g10'] {
+  @include themes.theme($g10);
+}
 
-.my-dark-theme {
-  @include theme($theme--g90) {
-    // Use the dark theme here
-  }
+[data-carbon-theme='g90'] {
+  @include themes.theme($g90);
 }
 
-.my-darker-theme {
-  @include theme($theme--g100) {
-    // Use the darker theme here
-  }
+[data-carbon-theme='g100'] {
+  @include themes.theme($g100);
 }
 ```
 
+Themes can also be extended with your own custom tokens:
+
+```scss
+@use '@carbon/themes/scss/themes';
+@use '@carbon/themes' with
+  (
+    $fallback: themes.$g100,
+    $theme: (
+      token-01: #000000,
+    )
+  );
+```
+
 ### JavaScript
 
 If you're looking to use these themes in JavaScript, we export a variety of
@@ -143,7 +151,7 @@ import {
   <Column colMd={4} colLg={4} noGutterSm>
     <ResourceCard
       subTitle="Carbon theme package"
-      href="https://github.com/carbon-design-system/carbon/blob/v10/packages/themes"
+      href="https://github.com/carbon-design-system/carbon/tree/main/packages/themes"
     >
 
 <MdxIcon name="bee" />