Design Tokens
Design Tokens are a strategy employed in managing design systems. They abstract reusable elements such as colors, fonts, and spacing into independent variables. These variables are then consistently used across the design system.
mdui employs global CSS custom properties to implement Design Tokens, ensuring style consistency across all components. By modifying these properties, you can globally adjust the styles of all mdui components. For your own styles, prioritize using these CSS custom properties to maintain consistency with mdui component styles. This also ensures your styles update synchronously when modifying dynamic color schemes.
Color
mdui provides CSS custom properties for both light and dark modes. In light mode, the property is named --mdui-color-{name}-light
, and in dark mode, it's --mdui-color-{name}-dark
.
Additionally, mdui provides CSS custom properties named --mdui-color-{name}
. This property references --mdui-color-{name}-light
in light mode and --mdui-color-{name}-dark
in dark mode, enabling automatic color switching based on the current mode.
To modify specific colors, adjust both --mdui-color-{name}-light
and --mdui-color-{name}-dark
. When reading CSS custom properties, use the --mdui-color-{name}
property.
The values of CSS custom properties are three RGB colors separated by ,
. Here's an example of how to use color CSS custom properties:
/* Modify the color value of primary */
:root {
--mdui-color-primary-light: 103, 80, 164;
--mdui-color-primary-dark: 208, 188, 255;
}
/* Set the background color of the foo element to primary */
.foo {
background-color: rgb(var(--mdui-color-primary));
}
/* Set the background color of the bar element to primary with 0.8 opacity */
.bar {
background-color: rgba(var(--mdui-color-primary), 0.8);
}
For creating a completely new color scheme, consider using the setColorScheme
function. This function generates a complete color scheme based on the provided color.
Color Name | CSS Custom Property | Default | Example |
---|---|---|---|
Primary | --mdui-color-primary-light |
103, 80, 164 |
|
--mdui-color-primary-dark |
208, 188, 255 |
||
--mdui-color-primary |
|||
Primary container | --mdui-color-primary-container-light |
234, 221, 255 |
|
--mdui-color-primary-container-dark |
79, 55, 139 |
||
--mdui-color-primary-container |
|||
On primary | --mdui-color-on-primary-light |
255, 255, 255 |
|
--mdui-color-on-primary-dark |
55, 30, 115 |
||
--mdui-color-on-primary |
|||
On primary container | --mdui-color-on-primary-container-light |
33, 0, 94 |
|
--mdui-color-on-primary-container-dark |
234, 221, 255 |
||
--mdui-color-on-primary-container |
|||
Inverse primary | --mdui-color-inverse-primary-light |
208, 188, 255 |
|
--mdui-color-inverse-primary-dark |
103, 80, 164 |
||
--mdui-color-inverse-primary |
|||
Secondary | --mdui-color-secondary-light |
98, 91, 113 |
|
--mdui-color-secondary-dark |
204, 194, 220 |
||
--mdui-color-secondary |
|||
Secondary container | --mdui-color-secondary-container-light |
232, 222, 248 |
|
--mdui-color-secondary-container-dark |
74, 68, 88 |
||
--mdui-color-secondary-container |
|||
On secondary | --mdui-color-on-secondary-light |
255, 255, 255 |
|
--mdui-color-on-secondary-dark |
51, 45, 65 |
||
--mdui-color-on-secondary |
|||
On secondary container | --mdui-color-on-secondary-container-light |
30, 25, 43 |
|
--mdui-color-on-secondary-container-dark |
232, 222, 248 |
||
--mdui-color-on-secondary-container |
|||
Tertiary | --mdui-color-tertiary-light |
125, 82, 96 |
|
--mdui-color-tertiary-dark |
239, 184, 200 |
||
--mdui-color-tertiary |
|||
Tertiary container | --mdui-color-tertiary-container-light |
255, 216, 228 |
|
--mdui-color-tertiary-container-dark |
99, 59, 72 |
||
--mdui-color-tertiary-container |
|||
On tertiary | --mdui-color-on-tertiary-light |
255, 255, 255 |
|
--mdui-color-on-tertiary-dark |
73, 37, 50 |
||
--mdui-color-on-tertiary |
|||
On tertiary container | --mdui-color-on-tertiary-container-light |
55, 11, 30 |
|
--mdui-color-on-tertiary-container-dark |
255, 216, 228 |
||
--mdui-color-on-tertiary-container |
|||
Surface | --mdui-color-surface-light |
254, 247, 255 |
|
--mdui-color-surface-dark |
20, 18, 24 |
||
--mdui-color-surface |
|||
Surface dim | --mdui-color-surface-dim-light |
222, 216, 225 |
|
--mdui-color-surface-dim-dark |
20, 18, 24 |
||
--mdui-color-surface-dim |
|||
Surface bright | --mdui-color-surface-bright-light |
254, 247, 255 |
|
--mdui-color-surface-bright-dark |
59, 56, 62 |
||
--mdui-color-surface-bright |
|||
Surface container lowest | --mdui-color-surface-container-lowest-light |
255, 255, 255 |
|
--mdui-color-surface-container-lowest-dark |
15, 13, 19 |
||
--mdui-color-surface-container-lowest |
|||
Surface container low | --mdui-color-surface-container-low-light |
247, 242, 250 |
|
--mdui-color-surface-container-low-dark |
29, 27, 32 |
||
--mdui-color-surface-container-low |
|||
Surface container | --mdui-color-surface-container-light |
243, 237, 247 |
|
--mdui-color-surface-container-dark |
33, 31, 38 |
||
--mdui-color-surface-container |
|||
Surface container high | --mdui-color-surface-container-high-light |
236, 230, 240 |
|
--mdui-color-surface-container-high-dark |
43, 41, 48 |
||
--mdui-color-surface-container-high |
|||
Surface container highest | --mdui-color-surface-container-highest-light |
230, 224, 233 |
|
--mdui-color-surface-container-highest-dark |
54, 52, 59 |
||
--mdui-color-surface-container-highest |
|||
Surface variant | --mdui-color-surface-variant-light |
231, 224, 236 |
|
--mdui-color-surface-variant-dark |
73, 69, 79 |
||
--mdui-color-surface-variant |
|||
On surface | --mdui-color-on-surface-light |
28, 27, 31 |
|
--mdui-color-on-surface-dark |
230, 225, 229 |
||
--mdui-color-on-surface |
|||
On surface variant | --mdui-color-on-surface-variant-light |
73, 69, 78 |
|
--mdui-color-on-surface-variant-dark |
202, 196, 208 |
||
--mdui-color-on-surface-variant |
|||
Inverse surface | --mdui-color-inverse-surface-light |
49, 48, 51 |
|
--mdui-color-inverse-surface-dark |
230, 225, 229 |
||
--mdui-color-inverse-surface |
|||
Inverse on surface | --mdui-color-inverse-on-surface-light |
244, 239, 244 |
|
--mdui-color-inverse-on-surface-dark |
49, 48, 51 |
||
--mdui-color-inverse-on-surface |
|||
Background | --mdui-color-background-light |
254, 247, 255 |
|
--mdui-color-background-dark |
20, 18, 24 |
||
--mdui-color-background |
|||
On background | --mdui-color-on-background-light |
28, 27, 31 |
|
--mdui-color-on-background-dark |
230, 225, 229 |
||
--mdui-color-on-background |
|||
Error | --mdui-color-error-light |
179, 38, 30 |
|
--mdui-color-error-dark |
242, 184, 181 |
||
--mdui-color-error |
|||
Error container | --mdui-color-error-container-light |
249, 222, 220 |
|
--mdui-color-error-container-dark |
140, 29, 24 |
||
--mdui-color-error-container |
|||
On error | --mdui-color-on-error-light |
255, 255, 255 |
|
--mdui-color-on-error-dark |
96, 20, 16 |
||
--mdui-color-on-error |
|||
On error container | --mdui-color-on-error-container-light |
65, 14, 11 |
|
--mdui-color-on-error-container-dark |
249, 222, 220 |
||
--mdui-color-on-error-container |
|||
Outline | --mdui-color-outline-light |
121, 116, 126 |
|
--mdui-color-outline-dark |
147, 143, 153 |
||
--mdui-color-outline |
|||
Outline variant | --mdui-color-outline-variant-light |
196, 199, 197 |
|
--mdui-color-outline-variant-dark |
68, 71, 70 |
||
--mdui-color-outline-variant |
|||
Shadow | --mdui-color-shadow-light |
0, 0, 0 |
|
--mdui-color-shadow-dark |
0, 0, 0 |
||
--mdui-color-shadow |
|||
Surface tint | --mdui-color-surface-tint-color-light |
103, 80, 164 |
|
--mdui-color-surface-tint-color-dark |
208, 188, 255 |
||
--mdui-color-surface-tint-color |
|||
Scrim | --mdui-color-scrim-light |
0, 0, 0 |
|
--mdui-color-scrim-dark |
0, 0, 0 |
||
--mdui-color-scrim |
Corner Radius
mdui provides 7 corner radius sizes. These CSS custom properties allow you to adjust the corner radius:
/* Modify the corner radius size of extra-smal */
:root {
--mdui-shape-corner-extra-small: 0.3rem;
}
/* Set the corner radius of the foo element to extra-small */
.foo {
border-radius: var(--mdui-shape-corner-extra-small);
}
CSS Custom Property | Default | Example |
---|---|---|
--mdui-shape-corner-none |
0 |
|
--mdui-shape-corner-extra-small |
0.25rem |
|
--mdui-shape-corner-small |
0.5rem |
|
--mdui-shape-corner-medium |
0.75rem |
|
--mdui-shape-corner-large |
1rem |
|
--mdui-shape-corner-extra-large |
1.75rem |
|
--mdui-shape-corner-full |
1000rem |
Typography
mdui provides 15 typography styles. Each style includes properties for line height, font size, letter spacing, and font weight.
Here's an example of how to use these properties:
/* Modify the text style of Body large */
:root {
--mdui-typescale-body-large-line-height: 1.6rem;
--mdui-typescale-body-large-size: 1.2rem;
--mdui-typescale-body-large-tracking: 0.01rem;
--mdui-typescale-body-large-weight: 400;
}
/* Set the text style of the foo element to Body large */
.foo {
line-height: var(--mdui-typescale-body-large-line-height);
font-size: var(--mdui-typescale-body-large-size);
letter-spacing: var(--mdui-typescale-body-large-tracking);
font-weight: var(--mdui-typescale-body-large-weight);
}
CSS Custom Property | Default | Example |
---|---|---|
--mdui-typescale-display-large-line-height |
4rem |
Display large |
--mdui-typescale-display-large-size |
3.5625rem |
|
--mdui-typescale-display-large-tracking |
0 |
|
--mdui-typescale-display-large-weight |
400 |
|
--mdui-typescale-display-medium-line-height |
3.25rem |
Display medium |
--mdui-typescale-display-medium-size |
2.8125rem |
|
--mdui-typescale-display-medium-tracking |
0 |
|
--mdui-typescale-display-medium-weight |
400 |
|
--mdui-typescale-display-small-line-height |
2.75rem |
Display small |
--mdui-typescale-display-small-size |
2.25rem |
|
--mdui-typescale-display-small-tracking |
0 |
|
--mdui-typescale-display-small-weight |
400 |
|
--mdui-typescale-headline-large-line-height |
2.5rem |
Headline large |
--mdui-typescale-headline-large-size |
2rem |
|
--mdui-typescale-headline-large-tracking |
0 |
|
--mdui-typescale-headline-large-weight |
400 |
|
--mdui-typescale-headline-medium-line-height |
2.25rem |
Headline medium |
--mdui-typescale-headline-medium-size |
1.75rem |
|
--mdui-typescale-headline-medium-tracking |
0 |
|
--mdui-typescale-headline-medium-weight |
400 |
|
--mdui-typescale-headline-small-line-height |
2rem |
Headline small |
--mdui-typescale-headline-small-size |
1.5rem |
|
--mdui-typescale-headline-small-tracking |
0 |
|
--mdui-typescale-headline-small-weight |
400 |
|
--mdui-typescale-title-large-line-height |
1.75rem |
Title large |
--mdui-typescale-title-large-size |
1.375rem |
|
--mdui-typescale-title-large-tracking |
0 |
|
--mdui-typescale-title-large-weight |
400 |
|
--mdui-typescale-title-medium-line-height |
1.5rem |
Title medium |
--mdui-typescale-title-medium-size |
1rem |
|
--mdui-typescale-title-medium-tracking |
0.009375rem |
|
--mdui-typescale-title-medium-weight |
500 |
|
--mdui-typescale-title-small-line-height |
1.25rem |
Title small |
--mdui-typescale-title-small-size |
0.875rem |
|
--mdui-typescale-title-small-tracking |
0.00625rem |
|
--mdui-typescale-title-small-weight |
500 |
|
--mdui-typescale-label-large-line-height |
1.25rem |
Label large |
--mdui-typescale-label-large-size |
0.875rem |
|
--mdui-typescale-label-large-tracking |
0.00625rem |
|
--mdui-typescale-label-large-weight |
500 |
|
--mdui-typescale-label-medium-line-height |
1rem |
Label medium |
--mdui-typescale-label-medium-size |
0.75rem |
|
--mdui-typescale-label-medium-tracking |
0.03125rem |
|
--mdui-typescale-label-medium-weight |
500 |
|
--mdui-typescale-label-small-line-height |
0.375rem |
Label small |
--mdui-typescale-label-small-size |
0.6875rem |
|
--mdui-typescale-label-small-tracking |
0.03125rem |
|
--mdui-typescale-label-small-weight |
500 |
|
--mdui-typescale-body-large-line-height |
1.5rem |
Body large |
--mdui-typescale-body-large-size |
1rem |
|
--mdui-typescale-body-large-tracking |
0.009375rem |
|
--mdui-typescale-body-large-weight |
400 |
|
--mdui-typescale-body-medium-line-height |
1.25rem |
Body medium |
--mdui-typescale-body-medium-size |
0.875rem |
|
--mdui-typescale-body-medium-tracking |
0.015625rem |
|
--mdui-typescale-body-medium-weight |
400 |
|
--mdui-typescale-body-small-line-height |
1rem |
Body small |
--mdui-typescale-body-small-size |
0.75rem |
|
--mdui-typescale-body-small-tracking |
0.025rem |
|
--mdui-typescale-body-small-weight |
400 |
State Layer Opacity
mdui components, such as <mdui-button>
, utilize a semi-transparent overlay layer during interaction states like hover, focus, press, and drag. The opacity of this layer can be adjusted by modifying the following CSS custom properties:
/* Modify the opacity of the state layer */
:root {
--mdui-state-layer-hover: 0.08;
--mdui-state-layer-focus: 0.12;
--mdui-state-layer-pressed: 0.12;
--mdui-state-layer-dragged: 0.16;
}
CSS Custom Property | Default | Example |
---|---|---|
--mdui-state-layer-hover |
0.08 |
|
--mdui-state-layer-focus |
0.12 |
|
--mdui-state-layer-pressed |
0.12 |
|
--mdui-state-layer-dragged |
0.16 |
Elevation
mdui components use elevation to create depth with shadows. You can adjust these shadows by modifying the CSS custom properties:
/* Modify the elevation of level1 */
:root {
--mdui-elevation-level1: 0 0.5px 1.5px 0 rgba(var(--mdui-color-shadow), 19%), 0 0 1px 0 rgba(var(--mdui-color-shadow), 3.9%);
}
/* Set the elevation of the foo element to level1 */
.foo {
box-shadow: var(--mdui-elevation-level1);
}
CSS Custom Property | Default | Example |
---|---|---|
--mdui-elevation-level0 |
none |
|
--mdui-elevation-level1 |
0 0.5px 1.5px 0 rgba(var(--mdui-color-shadow), 19%), 0 0 1px 0 rgba(var(--mdui-color-shadow), 3.9%) |
|
--mdui-elevation-level2 |
0 0.85px 3px 0 rgba(var(--mdui-color-shadow), 19%), 0 0.25px 1px 0 rgba(var(--mdui-color-shadow), 3.9%) |
|
--mdui-elevation-level3 |
0 1.25px 5px 0 rgba(var(--mdui-color-shadow), 19%), 0 0.3333px 1.5px 0 rgba(var(--mdui-color-shadow), 3.9%) |
|
--mdui-elevation-level4 |
0 1.85px 6.25px 0 rgba(var(--mdui-color-shadow), 19%), 0 0.5px 1.75px 0 rgba(var(--mdui-color-shadow), 3.9%) |
|
--mdui-elevation-level5 |
0 2.75px 9px 0 rgba(var(--mdui-color-shadow), 19%), 0 0.25px 3px 0 rgba(var(--mdui-color-shadow), 3.9%) |
Animation
mdui components incorporate animations, with customizable easing curves and durations. These properties can be adjusted using CSS custom properties:
/* Modify the standard easing curve and short1 duration */
:root {
--mdui-motion-easing-standard: cubic-bezier(0.2, 0, 0, 1);
--mdui-motion-duration-short1: 40ms;
}
/* Apply the standard easing curve and short1 duration to the transition effect of the foo element */
.foo {
transition: all var(--mdui-motion-duration-short1) var(--mdui-motion-easing-standard);
}
Type | CSS Custom Property | Default |
---|---|---|
Easing Curve | --mdui-motion-easing-linear |
cubic-bezier(0, 0, 1, 1) |
--mdui-motion-easing-standard |
cubic-bezier(0.2, 0, 0, 1) |
|
--mdui-motion-easing-standard-accelerate |
cubic-bezier(0.3, 0, 1, 1) |
|
--mdui-motion-easing-standard-decelerate |
cubic-bezier(0, 0, 0, 1) |
|
--mdui-motion-easing-emphasized |
var(--mdui-motion-easing-standard) |
|
--mdui-motion-easing-emphasized-accelerate |
cubic-bezier(0.3, 0, 0.8, 0.15) |
|
--mdui-motion-easing-emphasized-decelerate |
cubic-bezier(0.05, 0.7, 0.1, 1) |
|
Duration | --mdui-motion-duration-short1 |
50ms |
--mdui-motion-duration-short2 |
100ms |
|
--mdui-motion-duration-short3 |
150ms |
|
--mdui-motion-duration-short4 |
200ms |
|
--mdui-motion-duration-medium1 |
250ms |
|
--mdui-motion-duration-medium2 |
300ms |
|
--mdui-motion-duration-medium3 |
350ms |
|
--mdui-motion-duration-medium4 |
400ms |
|
--mdui-motion-duration-long1 |
450ms |
|
--mdui-motion-duration-long2 |
500ms |
|
--mdui-motion-duration-long3 |
550ms |
|
--mdui-motion-duration-long4 |
600ms |
|
--mdui-motion-duration-extra-long1 |
700ms |
|
--mdui-motion-duration-extra-long2 |
800ms |
|
--mdui-motion-duration-extra-long3 |
900ms |
|
--mdui-motion-duration-extra-long4 |
1000ms |
Breakpoint
mdui components adjust their layout based on various breakpoints, which are provided through CSS custom properties. Here's an example of how to modify a breakpoint:
/* Modify the breakpoint value for sm */
:root {
--mdui-breakpoint-sm: 560px;
}
Please note that CSS custom properties cannot be used in CSS media queries. For example, the following usage is incorrect:
/* Incorrect usage. CSS custom properties cannot be used in media queries */
@media (min-width: var(--mdui-breakpoint-sm)) {
}
To determine breakpoints in JavaScript, use the breakpoint
function.
CSS Custom Property | Default |
---|---|
--mdui-breakpoint-xs |
0px |
--mdui-breakpoint-sm |
600px |
--mdui-breakpoint-md |
840px |
--mdui-breakpoint-lg |
1080px |
--mdui-breakpoint-xl |
1440px |
--mdui-breakpoint-xxl |
1920px |