Bliss Tokens Toolkit

This repository exists as a single source of truth for Bliss design tokens.

Design tokens define the visual foundations of the Bliss Design System - including 🎨 colors, ⌨️ typography, ↔️ spacing, and more. These are values that are determined by the designs of the BRYTER brand and product.

• Installation
• Usage
• Structure
• Contributing
  • Reporting a bug
  • Committing
  • Opening a merge request
• Troubleshooting

📦 Installation

To use the design tokens, install the package in the root of your client-facing application:

yarn add @bliss-design-system/tokens

🏎 Usage

After installation, load the design tokens directly into your Sass stylesheet with the @use command:

@use '@bliss-design-system/tokens';

From there, you can access the values using the tokens prefix:

@mixin example() {
  width: tokens.$space-6;
  font-size: tokens.$font-size-8;
  font-weight: tokens.$font-weight-bold;
}

📁 Structure

You'll find the JSON files describing the design tokens in the src folder, sorted by category. Within each category, there will be an options.json and/or patterns.json file.

Options supply the foundations for the visual elements. These contain defined yet obscure values and transform them into variables that have meaning.

An example of color options:

"gray": {
  "0": { "value": "#F4F4F6" },
  "100": { "value": "#E2E5E9" },
  "200": { "value": "#CCD0D7" }
}

Patterns take the available options and turn them into decisions. These tokens make an explicit decision about which of the option tokens to use for specific implementations.

Here's what it'd look like if we provided tokens for text colors based on interactive state:

"color-action-text-primary-default" : gray.0,
"color-action-text-primary-hover" : gray.500

🫕 Contributing

If you'd 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/tokens.git
cd tokens

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

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 updating the values of a token, this qualifies as a patch version (fix)
• If you are adding new tokens, this qualifies as a minor version (feat)

⚠️ If you are removing or renaming tokens, 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 [email protected] or via the #bliss_support Slack channel ✨.