Honeycomb 6.0 migration guide

This guide aims to help you with upgrading your application to Honeycomb 6.0 which brings you many updates in terms of how components look and how to use them. Information is grouped into steps making it easier to follow and focus on the things that matter to you and your setup.

At first glance the number of updates might seem overwhelming, but most of them are rather small ones which intended to greatly improve the usability and accessibility of our components.

Table of Contents

• Honeycomb 6.0 migration guide
  • Table of Contents
  • Step 1: Package upgrade
  • Step 2: Deprecated components and variations
    • Icons
    • Arrow buttons
    • Hints
    • Radio wrapper
    • Lists
    • "flix-control" becomes "flix-form-row"
    • New spacing scale and helpers update
    • Deleted theme variables
    • Notification variations
    • Tags
  • Step 3: Accessibility related breaking changes
    • Connection
    • Fineprint
    • Header
    • Pager
    • Progress tracker

Step 1: Package upgrade

Upgrading with npm

That's a one command story in here:

npm update @flixbus/honeycomb@latest

Upgrading with a CDN

If Honeycomb is served to your application through the CDN you'll need to update the url providing the proper version part, like so:

<link rel="stylesheet" href="https://honeycomb.flixbus.com/dist/6.3.0/css/honeycomb.min.css"/>

Same applies to any partials you fetch from our CDN, e.g. if you need the honeycomb themes this would be:

<link rel="stylesheet" href="https://honeycomb.flixbus.com/dist/6.3.0/css/honeycomb-themes.min.css"/>

Step 2: Deprecated components and variations

With Honeycomb 6.0 we've decided to cut down the number of components a bit offering a unified alternatives that are more flexible and suit to more use cases. This means that while upgrading to this version you'll need to replace all the usages of these components in your code.

In this section we'll go through them one by one, offering you code snippets you can use as the basis while updating your application.

Icons

Starting from Honeycomb 6.0, all the icon assets were extracted into dedicated packages:

• @flixbus/honeycomb-icons-static - replaces initial icon font functionality of previous version of Honeycomb
• @flixbus/honeycomb-icons-components - allows for web component based icons.

If you are using icon font or CDN icon images you'll need to add honeycomb-icons CDN url to you app: <link rel="stylesheet" href="https://honeycomb-icons.hive.flixbus.com/4.0.0/fonts/flix-icon.css">

New library is also available via npm, the process is the same as for honeycomb, you can do npm i -s @flixbus/honeycomb-icons-static and import icon font css, sass or less files from there, like so:

import '@flixbus/honeycomb-icons-static/dist/fonts/flix-icon.scss';

Both options are equal and preference purely depends on your setup and taste.

For more information on the icons library, check out the Honeycomb Icons Repository on GitLab.

Arrow buttons

Honeycomb 4.0 introduces link Button variation, with our 6.0 release we've decided to dismiss arrow buttons in favour of this one as they produce the same result giving you more options in terms of appearance and icon usage. Bellow you can find example code for every arrow button variation recreated with a link button type:

<button type="button" class="flix-btn flix-btn--link flix-btn--has-icon">
  <i class="flix-btn__icon flix-icon flix-icon-arrow-left" aria-hidden="true"></i>
  <span class="flix-btn__text">Go back button</span>
</button>
<button type="button" class="flix-btn flix-btn--link flix-btn--has-icon">
  <span class="flix-btn__text">Go forward button</span>
  <i class="flix-btn__icon flix-icon flix-icon-arrow-right" aria-hidden="true"></i>
</button>
<button type="button" class="flix-btn flix-btn--link flix-btn--has-icon">
  <span class="flix-btn__text">Collapse button</span>
  <i class="flix-btn__icon flix-icon flix-icon-arrow-up" aria-hidden="true"></i>
</button>
<button type="button" class="flix-btn flix-btn--link flix-btn--has-icon">
  <span class="flix-btn__text">Expand button</span>
  <i class="flix-btn__icon flix-icon flix-icon-arrow-down" aria-hidden="true"></i>
</button>
<button type="button" class="flix-btn flix-btn--link flix-btn--primary flix-btn--has-icon">
  <i class="flix-btn__icon flix-icon flix-icon-arrow-left" aria-hidden="true"></i>
  <span class="flix-btn__text">Strong arrow button</span>
