ux-poc v1.9.0

UX Design System

Follow this link there you can find the "Main Idea" topic. There we're using Storybook for Components functionality preview and managing Components stories.

• Structure
  • Components
  • Context
  • Utilities
  • Custom Hooks
  • Types
  • Assets
• Get Started
  • Installation
  • Git branch
  • Create new Components
  • Exporting
  • Component Styles
  • Global Styles
  • Design Tokens
  • Unit testing
  • Prepare PR
  • Local Build
  • Package Publishing
• Package Using
• Technologies

Package Structure

Components

All components are placed in the src/atomic/** folder.

We are using Atomic Design Structure: Atoms Molecules Organisms Pages Templates

Context

You will find React Context implementation in the src/atomic/context folder.

MockDataContext.tsx: Set of functionality for the mocked data and state managing.

InterfaceContext.tsx: Set of functionality for Interface (markup, fonts, themes etc.) managing.

Utilities

You will find shared utilities in the src/utils folder. In the utils you can find functions, design tokens, hooks, mocked data.

1. Functions: src/utils/functions folder. There we're adding shared functions such as content parsing, configs, dates pasing, color updates (hexToRgb), object utilities, etc.

2. Hooks: src/utils/hooks folder. You'll be able to create your own React hooks. We're working in a functional way so please don't use the HOC approach.

3. Design Tokens: src/utils/designTokens folder. For better UI/UX we're using shared Design Tokens approach. Our design tokens - values, constants and objects needed to construct our design system.

4. Mocked Data: src/utils/mockedData folder. We should mock the data for Components where required connection with API.

Types

There we placed type declarations src/types/declarations.ts and shared typings src/types/shared.

Assets

Fonts src/assets/fonts, icons src/assets/icons, global styles src/assets/styles placed there.

Get Started Developing the Package

Installation

1. Make sure that the Node.js is installed. We're using version 14.
2. Clone the repository.
3. Run command yarn install for dependencies installing.
4. Run command yarn prepare for Husky and Git Hooks enabling.
5. Run command yarn start. This will start the storybook preview app.

or shortcut

yarn install && yarn prepare && yarn start

Husky/Git Hooks

We're using Husky and Git hooks for the pre-commit and pre-push

• pre-commit - we're running linter and prettier
• pre-push - we're running unit tests

If after package installation for some reason you'll miss .husky/pre-commit and .husky/pre-push shell files, you should install this manually:

yarn run prepare

npx husky add .husky/pre-commit "lint-staged"
npx husky add .husky/pre-push "npm run test"

Git branch

All new features, bugfixes, hotfixes should be in the own branches. Before starting development, create a new branch, with name:

[feature|hotfix|bugfix]/[Jira number]-[short description]

Example:

feature/DSX-93-components-label

Creating new Components

For building our component library we are using Rollup. Configuration added to the core of app in the rollup.config.js.

Each new component should be added to the atomic/**/* folder.

For each new component, we're creating our own folder in the atoms, molecules, organisms, pages or templates.

Example: src/atomic/molecules/InfoCard.

Exporting

After creating a new component in the Atoms, Molecules, Organisms, Pages or Templates, you should create the re-export in the atomic/index.ts:

Example:

import { Button, Link } from "./atoms";

export { Button, Link };

Component Styles

Component styles should be created at the separate file styles.ts, we're using Styled Components for this.

Example:

export const InfoCardStyled = styled.div`
  font-family: "Noto Sans", sans-serif;
  display: flex;
  flex-direction: column;
  justify-content: space-between;
  box-shadow: 20px 40px 128px -18px rgba(34, 52, 87, 0.24);
  border-radius: 8px;
  background: #ffffff;
  padding: 16px 22px;
  position: relative;
  overflow: hidden;
  height: 100%;
  max-height: 200px;

  ${({ isActive }) => handleActive(isActive)}
`;

Usage:

<InfoCardStyled isActive={isSelected}>...</InfoCardStyled>

Global Styles

Global styles you can find in the src/assets/styles. These styles we're using for Storybook styling storybook.scss and for global styling, as the global font.

Example:

export const GlobalFonts = createGlobalStyle`
  @import url('https://fonts.googleapis.com/css?family=Noto+Sans');

  body {
    font-family: 'Noto Sans', sans-serif;
  }
`;

Design tokens

For better UX and providing more flexibility for components, we're using the Design Tokens approach.

Component Design Tokens: utils/designTokens.

Current list of tokens:

• colorPalettes
• elevations
• grid
• spacing
• typography

Note: After implementing new design token and/or functions for them, please make re-export in utils/designTokens/index.ts and export to the main bundle atomic/index.ts.

Design tokens example:

