# @scalingfunds/styleguide

> ScalingFunds Styleguide

Latest version **4.54.0** (published 2022-11-08) · UNLICENSED license · 0 weekly downloads

## Install

```sh
npm install @scalingfunds/styleguide
pnpm add @scalingfunds/styleguide
yarn add @scalingfunds/styleguide
bun add @scalingfunds/styleguide
```

## Health

**Score 20/100 (F)** — status: abandoned.

Positive: esm support; no vulnerabilities.

Warnings: low downloads; no types.

Negative: abandoned; low maintenance score.

## Facts

| | |
|---|---|
| Version | 4.54.0 |
| Published | 2022-11-08 |
| First published | 2021-04-16 |
| Weekly downloads | 0 |
| License | UNLICENSED |
| TypeScript types | none |
| Module format | ESM + CommonJS |
| Node | >=16.0.0 |
| Dependencies | 3 |
| Unpacked size | 1.1 MB |
| Known vulnerabilities | 0 |
| Install scripts | no |
| Author | ScalingFunds Engineering |
| Maintainers | jonathanscalingfunds, brickblock-dev-team |

## Links

- npm: https://www.npmjs.com/package/@scalingfunds/styleguide
- Repository: https://git.brickblock.sh/core/styleguide
- Homepage: https://styleguide.scalingfunds.com
- npm.io page: https://npm.io/package/@scalingfunds/styleguide

## Dependencies (3)

- [clsx](https://npm.io/package/clsx.md) ^1.1.1
- [ramda](https://npm.io/package/ramda.md) ^0.27.1
- [react-copy-to-clipboard](https://npm.io/package/react-copy-to-clipboard.md) ^5.0.4

## Recent versions

- 4.54.0 (latest) — 2022-11-08
- 4.53.0 — 2022-11-07
- 4.52.6 — 2022-11-03
- 4.52.5 — 2022-10-21
- 4.52.4 — 2022-09-09
- 4.52.3 — 2022-08-26
- 4.52.2 — 2022-08-17
- 4.52.1 — 2022-08-09
- 4.52.0 — 2022-08-08
- 4.51.0 — 2022-08-05
- 4.50.0 — 2022-08-04
- 4.49.6 — 2022-08-03
- 4.49.5 — 2022-08-02
- 4.49.4 — 2022-06-16
- 4.49.3 — 2022-06-16
- … 85 more at https://npm.io/package/@scalingfunds/styleguide/versions

## README

# 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](https://material-ui.com)
   - [Themable](https://material-ui.com/styles/advanced/#theming), to allow customizing the design for each client

1. 📦 An npm package named [`@scalingfunds/styleguide`](https://www.npmjs.com/package/@scalingfunds/styleguide)

   - The interface between our frontends and the styleguide components
   - Uses [rollup.js](https://rollupjs.org/) for bundling the npm package
   - Frontends can import components from the styleguide like so:

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

1. 📕 A [storybook](https://storybook.js.org) 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

![Arch Diagram of this Repo](./arch-diagram.svg 'Arch Diagram of this repo')

## 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>`
1. Decide what kind of component it is:
   1. **Material UI component with styling changes only**
      - Example: [Chip](./src/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
   1. **Material UI component with functionality changes** (e.g. extending a MUI component with new features)
      - Example: [Button](./src/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
   1. **A custom component** (either combining several MUI components into a new one, or a component that isn't available in MUI)
      - Example: [UserName](./src/UserName)
      - Create a `index.js` file that implements the component
      - Create a `styles.js` if your component needs any custom styling
1. Create a `stories.js` file that renders the component
   - How to [write stories](https://storybook.js.org/docs/react/writing-stories/introduction)
1. 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)
1. 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`
1. 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](https://storybook.js.org/docs/react/essentials/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`](https://classic.yarnpkg.com/en/docs/cli/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](https://github.com/facebook/react/issues/14257#issuecomment-595183610)
     - 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`)
1. 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
1. Start your frontend app: `yarn start`
1. 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 :)

---
_Source: https://npm.io/package/@scalingfunds/styleguide · Machine-readable twin of the npm.io package page. Health data is recomputed on every publish._