npm package: @mudita/space-design-system
Description: Mudita Design System
Author: Mudita
Latest version: 1.3.1

# Mudita Space Design System

A React based library for components and predefined styles used in Mudita products like Mudita Cloud.

All the currently available components can be seen on our [Storybook](https://mudita-space-design-system.netlify.app).
It's a kind of visual guide and documentation.

## Usage

1. Install `@mudita/space-design-system` package:
   ```
   npm install --save @mudita/space-design-system
   ```
2. Install additional dependencies:
   - `react` in version 17 or higher
      ```
      npm install --save react
      ```
   - `styled-components` in version 5 or higher
      ```
      npm install --save styled-components
      ```
3. Use the `ThemeProvider` from the package:

   ```TSX
   import { MuditaThemeProvider } from "@mudita/space-design-system"

   ReactDOM.render(
     <MuditaThemeProvider>
       <App />
     </MuditaThemeProvider>,
     document.getElementById("root")
   )
   ```

4. Now you can use the library freely:

   ```TSX
   import { Button } from "@mudita/space-design-system"

   const SomeComponent = () => (
     <Button>
       Click me!
     </Button>
   )
   ```

    **CJS, ESModules, and UMD module formats are supported.**

    ### Fonts
    
    The basic Mudita's font is `Facto` but it's not open sourced, so we can't provide it to you. Instead, there is a very similar font used as a fallback - `Arial`. 
    However, you can still attach a `Facto` font to your project if you [own it](https://fonts.adobe.com/fonts/facto).
    
    Then, you just need to import the CSS file in your main app's component:
    
    ```TSX
    // index.tsx
    
    import "./path/to/font/style.css"
    
    ReactDOM.render(...)
    ```
    
    The `Facto` font has bigger priority, so no additional actions are required. It will be immediately displayed instead of other fonts.

## Development

### Installation

1. Install dependencies:

   ```
   npm install
   ```

2. Install `Facto` font (optional):
   
   1. add `FONTS_DIRECTORY_URL` and `GITHUB_ACCESS_TOKEN` environment variables to your repo with given font
   2. run font downloading script:
      ```
      npm run fonts:download
      ```

   > **Note:** Please make sure you entered `FONTS_DIRECTORY_URL` in a proper format (refer to troubleshooting section).

### Local testing

1. Make appropriate changes.

2. Increase package version manually (only in `package.json` file).

3. Build the package:
   ```
   npm run build
   ```

4. Pack the library into a `tar` package:
   ```
   npm pack
   ```
   
5. In your project that consumes this library, instead of version number in `dependencies` for `@mudita/space-design-system` package put the path to the already generated `.tar` file:
   ```
   "@mudita/space-design-system": "file:../space-design-system/mudita-space-design-system-X.Y.Z.tgz",
   ```
   
6. Reinstall the updated package:
   ```
   npm install @mudita/space-design-system
   ```

7. Depending on your project's setup, rebuild it or reload the page to apply changes.

> More information and different methods of developing and testing packages locally can be found [in this awesome article](https://medium.com/@debshish.pal/publish-a-npm-package-locally-for-testing-9a00015eb9fd). 

### Release flow

1. Make appropriate changes.

2. Rebuild the package:
   ```
   npm run build
   ```
3. Increase package version:

   ```
   npm version <version>
   ```

   > **Note:** For version `0.0.31` the command will be `npm version 0.0.31`. We are using [semantic versioning](https://semver.org/).

4. Publish the package to the NPM registry:
   ```
   npm publish
   ```
   
5. Commit and push changes (with updated version) to the repo:
   ```
   git add .
   git commit -m "Updated to version x.y.z"
   git push -u origin master
   ```

### Troubleshooting

- Authentication error while downloading fonts (`npm run fonts:download`).

  **Solution:**
  Please make sure you have the following envs added in the `.env` file:

  ```
  GITHUB_ACCESS_TOKEN=
  FONTS_DIRECTORY_URL=https://raw.githubusercontent.com/<username | organisation name>/<repo name>/<branch name>/<path to directory with font files>
  ```

  > **Note:** The token should have granted at least `repo` scope and be able to access the repository defined in `FONTS_DIRECTORY_URL` env.

### Bundle analysis

Calculates the real cost of your library using [size-limit](https://github.com/ai/size-limit) with `npm run size` and visualize it with `npm run analyze`.