Styleguide 💅

Styleguide for reusable React components across our frontends

• Production: styleguide.scalingfunds.com
• Staging: styleguide.staging.scalingfunds.com

Overview

This repo consists of three main parts:

1. 🧩 A collection of individual React components to be re-used across all our frontends

   • Based on Material UI
   • Themable, to allow customizing the design for each client

2. 📦 An npm package named @scalingfunds/styleguide

   • The interface between our frontends and the styleguide components

   • Uses rollup.js for bundling the npm package

   • Frontends can import components from the styleguide like so:

     import { Button, CheckBox, TextField } from '@scalingfunds/styleguide'

3. 📕 A storybook deployed to styleguide.scalingfunds.com

   • For developing React components in isolation
   • To serve as our shared source of truth for UI components between Design and Engineering

Getting Started

Running Storybook

• Install dependencies: yarn install
• Run storybook server: yarn start
• Open storybook: http://localhost:8080/
• Familiarize yourself with storybook's shortcuts for a faster development experience: http://localhost:8080/?path=/settings/shortcuts
  • For example, try hitting S to toggle the sidebar on and off

Using a local styleguide with our frontend apps

• Run yarn link:all in your local styleguide repo
• Run yarn build:watch:dev to start rollup in watch-mode so it recompiles the ./build folder on every file change
• In the frontend app, run yarn link:styleguide
• In the frontend app, run yarn start
• Your frontend app should now be using your local styleguide and changing code in the styleguide should also hot-reload your frontend app 😎

Creating a new component

a) Build the component

1. Create a new folder for your component
   • Most components will live in the root src/<YourNewComponent> folder
   • For some components there are sub-categories, for example src/Forms/<YourNewComponent>
2. Decide what kind of component it is:
   1. Material UI component with styling changes only
      • Example: Chip
      • Create a mui-overrides.js file in which you tweak the component styles using the provided classes from Material UI, for example: https://material-ui.com/api/button/#css
   2. Material UI component with functionality changes (e.g. extending a MUI component with new features)
      • Example: Button
      • Create a index.js file that wraps the original MUI component in our own React component and add any features you need
      • Create a styles.js if your component needs any custom styling
   3. A custom component (either combining several MUI components into a new one, or a component that isn't available in MUI)
      • Example: UserName
      • Create a index.js file that implements the component
      • Create a styles.js if your component needs any custom styling
3. Create a stories.js file that renders the component
   • How to write stories
4. Navigate to your new component in storybook (creating a new story in stories.js in the right format will add it to the sidebar automatically)
5. Develop your component, all code changes are live-reloaded into storybook

b) Document the component

A component's story page in storybook serves as the interface between Engineering and Design. The better we document our components and allow the Design team to interact with them, the more productive our collaboration becomes.

1. Add documentation to your component's stories.js
2. Add controls to your component's stories.js to allow the Design team to play with the component
   • Controls are very useful for our design team to understand all the different states a component can be in
   • How to use controls

c) Test the component in a local frontend app

To use a local version of the styleguide in a local Admin Dashboard or Investor Portal we make use of yarn link. This allows us to symlink the node_modules/@scalingfunds/styleguide folder in the Admin Dashboard to our local styleguide project.

From your local styleguide repo

1. Make required dependencies available to your local package registry: yarn link:all
   • This will yarn link the local styleguide package as well as the styleguide's version of react, react-dom and @material-ui/core
   • This workaround is necessary due to this React issue
     • Without this, the admin-dashboard would throw a hooks error, because it thinks it has two versions of React (one in admin-dashboard/node_modules/react and the other in admin-dashboard/node_modules/@scalingfunds/styleguide/node_modules/react)
2. Start the styleguide in watch-mode: yarn build:watch
   • This starts rollup in watch-mode where every change will re-compile the styleguide npm package on the fly and live-reload the consuming application (e.g. the admin dashboard)

From your local frontend app repo (e.g. admin-dashboard)

1. Symlink required dependencies from local package registry: yarn link:styleguide
   • This will solve the duplicate dependency issue by using the styleguide's versions of React and Material UI
2. Start your frontend app: yarn start
3. All changes to styleguide components should now trigger a live-reload in your frontend app 🥳

Changing an existing component

• Navigate to the component in the Storybook sidebar, for example: http://localhost:8080/?path=/story/buttons-%F0%9F%94%98--play
• Open the component in your IDE:
  • ./src/Button/index.js ➡️ The actual <Button> component
  • ./src/Button/styles.js ➡️ The component styles as a function that accepts an optional theme argument if you want to style the component based on theme-specific parameters (for example using the primary color of a theme)
  • ./src/Button/stories.js ➡️ The storybook file that controls how the component will be shown in the storybook app
  • ./src/Button/mui-overrides.js ➡️ For overriding global Material UI theme properties.
    • Example 1: If we wanted all buttons globally to have a certain style, no matter whether they're directly included from @scalingfunds/styleguide or @material-ui/core
    • Example 2: For Material UI components where we don't change any functionality, for example <Chips>, we don't to wrap them into our own React component. That would be a needless abstraction. Instead we just override the global styles of the Chip component via the theme and import it directly into the app via import Chip from '@material-ui/core/Chip'
• Make changes to the code
• Watch the changes being live-reloaded into storybook

Deployment & Release Process

NPM Package

• Every merge into master will automatically release a new version of the @scalingfunds/styleguide package to npm
• After a successful npm release, update the package version in the consuming frontend apps (e.g. admin dashboard):
  • Run yarn upgrade --latest @scalingfunds/styleguide to install the latest version of the styleguide package

Storybook Staging

• Every merge into master will automatically be deployed to https://staging.styleguide.scalingfunds.com

Storybook Production

• Every successful npm package release will automatically trigger a production deploy to https://styleguide.scalingfunds.com
• You don't need to do anything :)