@gravity-ui/uikit-themer

中文文档
2.1.0发布于 2026/10/22MITTypeScriptES Module近 30 天下载 1.2万

A library for manipulating themes for the @gravity-ui/uikit library. Allows you to parse existing themes and generate new ones using a convenient API.

原始使用文档
文档目录17 节
  1. Features
  2. Installation
  3. Basic Usage
  4. Theme Generation
  5. Parsing Existing Theme
  6. Converting Between Formats
  7. API Reference
  8. Default Theme
  9. Color Utilities
  10. Typography
  11. Borders
  12. Working with JSON Themes
  13. Core Types
  14. Examples
  15. Creating a Custom Theme
  16. Parsing and Modifying Existing Theme
  17. Working with Specific Theme Parts

@gravity-ui/uikit-themer · npm package CI

A library for manipulating themes for the @gravity-ui/uikit library. Allows you to parse existing themes and generate new ones using a convenient API.

Features

  • 🎨 Theme Generation - create new themes for Gravity UI
  • 📖 Theme Parsing - analyze existing themes in CSS and JSON formats
  • 🔄 Conversion - transform between CSS and JSON formats
  • 🎨 Color Management - work with private and utility colors
  • ✍️ Typography - configure fonts and text styles
  • 📏 Borders - manage border radius

Installation

npm install @gravity-ui/uikit-themer

Basic Usage

Theme Generation

Theme generation functions require a complete theme object. For convenience, you can use DEFAULT_THEME and override the necessary parameters.

⚠️ Note: When modifying base colors, use updateBaseColor instead of direct manipulation to ensure private colors are properly regenerated.

import { generateCSS, generateJSON, updateBaseColor, DEFAULT_THEME } from '@gravity-ui/uikit-themer';

// Recommended: Use updateBaseColor for modifying colors
const themeWithCustomColors = updateBaseColor({
  theme: DEFAULT_THEME,
  colorToken: 'brand',
  value: {
    dark: '#007AFF',
    light: '#007AFF'
  }
});

// Generate CSS theme
const cssTheme = generateCSS({
  theme: themeWithCustomColors
});

// Generate JSON theme with typography changes
const jsonTheme = generateJSON({
  theme: {
    ...DEFAULT_THEME,
    typography: {
      ...DEFAULT_THEME.typography,
      fontFamilies: {
        ...DEFAULT_THEME.typography.fontFamilies,
        sans: {
          mainFont: 'SF Pro Text',
          fallbackFonts: ['Arial'],
        },
      }
    }
  }
});

Parsing Existing Theme

import { parseCSS, parseJSON } from '@gravity-ui/uikit-themer';

// Parse CSS theme to internal GravityTheme
const parsedCssTheme = parseCSS(cssString);

// Parse JSON theme to internal GravityTheme
const parsedJsonTheme = parseJSON(jsonString);

Converting Between Formats

import { convertCSStoJSON, convertJSONtoCSS } from '@gravity-ui/uikit-themer';

// Convert CSS to JSON
const jsonFromCss = convertCSStoJSON(cssTheme);

// Convert JSON to CSS
const cssFromJson = convertJSONtoCSS(jsonTheme);

API Reference

Default Theme

The library provides a DEFAULT_THEME constant that contains all the default values for a complete Gravity UI theme. This is the recommended starting point for creating custom themes.

⚠️ Important: When modifying baseColors, use the updateBaseColor function instead of direct manipulation to ensure private colors are properly regenerated.

import { DEFAULT_THEME, updateBaseColor } from '@gravity-ui/uikit-themer';
import type { GravityTheme } from '@gravity-ui/uikit-themer';

// Recommended: Use updateBaseColor for base color changes
const customTheme: GravityTheme = updateBaseColor({
  theme: DEFAULT_THEME,
  colorToken: 'brand',
  value: {
    dark: '#FF3B30',
    light: '#FF3B30'
  }
});

// For other theme parts, direct modification is fine
const themeWithCustomTypography: GravityTheme = {
  ...customTheme,
  typography: {
    ...customTheme.typography,
    // typography modifications...
  }
};

Color Utilities

import {
  isColorCssVariable,
  isUtilityColorCssVariable,
  isPrivateColorCssVariable,
  parsePrivateColorCssVariable,
  createPrivateColorCssVariable,
  createUtilityColorCssVariable,
  getUtilityColorTypeFromCssVariable,
  updateBaseColor
} from '@gravity-ui/uikit-themer';

// Check CSS variable type
const isColor = isColorCssVariable('--g-color-base-brand');
const isUtility = isUtilityColorCssVariable('--g-color-text-primary');
const isPrivate = isPrivateColorCssVariable('--g-private-color-red-500');

// Parse private color variable
const {mainColorToken, privateColorToken} = parsePrivateColorCssVariable('--g-private-color-red-500');

