@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);
}