- theme.palette.primary.main
+ theme.vars.palette.primary.main
|
#005bbb
@@ -80,6 +80,39 @@ Using semantic roles keeps interfaces consistent across products, supports light
and dark themes, and allows the system to evolve without rewriting component
styles.
+### Read intent colours from `theme.vars`
+
+The light, main, dark and contrast text slots of the intent colours (primary, secondary, error, warning, success, info) are fixed hex values on `theme.palette`. Read in code, they give the light theme's colour in both modes and do not change when the mode does. `theme.vars.palette` returns a CSS variable instead, so the colour follows the mode. It is there whenever the theme uses CSS variables, as the Diamond theme does.
+
+
+
+
+ | ✅ Prefer |
+ ❌ Avoid |
+
+
+
+
+
+ theme.vars.palette.primary.main
+ |
+
+ theme.palette.primary.main
+ |
+
+
+
+ rgb(var(--ds-primary-channel) / 0.12)
+ |
+
+ alpha(theme.palette.primary.main, 0.12)
+ |
+
+
+
+
+Roles that are already CSS variables, such as text, background, border, surface and the container and solid roles, are safe to read from either. `alpha()`, `lighten()` and `darken()` throw on a `var()` colour, so use the channel tokens for transparency. The tokens for the error intent are named `danger`, so its channel token is `--ds-danger-channel`.
+
## Using components
Build with existing components and patterns before creating new ones.
@@ -217,7 +250,7 @@ Brand colour is intentionally separate. Brand communicates Diamond identity rath
- Use neutral roles for structure.
- Use intent roles for meaning.
- - Use
theme.palette or MUI component props so colours work across light and dark themes.
+ - Use theme roles or MUI component props so colours work across light and dark themes.
- Ensure disabled and error states override hover, focus and selected styling.
@@ -253,7 +286,7 @@ Each role includes related tokens for emphasis, contrast, containers, and intera
--ds-[token]
|
- palette.[role].main
+ theme.vars.palette.[role].main
|
Main semantic colour |
Actions, status communication, emphasis, identity |
@@ -263,7 +296,7 @@ Each role includes related tokens for emphasis, contrast, containers, and intera
--ds-on-[token]
- palette.[role].contrastText
+ theme.vars.palette.[role].contrastText
|
Foreground colour paired with the role |
Text and icons shown on the role colour |
@@ -273,7 +306,7 @@ Each role includes related tokens for emphasis, contrast, containers, and intera
--ds-[token]-emphasis
- palette.[role].dark
+ theme.vars.palette.[role].dark
|
Stronger variation of the role |
Hover, active, or stronger emphasis states |
@@ -283,7 +316,7 @@ Each role includes related tokens for emphasis, contrast, containers, and intera
--ds-[token]-accent
- palette.[role].light
+ theme.vars.palette.[role].light
|
Lighter accent variation |
Focus rings, highlights, supporting accents |
@@ -293,7 +326,7 @@ Each role includes related tokens for emphasis, contrast, containers, and intera
--ds-[token]-container
- palette.[role].container
+ theme.vars.palette.[role].container
|
Lower-emphasis role surface |
Chips, alerts, selected regions, grouped states |
@@ -303,7 +336,7 @@ Each role includes related tokens for emphasis, contrast, containers, and intera
--ds-on-[token]-container
- palette.[role].onContainer
+ theme.vars.palette.[role].onContainer
|
Foreground colour paired with role containers |
Text and icons inside semantic containers |
@@ -313,7 +346,7 @@ Each role includes related tokens for emphasis, contrast, containers, and intera
--ds-[token]-solid
- palette.[role].solid
+ theme.vars.palette.[role].solid
|
High-emphasis interactive surface |
Contained buttons and strong interactive controls |
@@ -323,7 +356,7 @@ Each role includes related tokens for emphasis, contrast, containers, and intera
--ds-on-[token]-solid
- palette.[role].onSolid
+ theme.vars.palette.[role].onSolid
|
Foreground colour paired with solid surfaces |
Text and icons inside solid controls |
diff --git a/src/storybook/foundation/1. colour.mdx b/src/storybook/foundation/1. colour.mdx
index 62400b63..c333fe9b 100644
--- a/src/storybook/foundation/1. colour.mdx
+++ b/src/storybook/foundation/1. colour.mdx
@@ -783,7 +783,7 @@ Intent and brand colours follow a shared semantic structure.
--ds-[token]
- palette.[role].main
+ theme.vars.palette.[role].main
|
Main semantic colour |
Actions, status communication, emphasis, identity |
@@ -793,7 +793,7 @@ Intent and brand colours follow a shared semantic structure.
--ds-on-[token]
- palette.[role].contrastText
+ theme.vars.palette.[role].contrastText
|
Foreground colour paired with the role |
Text and icons shown on the role colour |
@@ -803,7 +803,7 @@ Intent and brand colours follow a shared semantic structure.
--ds-[token]-emphasis
- palette.[role].dark
+ theme.vars.palette.[role].dark
|
Stronger variation of the role |
Hover, active, or stronger emphasis states |
@@ -813,7 +813,7 @@ Intent and brand colours follow a shared semantic structure.
--ds-[token]-accent
- palette.[role].light
+ theme.vars.palette.[role].light
|
Lighter accent variation |
Focus rings, highlights, supporting accents |
@@ -823,7 +823,7 @@ Intent and brand colours follow a shared semantic structure.
--ds-[token]-container
- palette.[role].container
+ theme.vars.palette.[role].container
|
Lower-emphasis role surface |
Chips, alerts, selected regions, grouped states |
@@ -833,7 +833,7 @@ Intent and brand colours follow a shared semantic structure.
--ds-on-[token]-container
- palette.[role].onContainer
+ theme.vars.palette.[role].onContainer
|
Foreground colour paired with role containers |
Text and icons inside semantic containers |
@@ -843,7 +843,7 @@ Intent and brand colours follow a shared semantic structure.
--ds-[token]-solid
- palette.[role].solid
+ theme.vars.palette.[role].solid
|
High-emphasis interactive surface |
Contained buttons and strong interactive controls |
@@ -853,7 +853,7 @@ Intent and brand colours follow a shared semantic structure.
--ds-on-[token]-solid
- palette.[role].onSolid
+ theme.vars.palette.[role].onSolid
|
Foreground colour paired with solid surfaces |
Text and icons inside solid controls |
diff --git a/src/storybook/foundation/1.1. theme-colours.mdx b/src/storybook/foundation/1.1. theme-colours.mdx
index 58facf6f..f4b93991 100644
--- a/src/storybook/foundation/1.1. theme-colours.mdx
+++ b/src/storybook/foundation/1.1. theme-colours.mdx
@@ -22,7 +22,7 @@ This page is a token reference. If you're deciding which colour role to use, rea
Intent colours
- Exposed as MUI palette roles (e.g. theme.palette.primary.main
+ Exposed as MUI palette roles (e.g. theme.vars.palette.primary.main
).
@@ -246,7 +246,7 @@ This page is a token reference. If you're deciding which colour role to use, rea
Intent colours
- Exposed as MUI palette roles (e.g. theme.palette.primary.main
+ Exposed as MUI palette roles (e.g. theme.vars.palette.primary.main
).