diff --git a/packages/website/docs/getting-started/theming/tokens/colors/background_colors_table.tsx b/packages/website/docs/getting-started/theming/tokens/colors/background_colors_table.tsx
index 7a86e4acdb57..6ad97b66edb3 100644
--- a/packages/website/docs/getting-started/theming/tokens/colors/background_colors_table.tsx
+++ b/packages/website/docs/getting-started/theming/tokens/colors/background_colors_table.tsx
@@ -11,166 +11,211 @@ export const BackgroundColorsTable = () => {
         {
           value: euiTheme.colors.backgroundBasePrimary,
           token: 'colors.backgroundBasePrimary',
+          description: <>Subtle primary-tinted background for selected or active containers.</>,
         },
         {
           value: euiTheme.colors.backgroundBaseAccent,
           token: 'colors.backgroundBaseAccent',
+          description: <>Subtle accent background for attention-drawing elements.</>,
         },
         {
           value: euiTheme.colors.backgroundBaseAccentSecondary,
           token: 'colors.backgroundBaseAccentSecondary',
+          description: <>Subtle secondary accent background.</>,
         },
         {
           value: euiTheme.colors.backgroundBaseNeutral,
           token: 'colors.backgroundBaseNeutral',
+          description: <>Subtle neutral background for informational content.</>,
         },
         {
           value: euiTheme.colors.backgroundBaseSuccess,
           token: 'colors.backgroundBaseSuccess',
+          description: <>Subtle success background for positive status indicators.</>,
         },
         {
           value: euiTheme.colors.backgroundBaseWarning,
           token: 'colors.backgroundBaseWarning',
+          description: <>Subtle warning background for caution indicators.</>,
         },
         {
           value: euiTheme.colors.backgroundBaseRisk,
           token: 'colors.backgroundBaseRisk',
+          description: <>Subtle risk background for elevated concern indicators.</>,
         },
         {
           value: euiTheme.colors.backgroundBaseDanger,
           token: 'colors.backgroundBaseDanger',
+          description: <>Subtle danger background for error states.</>,
         },
         {
           value: euiTheme.colors.backgroundBaseAssistance,
           token: 'colors.backgroundBaseAssistance',
+          description: <>Subtle assistance background for supplementary context.</>,
         },
         {
           value: euiTheme.colors.backgroundBaseSubdued,
           token: 'colors.backgroundBaseSubdued',
+          description: <>Default page-level background. Slightly tinted compared to plain.</>,
         },
         {
           value: euiTheme.colors.backgroundBasePlain,
           token: 'colors.backgroundBasePlain',
+          description: (
+            <>
+              Pure background for panels, modals, flyouts, and content containers.
+            </>
+          ),
         },
         {
           value: euiTheme.colors.backgroundBaseDisabled,
           token: 'colors.backgroundBaseDisabled',
+          description: <>Background for disabled elements and controls.</>,
         },
         {
           value: euiTheme.colors.backgroundBaseHighlighted,
           token: 'colors.backgroundBaseHighlighted',
+          description: <>Background for highlighted or focused content areas.</>,
         },
         {
           value: euiTheme.colors.backgroundBaseFormsPrepend,
           token: 'colors.backgroundBaseFormsPrepend',
+          description: <>Background for form input prepend/append areas.</>,
         },
         {
           value: euiTheme.colors.backgroundBaseFormsControlDisabled,
           token: 'colors.backgroundBaseFormsControlDisabled',
+          description: <>Background for disabled form controls.</>,
         },
         {
           value: euiTheme.colors.backgroundBaseInteractiveHover,
           token: 'colors.backgroundBaseInteractiveHover',
+          description: <>Hover state background for interactive elements like list items.</>,
         },
         {
           value: euiTheme.colors.backgroundBaseInteractiveHoverAssistance,
           token: 'colors.backgroundBaseInteractiveHoverAssistance',
+          description: <>Hover state background for assistance-themed interactive elements.</>,
         },
         {
           value: euiTheme.colors.backgroundBaseInteractiveSelect,
           token: 'colors.backgroundBaseInteractiveSelect',
+          description: <>Background for selected interactive elements.</>,
         },
         {
           value: euiTheme.colors.backgroundBaseInteractiveOverlay,
           token: 'colors.backgroundBaseInteractiveOverlay',
+          description: <>Semi-transparent overlay background for modals and dialogs.</>,
         },
         {
           value: euiTheme.colors.backgroundBaseSkeletonEdge,
           token: 'colors.backgroundBaseSkeletonEdge',
+          description: <>Edge color for skeleton loading animations.</>,
         },
         {
           value: euiTheme.colors.backgroundBaseSkeletonMiddle,
-          token: 'colors.backgroundBaseSkeletonEdge',
+          token: 'colors.backgroundBaseSkeletonMiddle',
+          description: <>Middle color for skeleton loading animations.</>,
         },
         {
           value: euiTheme.colors.backgroundLightPrimary,
           token: 'colors.backgroundLightPrimary',
+          description: <>Light primary background for callouts and highlighted sections.</>,
         },
         {
           value: euiTheme.colors.backgroundLightAccent,
           token: 'colors.backgroundLightAccent',
+          description: <>Light accent background for attention-drawing sections.</>,
         },
         {
           value: euiTheme.colors.backgroundLightAccentSecondary,
           token: 'colors.backgroundLightAccentSecondary',
+          description: <>Light secondary accent background.</>,
         },
         {
           value: euiTheme.colors.backgroundLightNeutral,
           token: 'colors.backgroundLightNeutral',
+          description: <>Light neutral background for informational sections.</>,
         },
         {
           value: euiTheme.colors.backgroundLightSuccess,
           token: 'colors.backgroundLightSuccess',
+          description: <>Light success background for positive callouts.</>,
         },
         {
           value: euiTheme.colors.backgroundLightWarning,
           token: 'colors.backgroundLightWarning',
+          description: <>Light warning background for caution callouts.</>,
         },
         {
           value: euiTheme.colors.backgroundLightRisk,
           token: 'colors.backgroundLightRisk',
+          description: <>Light risk background for elevated concern callouts.</>,
         },
         {
           value: euiTheme.colors.backgroundLightDanger,
           token: 'colors.backgroundLightDanger',
+          description: <>Light danger background for error callouts.</>,
         },
         {
           value: euiTheme.colors.backgroundLightAssistance,
           token: 'colors.backgroundLightAssistance',
+          description: <>Light assistance background for supplementary callouts.</>,
         },
         {
           value: euiTheme.colors.backgroundLightText,
           token: 'colors.backgroundLightText',
+          description: <>Light neutral text-toned background.</>,
         },
         {
           value: euiTheme.colors.backgroundFilledPrimary,
           token: 'colors.backgroundFilledPrimary',
+          description: <>Bold primary background for buttons and strong emphasis.</>,
         },
         {
           value: euiTheme.colors.backgroundFilledAccent,
           token: 'colors.backgroundFilledAccent',
+          description: <>Bold accent background for notifications and badges.</>,
         },
         {
           value: euiTheme.colors.backgroundFilledAccentSecondary,
           token: 'colors.backgroundFilledAccentSecondary',
+          description: <>Bold secondary accent background.</>,
         },
         {
           value: euiTheme.colors.backgroundFilledNeutral,
           token: 'colors.backgroundFilledNeutral',
+          description: <>Bold neutral background for tags and neutral badges.</>,
         },
         {
           value: euiTheme.colors.backgroundFilledSuccess,
           token: 'colors.backgroundFilledSuccess',
+          description: <>Bold success background for positive badges and indicators.</>,
         },
         {
           value: euiTheme.colors.backgroundFilledWarning,
           token: 'colors.backgroundFilledWarning',
+          description: <>Bold warning background for caution badges and indicators.</>,
         },
         {
           value: euiTheme.colors.backgroundFilledRisk,
           token: 'colors.backgroundFilledRisk',
+          description: <>Bold risk background for elevated concern badges.</>,
         },
         {
           value: euiTheme.colors.backgroundFilledDanger,
           token: 'colors.backgroundFilledDanger',
+          description: <>Bold danger background for error badges and destructive buttons.</>,
         },
         {
           value: euiTheme.colors.backgroundFilledAssistance,
           token: 'colors.backgroundFilledAssistance',
+          description: <>Bold assistance background for supplementary badges.</>,
         },
         {
           value: euiTheme.colors.backgroundFilledText,
           token: 'colors.backgroundFilledText',
+          description: <>Bold text-toned background for inverted content areas like tooltips.</>,
         },
       ]}
     />
