@sinoui/tailwindcss-plugin

在项目中使用 @sinoui/core，必须集成 @sinoui/tailwindcss-plugin 插件。

1. m3 设计变量

通过 css 变量可以动态改变设计变量，可以在 tailwindcss 中直接使用 m3(material design v3, material you) 设计变量。

1.1. 颜色系统

可以通过 css 变量动态定制颜色系统。

以 primary 为例说明。

1.1.1. 在 tailwindcss 中使用

在 tailwindcss 中这样使用：

<div className="text-primary"></div>

会生成一下 css：

.text-primary {
  --opacity: 1;
  color: rgba(var(--md-sys-color-primary), var(--opacity));
}

1.1.2. 通过 css 变量定制主题

@sinoui/tailwindcss-plugin 会插入以下基础 css：

:root {
  /** 默认的 primary 设计变量 */
  --md-ref-palette-primary0: #000000;
  --md-ref-palette-primary10: #21005d;
  --md-ref-palette-primary20: #381e72;
  --md-ref-palette-primary30: #4f378b;
  --md-ref-palette-primary40: #6750a4;
  --md-ref-palette-primary50: #7f67be;
  --md-ref-palette-primary60: #9a82db;
  --md-ref-palette-primary70: #b69df8;
  --md-ref-palette-primary80: #d0bcff;
  --md-ref-palette-primary90: #eaddff;
  --md-ref-palette-primary95: #f6edff;
  --md-ref-palette-primary99: #fffbfe;
  --md-ref-palette-primary100: #ffffff;

  /** light */
  --md-sys-color-primary-light: --md-ref-palette-primary40;
  /** dark */
  --md-sys-color-primary-dark: --md-ref-palette-primary80;

  /** 主颜色在 light 情况下的值 */
  --md-sys-color-primary: var(--md-sys-color-primary-light);
}

.dark {
  /** 主颜色在 dark 情况下的值 */
  --md-sys-color-primary: var(--md-sys-color-primary-dark);
}

如果我们需要切换主颜色，只需要变更primary 设计变量即可。

1.2. state layer

不可以通过 css 变量定制状态层透明度。

m3 采用透明度来定义状态层的深度感。定义了以下透明度：

state	opacity	对应的 tailwindcss 中的名称	备注
hover	0.08	state-hover
focus	0.12	state-focus
pressed	0.12	state-pressed
dragged	0.16	state-dragged
disabled for content	0.38	state-disbled-content	不可用元素的内容透明度
disabled for container	0.12	state-disabled-container	不可用元素的表面透明度

tailwindcss 中使用的示例：

<div class="text-primary/state-hover"></div>

产生的 css 如下：

.text-primary\/state-hover {
  --opacity: 0.08;
  color: rgba(var(--md-sys-color-primary), var(--opacity));
}

1.3. 文本样式

可以通过 css 变量定制文本样式。

m3 定义了 5 大类文本样式，每个分类又分成 large、medium 和 small 三个档次。

定义的 5 大类文本：

• display
• headline
• body
• label
• title

在 tailwindcss 中，可以直接使用这些文本样式功能类，功能类的名称为 ${类别名称}-${档次}，如display-large。

例如：

<div class="display-large"></div>

会生成以下 css：

.display-large {
  font-style: Regular;
  font-weight: 400;
  font-size: 57px;
  line-height: 64px;
  letter-spacing: -0.25px;
}

1.4. 海拔

在 m3 体系中的组件都有自己的海拔。可以通过三种手段来表达海拔：

• 不同的表面颜色可以用来表达组件之间的海拔
• 使用阴影来表达关键组件的海拔（例如 FAB，即浮动按钮）
• 使用遮罩层来表达组件的海拔（例如弹窗）

大部分情况下推荐采用第一种方案，只有第一种方案无法满足时，采用阴影方案。

1.4.1. 海拔阴影

可以通过环境变量定制海拔阴影颜色。

m3 体系定了 5 个级别的海拔，如下所示：

海拔级别	对应的阴影高度(px)
level 0	0
level 1	1
level 2	3
level 3	6
level 4	8
level 5	12

我们可以在 tailwindcss 中直接使用海拔阴影样式：elevation-0、elevation-1、elevation-2...。

1.4.2. 通过透明度表达海拔

m3 推荐表面采用不同透明度的主颜色来表达海拔。海拔与透明度的对应关系如下：

海拔级别	对应的透明度
level 0	0
level 1	0.05
level 2	0.08
level 3	0.11
level 4	0.12
level 5	0.14

1.5. 圆角样式

m3 中几乎每个组件都会有圆角样式。 m3 定义了以下级别的样式，@sinoui/core 扩展了 tailwdindcss 的 rounded 功能类，纳入了 m3 这些圆角样式：

圆角级别	圆角尺寸	对应的 tailwindcss 样式
extra-small	4px	rounded、rounded-extra-small
small	8px	rounded-small
medium	12px	rounded-medium
large	16px	rounded-large
extra-large	28px	rounded-extra-large

1.6. 动效（motion）

动效可以使 UI 变得有趣、富有变现力且易于使用。

