npm package: @qql1/unocss-preset-elementplus
Description: UnoCSS preset for Element Plus CSS variables and design tokens integration
Author: qql2
Latest version: 1.0.5

# UnoCSS Preset Element Plus

A UnoCSS preset that provides comprehensive support for Element Plus CSS variables and design tokens, allowing seamless integration between UnoCSS utility classes and Element Plus components.

## Features

- 🎨 **Complete Element Plus Color System** - Access all Element Plus color variables through UnoCSS utilities
- 🌗 **Theme Support** - Full support for light/dark theme variables
- 📦 **Zero Configuration** - Works out of the box with Element Plus
- 🔧 **Flexible Options** - Customizable prefix and feature toggles
- 💡 **Intelligent IntelliSense** - Full TypeScript support with proper type definitions
- 🎯 **Optimized Bundle** - Tree-shakeable with minimal runtime overhead

## Installation

```bash
npm install @qql1/unocss-preset-elementplus
# or
pnpm add @qql1/unocss-preset-elementplus
# or
yarn add @qql1/unocss-preset-elementplus
```

## Usage

### Basic Setup

Add the preset to your UnoCSS configuration:

```typescript
// unocss.config.ts
import { defineConfig } from 'unocss'
import { presetElementPlus } from '@qql1/unocss-preset-elementplus'

export default defineConfig({
  presets: [
    // ... other presets
    presetElementPlus()
  ]
})
```

### With Options

```typescript
import { defineConfig } from 'unocss'
import { presetElementPlus } from '@qql1/unocss-preset-elementplus'

export default defineConfig({
  presets: [
    presetElementPlus({
      prefix: 'el-',                    // Add prefix to utilities
      includeColorVariants: true,      // Include light/dark color variants
      includeShadows: true             // Include shadow utilities
    })
  ]
})
```

### Using Shortcuts

The preset includes predefined shortcuts for common Element Plus patterns:

```typescript
import { defineConfig } from 'unocss'
import { presetElementPlus, elementPlusShortcuts } from '@qql1/unocss-preset-elementplus'

export default defineConfig({
  presets: [
    presetElementPlus()
  ],
  shortcuts: [
    ...elementPlusShortcuts
  ]
})
```

## Available Utilities

### Color System

#### Theme Colors
```html
<!-- Background Colors -->
<div class="bg-primary">Primary background</div>
<div class="bg-success">Success background</div>
<div class="bg-warning">Warning background</div>
<div class="bg-danger">Danger background</div>
<div class="bg-info">Info background</div>

<!-- Text Colors -->
<span class="text-primary">Primary text</span>
<span class="text-success">Success text</span>

<!-- Border Colors -->
<div class="border border-primary">Primary border</div>
```

#### Color Variants
```html
<!-- Light variants (1-9) -->
<div class="bg-primary-light-3">Light primary</div>
<div class="text-success-light-5">Light success text</div>

<!-- Dark variants (1-2) -->
<div class="bg-warning-dark-2">Dark warning</div>
<div class="border-danger-dark-1">Dark danger border</div>
```

#### Opacity Variants
支持所有颜色的透明度变体，使用 `/{opacity}` 语法，透明度值为 0-100 的整数：

```html
<!-- Background colors with opacity -->
<div class="bg-primary/30">30% 透明度的主色背景</div>
<div class="bg-success/50">50% 透明度的成功色背景</div>
<div class="bg-white/20">20% 透明度的白色背景</div>

<!-- Text colors with opacity -->
<span class="text-primary/80">80% 透明度的主色文字</span>
<span class="text-danger/60">60% 透明度的危险色文字</span>
<span class="text-regular/70">70% 透明度的常规文字</span>

<!-- Border colors with opacity -->
<div class="border border-primary/40">40% 透明度的主色边框</div>
<div class="border border-light/50">50% 透明度的浅色边框</div>

<!-- Color variants with opacity -->
<div class="bg-primary-light-3/50">50% 透明度的浅主色背景</div>
<div class="text-success-dark-2/70">70% 透明度的深成功色文字</div>

<!-- Fill colors with opacity -->
<div class="bg-fill/30">30% 透明度的填充色背景</div>
<div class="bg-fill-light/40">40% 透明度的浅填充色背景</div>
```

#### System Colors
```html
<!-- Text System Colors -->
<p class="text-regular">Regular text</p>
<p class="text-secondary">Secondary text</p>
<p class="text-placeholder">Placeholder text</p>
<p class="text-disabled">Disabled text</p>

<!-- Background System Colors -->
<div class="bg-default">Default background</div>
<div class="bg-page">Page background</div>
<div class="bg-overlay">Overlay background</div>

<!-- Border System Colors -->
<div class="border border-light">Light border</div>
<div class="border border-lighter">Lighter border</div>
<div class="border border-extra-light">Extra light border</div>
```

#### Fill Colors
```html
<!-- Fill color backgrounds -->
<div class="bg-fill">Default fill</div>
<div class="bg-fill-light">Light fill</div>
<div class="bg-fill-lighter">Lighter fill</div>
<div class="bg-fill-extra-light">Extra light fill</div>
<div class="bg-fill-dark">Dark fill</div>
<div class="bg-fill-darker">Darker fill</div>
<div class="bg-fill-blank">Blank fill</div>
```

