From 5fc4fb6311fe125c1fb92e2b57937ce727967783 Mon Sep 17 00:00:00 2001
From: Alison Joseph <alison.joseph@us.ibm.com>
Date: Wed, 3 Apr 2024 16:52:33 -0500
Subject: [PATCH] docs: add docs around component tokens to migration guide
 (#16129)

---
 docs/migration/v11.md        | 17 +++++++++++++++++
 packages/styles/docs/sass.md |  2 +-
 2 files changed, 18 insertions(+), 1 deletion(-)

diff --git a/docs/migration/v11.md b/docs/migration/v11.md
index 7b3db247c9c8..ac0cd2466cd1 100644
--- a/docs/migration/v11.md
+++ b/docs/migration/v11.md
@@ -1878,6 +1878,23 @@ const { white, g10, g90, g100 } = v10;
   counterpart.
 - **Deprecated:** v10 token was removed in v11.
 
+V11 introduces the idea of
+[component tokens](https://github.com/carbon-design-system/carbon/blob/main/packages/styles/docs/sass.md#component-tokens)
+for tokens specific to a particular component; for example button, tag or
+notification. If you'd like to use these component tokens in your stylesheet,
+you'll need to `@use` them:
+
+```scss
+@use '@carbon/styles/scss/components/button';
+
+.my-selector {
+  background: button.$button-primary;
+}
+```
+
+Read more about using or customizing
+[component tokens](https://github.com/carbon-design-system/carbon/blob/main/packages/styles/docs/sass.md#component-tokens).
+
 | V10 token name     | V11 token name            | V11 Contextual token   | Status     |
 | ------------------ | ------------------------- | ---------------------- | ---------- |
 | active-danger      | button-danger-active      | —                      | Updated    |
diff --git a/packages/styles/docs/sass.md b/packages/styles/docs/sass.md
index dd193c4b16d3..21316dc0d829 100644
--- a/packages/styles/docs/sass.md
+++ b/packages/styles/docs/sass.md
@@ -400,7 +400,7 @@ synonymous - `@carbon/react` re-exports everything from `@carbon/styles`.**
 | treeview              | `@use '@carbon/styles/scss/components/treeview';`              | [`scss/components/treeview`](../scss/components/treeview)                           |
 | ui-shell              | `@use '@carbon/styles/scss/components/ui-shell';`              | [`scss/components/ui-shell`](../scss/components/ui-shell)                           |
 
-**Component tokens**
+#### Component tokens
 
 In some situations, you may want to change the tokens for a specific component.
 To do so you will need to configure the modules and provide the tokens you would