--- title: "How to Work on the Component Library" --- > Documentation Index > Fetch the complete documentation index at: https://contribute.freecodecamp.org/llms.txt > Use this file to discover all available pages before exploring further. # How to Work on the Component Library :::tip You'll need this guide if you're building or modifying user interface components for the freeCodeCamp platform. If you're working on curriculum, documentation, or other areas, you can skip this guide. ::: Welcome to freeCodeCamp's `ui` library. The components are built mostly from scratch with basic HTML elements and [Tailwind CSS](https://tailwindcss.com/). :::note We have our own component library which helps standardize our UX/UI patterns and improve accessibility. The project is stored in [this GitHub repository](https://github.com/freeCodeCamp/ui). ::: 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 or modifying a component, review the existing components in the `ui` library and document the behavior, appearance, and accessibility requirements for your use cases. Check which HTML elements and ARIA attributes are appropriate and how users will interact with the component using a keyboard. When modifying an existing component, inspect its current usages so that you can preserve the behavior and styles its consumers rely on. Design the props interface around the component's requirements and the patterns used by the `ui` library. For an existing component, consider how interface changes will affect its consumers. For a new component, use related `ui` components as references and expose the props its consumers need. 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. ## Implementing the Component A new component can be created using the following command from the root directory: ```bash pnpm run gen-component MyComponent ``` The command will generate a new folder inside the `ui` project, 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 its states. :::note Color definition can be found in the [`colors.css` file](https://github.com/freeCodeCamp/ui/blob/main/src/colors.css). A color is only available for use if it is added to the [`tailwind.config.js` file](https://github.com/freeCodeCamp/ui/blob/main/tailwind.config.js) under the `colors` property. ::: ### Useful Links - [Tailwind CSS Configuration](https://v3.tailwindcss.com/docs/configuration) - [UI component implementations, stories, and tests](https://github.com/freeCodeCamp/ui/tree/main/src) ## 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: ```bash pnpm run storybook ``` The Storybook page is available on `http://localhost:6006`. ## Writing Unit Tests We use [React Testing Library](https://testing-library.com/docs/react-testing-library/intro/) 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: ```bash pnpm run test ``` ## Proposing a Pull Request (PR) After you've committed your changes, check here for [how to open a Pull Request](/how-to-open-a-pull-request/). ## Adding Packages to the UI Library We restrict adding new packages to the UI Library 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: ```bash pnpm add package_name ``` ## Useful Links - [Testing for Accessibility](https://testing-library.com/docs/dom-testing-library/api-accessibility) - [Order of priority of React Testing Library's queries](https://testing-library.com/docs/queries/about/#priority) - [Common mistakes with React Testing Library](https://kentcdodds.com/blog/common-mistakes-with-react-testing-library) Source: https://contribute.freecodecamp.org/how-to-work-on-the-component-library/index.mdx