Theme System

VUP provides a unified theme system, maintaining global themes and design tokens through the _shared/assets/styles directory, supporting CSS variables and Tailwind CSS integration.

Overview

The theme system includes the following core files:

• base-colors.scss - Base color palette (0-9 color scales)
• base-size.scss - Spacing, border radius, font size, line height, control height
• theme.scss - Semantic color mapping (primary/success/warning/error/info/neutral)
• tailwind.scss - Tailwind CSS theme integration

File Structure

_shared/assets/styles/
  ├─ base-colors.scss    # Base color palette
  ├─ base-size.scss     # Size system
  ├─ theme.scss         # Semantic color mapping
  └─ tailwind.scss      # Tailwind integration

Base Color Palette (base-colors.scss)

The base color palette defines 10 color scales (0-9) for each color, providing a complete color system:

Color Categories

• Blue (primary) - Primary color, blue series
• Green (success) - Success color, green series
• Gold (warning) - Warning color, gold series
• Red (error) - Error color, red series
• Gray (info/neutral) - Info color/neutral color, gray series

Color Scale Explanation

Each color has 10 scales from 0-9:

• 0 - Lightest (background color)
• 5 - Main color (commonly used)
• 9 - Darkest (text color)

Usage Example

/* Using base color palette */
.element {
  background-color: var(--vup-blue-0); /* Lightest blue */
  color: var(--vup-blue-5); /* Main blue */
  border-color: var(--vup-blue-9); /* Darkest blue */
}

Size System (base-size.scss)

The size system defines unified spacing, border radius, font size, and other design tokens:

Spacing

--vup-space-0: 0;
--vup-space-2: 2px;
--vup-space-4: 4px;
--vup-space-8: 8px;
--vup-space-12: 12px;
--vup-space-16: 16px;
--vup-space-24: 24px;
--vup-space-32: 32px;
--vup-space-48: 48px;
--vup-space-64: 64px;

Border Radius

--vup-radius-xs: 2px;
--vup-radius-sm: 4px;
--vup-radius-md: 6px;
--vup-radius-lg: 8px;
--vup-radius-xl: 12px;

Font Size

--vup-font-size-xs: 12px;
--vup-font-size-sm: 13px;
--vup-font-size-md: 14px;
--vup-font-size-lg: 16px;
--vup-font-size-xl: 18px;
--vup-font-size-2xl: 20px;

Line Height

--vup-line-height-xs: 1.2;
--vup-line-height-sm: 1.4;
--vup-line-height-md: 1.6;
--vup-line-height-lg: 1.8;

Control Height

--vup-control-height-xs: 24px;
--vup-control-height-sm: 28px;
--vup-control-height-md: 32px;
--vup-control-height-lg: 36px;
--vup-control-height-xl: 40px;

Semantic Colors (theme.scss)

Semantic colors map the base color palette to semantic color variables:

Semantic Color Categories

• primary - Primary color (mapped from blue)
• success - Success color (mapped from green)
• warning - Warning color (mapped from gold)
• error - Error color (mapped from red)
• info - Info color (mapped from gray)
• neutral - Neutral color (mapped from gray)

Usage Example

/* Using semantic colors */
.button-primary {
  background-color: var(--vup-primary-5);
  color: var(--vup-primary-0);
}

.button-success {
  background-color: var(--vup-success-5);
  color: var(--vup-success-0);
}

.text-error {
  color: var(--vup-error-5);
}

Import Methods

1. Import Semantic Theme (CSS Variables)

Import in the project entry file or global style file:

// main.ts or global style file
import '@_shared/assets/styles/theme.scss';

After importing, you can use CSS variables in components:

<template>
  <div class="custom-element">Content</div>
</template>

<style scoped>
.custom-element {
  background-color: var(--vup-primary-0);
  color: var(--vup-primary-5);
  padding: var(--vup-space-16);
  border-radius: var(--vup-radius-md);
}
</style>

2. Import Tailwind Integration

If the project has Tailwind CSS enabled, you can import the Tailwind theme integration:

// main.ts or global style file
import '@_shared/assets/styles/tailwind.scss';

