Generating themes

Creating custom themes and especially their color palettes can be a challenge. You need to understand the available tokens and their roles in the components, as well as find values that are perceptually aligned for users. To simplify this process, Reshaped includes a way to generate colors for your themes.

With the generateThemeColors helper, you can generate the entire palette for light and dark modes using a single primary hex color.

import { generateThemeColors } from "reshaped/themes";

const colors = generateThemeColors({ primary: "#2563eb" })

Similarly, you can pass the starting values for other colors supported in Reshaped:

const colors = generateThemeColors({
  primary: "#...",
  critical: "#...",
  positive: "#...",
  neutral: "#...",
})

When generating the themes, we adjust the color values to look aligned across hues using the HSL and HSLuv color values. However, you can override any specific value yourself if you don't like the generated default, using our regular color token format:

const colors = {
  ...generateThemeColors({ primary: "#..." }),
  backgroundElevationBase: { hex: "#fff", hexDark: "#..." },
}

When building a theme using our theming CLI, you can generate the theme in the reshaped.config.js file. Since the generateThemeColors helper only returns the color values, you can use it for generating the whole theme or just a fragment containing the color tokens. You can also override specific color tokens as mentioned above.

const { generateThemeColors } = require("reshaped/themes");

const config = {
  themes: {
    productTheme: {
      color: generateThemeColors({ primary: "#2563eb" }),
    },
  },
  themeFragments: {
    productThemeFragment: {
      color: generateThemeColors({ primary: "#2563eb" }),
    },
  },
};

module.exports = config

You can use our theming generation helper in the browser runtime as well, together with the getThemeCSS utility.

By default, runtime theming only generates CSS for the tokens you pass to it. If you want to generate the colors but also include the tokens from the full theme definition, you can use the baseThemeDefinition provided by the package:

import {
  getThemeCSS,
  generateThemeColors,
  baseThemeDefinition,
} from "reshaped/themes";

const css = getThemeCSS("myTheme", {
  ...baseThemeDefinition,
  color: generateThemeColors({ primary: "#2563eb" }),
})

You can also use the transform utility from Reshaped to get a theme JS output instead of CSS and use it for custom theming features.

import { transform } from "reshaped/themes";

const theme = transform(name, themeDefinition, {
  isFragment: true,
  themeOptions: { ... },
})

• isFragment outputs only the code for the tokens passed with themeDefinition instead of the entire theme
• themeOptions is the same as the options in the reshaped.config.js