sn-ui-kit-new v4.9.6

Snapp New UI Kit

This New UI Kit is supposed to be widely used in Snapp! company and its ventures.

Components are based on Figma Design System.

Table Of Contents

• Getting Started to Develop
• Use it inside your project
• Installed Packages
  • Core Packages
• Prerequisites Knowledge
• Directory Structure
• Conventions
  • Naming Conventions
• Component Generator
• Available Scripts

Getting Started to Develop

If you only want to use this UI Kit inside your project, checkout Usage Guide.

After making sure that you're connected to Sanpp! proxy (FortiClient VPN), you could run:

npm install

We currently use Storybook to visualize components during development phase, you can run

npm run storybook

to start an storybook server while developing components.

Use it inside your project

If you want to add this UI Kit to your project, first install it as a dependency:

yarn add @snapp/ui-kit-new
// or
npm install @snapp/ui-kit-new

Then, what you only need to do is wrap your whole application inside ThemeProvider component:

import { ThemeProvider } from '@snapp/ui-kit-new';

function App() {
  return <ThemeProvider>/* Your application */</ThemeProvider>;
}

What does the ThemeProvider component apply?

• Enabling UI Kit default theme inside your application to be used by components. You can override some parts of this theme by providing your own theme prop. Checkout type of the theme you can provide (StrictTheme).
• Enabling light mode by default. You can change it by setting the mode prop to dark.
• Applying modern-normalize.css to normalize styles between browsers and applying a bunch of other cool stuff.
• Applying @font-face declarations based on the direction in theme prop. it's value is rtl by default. Based on the Typography in Design System, we apply:
  • IRANSansX font as the default font for rtl direction
  • Inter font as the default font for ltr direction

Installed Packages

Core Packages

• Emotion - Styled Components: as the css-in-js library.

Currently we do not use any bundler to bundle components and other files. We simply use tsc compiler to make codes ready to be published on NPM. however you can use npm run storybook to visualize components using Storybook server.

:construction: Under Construction :construction:

Prerequisites Knowledge

• Typescript: The project is based on Typescript. Following courses and links are your friends to get involved with Typescript in a proper way.
  • Youtube - React & TypeScript - Course for Beginners - Watch it if you're beginner to TS
  • Frontend Masters - React and TypeScript - A TS in-depth course
  • React TypeScript Cheatsheets - One of the best available cheat sheets you can find
• Emotion: Our Styling system is based on @emotion/styled which is pretty similar to styled-components. If you don't have any experience with Emotion or Styled Components, Please read their official documentations.
  • Emotion - Styled Components
  • Styled Components - Documentation

Directory Structure

Inside the src directory, you can see:

.
└── src
    ├── components
    ├── theme
    └── utilities

• components: Where you can find all components :smile:
  • Inside each component, we have 5 files as follows:
    • <ComponentName>.stories.ts: contains all stories related to the component and Storybook
    • <ComponentName>.styled.ts: all emotion's styled components should be written in this file
    • <ComponentName>.tsx: contains JSX definition and final React component constructed using Emotion's styled components and types.
    • <ComponentName>.types.ts: the base <ComponentName>Props, <ComponentName>StyledProps and other component-related types should be defined in this files
    • index.ts: exporting component occurs in this file
• theme: Provides Theme type definition and a base theme to be used by Emotion
• utilities: Consist of all utility functions that may be used anywhere in the codebase

Conventions

We use conventional commit as the convention for commit messages. Please obey its rules otherwise you get error and can not commit with unprincipled commit messages.

Naming Conventions

We use these name casing conventions:

• Each component directory: PascalCase (<ComponentName>)
• Each file inside each component: PascalCase (<ComponentName>.<postfix>.<ts/tsx>)

:construction: Under Construction :construction:

Component Generator

We use Yeoman Generator to make the new components creation much more easier.

There is a @snapp/generator-ui-kit-new package which contains templates and instructions to create new components.

You can simply run

npm run generate

and go through some steps to generate basic component files which follow naming conventions as well. It will eventually create component files that are mentioned in Directory Structure section.

Available Scripts

We have a few commands to be ran using package manager cli:

build

Use tsc compiler to generate jss and d.ts type definitions for all components inside dist directory.

copyfiles

Copy non TS/JS files into dist directory. It should be run during build command (after creating dist directory using tsc compiler) and it's not supposed to execute separately.

deploy

Build (npm run build) and deploy package to Snapp! private NPM registry.

storybook

Run Storybook server which helps developers to visually see available created components through rich UI.

build-storybook

Build an static version of Storybook inside storybook-static directory. useful for deploying Storybook and make it available online.

generate

Run Yo generator. Read Component Generator

lint

Run eslint through code. To find if there's any error using CLI. useful to be used on CICD system.

lint:fix

Run eslint with fix flag. It will fix fixable errors (auto-fixable ones).