Skip to content

Latest commit

 

History

History
206 lines (141 loc) · 7.57 KB

README.EN.md

File metadata and controls

206 lines (141 loc) · 7.57 KB

Design React Kit

CircleCI Join channel #design-devel Get an invitation for Slack

Read this in other languages: Italiano.

Important: this kit has been designed to work with Bootstrap Italia v.1. There's no kit currently available for Bootstrap Italia v.2.

Intro

Design React kit is a set of React components that implements Bootstrap Italia and Design UI Kit styling, as shown on InVision.

Components are showcased with Storybook.

Public version of Storybook is available here for the latest stable release, while here for the current development version built from master branch.

Table of contents

Requirements

  • NodeJS
  • Yarn

Usage

To use Design React as a dependency in your React project you can install it from npm. We suggest to use create-react-app to create a new React webapp from scratch as follows:

$ create-react-app nome-app
$ cd nome-app
$ yarn add design-react-kit --save

Add bootstrap-italia and fonts

The design-react-kit module does not include the CSS and font files in the bundle, so this needs to be installed as well:

$ yarn add bootstrap-italia typeface-lora typeface-roboto-mono typeface-titillium-web --save

App.js

Then, you just need to import CSS e font editing ./src/App.js as shown:

import React from 'react';
import './App.css';
import { Alert } from 'design-react-kit';
import 'bootstrap-italia/dist/css/bootstrap-italia.min.css';
import 'typeface-titillium-web';
import 'typeface-roboto-mono';
import 'typeface-lora';

const App = () => {
    return (
        <Alert>This is an Alert</Alert>
    );
};

export default App;

Loading Fonts

The Bootstrap Italia theme defines a specific set of font typefaces to work: titillium-web, roboto-mono and lora. The loading of this set of fonts can be left to the browser or controlled: in this last case it is necessary to use the FontLoader component exported by the library. Declaring the FontLoader on top of the Application tree it is enough to trigger the loading of the fonts.

As alternative it is required to manually manage the loading via the webfontloader package:

const WebFont = require('webfontloader')
WebFont.load({
    custom: {
        families: [
          'Titillium Web:300,400,600,700:latin-ext',
          'Lora:400,700:latin-ext',
          'Roboto Mono:400,700:latin-ext'
        ]
    }
})

Peer dependencies

The library does not include react and react-dom, avoiding versions clashing and increasing the size of the bundle. For this reason, for local development it will be necessary to manually install dependencies.

The command to be executed is

$ yarn install --peers

or alternatively manually

$ yarn install react react-dom

Compiling Storybook

Clone the repo and run yarn to install the dependencies. Then run the yarn storybook:serve command to start the development server.

Storybook will therefore be available at http://localhost:9001/

storybook

Public version of the Storybook is available here.

Storybook has been enriched with some addons that make it more talented. Check dependencies on the package.json file for details.

How to create new components

This section explains how to create new components in the repository. All components reside in the src directory: each component is a folder with all that is needed to make it work. Storybook stories are instead under stories.
Unit tests are under the test folder.

i.e. the Button component is shown below the src/Button path and its structure is as follows:

src
    └── Button
        ├── Button.tsx
stories
    └── Button
        ├── Button.stories.mdx
        ├── Button.stories.tsx
test
    ├── Button.test.tsx

Some basic rules for structuring the components:

  • TSX file component files use JSX syntax.
  • The .stories.tsx files only contains examples relative to component.
  • The .stories.mdx files only contains documentation relative to component.
  • The .test.tsx files only contains tests relative to component.

Once you have created a new component, with its history, starting Storybook will be able to check that everything works as it should.

How to contribute

To submit new content (feature or bug fixes) is required to fork the repository, starting from master create a new branch for the new feature: once completed the development (with tests when possible), create a PR to the original repository.

Snapshot tests

The testing system has been provided with a snapshot check on existing stories: this means that each story content is copied into a special file used as reference to check changes in the future. This might fail some test checks on the PR in case of new or changed stories.
In such case it is possible to update the snapshot file with the following command:

yarn test -u

At this point create a new commit and update the PR. Make sure to check the new snapshot content whether it is in line with the changes made before pushing.

Publishing

A command is available to reach a static version of the Storybook catalog as it can be deployed without using a webserver.

$ yarn storybook:build

Static pages obtained from the compilation process generate under the storybook-static directory.

Building library

To build the library and add files into the dist folder:

$ yarn build

Browsers support

The design kit follows the Guidelines for Public Services Design, within the Section 6.3.1.2.1. Supporto browser via the package browserslist-config-design-italia.

TypeScript typing definitions

The library has been rewritten in Typescript and types are exported in the bundle.

Thanks

Chromatic

Thanks to Chromatic for providing the visual testing platform that helps us review UI changes and catch visual regressions.

Thanks to Circle CI for providing the infrastructure for our Continuous Integration needs.