Catalyst Design System

Package	Description	Status	Docs
@haiilo/catalyst	Core web components		README
@haiilo/catalyst-tokens	Style Dictionary design tokens		README
@haiilo/catalyst-angular	Angular bindings for components		README
@haiilo/catalyst-angular-formly	Angular custom types for Formly		README
@haiilo/catalyst-react	React bindings for components		README

Setup

Please take a look at the official design documentation at https://design.haiilo.com and follow the Getting Started guide to learn how to setup your project locally.

When installing dependencies with npm or Yarn Classic, all packages are hoisted to the root of the modules directory. As a result, source code has access to dependencies that are not added as dependencies to the project. In the past, this has resulted in a number of indeterministic errors, that are very hard to debug. As a consequence, this monorepo uses pnpm as a package manager. Please follow the installation guide to get started.

When working with pnpm, we recommend to set the following aliases in your .bashrc, .zshrc, or config.fish:

alias pn='pnpm'
alias pnr='pnpm run'
alias pni='pnpm install'
alias pns='pnpm run start'
alias pnb='pnpm run build'
alias pnt='pnpm run test'

Release

Creating a new version via CI (recommended)

The entire release process is automated via Google's release please action. Release Please automates CHANGELOG generation, the creation of GitHub releases, and version bumps for all projects of the monorepo. As of now, the version numbers of all projects are kept in sync. That means that releasing a new version will increase the version of every project, even if the project has not been changed.

Every commit that is prefixed with conventional commit guidelines triggers the creation (or update) of a release PR in the GitHub project. The PR is labeled with "autorelease: pending". These Release PRs are kept up-to-date as additional work is merged. When you're ready to tag a release, simply merge the release PR. When the Release PR is merged, release-please takes the following steps:

• Updates the CHANGELOG file(s), along with other language specific files (for example package.json).
• Tags the commit with the version number.
• Creates a GitHub Release based on the tag.

Additionally, the new release is directly published to npm.

Manually creating a new version (not recommended)

All projects in the repository are using semantic-release and define helper scripts in the respective package.json files. To create a new release bundle (i.e. release all projects in a new version), simply use the following combination of utility scripts provided in the top level package.json:

• Run pnpm run release:{patch|minor|major} to create a new version in every project of the repository.
• Run pnpm run build to build all projects.
• Run pnpm install to install dependencies for every project.
• Run pnpm run publish to publish every project to npmjs.com.
• Run git push --follow-tags origin main to push your changes.

Note: Make sure you are logged in with your npm account and you have permissions to release under the haiilo organisation. Otherwise contact one of the collaborators to request access.

Local development

Since the catalyst project is monorepo and managing multiple packages via workspaces, we can't simply refer the output folders in file protocol, we need to prepare it first and resolve workspace dependencies.

Steps:

1. Make changes;
2. Run pnpm build;

Extra steps for testing the changes in angular package:

1. Run pnpm install again;
2. For
   • angular Go to /angular/dist/catalyst;
   • angular-formly Go to /angular/dist/catalyst-formly;
3. Run pnpm pack;

In consumer project: In package json replace those packages you want to test with file protocol path:

"@haiilo/catalyst": "file:../../../catalyst/core",
"@haiilo/catalyst-angular": "file:../../../catalyst/angular/dist/catalyst/haiilo-catalyst-angular-13.4.0.tgz",

or

"@haiilo/catalyst": "file:../../../catalyst/core",
"@haiilo/catalyst-react": "file:../../../catalyst/react/dist",

Pre-releases

Warning

Making a successful pre-release requires several careful manual steps, if you are not sure, better to go with regular release.

At the moment Release Please is used for pre-releases as well as for releases

1. Update beta branch with main branch (or alternatively make sure that all commits from main are contained in beta);
2. Create feature branch from beta branch;
3. Make the changes in you feature branch, open PR, wait for green pipeline and approve, merge your PR to beta;
4. Release Please creates or updates already existed pre-release PR.
5. When you're ready to tag a pre-release, simply merge the pre-release PR.

IMPORTANT! After testing of your pre-release branch is done you need to release you changes.

6. Create PR beta > main. While merging make sure the commit message is conventional. Otherwise, your changes will be ignored by regular release.
7. Go with regular release steps.

Screenshot tests

Visual regression tests live alongside components as *.screenshot.tsx files and use toMatchScreenshot() to compare against reference images stored in __screenshots__ directories.

Both local and CI reference screenshots are committed to the repository so that developers can run and verify screenshot tests on their own machines without needing a CI run.

• Screenshots generated on macOS (local development) have the suffix -darwin.
• Screenshots generated on Linux (CI / ubuntu-latest) have the suffix -linux.

Running screenshot tests locally

Screenshot tests are intentionally excluded from pnpm run test. To run them locally:

pnpm run test:screenshot        # from core/

To update the local (macOS) reference screenshots after an intentional visual change:

pnpm run test:screenshot:update # from core/

This regenerates the -darwin screenshots and commits them alongside your changes.

Creating or updating CI reference screenshots

When you add a new screenshot test or intentionally change a component's appearance, regenerate the CI reference images using the Update Screenshots GitHub Actions workflow:

1. Push your branch to GitHub.
2. Go to Actions → Update Screenshots → Run workflow and select your branch.
3. The workflow runs on ubuntu-latest, commits the updated -linux __screenshots__ files back to your branch, then triggers the core CI workflow to verify everything passes.

Reviewing failed screenshots in CI

When a screenshot test fails in CI, the actual and diff images are uploaded as an artifact named screenshot-diffs. Download it from the failed workflow run under Actions → Core → <run> → Artifacts.

Code contributors

This project exists thanks to all the people who contribute.

License

The license can be found in the LICENSE file.