Hi, thanks for taking an interest in contributing to the UI Kit repository. We welcome any kind of contribution, from reporting issues or idea to submitting pull requests for bug fixes, improvements, new features, etc.
Please take a moment to review this document in order to make the contribution process straightforward and effective for everyone involved.
The UI Kit repository primarily contains UI components that implement commercetools Design System. The following assumptions and criteria are valid:
- Components are ideally agnostic to any domain-specific functionality or behavior.
- Components are meant to be easily composed with each other.
- Components use Design Tokens defined in the Design System.
- Components are implemented following UX Guidelines.
This repository is managed as a monorepo, meaning it contains multiple (sub)packages located in the packages directory.
packages/
components/
buttons/
...
Some of the packages are used as "presets" and live in the presets folder. Those simply group other packages together to avoid importing each single one of them, for example inputs, buttons, etc.
At commercetools we use the following development tools:
We use Yarn workspaces to manage dependencies between multiple packages.
We use Jest as the main framework for testing. Additionally, we take advantage of the Jest runners to run other tasks such as ESLint.
We rely on Prettier to consistently format our code.
We prefer to implement our UI components using TypeScript. This has the benefit of provide packages with type declarations, thus a better developer experience, but also to have the codebase more maintainable and less error-prone.
We use Storybook to provide a playground UI to showcase and play around with the UI components.
We rely on Preconstruct to build the packages.
Commit messages should follow a conventional commit format.
Different forms of testing occur an different levels to ensure the workings of UI Kit.
Components in UI Kit are integration tested to ensure they meet requirements over time. For this react-testing-library is used. Using Behavior driven development and Jest you specify your acceptance criteria and write expectations based on the component鈥檚 state. There are numerous examples in code for existing components. There are many examples of tests when you search for .spec.js files.
It is crucial for a Design System to not introduce visual regressions. To achieve this UI Kit performs Visual Regression Testing using Percy. Every component must have a so called visual specification alongside it. This is just a React component conveniently defining all visual states such placeholder being filled, a warning being triggered or a component being in readonly state. An example can be found here. This specification is rendered and sent to Percy via a GitHub Action. Once regressions are detected, they will be reported on a subsequent change and have to be approved by a UI/UX Designer.
In general, it's a good idea to open an issue first, no matter if it's a bug report, a new feature, etc. Doing so allows maintainers and other contributors to be aware of the context when an associated pull request is provided. It also gives a chance to provide early feedback and suggestions on what the pull request should focus on and what the expectations, avoiding unnecessary work during a pull request.
When planning to work on a new feature/component, we strongly recommend to start with an issue, describing the use case, the expected interactions, etc. Ideally, some basic design or sketches should be provided to give a clear idea of how the component looks like.
If possible, wait for other maintainers or contributors to give a thumbs up before starting development, to make sure the requirements are accepted.
Good pull requests, such as patches, improvements, and new features, are a fantastic help. They should remain focused in scope and avoid containing unrelated commits.
If possible, please try to provide a related issue first, where the topic is discussed and agreed upon before starting to work on that. This is helpful for both you and the maintainers to be familiar with the changes beforehand.
- Clone the repository.
- Run
yarnin the root folder to install the dependencies.
At this point you can start working on the UI components in the packages folder.
Some useful commands to work with the repository:
yarn testandyarn test:watchyarn typecheckyarn buildyarn lint
When you develop UI components, it's recommended to start Storybook.
yarn start
The UI Kit uses react-intl to define and consume messages. The source/core messages are usually defined in messages.js files, co-located to each component that requires messages.
The translations for the supported languages exist in the /i18n folder. We do not use any automated translation software.
After adding new messages, you need to run yarn extract-intl. This will modify the language files in /i18n by adding empty translations for the message keys.
If you want to modify an existing translation, you will need to manually edit the related files in /i18n.
To add new icons in the @commercetools-uikit/icons package:
- Add the raw SVG file to the
packages/components/icons/src/svgfolder. Make sure the file name ends with.react.svg. - Run the
yarn generate-iconscommand to generate the React component files. The components are generated using thesvgoCLI and the template filepackages/components/icons/src/templates/icon.styles.tsx.
commercetools ui-kit uses changesets to do versioning and creating changelogs.
As a contributor you need to add a changeset by running yarn changeset.
The command will prompt to select the packages that should be bumped, their associated semver bump types and some markdown which will be inserted into the changelogs.
When opening a Pull Request, a changeset-bot checks that the Pull Request contains a changeset. A changeset is NOT required, as things like documentation or other changes in the repository itself generally don't need a changeset.
commercetools ui-kit uses changesets to do versioning and publishing a release.
A Changesets release GitHub Action opens a Version Packages Pull Request whenever there are some changesets that have not been released yet.
When the Version Packages Pull Request gets merged, the Changesets release GitHub Action will automatically trigger the release.
On main branch, we automatically publish canary releases from CI to the canary distribution channel, after the build runs successfully.
Canary releases are useful to test early changes that should not be released yet to next or latest. They are automatically triggered and released after a Pull Request merged into main.
Note that canary releases will not create git tags and version bump commits.