freeCodeCamp/docs/how-to-work-on-the-component-library.md

Welcome to freeCodeCamp's ui-components library. The components are built mostly from scratch with basic HTML elements and Tailwind CSS.

How to Work on the Component Library

Note

freeCodeCamp has been using Bootstrap components in the UI. However, we are moving away from it and building our own component library, which helps standardize our UX/UI patterns and improve accessibility. The project is tracked in this GitHub issue.

The following steps are recommended when working on a new component:

• Research and planning
• Implement the component
• Display the use cases on Storybook
• Write unit tests

Researching and planning

Before building a component, you need to research and document on how the existing version behaves and looks, to ensure that the new one has matching styles and supports all the current usages. In order to meet the web accessibility requirements, you should also pay attention to the accessibility aspect of the component, see which HTML elements and ARIA attributes are used under the hood.

Once you have gathered enough information about the component, you can start thinking about the props interface. Ideally, the interface should be as similar to the current version as possible, to ease the adoption later on. Since we are using Bootstrap components, the simplest approach is to mimic their implementation.

We prefer smaller pull requests rather than a large one, because they speed up the review time and reduce cognitive overload for the reviewers. For that reason, you should think about how you would break down the implementation and come up with a delivery plan.

We recommend opening a separate GitHub issue for each component and include all the notes in the issue description. It can be used as a place to host all of your working notes, as well as a way to communicate the approach with the reviewers. We will use the issue thread for further discussion if needed. The issue for Button component can be used as a reference.

Implementing the component

A new component can be created using the following command from the root directory:

cd tools/ui-components

pnpm run gen-component MyComponent

The command will generate a new folder inside the ui-components directory, with the following files:

File name	Purpose
index.ts	It is used for exporting the component and its types.
my-component.stories.tsx	It is used for demoing the component on Storybook.
my-component.test.tsx	It is a test file.
my-component.tsx	It is where we implement the component.
types.ts	It is where we locate the component's interface and types.

Each component is different, but in general a component should:

• Support forwarding ref
• Be styled for both light and dark themes
• Be styled internally based on their props (the consumers should not need to restyle the component with the className prop)
• Utilize the built-in styling system from Tailwind instead of having custom styles

Using colors

There are two color "layers" in the component library:

• The base layer, where the color names describe what the colors are, e.g. gray00, blue50
• The semantic layer, where the color names describe what the colors are for, e.g. foreground-primary, background-danger

Generally when using colors in a component, you should choose semantic variables over the base ones. There are exceptions, however, specifically when you are styling the component's states such as hover, active, disabled, etc. In these cases, we recommend using the base variables directly instead of creating new semantic variables, since each component can have different styles for their states.

Note

Color definition can be found in the colors.css file. A color is only available for use if it is added to the tailwind.config.js file under the colors property.

Useful links

• Tailwind CSS Configuration
• React Bootstrap v0.33 Docs
• Bootstrap 3.3.7 stylesheet
• React Bootstrap current implementation
• React Bootstrap current tests

Displaying the use cases on Storybook

Use cases of the component should be added to the Storybook file (.stories.tsx).

To start Storybook, run the following command from the root directory:

pnpm run storybook

The Storybook page is available on http://localhost:6006.

Writing unit tests

We use React Testing Library to write unit tests. The tests should assert that the components behave as expected and are accessible.

To run tests against the component library, run the following command from the root directory:

pnpm run test-ui-components

Adding packages to the UI-Component library

We restrict adding new packages to the UI Components to help with the project's maintainability. In the rare chance that you think a dependency is needed, please check with the maintainers first and then use the following command to add a package:

cd tools/ui-components 
pnpm add package_name

Useful links

• Testing for Accessibility
• Order of priority of React Testing Library's queries
• Common mistakes with React Testing Library