@bloomreach/banana-theme

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.

This project is currently in development. The goal is to start small and build up the system over time. The first step is to create a set of design tokens that are exported to different platforms, starting with CSS variables.

Getting Started

Prerequisites

• Node.js (v18 or higher)
• npm (v9 or higher)

Installation

npm install @bloomreach/banana-theme

Usage

After installing the package, you can import the CSS variables into your project. 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's CSS with:

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

You can then use the variables in your CSS.

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

Debugging or Customizing the theme at runtime

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

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

Design Token Naming Scheme

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

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

e.g.:

--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 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/banana-theme@0.0.2/dist/css/fonts.css">

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/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.

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.