createTheme

Purpose

createTheme builds a resolved Theme object (color + spacing + foundation + surface) from a partial input. It is the recommended path to build a theme programmatically — tests, runtime experiments, or apps where the theme needs to be assembled in JavaScript.

For projects that prefer declarative file-based configuration, there is the alternative path via apollion.config.mjs + the apollion-tokens build CLI — see @apollion-dsi/tokens.

Example

Color

The following example shows a warning button colored green defined using createTheme.

import { Button } from '@apollion-dsi/core/elements/button';
import { ApollionProvider, createTheme } from '@apollion-dsi/core/themes';
 
const theme = createTheme({
  colors: {
    // contrast Colors
    baseDark: '#26292E',
    baseLight: '#FCFCFC',
 
    // deep Colors
    deepDark: '#000',
    deepLight: '#FFF',
 
    // brand Colors
    main: '#003750',
    opposite: '#003750',
    complementary: '#F6BA20',
 
    // action Colors
    information: '#3399FF',
    success: '#2CB567',
    danger: '#E12712',
    warning: 'green',
 
    // main Colors
    primary: '#32AFDC',
    secondary: '#2D81AA',
    tertiary: '#2CE571',
  },
  dimension: 'normal', // optional — density applied to spacing
});
 
<ApollionProvider theme={theme}>
  <Button text="Submit" color="warning" />
</ApollionProvider>;

You can build the color scheme quickly and easily through this documentation topic.

Config-First — `apollion.config.mjs`

In projects that prefer declarative configuration (ideal for design + dev teams collaborating, or to generate static tokens consumable outside React), declare the theme in an .mjs file at the project root and run the CLI to generate artifacts (CSS variables, JSON, TypeScript):

// apollion.config.mjs (consumer project root)
import { defineConfig } from '@apollion-dsi/tokens/config-loader';
 
export default defineConfig({
  brands: {
    default: {
      baseDark: '#26292E',
      baseLight: '#FCFCFC',
      deepDark: '#000',
      deepLight: '#FFF',
      main: '#003750',
      opposite: '#003750',
      complementary: '#F6BA20',
      information: '#3399FF',
      success: '#2CB567',
      danger: '#E12712',
      warning: 'green',
      primary: '#32AFDC',
      secondary: '#2D81AA',
      tertiary: '#2CE571',
    },
  },
  modes: ['light'],
  surfaces: ['positive', 'negative'],
  dimensions: ['compact', 'normal', 'spacious'],
  output: { css: true, json: true, ts: true },
});

npx apollion-tokens build --config apollion.config.mjs --out dist/tokens

The loader runs in an isolated environment — access to require() / dynamic import() is rejected before evaluation. The build is idempotent: running it twice produces byte-identical output.

API doc

Property	Type	Default	Optional	Description
inputs	ThemeInputsInterface		No	Definition of the theme to be applied to child components

ThemeInputsInterface

Parameter	Type	default	Optional
breakpoints	BreakpointDefault		Yes
spacing	CreateSpacingArguments		Yes
colors	`Partial<InputColorsInterface>`		Yes
font	`Partial<FontThemeInterface>`		Yes
border	`Partial<BorderThemeInterface>`		Yes
dimension	`'compact' \| 'normal' \| 'spacious'`	`'normal'`	Yes

ApollionProvider GlobalStyle