 is a utility library which can be used to include Matchbox styles in any front-end architecture. Matchbox components are built to be used within a React application, but when that isn't possible this library helps to bridge the gap and provide Matchbox styles to any front-end application.

Import the utility file to the top level of your stylesheet.

Usage Example

The Matchbox CSS utility library provides different interaction states that can be used for the following: 

To create styles for these interactions, prefix your classes with 

The Matchbox CSS utility library provides a helper to apply different styles at the following media queries:

To create styles for these breakpoints, prefix your classes with 

Start building user interfaces with Matchbox styles when react components aren't an option.

CSS Utility Library

Matchbox uses colors to visually describe how things function in a UI. By giving meaning to colors, we create consistent visual patterns that help make interactions more predictable.

Primary color for interactive elements and call to actions such as buttons and links. Used to indicate creation, progression or importance.

color_blue_700

Alternative to the primary blue for use in high contrast situations.

color_blue_800

Represents a positive or congratulatory tone.

color_green_700

Alternative to the primary green for use in high contrast situations.

color_green_800

Represents a negative or destructive tone.

color_red_700

color_yellow_400

color_purple_700

color_white

color_gray_300

color_gray_900

Colors is used to visually describe how things function in a UI.

Color

Design tokens are the smallest indivisible units of a design system. They are named entities with immutable values that embody visual design attributes and serve as the foundation for UI development.

Design tokens are another tool for designers and developers to more effectively collaborate and maintain consistency across UI solutions. They help all contributors to “speak the same language”, minimizing confusion and elemental translation. For example, using the token 

 is a term that is understood by both designers and developers, whereas 

 may need additional translation for implementation.

Use of tokens also creates an efficient solution to the “find and replace” time-waster that occurs any time an attribute is redefined. If a decision is made to give 

 a different value, a single update to the token definition will propagate the change across the entire design, minimizing the risk of mistakes or missed code replacements.

Use Matchbox Design Tokens in Development

Tokens from Matchbox are available in three formats: CSS, Scss, and JavaScript.

Matchbox provides CSS custom properties which you can access in vanilla CSS.

Matchbox provides a CSS utility library which you can use in your HTML. 

Matchbox provides Sass functions to retrieve token values.

Tokens are also available to JavaScript-based applications in JSON format.


. For a complete list of all tokens and their corresponding API code, visit the 

Design tokens are the smallest indivisible units of a design system.

Design Tokens

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.

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.

Designers can quickly start creating SparkPost experiences by combining Matchbox principles with its User Interface (UI) Kit, built in Figma. A UI Kit is a comprehensive set of ready-to-use UI components and styles within a design tool (e.g. Figma). They benefit teams by speeding up the design process and helping to enforce consistency, irrespective of the designer.

To use the Matchbox UI Kit, you must first be invited to Figma as a team editor of the SparkPost account. The limited team editor seats are only available for designers and those given special permission. To request a team editor seat, send a message to the #team-ux SparkPost Slack channel. Once you’ve joined Figma, create a new file, locate the “Assets” tab, and drag components onto the canvas to start building.

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.

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.

Start designing experiences with Matchbox

Designer Guide

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

 – A library of static assets including videos and images

To use Matchbox, install the component library and its peer dependencies with 

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

While Matchbox works fine with system default fonts, its components are optimized to be used with Calibre. Head over to the resources section to 

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. 

 templates to set up new projects quickly. These templates install Matchbox, all of its peer dependencies, Typescript, and Calibre.

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.


Start building user interfaces with Matchbox

Developer Guide

Matchbox uses elevation to define the distance between multiple objects along the z-axis. It’s a visual tool which uses depth to create hierarchy and spatial contrast, focusing user attention.

All UI elements sit on imagined planes. The distance between the front of one plane to the front of another plane creates a depth, which Matchbox depicts by use of box shadows. The intensity and size of the shadow cast visually implies elevation.

Shadows should be used infrequently on static, non-interactive UI elements as they are often a visual cue to users, indicating component interactivity. Elements should be given a higher elevation, creating a shadow, during interaction (e.g. hovering, clicking) or to draw the attention of the user to specific tasks (like in modals, drawers, and trays).

All imagined planes sit atop a scale beginning at the base plane of 0px. With consideration to spatial contrast against the base plane, Matchbox uses four variants of elevation, reflected by the Box Shadow tokens.

Use depth to create hierarchy and spatial contrast, focusing user attention.

Elevation

. Icons are a visual tool used to draw attention to common ideas, objects, and actions.

Icons should be used infrequently and purposefully. Using too many icons can create visual noise for the user and degrade the experience.

Icons should always be paired with meaningful text labels when possible to improve user understanding and accessibility. 

Avoid using icons decoratively and without intention as it can detract from their purpose in other parts of the UI.

Icons are used to convey common ideas, objects, or actions to the user.

Iconography

Intentional spacing adds uniformity and rhythm to visual design, creating a more predictable and serviceable experience for users.

Spacing tokens make it easy to configure a component's padding, margin, or position. Instead of setting these properties in pixels or rems, using spacing tokens ensures consistency and minimizes mistakes.

Matchbox operates on a 4px baseline scale where each token variant is a multiple of the baseline; spacing larger than the 800 token is a multiple of 16px.

Intentional spacing adds uniformity and rhythm to visual design.

Spacing

System props are props that directly access a theme. In the following example, the 

Each React component in Matchbox is given access to certain groups of system props depending on the flexibility and requirements of that component. Every component API page is documented with the system props allowed for that component. 

 is the only component that has access to every system prop.

System props also work with non-token values. You can pass through any value so long as it is a valid CSS value for that property.

 is set to a hexadecimal value instead of referencing a design token.

You can also pass in numerical values or expressions.

System props also allow you to easily create media query breakpoints by passing in an array.

Here, this component is applying different 

 values at different breakpoints. Responsive arrays operate on a min-width basis, meaning 

 will be used up to the third breakpoint, and 

 will be used after the third breakpoint.

System props are organized into categories of props, which decide which design tokens are available to that prop. These categories are:

One each component API page, you will see a list of available system props. 

Matchbox's theme file is extendable through the 

 component, useful for building your own themes. See the 

System props provide direct access to design tokens, without writing a single like of CSS.

System Props

Reference sheet for all design tokens

Token Reference

Matchbox uses a predefined set of typefaces, font styling, and guidelines to ensure cohesive and clear communication across all experiences. Typography standards are used to maintain readability and visual hierarchy, directly impacting how a user interprets information.

 font. It is the primary typeface of the base font stack token, Font Family Sans. In situations where Calibre may be unavailable (i.e. fails to load), Font Family Sans will default to native system font families. Note, Calibre is visually small with a low baseline; when paired with other typefaces, size adjustments should be made to account for the difference in visual weight.

When displaying code, defer to the monospace font stack. The monospace font token, Font Family Monospace, defaults to the respective native monospace font families.

Three font weights are used: Normal, Medium, and Semibold. While the font weight, Light, is available, it should be used sparingly.

Each font size is paired with a specific line height (e.g. Font Size 300 should be used with Line Height 300). The ratio given to each set is intentional, with the goal of optimal readability and accessibility for users of all abilities.

Guidelines for combining font family, font size, font weight, and line height help maintain consistency and hierarchy and act as an instructions-for-use tool.

Select the typography variables to view the respective Matchbox font values.