Skip to content
Gusto’s condensed “G” logoWorkbench

Getting started with Workbench
for engineers

New to building in Workbench? Start here.

Workbench is made up of several packages with specific purposes.

NPM packages available in the Workbench design system
PackagePurpose
@gusto/workbenchWorkbench’s core React component library
@gusto/workbench-labExperimental React components
@gusto/workbench-formikFormik adapters for Workbench core components
@gusto/workbench-data-gridThe package containing DataGrid
@gusto/workbench-iconsSVG icon library
@gusto/workbench-illosIllustration library
@gusto/workbench-react-routerReact Router adapters for Workbench Link components
@gusto/workbench-scssSass helpers
@gusto/workbench-tokensDesign tokens used throughout Workbench
@gusto/workbench-codemodsCodemods for migrating from the Component Library to Workbench
@gusto/workbench-testing-libraryTesting utilities to help with testing Tables
@gusto/workbench-vscodeThe Workbench VS Code extension
@gusto/typefaces-gcentraGCentra typeface; Gusto’s base sans-serif font
@gusto/typefaces-clearfaceClearface typeface; Gusto’s serif font, used almost exclusively in marketing
@gusto/typefaces-moonstoneMoonstone typeface; Gusto’s script font, used for signatures
@gusto/workbench-webpack-pluginWebpack plugin to configure @gusto/workbench-illos
@gusto/workbench-rollup-pluginPlugin for Rollup
yarn add @gusto/[email protected]

WorkbenchProvider is a context provider exported from @gusto/workbench. It provides Workbench components with access to our tokens that specify colors, spacing, breakpoints, etc.

We suggest that it wrap your app at a high level so that it can be accessed anywhere downstream.

import React from 'react';
import ReactDOM from 'react-dom';
import { WorkbenchProvider, TextField } from '@gusto/workbench';


const App = () => {
  return (
    <WorkbenchProvider>
      <TextField name="full_name" label="Full name" />
    </WorkbenchProvider>
  );
};


ReactDOM.render(<App />, document.getElementById('root'));

Workbench is designed to be modular and does not rely heavily on global CSS rules with the few exceptions listed below. Design Systems manages the required resets within ZP.

  • We use normalize.cssExternal link to establish a consistent baseline between browsers.
  • Workbench is built using REM units based off a 10px baseline, which will require a global reset (provided below). We do this to make it easier to work with REM units.
*,
*::before,
*::after {
  box-sizing: inherit;
}


html {
  font-size: 62.5%;
}


body {
  font: 400 1.6rem / 1.5 "Helvetica Neue", Helvetica, Arial, sans-serif;
}

Workbench offers three typefaces that are used throughout Gusto for different purposes. GCentra is by far the most common.

First, install the package.

yarn add @gusto/[email protected]

Then import the package. Workbench is written using the modern Sass module syntaxExternal link.

@use '[email protected]/typefaces-gcentra';

Lastly, define the font rules.

We do not implement a “bold” weight, so we redefine all tags typically associated with font weight: 700 to font-weight: 500, which maps to GCentra Medium. font-weight: 400 is mapped to GCentra Book.

body {
  font: 400 1.6rem / 1.5 'GCentra', -apple-system, BlinkMacSystemFont,
    'Segoe UI', Roboto, Helvetica, Arial, sans-serif;
}


b, h1, h2, h3, h4, h5, h6, strong {
  font-weight: 500;
}

Our CSS utilities are currently quite limited in scope as most CSS rules can be set through various APIs (using Box, for example), but we will expand upon them in time as we extract essential helpers from the Component Library. For now, please reference @gusto/workbench-scssExternal link directly to see what is available.

@gusto/workbench-illos requires @gusto/workbench-webpack-plugin in order to specify the location where the illustrations will be stored.

The plugin should be added to your Webpack plugins array with your custom configuration.

Configuration will vary, but it will look a little something like this:

const WorkbenchPlugin = require('@gusto/workbench-webpack-plugin');


const config = {
  plugins: [new WorkbenchPlugin({ publicUrl: '/static' })],
}


module.exports = config;

Please see the Workbench API guidelinesExternal link when developing for Workbench.

git clone [email protected]:Gusto/workbench.git


cd workbench


# Install Lerna for monorepo development
yarn global add lerna


# Symlink interdependent packages
lerna bootstrap


# Run your first build to ensure symlinks are established
yarn build


# Start a local dev server via Storybook
yarn storybook

Workbench comes with VS Code configured out-of-the-box. When you open the project, install the recommended workspace plugins for an optimal experience.

Importantly, one of the recommended apps is the Workbench VS Code extension that provides a collection of code snippets for Workbench components, which allows engineers to scaffold a component with a few keystrokes. Learn more about the Workbench VS Code extension