</button>

Hints

With version 6.0 we deprecate Hint component replacing it with a Tooltip alternative. These components were very similar and sometimes created confusion when trying to pick up the right one for a specific purpose.

As a benefit tooltips allow you to put rich text HTML content inside as well as providing more variations and positioning options, but some additional work would be required from your side.

A typical hint implementation normally looks as follows:

<span class="flix-element-has-hint" data-hint="I&#x27;m just a normal hint, the right one">
  Hover me for a hint
</span>

Here is a recreation of that with a Tooltip component:

<div class="flix-tooltip-target">
    <span data-tooltip="tooltip-default">
      Hover me for a tooltip
    </span>
    <div id="tooltip-default" hidden="" class="flix-tooltip flix-tooltip--small">
      <div class="flix-tooltip__content">
        I&#x27;m just a normal tooltip, the right one
      </div>
    </div>
</div>

To make tooltips work you need to have our tooltip.js plugin included and initialized on the page. Check out using the plugin section for more info on how to get it up and running.

If you have your hints displaying error messages make sure to use danger variation of the tooltip component.

Radio wrapper

This component was deprecated in favour of ChoiceWrapper that is more flexible when it comes to configuring selections. In order to migrate simply replace all css class names containing flix-radio-wrapper with flix-choice-wrapper.

Lists

In version 6.0 we introduced a ListWrapper component that extends from LinkedList giving even more functionality at hand. This allowed us to deprecate and remove LinkedList in favour of the new component.

In order to migrate to 6.0 you'll need replacing your LinkedList usages with ListWrapper. Luckily their HTML structure is super similar, bellow you can find a sample LinkedList markup and the same thing implemented with ListWrapper:

<ul class="flix-list-linked">
    <li class="flix-list-linked__item">
        <a class="flix-list-linked__link" href="#">Bus Copenhagen - Berlin</a>
    </li>
    <li class="flix-list-linked__item">
        <a class="flix-list-linked__link" href="#">Bus Berlin - Amsterdam</a>
    </li>
    <li class="flix-list-linked__item">
        <a class="flix-list-linked__link" href="#">Bus Berlin - Bremen</a>
    </li>
</ul>

<ul class="flix-list-wrapper">
    <li class="flix-list-wrapper__item">
        <a class="flix-list-wrapper__content" href="#">Bus Copenhagen – Berlin</a>
    </li>
    <li class="flix-list-wrapper__item">
        <a class="flix-list-wrapper__content" href="#">Bus Berlin - Amsterdam</a>
    </li>
    <li class="flix-list-wrapper__item">
        <span class="flix-list-wrapper__content">Bus Berlin - Bremen</span>
    </li>
</ul>

There are 2 main changes in the markup and CSS class naming:

• flix-list-linked CSS classes should be renamed to flix-list-wrapper;
• flix-list-linked__link CSS class has become flix-list-wrapper__content;

Furthermore small variation of ListWrapper replaces ListSimple component as well.

Here is an example of that one:

<ul class="flix-list-simple">
    <li class="flix-list-simple__item">
        Bus Schedules &amp; Bus Stops
    </li>
    <li class="flix-list-simple__item">
        Bus Journey
    </li>
    <li class="flix-list-simple__item">
        Overnight Buses
    </li>
</ul>

<ul class="flix-list-wrapper flix-list-wrapper--small">
    <li class="flix-list-wrapper__item">
      <div class="flix-list-wrapper__content">
        Bus Schedules &amp; Bus Stops
      </div>
    </li>
    <li class="flix-list-wrapper__item">
      <div class="flix-list-wrapper__content">
        Bus Journey
      </div>
    </li>
    <li class="flix-list-wrapper__item">
      <div class="flix-list-wrapper__content">
        Overnight Buses
      </div>
    </li>
</ul>

Some things to not in here:

• flix-list-simple CSS class should be replaced with flix-list-wrapper flix-list-wrapper--small combination
• flix-list-simple__item becomes flix-list-wrapper__item
• content inside should be wrapped into flix-list-wrapper__content element.

"flix-control" becomes "flix-form-row"

