Wix Theme Variables

A TypeScript library for working with Wix Theme System variables - providing structured access to CSS custom properties and theme definitions.

What are Wix Themes?

Wix Themes use a CSS custom property system that allows consistent styling across Wix sites. Each theme defines variables for colors, typography, spacing, and layout that components can reference. This library provides a typed interface to access and work with these theme variables.

Installation

npm install @wix/wix-theme-variables

API Methods

Core Functions

import { 
  getAllVariables, 
  getVariablesByType, 
  getVariablesByCategory,
  getVariableByName 
} from '@wix/wix-theme-variables';

// Get all theme variables
const allVars = getAllVariables();

// Get variables by type (with TypeScript autocomplete)
const colorVars = getVariablesByType('color');
const fontVars = getVariablesByType('fontSize');

// Get variables by category
const textStyles = getVariablesByCategory('textStyle');
const backgrounds = getVariablesByCategory('background');

// Find specific variable
const heading = getVariableByName('heading_1_font');

Lookup Functions

// Find by legacy CSS property name
const variable = getVariableByLegacyName('heading-1-font');

// Find by CSS custom property key
const variable = getVariableByVariableKey('--wst-heading-1-font');

// Get available types and categories
const types = getAllTypes();           // ['color', 'fontSize', 'fontFamily', ...]
const categories = getAllCategories(); // ['textStyle', 'background', 'border', ...]

Variable Structure

Each variable contains:

interface WixThemeVariable {
  name: string;           // 'heading_1_font'
  legacyName: string;     // 'heading-1-font' 
  variableKey: string;    // '--wst-heading-1-font'
  type: VariableType;     // 'font' | 'color' | 'fontSize' | ...
  category: VariableCategory; // 'textStyle' | 'background' | ...
  description?: string;   // Optional description
  complexity?: 'Simple' | 'Complex';
  reference?: string;     // Reference to other variables
}

Type Safety

The library provides full TypeScript support with autocomplete for:

• ✅ Variable types: 'color', 'fontSize', 'border', 'spacing', etc.
• ✅ Categories: 'textStyle', 'background', 'globalColor', etc.
• ✅ All function parameters and return types

Example Usage

import { getVariablesByType, getVariablesByCategory } from 'wix-theme-variables';

// Get all color variables for a color picker
const colorOptions = getVariablesByType('color');

// Get text styling variables for typography controls  
const textStyles = getVariablesByCategory('textStyle');

// Build CSS custom property references
const cssVars = colorOptions.map(v => v.variableKey);
// Result: ['--wst-base-1-color', '--wst-shade-1-color', ...]

Development

See DEVELOPMENT.md for development setup, linting, and contribution guidelines.

License

ISC