diff --git a/.storybook/preview.tsx b/.storybook/preview.tsx
index 3ddb829..20fb89b 100644
--- a/.storybook/preview.tsx
+++ b/.storybook/preview.tsx
@@ -6,7 +6,7 @@ import "./storybook.css"; /* Storybook CSS override */
 import { ThemeProvider } from "../src";
 import { GenericTheme, DiamondTheme, DiamondDSTheme } from "../src";
 import { ThemeSwapper, TextLight, TextDark, TextSystem } from "./ThemeSwapper";
-import "../src/styles/diamondDS/diamond-ds-roles.css";
+import "../src/styles/diamondDS/diamond-ds-tokens.css";
 
 const TextThemeBase = "Theme: Generic";
 const TextThemeDiamond = "Theme: Diamond";
diff --git a/src/storybook/PracticalGuidance.mdx b/src/storybook/PracticalGuidance.mdx
index 6bc79b7..42a5619 100644
--- a/src/storybook/PracticalGuidance.mdx
+++ b/src/storybook/PracticalGuidance.mdx
@@ -27,14 +27,17 @@ Diamond Design System uses MUI with Diamond semantic tokens layered on top.
 
 ## Using the theme
 
-Diamond Design System uses semantic design tokens mapped into MUI’s theme
-system.
+Diamond Design System uses semantic design tokens mapped into MUI’s theme system.
 
-CSS variables remain the source of truth. The MUI theme adapts those values into
-component APIs, palette roles, typography, spacing, elevation, and interaction
-states.
+Design tokens are defined as CSS variables and remain the source of truth. <br />
+The MUI theme maps those tokens into semantic roles exposed through the palette, typography, spacing, elevation, and interaction state APIs.
 
-<strong>Prefer theme roles and semantic tokens over hardcoded values.</strong>
+Components should consume semantic theme roles rather than hardcoded values. Theme customisation and component overrides should reference design tokens to maintain consistency across the system.
+
+<strong>
+  Use theme roles in components and design tokens when defining or customising
+  the theme.
+</strong>
 
 <table className="ds-table">
   <thead>
diff --git a/src/styles/diamondDS/diamond-ds-roles.css b/src/styles/diamondDS/diamond-ds-tokens.css
similarity index 100%
rename from src/styles/diamondDS/diamond-ds-roles.css
rename to src/styles/diamondDS/diamond-ds-tokens.css
diff --git a/src/themes/DiamondDSTheme.ts b/src/themes/DiamondDSTheme.ts
index 7e633b5..5a7d2ea 100644
--- a/src/themes/DiamondDSTheme.ts
+++ b/src/themes/DiamondDSTheme.ts
@@ -1,16 +1,21 @@
 /**
  * DiamondDS MUI theme
  *
- * Maps DiamondDS semantic design tokens and interaction rules into MUI's
- * theme system, component model and runtime styling APIs.
+ * Maps DiamondDS semantic design tokens, palette roles and interaction rules
+ * into MUI's theme system, component model and runtime styling APIs.
+ *
+ * CSS variables are the source of truth.
+ * These are defined in diamond-ds-tokens.css.
+ *
+ * Tokens are the CSS variables.
+ * Roles are the semantic values exposed through the MUI palette and component APIs.
  *
- * CSS variables remain the source of truth.
  * The MUI theme acts as the semantic adapter consumed by components.
  *
  * Components should consume semantic roles from the theme or semantic CSS
  * variables rather than raw colour values.
  */
-import "../styles/diamondDS/diamond-ds-roles.css";
+import "../styles/diamondDS/diamond-ds-tokens.css";
 
 // Enables `theme.vars` typings for MUI CSS variable themes.
 import type {} from "@mui/material/themeCssVarsAugmentation";