export const typography = {
  fontFamily: "'Noto Sans', sans-serif",
  tokens: {
    "header-01": {
      tag: "h1",
      fontSize: "2rem",
      lineHeight: "2.5rem",
      fontWeight: 400,
      letterSpacing: "0",
    },
    "header-01-strong": {
      tag: "h1",
      fontSize: "2rem",
      lineHeight: "2.5rem",
      fontWeight: 600,
      letterSpacing: "0",
    },
  },
  componentsTokens: {
    Button: {
      "button-text-default": {
        fontSize: "0.875rem",
        lineHeight: "1.25rem",
        fontWeight: 700,
      },
    },
    Form: {
      "input-text-default": {
        fontSize: "0.875rem",
        lineHeight: "auto",
        fontWeight: 400,
      },
    },
    Caption: {
      "caption-regular": {
        fontSize: "0.75rem",
        lineHeight: "1.125rem",
        fontWeight: 400,
      },
    },
  },
};

export const getComponentToken = (componentName: string, token: string) => {
  const componentTokens = typography.componentsTokens;

  if (!componentTokens[componentName]) {
    return console.error(`Component '${componentName}' has no tokens defined.`);
  }

  if (!componentTokens[componentName][token]) {
    return console.error(`Token '${token}' is not defined for '${componentName}'.`);
  }

  return componentTokens[componentName][token];
};

Usage:

import { getComponentToken } from "utils/designTokens/typography";

export const ButtonExample = styled.button`
  ...
  ${getComponentToken(componentName, tokenName)}
  ...

  ...
  ${getComponentToken("Button", "button-text-sm")}
  ...
`;

With props

export const SomeComponent = styled.div`
  font-family: ${typography.fontFamily};
  ${({ token }) => typography.tokens[token]}
`;

Preview Design Tokens: srs/styles/designTokens. Preview Design Tokens needs to create Storybook documentation. We're using mdx for creating tokens documentation, when we're creating a new design token, we should add related file to the docs folder.

See an Examples in the src/docs:

src/docs/Colors.stories.mdx
src/docs/Elevations.stories.mdx
src/docs/Typography.stories.mdx
...

Unit testing

For the unit testing we're using Jest and @testing-library/react.

Important: Functional coverage for all new Components, hooks, utility functionality should be 100%. Main goal is cover all functionality should be covered on 100%.

Components testing: Unit tests should be created in Components folder as Component.test.tsx. Utilities testing: All unit tests files should be created in the separate folder test, with name of main file: utils/functions/test/object.test.ts

Prepare PR

After implementation feature/hotfix/bug, please make sure:

1. Branch name match naming rules.

[feature|hotfix|bugfix]/[Jira number]-[short description]

2. Write a title in style: [Jira nubmer] [Components|Tokens|Feature Name]: Short Description
3. Add the description
4. Follow the PR checklist
5. Request reviewers
6. When PR will be ready to go, please make sure you're squashed commits

Example:

  [DSX-93] Components: Label
  [Hotfix] Documentation

Local build

For building our component library we are using Rollup.

1. Make sure that the Node.js is installed. We're using version 14.
2. Clone the repository.
3. Run command yarn install for dependencies installing.
4. Run command yarn build. This will prepare the component library build for publishing.

Package publishing

Release process described on the Confluence.

Before release, make sure:

1. Create release candidate branch from develop. Following our git flow process, we should create an RC branch which should be published as:

[next-version]-rc-[rc number]

Example:

0.2.0-rc-1

More information about rc number you'll find there. 2. Create PR from where RC branch is compare and base branch - main 3. Get approvals from team members. 4. Merge RC PR to main.

We're using Codefresh pipelines for build and publishing. After merging the RC branch to the main the Codefresh production pipeline will start. If build and publish pass correctly - NPM package will be released.

5. Check released package there.

Getting Started Using the Package

To use the EVO package in your project the following dependencies must be met:

• React.js ^18.1.0v - To use react components. Note some tokens do not use react and may be used without it.
• React Dom ^18.1.0v - React Dom is a package peerDependency.
• Styled Components ^5.3.3v - styled-components is a package peerDependency.
• Node 14.17.1 or higher, Node 16 is recommended.

Add the following to your project:

1. Create a .npmrc file in the same directory as your package.json and add the following:

always-auth=true
registry=https://registry.npmjs.org
//npm.pkg.github.com/:_authToken=YOUR_TOKEN_HERE
@runeffective:registry=https://npm.pkg.github.com/

Replace YOUR_TOKEN_HERE with a GitHub personal access token with access to the ux-design registry. It should have the read:packages scope.

2. If using yarn (recommended) create a .yarnrc file in the same directory as your package.json and add the following:

"always-auth" "true"
"@runeffective:registry" "https://npm.pkg.github.com"
registry "https://registry.npmjs.org"

3. Make sure you have installed peerDependencies:

npm install react react-dom styled-components

yarn add react react-dom styled-components

4. Add the package to your project by running the following:

npm install @runeffective/ux-design

yarn add @runeffective/ux-design

Technologies

Core

• React.js v17.0
• TypeScript v4.4
• Styled Components v5.3

Testing

• Jest v27.3
• Testing Library/react v12.1

Preview

• Storybook

Building tools

• Rollup v2.58
• Prettier
• Git hooks
• Husky

Lints

• ESLint v8.0