Skip to contentSkip to navigationSkip to topbar
Figma
Star

Creating a Custom Theme

Creating a custom theme is the most the common way a consumer can customize the look and feel of a Paste application.


A custom theme can be created either manually or using the Paste Theme Designer(link takes you to an external page). A Paste Theme is categorized into groups of Design Tokens. The value of any Design Token from any Group can be changed when supplied to the Customization Provider via the theme object. The following token groups are available for customization:

  • backgroundColors
  • borderColors
  • borderWidths
  • breakpoints
  • fontSizes
  • fontWeights
  • fonts
  • heights
  • iconSizes
  • lineHeights
  • maxHeights
  • maxWidths
  • minHeights
  • minWidths
  • radii
  • shadows
  • sizes
  • space
  • textColors
  • widths
  • zIndices

Choosing your base theme

Choosing your base theme page anchor

Firstly you need to decide what base theme you want to extend from. The Customization Provider allows you to choose either the default or dark themes as a base. This means that you can choose to only override certain tokens from the base theme, or completely replace it with a whole new theme.

import {CustomizationProvider} from '@twilio-paste/core/customization';

const MyApp = () => <CustomizationProvider baseTheme="dark">rest of app</CustomizationProvider>;

Manually creating a custom theme

Manually creating a custom theme page anchor

Manually creating a custom theme can be done by duplicating the Paste default theme, and changing the design token values you want to customize. You can change every design token value within the theme, or just a small set. The value of each key/value pair on the theme can be any valid value for the CSS property that the design token can be used for. This might be the best method if youre only customizing a small set of tokens as you only need to provide those specific token overrides.

Below we are choosing the dark theme as our base, and manually creating a custom theme by providing the Customization Provider an object that only overrides certain font weights and border widths.

import {CustomizationProvider} from '@twilio-paste/core/customization';

const MyApp = () => (
  <CustomizationProvider baseTheme="dark" theme={{
    "fontWeights": {
      "fontWeightNormal": "light"
      "fontWeightMedium": "500"
      "fontWeightBold": "600"
    }
    "borderWidths": {
      "borderWidth10": '2px'
      "borderWidth20": '4rem'
      "borderWidth30": '4em'
    }
  }}>
    rest of app
  </CustomizationProvider>
)

Create a custom theme using the Paste Theme Designer

Create a custom theme using the Paste Theme Designer page anchor

If youre looking for a visual approach to creating a custom theme, then the Paste Theme Designer(link takes you to an external page) is the best choice.

The theme designer comes with a UI so you can visually see what tokens are used in various components. For ease of use, each set of tokens is separated into categories. Once a category is selected, you can change individual token values and immediately see what component(s) will be affected by that change. Once all token changes have been made, you can then export your custom theme.

Once exported from the Theme Designer, you can store that JSON object in you application and import in where you initialize the Customization Provider to provide your application with an entire custom theme.

import {CustomizationProvider} from '@twilio-paste/core/customization';
import CustomTheme from './themes/theme.json';

const MyApp = () => (
  <CustomizationProvider baseTheme="default" theme={CustomTheme}>
    rest of app
  </CustomizationProvider>
);

The theme designer can also be used to import a custom theme if you wish to make a change to an existing theme and want immediate feedback on how that change would affect Paste components.

Tips for creating your custom theme

Tips for creating your custom theme page anchor
  • Make sure your color choices are accessible.
  • Provide clear focus shadow or outline color.
  • If you change the font family tokens, make sure youre loading the font in the head of your application.
  • Make sure your hover, focus, and active states provide enough visual affordance for all users.
  • Follow the Paste Inclusive Design Checklist
(warning)

Need to check the accessibility of your colors?

Checkout aremycolorsaccessible.com(link takes you to an external page) to make sure your colors meet at least AA accessibility requirements. Read more about why this is important here(link takes you to an external page).


Examples

Examples page anchor

Creating a branded theme

Creating a branded theme page anchor

Something simple, yet effective that you might want to do is apply branding to your custom application. With Paste, a quick way to do that is to change the Primary colors within in the theme to be a tint of your primary brand color.

As an example you might provide the Customization Provider a theme object that only sets values for the follow Design Tokens, based on your own companies branding:

{
  backgroundColors: {
    colorBackgroundPrimaryWeakest: PROVIDE_YOUR_COLOR,
    colorBackgroundPrimaryWeaker: PROVIDE_YOUR_COLOR,
    colorBackgroundPrimaryWeak: PROVIDE_YOUR_COLOR,
    colorBackgroundPrimary: PROVIDE_YOUR_COLOR,
    colorBackgroundPrimaryStrong: PROVIDE_YOUR_COLOR,
    colorBackgroundPrimaryStronger: PROVIDE_YOUR_COLOR,
    colorBackgroundPrimaryStrongest: PROVIDE_YOUR_COLOR
  },
  borderColors: {
    colorBorderPrimaryWeakest: PROVIDE_YOUR_COLOR,
    colorBorderPrimaryWeaker: PROVIDE_YOUR_COLOR,
    colorBorderPrimaryWeak: PROVIDE_YOUR_COLOR,
    colorBorderPrimary: PROVIDE_YOUR_COLOR,
    colorBorderPrimaryStrong: PROVIDE_YOUR_COLOR,
    colorBorderPrimaryStronger: PROVIDE_YOUR_COLOR,
    colorBorderPrimaryStrongest: PROVIDE_YOUR_COLOR
  },
  shadows: {
    shadowBorderPrimaryWeaker: PROVIDE_YOUR_COLOR,
    shadowBorderPrimaryWeak: PROVIDE_YOUR_COLOR,
    shadowBorderPrimary: PROVIDE_YOUR_COLOR,
    shadowBorderPrimaryStrong: PROVIDE_YOUR_COLOR,
    shadowBorderPrimaryStronger: PROVIDE_YOUR_COLOR,
    shadowBorderPrimaryStrongest: PROVIDE_YOUR_COLOR
  },
  textColors: {
    colorTextLinkWeak: PROVIDE_YOUR_COLOR,
    colorTextLink: PROVIDE_YOUR_COLOR,
    colorTextLinkStrong: PROVIDE_YOUR_COLOR,
    colorTextLinkStronger: PROVIDE_YOUR_COLOR,
  }
}

This will apply your companies brand color as the primary accent to all Paste components that need to use it. You can see an example of this in the Code Sandbox below.

Customizating typography

Customizating typography page anchor

Another small customization might involve changing the typography that is supplied with Paste. Maybe your companies brand guidelines stipulate that you should use a certain font family? By changing the set of typography tokens on the theme, you can make ajustments to the font family and sizing ramps used in Paste to suit your companies needs.

To achieve the result displayed below, we have provided Paste with the following partial theme object.

{
  "fonts": {
    "fontFamilyText": "'Poppins', sans-serif"
  },
  "fontWeights": {
    "fontWeightLight": "400",
    "fontWeightNormal": "400",
    "fontWeightMedium": "500",
    "fontWeightSemibold": "600",
    "fontWeightBold": "800"
  },
  "fontSizes": {
    "fontSize10": "10px",
    "fontSize20": "12px",
    "fontSize30": "16px",
    "fontSize40": "20px",
    "fontSize50": "24px",
    "fontSize60": "28px",
    "fontSize70": "32px",
    "fontSize80": "36px",
    "fontSize90": "40px",
    "fontSize100": "44px",
    "fontSize110": "48px"
  }
}
(warning)

Don’t forget to load your custom fonts

Paste only handles loading the Inter font. If you override the font family to a custom font, be sure you are loading the font files into the web page correctly. Depending on your application and font provider, the method by which you do this will be specific to you.