From 43f6731decc5a7c5362c48b7afb6b6046b9d0a8e Mon Sep 17 00:00:00 2001
From: TJ Egan <tw15egan@gmail.com>
Date: Mon, 15 Apr 2024 07:30:51 -0700
Subject: [PATCH] docs(@carbon/colors): Update carbon colors documentation
 (#16193)

* docs(@carbon/colors): update documentation for v11

* docs(@carbon/colors): update more documentation
---
 packages/colors/README.md | 79 +++++++--------------------------------
 1 file changed, 13 insertions(+), 66 deletions(-)

diff --git a/packages/colors/README.md b/packages/colors/README.md
index 5eef68273d75..82f39fdf43ea 100644
--- a/packages/colors/README.md
+++ b/packages/colors/README.md
@@ -28,56 +28,31 @@ Sass.
 In Sass, you can import the files individual by doing:
 
 ```scss
-@import '@carbon/colors/scss/colors';
-```
-
-This file automatically includes the `carbon--colors` mixin which initializes
-all the color variables for the IBM Design Language.
-
-These color variables follow the naming convention: `$carbon--<swatch>-<grade>`.
-For example:
+@use '@carbon/colors';
 
-```scss
-$carbon--blue-50;
-$carbon--cool-gray-10;
-$carbon--black-100;
-$carbon--white-0;
+// Another way if using `@carbon/react
+@use '@carbon/react/scss/colors';
 ```
 
-You can also use the shorthand form of these colors by dropping the `carbon--`
-namespace:
+These color variables follow the naming convention: `<swatch>-<grade>`. For
+example:
 
 ```scss
-$blue-50;
-$cool-gray-10;
-$black-100;
-$white-0;
-```
-
-_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._
-
-If you would like you choose when these variables are defined, then you can call
-the `carbon--colors` mixin directly by importing the following file:
-
-```scss
-@import '@carbon/colors/scss/mixins';
-
-// ...
-@include carbon--colors();
+colors.$blue-50;
+colors.$cool-gray-10;
+colors.$black-100;
+colors.$white-0;
 ```
 
 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
-`$carbon--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:
+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 -->
 
 ```scss
-$carbon--colors: (
+$colors: (
   'blue': (
     10: #edf4ff,
     // ...
@@ -87,34 +62,6 @@ $carbon--colors: (
 
 <!-- prettier-ignore-end -->
 
-You can include this variable by including `@carbon/colors/scss/colors` or
-calling the `carbon--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