Demio React UI Components Library

As a small team, we need to build and maintain our UI library quickly and with a high level of quality. These are the tools and processes we use to achieve this.

Table of Contents

1. Project Roadmap
2. Getting Started
3. Tools
4. VS Code setup
5. Project Structure
6. Component Development
7. Styling
8. Storybook
9. Testing
10. Publishing

Project Roadmap

• add CSS variables to variables.css from Figma

• create a new components ( one MR for one component implementation)

  • <Icon /> - SVG icon component
    • all SVG styles (including color and size) should be managed by CSS

• review Rollup configuration for CSS modules to add readable class names for components(possible switch to Webpack)

• compare NewButton component with the design and replace Button with props updating at UD and Room apps

• all existing components should be aligned with the current design( + update styles using CSS variables)

• review and improve test coverage

Getting Started

To get started with the Demio React UI Components Library, follow these steps:

1. Clone the repository: git clone [email protected]:banzai_io/demio/demio-ui.git
2. Install dependencies: npm install
3. Run Storybook: npm run storybook and open http://localhost:6006 in your browser if it doesn't open automatically.

Tools

• TypeScript - strongly typed programming language that builds on JavaScript
• Rollup - module bundler like Webpack. While webpack and Rollup can achieve similar outcomes based on their configurations, webpack is commonly utilized for bundling applications, whereas Rollup is especially well-suited for bundling libraries.
• Storybook - UI library development environment and component showcase
• Maybe chromatic - visual regression testing for Storybook
• Prettier - Code for matter
• ESLint - Code linter
• Jest and React Testing Library - unit testing
• Rudix-UI
  • we can import only the components we need - this is important for bundle size
  • as it is unstyled, we don't need to overwrite styles like in Ant Design or Material UI
  • it has a high level of accessibility and customizability
• CSS Modules - CSS modules allow us to write CSS in a modular way. Each component has its own CSS file, and class names are scoped to the component. This prevents CSS collisions and makes it easy to find and update styles.

Project Structure

The project follows a modular structure to make organizing and maintaining components easy. Key directories include:

• src/components: Contains individual UI components.
• src/icons: SVG icons.
• src/index.css: Global styles.
• src/variables.css Global CSS variables.
• src/stories: global Storybook stories.
• .storybook: Storybook configuration files.

VS Code setup

• install Component Creator extension to create new component from template (.vscode/cch-template/React FC (ts, css, story, test)/{{pascalCase}}) with one command
• install ESLint extension to lint your code
• install Prettier extension to format your code

Component Development

All changes of Demio-UI should be done through MR!

When creating new components, follow these steps:

1. Create a new component by Component Creator plugin with the name of your component in PascalCase.
2. Check if this component already exists in the Radix UI library. If it does, use it instead of creating a new one.
3. If you decide to add a new npm package, share the results of your research with the dev team.
4. Add your component to src/{ComponentName}/{ComponentName}.stories.tsx file.
5. Write tests for your component in src/{ComponentName}/{ComponentName}.test.tsx file.
6. After development is finished - export your component from src/index.ts file.

Code recommendations:

• one component -> one file with all related files (CSS, tests etc.)
• try to make components as simple as possible(try make it stateless if it possible)
• group hooks by type (state, ref, effect, etc.)
• if you write a comment - try to make it short and clear, don't add obvious comments in code like // render component or //hooks
• component should accept cssClass as a prop and apply it to the root element
• use consistent naming across the whole library's components (i.e., className, width, isOpen, etc.).
• try to keep backward compatibility while it doesn't cause unnecessary complications (all the corner cases have to be discussed)
• every important node of the component has to have a unique class name formatted as "demio-ui-${component-name}-${element}" (for example, "demio-ui-modal-close-button", "demio-ui-modal-title", "demio-ui-modal-content", etc.). This is important for testing and styling purposes.
• Avoid inline styling. If the component accepts the inline style - it should be applied to a component.
• Props naming. Use consistent naming across the whole lib's components (i.e., className, width, isOpen, etc.).

Styling

1. Every CSS variable should start with the --demio-ui- prefix. For example, --demio-ui-color-primary.
2. The CSS variable name should be in the kebab-case.
3. Global CSS variables should be defined in the src/variables.css file. These variables include the color palette, font sizes, font families, border radius, and more. Use them in your components.
4. Component-specific styles should be defined in the src/components/{ComponentName}/{ComponentName}.module.css file. Use global css variables in your component styles to set up local variables. For example:

--demio-ui-button-color: var(--demio-ui-color-primary);

.button {
  color: var(--demio-ui-button-color);
}

5. Use CSS variables to manage component variants without property duplication. For example:

--demio-ui-button-color: var(--demio-ui-button-color-primary);

.button {
  color: var(--demio-ui-button-color);
}

.button--secondary {
  --demio-ui-button-color: var(--demio-ui-button-color-secondary);
}

The same variables can be used to override component styles in your application. For example:

.parent .demio-ui-button {
  --demio-ui-button-color: blue;
}

For an example of component styles, look at the src/components/NewButton/Button.css file.

Storybook

Storybook is a UI library development environment and component showcase. It allows us to develop components in isolation, document them with examples, and test them in different states and configurations.

1. Try to cover the main component variants in Storybook stories.
2. Add all argTypes and args to your component stories.

We have automated deployment of Storybook to CDN on every push to the main branch.

Testing

We use Jest and React Testing Library for unit testing. We aim to have 100% test coverage for all components. Tests are run automatically on every commit or push. Testing commands:

• npm run test - run all tests
• npm run test:watch - run all tests in watch mode

Publishing

When publishing a new version of the library, follow these steps: Try to follow Semantic Versioning rules and Conventional Commits.

• update the CHANGELOG.md file with the description of the changes
• npm version <major|minor|patch> - bump the version
• npm publish - publish to NPM (only from main branch)
• push changes to the git
• share CHANGELOG.md changes with the team in Slack dev channel

Git hooks

We use pre-commit and pre-push git hooks to run tests and linting before committing and pushing code. This ensures we don't commit code that doesn't pass tests or linting. Hooks are managed by husky and lint-staged.