Development Usage

The TechUI theme system distributes configuration data as CSS variables and JavaScript reactive states via TuiProvider. This means you can seamlessly use the same set of semantic colors in stylesheets, Vue templates, logic code, and even Canvas contexts.

Using in CSS/Less

This is the most common approach. Once a theme is registered, the system automatically flattens the JS objects into CSS variables (Custom Properties) and injects them into the :root scope.

Standard Variable Mapping

Variable names follow the Kebab Case rule, connecting the hierarchical paths of the JSON object with hyphens.

• common.bg -> var(--common-bg)
• primary.base -> var(--primary-base)
• button.bg_hov -> var(--button-bg-hov)
• scifi.header.hlite -> var(--scifi-header-hlite)

Opacity Variants

For development convenience, TechUI automatically detects specific attributes during theme initialization and generates opacity derivatives ranging from 10% to 90%.

Naming Convention: Append _op + 1~9 (representing 10%–90% opacity) to the original variable name.

Examples:

• var(--primary-base): Original color (100% opaque)
• var(--primary-base_op1): 10% opacity
• var(--primary-base_op5): 50% opacity
• var(--primary-base_op9): 90% opacity

Supported Range: To avoid an explosion in the number of CSS variables, the system only generates opacity versions for high-frequency categories and attributes.

• Supported Categories: common, button, input, tone, primary, success, info, warning, danger, emphasis
• Supported Keys: bg, bd, weakest, weaker, weak, base, strong, stronger, strongest

Styling Example

In a Vue component's <style> block, you should always use var(--...) instead of hard-coding color values.

<style lang="less" scoped>
.my-card {
  /* Use primary color with 10% opacity as background */
  background-color: var(--primary-base_op1);
  /* Use common layer background */
  background-color: var(--common-bg-layer);
  
  /* Use common border color */
  border: 1px solid var(--common-bd);
  /* Use common background with 50% opacity as border */
  border: 1px solid var(--common-bg_op5);
  /* Use primary color for text */
  color: var(--primary-base);

  .title {
    /* Use hierarchical font color */
    color: var(--font-strong);
  }

  &:hover {
    /* Use predefined interaction state color */
    border-color: var(--primary-strong);
    box-shadow: 0 0 10px var(--scifi-hlite); /* Reference sci-fi glow color */
  }
}
</style>

Tip: The greatest advantage of using CSS variables is that when a user switches themes (e.g., from Light to Dark), the browser automatically repaints all areas referencing the variables without any JS intervention, ensuring high performance.

Using in JavaScript

In certain scenarios, you may need to retrieve color values within your logic, such as:

• Drawing with Canvas / WebGL.
• Configuring third-party libraries like ECharts / Three.js / Cesium.
• Dynamically calculating inline styles.

TechUI provides a global injection function $tc (Theme Color) to simplify this process.

$tc Function Details

The $tc function supports two retrieval modes: static values and reactive objects.

Function Signature: $tc(path: String, isComputed: Boolean = false): String | ComputedRef<String>

1. Retrieve Static Value (One-time)

When isComputed is false (default), it returns the color string at the current moment.

import { inject, onMounted } from 'vue';

const { $tc } = inject('$global');

const initCanvas = () => {
  const ctx = canvas.getContext('2d');
  
  // Get current canvas background color
  // Example return: "#ffffff" or "rgba(0,0,0,0.5)"
  ctx.fillStyle = $tc('common.bg'); 
  ctx.fillRect(0, 0, 100, 100);
};

Note: Colors retrieved this way are non-reactive. If the user switches the theme, the Canvas will not redraw automatically; you must listen for theme changes and refresh manually.

2. Retrieve Reactive Object (Recommended)

When isComputed is true, it returns a Vue ComputedRef object. When the global theme changes, the value of this object updates automatically.

This is highly useful in Vue computed properties or watch listeners.

import { inject, computed } from 'vue';

const { $tc } = inject('$global');

// Create a reactive style object
const cardStyle = computed(() => {
  return {
    // Must use .value to get the value of the computed property
    backgroundColor: $tc('primary.weak', true).value,
    border: `1px solid ${$tc('primary.base', true).value}`
  };
});

Handling Color Opacity

Unlike CSS, which uses auto-generated _op variables, we recommend using the $c utility function for opacity processing in JavaScript to maintain logical flexibility and reduce memory usage.

$c (TechUI Colors) provides powerful color manipulation capabilities.

Example Code:

import { inject, computed } from 'vue';

// Inject global services and color tools
const { $tc, $c } = inject('$global');

// Scenario 1: Get color string with opacity (Common for ECharts/Canvas)
const initChart = () => {
  // Get primary.base and apply 30% opacity
  // $c.fade(colorValue, opacity 0-1)
  const areaColor = $c.fade($tc('primary.base'), 0.3); 
  
  console.log(areaColor); // Output: "rgba(24, 144, 255, 0.3)"
};

// Scenario 2: Dynamic calculation in Computed
const tagStyle = computed(() => {
  // Get reactive theme color
  const baseColor = $tc('success.base', true).value;
  
  return {
    color: baseColor,
    // Dynamically generate background: use success color at 10% opacity
    backgroundColor: $c.fade(baseColor, 0.1),
    border: `1px solid ${$c.fade(baseColor, 0.2)}`
  };
});

Listening to Theme Changes

For libraries like ECharts or Mapbox that require explicit calls to setOption or update methods, it is recommended to use watch.

import { inject, watch, ref } from 'vue';

const { $gTheme, $tc } = inject('$global');
const chartInstance = null;

// Watch for changes in theme name ($gTheme)
watch($gTheme, () => {
  if (chartInstance) {
    // Retrieve the latest color value
    const newColor = $tc('chart.map.bg');
    
    // Update the third-party instance
    chartInstance.setOption({
      backgroundColor: newColor
    });
  }
});

Best Practices Summary

1. CSS First: Whenever a style can be solved with CSS, use var(--...). This is the most performant and maintainable method.
2. Avoid Hard-coding: Never write #fff or rgba(0,0,0,0.5) in your code. If a color is missing from the existing theme, extend the custom theme instead of hard-coding it in the component.
3. Semantic Alignment:
   • Use common.bg_xxx for backgrounds.
   • Use font.xxx for text.
   • Use button.xxx for buttons.
   • Do not mix semantics (e.g., using button.bg for text color), as this may cause "white text on white background" bugs in inverted (Dark Mode) themes.
4. Use $tc for Configuration: Besides colors, themes may contain non-color configurations (such as opacity or line widths in scifi), which can also be retrieved using $tc\.