Style Development Documentation

Overview

This document details the style processing mechanism and customization methods of the VJSP Vue3 framework. The framework adopts a modern CSS architecture, combining Tailwind CSS, Less preprocessor, and CSS variable system to provide a flexible and maintainable style solution.

Style Architecture

1. Style File Structure

src/styles/
├── components/           # Component styles
│   ├── nprogress.less   # Progress bar styles
│   ├── tables.less      # Table-related styles
│   └── tools.less       # Utility class styles
├── element/              # Element Plus theme customization
│   ├── dark.less        # Dark theme
│   └── index.less       # Element Plus theme entry
├── index.less           # Global style entry
└── variables.module.less # CSS variable system

2. Style Processing Flow

1. CSS Variable Definition: Define global CSS variables in variables.module.less
2. Tailwind Integration: Import Tailwind base styles through index.less
3. Component Styles: Organize component styles by functional modules
4. Theme Customization: Element Plus theme customization through CSS variable overrides

Core Style Mechanisms

1. CSS Variable System

The framework uses CSS custom properties (CSS Variables) as the style foundation, supporting light/dark theme switching. All CSS variables are defined in the [variables.module.less] file.

Complete CSS Variable Table

Variable Name	Default Value	Function Description	Theme Support
--left-menu-max-width	200px	Left menu maximum width	General
--navbar-height	64px	Desktop navigation bar height	General
--navbar-height-mobile	56px	Mobile navigation bar height	General
--tags-view-height	36px	Desktop tag page height	General
--tags-view-height-mobile	32px	Mobile tag page height	General
--global-btn-radius	6px	Global button border radius	General
--spacing-xs	4px	Extra small spacing for tight arrangements	General
--spacing-sm	8px	Small spacing for internal element spacing	General
--spacing-md	16px	Medium spacing for regular element spacing	General
--spacing-lg	24px	Large spacing for block spacing	General
--spacing-xl	32px	Extra large spacing for large block spacing	General
--font-size-xs	12px	Extra small font for auxiliary text	General
--font-size-sm	14px	Small font for body content	General
--font-size-md	16px	Medium font for titles	General
--font-size-lg	18px	Large font for large titles	General
--font-size-xl	20px	Extra large font for page titles	General
--shadow-sm	0 1px 2px rgba(0, 0, 0, 0.05)	Small shadow for card hover	General
--shadow-md	0 4px 6px -1px rgba(0, 0, 0, 0.1)	Medium shadow for modal boxes	General
--shadow-lg	0 10px 15px -3px rgba(0, 0, 0, 0.1)	Large shadow for dropdown menus	General
--shadow-xl	0 20px 25px -5px rgba(0, 0, 0, 0.1)	Extra large shadow for large components	General
--bg-primary	#ffffff	Primary background color	Light theme
--bg-secondary	#f5f7fa	Secondary background color	Light theme
--bg-tertiary	#f0f2f5	Tertiary background color	Light theme
--bg-card	#ffffff	Card background color	Light theme
--bg-hover	#f5f7fa	Hover background color	Light theme
--bg-active	#ecf5ff	Active state background color	Light theme
--text-primary	#303133	Primary text color	Light theme
--text-secondary	#606266	Secondary text color	Light theme
--text-tertiary	#909399	Tertiary text color	Light theme
--text-disabled	#c0c4cc	Disabled text color	Light theme
--border-color	#dcdfe6	Border color	Light theme
--border-light	#e4e7ed	Light border	Light theme
--border-dark	#c0c4cc	Dark border	Light theme
--color-primary	#409eff	Primary color	General
--color-success	#67c23a	Success color	General
--color-warning	#e6a23c	Warning color	General
--color-danger	#f56c6c	Danger color	General
--color-info	#909399	Info color	General
--shadow-color	rgba(0, 0, 0, 0.1)	Shadow color	Light theme
--shadow-color-dark	rgba(0, 0, 0, 0.2)	Dark shadow	Light theme
--mask-color	rgba(0, 0, 0, 0.8)	Mask color	General
--mask-color-light	rgba(0, 0, 0, 0.3)	Light mask	General
--striped-bg	rgba(255, 255, 255, 0.02)	Striped background	Light theme
--loading-gradient	linear-gradient(90deg, transparent, rgba(255, 255, 255, 0.4), transparent)	Loading animation gradient	Light theme
--bg-primary	#141414	Primary background color	Dark theme
--bg-secondary	#1f1f1f	Secondary background color	Dark theme
--bg-tertiary	#262626	Tertiary background color	Dark theme
--bg-card	#1f1f1f	Card background color	Dark theme
--bg-hover	#2a2a2a	Hover background color	Dark theme
--bg-active	#2a2a2a	Active state background color	Dark theme
--text-primary	#e5e5e5	Primary text color	Dark theme
--text-secondary	#a3a3a3	Secondary text color	Dark theme
--text-tertiary	#737373	Tertiary text color	Dark theme
--text-disabled	#525252	Disabled text color	Dark theme
--border-color	#404040	Border color	Dark theme
--border-light	#525252	Light border	Dark theme
--border-dark	#303030	Dark border	Dark theme
--shadow-color	rgba(0, 0, 0, 0.3)	Shadow color	Dark theme
--shadow-color-dark	rgba(0, 0, 0, 0.5)	Dark shadow	Dark theme
--transition-theme	0.3s ease	Theme switching transition time	General
--transition-fast	0.15s ease	Fast transition animation	General
--transition-slow	0.5s ease	Slow transition animation	General
--bg-gradient-start	#f5f7fa	Gradient background start color	Light theme
--bg-gradient-end	#c3cfe2	Gradient background end color	Light theme
--card-shadow	0 4px 6px -1px rgba(0, 0, 0, 0.1)	Card shadow	Light theme
--primary-color	#409eff	Primary color	General
--bg-gradient-start	#1f1f1f	Gradient background start color	Dark theme
--bg-gradient-end	#2a2a2a	Gradient background end color	Dark theme
--card-shadow	0 4px 6px -1px rgba(0, 0, 0, 0.3)	Card shadow	Dark theme

