Themes

This page describes the platform theme contract — the theme object served to the host and injected at runtime. For how a widget consumes a theme, see Using Themes.

How it works

A theme is a set of named values (colors, fonts, sizes). Change one value and every UI element that references it updates. For example, changing the primary color from white to black and secondary from black to white re-colors every element that uses those tokens.

At runtime the host's DynamicThemeProvider publishes each value from this theme object as a CSS variable named --theme-<key> (e.g. colors.primary → --theme-primary, colors.onSurface → --theme-onSurface). Widgets map those onto their shadcn/Tailwind tokens, so a single theme change cascades across all widgets. See Using Themes for the widget side.

Data structure

{
  /* Theme name */
  name: string;

  /* Font settings. For more info: `Fonts` chapter */
  fonts: FontsT;

  /* Color pallets. For more info: `Colors` chapter */
  colors: ColorPalette;

  /*

  All sizes should be multiplied by this value. When we make it less or bigger all proportion changes.

  sizeUnit: 4
  ---
  padding: 4 * 5 = 20px;
  width: 4 * 25 = 100px;

  */
  sizeUnit: number;
  borderRadius: number;
  widgetsBorderRadius: number;
  /* Array of colors using at charts */
  chartColors: RGBColor[];
}

Fonts

Possible using 2 fonts. Primary is required and covers all requirements. The secondary is optional.

type FontsT = {
  primary: {
    name: string;
    /* Link to service where to get font. It will be inserted in @font-face */
    link: string;
    /* woff, woff2, etc. */
    type?: string;
    /* font weights */
    weights?: number[];
  };
  secondary?: {
    ...
  }
}

Example:

{
  primary: {
    name: 'Roboto',
    link: '/assets/Roboto-Regular',
    type: 'woff2',
    weights: [400]
  }
}

Will insert next css:

@font-face {
  font-family: Roboto;
  font-style: normal;
  font-display: swap;
  src: url("/assets/Roboto-Regular") format("woff2");
}

Colors

Palette of colors:

type ColorPalette = {
  primary: string;
  secondary: string;
  background: string;
  surface: string;
  danger: string;
  warning: string;
  success: string;
  onPrimary: string;
  onSecondary: string;
  onBackground: string;
  onSurface: string;
  onDanger: string;
  link: string;
  linkHover: string;
  linkCurrent: string;
  linkVisited: string;
  shadows: string;
};

Initialization

White Label has default themes. Light and black. All customers can have custom default themes. It is served from our Customization server.

Default theme

1. CUSTOMER_NAME = 'Avocado' - deploy variable.
2. get the theme from /theme/Avocado-default.
3. Insert theme to store and use it.
4. If something went wrong, use the default light theme.