1.6.1. 缓动函数（easing）

m3 定义了两组缓动函数：

• emphasized easing set - 代表了 m3 的表现风格，是最常见的。
• standard easing set - 用于简单、小的或者功能为中心的过渡场景。

默认值如下所示：

token	默认值	tailwindcss 功能类
--m3-sys-motion-easing-emphasized	cubic-bezier(0.2, 0.0, 0, 1.0)	ease-emphasized
--m3-sys-motion-easing-emphasized-decelerate	cubic-bezier(0.05, 0.7, 0.1, 1.0)	ease-emphasized-decelerate
--m3-sys-motion-easing-emphasized-accelerate	cubic-bezier(0.3, 0.0, 0.8, 0.15)	ease-emphasized-accelerate
--m3-sys-motion-easing-standard	cubic-bezier(0.2, 0.0, 0, 1.0)	ease-standard
--m3-sys-motion-easing-standard-decelerate	cubic-bezier(0, 0, 0, 1)	ease-standard-decelerate
--m3-sys-motion-easing-standard-accelerate	cubic-bezier(0.3, 0, 1, 1)	ease-standard-accelerate

1.6.2. 持续时长（duration）

m3 定义了不同级别的过渡持续时长：

• short - 用于以小功能为中心的过渡，如切换单选按钮的选中状态。
• medium - 用于屏幕中等规模的区域过渡场景。
• long - 一般与 emphasized easing set 共同出现。用于大场景过渡。

每个级别又分成 4 个阶梯。持续时长如下：

token	默认值	tailwindcss 功能类
--m3-sys-motion-duration-short1	50ms	duration-short1
--m3-sys-motion-duration-short2	100ms	duration-short2
--m3-sys-motion-duration-short3	150ms	duration-short3
--m3-sys-motion-duration-short4	200ms	duration-short4
--m3-sys-motion-duration-medium1	250ms	duration-medium1
--m3-sys-motion-duration-medium2	300ms	duration-medium2
--m3-sys-motion-duration-medium3	350ms	duration-medium3
--m3-sys-motion-duration-medium4	400ms	duration-medium4
--m3-sys-motion-duration-long1	450ms	duration-long1
--m3-sys-motion-duration-long2	500ms	duration-long2
--m3-sys-motion-duration-long3	550ms	duration-long3
--m3-sys-motion-duration-long4	600ms	duration-long4

1.7. 文本颜色

三个最常用的文本颜色：

• 主文本颜色：text-on-surface
• 辅助文本颜色：text-secondary （或者 text-on-surface-variant）
• 禁用文本颜色：text-disabled （或者 -on-surface/state-disabled-content）

m3 中的文本颜色都是以 on- 开头的，例如：

• 背景色为主颜色之上的文本颜色：on-primary。
• 背景色为警告色之上的文本颜色：on-warning。

2. 组件

2.1. Alert 组件

2.1.1. 设计变量（design token）

基础的设计变量：

• --sino-color-alert - 警告提示组件关键色。
• --sino-color-alert-container - 用于警告提示组件的容器表面的颜色。
• --sino-color-alert-on-container - 在容器颜色之上的文本颜色。
• --sino-color-alert-icon - 在容器颜色之上的图标颜色。
• --sino-color-alert-outline - 警告提示框轮廓颜色。

需要将类型添加到 -alert 之后，例如：--sino-color-alert-info。

2.1.2. 默认值：light

设计变量	info	success	warning	error
--sino-color-alert	lightBlue[700]	green[800]	#ed6c02	red[700]
--sino-color-alert-container	lighten(lightBlue[500], 0.9)	lighten(green[500], 0.9)	lighten(orange[500], 0.9)	lighten(red[400], 0.9)
--sino-color-alert-on-container	darken(lightBlue[500], 0.6)	darken(green[500], 0.6)	darken(orange[500], 0.6)	darken(red[400], 0.6)
--sino-color-alert-icon	lightBlue[500]	green[500]	orange[500]	red[400]
--sino-color-alert-outline	lightBlue[500]	green[500]	orange[500]	red[400]

2.1.3. 默认值：dark

设计变量	info	success	warning	error
--sino-color-alert	lightBlue[900]	green[900]	orange[900]	red[800]
--sino-color-alert-container	darken(lightBlue[500], 0.9)	darken(green[500], 0.9)	darken(orange[500], 0.9)	darken(red[400], 0.9)
--sino-color-alert-on-container	lighten(lightBlue[500], 0.6)	lighten(green[500], 0.6)	lighten(orange[500], 0.6)	lighten(red[400], 0.6)
--sino-color-alert-icon	lightBlue[700]	green[800]	#ed6c02	red[700]
--sino-color-alert-outline	lightBlue[500]	green[500]	orange[500]	red[400]

2.1.4. tailwindcss 支持

会将警告提示框的颜色设计变量加入到 tailwindcss 颜色系统中，并且在 tailwidcss 的颜色名称与设计变量名称一致，只是需要去掉 --sino-color- 前缀。

如 text-alert-info 会生成以下 css 代码：

.text-alert-info {
  color: rgba(var(--sino-color-alert-info), 1);
}