@economist/design-system

The Economist Design System

Overview

This is the repository for The Economist Design System.

npm install @economist/design-system --save

Directory structure

• src/ - The components for the design system (JavaScript and CSS modules)
• examples/ - Examples of how to reference the design system in a project

Example usage

React components for the design system are simple to use in your project:

import React, { Component } from 'react'
import { Button } from '@economist/design-system/common'

export default class extends Component {
  render() {
    return (
    <Button>Example Button</Button>
    )
  }
}

ES6 + Next.js

Using the ES6 module export is the recommended way to use the design system with React.

The easiest way to use ES6 modules with React - and to take advantage of features such tree shaking of both JavaScript and CSS and Server Side Rendering - is to use Next.js.

If you have a Next.js project (which is recommended) you can let the design system manage your webpack configuration for you, which will also allow you to load and optimize CSS and SVG files without additional configuration in your application.

With a Next.js additional dependencies need to be specified in a project when using the design system - everything you need is included.

i.e. all a project needs to have in it's dependencies is something like this:

  "dependencies": {
    "@economist/design-system": "0.0.17",
    "next": "^8.1.0",
    "react": "^16.8.6",
    "react-dom": "^16.8.6"
  }

For next.config.js (to configure webpack) you can use a helper function:

const withDesignSystem = require('@economist/design-system/next');
module.exports = withDesignSystem();

For postcss.config.js (to configure PostCSS) you can also use a helper function:

const withPostCSS = require('@economist/design-system/postcss');
module.exports = withPostCSS();

Both of these helper functions take custom options which override the default values. You don't need to use these helper files, but you may find it's easier than keeping the configuration in these files up to date yourself.

You do not need to use Next.js at all to use the design system, the helper methods for Next.js projects are provided for convenience.

If you have a different build system, you might find it helpful to access access the suggest webpack config for the design system:

const webpackConfig = require('@economist/design-system/webpack.config.js')

Universal Module Definition support

If using ES6 modules isn't practical in your project, you can also use the components via UMD module, which should work for any project.

To see how to use the design system in a projects, checkout the example projects in the ./examples/ directory.

Jest/Babel configuration

If you are using the popular Jest testing framework, you may need to do some additional configuration in your project, as Jest won't pick up the Next.js configuration.

1. Add a Babel plugin for SVG files to your devDependencies:

   npm i babel-plugin-inline-react-svg -D

2. Configure your babel.config.js to load the plugin (and the Next.js preset):

 module.exports = {
   plugins: ['inline-react-svg'],
   presets: ['next/babel'],
 };

1. Configure jest.react.config.js to work with the design system module:

transformIgnorePatterns: [
  '/node_modules/(?!@economist/design-system).+\\.js$',
],

Building

Run npm run build to run all the build steps.

This will run steps to compile JavaScript and CSS.

Deploying

There are build and deploy commands defined in package.json.

A build is triggered automatically when publishing.

Publishing

Publishing Canary releases

To publish a canary (preview/testing) release you need to be a member of the @economist organization on NPM.

1. Update the version in package.json to add the suffix -canary. followed by a canary release number - e.g. '0.0.1-canary.0' or '0.0.1-canary.1' (etc…)
2. To publish the release, run NPM with the --tag option: npm publish --tag canary

Publishing a new version to production

@TODO Document how publishing a release to production works with our CD/CI pipeline