This repository is a React Component Design System intended to act as the foundational UI layer for all OSG projects. The Scrowl project will be the first to utilize it, with the hope that we will incorporate this system into the existing projects.
This document explains the what, how, and why of the project. Details on how to best implement this Design System in your project can be found here.
This project makes use of a few packages that should be installed globally, so let’s install those first before installing all of the dependencies.
npm install yarn lerna parcel -g
In case you get the error Error: EACCES: permission denied try to install the packages using sudo permissions, your user's password may be requested:
sudo npm install yarn lerna parcel -g
Once those global packages have been installed, you can install the remaining dependencies.
yarn install
This project is built with: Typescript, React, and Sass. It uses Storybook to visualize components and provide documentation. Additionally, we make use of the VS Code extension Adobe XD to help translate designs into code. This extension is optional to install.
You can find more information about how we use the XD pipeline here.
We use Yarn to manage dependencies instead of npm. This project and others are mono repos and we make use of yarn’s workspace feature to make management easier.
Being a monorepo, this project uses Lerna to manage interdependencies as well as to publish its packages on npm.
This project uses Parcel to build the packages for distribution to npm.
This project is built with functional react components.
The React version of the front-end Framework Bootstrap userd to build OwlUI components.
There are a number of custom commands to help facilitate development and publishing.
After you install but before you begin any development you should run the setup command.
yarn run setup
This command will initialize Lerna and move the design variables/tokens into the theme component.
yarn run build:system
This command will compile and build the distribuition files of existing component and the Utils package.
To create a new component requires a lot of boilerplate. To make things a little easier, run the following command:
yarn run create:component -n [COMPONENT_NAME]
The name of the your component must contain only letters and no special characters (with the exception of _ and -) or numbers. This command will transform the component name to camelCase, as we implement this rule in our TS config. The component will be created under the packages folder and have an initial Default option.
Options also have their own boilerplate required to package and expose them through the component correctly. The name of the your component must contain only letters and no special characters (with the exception of _ and -), The easiest way to add a new option to a component is with the following command:
yarn run create:component -o [COMPONENT_NAME]@[OPTION_NAME]
Additionally, when creating a component, you can initialize it with an option:
yarn run create:component -n [COMPONENT_NAME]@[OPTION_NAME]
Component Option names are transformed to PascelCase, we do this so that the folder names match the variable names as we use React's functional components. Non-default component options use the Default option essentially as "class" to handle basic functionality and styling.
To create multiple components you can use the -m flag followed by the component names separated by , all wrapped in quotes:
yarn run create:component -m "[COMPONENT_NAME], [COMPONENT_NAME], [COMPONENT_NAME]"
If you are creating a component that makes use of another, you can add it as a dependency with the following Lerna command:
lerna add @owlui/[COMPONENT_DEPENDENCY] --scope=@owlui/[COMPONENT]
We make use of Storybook to create components in isolation. To start storybook, run this command:
yarn run start:storybook
Additionally, there is a simple web service that you can use to test out importing/consuming your component. Run this command to start the web service:
yarn run start:web
You can create a distribution build using the following command:
yarn run build:system
You can create a storybook build with:
yarn run build:storybook
You can also create a build of the web service with:
yarn run build:web
Publishing should only occur once your code has been tested, reviewed, and merged. To publish to npm, run the following command:
yarn run publish:lerna
In order to publish to npm, you will need to have an npm account and be a member of the owlui organization.
There might arise a scenario where Lerna wasn’t able to completely publish. In that case, after you make the necessary corrections, run this command to complete it:
yarn run republish:lerna
You can find more information on commands here.
There are many different design systems out there: Microsoft’s Fluent UI, Google’s Material Components, IBM’s Carbon, and Adobe’s Spectrum, just to name a few. This design system is largely inspired by those, both in terms of design but also how they have structured themselves as mono-repos.
One of the biggest differences between those and this project is that this project makes use of css (sass) modules. If you are unfamiliar with sass modules here is a good article from css-tricks. For general information on css modules check out the repo.
The folder and filename structure is modeled most closely after Fluent UI. So if you’re looking for a reference on how to name something check out that repo. In most cases the create:component command should be supplying all the foundation you need to start something new. Until we develop our own process, it is recommended to follow these contributing guidelines.
When adding a new feature or fixing a bug, make sure to branch from main and name your branch something meaningful. For example: feature/[FEATURE_NAME], bug/[BUG_NAME], hotfix/[TICKET_NAME], chore/[CHORE_NAME]. Your commits should always be related to a task in shortcut. To link the commit to the task, include the shortcut id in the message.
Example Commits
On Initialization:
INIT [sc-120] - Added boilerplate/structure for button componentOn Change/Fix:
UPDATE [sc-120] - Added basic structure for button componentOn Change Completion:
DONE [sc-120] - Button componentOn Fix Completion:
FIX [sc-121] - Button component wasn't handling events correctlyES Lint or Prettier changes:
LINT [sc-122]
Before submitting a PR make sure to run build:system, this will ensure linting and prettifying, as well as catch any typescript or general build errors.