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
MDUIDocsEnglish简体中文LightDarkSystem
Preset Colors
Custom Color
Extract Color from Wallpaper
Select a Wallpaper
Getting Started
Introduction Installation Usage TypeScript Support IDE Support Localization Frequently Asked Questions
Styles
Dark Theme Dynamic Theme Typography Design Tokens
Frameworks
React Vue Angular
Components
Button ButtonIcon Fab SegmentedButton Chip Card Checkbox Radio Switch Slider RangeSlider List Collapse Tabs Dropdown Menu Select TextField LinearProgress CircularProgress Dialog Divider Avatar Badge Icon Tooltip Snackbar NavigationBar NavigationDrawer NavigationRail BottomAppBar TopAppBar Layout
Functions
JavaScript Library dialog alert confirm prompt snackbar getTheme setTheme getColorFromImage setColorScheme removeColorScheme loadLocale setLocale getLocale throttle observeResize breakpoint
Libraries
@mdui/icons