@caspeco/casper-ui-library

Caspeco's UI component library, built on top of Chakra UI.

👉 The usage documentation can be found at https://caspeco.github.io/casper-ui-library**

Local development

To build this project you need to have Node.js installed.

Commands

All commands are run from the root of the project, from a terminal.

Preview locally in another project

1. Build local development version (see above).
2. In the consuming app, run npm install --no-save ./relative/path/to/this/directory (no trailing slash).
   • For example: npm install --no-save ../../casper-ui-library/packages/casper-ui-library

Now when you make a change in the component library, it should rebuild automatically and the consuming app's HMR should kick in and reload the page (preserving state is not possible as the entire library is rebuilt).

To unlink again you just need to run npm install in the consuming app. If it fails, you may need to delete node_modules first.

If you get an error about duplicate react versions, make sure this is in the vite.config.ts in the consuming app:

import path from "node:path";

export default defineConfig({
    // ...
    resolve: {
        alias: {
            react: path.resolve("./node_modules/react"),
        },
    },
});

Visual Regression Tests

Visual regression tests catch unintended UI changes by comparing screenshots of component variants to committed baselines in __screenshots__/. They run with Playwright in Docker to ensure consistent rendering across different development environments and CI.

Requirements: Docker must be installed and running.

Running tests:

• npm run test:visual - Runs all visual tests
• npm run test:visual:ui - Opens the HTML report viewer
• npm run test:visual:update - Updates baseline screenshots after intentional UI changes

[!TIP] CI fails but local passes?

1. Go to the visual-tests job in GitHub Actions
2. Download and extract the HTML artifact under the Upload visual test report step
3. Run npx vite preview --outDir . in the extracted directory to see diff report from CI

You may need to tweak the pixelmatch comparator options if you see false positives due to anti-aliasing or sub-pixel rendering differences. See existing tests for examples.

Contributing

1. Make sure your repository is up to date.

   git pull
   

2. Create a new branch and make your changes there. Preferrably use a branch name that includes any related Jira issue and some short descriptive name.

   git checkout -b UTF-837-add-checkbox-component
   

3. Make your changes. Don't touch the version field in package.json, CI handles it.
4. Open a pull request using the template and assign a reviewer.
5. If the change should be released, add one of the labels bump-patch, bump-minor or bump-major (following Semantic versioning). The version reflects API changes only (e.g. removing a prop → MAJOR, adding a prop → MINOR, no public API changes → PATCH). UI changes are NOT API changes.
6. If the PR makes significant changes to the UI (e.g. changes the sizes for all buttons), clearly announce this in the Mattermost channel.
7. After approval, merge the PR. If it has a bump label, CI bumps the version, commits it to main and publishes to npm. @caspeco/casper-ui-css is released the same way with its own bump-css-* labels. The documentation website is always rebuilt.

How to add new icons

1. Export from Figma In the Figma Icons document, choose File → Export and export all icons as SVG.

2. Clean icon assets From the repository root, run npm run clean:icons to delete the existing assets in lib/components/icon/assets and the generated React icon components in lib/components/icon/icons.

3. Update assets Drop in the exported SVGs. Verify changes with git diff.

4. Generate components From the repository root, run npm run generate:icons to generate React components for each icon.

5. Format generated React icon components The generated icon components may not be formatted correctly initially. If that happens, run npm run prettier:fix.