diff --git a/packages/website/docs/getting-started/theming/tokens/colors/border_colors_table.tsx b/packages/website/docs/getting-started/theming/tokens/colors/border_colors_table.tsx
index 1b9ffa411b46..2a73933781da 100644
--- a/packages/website/docs/getting-started/theming/tokens/colors/border_colors_table.tsx
+++ b/packages/website/docs/getting-started/theming/tokens/colors/border_colors_table.tsx
@@ -11,110 +11,147 @@ export const BorderColorsTable = () => {
         {
           value: euiTheme.colors.borderBasePrimary,
           token: 'colors.borderBasePrimary',
+          description: <>Subtle primary border for selected or active containers.</>,
         },
         {
           value: euiTheme.colors.borderBaseAccent,
           token: 'colors.borderBaseAccent',
+          description: <>Subtle accent border for attention-drawing elements.</>,
         },
         {
           value: euiTheme.colors.borderBaseAccentSecondary,
           token: 'colors.borderBaseAccentSecondary',
+          description: <>Subtle secondary accent border.</>,
         },
         {
           value: euiTheme.colors.borderBaseNeutral,
           token: 'colors.borderBaseNeutral',
+          description: <>Subtle neutral border for informational elements.</>,
         },
         {
           value: euiTheme.colors.borderBaseSuccess,
           token: 'colors.borderBaseSuccess',
+          description: <>Subtle success border for positive indicators.</>,
         },
         {
           value: euiTheme.colors.borderBaseWarning,
           token: 'colors.borderBaseWarning',
+          description: <>Subtle warning border for caution indicators.</>,
         },
         {
           value: euiTheme.colors.borderBaseRisk,
           token: 'colors.borderBaseRisk',
+          description: <>Subtle risk border for elevated concern.</>,
         },
         {
           value: euiTheme.colors.borderBaseDanger,
           token: 'colors.borderBaseDanger',
+          description: <>Subtle danger border for error states.</>,
         },
         {
           value: euiTheme.colors.borderBaseAssistance,
           token: 'colors.borderBaseAssistance',
+          description: <>Subtle assistance border for supplementary context.</>,
         },
         {
           value: euiTheme.colors.borderBasePlain,
           token: 'colors.borderBasePlain',
+          description: (
+            <>
+              Standard visible border for forms and containers needing clear
+              delineation.
+            </>
+          ),
         },
         {
           value: euiTheme.colors.borderBaseSubdued,
           token: 'colors.borderBaseSubdued',
+          description: (
+            <>
+              Default border color. Used as <code>border.color</code> for most
+              UI elements.
+            </>
+          ),
         },
         {
           value: euiTheme.colors.borderBaseProminent,
           token: 'colors.borderBaseProminent',
+          description: <>Stronger border for elements needing extra emphasis.</>,
         },
         {
           value: euiTheme.colors.borderBaseDisabled,
           token: 'colors.borderBaseDisabled',
+          description: <>Border for disabled elements and controls.</>,
         },
         {
           value: euiTheme.colors.borderBaseFloating,
           token: 'colors.borderBaseFloating',
+          description: <>Border for floating elements like popovers and tooltips.</>,
         },
         {
           value: euiTheme.colors.borderBaseFormsColorSwatch,
           token: 'colors.borderBaseFormsColorSwatch',
+          description: <>Border for color swatch form elements.</>,
         },
         {
           value: euiTheme.colors.borderInteractiveFormsHoverPlain,
           token: 'colors.borderInteractiveFormsHoverPlain',
+          description: <>Hover border for standard form controls.</>,
         },
         {
           value: euiTheme.colors.borderInteractiveFormsHoverProminent,
           token: 'colors.borderInteractiveFormsHoverProminent',
+          description: <>Hover border for prominent form controls.</>,
         },
         {
           value: euiTheme.colors.borderInteractiveFormsHoverDanger,
           token: 'colors.borderInteractiveFormsHoverDanger',
+          description: <>Hover border for form controls in error state.</>,
         },
         {
           value: euiTheme.colors.borderStrongPrimary,
           token: 'colors.borderStrongPrimary',
+          description: <>Bold primary border for maximum emphasis.</>,
         },
         {
           value: euiTheme.colors.borderStrongAccent,
           token: 'colors.borderStrongAccent',
+          description: <>Bold accent border for maximum emphasis.</>,
         },
         {
           value: euiTheme.colors.borderStrongAccentSecondary,
           token: 'colors.borderStrongAccentSecondary',
+          description: <>Bold secondary accent border.</>,
         },
         {
           value: euiTheme.colors.borderStrongNeutral,
           token: 'colors.borderStrongNeutral',
+          description: <>Bold neutral border for strong informational emphasis.</>,
         },
         {
           value: euiTheme.colors.borderStrongSuccess,
           token: 'colors.borderStrongSuccess',
+          description: <>Bold success border for strong positive emphasis.</>,
         },
         {
           value: euiTheme.colors.borderStrongWarning,
           token: 'colors.borderStrongWarning',
+          description: <>Bold warning border for strong caution emphasis.</>,
         },
         {
           value: euiTheme.colors.borderStrongRisk,
           token: 'colors.borderStrongRisk',
+          description: <>Bold risk border for strong concern emphasis.</>,
         },
         {
           value: euiTheme.colors.borderStrongDanger,
           token: 'colors.borderStrongDanger',
+          description: <>Bold danger border for strong error emphasis.</>,
         },
         {
           value: euiTheme.colors.borderStrongAssistance,
           token: 'colors.borderStrongAssistance',
+          description: <>Bold assistance border for strong supplementary emphasis.</>,
         },
       ]}
     />