// Create color variables
createPrivateColorCssVariable('brand', '200-solid') === '--g-color-private-brand-200-solid'
createUtilityColorCssVariable('text-link-visited') === '--g-color-text-link-visited'

// Get utility color type
getUtilityColorTypeFromCssVariable('--g-color-text-link-hover') === 'text-link-hover'

Updating Base Colors

⚠️ Important: Always use updateBaseColor when modifying base colors to ensure proper regeneration of private colors.

import { updateBaseColor, DEFAULT_THEME } from '@gravity-ui/uikit-themer';

// Update base color for a single theme variant
const updatedTheme = updateBaseColor({
  theme: DEFAULT_THEME,
  colorToken: 'brand',
  themeVariant: 'light',
  value: '#007AFF',
});

// Update base color for both theme variants
const updatedBothThemes = updateBaseColor({
  theme: DEFAULT_THEME,
  colorToken: 'brand',
  value: {
    light: '#007AFF',
    dark: '#0056CC',
  },
});

// Create a new color token
const newColorTheme = updateBaseColor({
  theme: DEFAULT_THEME,
  colorToken: 'custom-accent',
  value: {
    light: '#FF6B35',
    dark: '#FF8C5A',
  },
});

The updateBaseColor function:

  • Updates the base color in baseColors
  • Automatically regenerates corresponding private colors
  • Maintains theme immutability (returns a new theme object)
  • Handles both existing and new color tokens
  • Supports updating single theme variant or both variants simultaneously

Why use updateBaseColor?

Direct modification of baseColors without regenerating private colors can lead to inconsistent themes. Private colors are calculated from base colors and are used throughout the UI components. The updateBaseColor function ensures that:

  1. Base colors are properly updated
  2. Private colors are regenerated with the new base color
  3. The theme remains internally consistent
  4. All color dependencies are maintained

Typography

Working with fonts and text styles.

import {
  isTextCssVariable,
  isFontCssVariable,
  createFontCssVariable,
  createTextCssVariable,
  getKeyFromCssFontVariable,
  parseTextCssVariable,
  generateCssFontFamily,
  TEXT_VARIANTS,
  TEXT_GROUP_PROPERTIES,
  TEXT_VARIANT_PROPERTIES
} from '@gravity-ui/uikit-themer';
import type {
  TypographyOptions,
  TextGroup,
  TextVariant,
  FontOptions
} from '@gravity-ui/uikit-themer';

// Check typography CSS variables
const isText = isTextCssVariable('--g-text-body-1-font-size');
const isFont = isFontCssVariable('--g-font-family-sans');

// Create typography variables
createFontCssVariable('additional') === '--g-font-family-additional';

createTextCssVariable({
    variant: 'body-1',
    property: 'font-size'
}) === '--g-text-body-1-font-size'

// Utilities
getKeyFromCssFontVariable('--g-font-family-sans') === 'sans'

parseTextCssVariable('--g-text-body-1-font-size') === {
    "group": "body",
    "variant": "body-1",
    "property": "font-size"
}

generateCssFontFamily({
    "mainFont": "SF Pro Text",
    "fallbackFonts": ["Arial", "sans-serif"]
}) === "'SF Pro Text', 'Arial', 'sans-serif'"

// Constants
console.log(TEXT_VARIANTS); // All available text variants
console.log(TEXT_GROUP_PROPERTIES); // Text group properties
console.log(TEXT_VARIANT_PROPERTIES); // Text variant properties

Typography Types:

  • TypographyOptions - typography options
  • TextGroup - text group (body, header, display, etc.)
  • TextVariant - text variant
  • TextBodyVariant, TextCaptionVariant, TextHeaderVariant - specific variants
  • FontOptions - font options

Borders

Working with border radius.

import {
  isBorderRadiusCssVariable,
  createBorderRadiusCssVariable,
  BORDER_SIZES
} from '@gravity-ui/uikit-themer';
import type { BorderSize } from '@gravity-ui/uikit-themer';

// Check border radius variable
const isBorderRadius = isBorderRadiusCssVariable('--g-border-radius-m');

// Create border radius variable
const borderVar = createBorderRadiusCssVariable('m');

// Available border sizes
console.log(BORDER_SIZES); // ['xs', 's', 'm', 'l', 'xl']

Working with JSON Themes

import {
  generateJSON,
  parseJSON,
  isValueWithReference,
  isThemizedValueWithReference
} from '@gravity-ui/uikit-themer';
import type {
  JsonTheme,
  ThemizedValueWithReference,
  ValueWithReference
} from '@gravity-ui/uikit-themer';

// Check values with references
const hasRef = isValueWithReference(value);
const hasThemizedRef = isThemizedValueWithReference(value);

JSON Types:

  • JsonTheme - JSON representation of theme
  • ThemizedValueWithReference - value with themized reference
  • ValueWithReference - value with reference

Core Types

