Developers guide

This section aims to show you around, so you can feel yourself comfortable while browsing the code and contributing to the project.

Here we assume you've already read our CONTRIBUTING.md documentation and know the prerequisites. So make sure to read that first if you still haven't.

Thank you for being interested in our tools!

Table of contents

• Directory structure
  • components/
  • helpers/
  • img/
  • js/
  • scss/
    • Positioning and responsive utils
    • Typography mixins
  • tokens/
  • docs/
• Design tokens
  • Tokens definition and structure
  • Build script and configuration
• UI kit versioning
  • Major release
  • Minor release
  • Patch release
  • Accessing the releases
• Adding components
• Building from sources
  • Webpack script
• Linters
• Visual regression tests
  • Running tests
  • Configuring stories for testing

Directory structure

Honeycomb library itself is located in the src folder. Here is an overview of its structure:

honeycomb/
└── src/
    ├── components/
    │       ├── box/
    │       ├── button/
    │       ├── ....
    │       └── tooltip
    ├── helpers
    │       ├── reset/
    │       ├── space/
    │       ├── ....
    │       └── visibility
    ├── img/
    │       ├── logos/
    │       ├── favicons-greyhound.zip
    │       ├── favicons-kamil.zip
    │       ├── favicons-flix.zip
    │       └── ....
    ├── js/
    │       ├── classToggler/
    │       └── dropdown/
    │       └── popup/
    │       └── ....
    ├── scss/
    │    ├── common/
    │    ├── components/
    │    ├── helpers/
    │    ├── icons/
    │    └── themes/
    └── tokens/
         ├── templates/
         └── themes/

components/

All the HTML markup and documentation for components can be found in the this folder. Here each component has related files grouped in folders named by the component names. These files are:

• component.stories.js - holds the HTML markup for the component, should contain individual stories for all the possible states and modifier classes in order to be properly tested with visual regression testing tools;
• component.mdx - renders the component stories and documentation to be presented in Storybook;
• readme.md - holds all the relevant tech documentation and component usage guidelines, is visible in the Styleguide website;
• readme-design.md - optional design guide that has additional information mostly related to designers;

helpers/

Helper classes are located in the helpers folder. These classes are used for general styles that are not specific to any component, but the structure they follow is similar to the components one, as they are should be documented with Storybook stories and are covered by visual regression tests as well.

img/

This folder contain static assets as well as the favicon archives for each brand.

js/

This folder contains the JS plugins we offer on Honeycomb. The structure is similar to the components one, but the stories also contain unit tests that are run within Storybook stories and with npm test command.

scss/

SCSS part has its own folder structure, here are few notes regarding that.

• common folder contains configuration files, SASS mixins and base styles;
• components folder contains component specific SCSS partials that are named according to component class names but without a flix prefix;
• helpers folder contains helper classes
• icons folder contains icon related styles, you won't need it in most of the cases, please use our icons libraries for everything around icons;
• themes holds themes and theme colors (note that files in here are generated out of design tokens and not meant to be edited directly);

There are several SCSS entry points:

• honeycomb.scss - includes all the stuff and is the one that is used to compile the resulting CSS;
• honeycomb-tools.scss - the one you may need to kickstart your custom CSS with some of Honeycomb variables, breakpoints and mixins;
• honeycomb-base.scss - same as tools but with some base styles attached (e.g. box-sizing: border-box;, a bit of resets for flix- elements);
• honeycomb-components.scss - has only component styles without theme design tokens;
• honeycomb-fonts.scss - custom font declarations, required for honeycomb to work properly;
• honeycomb-helpers.scss - helpers only;
• honeycomb-sm.scss - limited, mobile only version with all the breakpoints specific styles above sm stripped out;
• honeycomb-theme-{theme_name}.scss - holds theme variables for the respective theme;
• honeycomb-themes.scss - holds all theme variables for all themes;
• honeycomb-custom-colors.css - theme variables with custom color set for color coding, not bound to any theme.

SASS mixins and functions

Honeycomb provides a handful of SASS mixins and functions to ease your work.

Just include assets/scss/honeycomb-tools.scss in our SASS/SCSS file to benefit from them. Here are some examples:

Positioning and responsive utils

This includes on-bp(), on-range() mixins and the z() function, to control responsive behaviour and z-index layering.

on-bp() mixin