New version requires you to rename all the occurrences of flix-control element to flix-form-row. We believe that new name better reflects the nature of this element, also highlighting that it should only be used in form contexts.

New spacing scale and helpers update

Honeycomb 6.0 introduces the new multiplier based spacing schema. In order to continue using Honeycomb spacing theme variables in your custom styles you'll need updating them according to the table bellow:

Same applies for the cases with cssvar() SCSS mixin: cssvar(spacing-xs) becomes cssvar(spacing-2) and so on.

Deleted theme variables

With the new version we try to reduce the number of component specific theme variables. Some of them have become redundant with the new interaction states concept, others were replaced with more general ones like primary-content-color instead of input-info-color. Please refer to the table bellow to see how old variables can be replaced in your project.

Notification variations

This update aligns modifier naming for Notification component with other components to "success/warning/danger" scheme. This means you'll need to rename flix-notification--error CSS classes in your code to flix-notification--danger, all other variations remain in place.

Tags

Honeycomb 6.0 introduces a more flexibility when using icons and tags. In order to make this happen we highly recommend having text content wrapped in a flix-tag__text element for all the tags.

Older Honeycomb versions:

<span class="flix-tag">Normal tag</span>

Honeycomb 6.0:

<span class="flix-tag">
  <span class="flix-tag__text">Normal tag</span>
</span>

Step 3: Accessibility related breaking changes

Honeycomb 6.0 introduces markup changes to improve semantics and accessibility for the following components:

• connection;
• header;
• pager;
• progress-tracker;

In this section we'll briefly go through them, please check the documentation for respective component in order to get more details.

Connection

Main thing to pay attention to in connection component is time elements (flix-connection__time). We strongly advice using HTML <time> element in combination with datetime attribute instead of plain div-based markup. Bellow you can find an example comparison.

Previous Honeycomb versions:

<div class="flix-connection__time">
  07:00
</div>

Honeycomb 6.0:

<time class="flix-connection__time" dateTime="2016-10-17T07:00">
  07:00
</time>

For flix-connection--live variation there is a change of HTML structure in old/new time definition columns:

Previous Honeycomb versions:

    <div class="flix-connection__time flix-connection__time--old">
      23:30
    </div>
    <div class="flix-connection__time flix-connection__time--old">
      23:35
    </div>


    <div class="flix-connection__time flix-connection__time--warning">
      00:35<span class="flix-connection__day">+1</span>
    </div>
    <div class="flix-connection__time flix-connection__time--warning">
      00:40<span class="flix-connection__day">+1</span>
    </div>

Honeycomb 6.0, note how "old" time declarations are wrapped into <del> element and "new" ones into <ins> tag:

    <del>
      <span class="flix-sr-only">Old time:</span>
      <time class="flix-connection__time flix-connection__time--old" dateTime="2016-10-16T23:30">
        23:30
      </time>
    </del>
    <del>
      <span class="flix-sr-only">Old time:</span>
      <time class="flix-connection__time flix-connection__time--old" dateTime="2016-10-16T23:35">
        23:35
      </time>
    </del>


    <ins>
      <span class="flix-sr-only">New time:</span>
      <time class="flix-connection__time flix-connection__time--warning" dateTime="2016-10-17T00:35">
        00:35<span class="flix-connection__day">+1</span>
      </time>
    </ins>
    <ins>
      <span class="flix-sr-only">New time:</span>
      <time class="flix-connection__time flix-connection__time--warning" dateTime="2016-10-17T00:40">
        00:40<span class="flix-connection__day">+1</span>
      </time>
    </ins>

Another thing to note is the usage of screen reader helping element flix-sr-only. Elements with this class are not normally visible but they play a major role when it comes to giving contextual information to screen reader users.

Fineprint

To enforce a more semantic usage of flix-fineprint, fineprint styles now only take effect if the class is applied to a <small> HTML tag.

Previously you could apply the class to any element, e.g:

<p class="flix-fineprint">Some small text</p>

or

<div class="flix-fineprint">Some small text</div>

Honeycomb 6.0, you can still have the paragraph or div wrappers, but the fineprint (copyright, disclaimer, etc) must be inside a <small> tag:

