CRUK Chakra Components 🎨

A Chakra UI v2 based component library that provides styled components following the Cancer Research UK Helix design system 🧬.

📚 Quick Links & Documentation

• Component Documentation (Storybook)
• Full Documentation (Style guide, Theming, Testing and more)

Using the Library

Quick Start

Depending on your project, you might install the library in the project root directory, or in client:

# Install the package
npm install @cruk/chakra-components

# Install peer dependencies (if you don't already have them)
npm install @chakra-ui/react @emotion/react @emotion/styled framer-motion

NOTE: Not all projects use npm as their package managers - use whichever is appropriate for your project.

Basic Setup

Once added to the project, you can use the ChakraBaseProvider to wrap your application and provide styled based on the crukBrand theme.

import type { AppProps } from "next/app";
import { ChakraBaseProvider, crukBrand } from "@cruk/chakra-components";

const App = ({ Component, pageProps }: AppProps) => (
  <ChakraBaseProvider theme={crukBrand}>
    <Component {...pageProps} />
  </ChakraBaseProvider>
);

export default App;

• 📖 Styling documentation
• 📖 Theming documentation

Contributing 🛠️

Development Setup

After cloning the repository, install the dependencies:

# Clone and setup
git clone https://github.com/CRUKorg/cruk-chakra-components
cd cruk-chakra-components
npm ci

# Start Storybook
npm run storybook

Quick Test

npm run test     # Unit tests
npm run test-ct  # Component tests

Deployment and Releases 🚀

Release Process

This library uses semantic-release with GitHub PR labels to automate versioning and package publishing.

Branch Strategy

• dev branch: Configured as a prerelease branch with the dev prerelease tag
• main branch: Configured as a regular release branch

Release Requirements

Important: Only pull requests with the release label will trigger a release. The version type is determined by additional labels.

Creating a Release

1. Create your pull request and add labels:

   Required label:

   • release - Must be present to trigger any release

   Version labels (choose one):

   • breaking or major - Major release (v1.0.0 → v2.0.0)
   • minor - Minor release (v1.0.0 → v1.1.0)
   • patch - Patch release (v1.0.0 → v1.0.1)

   Optional label:

   • force - Forces a release even when semantic-release detects no changes

   If only the release label is present, it defaults to a patch release.

2. For main branch releases: Obtain ServiceNow approval

   Important: All releases to the main branch require an approved ServiceNow change request before merging. This is mandatory for production deployments.

3. Merge your PR to the appropriate branch:

   Important: When merging, do NOT modify the merge commit message. The PR label analyzer requires the default message format "Merge pull request #XXX from..." to extract the PR number. Changing this message will prevent the release from being triggered.

   • Merge to dev for prerelease versions (no ServiceNow required)
   • Merge to main for standard releases (ServiceNow approval required)

4. The semantic-release system will automatically:

   • Read the PR labels
   • Determine the appropriate version bump
   • Generate release notes
   • Publish to npm
   • Create a GitHub release

Examples

✅ Will trigger a minor release:

• Labels: release, minor

✅ Will trigger a patch release:

• Labels: release, patch
• Labels: release (defaults to patch)

✅ Will trigger a major release:

• Labels: release, breaking

✅ Will force a release (even with no detected changes):

• Labels: release, force, minor
• Labels: release, force, patch

❌ Will NOT trigger any release:

• No release label present

Manual Release

If needed, you can manually trigger a release:

npm run release

Resources 📖

• Component Examples (Storybook)
• Full Documentation (Style guide, Theming, Testing and more)
• Need help? Message us on Slack
• svg to chakra component converter- converts svgs into format needed for tsx files in static/icons

📄 Licence

MIT © Cancer Research UK