@sirclo/diametra NPM

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

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.

Diametra Design System

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:

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.

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

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, 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:

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:

<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. 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:

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:

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:

/* 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:

/* 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)