@worthy-npm/clarity NPM

Clarity Design System

The Clarity design system was created as a communication and standards tool that will help developers and designers communicate easily and efficiently.

This project contains the technical product of the design system. The purpose of this project is to create a library of components that will be used throughout Worthy's products and so help maintain a consistent design language.

This project was bootstrapped with Create React App.

Language and phrasing

Users: In clarity the users are the implementing developers (in site and app).
Atomic component: A component that only recieves information, presents it and reports to a containing element.
Pattern: a component that contains other atomic components and defines the relationship between them. It has constant-content area and a free-content area.

Concepts

UX requirements:
- Safety in changes - Repetition over Cascading in CSS.
- Difficulty in overrides in implementation (site or app).
Restriction and limitations: Unlike regular programming, in Clarity we want to limit the freedom that the users have.
- Using TypeScript
- Preferring Closed arrays to open params (Popup Icons example)
- File for Globals: Inventory.ts
- Comments are used for developers as well as users as demonstrated here

Technical Design

All components will be divided and included in a hierarchy as following:

Component Groups --> Component Types --> Atomic Components

Each component group can contain several component types, and each component type can contain several atomic component.

As a guideline, we want to have all styles on the html itself (styled components), so that it will be harder for developers to override styles. The styles of Atomic components are defined using a central object called the Style Registry, which can hold styles for the group / type / atomic hierarchies.

    {
        groupA: {},
        groupB: {
            typeM: {},
            typeN: {
                AtomicComp:{
                    hover: {
                        width: "180px"
                        }
                },
                class: {
                    backgroundColor: $worthy_mint
                }
            },
            style: {
                font: $OS_600_32px
            }
        }
    }

By definition, a style should not appear on 2 different hierarchies. i.e. a style that exists on the group level must not exist on the type level or atomic level..

Changing the style obj:

 private addStyle(
     style:CSSProperties,
     styleType:CSSStyleTypes,
     group:ComponentGroups, 
     type?:ComponentTypes, 
     name?:AtomicComponents
    )

     this.addStyle({
            width: "100%",
            display: "block",
            boxSizing: "border-box"
        },
        CSSStyleTypes.mobile,
        ComponentGroups.inputs,
        ComponentTypes["search-input"],
        AtomicComponents["primary-search-input"]
    );

On Atomic components, developers should add jsdoc comments so that the system will automatically create documentation to be used in the clarity website.

Example jsdoc:

/**
 * @prop {Function} click - the function will run when clicking the button.
 * @prop {string} text - the button text
 * @prop {boolean} disabled - true if the button is to be disabled.
 *
 * @summary <LargePrimaryButton text="Sell Your Ring" disabled={false} click={() => console.log("Sold!!")} />
 * @extends AtomicComponent
 */

Output

This project has 2 different products:

It can run as a react application that shows example components and documentation according to the jsdoc developers added.
It can be deployed as an npm package so that developers can use the component libraries in other projects.

Working with the project

There are a few auto-generated files so make sure to run npm start before pushing to remote and avoid adding them to the repo.
New components creation is initiated in Product-Design. Otherwise you should be able to use only the existing components for patterns or to be implemented in other projects.

Deployment Processes

Open branch from Master and code.
Run npm run prePublishOnly
Create and assign a PR.
Once approved deploy to clarity staging bucket for UX review - npn run deployStaging
- Make sure you have AWS CLI installed.
- Make sure you have permissions to deploy to the bucket in s3.
- If you wish to see the results imediately, invalidate /index.html file in the Cloudfront distribution.
- Check clarity-staging
Once UX approved, merge to Master, publish to npm using the following chapter after it deploy to Clarity-Docs npm run deploy.

Publishing to NPM

In order to publish the package you need to install np package globally on your computer, e.g. running npm i np -g in terminal.

Before you use np you need to make sure:
1. Your project is a Git repository
2. It needs to have a remote
3. You must have pushed to the remote at least once.
4. You also need to make sure your working directory is clean.
If your project doesn’t have remote, you’ll get this error (at a later part of the checks).
If your working directory is dirty, you’ll get this error:
Error with running tests

To fix this error, you need to change the test script or use flag --no-tests (not recommended).
Moving on
So once you've created a commit, sent PR and got it approved, merged it to the master branch you can run np and got the similar questionnaire:
After all checks are passed you get final screen which states that the package is successfully published, and also contains all commits from the previous published version:
Now browser window opens up with pre filled Release note
What's left is to submit your release note and we are done.
Congrats! 🎉
But don't forget to deploy to Clarity-Docs npm run deploy

Available Scripts

In the project directory, you can run:

`npm run prebuild`

Builds documentation from the different jsdoc in the system
Creates the index.ts for the package.

`npm publish`

Builds the component system as a package (prepublish). The package is built to the 'dist' folder and published to npm.

`npm run deploy`

Deploys the component system server (to serve the documentation wordpress) to our S3 bucket.

All sections below are automatic documentation from create-react-app

`npm run deployStaging`

Deploys the component system to clarity-staging s3 bucket for UI/UX review. Make sure you have permissions to upload to this specific bucket. If you need to see the results immidiatly, remember to invalidate the distribution in CloudFront.

`npm start`

Runs the app in the development mode. Open http://localhost:3000 to view it in the browser.

The page will reload if you make edits. You will also see any lint errors in the console.

`npm test`

Launches percy tests on the localhost. (localhost server is expected to be running)

`npm testgen`

Generate percy visual test files for component packages.

`npm run build`

Builds the app for production to the build folder. It correctly bundles React in production mode and optimizes the build for the best performance.

The build is minified and the filenames include the hashes. Your app is ready to be deployed!

See the section about deployment for more information.

`npm run eject`

Note: this is a one-way operation. Once you eject, you can’t go back!

If you aren’t satisfied with the build tool and configuration choices, you can eject at any time. This command will remove the single build dependency from your project.

Instead, it will copy all the configuration files and the transitive dependencies (Webpack, Babel, ESLint, etc) right into your project so you have full control over them. All of the commands except eject will still work, but they will point to the copied scripts so you can tweak them. At this point you’re on your own.

You don’t have to ever use eject. The curated feature set is suitable for small and middle deployments, and you shouldn’t feel obligated to use this feature. However we understand that this tool wouldn’t be useful if you couldn’t customize it when you are ready for it.