设计令牌

设计令牌(Design Tokens)是一种用于管理设计系统的策略。它将设计系统中的所有可复用元素(例如颜色、字体、间距等)抽象为独立的变量,以便在整个设计系统中进行统一的管理和应用。

mdui 使用全局 CSS 自定义属性来实现设计令牌。这意味着,你只需修改 CSS 自定义属性,就能全局修改所有 mdui 组件的样式。同时,对于你自己开发的样式,也推荐优先引用 CSS 自定义属性,以确保你的样式与 mdui 组件的样式保持统一,此外,在修改动态配色时,你自己的样式也能同步更新配色。

颜色

mdui 为亮色模式和暗色模式分别提供了一组 CSS 自定义属性。在亮色模式下,CSS 自定义属性名为 --mdui-color-{name}-light,其中 {name} 为颜色名称;在暗色模式下则为 --mdui-color-{name}-dark

此外,mdui 还提供了一组名为 --mdui-color-{name} 的 CSS 自定义属性,该属性在亮色模式下会引用 --mdui-color-{name}-light,在暗色模式下会引用 --mdui-color-{name}-dark,因此能根据当前亮、暗色模式自动切换颜色。

如果你需要修改部分颜色的 CSS 自定义属性,需要同时修改 --mdui-color-{name}-light--mdui-color-{name}-dark 两个属性。而在读取 CSS 自定义属性时,直接使用 --mdui-color-{name} 属性即可。

CSS 自定义属性的属性值为 RGB 的三个颜色使用 , 分隔,下面的示例演示了颜色的 CSS 自定义属性的用法:

/* 修改 primary 的颜色值 */
:root {
  --mdui-color-primary-light: 103, 80, 164;
  --mdui-color-primary-dark: 208, 188, 255;
}

/* 把 foo 元素的背景色设置为 primary */
.foo {
  background-color: rgb(var(--mdui-color-primary));
}

/* 把 bar 元素的背景色设置为含 0.8 不透明度的 primary */
.bar {
  background-color: rgba(var(--mdui-color-primary), 0.8);
}

如果你需要创建一套全新的配色,推荐使用 setColorScheme 函数,该函数能根据你给定的一个颜色值生成一整套配色方案。

颜色名 CSS 自定义属性 默认值 示例
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

圆角

mdui 提供了 7 种不同大小的圆角。以下是如何使用这些圆角的 CSS 自定义属性的示例:

/* 修改 extra-small 的圆角大小 */
:root {
  --mdui-shape-corner-extra-small: 0.3rem;
}

/* 把 foo 元素的圆角设置为 extra-small */
.foo {
  border-radius: var(--mdui-shape-corner-extra-small);
}
CSS 自定义属性 默认值 示例
--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

排版

mdui 提供了 15 种不同的文字样式,包括 Display large、Display medium、Display small、Headline large、Headline medium、Headline small、Title large、Title medium、Title small、Label large、Label medium、Label small、Body large、Body medium、Body small。

下面是使用示例:

/* 修改 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;
}

/* 把 foo 元素的文字样式设置为 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 自定义属性 默认值 示例
--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

状态层不透明度

部分 mdui 组件在交互时会在其上添加一层半透明遮罩。例如 <mdui-button> 组件,在鼠标悬浮、聚焦、按下或拖动时,都会出现半透明遮罩。你可以通过修改 CSS 自定义属性来调整这些遮罩的不透明度。

下面是使用示例:

/* 修改状态层不透明度 */
: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 自定义属性 默认值 示例
--mdui-state-layer-hover 0.08
--mdui-state-layer-focus 0.12
--mdui-state-layer-pressed 0.12
--mdui-state-layer-dragged 0.16

抬升高度(阴影)

部分 mdui 组件具有阴影效果,以模拟组件在页面上的抬升感。你可以通过修改 CSS 自定义属性来调整组件的阴影效果。

下面是使用示例:

/* 修改 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%);
}

/* 把 foo 元素的阴影设置为 level1 */
.foo {
  box-shadow: var(--mdui-elevation-level1);
}
CSS 自定义属性 默认值 示例
--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%)

动画

mdui 组件中的动画缓动曲线和持续时间可以通过 CSS 自定义属性进行配置。

下面是使用示例:

/* 修改 standard 的缓动曲线、及 short1 的持续时间 */
:root {
  --mdui-motion-easing-standard: cubic-bezier(0.2, 0, 0, 1);
  --mdui-motion-duration-short1: 40ms;
}

/* 设置 foo 元素的过渡效果使用 standard 的缓动曲线、及 short1 的持续时间 */
.foo {
  transition: all var(--mdui-motion-duration-short1) var(--mdui-motion-easing-standard);
}
类型 CSS 自定义属性 默认值
缓动曲线 --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)
持续时间 --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

响应式断点

mdui 提供了一系列的响应式断点,这些断点可以通过 CSS 自定义属性进行配置。下面是使用示例:

/* 修改 sm 的断点值 */
:root {
  --mdui-breakpoint-sm: 560px;
}

需要注意的是,这些 CSS 自定义属性不能在 CSS 媒体查询中使用。以下是一个错误的示例:

/* 错误用法。媒体查询中无法使用 CSS 自定义属性 */
@media (min-width: var(--mdui-breakpoint-sm)) {

}

如果你需要在 JavaScript 中进行断点判断,可以使用 breakpoint 函数。

CSS 自定义属性 默认值
--mdui-breakpoint-xs 0px
--mdui-breakpoint-sm 600px
--mdui-breakpoint-md 840px
--mdui-breakpoint-lg 1080px
--mdui-breakpoint-xl 1440px
--mdui-breakpoint-xxl 1920px
MDUI文档English简体中文亮色模式暗色模式跟随系统
预设颜色
自选颜色
从壁纸提取颜色
请选择一张壁纸
开发指南
概述 安装 快速入门 TypeScript 支持 IDE 支持 本地化 常见问题
样式
暗色模式 动态配色 文章排版 设计令牌
与框架集成
React Vue Angular
组件
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 布局
工具函数
jq 工具库 dialog alert confirm prompt snackbar getTheme setTheme getColorFromImage setColorScheme removeColorScheme loadLocale setLocale getLocale throttle observeResize breakpoint
独立包
@mdui/icons 图标组件库