npm package: @sinoui/tailwindcss-plugin
Description: @sinoui/core与tailwindcss组合使用的插件
Latest version: 2.0.0-alpha.26

# @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 中这样使用：

```react
<div className="text-primary"></div>
```

会生成一下 css：

```css
.text-primary {
  --opacity: 1;
  color: rgba(var(--md-sys-color-primary), var(--opacity));
}
```

#### 1.1.2. 通过 css 变量定制主题

`@sinoui/tailwindcss-plugin` 会插入以下基础 css：

```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 中使用的示例：

```html
<div class="text-primary/state-hover"></div>
```

产生的 css 如下：

```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`。

例如：

```html
<div class="display-large"></div>
```

会生成以下 css：

```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 代码：

```css
.text-alert-info {
  color: rgba(var(--sino-color-alert-info), 1);
}
```