Bloomreach Banana Theme

About

The Bloomreach Banana Theme is a design system that is used to create a consistent look and feel across all Bloomreach products. It is a collection of reusable components, guided by clear standards, that can be assembled together to build any number of applications.

The theme is built using design tokens defined in JSON files that are exported as CSS variables and SCSS variables. The design tokens are managed by the Design team and defines the core variables that consumers can use to style their components.

Getting Started

Prerequisites

• Node.js (v16 or higher)
• npm (v8 or higher)

Installation

npm install @bloomreach/banana-theme

Usage

After installing the package, you can import the variables (CSS or SCSS) into your project. We recommend using the CSS variables, since they are more flexible and can be used in any project, regardless of the CSS preprocessor that you are using. However, if you are using SCSS and require the values at compile-time (because you are using them in mixins, functions, etc.), you can use the SCSS variables instead.

The Banana theme currently exports two sets of variables: base and theme. The base variables are the core variables that are used to build the theme. The theme variables are the variables that are used to style your components. In general, you should use the theme variables in your project.

Import the theme variables into your project with:

@import '@bloomreach/banana-theme/css/theme.css';

or when using SCSS:

@import '@bloomreach/banana-theme/scss/theme.scss';

You can then use the variables in your CSS:

button {
  background-color: var(--banana-button-primary-background-default);
}

Or in your SCSS:

button {
  background-color: $banana-button-primary-background-default;
}

Note: when using Webpack, you can use the ~ alias to import the (S)CSS from node_modules, e.g.:

import '~@bloomreach/banana-theme/css/theme.css';

Debugging or customizing the theme at runtime

To accommodate these use cases, the Banana theme package exports a theme-unresolved.(s)css file that contains the unresolved variables. This file can be used to debug or customize the theme by changing the base variables. To use this file, import it into your project alongside the base file.

@import '@bloomreach/banana-theme/css/base.css';
@import '@bloomreach/banana-theme/css/theme-unresolved.css';

Or when using SCSS:

@import '@bloomreach/banana-theme/scss/base.scss';
@import '@bloomreach/banana-theme/scss/theme-unresolved.scss';

Design Token Naming Scheme

The naming scheme for the design tokens is based on the following pattern:

[element] [.variant] [.property] [.state]

For CSS, this looks like:

--banana-button-primary-background-disabled
--banana-table-row-border-default

And for SCSS:

$banana-button-primary-background-disabled
$banana-table-row-border-default

To use the Banana theme font(s) you can import the font rules in your project's CSS.

@import '@bloomreach/banana-theme/css/fonts.css';

Or when using SCSS:

@import '@bloomreach/banana-theme/scss/fonts.css';

Or in your project's JavaScript/TypeScript.

import '@bloomreach/banana-theme/css/fonts.css';

Or in your project's HTML.

<link rel="stylesheet" href="~@bloomreach/banana-theme/css/fonts.css">

Note: this will only work if you are using a bundler that supports importing CSS from node_modules. Alternatively, you can use a CDN like unpkg.com, e.g.:

<link rel="stylesheet" href="https://unpkg.com/@bloomreach/[email protected]/dist/css/fonts.css">

Note2: the font rules are not included in the theme.css file, so you will need to import the fonts.css file explicitly.

Note3: the font rules are only available in CSS, so you will need to import the CSS file even if you are using SCSS.

Development

The design tokens are defined in the tokens directory. The build.ts file defines the build process. The dist directory is where the built files are output.

Build

Build the theme using the design tokens and output them to the dist directory. It will generate the following files:

• dist/css/base.css
• dist/css/theme.css (CSS variables)
• dist/css/theme-unresolved.css
• dist/css/fonts.css (font rules)
• dist/scss/base.scss
• dist/scss/theme.scss (SCSS variables)
• dist/scss/theme-unresolved.scss
• dist/html/tokens.html (HTML table with all tokens)
• dist/assets/fonts/*.woff (font files)
• dist/assets/fonts/*.woff2 (font files)

Ensure the dependencies are installed with npm ci before running the build command.

npm run build

Lint

Lint the TypeScript and JavaScript files using the @bloomreach/eslint-config-base rules, and lint the JSON tokens using the eslint-plugin-jsonc plugin with the plugin:jsonc/recommended rules and a couple of custom rules to ensure proper formatting.

Run the following command to lint the files:

npm run lint

Since the build process skips type-checking, a separate command is available to check the types using the TypeScript compiler.

npm run lint:types

To automatically fix linting errors, run the following command:

npm run lint:fix

Note: this will only fix the linting errors that can be fixed automatically by ESLint.

Test

Run the following command to run the tests:

npm run test

Clean

Delete the dist directory.

Note: the build command will automatically clean the files in the dist directory before building, but only the files that are generated by the current build process. If you want to clean the entire dist directory, including files that were generated by previous builds, you can run the clean command.

npm run clean

Release

The release process is split into three steps: generating the changelog, bumping the version and publishing the package. Generating the changelog and bumping the version is handled by the developer, the package is then published by the CI/CD pipeline.

Changelog

To generate the changelog, run the following command:

npm run changelog <version> <fileName>

The version argument is the version that you are releasing, e.g. 0.0.1. The fileName argument is the name of the file that the changelog will be written to, e.g. CHANGELOG.md. If the file already exists, the changelog will be appended to the file. If the fileName argument is omitted, the changelog will be written to the console.

Note: the changelog will not include any Jira data other than the ticket number. For the best results, you should add the ticket title(s) manually.

Version

To bump the version, we use the npm version command. This will update the version in the package.json file, the package-lock.json file, and create a git tag.

Use the following command to bump the version:

npm version patch -m "BAN-1 Release v%s"

Note: the patch argument can be replaced with minor or major depending on the type of release. Note2: the -m argument is required to alter the commit message and specify a valid Jira ticket number. Note3: The %s will be replaced with the version number.

Publish

After bumping the version, push the changes to the remote repository. This will trigger the CI/CD pipeline to publish the package to the npm registry.

Storybook

Start storybook by running the following command:

npm run storybook

This should automatically open storybook in your default browser. If not, go to localhost:6006 in your browser