wukuang/theme-变量速查手册.md

# 主题变量与 UnoCSS 类名速查手册

> 🎨 本文档用于快速查找可用的主题变量和 UnoCSS 类名，方便样式开发。
> 📋 基于设计系统规范整理，标注了变量在 theme-lib/palette 中的实际支持情况。

---

## 📋 目录

- [UnoCSS 类名使用规则](#unocss-类名使用规则)
- [CSS 变量使用方式](#css-变量使用方式)
- [1. 中性色彩（背景色）](#1-中性色彩背景色)
- [2. 中性色彩交互状态](#2-中性色彩交互状态)
- [3. 文字&图标色彩](#3-文字图标色彩)
- [4. 主题色&功能色](#4-主题色功能色)
- [实际使用示例](#实际使用示例)
- [SCSS 变量使用](#scss-变量使用)

---

## UnoCSS 类名使用规则

### 基本格式

```
lst-[属性缩写]-[变量名]
```

### 属性缩写

| 缩写 | 完整写法     | 对应 CSS 属性      | 示例                 |
| ---- | ------------ | ------------------ | -------------------- |
| `c`  | `color`      | `color`            | `lst-c-brand-color`  |
| `bg` | `background` | `background-color` | `lst-bg-brand-color` |
| `b`  | `border`     | `border-color`     | `lst-b-brand-color`  |

### 两类变量

#### 1️⃣ 特殊颜色变量（需要加属性前缀）

这些变量必须指定应用到的 CSS 属性：

```html
<!-- ✅ 正确 -->
<div class="lst-c-brand-color">文字</div>
<div class="lst-bg-brand-color">背景</div>
<div class="lst-b-brand-color">边框</div>

<!-- ❌ 错误：缺少属性前缀 -->
<div class="lst-brand-color">不生效</div>
```

**特殊颜色变量列表（主题色&功能色）：**

- `brand-color` - 品牌色
- `brand-color-hover` - 品牌色 hover
- `brand-color-active` - 品牌色 active
- `brand-color-disabled` - 品牌色 disabled
- `brand-color-focus` - 品牌色 focus
- `brand-color-light` - 品牌色 light
- `error-color` - 错误色
- `error-color-hover` - 错误色 hover
- `error-color-active` - 错误色 active
- `error-color-disabled` - 错误色 disabled
- `error-color-focus` - 错误色 focus
- `error-color-light` - 错误色 light
- `warning-color` - 警示色
- `warning-color-hover` - 警示色 hover
- `warning-color-active` - 警示色 active
- `warning-color-disabled` - 警示色 disabled
- `warning-color-focus` - 警示色 focus
- `warning-color-light` - 警示色 light
- `success-color` - 成功色
- `success-color-hover` - 成功色 hover
- `success-color-active` - 成功色 active
- `success-color-disabled` - 成功色 disabled
- `success-color-focus` - 成功色 focus
- `success-color-light` - 成功色 light

#### 2️⃣ 普通变量（直接使用）

其他变量直接使用 `lst-变量名`：

```html
<div class="lst-text-color-primary">文字</div>
<div class="lst-bg-color-container">背景</div>
<div class="lst-component-border">边框</div>
```

---

## CSS 变量使用方式

### 基本格式

```css
var(--ls-[变量名])
```

### 使用场景

当你需要在 **JavaScript/TypeScript** 或 **内联样式** 中使用主题变量时，可以使用 CSS 变量：

#### 1️⃣ 在 JavaScript 中获取变量值

```typescript
// 获取主题变量值
const brandColor = getComputedStyle(document.documentElement).getPropertyValue(
  "--ls-brand-color",
);
// 返回: "#1765FF"

const textColor = getComputedStyle(document.documentElement).getPropertyValue(
  "--ls-text-color-primary",
);
// 返回: "rgba(0,0,0,.9)"
```

#### 2️⃣ 在 Vue 内联样式中使用

```vue
<template>
  <div :style="{ backgroundColor: 'var(--ls-bg-color-container)' }">
    动态背景色
  </div>
</template>
```

#### 3️⃣ 在 CSS 中使用

```css
.custom-element {
  background-color: var(--ls-bg-color-container);
  color: var(--ls-text-color-primary);
  border: 1px solid var(--ls-component-border);
}
```

#### 4️⃣ 在 SCSS 中使用

```scss
.custom-element {
  background-color: var(--ls-bg-color-container);
  color: var(--ls-text-color-primary);

  &:hover {
    background-color: var(--ls-bg-color-container-hover);
  }
}
```

### 变量映射规则

| UnoCSS 类名                | CSS 变量                       | 说明     |
| -------------------------- | ------------------------------ | -------- |
| `lst-c-brand-color`        | `var(--ls-brand-color)`        | 文字颜色 |
| `lst-bg-brand-color`       | `var(--ls-brand-color)`        | 背景颜色 |
| `lst-b-brand-color`        | `var(--ls-brand-color)`        | 边框颜色 |
| `lst-bg-color-container`   | `var(--ls-bg-color-container)` | 容器背景 |
| `lst-c-text-color-primary` | `var(--ls-text-color-primary)` | 主要文字 |
| `lst-component-border`     | `var(--ls-component-border)`   | 组件边框 |

### 完整变量名列表

所有主题变量都遵循 `--ls-[变量名]` 的格式，例如：

**中性色彩：**

- `--ls-bg-color-page`
- `--ls-bg-color-container`
- `--ls-bg-color-secondarycontainer`
- `--ls-bg-color-component`
- `--ls-component-stroke`
- `--ls-component-border`

**主题色&功能色：**

- `--ls-brand-color`
- `--ls-brand-color-hover`
- `--ls-brand-color-active`
- `--ls-error-color`
- `--ls-warning-color`
- `--ls-success-color`

**文字色彩：**

- `--ls-text-color-primary`
- `--ls-text-color-secondary`
- `--ls-text-color-placeholder`
- `--ls-text-color-disabled`
- `--ls-text-color-anti`

### 注意事项

1. **变量前缀**：所有 CSS 变量都以 `--ls-` 开头
2. **响应式**：CSS 变量会自动跟随主题切换，无需手动更新
3. **兼容性**：支持所有现代浏览器（Chrome 49+, Firefox 31+, Safari 9.1+）
4. **推荐用法**：
   - ✅ 模板中使用 UnoCSS 类名（性能更好）
   - ✅ 动态样式使用 CSS 变量
   - ✅ SCSS 中优先使用 `useThemeVar()` 函数（见下方 SCSS 章节）

---

## 1. 中性色彩（背景色）

> Light 模式默认全局中性色彩配置

| 变量名                        | UnoCSS 类名                       | 颜色值    | 颜色描述           | 用途                           | 状态      |
| ----------------------------- | --------------------------------- | --------- | ------------------ | ------------------------------ | --------- |
| `bg-color-page`               | `lst-bg-color-page`               | `#EEEEF0` | 浅灰（冷色调）     | 默认页面底层背景               | ✅ 已支持 |
| `bg-color-container`          | `lst-bg-color-container`          | `#FFFFFF` | 纯白色             | 主要容器背景、次要层级页面背景 | ✅ 已支持 |
| `bg-color-secondarycontainer` | `lst-bg-color-secondarycontainer` | `#F6F6F7` | 极浅灰（接近白色） | 次要容器背景                   | ✅ 已支持 |
| `bg-color-component`          | `lst-bg-color-component`          | `#E7E8EB` | 浅灰色             | 组件背景、主要容器之上组件背景 | ✅ 已支持 |
| `component-stroke`            | `lst-component-stroke`            | `#E7E8EB` | 浅灰色             | 默认组件分割线                 | ✅ 已支持 |
| `component-border`            | `lst-component-border`            | `#DCDDE1` | 中浅灰色           | 默认边框                       | ✅ 已支持 |

---

## 2. 中性色彩交互状态

> 交互状态（hover、active、disabled）

| 变量名                               | UnoCSS 类名                              | 颜色值    | 颜色描述           | 用途                                             | 状态      |
| ------------------------------------ | ---------------------------------------- | --------- | ------------------ | ------------------------------------------------ | --------- |
| `bg-color-container-hover`           | `lst-bg-color-container-hover`           | `#F6F6F7` | 极浅灰（接近白色） | 主要容器背景 hover、次要层级页面背景 hover       | ✅ 已支持 |
| `bg-color-container-active`          | `lst-bg-color-container-active`          | `#E7E8EB` | 浅灰色             | 主要容器背景 click、次要层级页面背景 click       | ✅ 已支持 |
| `bg-color-secondarycontainer-hover`  | `lst-bg-color-secondarycontainer-hover`  | `#EEEEF0` | 浅灰（冷色调）     | 次要容器背景 hover                               | ✅ 已支持 |
| `bg-color-secondarycontainer-active` | `lst-bg-color-secondarycontainer-active` | `#DCDDE1` | 中浅灰色           | 次要容器背景 click                               | ✅ 已支持 |
| `bg-color-component-hover`           | `lst-bg-color-component-hover`           | `#DCDDE1` | 中浅灰色           | 组件背景 hover、主要容器之上组件背景 hover       | ✅ 已支持 |
| `bg-color-component-active`          | `lst-bg-color-component-active`          | `#A2A6B1` | 中灰色             | 组件背景 active、主要容器之上组件背景 active     | ✅ 已支持 |
| `bg-color-component-disabled`        | `lst-bg-color-component-disabled`        | `#EEEEF0` | 浅灰（冷色调）     | 组件背景 disabled、主要容器之上组件背景 disabled | ✅ 已支持 |

---

## 3. 文字&图标色彩

> 默认 Light 模式文字色彩配置

| 变量名                   | UnoCSS 类名                    | 颜色值                 | 颜色描述               | 用途                       | 状态      |
| ------------------------ | ------------------------------ | ---------------------- | ---------------------- | -------------------------- | --------- |
| `text-color-primary`     | `lst-c-text-color-primary`     | `rgba(0,0,0,.9)`       | 深黑（90%透明度）      | 主要文字色彩               | ✅ 已支持 |
| `text-color-secondary`   | `lst-c-text-color-secondary`   | `rgba(0,0,0,.6)`       | 中黑（60%透明度）      | 次要文字色彩               | ✅ 已支持 |
| `text-color-placeholder` | `lst-c-text-color-placeholder` | `rgba(0,0,0,.4)`       | 浅黑（40%透明度）      | 占位符文字色彩             | ✅ 已支持 |
| `text-color-disabled`    | `lst-c-text-color-disabled`    | `rgba(0,0,0,.26)`      | 极浅黑（26%透明度）    | 文字 disabled 态           | ✅ 已支持 |
| `text-color-anti`        | `lst-c-text-color-anti`        | `rgba(255,255,255,.9)` | 纯白（90%透明度）      | 文字反色色彩（深色背景上） | ✅ 已支持 |
| `text-color-brand`       | `lst-c-text-color-brand`       | `#1765FF`              | 品牌蓝（中等亮度蓝色） | 主题色文字色彩             | ✅ 已支持 |
| `text-color-link`        | `lst-c-text-color-link`        | `#1765FF`              | 品牌蓝（中等亮度蓝色） | 链接文字                   | ✅ 已支持 |

---

## 4. 主题色&功能色

> 主题相关配置

### 品牌色

| 变量名                 | UnoCSS 类名                                                        | 颜色值    | 颜色描述               | 用途                         | 状态      |
| ---------------------- | ------------------------------------------------------------------ | --------- | ---------------------- | ---------------------------- | --------- |
| `brand-color`          | `lst-c-brand-color`<br>`lst-bg-brand-color`<br>`lst-b-brand-color` | `#1765FF` | 品牌蓝（中等亮度蓝色） | 品牌色                       | ✅ 已支持 |
| `brand-color-hover`    | `lst-c-brand-color-hover`<br>`lst-bg-brand-color-hover`            | `#4287FF` | 亮蓝（较浅蓝色）       | 品牌色 hover                 | ✅ 已支持 |
| `brand-color-active`   | `lst-c-brand-color-active`<br>`lst-bg-brand-color-active`          | `#0947D9` | 深蓝（较深蓝色）       | 品牌色 active                | ✅ 已支持 |
| `brand-color-disabled` | `lst-c-brand-color-disabled`<br>`lst-bg-brand-color-disabled`      | `#C4E0FF` | 极浅蓝（接近白色）     | 品牌色 disabled              | ✅ 已支持 |
| `brand-color-focus`    | `lst-c-brand-color-focus`<br>`lst-bg-brand-color-focus`            | `#99C5FF` | 浅蓝（明亮蓝色）       | 品牌色 focus                 | ✅ 已支持 |
| `brand-color-light`    | `lst-bg-brand-color-light`                                         | `#F0FAFF` | 极浅蓝（接近白色）     | 品牌色 light（交互状态使用） | ✅ 已支持 |

### 错误色

| 变量名                 | UnoCSS 类名                                                        | 颜色值    | 颜色描述               | 用途                         | 状态      |
| ---------------------- | ------------------------------------------------------------------ | --------- | ---------------------- | ---------------------------- | --------- |
| `error-color`          | `lst-c-error-color`<br>`lst-bg-error-color`<br>`lst-b-error-color` | `#F63D46` | 警示红（高饱和度红色） | 错误色                       | ✅ 已支持 |
| `error-color-hover`    | `lst-c-error-color-hover`<br>`lst-bg-error-color-hover`            | `#FF6B6E` | 亮红（较浅红色）       | 错误色 hover                 | ✅ 已支持 |
| `error-color-active`   | `lst-c-error-color-active`<br>`lst-bg-error-color-active`          | `#CF2937` | 深红（较深红色）       | 错误色 active                | ✅ 已支持 |
| `error-color-disabled` | `lst-c-error-color-disabled`<br>`lst-bg-error-color-disabled`      | `#FFC5C2` | 极浅红（粉色）         | 错误色 disabled              | ✅ 已支持 |
| `error-color-focus`    | `lst-c-error-color-focus`<br>`lst-bg-error-color-focus`            | `#FF9896` | 浅红（明亮红色）       | 错误色 focus                 | ✅ 已支持 |
| `error-color-light`    | `lst-bg-error-color-light`                                         | `#FFEFED` | 极浅红（接近白色）     | 错误色 light（交互状态使用） | ✅ 已支持 |

### 警示色

| 变量名                   | UnoCSS 类名                                                              | 颜色值    | 颜色描述               | 用途                         | 状态      |
| ------------------------ | ------------------------------------------------------------------------ | --------- | ---------------------- | ---------------------------- | --------- |
| `warning-color`          | `lst-c-warning-color`<br>`lst-bg-warning-color`<br>`lst-b-warning-color` | `#FF7C17` | 警示橙（高饱和度橙色） | 警示色                       | ✅ 已支持 |
| `warning-color-hover`    | `lst-c-warning-color-hover`<br>`lst-bg-warning-color-hover`              | `#FF9A42` | 亮橙（较浅橙色）       | 警示色 hover                 | ✅ 已支持 |
| `warning-color-active`   | `lst-c-warning-color-active`<br>`lst-bg-warning-color-active`            | `#D95C09` | 深橙（较深橙色）       | 警示色 active                | ✅ 已支持 |
| `warning-color-disabled` | `lst-c-warning-color-disabled`<br>`lst-bg-warning-color-disabled`        | `#FFE6C4` | 极浅橙（淡黄色）       | 警示色 disabled              | ✅ 已支持 |
| `warning-color-focus`    | `lst-c-warning-color-focus`<br>`lst-bg-warning-color-focus`              | `#FFCF99` | 浅橙（明亮橙色）       | 警示色 focus                 | ✅ 已支持 |
| `warning-color-light`    | `lst-bg-warning-color-light`                                             | `#FFF9F0` | 极浅橙（接近白色）     | 警示色 light（交互状态使用） | ✅ 已支持 |

### 成功色

| 变量名                   | UnoCSS 类名                                                              | 颜色值    | 颜色描述               | 用途                         | 状态      |
| ------------------------ | ------------------------------------------------------------------------ | --------- | ---------------------- | ---------------------------- | --------- |
| `success-color`          | `lst-c-success-color`<br>`lst-bg-success-color`<br>`lst-b-success-color` | `#11B832` | 自然绿（中等亮度绿色） | 成功色                       | ✅ 已支持 |
| `success-color-hover`    | `lst-c-success-color-hover`<br>`lst-bg-success-color-hover`              | `#33C44B` | 亮绿（较浅绿色）       | 成功色 hover                 | ✅ 已支持 |
| `success-color-active`   | `lst-c-success-color-active`<br>`lst-bg-success-color-active`            | `#069126` | 深绿（较深绿色）       | 成功色 active                | ✅ 已支持 |
| `success-color-disabled` | `lst-c-success-color-disabled`<br>`lst-bg-success-color-disabled`        | `#B5EBB8` | 极浅绿（淡绿色）       | 成功色 disabled              | ✅ 已支持 |
| `success-color-focus`    | `lst-c-success-color-focus`<br>`lst-bg-success-color-focus`              | `#85DE8E` | 浅绿（明亮绿色）       | 成功色 focus                 | ✅ 已支持 |
| `success-color-light`    | `lst-bg-success-color-light`                                             | `#EEFCED` | 极浅绿（接近白色）     | 成功色 light（交互状态使用） | ✅ 已支持 |

---

## 实际使用示例

### 示例 1：卡片组件

```vue
<template>
  <!-- 白色卡片，带边框 -->
  <div
    class="lst-bg-color-container lst-component-border rounded-lg shadow-sm p-4"
  >
    <h3 class="lst-c-text-color-primary font-bold mb-2">卡片标题</h3>
    <p class="lst-c-text-color-secondary mb-4">卡片内容描述</p>
    <button
      class="lst-bg-brand-color lst-c-text-color-anti px-4 py-2 rounded hover:lst-bg-brand-color-hover"
    >
      主要操作
    </button>
  </div>
</template>
```

### 示例 2：警告提示框

```vue
<template>
  <!-- 橙色警告提示 -->
  <div
    class="lst-bg-warning-color-light lst-b-warning-color p-4 rounded flex items-center"
  >
    <span class="lst-c-warning-color mr-2">⚠️</span>
    <span class="lst-c-warning-color">这是一条警告信息</span>
  </div>
</template>
```

### 示例 3：表格样式

```vue
<template>
  <!-- 表格容器 -->
  <div class="lst-bg-color-container lst-component-border rounded">
    <!-- 表头 -->
    <div
      class="lst-bg-color-secondarycontainer lst-c-text-color-primary font-bold px-4 py-2"
    >
      列标题
    </div>
    <!-- 斑马纹行 -->
    <div
      class="lst-bg-color-secondarycontainer lst-c-text-color-secondary px-4 py-2"
    >
      普通行
    </div>
    <div class="lst-bg-color-container lst-c-text-color-secondary px-4 py-2">
      斑马行
    </div>
    <!-- 分隔线 -->
    <div class="lst-component-stroke h-px"></div>
  </div>
</template>
```

### 示例 4：表单输入框

```vue
<template>
  <div class="space-y-2">
    <label class="lst-c-text-color-primary">用户名</label>
    <input
      class="lst-bg-color-container lst-component-border lst-c-text-color-primary
             border rounded px-3 py-2 w-full
             focus:lst-b-brand-color focus:outline-none"
      placeholder="请输入用户名"
    />
    <!-- 占位符提示 -->
    <p class="lst-c-text-color-placeholder text-sm">请输入您的登录用户名</p>
    <!-- 错误提示 -->
    <p class="lst-c-error-color text-sm">用户名不能为空</p>
  </div>
</template>
```

### 示例 5：成功提示框

```vue
<template>
  <!-- 绿色成功提示 -->
  <div
    class="lst-bg-success-color-light lst-b-success-color p-4 rounded flex items-center"
  >
    <span class="lst-c-success-color mr-2">✅</span>
    <span class="lst-c-success-color">操作成功！</span>
  </div>
</template>
```

### 示例 6：按钮组

```vue
<template>
  <div class="flex gap-2">
    <!-- 主按钮 -->
    <button
      class="lst-bg-brand-color lst-c-text-color-anti px-4 py-2 rounded hover:lst-bg-brand-color-hover"
    >
      确认
    </button>

    <!-- 次要按钮 -->
    <button
      class="lst-bg-brand-color-light lst-c-brand-color px-4 py-2 rounded hover:lst-bg-brand-color-hover"
    >
      提交
    </button>

    <!-- 灰色按钮 -->
    <button
      class="lst-bg-color-component lst-c-text-color-primary px-4 py-2 rounded hover:lst-bg-color-component-hover"
    >
      取消
    </button>

    <!-- 危险按钮 -->
    <button
      class="lst-bg-error-color lst-c-text-color-anti px-4 py-2 rounded hover:lst-bg-error-color-hover"
    >
      删除
    </button>

    <!-- 成功按钮 -->
    <button
      class="lst-bg-success-color lst-c-text-color-anti px-4 py-2 rounded"
    >
      通过
    </button>

    <!-- 禁用按钮 -->
    <button
      class="lst-bg-brand-color-disabled lst-c-text-color-disabled px-4 py-2 rounded"
      disabled
    >
      不可用
    </button>
  </div>
</template>
```

### 示例 7：弹窗/模态框

```vue
<template>
  <!-- 遮罩层 -->
  <div
    class="lst-bg-color-page fixed inset-0 z-50 flex items-center justify-center"
  >
    <!-- 弹窗内容 -->
    <div
      class="lst-bg-color-container lst-c-text-color-primary rounded-lg shadow-lg w-96 p-6"
    >
      <!-- 标题栏 -->
      <div
        class="lst-bg-color-secondarycontainer lst-c-text-color-primary font-bold pb-4 mb-4 border-b lst-component-border"
      >
        弹窗标题
      </div>
      <!-- 内容区 -->
      <div class="lst-c-text-color-secondary mb-6">这里是弹窗内容区域</div>
      <!-- 底部按钮 -->
      <div class="flex justify-end gap-2">
        <button
          class="lst-bg-color-component lst-c-text-color-primary px-4 py-2 rounded hover:lst-bg-color-component-hover"
        >
          取消
        </button>
        <button
          class="lst-bg-brand-color lst-c-text-color-anti px-4 py-2 rounded hover:lst-bg-brand-color-hover"
        >
          确认
        </button>
      </div>
    </div>
  </div>
</template>
```

### 示例 8：状态标签

```vue
<template>
  <div class="flex gap-2">
    <!-- 成功状态 -->
    <span
      class="lst-bg-success-color-light lst-c-success-color px-3 py-1 rounded-full text-sm"
    >
      已通过
    </span>

    <!-- 警告状态 -->
    <span
      class="lst-bg-warning-color-light lst-c-warning-color px-3 py-1 rounded-full text-sm"
    >
      待审核
    </span>

    <!-- 错误状态 -->
    <span
      class="lst-bg-error-color-light lst-c-error-color px-3 py-1 rounded-full text-sm"
    >
      已拒绝
    </span>

    <!-- 品牌状态 -->
    <span
      class="lst-bg-brand-color-light lst-c-brand-color px-3 py-1 rounded-full text-sm"
    >
      进行中
    </span>
  </div>
</template>
```

---

## SCSS 变量使用

当 UnoCSS 无法满足需求时（如复杂计算、伪元素、媒体查询等），使用 SCSS：

### 基本用法

```vue
<style lang="scss" scoped>
@use "@lingshu/theme-lib/scss/util.scss" as *;

.my-component {
  color: useThemeVar("text-color-primary");
  background-color: useThemeVar("bg-color-container");
  border: 1px solid useThemeVar("component-border");
}
</style>
```

### 复杂示例

```vue
<style lang="scss" scoped>
@use "@lingshu/theme-lib/scss/util.scss" as *;

.card {
  background-color: useThemeVar("bg-color-container");
  border: 1px solid useThemeVar("component-border");
  border-radius: useThemeVar("border-radius-md");
  transition: all 0.3s ease;

  &:hover {
    border-color: useThemeVar("border-color-primary");
    box-shadow: useThemeVar("shadow2");
    background-color: useThemeVar("bg-color-secondarycontainer");
  }

  &::before {
    content: "";
    position: absolute;
    background-color: useThemeVar("brand-color");
  }

  .title {
    color: useThemeVar("text-color-primary");
    font-size: 16px;
  }

  .description {
    color: useThemeVar("text-color-secondary");
  }

  .divider {
    height: 1px;
    background-color: useThemeVar("component-stroke");
  }

  .error-message {
    color: useThemeVar("error-color");
    background-color: useThemeVar("error-color-light");
  }

  .success-message {
    color: useThemeVar("success-color");
    background-color: useThemeVar("success-color-light");
  }
}
</style>
```

---

## 🎯 常用组合速查

### 文字层次

```html
<!-- 标题 -->
<h1 class="lst-c-text-color-primary text-xl font-bold">一级标题</h1>
<h2 class="lst-c-text-color-primary text-lg font-semibold">二级标题</h2>

<!-- 正文 -->
<p class="lst-c-text-color-secondary">正文内容</p>

<!-- 占位符 -->
<span class="lst-c-text-color-placeholder">占位符文字</span>
<span class="lst-c-text-color-disabled">禁用文字</span>
```

### 卡片/容器

```html
<!-- 基础卡片 -->
<div class="lst-bg-color-container lst-component-border rounded p-4">
  白色卡片
</div>

<!-- 带阴影的卡片 -->
<div class="lst-bg-color-container rounded shadow-md p-4">悬浮卡片</div>

<!-- 灰色背景容器 -->
<div class="lst-bg-color-secondarycontainer rounded p-4">灰色背景区域</div>

<!-- 页面底层背景 -->
<div class="lst-bg-color-page min-h-screen">页面内容</div>
```

### 表单元素

```html
<!-- 输入框 -->
<input
  class="lst-bg-color-container lst-component-border lst-c-text-color-primary border rounded px-3 py-2"
/>

<!-- 标签 -->
<label class="lst-c-text-color-primary font-medium">标签文字</label>

<!-- 错误提示 -->
<p class="lst-c-error-color text-sm">错误信息</p>

<!-- 成功提示 -->
<p class="lst-c-success-color text-sm">操作成功</p>
```

### 状态标签

```html
<!-- 成功标签 -->
<span class="lst-bg-success-color-light lst-c-success-color px-2 py-1 rounded"
  >成功</span
>

<!-- 警告标签 -->
<span class="lst-bg-warning-color-light lst-c-warning-color px-2 py-1 rounded"
  >警告</span
>

<!-- 错误标签 -->
<span class="lst-bg-error-color-light lst-c-error-color px-2 py-1 rounded"
  >错误</span
>

<!-- 品牌标签 -->
<span class="lst-bg-brand-color-light lst-c-brand-color px-2 py-1 rounded"
  >进行中</span
>
```

### 按钮状态

```html
<!-- 主按钮 -->
<button class="lst-bg-brand-color lst-c-text-color-anti px-4 py-2 rounded">
  默认
</button>

<!-- 主按钮 Hover -->
<button
  class="lst-bg-brand-color-hover lst-c-text-color-anti px-4 py-2 rounded"
>
  Hover
</button>

<!-- 禁用按钮 -->
<button
  class="lst-bg-brand-color-disabled lst-c-text-color-disabled px-4 py-2 rounded"
  disabled
>
  Disabled
</button>

<!-- Focus 状态 -->
<button
  class="lst-bg-brand-color lst-c-text-color-anti px-4 py-2 rounded focus:lst-ring-brand-color-focus"
>
  Focus
</button>
```

---

## ⚠️ 注意事项

### 1. 特殊颜色必须加属性前缀

```html
<!-- ✅ 正确 -->
<div class="lst-c-brand-color lst-bg-brand-color">
  <!-- ❌ 错误 -->
  <div class="lst-brand-color"></div>
</div>
```

### 2. 不要在样式中硬编码颜色值

```vue
<!-- ❌ 错误 -->
<div style="color: #333; background: #fff;">

<!-- ✅ 正确 -->
<div class="lst-c-text-color-primary lst-bg-color-container">
```

### 3. 阴影使用

UnoCSS 暂不支持直接使用阴影变量，需要：

- 使用 UnoCSS 内置的 `shadow-sm`、`shadow-md`、`shadow-lg`
- 或在 SCSS 中使用 `useThemeVar('shadow1')`

### 4. 圆角使用

推荐使用 UnoCSS 内置类名：

- `rounded-sm` = 2px
- `rounded` = 4px
- `rounded-md` = 6px
- `rounded-lg` = 8px
- `rounded-xl` = 12px

或使用主题变量（SCSS 中）：

- `useThemeVar('border-radius-sm')` = 2px
- `useThemeVar('border-radius-base')` = 4px
- `useThemeVar('border-radius-md')` = 8px
- `useThemeVar('border-radius-lg')` = 10px
- `useThemeVar('border-radius-xl')` = 15px

---

## 🔍 调试技巧

### 在浏览器中查看当前主题变量

1. 打开开发者工具（F12）
2. 切换到 Elements 面板
3. 选中 `<html>` 元素
4. 查看 Computed 样式中的 `--ls-*` 变量
5. 点击变量值可以实时修改预览

### 切换主题查看效果

在控制台执行：

```javascript
// 切换到暗色主题
document.documentElement.classList.add("ls-theme__dark");
document.documentElement.classList.remove("ls-theme__light");

// 切换到亮色主题
document.documentElement.classList.add("ls-theme__light");
document.documentElement.classList.remove("ls-theme__dark");
```

---

## 🎯 快速参考卡片

### 最常用变量 TOP 10

| 排名 | 变量                          | 用途      | UnoCSS 类名                       |
| ---- | ----------------------------- | --------- | --------------------------------- |
| 1    | `text-color-primary`          | 标题/正文 | `lst-c-text-color-primary`        |
| 2    | `text-color-secondary`        | 次级文字  | `lst-c-text-color-secondary`      |
| 3    | `bg-color-container`          | 白色背景  | `lst-bg-color-container`          |
| 4    | `bg-color-secondarycontainer` | 灰色背景  | `lst-bg-color-secondarycontainer` |
| 5    | `brand-color`                 | 品牌色    | `lst-c-brand-color`               |
| 6    | `component-border`            | 边框      | `lst-component-border`            |
| 7    | `error-color`                 | 错误色    | `lst-c-error-color`               |
| 8    | `success-color`               | 成功色    | `lst-c-success-color`             |
| 9    | `warning-color`               | 警告色    | `lst-c-warning-color`             |
| 10   | `component-stroke`            | 分割线    | `lst-component-stroke`            |

---