@economist/design-system

The Economist Design System

Table of contents

• Overview
  • Directory structure
  • Example usage
    • ES6 and Next
    • Universal Module Definition
    • Other configuration options
    • Jest and Babel configuration
• Contributing
• Maintainers

Overview

This is the repository for The Economist Design System.

npm install @economist/design-system

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

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.

ES6 and Next

The Design System is currently incompatible with Next 12, please use version 11x

Example of how use a component from the design system:

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

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

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

No additional dependencies need to be specified when using the design system with a Next.js project. The only dependencies you need are Next, React and The Economist Design System.

"dependencies": {
  "@economist/design-system": "^5.44.0",
  "next": "11.1.0",
  "react": "17.0.2",
  "react-dom": "17.0.2"
}

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.

Note: You don't need to use these helper methods (or use Next.js to use ES6 modules) but you may find it's easier than maintaining these configuration files yourself. If you need to add custom configuration directives or override the default settings, you can pass options to both of these helper methods.

Universal Module Definition

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

Using the UMD module is similar to using the ES6 module, the import path will be different and you will also need to include the CSS (as the UMD module can't load the CSS itself):

import React, { Component } from 'react';
import { Button } from '@economist/design-system/dist/umd/common';
import '@economist/design-system/dist/umd/common.css';

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

You can include CSS either by adding a CSS loader to your webpack configuration and loading the CSS in React component (as in the example above) or simply in a stylesheet used on your site.

Other configuration options

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

If you have a different build system, you may find it helpful to refer to the suggested webpack and postcss configuration files, which are bundled along with the module:

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

Checkout the projects in the ./examples/ directory for examples of how to configure a project to use the design system.

Jest and 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 them up automatically.

1. Configure babel.config.js to load the Next preset (if using Next.js):

module.exports = {
  presets: ['next/babel'],
};

1. Configure transformIgnorePatterns in jest.react.config.js:

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

Contributing

To create or modifiy a component, open a pull request following the steps outlined in CONTRIBUTING.md and following the FE-GUIDELINES.md.

Maintainers

See MAINTAINERS.md.