Variable Usage Examples

// Using CSS variables
.component {
  background-color: var(--bg-primary);
  color: var(--text-primary);
  border: 1px solid var(--border-color);
  border-radius: var(--global-btn-radius);
  padding: var(--spacing-md);
  box-shadow: var(--shadow-sm);
  transition: all var(--transition-fast);
}

// Responsive spacing
.responsive-spacing {
  padding: var(--spacing-sm);
  
  @media (min-width: 768px) {
    padding: var(--spacing-md);
  }
  
  @media (min-width: 1024px) {
    padding: var(--spacing-lg);
  }
}

2. Tailwind CSS Integration

The framework integrates Tailwind CSS, providing atomic CSS class names:

// Tailwind configuration extensions
tailwind.config.js defines:
- Color extensions: primary, success, warning, etc.
- Animation configuration: fade, slide, and other transition effects
- Shadow system: sm, md, lg, etc. shadow levels
- Responsive breakpoints: sm, md, lg, xl, 2xl

3. Responsive Design

Adopts a mobile-first responsive strategy:

// Breakpoint definitions
@screen-sm: 640px;
@screen-md: 768px;
@screen-lg: 1024px;
@screen-xl: 1280px;
@screen-2xl: 1536px;

// Responsive utility classes
.responsive-grid {
  display: grid;
  grid-template-columns: 1fr;
  
  @media (min-width: @screen-md) {
    grid-template-columns: repeat(2, 1fr);
  }
  
  @media (min-width: @screen-lg) {
    grid-template-columns: repeat(3, 1fr);
  }
}

Business Module Style Development Example (Product Module)

1. Page Layout Structure

The product management page adopts a modular layout design:

<template>
  <div class="product-container query-container">
    <!-- Filter condition area -->
    <el-card class="filter-container">
      <!-- Filter form content -->
    </el-card>

    <!-- Data display area -->
    <el-card class="table-container">
      <!-- Desktop table view -->
      <div v-if="!isMobile" class="desktop-view">
        <!-- Table component -->
      </div>

      <!-- Mobile card view -->
      <div v-else class="mobile-view">
        <!-- Card layout -->
      </div>
    </el-card>
  </div>
</template>

2. Responsive Adaptation Implementation

The product page implements complete responsive adaptation:

Desktop Layout:

• Uses Element Plus table component to display data
• Fixed column width and header alignment optimization
• Pagination component displayed at bottom

Mobile Adaptation:

• Card layout replaces tables
• Filter conditions can be collapsed
• Touch-friendly operation buttons
• Pull-up load more mechanism

3. Style Class Name Conventions

The product module adopts BEM naming convention:

// Container class names
.product-container {
  // Page container styles
}

.query-container {
  // Query area styles
}

.filter-container {
  // Filter condition container
}

.table-container {
  // Table container styles
}

// Mobile-specific styles
.mobile-view {
  .mobile-cards-container {
    // Card container
  }
  
  .mobile-card {
    // Single card
    .card-header { /* Card header */ }
    .card-content { /* Card content */ }
    .card-actions { /* Operation area */ }
  }
}

4. Dynamic Style Processing

The product page dynamically adjusts styles based on device type:

<template>
  <el-form
    :inline="!isMobile"
    :label-position="isMobile ? 'top' : 'left'"
    :label-width="isMobile ? '80px' : '100px'"
  >
    <el-input
      :style="{ width: isMobile ? '100%' : '160px' }"
      :size="isMobile ? 'small' : 'default'"
    />
  </el-form>
</template>

Style Customization Guide

1. Theme Color Customization

Modify CSS variables to customize theme colors:

// Modify in variables.module.less
:root {
  --color-primary: #your-primary-color;
  --color-success: #your-success-color;
  // ...other color variables
}

2. Component Style Overrides

Override Element Plus component styles through CSS selectors:

// Override table styles
.el-table {
  .el-table__header {
    th {
      background-color: var(--bg-color-secondary);
    }
  }
}

3. Responsive Breakpoint Customization

Modify responsive breakpoints in Tailwind configuration:

// tailwind.config.js
module.exports = {
  theme: {
    screens: {
      'sm': '640px',
      'md': '768px',
      'lg': '1024px',
      'xl': '1280px',
      '2xl': '1536px',
    }
  }
}

Best Practices

1. Style Organization Principles

• Modularity: Organize style files by functional modules
• Reusability: Extract common styles as utility classes
• Maintainability: Use CSS variables and preprocessors
• Performance Optimization: Avoid deep nested selectors

2. Responsive Design Recommendations

• Mobile-first design strategy
• Use relative units (rem, em)
• Set reasonable breakpoint thresholds
• Test multi-device compatibility

3. Theme Switching Implementation

The framework supports light/dark theme switching by modifying the data-theme attribute:

// Switch theme
document.documentElement.setAttribute('data-theme', 'dark');

Common Questions

1. Style Overrides Not Working

Ensure style file loading order is correct, custom styles should load after framework styles.

2. Mobile Adaptation Issues

Use the responsive utility classes and breakpoint system provided by the framework, avoid hardcoding dimensions.

3. Theme Switching Abnormalities

Check if CSS variable definitions are complete, ensure both light and dark theme variables have corresponding values.

Summary

The VJSP Vue3 framework's style system provides a complete solution, combining modern CSS technology and best practices. Through CSS variables, Tailwind CSS, and modular organization, developers can efficiently perform style customization and business development.