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

$3

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

$3

``bash
npm install @bloomreach/banana-theme
`

$3

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:

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

or when using SCSS:

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

You can then use the variables in your CSS:

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

Or in your SCSS:

`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.:

`css
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.

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

Or when using SCSS:

`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:

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

And for SCSS:

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

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

Or when using SCSS:

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

Or in your project's JavaScript/TypeScript.

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

Or in your project's HTML.

`html

`

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

`html

`

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.

$3

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.

`bash
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:

`bash
npm run lint
`

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

`bash
npm run lint:types
`

To automatically fix linting errors, run the following command:

`bash
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:

`bash
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.

`bash
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.

$3

To generate the changelog, run the following command:

`bash
npm run changelog
`

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.

$3


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:

`bash
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.

$3

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:

`bash
npm run storybook
``

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