diff --git a/packages/website/docs/getting-started/theming/tokens/colors/data_vis_colors_table.tsx b/packages/website/docs/getting-started/theming/tokens/colors/data_vis_colors_table.tsx
index 1adc8f4a68c1..eeb8d1c710cc 100644
--- a/packages/website/docs/getting-started/theming/tokens/colors/data_vis_colors_table.tsx
+++ b/packages/website/docs/getting-started/theming/tokens/colors/data_vis_colors_table.tsx
@@ -10,42 +10,52 @@ export const DataVisColorsTable = () => {
         {
           value: euiTheme.colors.vis.euiColorVis0,
           token: 'colors.vis.euiColorVis0',
+          description: <>Color-blind safe categorical color 1 for data series.</>,
         },
         {
           value: euiTheme.colors.vis.euiColorVis1,
           token: 'colors.vis.euiColorVis1',
+          description: <>Color-blind safe categorical color 2 for data series.</>,
         },
         {
           value: euiTheme.colors.vis.euiColorVis2,
           token: 'colors.vis.euiColorVis2',
+          description: <>Color-blind safe categorical color 3 for data series.</>,
         },
         {
           value: euiTheme.colors.vis.euiColorVis3,
           token: 'colors.vis.euiColorVis3',
+          description: <>Color-blind safe categorical color 4 for data series.</>,
         },
         {
           value: euiTheme.colors.vis.euiColorVis4,
           token: 'colors.vis.euiColorVis4',
+          description: <>Color-blind safe categorical color 5 for data series.</>,
         },
         {
           value: euiTheme.colors.vis.euiColorVis5,
           token: 'colors.vis.euiColorVis5',
+          description: <>Color-blind safe categorical color 6 for data series.</>,
         },
         {
           value: euiTheme.colors.vis.euiColorVis6,
           token: 'colors.vis.euiColorVis6',
+          description: <>Color-blind safe categorical color 7 for data series.</>,
         },
         {
           value: euiTheme.colors.vis.euiColorVis7,
           token: 'colors.vis.euiColorVis7',
+          description: <>Color-blind safe categorical color 8 for data series.</>,
         },
         {
           value: euiTheme.colors.vis.euiColorVis8,
           token: 'colors.vis.euiColorVis8',
+          description: <>Color-blind safe categorical color 9 for data series.</>,
         },
         {
           value: euiTheme.colors.vis.euiColorVis9,
           token: 'colors.vis.euiColorVis9',
+          description: <>Color-blind safe categorical color 10 for data series.</>,
         },
       ]}
     />
