Virtuoso Design System

This repo enables using the Virtuoso Design System as front-end code (HTML, CSS, & JavaScript).

This project is not a common place for library reuse. For instance charts and graphs should be added to the app directly. For charting we suggest nivo charts.

📖 Dive into the docs

🤖 Explore the code

Docs

The documentation for Virtuoso is hosted on GitHub Pages and powered by Storybook.

To run storybook locally:

npm run storybook

Installing

🚨 Virtuoso is still a work in progress and installation instructions are limited.

Create-React-App

To install with Create React App you will need to use Craco (Create React App Configuration Override).

Install Craco npm i --save-dev craco
Install Craco-Antd plugin npm i --save-dev craco-antd
Install Virtuoso and Antd npm i --save virtuoso-design-system antd
Create a craco.config.js and add the config
Use Virtuoso

Config:

// craco.config.js
// https://github.com/gsoft-inc/craco/blob/master/packages/craco/README.md#configuration
const { when, whenDev, whenProd, whenTest, ESLINT_MODES, POSTCSS_MODES } = require("@craco/craco");
const CracoAntDesignPlugin = require("craco-antd");
const VirtuosoTheme = require('virtuoso-design-system/dist/antd')

module.exports = {
  plugins: [
    {
      plugin: CracoAntDesignPlugin,
      options: {
        customizeTheme: VirtuosoTheme
      }
    }
  ],
}

Update the existing calls to react-scripts in the scripts section of your package.json file to use the craco CLI:

/* package.json */

"scripts": {
-   "start": "react-scripts start",
+   "start": "craco start",
-   "build": "react-scripts build",
+   "build": "craco build"
-   "test": "react-scripts test",
+   "test": "craco test"
}

In index.css need add

@import '~virtuoso-design-system/dist/design_tokens.css';
@import '~virtuoso-design-system/dist/bundle.cjs.css';
@import '~virtuoso-design-system/dist/open-sans.css';
@import '~virtuoso-design-system/dist/raleway.css';

html {
    font-size: 62.5%;
}

Example:

import React from 'react';
import { Button } from 'virtuoso-design-system';

export default function MyComponment() {
 return <Button>Hi there!</Button>
}

Design Tokens

Design tokens are the visual design atoms of the design system — specifically, they are named entities that store visual design attributes. We use them in place of hard-coded values (such as hex values for color or pixel values for spacing) in order to maintain a scalable and consistent visual system for UI development.

— Salesforce Lightning Design System

Style Dictionary is a build system that allows you to define design tokens once, in a way for any platform or language to consume.

Our design tokens are defined in lib/styles/style_dict/tokens/ as JSON files…
…read by the config in lib/styles/style_dict/config.json
…and built by the command

npm run style-dictionary:build

…which creates lib/styles/build/ files for CSS, JS, or whatever platform needs them.
You can clear the built tokens with

npm run style-dictionary:clean

Examples

Examples can be found in /examples

Releasing

Releases are handled by Auto.

Please tag your PRs "release" in order for Auto to find them.
Then, all you have to do is npm run release and you'll get:

automatic changelog
bump npm version
publish to npm — based on your npm login or NPM_TOKEN in .env
make a GitHub release — based on your GH_TOKEN in .env

This works with the magic described in auto shipit docs.

A static version of the Storybook docs are generated automatically before we publish releases to npm.

Development & Testing & Updating

To develop new components make sure to:

add components to /lib/components
add helpers and hooks to /lib/helpers
add relevant stories to /stories
add tests next to the component

Run locally

npm run storybook

Run tests

npm run test

Visual Regression Testing (VRT)

This repository uses Loki for VRT to ensure the visual appearance of states of the components does not regress. Baseline reference images are intentionally checked into this repository in .loki/reference/.

Running VRT locally

You can run the VRT tests locally to check to see if your changes have caused visual regressions from the existing baselines for all components based on the loki config in package.json:

npm run test:vrt

For faster results, you can run a subset of tests using --storiesFilter:

npm run test:vrt -- --storiesFilter=Input

Any failed tests will be output in .loki/difference/. You can inspect any visual differences that are highlighted in these output images.

If the differences are intended, you can update the baselines by following the instructions in the next section.

Updating Loki Baselines

Note: Before performing this step, you must first run the VRT once (see previous section).

If you run the tests above and have legitimate changes in the visual appearance of the components, you can approve new baselines, which will replace the existing baseline images with the new, current images:

npm run loki:approve

This will immediately take all new baseline images from the last test run and replace the existing baseline images. If you wish to update a specific test case image only but reject other changes, see the Loki CLI reference.

We recommend only approving new baselines once all unintended visual changes have been fixed, then running the command above so no fine-grained filtering of new baselines is needed.