@bliss-design-system/workbench NPM

Bliss Workbench Toolkit

This repository is a CLI tool for constructing different aspects of the Bliss Design System toolkits and components.

Installation
Usage
Structure
Contributing
Troubleshooting

📦 Installation

To use the workbench, install the package in the root of your Bliss toolkit:

yarn add -D @bliss-design-system/workbench

🏎 Usage

The workbench has a few commands that should be run as a command under a package.json script.

Component Commands

The workbench component command houses two further commands; boilerplate and styles.

`workbench component boilerplate`

This command will initialise a boilerplate folder structure for a new component, and should only be used within the Component toolkit.

The full command is:

workbench component boilerplate

But you can call

yarn boilerplate

Within the component toolkit root, and you'll be lead through a series of prompts to name your component and confirm the folder structure that will be built. This command must be called in the root of the toolkit, and all new components will be added to the packages/ directory.

`workbench component styles`

Given the decisions that have been made around Bliss' construction of web components, we've opted not to use bundlers and be as minimalistic as possible. However, because we rely on Sass for our styling (see the Tokens toolkit), we need to transpile that into CSS. But since lit-element, the tool we rely on to create web components, doesn't understand CSS, we also need to convert that CSS into a file our component can use.

All style commands must be run inside the package you are working on (e.g. packages/button), and that package requires a src/styles/index.scss file to be compatible with workbench.

ℹ️ Note: if you have initialised your component with workbench component boilerplate (which you should!), src/styles/index.scss will have been created for you, along with src/styles/index.css and src/styles/index.css.ts.

To generate the CSS from the SCSS and the *.css.ts from the CSS run:

workbench component styles

You can run the build command in watch mode (-w or --watch) to have all of your files updates as you write Sass.

🫕 Contributing

This toolkit is intended mostly for the Bliss team, but if you find that you use it and would like to contribute, please open an issue with your suggested change. This issue will automatically be added to the Bliss Proposal Board. Once that is accepted, either the Bliss team will work on it or you can make changes locally.

If you would like to contribute, run the following:

# Clone and move into this repository
git clone https://gitlab.com/bliss-design-system/workbench.git
cd workbench

# Install the dependencies
yarn

Reporting a bug

Notice something off? Please open an issue using our Bug Report template and fill in as many details as possible.

Testing locally

Because the workbench contains CLI scripts, you need to run it in a node environment to test it locally.

To launch your node environment, run node along with a path to the entry file:

node path/to/workbench/commands/workbench.js

Then, you can follow that with any of the workbench commands you'd like to test.

For example, to test the workbench component boilerplate script, create an empty directory called packages and then run the following:

node path/to/workbench/commands/workbench.js component boilerplate

Committing

We follow the Conventional Commits specification, meaning that you'll be prompted to fill out a descriptive message when you commit. We also use these commits to manage our releases, so we appreciate details.

As a guideline for this toolkit, we recommend the following:

If you are correcting a bug in a command, this qualifies as a patch version (fix)
If you are adding new command, this qualifies as a minor version (feat)

⚠️ If you are removing or renaming a command, please speak with the Bliss team, as this will qualify as a major version and involves a breaking change.

Opening a merge request

When you're ready to open a merge request, please use a descriptive title and fill out the provided template.

The team will be notified, but it helps to post your merge request in #bliss_support.

🙃 Troubleshooting

We'll fill this section out as we go and as issues are raised. But if you haven't found what you're looking for, get in touch via bliss@bryter.io or via the #bliss_support Slack channel ✨.