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

   bash
   1yarn 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:

  json
  1{
  2  "codeSyntax": {
  3    "WEB": "var(--uui-control-border-focus)"
  4  }
  5}

  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:

json
1{
2  "id": "core/controls/control-bg",
3  "type": "COLOR",
4  "cssVar": "--uui-control-bg",
5  "valueByTheme": {
6    "Loveship-Light": {
7      "value": "#FFFFFF",
8      "valueChain": {
9        "alias": [
10          { "id": "core/surfaces/surface-main", "cssVar": "--uui-surface-main" }
11        ]
12      }
13    }
14  }
15}

External Themes

Connect themes hosted outside the UUI repository.

Setup

1. Add theme URLs to localStorage:

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

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

Theme Manifest Structure

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

typescript
1interface IThemeManifest {
2    id: string;                    // Unique theme identifier
3    name: string;                  // Display name
4    css: string[];                 // Array of CSS file URLs
5    settings?: string | null;      // Optional settings URL
6    propsOverride?: {              // Optional component prop overrides
7        [typeRef: string]: {
8            [propName: string]: IThemeManifestPropOverride
9        }
10    };
11}

Example manifest:

json
1{
2  "id": "custom-theme",
3  "name": "Custom Theme",
4  "css": [
5    "https://cdn.example.com/theme-1/styles.css"
6  ],
7  "settings": "https://cdn.example.com/theme-1/settings.json"
8}

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:

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:

scss
1// Component.module.scss
2.root {
3    background-color: var(--uui-control-bg);
4    border-color: var(--uui-control-border);
5    color: var(--uui-text-primary);
6}

Theme Settings

Components can access theme settings via the settings object:

typescript
1import { settings } from '../../settings';
2
3// Access theme-specific icons, sizes, etc.
4const icon = settings.button.icons.dropdownIcon;
5const defaultSize = settings.button.sizes.default;

Commands

Generate theme tokens:

bash
1yarn generate-theme-tokens

Process icons (if updating theme icons):

bash
1yarn 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/