Updated Jan 7, 2022

Developer Guide


Start building user interfaces with Matchbox

Welcome to the Matchbox Design System! If you’re unfamiliar with Matchbox, take a few minutes to understand what Matchbox is, how it’s used, how to set it up.

What is Matchbox?

Matchbox is the design system created by SparkPost. A design system is a collection of reusable components, digital assets, guidelines, patterns, and philosophies that follow clearly defined standards to manage design at scale.

How Developers Can Start Using Matchbox

There are several ways to use Matchbox in your front end application. Matchbox includes 4 packages that could be used together, or independently.

  • @sparkpost/matchbox – A React component library
  • @sparkpost/matchbox-css – A css utility library
  • @sparkpost/design-tokens – A collection of design tokens
  • @sparkpost/matchbox-icons – A library of icons
  • @sparkpost/matchbox-media – A library of static assets including videos and images

Using the React Component Library

To use Matchbox, install the component library and its peer dependencies with Node Package Manager (NPM) in your React application.

npm install @sparkpost/matchbox @sparkpost/matchbox-icons @sparkpost/design-tokens styled-components --save

Wrap your React app with our ThemeProvider component:

import { ThemeProvider } from '@sparkpost/matchbox';

function App(props) {
 return <ThemeProvider>{props.children}</ThemeProvider>;

That's pretty much it! You can now begin to use our components. Visit the components section to learn more.

Installing Fonts

While Matchbox works fine with system default fonts, its components are optimized to be used with Calibre. Head over to the resources section to download them and install them in your app.

Using Design Tokens

If you are using a frontend framework other than React, you can use our design tokens to build your own front end component libraries. Tokens are available in several forms, one of which should be able to fit your needs.

Read our Design Token documentation for more information.

Using Framework Templates

Matchbox includes Create React App and Next.js templates to set up new projects quickly. These templates install Matchbox, all of its peer dependencies, Typescript, and Calibre.

To create a new Next.js app:

npx create-next-app --example

To create a new CRA app:

npx create-react-app --template @sparkpost/matchbox my-app

Using this Site


The Foundations section is the resource for design principles such as accessibility, color, typography, design tokens (units of the Matchbox Design System), and more.


Housed under Components is the complete library of Matchbox components, or interface elements, reused through the design system. Each component page includes its respective code and live previews, pattern documentation, and styling.


Content (or writing) best practices and guides are integral to design and communication. Matchbox provides both voice and tone, as well as inclusive language principles.


Patterns contain the global, reusable solutions to common design scenarios. Though each component may have its own respective patterns, larger scale patterns combine various components and ensure experiential consistency.

Brand Resources

The tools and standards that reflect how our users perceive SparkPost are found in Brand Resources. When used together, they convey a clear and cohesive representation of the organization.


Updates is the compilation of Matchbox package release history. Version number, release date, and additional notes, as well as relevant resources, are provided for each update.


Need clarification about an area of the Matchbox Design System? Whether you have a question or request regarding components, the UI kit, foundations, etc., feel free to reach out on Slack: #team-ux.