<small class="flix-fineprint">
  Fineprint is not just small text, it usually refers to the part of a document that contains disclaimers, caveats, or legal restrictions, such as copyrights.
</small>

Or inside a paragraph:

<p class="flix-text">
  This is a sentence. <small class="flix-fineprint">Some disclaimer regarding the previous sentence.</small>
</p>

Header

For a proper keyboard navigation support all the nav item elements that contain a sub navigation in Header component (flix-header-nav__item--has-subnav) should have: role="button" tabindex="0" attributes.

Pager

Pager has been adapted to have a proper HTML list structure utilizing ul and li elements.

Old Honeycomb versions:

<nav class="flix-pager" aria-label="Pagination">
  <span href="#" class="flix-pager__item flix-pager__item--prev flix-pager__item--disabled">
      <span class="flix-sr-only">Previous page</span>
  </span>
  <a class="flix-pager__item flix-pager__item--active" href="#" aria-current="page">1</a>
  <a class="flix-pager__item" href="#">2</a>
  <a class="flix-pager__item flix-pager__item--next" href="#">
    <span class="flix-sr-only">Next page</span>
  </a>
</nav>

Honeycomb 6.0:

<nav class="flix-pager" aria-label="Pagination">
  <ul class="flix-pager__list">
    <li class="flix-pager__item">
      <span class="flix-pager__link flix-pager__link--prev flix-pager__link--disabled" aria-disabled="true">
        <span class="flix-sr-only">Previous page</span>
      </span>
    </li>
    <li class="flix-pager__item">
      <a class="flix-pager__link flix-pager__link--active" href="#" aria-current="page">
        1
      </a>
    </li>
    <li class="flix-pager__item">
      <a class="flix-pager__link" href="#">
        2
      </a>
    </li>
    <li class="flix-pager__item">
      <a class="flix-pager__link flix-pager__link--next" href="#">
        <span class="flix-sr-only">Next page</span>
      </a>
    </li>
  </ul>
</nav>

Progress tracker

This component was simplified to use CSS counters for numbers, meaning you should remove <div class="flix-progress-tracker__number"></div> elements in order to avoid possible number duplication and other issues. One thing you should make sure is to use ordered list - <ol> as implementations using "unordered list" <ul> will no longer work.

Old Honeycomb versions:

<ol class="flix-progress-tracker">
    <li class="flix-progress-tracker__item flix-progress-tracker__item--active">
      <div class="flix-progress-tracker__number">1</div>
      <div class="flix-progress-tracker__text">Get Honeycomb</div>
      <div class="flix-sr-only">Completed</div>
    </li>
    <li class="flix-progress-tracker__item" aria-current="step">
      <div class="flix-progress-tracker__number">2</div>
      <div class="flix-progress-tracker__text">Use it</div>
    </li>
    <li class="flix-progress-tracker__item">
      <div class="flix-progress-tracker__number">3</div>
      <div class="flix-progress-tracker__text">Enjoy</div>
    </li>
    <li class="flix-progress-tracker__item">
      <div class="flix-progress-tracker__number">4</div>
      <div class="flix-progress-tracker__text">Spread the word</div>
    </li>
</ol>

Honeycomb 6.0:

<ol class="flix-progress-tracker">
    <li class="flix-progress-tracker__item flix-progress-tracker__item--active">
      <span class="flix-progress-tracker__text">Get Honeycomb</span>
      <span class="flix-sr-only">Completed</span>
    </li>
    <li class="flix-progress-tracker__item" aria-current="step">
      <span class="flix-progress-tracker__text">Use it</span>
    </li>
    <li class="flix-progress-tracker__item">
      <span class="flix-progress-tracker__text">Enjoy</span>
    </li>
    <li class="flix-progress-tracker__item">
      <span class="flix-progress-tracker__text">Spread the word</span>
    </li>
</ol>

When using links as progress tracker items ensure flix-progress-tracker--linked modifier class is present on flix-progress-tracker element. This makes visual interaction states to work.

That's mostly it!

If you're interested in all the changes Honeycomb 6.0 brings check our full changelog page. Please contact us in case you faced any issues when updating to version 6.0, we'll gladly assist you and provide more information on any related topic.