uui-themes

name	uui-themes
description	Helps work with UUI themes including generating theme tokens from Figma, working with skin packages, and connecting external themes. Use when generating theme tokens, working with loveship/electric/promo themes, or connecting external themes.

UUI Themes

UUI supports multiple themes (skins) and allows connecting external themes. Built-in themes include Loveship, Electric, and Promo.

Built-in Theme Packages

UUI includes three styled theme packages:

• @epam/loveship — Loveship theme (light and dark modes)
• @epam/electric — Electric theme (light and dark modes)
• @epam/promo — Promo theme

These are located in:

• loveship/ — Loveship theme package
• epam-electric/ — Electric theme package
• epam-promo/ — Promo theme package

Generating Theme Tokens from Figma

Theme tokens are generated from Figma JSON exports.

Process

1. Obtain Theme.json from UX design team

   • Request the most recent Theme.json file exported from Figma

2. Replace existing file

   • Place new Theme.json in public/docs/figmaTokensGen/Theme.json
   • Replace the existing file

3. Generate tokens

   yarn generate-theme-tokens
   

   Important: Run from UUI monorepo root!

Generated Files

The command generates:

• public/docs/figmaTokensGen/ThemeOutput.json — Original file with added CSS variable info:

  {
    "codeSyntax": {
      "WEB": "var(--uui-control-border-focus)"
    }
  }
  

  This file should be sent back to UX designers to import into Figma.

• public/docs/figmaTokensGen/ThemeTokens.json — Normalized tokens with inheritance hierarchy in minimalistic format. Used for:

  • Color palette documentation
  • Token tables in sandbox

• epam-assets/theme/variables/tokens/*.scss — Theme-specific SCSS mixins with token variables

Token Structure

Tokens include:

• Modes — Theme variants (e.g., Loveship-Light, Loveship-Dark, Promo, Electric-Light, Electric-Dark)
• Exposed tokens — CSS variables with values per theme
• Value chains — Token aliases and inheritance

Example token:

{
  "id": "core/controls/control-bg",
  "type": "COLOR",
  "cssVar": "--uui-control-bg",
  "valueByTheme": {
    "Loveship-Light": {
      "value": "#FFFFFF",
      "valueChain": {
        "alias": [
          { "id": "core/surfaces/surface-main", "cssVar": "--uui-surface-main" }
        ]
      }
    }
  }
}

External Themes

Connect themes hosted outside the UUI repository.

Setup

1. Add theme URLs to localStorage:

   localStorage.setItem('uui-custom-themes', JSON.stringify({
       customThemes: [
           "https://cdn.example.com/theme-1",
           "https://cdn.example.com/theme-2"
       ]
   }))
   

2. Theme URL must serve /theme-manifest.json

Theme Manifest Structure

The theme URL must serve a /theme-manifest.json endpoint with this structure:

interface IThemeManifest {
    id: string;                    // Unique theme identifier
    name: string;                  // Display name
    css: string[];                 // Array of CSS file URLs
    settings?: string | null;      // Optional settings URL
    propsOverride?: {              // Optional component prop overrides
        [typeRef: string]: {
            [propName: string]: IThemeManifestPropOverride
        }
    };
}

Example manifest:

{
  "id": "custom-theme",
  "name": "Custom Theme",
  "css": [
    "https://cdn.example.com/theme-1/styles.css"
  ],
  "settings": "https://cdn.example.com/theme-1/settings.json"
}

CSS Variables and uui-* Classes

CSS variables use --uui-* prefix:

• --uui-control-bg, --uui-control-border, --uui-text-primary, etc.
• Defined in theme token SCSS files. Follow existing token structure for consistency.

Global utility classes use uui-* prefix for themeable props. These are applied by components via applyMods:

Pattern	Purpose	Examples
uui-color-{value}	Text/icon color	uui-color-primary, uui-color-neutral, uui-color-error
uui-size-{value}	Component size	uui-size-24, uui-size-36, uui-size-48
uui-fill-{value}	Button fill style	uui-fill-solid, uui-fill-outline, uui-fill-ghost
uui-{component}	Component root	uui-button, uui-tab-button, uui-input-box
uui-{component}_{part}	Component part	uui-icon_button, uui-link_button

Skin packages (loveship, epam-electric, epam-promo) define styles for these classes. When adding new component mods, follow the same pattern so themes can style them.

Working with Theme Tokens in Components

Components access theme tokens via CSS variables:

// Component.module.scss
.root {
    background-color: var(--uui-control-bg);
    border-color: var(--uui-control-border);
    color: var(--uui-text-primary);
}

Theme Settings

Components can access theme settings via the settings object:

import { settings } from '../../settings';

// Access theme-specific icons, sizes, etc.
const icon = settings.button.icons.dropdownIcon;
const defaultSize = settings.button.sizes.default;

Commands

Generate theme tokens:

yarn generate-theme-tokens

Process icons (if updating theme icons):

yarn process-icons

Place icons in icons-source folder first.

References

• Theme tokens generation: uui-build/ts/themeTokens.md
• External themes: .cursor/skills/documentation/SKILL.md (External Themes section)
• Theme tokens output: public/docs/figmaTokensGen/ThemeTokens.json
• SCSS mixins: epam-assets/theme/variables/tokens/