@TechUI/Themes Introduction

TechUI Themes is the visual soul of the TechUI component library.

Unlike traditional theme solutions that rely solely on CSS preprocessor (Less/Sass) variables, TechUI adopts a "Data-Driven" design pattern. Themes are defined as standard JavaScript data structures, enabling TechUI to break through DOM limitations and achieve full-stack theme coverage for Canvas, ECharts, and even WebGL scenarios.

One-sentence summary: One set of data, dual-channel distribution (CSS + JS), and zero-compilation runtime switching.

Dual-Channel Rendering

The TechUI theme system distributes configurations through TuiProvider to two rendering channels, ensuring visual consistency across all parts of the application.

Channel A: CSS Variable System (The DOM World)

The system automatically flattens the JS theme tree and generates CSS custom properties (CSS Variables), which are injected into the document root.

• Conversion Rule: primary.base -> --primary-base.
• Use Cases: All Vue components, layout containers, and HTML elements.
• Advantages: Utilizes native browser rendering capabilities for zero performance overhead.

Channel B: JS Reactive State (The Canvas World)

The system mounts the complete theme object into a global reactive state $tState.themePalette.

• Use Cases: ECharts charts, Three.js scenes, OpenLayers maps, and other Canvas elements that cannot read CSS variables.
• Advantages: Solves the pain point where traditional CSS theme solutions cannot reach inside Canvas, allowing chart colors to change automatically with the theme.

Built-in Themes

Currently, the official library provides three meticulously tuned standard themes:

Theme ID	Name	Description
lightBlue	Light Blue (Default)	Bright and fresh, suitable for most B-end data management backends.
darkBlue	Dark Blue	Professional and modern, suitable for command centers and data dashboard scenarios.
darkBlack	Deep Black	Elegant and mysterious with high contrast, suitable for night mode or dark-style applications.

Import and Activation

In TechUI, themes are loaded on demand. You must explicitly import the themes you wish to use in the application entry file (e.g., main.ts).

Importing Themes

// main.ts

// Import light theme (Recommended/Required as a fallback)
import "@techui/themes/lightBlue";

// Import dark theme (Optional, switchable after importing)
import "@techui/themes/darkBlue";

Single/Multi-Theme Strategy

The system automatically detects the number of registered themes:

• Single Theme Mode: If only lightBlue is imported, the global theme switcher is automatically hidden.
• Multi-Theme Mode: If multiple themes are imported, users can switch between them in real-time via the control panel or the <TuiThemeToggle> component without refreshing the page.

Development Guide

Calling in CSS / Less

Use CSS variables following the flattened naming convention.

.my-card {
  /* Format: --category-property */
  background: var(--common-bg);
  border: 1px solid var(--primary-base);
  color: var(--font-primary);
}

Calling in JavaScript / Vue

Use the global utility function $tc (Get Theme Color) or access the Store directly.

// Method A: Using the utility function (Recommended)
const color = $tc('primary.base');

// Method B: Using within ECharts configuration
import { computed } from 'vue';
import { useStore } from 'vuex'; // or pinia

const option = computed(() => {
  // Get current theme palette
  const palette = $tState.themePalette;
  return {
    backgroundColor: palette.common.bg, // Dynamically responds to theme switching
    series: [{
      itemStyle: { color: palette.primary.base }
    }]
  };
});

Theme Customization Rules

If you need to develop custom themes or extend existing ones, you must follow these strict specifications to ensure system compatibility.

Naming Conventions

• camelCase: Used for most properties (e.g., primary, base).
• Snake Suffix: Used only for specific states:
• _hov (hover), _act (active), _dis (disabled).
• _op1 ~ _op9 (opacity levels).

Common Abbreviations

To shorten CSS variable lengths, the following abbreviations are used:

• background -> bg
• border -> bd
• fontColor -> fc
• highlight -> hlite

Auto Opacity Variants

The system automatically generates opacity variants for core colors like primary, success, and danger for their base, bg, and bd properties; you do not need to define these manually.

• Definition: primary: { base: '#007bff' }.
• Auto-generated: --primary-base_op1 (10% opacity), --primary-base_op5 (50% opacity).

Registering Custom Themes

You can use the tTheme.register API to inject a custom-developed theme into the system.

import { tTheme } from "@techui/utils";
import { $c } from "@techui/colors";

tTheme.register({
  value: "myLuxuryGold",    // Unique ID
  scheme: "dark",           // Base color scheme (light/dark)
  colors: [$c.orl5, "#000"],// Preview color blocks
  data: {
    common: { bg: "#000000", bd: "#FFD700" }, // Follow full Schema
    primary: { base: "#FFD700", ... },
    // ... other required fields
  }
});