import type {
  GravityTheme,
  PrivateColorOptions,
  PrivateColors,
  BaseColors,
  ThemizedColorOptions,
  ColorOptions,
  Theme
} from '@gravity-ui/uikit-themer';
  • GravityTheme - main internal Gravity UI theme type
  • PrivateColorOptions - private color options
  • PrivateColors - private colors
  • BaseColors - base colors
  • ThemizedColorOptions - themized color options
  • ColorOptions - general color options
  • Theme - universal theme type (light | dark)

Examples

Creating a Custom Theme

import { generateCSS, updateBaseColor, DEFAULT_THEME } from '@gravity-ui/uikit-themer';

// Recommended: Use updateBaseColor to modify base colors
const themeWithCustomBrand = updateBaseColor({
  theme: DEFAULT_THEME,
  colorToken: 'brand',
  value: {
    dark: '#007AFF',
    light: '#007AFF'
  }
});

const customTheme = generateCSS({
  theme: {
    ...themeWithCustomBrand,
    typography: {
      ...themeWithCustomBrand.typography,
      fontFamilies: {
        ...themeWithCustomBrand.typography.fontFamilies,
        sans: {
          mainFont: 'SF Pro Text',
          fallbackFonts: ['Arial'],
        },
      },
      variants: {
        ...themeWithCustomBrand.typography.variants,
        'body-1': {
          'font-size': '13px',
          'line-height': '18px',
        }
      }
    }
  }
});

Parsing and Modifying Existing Theme

import { parseCSS, generateCSS, updateBaseColor } from '@gravity-ui/uikit-themer';

// Parse existing theme
const existingTheme = parseCSS(cssString);

// Recommended: Use updateBaseColor to modify brand color
const modifiedTheme = updateBaseColor({
  theme: existingTheme,
  colorToken: 'brand',
  value: {
    dark: '#FF3B30',
    light: '#FF3B30'
  }
});

// Generate new CSS
const newCSS = generateCSS({theme: modifiedTheme});

Working with Specific Theme Parts

import { generateCSS, DEFAULT_THEME } from '@gravity-ui/uikit-themer';

// Override only typography
const typographyOnlyTheme = generateCSS({
  theme: {
    ...DEFAULT_THEME,
    typography: {
      ...DEFAULT_THEME.typography,
      fontFamilies: {
        ...DEFAULT_THEME.typography.fontFamilies,
        'custom-font': {
          mainFont: 'SF Pro Text',
          fallbackFonts: ['Arial'],
        },
      },
      groups: {
        ...DEFAULT_THEME.typography.groups,
        body: {
          'font-family': 'custom-font',
          'font-weight': 400,
        },
      }
    }
  }
});

版本与发布记录

@gravity-ui/uikit-themer 共发布 16 个版本,首次发布于 2025/06/02;过去 12 个月发布了 8 个版本。

版本发布日期距今
2.1.0latest2026/10/2225 天前
2.0.02026/10/081 个月前
1.8.12026/07/164 个月前
1.8.02026/04/226 个月前
1.7.02025/12/1611 个月前
1.6.12025/12/0811 个月前

关于 @gravity-ui/uikit-themer 的常见问题

@gravity-ui/uikit-themer 是什么?

A library for manipulating themes for the @gravity-ui/uikit library. Allows you to parse existing themes and generate new ones using a convenient API.

如何安装 @gravity-ui/uikit-themer?

在项目目录运行 npm install @gravity-ui/uikit-themer,或使用 pnpm add / yarn add / bun add。

@gravity-ui/uikit-themer 支持 TypeScript 吗?

支持。包内自带 TypeScript 类型声明(package.json 声明了 types 入口),安装后即可获得类型提示,无需再安装 @types 包。

@gravity-ui/uikit-themer 支持 ESM 还是 CommonJS?

以 ES Module 形式发布,推荐使用 import 引入。在 CommonJS 项目中,Node.js 20.19+ / 22.12+ 可以直接 require() 不含顶层 await 的 ES Module,更早的版本需要改用动态 import()。

@gravity-ui/uikit-themer 可以商用吗?

@gravity-ui/uikit-themer 使用 MIT 许可。宽松许可:允许商业使用、修改和再分发,通常只需在分发时保留原版权与许可声明。以上为概括,不构成法律意见,请以许可原文为准。

@gravity-ui/uikit-themer 的下载量有多少?

根据 npm 官方下载统计,@gravity-ui/uikit-themer 在 2026/10/17 – 2026/11/15 这 30 天内被下载 12,074 次,日均约 402 次。下载量会把 CI 构建、镜像同步和作为其他包依赖的安装一并计入,适合横向比较热度,不能直接等同于使用人数。

@gravity-ui/uikit-themer 还在维护吗?

最新版本 2.1.0 发布于 2026/10/22(25 天前);至今共发布 16 个版本,其中过去 12 个月发布了 8 个;首次发布于 2025/06/02。发布频率只是参考信号:功能稳定的工具可能很少需要更新,建议结合源码仓库的 issue 和提交记录判断。