### Gradient Utilities

#### Theme Color Gradients
```html
<!-- Basic gradients -->
<div class="bg-gradient-to-r from-primary to-success">
  Primary to success gradient
</div>

<!-- With color variants -->
<div class="bg-gradient-to-br from-primary-light-3 via-success to-warning-dark-1">
  Complex gradient with variants
</div>

<!-- Fill color gradients -->
<div class="bg-gradient-to-t from-fill-light to-fill-darker">
  Fill gradient
</div>
```

### Shadow Utilities
```html
<!-- Element Plus shadows -->
<div class="shadow-base">Base shadow</div>
<div class="shadow-light">Light shadow</div>
<div class="shadow-lighter">Lighter shadow</div>
<div class="shadow-dark">Dark shadow</div>
```

### State Utilities
```html
<!-- Disabled states -->
<div class="bg-disabled text-disabled border-disabled">
  Disabled element
</div>

<!-- Overlay and mask -->
<div class="bg-overlay">Overlay background</div>
<div class="bg-mask">Mask background</div>
```

## Predefined Shortcuts

The preset includes shortcuts for common Element Plus component patterns:

```html
<!-- Card-like appearance -->
<div class="el-card">Card styled element</div>

<!-- Button styles -->
<button class="el-button-primary">Primary Button</button>
<button class="el-button-success">Success Button</button>
<button class="el-button-warning">Warning Button</button>
<button class="el-button-danger">Danger Button</button>

<!-- Input styles -->
<input class="el-input" placeholder="Enter text">
<input class="el-input-disabled" disabled>
```

## Configuration Options

### PresetElementPlusOptions

```typescript
interface PresetElementPlusOptions {
  /**
   * Prefix for utility classes
   * @default ''
   */
  prefix?: string
  
  /**
   * Whether to include color variant utilities (light/dark levels)
   * @default true
   */
  includeColorVariants?: boolean
  
  /**
   * Whether to include shadow utilities
   * @default true
   */
  includeShadows?: boolean
}
```

## Element Plus Integration

This preset is designed to work seamlessly with Element Plus. Make sure you have Element Plus CSS variables available in your project:

```typescript
// main.ts
import { createApp } from 'vue'
import ElementPlus from 'element-plus'
import 'element-plus/dist/index.css' // This provides the CSS variables
import 'uno.css' // Your UnoCSS styles

const app = createApp(App)
app.use(ElementPlus)
app.mount('#app')
```

## Examples

### Complete Component Example

```vue
<template>
  <div class="el-card">
    <h2 class="text-primary text-xl font-bold mb-4">Settings Panel</h2>
    
    <div class="space-y-4">
      <div class="bg-fill-light p-4 rounded">
        <label class="text-regular text-sm">Username</label>
        <input 
          class="el-input mt-1 w-full" 
          placeholder="Enter username"
        >
      </div>
      
      <div class="flex gap-2">
        <button class="el-button-primary">Save</button>
        <button class="el-button-danger">Cancel</button>
      </div>
    </div>
    
    <!-- Status indicators with variants -->
    <div class="mt-6 space-y-2">
      <div class="bg-success-light-9 text-success p-2 rounded text-sm">
        ✓ Profile updated successfully
      </div>
      
      <div class="bg-warning-light-9 text-warning p-2 rounded text-sm">
        ⚠ Please verify your email
      </div>
    </div>
  </div>
</template>
```

### Theme-Aware Components

```vue
<template>
  <div class="min-h-screen bg-page">
    <!-- Header with theme colors -->
    <header class="bg-default border-b border-light p-4">
      <h1 class="text-primary text-2xl font-bold">My App</h1>
    </header>
    
    <!-- Content area -->
    <main class="p-6">
      <div class="bg-default shadow-base rounded-lg p-6">
        <p class="text-regular">
          This content automatically adapts to light/dark themes
          using Element Plus CSS variables.
        </p>
        
        <!-- Interactive elements -->
        <div class="mt-4 space-x-2">
          <span class="bg-primary-light-9 text-primary px-2 py-1 rounded text-sm">
            Primary Tag
          </span>
          <span class="bg-success-light-9 text-success px-2 py-1 rounded text-sm">
            Success Tag  
          </span>
        </div>
      </div>
    </main>
  </div>
</template>
```

## CSS Variables Reference

This preset provides access to all Element Plus CSS variables:

- **Colors**: `--el-color-primary`, `--el-color-success`, etc.
- **Text**: `--el-text-color-primary`, `--el-text-color-regular`, etc.
- **Backgrounds**: `--el-bg-color`, `--el-bg-color-page`, etc.
- **Borders**: `--el-border-color`, `--el-border-color-light`, etc.
- **Fill**: `--el-fill-color`, `--el-fill-color-light`, etc.
- **Shadows**: `--el-box-shadow`, `--el-box-shadow-light`, etc.

## Contributing

Contributions are welcome! Please feel free to submit a Pull Request.

## License

MIT License

## Related

- [UnoCSS](https://github.com/unocss/unocss) - The instant on-demand atomic CSS engine
- [Element Plus](https://github.com/element-plus/element-plus) - Vue 3 UI library