npm package: @sirclo/diametra
Description: Design System for SIRCLO Store
Author: SIRCLO
Latest version: 0.1.0-qa.18

import { ArgsTable, Meta, Story, Canvas } from '@storybook/addon-docs';

<Meta title="Introduction" />

# Diametra Design System

**_Diametra_** is a design system library used for SIRCLO Store Interfaces. It's a collection of **_guidelines_**, **_components_**, and many **_styles_** that can help us to build a consistent User Interface/Experience across all of SIRCLO Store's products.

## Table of Contents

- [Diametra Design System](#diametra-design-system)
  - [Table of Contents](#table-of-contents)
  - [Getting Started](#getting-started)
    - [Package Installation](#package-installation)
        - [npm](#npm)
        - [yarn](#yarn)
  - [Usage](#usage)
    - [Using Built-in Diametra Utilities](#using-built-in-diametra-utilities)
    - [Using Components](#using-components)
    - [Font](#font)
        - [npm](#npm-1)
        - [yarn](#yarn-1)
      - [Google Web Fonts](#google-web-fonts)
    - [Icons](#icons)
        - [npm](#npm-2)
        - [yarn](#yarn-2)
  - [Developing](#developing)
    - [Setup](#setup)
    - [Making a new Components](#making-a-new-components)
    - [Making changes for Components](#making-changes-for-components)
    - [Testing](#testing)
    - [Storybook](#storybook)
  - [Publishing](#publishing)

## Getting Started

### Package Installation

To install **Diametra**, run one of the following command to add it to your project:

##### npm

```
npm install @sirclo/diametra
```

##### yarn

```
yarn add @sirclo/diametra
```

You can update the version based on your needs by checking https://www.npmjs.com/package/@sirclo/diametra.

## Usage

### Using Built-in Diametra Utilities

If you want to use pre-configured Diametra Utilities, like _**custom class**_ for _**typography, spacing, shadow, and border radius,**_ make sure import Diametra's styles to your React root app with this line:

```js
import '@sirclo/diametra/dist/diametra.min.css';
```

You can check the guidelines part in this storybook for more details about custom class.

### Using Components

You can import single component to prevent system to load all the package with this one. This import method is recommended. You can check more detail about this [here](https://medium.com/singapore-gds/how-to-support-subpath-imports-using-react-rollup-typescript-1d3d331f821b).

We refer to “subpath imports” as importing individual components like `@sirclo/diametra/dist/components/Button` rather than the entire library `@sirclo/diametra`.

```js
import { Badge } from '@sirclo/diametra/dist/components/Badge';

const App = () => {
  return (
    <div>
      <Badge text="text" type="badge" variant="default" />
    </div>
  );
};
```

### Font

Diametra is designed to use Roboto font by default. You may add it to your project with npm or yarn via [Fontsource](https://fontsource.org/), or with the Google Fonts CDN.

##### npm

```
npm install @fontsource/roboto
```

##### yarn

```
yarn add @fontsource/roboto
```

Then you can import it in your entry point like this:

```js
import '@fontsource/roboto/100.css';
import '@fontsource/roboto/300.css';
import '@fontsource/roboto/400.css';
import '@fontsource/roboto/500.css';
import '@fontsource/roboto/700.css';
import '@fontsource/roboto/900.css';
```

Fontsource can be configured to load specific subsets, weights and styles. Diametra's default typography configuration relies only on the 100, 300, 400, 500, 700, and 900 font weights.

#### Google Web Fonts

To install the Roboto font in your project using the Google Web Fonts CDN, add the following code sniper inside your project's `</head>` tag:

```html
<link
  rel="stylesheet"
  href="https://fonts.googleapis.com/css?family=Roboto:100,300,400,500,700,900&display=swap"
/>
```

### Icons

Diametra use hero Icon, you must first install the hero Icons font from [react-icons](https://www.npmjs.com/package/react-icons). You can do so with npm or yarn.

##### npm

```
npm install react-icons
```

##### yarn

```
yarn add react-icons
```

and then use it with custom Icon component like this:

```ts
import { HiLightBulb } from 'react-icons/hi2';

const App = () => {
  return (
    <div>
      <Icon IconCustom={HiLightBulb} />;
    </div>
  );
};
```

## Developing

These components/docs will be maintained by Frontend or UI/UX Engineers in line with the needs of Design or Product team. If you are going to update these components/docs, please read some following steps below.

Some guides that might you should be checked before you start to develop:

- [Diametra Design System in Figma](https://www.figma.com/file/oGnr8xL7ki32W4ZXXJTEJe/Diametra?type=design&node-id=0%3A1&t=J4FWBs1ZfNT9Mj64-1)
- [Emotion CSS](https://emotion.sh/docs/introduction)
- [TypeScript React Cheatsheet](https://github.com/typescript-cheatsheets/react)
- [Storybook Docs](https://storybook.js.org/basics/introduction)
- [Jest Docs](https://jestjs.io/docs/getting-started)
- [Rollup](https://rollupjs.org/introduction/)
- [Support Subpath Imports Using React, Rollup, and Typescript](https://medium.com/singapore-gds/how-to-support-subpath-imports-using-react-rollup-typescript-1d3d331f821b)
- [Rollup for Building React Component](https://dev.to/alexeagleson/how-to-create-and-publish-a-react-component-library-2oe#adding-rollup)

### Setup

### Making a new Components

- Create a new file with `.tsx` extension in `src/components` directory. You can follow the existing components file and folder structure.
- Before you write your component behavior & styles, make sure that you have defined Prop Types with exported `interface` or `type` in that file. Examples:

```tsx
/* src/components/MyComponent/index.tsx */
...

export interface Props {
  label: string;
  disabled: boolean;
}
// or
export type Props = {
  label: string;
  disabled: boolean;
}

...
```

- Make sure you've defined component name uniquely that are not owned by existing components.
- Then you can write your component behavior & styles.
- Export default as naming component for grouping imports in `src/components/index.ts`. Examples:

```ts
/* src/components/index.ts */
...
...
export * from './Component';
```

### Making changes for Components

It's better to discuss it with other Squad first before you're going to change existing components.
That's because we want to avoid _breaking changes_ that happened on other Squads with your changes in using existing components.
Assume that you've discussed with other Squad, here's a guide to making changes for existing components:

- Make changes to the component file you want for, in `src/components` directory.
- Make sure you've modify test and doc cases that related with your changes.
- Make sure component test cases have passed and component docs runs properly on Documentation Server.

### Testing

If you've done writing your components, please build the package and test it via mini repo inside _**example folder**_ (The Playground). The Playground is just a simple Parcel app.

Steps:

- Build package
- Import it to the example mini project
- Run example project with `yarn start` command.
- Check your component

### Storybook

Start the component explorer on port 6006: with this command

```
yarn storybook
```

and build storybook with

```
yarn build-storybook
```

please always make sure master branch always have an up to date content. The storybook already deployed here via jenkist and everytime you update the master branch, it will be updated automatically.

Jenkist multibranch: https://jenkins.sirclo.net/job/Others/job/diametra-multibranch/job/master/

If there's any problems or simply you want an access to this link, you can always ask directly to #ask-entrepreneur-cloud-ops channel in slack.

## Publishing

Before pushing your changes to Git, make sure that version in `package.json` is changed to newest version. After your changes have been merged into master branch, you can publish the packages by creating new Release here:

Link: https://www.npmjs.com/package/@sirclo/diametra

Access: https://phabricator.sirclo.com/K196 (go to Actions > Show Secret) 

- First, you have to run `npm login` command and login with access from above.
-