uui-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** ```bash 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: ```json { "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: ```json { "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:** ```javascript 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: ```typescript 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:** ```json { "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: ```scss // 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: ```typescript 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:** ```bash yarn generate-theme-tokens ``` **Process icons** (if updating theme icons): ```bash 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](../documentation/SKILL.md) (External Themes section) - Theme tokens output: `public/docs/figmaTokensGen/ThemeTokens.json` - SCSS mixins: `epam-assets/theme/variables/tokens/`