General breakpoint mixins, accepts 2 params:

• $breakpoint - one of the map keys in breakpoints list (zero, xs, sm, md, lg, xl)
• $only - boolean property, indicates that style set should be applied for this breakpoint only, restricting the other ones with max-width

on-range() mixin

Similar to the breakpoint, but creates a media query for a range of breakpoints. Accepts 2 params:

• $from - one of the map keys in breakpoints list (zero, xs, sm, md, lg, xl)
• $to - one of the map keys in breakpoints list (zero, xs, sm, md, lg, xl)

z() function

z-index function that gives names to z-index layers in components, ensuring they won't collide and are consistent. Accepts $layer as param (one of 'base', 'form-label', 'dropdown', 'header', 'popup', 'side-menu').

Here is how we use those in our code:

.box {
  // assigning 12px spacing values
  margin-bottom: cssvar(spacing-2);
  padding: cssvar(spacing-2);

  // using on-bp mixin to define styles for wider ('sm' and bigger) screens
  @include on-bp(sm) {
    padding: cssvar(spacing-4); // we want a bigger spacing on wider screens, picking sm spacing for that
  }
}

Typography mixins

To keep various typography styles consistent, we provide a set of mixins for each typography element.

These mixins take care of the following properties: color, font-size, font-weight and line-height.

• show-as-text;
• show-as-small-text;
• show-as-fineprint;
• show-as-interactive-text;
• show-as-h1;
• show-as-h2;
• show-as-h3;
• show-as-h4;

tokens/

This folder contains design tokens in json format. This format makes them compatible with style-dictionary library and allows us generating theme/token configuration files not only for Honeycomb but also to other platforms in various formats.

docs/

The docs folder contains other guides and documentation that can be found on the website, such as this one.

Design tokens

Design tokens are a collection of attributes that describe any fundamental/atomic visual style. Each attribute is a key-value pair.

Honeycomb stores them as platform-agnostic set of json files that act as the main source of truth not only for generated cross-platform assets but also for Honeycomb itself.

Tokens definition and structure

Tokens are grouped in theme folders and separated into individual file configurations by the nature of attributes they describe:

tokens/
└── themes/
    ├── flix/
    │   ├── colors.json // colors
    │   ├── components.json // component specific variables
    │   ├── misc.json // all the rest, e.g. geometry or opacity variables
    │   ├── spacing.json // spacing schema
    │   └── typography.json // typography, e.g. font sizes, line heights etc.
    ├──...

Inside these files tokens are grouped by their type like color, size etc. and defined as followed:

{
  "color": {
    "ui-primary": {
      "comment": "primary color with shades",
      "name": "ui-primary-color",
      "value": "#73d700"
    },
    "secondary-ui": {
      "comment": "secondary color with shades",
      "name": "secondary-ui-color",
      "value": "#ffad00"
    },
  }
}

Where name provides optional name for the token that is by default gets defined by respective object keys, value declares token value and comment provides optional comment.

Build script and configuration

All the configuration and logic for token processing is located in build-tokens.js file.

For more info on that please refer to this file and documentation for style-dictionary library.

To build the tokens you can run the following command:

npm run build:tokens

By default a build is performed for flix theme only, to build for different themes you need to provide it as param, like so:

npm run build:tokens -- --theme neptune

UI kit versioning

