@xsolla/xui-core

Design system foundation providing theming, context, design tokens, and shared utilities for the XUI toolkit.

Installation

npm install @xsolla/xui-core

Usage

import { XUIProvider, useDesignSystem } from '@xsolla/xui-core';

function App() {
  return (
    <XUIProvider initialMode="dark">
      <MyApp />
    </XUIProvider>
  );
}

function MyComponent() {
  const { theme, mode, setMode } = useDesignSystem();
  return <div style={{ color: theme.colors.content.primary }}>Hello</div>;
}

Per-component theme overrides with useResolvedTheme:

import { useResolvedTheme, ThemeOverrideProps } from '@xsolla/xui-core';

type MyWidgetProps = ThemeOverrideProps & { label: string };

function MyWidget({ label, themeMode, themeProductContext }: MyWidgetProps) {
  const { theme, mode } = useResolvedTheme({ themeMode, themeProductContext });
  return <div style={{ color: theme.colors.content.primary }}>{label}</div>;
}

// Usage — override theme per-instance without nesting providers
<MyWidget label="Global theme" />
<MyWidget label="Light override" themeMode="light" />

Available Theme Modes

| Mode | Theme | |------|-------| | "dark" | Pentagram Dark (default) | | "light" | Pentagram Light | | "ltg-dark" | LTG Dark | | "blueprints" | Blueprints |

Per-Component Overrides

Every component accepts themeMode and themeProductContext props to override the global provider:

<Button themeMode="light" themeProductContext="b2c">Override Both</Button>

For custom components, use useResolvedTheme instead of useDesignSystem.

Responsive Typography

By default, XUIProvider injects CSS custom properties (--xui-font-size-*, --xui-lh-*) with @media queries so text scales between mobile and desktop breakpoints. Pass responsive={false} to disable this — all components will use the fixed common/desktop values instead.

// Default — responsive scaling via CSS vars + @media
<XUIProvider>
  <App />
</XUIProvider>

// Opt-out — fixed sizes, no @media queries injected
<XUIProvider responsive={false}>
  <App />
</XUIProvider>

The responsive flag is also available from useDesignSystem() if a component needs to branch on it:

const { responsive } = useDesignSystem();

Exports

• XUIProvider — Root context provider; accepts initialMode (see theme modes above) and responsive (opt-out of responsive typography, defaults to true)
• useDesignSystem — Hook returning { theme, mode, setMode, responsive }; falls back to dark theme if no provider
• useResolvedTheme — Hook returning resolved theme with per-component overrides applied; same return shape as useDesignSystem
• ThemeOverrideProps — Type: { themeMode?: ThemeMode; themeProductContext?: ProductContext }
• themeConfig — Function returning the full theme object for a given ThemeMode
• useId — Stable unique ID hook; polyfills React.useId for React < 18
• ModalIdContext — Context holding the current modal's ID for portal-based components
• useModalId — Hook returning the current modal ID, or null if outside a modal
• breakpoints — Responsive breakpoints: { mobile: 0, desktop: 768 }
• responsiveTypographyScale — Raw responsive font-size and line-height data (13 steps × 2 device modes: common/mobile)
• SCALE_STEPS — Array of all scale step identifiers
• generateTypographyCSS — Returns the full CSS string for responsive typography custom properties
• cssVar — Helper to get CSS variable references: cssVar.fontSize("350") → "var(--xui-font-size-350)"
• TypographyStyleLoader — Component that injects responsive typography CSS (rendered automatically by XUIProvider)
• FontLoader — Component that injects the @font-face declarations for XUI fonts
• fontFacesCSS — Raw @font-face CSS string (for SSR or manual injection)
• ThemeMode — Type: "dark" | "light" | "ltg-dark" | "blueprints"
• ThemeColors — Type of the colour token object
• ProductContext — Type of the themeProductContext prop: "b2c" | "b2b"
• colors — Raw colour tokens for all themes
• spacing — Spacing scale (xs, s, m, l, xl)
• radius — Border-radius tokens (button, card, input, tag, avatar variants)
• shadow — Shadow tokens
• fonts — Font-family definitions
• isWeb / isNative / isIOS / isAndroid — Platform detection booleans

Per-Component Theme Override

Every component accepts optional themeMode and themeProductContext props to override the global theme on a per-instance basis, without nesting additional providers.

useResolvedTheme is the hook that powers this. It accepts an optional overrides object and returns the same { theme, mode, productContext } shape as useDesignSystem:

import { useResolvedTheme, ThemeOverrideProps } from '@xsolla/xui-core';
import { Box, Text } from '@xsolla/xui-primitives';

type CardProps = ThemeOverrideProps & { title: string };

export const Card = ({ title, themeMode, themeProductContext }: CardProps) => {
  const { theme } = useResolvedTheme({ themeMode, themeProductContext });

  return (
    <Box backgroundColor={theme.colors.surface.primary}>
      <Text color={theme.colors.content.primary}>{title}</Text>
    </Box>
  );
};

// Consumer usage
<XUIProvider initialMode="dark">
  <Card title="Dark card" />
  <Card title="Light card" themeMode="light" />
  <Card title="B2C card" themeMode="light" themeProductContext="b2c" />
</XUIProvider>

When no overrides are passed, useResolvedTheme returns the global theme object by reference — zero overhead compared to useDesignSystem.