Design System Setup

This is the design system (style-guide) frontend library for a exmple project which holds UI themes and customizable react components for reuse.

The project uses React and Typescript 4.

How to use this library in another React FE project:

• First run: yarn add @goodslav/design-system-setup
• Then import what you need in the main app file: import { Box, global, themes } from '@goodslav/design-system-setup'
• Don't forget to wrap app components in the relevant ThemeProvider component and add the globalStyles:

import { Box, global, themes } from '@goodslav/design-system-setup'
 
const EquipDefaultThemeProvider = themes.EquipDefaultTheme
 
export const App: React.FC<{}> = () => (
 <EquipDefaultThemeProvider>
   <global.GlobalStyle />
 
   <Box
     color="primary-contrast-text"
     backgroundColor="primary-main"
     m={4}
     p={4}
     alignItems="center"
     justifyContent="center"
     width="fit-content"
     height={200}
     borderRadius="medium"
     opacity={1}
   >
       I'm a Themed Box
   </Box>
 </EquipDefaultThemeProvider>
)

Setup

Node version >=10.19.0 is required. We recommend using LTS one as of time of writing: 12.18.4

Install dependencies via yarn:

yarn install

This project uses Yarn Berry (aka Yarn 2). As of time of writing, Yarn Berry lacks proper support in IDEs to be used for production projects, because of the following issues: VSCode 75559 and Yarn Berry 806. This is why yarn 2 is configured to work like yarn 1 without PnP feature via nodeLinker: node-modules setting in .yarnrc.yml until these issues are resolved. To set up the project and your VSCode IDE for the eventual use of PnP feature read and follow instructions in the next two paragraphs.

This project uses Yarn Berry (aka Yarn 2), so in order to make it work with yur IDE of choice and other SDK tooling, please follow the instructions in this article. For VSCode run the following command in the root folder:

yarn dlx @yarnpkg/pnpify --sdk vscode

If using VSCode with prettier-vscode extension you may also have to add .vscode/pnpify/prettier/index.js to Prettier: Prettier Path setting in VSCode: link to issue

This project uses LF Unix line break type. If VSCode is giving you loads of Delete cr eslint errors, it means that the given file is set to CRLF mode, displayed and edited form the right side of the status bar. To fix that and utilize it in newly created files and you would need to update the VSCode files.eol setting to \n for this workspace.

Workflow

This project conforms to the The Conventional Commits specification which is a lightweight convention on top of commit messages. It provides an easy set of rules for creating an explicit commit history which makes it easier to write automated tools on top of. The project and project CI pipeline both use various dev tools to enforce this convention and prevent common commit message mistakes. More information on the convention specification and how to use it is available in this article

The project has pre-commit and pre-push hooks setup using husky dev dependecy. They will run typescript checks, formatters and relevant tests on staged files before commit and push. The hooks are configured in lint-staged and husky sections of the package.json file.

This poject uses React Storybook to develop, showcase and test components and design-system elements in isolation.

The project is written using the styled-components npm package. It has different themes support and implements design-system properties using the styled-system npm package and uses polished npm package for different util functions that speed-up writing styles.

The prepack node script command is ran by yarn/npm when the package is installed in order to build it and create the lib folder from which the module files are then imported in the project that uses this library.

Available Scripts

In the project directory, you can run:

yarn build

Builds the themable component library for production to the lib folder.

It correctly bundles React in production mode and optimizes the build for the best performance and creates a tree-shakable npm module.

The build is minified.

To see what the actual built module will include as files, you have to have 7zip installed and added to global PATH env variable and then you simply run the follwing command in the project's root folder:

yarn pack && 7z x *.tgz && rm -rf package.tgz lib

The library is ready to be deployed!

yarn storybook

Runs the app's storybook in the development mode.

It automatically opens http://localhost:6006 to view it in the browser.

The page will reload if you make edits.

You will also see any lint or typescript errors in the console.

yarn build-storybook

Builds the app's storybook in production mode.

It places the static html files in the storybook-static folder which is added to the .gitignore file.

yarn build-storybook-docs

Builds the app's storybook documentation.

yarn test

Launches the test runner in the interactive watch mode.

Snapshot tests are automatically created against component stories using the @storybook/addon-storyshots storybook plugin.

yarn format

Runs prettier opinionated formatter in write mode against all typescript files in the project and reformats them according to the settings from .prettierrc file and ignores the files listed in .pretttierignore.

yarn format:check

Runs prettier opinionated formatter in list mode against all typescript files in the project and lists the ones that need formatting according to the settings from .prettierrc file and ignores the files listed in .pretttierignore.

yarn lint

Runs typescript compliler silent check and then eslint formatter against all typescript files in the project and reformats them according to the settings from .eslintrc file and ignores the files listed in .eslintignore.

Imports are automatically sorted and grouped using the eslint-plugin-simple-import-sort eslint plugin and some rules from eslint-pluin-import based on the rules defined in the .eslintrc file.

For the typescript compiler check it exits on typescript syntax errors and displays them as output in the console.

yarn audit-scan

Runs the @efrem/auditdeps yarn plugin package in order to check project dependencies for known vulnerabilities.

yarn oss-scan

Runs the auditjs package from Sonatype in order to check project dependencies for known vulnerabilities against their OSS Index API.

The OSS Index API is rate limited to prevent abuse. Guests (non-authorized users) are restricted to 16 requests of 120 packages each, which replenish at a rate of one request per minute. This means if you have 600 dependencies, then 5 requests will be used. No problem! If you have many projects which are run close to each other you could run into the limit.

You can either wait for the cool-down period to expire, or make a free account at OSS Index. By going to the "settings" page for your account, you will see your "token". Using your username (email address) and this security token you would have access to 64 requests, which is likely plenty for most use cases.

To be able to run this command locally you have to first register for a OSS Index API account with your company email here: (register link)

Then create a .env.local file in the root of the project with the following content inside:

OSSINDEX_USER=your email
OSSINDEX_PASS=your token

yarn deploy

Runs the build command to create the storybook's production static files and then deploys them to the Chromatic service with the relevant project-token where they can be viewed and tested.

yarn release

Uses Auto npm dev util package to generate a changelog and publish a "latest" release to a package manager when run from the baseBranch. For detailed setup instructions, refer here.

Auto configuration is made in the .autorc.json file in the root of the project.

Learn More

To learn React, check out the React documentation.