OpenParable
Skip to content
← Back to skills

Uui Themes

Design
uui-themes

Uui Themes is an Agent Skill for design published in the epam/UUI repository on GitHub: a SKILL.md instruction file an AI agent can load to do this task.

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.

View on GitHub ↗
QUICK START

How to use this skill

Bring this guide into your coding agent with a prompt tailored to the tool you use.

  1. Open your project in Codex.
  2. Copy and paste the prompt below.
  3. Review files and risks before approving any action.
Prompt to paste
Inspect the Agent Skill at https://github.com/epam/UUI/blob/HEAD/.cursor/skills/themes/SKILL.md and all supporting files. Report provenance, permissions, scripts, dependencies, and security risks. Propose an exact installation into .agents/skills/uui-themes, but wait for my approval before writing files or running scripts.

Copying this prompt does not install or run the skill. Review third-party files before use.

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:

PatternPurposeExamples
uui-color-{value}Text/icon coloruui-color-primary, uui-color-neutral, uui-color-error
uui-size-{value}Component sizeuui-size-24, uui-size-36, uui-size-48
uui-fill-{value}Button fill styleuui-fill-solid, uui-fill-outline, uui-fill-ghost
uui-{component}Component rootuui-button, uui-tab-button, uui-input-box
uui-{component}_{part}Component partuui-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/