We strictly follow semantic versioning pattern when it comes to package versioning (see: http://semver.org/).

This means we differentiate between major, minor and patch releases for Honeycomb

Major release

A major release introduces breaking (incompatible) changes. By breaking change we usually mean:

• Your change produces different visual result:
  • different color scheme
  • different grid patterns
  • components appearance change
• Your change requires adjustments in the code for things to work in the new version:
  • changes in class names
  • changes in HTML structure
  • changes in component names
  • changes in tech stack, like moving from SASS to LESS or deprecating SASS themes in favor of CSS custom properties
  • renaming of theme variables
• Your changes result in the removal of functionality:
  • removal of components
  • removal of modifiers
  • removal of themes or theme variables

Minor release

Minor release introduces incremental changes, in most cases it adds new components or component variations.

It's usually fully safe to update to next minor releases as you code is safe, no deprecations or major layout changes happen between minor releases.

Patch release

Those are usually bug fix releases, not only it's safe to update to those, but it's also highly recommended to get rid of some bugs you might encounter.

We also release patches when we update or extend documentation of existing features.

Accessing the releases

Honeycomb gets distributed via CDN and private npm registry.

CDN url structure is the following:

https://honeycomb.flixbus.com/dist/{YOUR_VER_NAME}/css/honeycomb.min.css

For version "13.5.0" this would be:

https://honeycomb.flixbus.com/dist/13.5.0/css/honeycomb.min.css

Grabbing a specific version from NPM is even easier, all you need is specifying a version you need in your package.json file

Adding components

Fir you need to setup your development environment and start Storybook:

• Checkout project from the repo and install the dependencies.
• Create your development branch with the naming pattern feature-hny-xxx-add-my-new-component.
• Run npm start to start the development server, check the terminal for the url and port it is running on.

Then you can proceed to add new files for your component:

1. Add your component styles:

• Create a new file your-component.scss inside src/scss/components directory
• Import your file in all.scss that is in the same folder (note that components are included in alphabetical order)

2. Document your component:

• Create a new folder for your component in src/components/your-component
• Add a your-component.stories.js file with the Storybook stories to present your component and all variations
• Add a your-component.mdx to visualize the component docs in Storybook
• Add a readme.md file all the necessary documentation, this file will be visible in the Styleguide website for others to refer to when using your component
• Add a readme-design.md file with design related documentation

Building from sources

To build the library from sources to dist/ folder you need to run

npm run build

This runs a set of gulp and webpack tasks and creates resulting css and js files, including minified ones. This also makes sure the contents of the img folder are being copied to the dist as well for distribution.

Normally you do not need to run the build tasks when developing as built in devserver works with SASS partials assembling them on the fly.

Though build becomes handy when you wanna check the exact css output orf your SASS sources or when debugging some complex SASS structures.

To run build only for SCSS files:

npm run build:css

Webpack script

This script will bundle assets based on the config in ./webpack/webpack.conf.default.js.

This currently is bundling all files in ./src/js/ as separated bundles that are exported as umd libraries.

npm run build:js

Linters

Our linters help us to maintain the common code style and quality level as well as avoid obvious mistakes and typos in the code.

Linters are run in the pipeline whenever you push your changes, but you can run them locally in your CLI with the following command:

npm run lint

We use Stylelint for SCSS linting and ESLint for JS linting. You can also run them separately:

npm run lint:scss

npm run lint:js

We use the recommended settings for ESlint, more details about the rule set can be found here.

Visual regression tests

Visual regression testing helps us check the impact of CSS changes on component's visual appearance, ensures precise tracking of components visual changes.

Currently we use test our components using Chromatic, it offers a seamless integration with our Storybook instance.

It automatically ensures all component stories will receive visual regression tests.

Running tests

First create Chromatic configuration file in the root of the project:

cp chromatic.config.json.dist chromatic.config.json

Replace projectId, projectToken properties with valid values provided to you.

You are all set!

Now the tests can either be run through the local Storybook visual tests action or by using the following command on your local terminal:

npm run chromatic

For more information, open any story on the Storybook dev server and then navigate to the "Visual tests" tab.

Reference screenshots

Screenshot management and component listing are managed within our project on Chromatic website.

Updated screens can also be observed and managed (accepted or declined) from within the Storybook app.

Configuring stories for testing

All individual story configuration happens through chromatic property in the parameters section of the story config object.

It's possible to configure screen sizes and themes to test against.

Here is an example of enabling testing for all themes, mobile and desktop screen sizes in a component.stories.js:

export const ComponentStory = {
  name: 'Component story',
  parameters: {
    chromatic: {
      modes: {
        small: allModes['small'],
        large: allModes['large'],
        flix: allModes['flix'],
        'flix-dark': allModes['flix-dark'],
        kamil: allModes['kamil'],
        'kamil-dark': allModes['kamil-dark'],
        neptune: allModes['neptune'],
        'neptune-dark': allModes['neptune-dark'],
        'high-contrast': allModes['high-contrast'],
      },
    },
  },
}

The configuration happens through modes which are defined within out .storybook/modes.js file.

To save-up time on testing we only apply modes for individual components that really require different screen sizes and theme configurations. The ones that have known responsive or theme related layout changes.

It is also possible to exclude certain stories from the test pipeline, this is done via disableSnapshot parameter.

For more info on the options available see chromatic docs.