glints-aries

Introduction

We proudly present to you Glints Aries created by the front-end engineers of Glints. It is a front-end framework to simplify and speed up your development. This project is built with React and Styled Components. We are still actively developing this project day by day and there are still a ton of amazing components to be built.

Installation

npm install -S glints-aries

Basic usage

Before you start implementing the component, it's always a good idea to wrap your root component with <GlintsContainer />. We created that Container to adapt with every screen size, so users will always have the best experience regardless of the device they use. For more details, you can read this at Utilities, then GlintsContainer section.

import { GlintsContainer } from 'glints-aries';

<GlintsContainer>
  <Component />
</GlintsContainer>;

Demo

http://aries.glints.design/

Development

Before that, make sure you already have git, node (version >= 14), and yarn installed.

1. Clone the repository

git clone [e-mail]:glints-dev/glints-aries.git

1. Install the project dependencies (preferably use yarn here), then build the project

yarn
yarn build

1. Start the application

yarn storybook

1. Open your browser on (port 6006)[http://localhost:6006].

Note: For Windows user, please use WSL2 Linux to execute all the commands above. Make sure that the repository is cloned on the linux folder, not on your C drive.

How to test local changes in glints-aries in your project

yalc

install yalc globally

yarn global add yalc

in your local glints-aries directory:

yarn build
yalc publish

in your dependent project:

yalc add glints-aries
yarn start:dev

unlink local glints-aries in dependent project:

yalc remove glints-aries
yarn install

yarn link (might not work)

1. Open terminal in glints-aries.
2. Run yarn link.
3. Open terminal in your project.
4. Run yarn link glints-aries.
5. Run yarn build in glints-aries when finish changes and want to test locally in your project.

Run yarn unlink glints-aries and re-install glints-aries when you want to stop using local glints-aries

Currently there is an issue where the above leads to react complaining about multiple instances of react being found. The error message says Uncaught Invariant Violation: Invalid hook call [...]. If you encounter this, you can link your project's react into your local Glints Aries:

1. Open terminal in your project.
2. Run cd node_modules/react.
3. Run yarn link.
4. Open terminal in glints-aries.
5. Run yarn link react.

Adding visual test

We use playwright visual comparison test for components to check for regressions, since images in every browser and machine can be rendered differently we'll use docker image to generate and compare the screenshots.

All visual test and screenshots can be found in test/e2e directory

To generate new screenshots locally:

Create docker image with docker run --rm --network host -v $(pwd):/work/ -w /work/ -it mcr.microsoft.com/playwright:v1.29.0-focal /bin/bash

Run following commands in that image:

1. Install the dependencies yarn install or npm install
2. Run storybook yarn storybook
3. Generate screenshot of your tests with npx playwright test --update-snapshots
4. Commit and push your test screenshots

Code structure in glints-aries

1. Always do alphabetically when importing file.
2. Put file on proper folder based on each respective uses.
3. Use 2 Indent Spaces and Tab on the code.
4. Follow this import structure for your code
   • First: always import React library at first.
   • Second: third-party.
   • Third: glints-aries component.
   • Fourth: glints-aries utilities.
   • Fifth: styling.

import * as React from 'react'; // React

import classNames from 'classnames'; // Third-party
import PropTypes from 'prop-types'; // Third-party

import Modal from '../../Display/Modal'; // Glints Aries component

import { escEvent } from '../../Utils/DomUtils'; // Glints Aries utilities

import { Container, ModalBackground, ModalArea } from '../../Style/ModalStyle'; // Styling

Always give line break between different section when importing.

1. Follow this code structure for your code
   • First: Constructor / State
   • Second: Local Function
   • Third: React life cycle
   • Forth: Render
2. Always do line break whenever your import or variable is so long. You can do it like this but you can do it in another format as long as it can be legible and not long.

const { type, children, className, ...defaultProps } = this.props;

Code Procedure

1. Use Color library instead of writing hex codes.

background-color: #EC272B; // Wrong
background-color: ${PrimaryColor.glintsred}; // Right

1. Use ScreenSize instead of writing pixel size number.

@media (min-width: 640px) { ... } // Wrong
@media (min-width: ${ScreenSize.mobileL}px) { ... } //Right

1. Naming convention for styled-components.

Use the component name followed by the role of that style.

CheckboxContainer
1. Name: Checkbox
2. Role: Container

JobcardImageWrapper
1. Name: Jobcard
2. Role: ImageWrapper

1. Avoid offering styling props on a component.

<Collapsible onHoverColor="#FAFAFA" /> // Wrong

1. Minimize the number of elements inside a Component

// Wrong
<div className="container">
  <div className="wrapper">
    <div>
      <h1>This is Heading</h1>
    </div>
  </div>
</div>

1. Fix eslint/react warnings before pushing your code.

What is Component?

A standalone piece of software that has a clear boundary that is accessible via an API and contains all of the application dependencies.

Why we need a component-based design system?

1. Create consistent experience throughout our UI.
2. Component accelerates development.

What we need to prepare for constructing a design system?

1. Identify company culture/ mission
2. Base Color
3. Type scale
4. Border radius (rounding corner or sharp corner)
5. Spacing scale (line-height)
6. Letter spacing
7. Shadow (how our shadow look like on every component)

Creating and maintaining a consistent UI and UX across every part of our product. It helps users intuitively navigate and successfully interact with different sections of your applications without confusion. It also creates sense of branding.

If you design a component, you should pay attention to

1. Functional Consistency
2. Visual Consistency

What defines a great component?

1. Interface defines the component so component should respect the context. It means that Interface should be able to work in any possible context.
2. Interface should have clear usability.
3. Component should be flexible but still consistent.
4. Only support functional interaction, not style.
5. Great component supports accessibility.

How can we improve glints-aries?

1. Always leave room for component to be flexible but still consistent.
2. Component size should be flexible in every environment.
3. Glints Aries’s interface should be able handle any possibilities.
4. The name of the component must be easy to understand and clear based on the usage.
5. Differentiate between component that should have children and self-closing tag.
6. Improve accessibility.
7. Always checking your code whether it's having clash with existing code.
   • Do manual test.
   • Remove all warnings and errors before push it to Github.

More about Glints Aries

Find out more about the following topics in our wiki:

• Contributing
• Roadmap
• Testing