@@ -61,42 +71,102 @@ export const DataVisTextColorsTable = () => {
         {
           value: euiTheme.colors.vis.euiColorVisText0,
           token: 'colors.vis.euiColorVisText0',
+          description: (
+            <>
+              Text variant of <EuiCode>euiColorVis0</EuiCode>. Higher contrast
+              in light mode.
+            </>
+          ),
         },
         {
           value: euiTheme.colors.vis.euiColorVisText1,
           token: 'colors.vis.euiColorVisText1',
+          description: (
+            <>
+              Text variant of <EuiCode>euiColorVis1</EuiCode>. Higher contrast
+              in light mode.
+            </>
+          ),
         },
         {
           value: euiTheme.colors.vis.euiColorVisText2,
           token: 'colors.vis.euiColorVisText2',
+          description: (
+            <>
+              Text variant of <EuiCode>euiColorVis2</EuiCode>. Higher contrast
+              in light mode.
+            </>
+          ),
         },
         {
           value: euiTheme.colors.vis.euiColorVisText3,
           token: 'colors.vis.euiColorVisText3',
+          description: (
+            <>
+              Text variant of <EuiCode>euiColorVis3</EuiCode>. Higher contrast
+              in light mode.
+            </>
+          ),
         },
         {
           value: euiTheme.colors.vis.euiColorVisText4,
           token: 'colors.vis.euiColorVisText4',
+          description: (
+            <>
+              Text variant of <EuiCode>euiColorVis4</EuiCode>. Higher contrast
+              in light mode.
+            </>
+          ),
         },
         {
           value: euiTheme.colors.vis.euiColorVisText5,
           token: 'colors.vis.euiColorVisText5',
+          description: (
+            <>
+              Text variant of <EuiCode>euiColorVis5</EuiCode>. Higher contrast
+              in light mode.
+            </>
+          ),
         },
         {
           value: euiTheme.colors.vis.euiColorVisText6,
           token: 'colors.vis.euiColorVisText6',
+          description: (
+            <>
+              Text variant of <EuiCode>euiColorVis6</EuiCode>. Higher contrast
+              in light mode.
+            </>
+          ),
         },
         {
           value: euiTheme.colors.vis.euiColorVisText7,
           token: 'colors.vis.euiColorVisText7',
+          description: (
+            <>
+              Text variant of <EuiCode>euiColorVis7</EuiCode>. Higher contrast
+              in light mode.
+            </>
+          ),
         },
         {
           value: euiTheme.colors.vis.euiColorVisText8,
           token: 'colors.vis.euiColorVisText8',
+          description: (
+            <>
+              Text variant of <EuiCode>euiColorVis8</EuiCode>. Higher contrast
+              in light mode.
+            </>
+          ),
         },
         {
           value: euiTheme.colors.vis.euiColorVisText9,
           token: 'colors.vis.euiColorVisText9',
+          description: (
+            <>
+              Text variant of <EuiCode>euiColorVis9</EuiCode>. Higher contrast
+              in light mode.
+            </>
+          ),
         },
       ]}
     />
diff --git a/packages/website/docs/getting-started/theming/tokens/colors/index.mdx b/packages/website/docs/getting-started/theming/tokens/colors/index.mdx
index b9201405625b..851febb2c57c 100644
--- a/packages/website/docs/getting-started/theming/tokens/colors/index.mdx
+++ b/packages/website/docs/getting-started/theming/tokens/colors/index.mdx
@@ -6,10 +6,13 @@ sidebar_position: 3
 
 import { EuiSpacer, EuiCodeBlock } from '@elastic/eui';
 
-Elastic UI builds with a color palette that is based on predefined 14-step scales for a core set of three colors (blue / teal / pink) as well as a green / yellow / red qualitative set and combined with a 28-step grayscale.
-Colors are defined to work well when combined for their semantic purpose.
+EUI provides a comprehensive set of semantic color tokens through the Borealis theme. Rather than using raw color values, you should use these **semantic tokens** which are purpose-driven and automatically adapt between light and dark color modes.
 
-When switching between light and dark color modes, the theme keys do not change, only their values do.
+All color tokens are accessed via `euiTheme.colors` (from the `useEuiTheme()` hook). When switching between light and dark color modes, the token keys do not change — only their resolved values do.
+
+:::tip Use semantic tokens, not raw values
+Always prefer semantic color tokens over raw hex values or shade tokens. Semantic tokens ensure your UI stays consistent, accessible, and compatible with all color modes (light, dark, and high contrast).
+:::
 
 import ForcedColorsWarning from './_forced_colors_warning.mdx';
 
@@ -17,7 +20,7 @@ import ForcedColorsWarning from './_forced_colors_warning.mdx';
 
 ## Brand colors
 
-Elastic has two main brand colors. The other three are used for statefulness like indicating between successful and dangerous actions.
+Brand colors are the core semantic colors used throughout the UI. **Primary** and **accent** drive most interactive and attention-drawing elements, while **success**, **warning**, and **danger** communicate status. Each brand color also has corresponding text, background, and border variants documented in the sections below.
 
 import { Example } from '@site/src/components';
 import { BrandColorPreview } from './brand_color_preview';
@@ -47,9 +50,12 @@ import { BrandColorsTable } from './brand_colors_table';
 
 ## Text colors
 
