From dc6e7f4533e5413cbd44eb5799e017a0365d0f68 Mon Sep 17 00:00:00 2001
From: Zohar Manor-Abel <zohar.manor-abel@diamond.ac.uk>
Date: Wed, 3 Jun 2026 14:35:42 +0100
Subject: [PATCH] Renamed CSS file to Tokens rather than Roles

Added explanation in theme file and and updated practical guidance intro
---
 .storybook/preview.tsx                            |  2 +-
 src/storybook/PracticalGuidance.mdx               | 15 +++++++++------
 ...diamond-ds-roles.css => diamond-ds-tokens.css} |  0
 src/themes/DiamondDSTheme.ts                      | 13 +++++++++----
 4 files changed, 19 insertions(+), 11 deletions(-)
 rename src/styles/diamondDS/{diamond-ds-roles.css => diamond-ds-tokens.css} (100%)

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";