After importing, you can use theme colors in Tailwind classes:

<template>
  <div class="bg-primary-5 text-primary-0 p-4 rounded-md">
    Using Tailwind theme colors
  </div>
</template>

Tailwind CSS Integration

After importing tailwind.scss, theme colors are automatically mapped to Tailwind's color system:

Color Classes

<!-- Primary -->
<div class="bg-primary-5 text-primary-0">Primary</div>

<!-- Success -->
<div class="bg-success-5 text-success-0">Success</div>

<!-- Warning -->
<div class="bg-warning-5 text-warning-0">Warning</div>

<!-- Error -->
<div class="bg-error-5 text-error-0">Error</div>

<!-- Info -->
<div class="bg-info-5 text-info-0">Info</div>

Size Classes

<!-- Spacing -->
<div class="p-4 m-8">Using theme spacing</div>

<!-- Border radius -->
<div class="rounded-md">Using theme border radius</div>

Usage Examples

Using CSS Variables in Vue Components

<template>
  <div class="card">
    <h2 class="title">Title</h2>
    <p class="content">Content</p>
    <button class="button">Button</button>
  </div>
</template>

<style scoped>
.card {
  background-color: var(--vup-neutral-0);
  border: 1px solid var(--vup-neutral-3);
  border-radius: var(--vup-radius-lg);
  padding: var(--vup-space-24);
}

.title {
  color: var(--vup-primary-5);
  font-size: var(--vup-font-size-xl);
  margin-bottom: var(--vup-space-16);
}

.content {
  color: var(--vup-neutral-7);
  font-size: var(--vup-font-size-md);
  line-height: var(--vup-line-height-md);
}

.button {
  background-color: var(--vup-primary-5);
  color: var(--vup-primary-0);
  padding: var(--vup-space-8) var(--vup-space-16);
  border-radius: var(--vup-radius-md);
  height: var(--vup-control-height-md);
}
</style>

Using Tailwind Classes

<template>
  <div class="bg-neutral-0 border border-neutral-3 rounded-lg p-6">
    <h2 class="text-primary-5 text-xl mb-4">Title</h2>
    <p class="text-neutral-7 text-md leading-md">Content</p>
    <button class="bg-primary-5 text-primary-0 px-4 py-2 rounded-md h-8">
      Button
    </button>
  </div>
</template>

Combined Usage

<template>
  <div class="card">
    <div class="header">Header</div>
    <div class="body">Content</div>
  </div>
</template>

<style scoped>
.card {
  /* Using CSS variables */
  background-color: var(--vup-neutral-0);
  border-radius: var(--vup-radius-lg);

  /* Combined with Tailwind */
  @apply p-6 shadow-md;
}

.header {
  /* Using semantic colors */
  color: var(--vup-primary-5);
  @apply mb-4 text-xl font-bold;
}
</style>

Customizing Theme

Override Base Color Palette

If you need to customize colors, you can override the base color palette in your project:

// In your style file
:root {
  /* Override primary color */
  --vup-blue-5: #your-color;
  --vup-blue-6: #your-darker-color;
}

Override Semantic Colors

:root {
  /* Override semantic color mapping */
  --vup-primary-5: var(--vup-blue-5);
  --vup-primary-6: var(--vup-blue-6);
}

Override Sizes

:root {
  /* Override spacing */
  --vup-space-16: 20px;

  /* Override border radius */
  --vup-radius-md: 8px;
}

Best Practices

1. Prioritize Semantic Colors - Use primary, success, etc., instead of directly using blue, green
2. Use CSS Variables - Use CSS variables when precise control is needed
3. Combine with Tailwind - Use Tailwind classes for rapid development
4. Maintain Consistency - Use unified theme tokens throughout the project
5. Responsive Design - Combine Tailwind's responsive classes to achieve responsive layouts

Notes

• Theme files need to be imported in the project entry or global styles
• Most templates have already automatically imported theme files
• CSS variables are available at runtime, no compilation needed
• Tailwind integration needs to be properly configured in tailwind.config.js
• When customizing themes, maintain consistency in color scales

Related Resources

• Tailwind CSS Documentation
• CSS Variables Documentation