-Each brand color also has a corresponding text variant that should be used specifically when coloring text. As is used in [EuiTextColor](../../../../components/display/text.mdx#coloring-text).
+Text color tokens are optimized for readability and contrast. Each brand color has a corresponding text variant that should be used when coloring text (never use the brand color directly for text). These tokens are used by [EuiTextColor](../../../../components/display/text.mdx#coloring-text).
 
-Use `textGhost` for text and icons on dark backgrounds and `textInk` on light backgrounds. 
+- Use `textParagraph` for standard body text and `textHeading` for headings.
+- Use `textSubdued` for secondary or less prominent text.
+- Use `textGhost` for text and icons on dark backgrounds and `textInk` on light backgrounds.
+- Use `textDisabled` for disabled or inactive text elements.
 
 import { TextColorPreview } from './text_color_preview';
 import { TextColorsTable } from './text_colors_table';
@@ -78,9 +84,13 @@ import { TextColorsTable } from './text_colors_table';
 
 ## Background colors
 
-Semantic background colors. These should be used according to their semantic purpose.
+Background color tokens come in three intensity levels:
+
+- **Base** (`backgroundBase*`) — Subtle backgrounds for containers, panels, and interactive states.
+- **Light** (`backgroundLight*`) — Slightly more prominent backgrounds, useful for callouts and highlighted sections.
+- **Filled** (`backgroundFilled*`) — Bold, fully saturated backgrounds typically used for badges, buttons, and strong emphasis.
 
-If a border is needed use the semantically related border color, e.g. `backgroundBasePrimary` with `borderBasePrimary`.
+When pairing backgrounds with borders, use the semantically matching border token (e.g. `backgroundBasePrimary` with `borderBasePrimary`).
 
 import { BackgroundColorPreview } from './background_color_preview';
 import { BackgroundColorsTable } from './background_colors_table';
@@ -107,10 +117,11 @@ import { BackgroundColorsTable } from './background_colors_table';
 
 ## Borders
 
-Semantic border colors. These should be used according to their semantic purpose.
+Border color tokens come in three intensity levels:
 
-The default border color (used as `border.color`) `borderBaseSubdued`.
-Use the `base` border colors for most cases. Use `borderBasePlain` for a slightly stronger border (e.g. for forms).
+- **Base** (`borderBase*`) — Subtle borders for panels, cards, and containers. Use `borderBaseSubdued` as the default border and `borderBasePlain` for a slightly stronger border (e.g. for form controls).
+- **Interactive** (`borderInteractive*`) — Border colors for interactive states like form hover effects.
+- **Strong** (`borderStrong*`) — Bold, high-contrast borders for maximum emphasis.
 
 import { BorderColorPreview } from './border_color_preview';
 import { BorderColorsTable } from './border_colors_table';
@@ -137,18 +148,22 @@ import { BorderColorsTable } from './border_colors_table';
 
 ## Shades
 
-A six-color grayscale palette. Variation beyond these colors is minimal and always done through computations against this set.
+:::warning Deprecated
+Shade tokens are **deprecated** and will be removed in a future release. Use the semantic background, border, and text tokens instead. For example, instead of `emptyShade` use `backgroundBasePlain`, and instead of `lightShade` use `borderBaseSubdued`.
+:::
+
+A grayscale palette previously used for backgrounds, borders, and text. These are now replaced by purpose-specific semantic tokens.
 
 import { ShadeColorPreview } from './shade_color_preview';
 import { ShadeColorsTable } from './shade_colors_table';
 
 <Example>
   <Example.Description>
-    ### `euiTheme.colors[colorShade]` <Badge color="hollow">token</Badge>
+    ### `euiTheme.colors[colorShade]` <Badge color="hollow">deprecated</Badge>
 
-    Since the EUI colors usually evaluate to a hex value, the easiest way to perform color operations like transparency, shading, or tinting is by using the EUI provided methods of `transparentize()`, `shade()`, and `tint()` respectively.
+    These shade tokens are deprecated. Migrate to the semantic background, border, and text tokens for all new code.
 
-    For all available color functions see the [Colors Utilities page](../../utilities/colors.mdx).
+    For color manipulation functions see the [Colors Utilities page](../../utilities/colors.mdx).
   </Example.Description>
   <Example.Preview>
     <ShadeColorPreview />
@@ -168,7 +183,11 @@ import { ShadeColorsTable } from './shade_colors_table';
 
 ## Special colors
 
-These are used a lot for special cases.
+:::warning Mostly deprecated
+Most special color tokens are **deprecated** in favor of semantic alternatives. See individual token descriptions below for migration guidance. Only `highlight` and `shadow` remain as active tokens.
+:::
+
+Special-purpose color tokens for specific UI needs.
 
 import { SpecialColorsPreview } from './special_colors_preview';
 import { SpecialColorsTable } from './special_colors_table';
@@ -177,7 +196,7 @@ import { SpecialColorsTable } from './special_colors_table';
   <Example.Description>
     ### `euiTheme.colors[special]` <Badge color="hollow">token</Badge>
 
-    Constant colors are those that do not change no matter the theme or color mode and typically represent the polar extremes.
+    Special-purpose tokens. Most are deprecated — see descriptions for migration paths.
   </Example.Description>
   <Example.Preview>
     <SpecialColorsPreview />
@@ -198,13 +217,12 @@ import { SpecialColorsTable } from './special_colors_table';
 
 ## Data visualization colors
 
-:::note Guidance
-
-Data visualization colors are semantically tied to data visualizations and are not meant for use in other contexts. Do not use these colors in other contexts.
+:::warning Important
+Data visualization colors are **exclusively for charts and data visualizations**. Do not use them for UI elements like buttons, badges, or backgrounds — use the brand and semantic tokens above instead.
 :::
 
-import { DataVisColorsTable, DataVisBackgroundColor } from './data_vis_colors_table';
-import { DataVisColorsPreview } from './data_vis_colors_preview'
+import { DataVisColorsTable } from './data_vis_colors_table';
+import { DataVisColorsPreview } from './data_vis_colors_preview';
 
 
 <Example>
@@ -269,9 +287,8 @@ import { SeverityColorsPreview } from './severity_colors_preview'
 
 ## Data visualization text colors {#dataVisText}
 
-:::note Guidance
-
-Data visualization text colors are semantically tied to data visualizations colors and are not meant for use in other contexts. 
+:::warning Important
+Data visualization text colors are paired with the data visualization colors above. Use these **only** for text that labels or accompanies data visualizations — not for general UI text.
 :::
 
 import { DataVisTextColorsTable } from './data_vis_colors_table';
@@ -304,16 +321,16 @@ import { DataVisTextColorsPreview } from './data_vis_colors_preview'
 
 ## Contrast ratios and color modes {#contrast}
 
-Our Data visualization colors and Health and Severity colors prioritize visual clarity and aesthetic appeal over strict contrast compliance in light mode. **This means some colors may not meet WCAG contrast requirements against light backgrounds**, as lighter and more saturated tones help differentiate data and create a more visually engaging experience.
+Data visualization colors and severity colors prioritize visual clarity and data differentiation over strict contrast compliance in standard light mode. **This means some colors may not meet WCAG 3:1 contrast requirements against light backgrounds.**
 
-However, in dark mode, all colors meet the minimum 3:1 contrast ratio, ensuring accessibility compliance. 
+For accessible use cases, enable **high contrast mode** which improves contrast for data vis and severity colors in light mode. In dark mode, all colors meet the minimum 3:1 contrast ratio by default.
 
 import { EuiTable, EuiTableHeader, EuiTableHeaderCell, EuiTableRow, EuiTableRowCell } from '@elastic/eui';
 
 <EuiTable>
   <EuiTableHeader>
     <EuiTableHeaderCell>Color Mode</EuiTableHeaderCell>
-    <EuiTableHeaderCell>Meets 3:1 contrast ratios?</EuiTableHeaderCell>
+    <EuiTableHeaderCell>Data vis / severity colors meet 3:1?</EuiTableHeaderCell>
   </EuiTableHeader>
   <EuiTableRow>
     <EuiTableRowCell>Dark</EuiTableRowCell>
@@ -325,7 +342,7 @@ import { EuiTable, EuiTableHeader, EuiTableHeaderCell, EuiTableRow, EuiTableRowC
   </EuiTableRow>
   <EuiTableRow>
     <EuiTableRowCell>Light (high contrast)</EuiTableRowCell>
-    <EuiTableRowCell>Yes</EuiTableRowCell>
+    <EuiTableRowCell>Improved</EuiTableRowCell>
   </EuiTableRow>
   <EuiTableRow>
     <EuiTableRowCell>Dark (high contrast)</EuiTableRowCell>
diff --git a/packages/website/docs/getting-started/theming/tokens/colors/severity_colors_table.tsx b/packages/website/docs/getting-started/theming/tokens/colors/severity_colors_table.tsx
index c6d8ad7532d4..bfa1395febcf 100644
--- a/packages/website/docs/getting-started/theming/tokens/colors/severity_colors_table.tsx
+++ b/packages/website/docs/getting-started/theming/tokens/colors/severity_colors_table.tsx
@@ -10,26 +10,32 @@ export const SeverityColorsTable = () => {
         {
           value: euiTheme.colors.severity.unknown,
           token: 'colors.severity.unknown',
+          description: <>Unknown or indeterminate severity state.</>,
         },
         {
           value: euiTheme.colors.severity.success,
           token: 'colors.severity.success',
+          description: <>Healthy or successful state (e.g. service is running).</>,
         },
         {
           value: euiTheme.colors.severity.neutral,
           token: 'colors.severity.neutral',
+          description: <>Neutral or informational state.</>,
         },
         {
           value: euiTheme.colors.severity.warning,
           token: 'colors.severity.warning',
+          description: <>Warning state that requires attention (e.g. degraded performance).</>,
         },
         {
           value: euiTheme.colors.severity.risk,
           token: 'colors.severity.risk',
+          description: <>Elevated risk state between warning and danger.</>,
         },
         {
           value: euiTheme.colors.severity.danger,
           token: 'colors.severity.danger',
+          description: <>Critical or error state (e.g. service is down).</>,
         },
       ]}
     />
diff --git a/packages/website/docs/getting-started/theming/tokens/colors/shade_colors_table.tsx b/packages/website/docs/getting-started/theming/tokens/colors/shade_colors_table.tsx
index 08e8eac00fca..0f5972c11727 100644
--- a/packages/website/docs/getting-started/theming/tokens/colors/shade_colors_table.tsx
+++ b/packages/website/docs/getting-started/theming/tokens/colors/shade_colors_table.tsx
@@ -12,11 +12,8 @@ export const ShadeColorsTable = () => {
           token: 'colors.emptyShade',
           description: (
             <>
-              Used as the background color of primary{' '}
-              <strong>page content and panels</strong> including modals and
-              flyouts.
-              <br />
-              @deprecated - use specific semantic color tokens instead.
+              @deprecated — Use <code>backgroundBasePlain</code> for panels,
+              modals, and content containers.
             </>
           ),
         },
@@ -25,11 +22,9 @@ export const ShadeColorsTable = () => {
           token: 'colors.lightestShade',
           description: (
             <>
-              Used to lightly shade areas that contain{' '}
-              <strong>secondary content</strong> or contain panel-like
-              components.
-              <br />
-              @deprecated - use specific semantic color tokens instead.
+              @deprecated — Use <code>backgroundBaseSubdued</code> for secondary
+              content areas or <code>backgroundBaseDisabled</code> for disabled
+              states.
             </>
           ),
         },
@@ -38,10 +33,8 @@ export const ShadeColorsTable = () => {
           token: 'colors.lightShade',
           description: (
             <>
-              Used for most <strong>borders</strong> and dividers (horizontal
-              rules).
-              <br />
-              @deprecated - use specific semantic color tokens instead.
+              @deprecated — Use <code>borderBaseSubdued</code> for borders or{' '}
+              <code>borderBasePlain</code> for dividers.
             </>
           ),
         },
@@ -50,28 +43,29 @@ export const ShadeColorsTable = () => {
           token: 'colors.mediumShade',
           description: (
             <>
-              The middle gray for all themes; this is the base for{' '}
-              <code>colors.subdued</code>
-              <br />
-              @deprecated - use specific semantic color tokens instead.
+              @deprecated — Use <code>textSubdued</code> for subdued text or the
+              appropriate semantic token for your use case.
             </>
           ),
         },
         {
           value: euiTheme.colors.darkShade,
           token: 'colors.darkShade',
-          description: <>Slightly subtle graphic color</>,
+          description: (
+            <>
+              @deprecated — Use <code>textParagraph</code> for body text or the
+              appropriate semantic token.
+            </>
+          ),
         },
         {
           value: euiTheme.colors.darkestShade,
           token: 'colors.darkestShade',
           description: (
             <>
-              Used as the <strong>text</strong> color and the background color
-              for <strong>inverted components</strong> like tooltips and the
-              control bar.
-              <br />
-              @deprecated - use specific semantic color tokens instead.
+              @deprecated — Use <code>textHeading</code> for text, or{' '}
+              <code>backgroundFilledText</code> for inverted backgrounds like
+              tooltips.
             </>
           ),
         },
@@ -80,9 +74,8 @@ export const ShadeColorsTable = () => {
           token: 'colors.fullShade',
           description: (
             <>
-              The opposite of <code>emptyShade</code>
-              <br />
-              @deprecated - use specific semantic color tokens instead.
+              @deprecated — Use <code>textInk</code> for maximum contrast text
+              on light backgrounds, or <code>shadow</code> for shadow effects.
             </>
           ),
         },
diff --git a/packages/website/docs/getting-started/theming/tokens/colors/special_colors_table.tsx b/packages/website/docs/getting-started/theming/tokens/colors/special_colors_table.tsx
index 6b0a8a43dfa8..a49604bf5828 100644
--- a/packages/website/docs/getting-started/theming/tokens/colors/special_colors_table.tsx
+++ b/packages/website/docs/getting-started/theming/tokens/colors/special_colors_table.tsx
@@ -13,14 +13,9 @@ export const SpecialColorsTable = () => {
           token: 'colors.body',
           description: (
             <>
-              The background color for the <strong>whole window (body)</strong>{' '}
-              and is a computed value of <strong>colors.lightestShade</strong>.
-              Provides denominator (background) value for{' '}
-              <strong>contrast calculations</strong>
-              <br />
-              @deprecated - use <code>backgroundBasePlain</code> or{' '}
-              <code>backgroundBaseSubdued</code>
-              instead
+              @deprecated — Use <code>backgroundBasePlain</code> for content
+              backgrounds or <code>backgroundBaseSubdued</code> for the page
+              background.
             </>
           ),
         },
@@ -39,11 +34,9 @@ export const SpecialColorsTable = () => {
           token: 'colors.disabled',
           description: (
             <>
-              Computed against <code>colors.darkestShade</code>.
-              <br />
-              @deprecated - use specific semantic tokens instead (e.g.
-              <code>backgroundBaseDisabled</code>,{' '}
-              <code>borderBaseDisabled</code> etc)
+              @deprecated — Use <code>backgroundBaseDisabled</code> for disabled
+              backgrounds or <code>borderBaseDisabled</code> for disabled
+              borders.
             </>
           ),
         },
@@ -52,9 +45,7 @@ export const SpecialColorsTable = () => {
           token: 'colors.disabledText',
           description: (
             <>
-              Computed against <code>colors.disabled</code>
-              <br />
-              @deprecated - use <code>textDisabled</code> instead
+              @deprecated — Use <code>textDisabled</code> instead.
             </>
           ),
         },
@@ -63,8 +54,8 @@ export const SpecialColorsTable = () => {
           token: 'colors.shadow',
           description: (
             <>
-              The base color for shadows that gets <code>transparentized</code>{' '}
-              at a base value on the <code>colorMode</code> and then layered.
+              Base color for box shadows. Automatically adjusted for{' '}
+              <code>colorMode</code>.
             </>
           ),
         },
diff --git a/packages/website/docs/getting-started/theming/tokens/colors/text_colors_table.tsx b/packages/website/docs/getting-started/theming/tokens/colors/text_colors_table.tsx
index 96feeaec74fd..b163d57b85d9 100644
--- a/packages/website/docs/getting-started/theming/tokens/colors/text_colors_table.tsx
+++ b/packages/website/docs/getting-started/theming/tokens/colors/text_colors_table.tsx
@@ -12,62 +12,127 @@ export const TextColorsTable = () => {
         {
           value: euiTheme.colors.textParagraph,
           token: 'colors.textParagraph',
+          description: <>Default color for body text and paragraphs.</>,
         },
         {
           value: euiTheme.colors.textHeading,
           token: 'colors.textHeading',
+          description: <>Slightly bolder color for headings and titles.</>,
         },
         {
           value: euiTheme.colors.textSubdued,
           token: 'colors.textSubdued',
+          description: (
+            <>
+              For secondary or less prominent text such as help text,
+              descriptions, and labels.
+            </>
+          ),
         },
         {
           value: euiTheme.colors.textGhost,
           token: 'colors.textGhost',
+          description: (
+            <>
+              Light-colored text for use on <strong>dark backgrounds</strong>.
+            </>
+          ),
         },
         {
           value: euiTheme.colors.textInk,
           token: 'colors.textInk',
+          description: (
+            <>
+              Dark-colored text for use on <strong>light backgrounds</strong>.
+            </>
+          ),
         },
         {
           value: euiTheme.colors.link,
           token: 'colors.link',
+          description: <>Color for hyperlinks and interactive text elements.</>,
         },
         {
           value: euiTheme.colors.textPrimary,
           token: 'colors.textPrimary',
+          description: (
+            <>
+              Text variant of the <strong>primary</strong> brand color.
+            </>
+          ),
         },
         {
           value: euiTheme.colors.textAccent,
           token: 'colors.textAccent',
+          description: (
+            <>
+              Text variant of the <strong>accent</strong> brand color.
+            </>
+          ),
         },
         {
           value: euiTheme.colors.textAccentSecondary,
           token: 'colors.textAccentSecondary',
+          description: (
+            <>
+              Text variant of the <strong>secondary accent</strong> color.
+            </>
+          ),
         },
         {
           value: euiTheme.colors.textNeutral,
           token: 'colors.textNeutral',
+          description: <>Neutral text color for informational content.</>,
         },
         {
           value: euiTheme.colors.textSuccess,
           token: 'colors.textSuccess',
+          description: (
+            <>
+              Text variant of the <strong>success</strong> color for positive
+              messages.
+            </>
+          ),
         },
         {
           value: euiTheme.colors.textWarning,
           token: 'colors.textWarning',
+          description: (
+            <>
+              Text variant of the <strong>warning</strong> color for caution
+              messages.
+            </>
+          ),
         },
         {
           value: euiTheme.colors.textRisk,
           token: 'colors.textRisk',
+          description: (
+            <>
+              Text variant of the <strong>risk</strong> color for elevated
+              concern.
+            </>
+          ),
         },
         {
           value: euiTheme.colors.textDanger,
           token: 'colors.textDanger',
+          description: (
+            <>
+              Text variant of the <strong>danger</strong> color for errors and
+              destructive actions.
+            </>
+          ),
         },
         {
           value: euiTheme.colors.textAssistance,
           token: 'colors.textAssistance',
+          description: (
+            <>
+              Text variant of the <strong>assistance</strong> color for
+              supplementary context.
+            </>
+          ),
         },
       ]}
     />
diff --git a/packages/website/docs/patterns/severity/index.mdx b/packages/website/docs/patterns/severity/index.mdx
index 69d65eb2e2bd..e3d820e6f6bb 100644
--- a/packages/website/docs/patterns/severity/index.mdx
+++ b/packages/website/docs/patterns/severity/index.mdx
@@ -130,8 +130,6 @@ import { SeverityColorAssociationTable } from './color_association_table.tsx';
 ### Tokens
 
 import { SeverityColorsTable } from '../../getting-started/theming/tokens/colors/severity_colors_table.tsx';
-import { DataVisBackgroundColor } from '../../getting-started/theming/tokens/colors/data_vis_colors_table.tsx';
-import { DataVisColorsPreview } from '../../getting-started/theming/tokens/colors/data_vis_colors_preview.tsx'
 
 <SeverityColorsTable />
 
diff --git a/packages/website/docs/utilities/color-palettes/index.mdx b/packages/website/docs/utilities/color-palettes/index.mdx
index f3947ea43929..c208e63e1cd2 100644
--- a/packages/website/docs/utilities/color-palettes/index.mdx
+++ b/packages/website/docs/utilities/color-palettes/index.mdx
@@ -3,15 +3,21 @@
 import { ColorPaletteCopyCode, ColorPaletteFlexItem } from './color_palettes_components';
 import colorPaletteComponentsSource from '!raw-loader!./color_palettes_components';
 
-EUI provides a base set of color palettes that return an array of hexadecimal color for use in other EUI components or charts.
+EUI provides a set of color palette utility functions that return arrays of hexadecimal colors for use in charts and data visualizations.
+
+:::tip When to use palettes vs. color tokens
+**Color tokens** (`euiTheme.colors.vis.*`) should be your first choice for data visualizations — they are semantic, theme-aware, and automatically adapt to color modes.
+
+**Color palette functions** are useful when you need a dynamic number of colors (e.g. generating a gradient with N steps), or when working with charting libraries that require arrays of colors. For categorical data with up to 10 series, prefer using the `euiColorVis0`–`euiColorVis9` tokens directly.
+:::
 
 ## Preset qualitative palettes
 
-Qualitative palettes are best suited for communicating and comparing discrete data series. EUI recommends using the `euiPaletteColorBlind()` for qualitative and categorical data.
+Qualitative palettes are best suited for communicating and comparing discrete data series. Use `euiPaletteColorBlind()` for categorical data that needs more than 10 colors or dynamic palette generation.
 
-This palette is restricted to only 10 colors. However, you can add more groups of 10 which are alternates of the original. This is better than allowing the initial set to loop.
+This palette is restricted to 10 base colors. You can add more groups of 10 by increasing `rotations`, which generates alternates of the original set (preferable to letting the initial set loop).
 
-These colors are meant to be used as graphics and contrasted against the value of `euiColorEmptyShade` for the current theme. When placing text on top of these colors, use the `euiPaletteColorBlindBehindText()` variant. It is a brightened version of the base palette to create better contrast with text.
+These colors are designed to contrast against the current theme's background (`backgroundBasePlain`). When placing text on top of these colors, use the `euiPaletteColorBlindBehindText()` variant which provides better contrast for text readability.
 
 <Demo scope={{ ColorPaletteCopyCode, ColorPaletteFlexItem }} extraFiles={{ 'color_palettes_components.tsx': colorPaletteComponentsSource }}>
   ```tsx
@@ -152,13 +158,17 @@ These colors are meant to be used as graphics and contrasted against the value o
 
 ## Recommended quantitative palettes
 
-Quantitative palettes are best suited for displaying data on a continuum, as in the case of health statuses and large geographic or demographic-based data sets.
+Quantitative palettes are best suited for displaying data on a continuum, such as health statuses, geographic data, or demographic data sets.
 
-EUI provides the following common palettes for quantitative data and [charts](../../dataviz/index.mdx). Just pass in the number of steps needed and the function will interpolate between the colors.
-For usages in React we recommend using the respective <a href="https://github.com/elastic/eui/blob/main/packages/eui/src/services/color/eui_palettes_hooks.ts" target="_blank" rel="noopener noreferrer">palette hooks</a>, e.g. `useEuiPaletteColorBlind`.
+EUI provides the following palette functions for quantitative data and [charts](../../dataviz/index.mdx). Pass in the number of steps needed and the function will interpolate between the colors.
+For React usage, we recommend the corresponding <a href="https://github.com/elastic/eui/blob/main/packages/eui/src/services/color/eui_palettes_hooks.ts" target="_blank" rel="noopener noreferrer">palette hooks</a>, e.g. `useEuiPaletteColorBlind`.
+
+:::tip Palette usage guidance
+Whenever possible, prefer the data visualization color tokens (`euiTheme.colors.vis.*`) and the palette hooks (e.g. `useEuiPaletteColorBlind`) over manually calling these palette functions.
+:::
 
 :::warning
-The palette for status is the only palette that has proper contrast ratios. When using the other palettes, consider adding another form of the data for screen readers.
+The `euiPaletteForStatus` palette is the only palette that has proper contrast ratios. When using the other palettes, consider adding another form of the data for screen readers.
 :::
 
 <Demo scope={{ ColorPaletteCopyCode, ColorPaletteFlexItem }} extraFiles={{ 'color_palettes_components.tsx': colorPaletteComponentsSource }}>