diff --git a/docs/tokens/index.md b/docs/tokens/index.md
index 8dae4cfac6..d29dfdda48 100644
--- a/docs/tokens/index.md
+++ b/docs/tokens/index.md
@@ -10,11 +10,12 @@ tokenSearch: true
## Introduction
@@ -49,6 +54,34 @@ To install design tokens, please visit our dedicated repo for instructions.
Global tokens represent the foundations of our design language and should + have context-agnostic names. These can be used and are inherited by other + token types.
+Example:--rh-brand-red-500
Semantic tokens represent context or abstraction. They communicate the purpose + of a token and are effective when a value with a single intent is used + multiple times.
+Example:--rh-color-surface-lightest
Element tokens link semantic tokens to specific elements. They are + prefixed with the element name and ship in the @rhds/elements package, + rather than @rhds/tokens.
+Example:--rh-cta-color-primary
Global tokens represent the foundations of our design language and should - have context-agnostic names. These can be used and are inherited by other - token types.
---rh-brand-red-500
- Semantic tokens represent context or abstraction. They communicate the purpose - of a token and are effective when a value with a single intent is used - multiple times.
---rh-color-surface-lightest
- Element tokens link semantic tokens to specific elements. They are - prefixed with the element name and ship in the @rhds/elements package, - rather than @rhds/tokens.
---rh-cta-color-primary
-