MDUI文档English简体中文亮色模式暗色模式跟随系统
预设颜色
自选颜色
从壁纸提取颜色
请选择一张壁纸
开发指南
样式
暗色模式 动态配色 文章排版 设计令牌
与框架集成
组件
工具函数
独立包

设计令牌

设计令牌(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
本页目录