Contributing to Oxygen UI: A guide

3 min readAug 20, 2023

In my previous article, I spoke about the new UI library by WSO2, Oxygen UI, and we would love for you to contribute to it and help make it even better than it is today!

Introduction

Oxygen UI is built by wrapping Material UI (MUI) components.

It includes a number of atomic, compound and custom components for you to use in your application.

Setting Up the development environment

Mandatory Software & Tools

To build and write code, ensure you have the following set of tools in your local environment.

Note — This project requires atleast NodeJS v14.6.x or above to work.

pnpm

Note — This project adopts Lockfile v6. Hence, it’ll not work with pnpm v7 or lower. If you do not have the latest pnpm installed, update to the latest pnpm version using the following command.

pnpm install -g pnpm@latest

Setting up Development Tools

These developer tools will help you have a better developer experience since they’ll help debug code, etc.

React Developer Tools

Download for Chrome

Download for Firefox

ESLint

Download for Webstorm

Download for VS Code

Stylelint

Setup for Webstorm

Download for VS Code

ShellCheck

ShellCheck Core

Download for VS Code

NX Console

Download for VS Code

Download for Web Storm

Setting up the Source Code

Fork the repo

Fork the repository.
Clone your fork to the local machine.

Replace <github username> with your own username.

git clone https://github.com/<github username>/oxygen.git

3. Set the original repo as the upstream remote.

git remote add upstream https://github.com/wso2/oxygen.git

Install the dependencies

From the root of the project, execute the following command to install the project dependencies with pnpm.

pnpm install

Build the project

From the root of the project, execute the following command to build the project.

pnpm build

Adding Components to Oxygen UI

Use existing components and patterns if they suit your intended functionality.

Use atomic components to build compound or custom components in your application’s source code if they are specific to your use case/app.

The definition of done (DOD) of the development of a component is defined as follows.

Implementation of the component along with the supplementary hooks, utils, etc.
Unit Tests (With Jest).
Visual Testing & Accessibility Compliance Testing.
Story with proper documentation.

⭐️ Components must be added to the react package.

cd packages/react

⭐️ Add the component in the component development progress task and tag yourself so everyone knows you are working on the component.

⭐️ Develop

Wrapping MUI Components

MUI components must be wrapped and used. Example.

Adding Custom Components

If there are custom components to be added,

Outline the requirement and reusability of the component and justify why it must be included in Oxygen UI in the PR.
Add Figma design files if necessary.

Once the component is added, update the component development progress task.

✨ General guidelines to follow when developing

1. Always use `forwardRef`

Example

2. The written component should be polymorphic if the wrapped component has a `component` property.

MUI allows you to change the root element that will be rendered via a prop called component.

Check in MUI documentation’s Component API whether the component has a `component` property.

> MUI Doc Confirmation

> Sample Implementation

3. Ensure the Accessibility checks are passed in the component’s Story.

4. Ensure that there are no console errors logged by the component.

5. Follow guidelines when designing icons.