Vanilla Framework 2.0 upgrade guide

We have just released Vanilla Framework 2.0, Canonical’s SCSS styling framework, and – despite our best efforts to minimise the impact – the new features come with changes that will not be automatically backwards compatible with sites built using previous versions of the framework.

To make the transition to v2.0 easier, we have compiled a list of the major breaking changes and their solutions (when upgrading from v1.8+). This list is outlined below. We recommend that you treat this as a checklist while migrating your projects.

1. Spacing variable mapping

If you’ve used any of the spacing variables (they can be recognised as variables that start with $spv or $sph) in your Sass then you will need to update them before you can build CSS. The simplest way to update these variables is to find/replace them using the substitution values listed in the Vanilla spacing variables table.

2. Grid

2.1 Viewport-specific column names

2.2 Columns must be direct descendants of rows

Ensure .col-* are direct descendants of .row; this has always been the intended use of the pattern but there were instances where the rule could be ignored. This is no longer the case.

Additionally, any .col-*s that are not direct descendants will just span the full width of their container as a fallback.

You can see an example of correcting improperly-nested column markup in this ubuntu.com pull request.

2.3 Remove any Shelves grid functionality

The framework no longer includes Shelves, classes starting with prefix-, suffix-, push- and pull- and no longer supported but arbitrary positioning on our new grid is achieved by stating an arbitrary starting column using col-start- classes.

For example: if you want an eight-column container starting at the fourth column in the grid you would use the classes col-8 col-start-4.

You can read full documentation and an example in the Empty Columns documentation.

2.4 Fixed width containers with no columns

Previously, a .row with a single col-12 or a col-12 on its own may have been used to display content in a fixed-width container. The nested solution adds unnecessary markup and a lone col-12 will no longer work.

A simple way to make an element fixed width, use the utility .u-fixed-width, which does not need columns.

2.5 Canonical global nav

If your website makes use of the Canonical global navigation module (If so, hello colleague or community member!) then ensure that the global nav width matches the new fixed-width (72rem by default). A typical implementation would look like the following HTML:

<script src="/js/global-nav.js"></script> <script>canonicalGlobalNav.createNav({maxWidth: '72rem'});</script>

3. Renamed patterns

Some class names have been marked for renaming or the classes required to use them have been minimised.

3.1 Stepped lists

We favour component names that sound natural in English to make the framework more intuitive. “list step” wasn’t a good name and didn’t explain its use very well so we decedided to rename it to the much more explicit “stepped list”.

In order to update the classes in your project search and replace the following:

3.2 Code snippet

“Code snippet” was an ambiguous name so we have renamed it to “code copyable” to indicate the major difference between it and other code variants.

Change the classes your code to the following:

If you’ve extended the mixin then you’ll need to update the mixin name as follows:

The p-tooltips class remains the same but you no longer need two classes to use the pattern because the modified tooltips now include all required styling. Markup can be simplified as follows (this is the same for all tooltip variants):

4. Breakpoints

Media queries changed due to a WG proposal. Ensure any local media queries are aligned with the new ones. Also, update any hard-coded media queries (e.g. in the markup) to the new values. The new values can be found in the docs (local link)

5. Deprecated components

5.1 Footer (p-footer)

This component is now entirely removed with no direct replacement. Footers can be constructed with a standard p-strip, row markup.

5.2 Button switch (button.p-switch)

Buttons shouldn’t be used with the p-switch component and are no longer supported. Instead, use the much more semantic checkbox input instead.

5.3 Hidden, visible (u-hidden, u-visible)

These have been deprecated and the one visibility-controlling class format is u-hide (and the more specific variants – u-hide documentation)

5.4 Warning notification (p-notification–warning)

This name for the component has been deprecated and it is now only available as p-notification--caution

5.5 p-link–no-underline

This was an obsolete modifier for a removed version underlined links that used borders

5.6 Strong link (p-link–strong)

This has been removed with no replacement as it was an under-utilised component with no clear usage guidelines.

5.7 Inline image variants

The variants p-inline-images img and p-inline-images__img have been removed and the generic implementation now supports all requirements.

5.7 Sidebar navigation (p-navigation–sidebar)

For navigation, the core p-navigation component is recommended. If sidebar-like functionality is still required then if can be constructed with the default grid components.

5.7 Float utilities (p-float*)

To move them in-line with the naming conventions used elsewhere in the framework, u-float--right and u-float--left are now u-float-right and u-float-left (One “-” is removed to make them first-level components rather than modifers. This is to allow for modifiers for screen sizes).

6. (Optional) Do not wrap buttons / anchors in paragraphs.

We have CSS rules in place to ensure that wrapped buttons behave as if they aren’t, and we would like to remove this as it is unnecessary bloat. In order to do that, we need to ensure buttons are no longer wrapped. This back-support is likely to be deprecated in future versions of the framework.

7. Update stacked forms to use the grid (p-form–stacked).

The hard-coded widths (25%/75%) on labels and inputs have been removed. This will break any layouts that use them, so please wrap the form elements in .row>.col-*.

8. Replace references to $px variable

$px used to stand for 1px expressed as a rem value. This was used, for example, to calculate padding so that the padding plus the border equals a round rem value. This could no longer work once we introduced the font size increase at 1680px, because the value of 1rem changes from 16px to 18px.

Replace instances of this variable with calc({rem value} +/- 1px).

This means you need to replace e.g.:

Before: padding: $spv-nudge - $px $sph-intra--condensed * 1.5 - ($px * 2);

After: padding: calc(#{$spv-nudge} - 1px) calc(#{$sph-intra--condensed * 1.5} - 2px);

9. Replace references to $color-warning with $color-caution

This was a backwards compatibility affordance that had been deprecated for the last few releases.

10. (Optional) Try to keep text elements as siblings in the same container

Unless you really need to wrap in different containers, e.g. (emmet notation) div>h4+div>p, use div>h4+p. This way the page will benefit from the careful adjustments of white space using <element>+<element> css rules, i.e. p+p, p+h4 etc. Ignoring this won’t break the page, but the spacing between text elements will not be ideal.

11. $font-base-size is now a map of sizes

To allow for multiple base font sizes for different screen sizes, we have turned the $font-base-size variable into a map.

A quick fix to continue using the deprecated variable locally would be:

$font-base-size: map-get($base-font-sizes, base);

But, for a more future-proof version, you should understand and use the new map.

By default, the font-size of the root element (<html>) increases on screens larger than the value of $breakpoint-x-large. This means it can no longer be represented as a single variable. Instead, we use a map to store the two font sizes ($base-font-sizes). If you are using $font-base-size in your code, replace as needed with a value from the $base-font-sizes map.

That’s it

Following the previous steps should now have your project using the latest features of Vanilla 2.0. There may be more work updating your local code and removing any temporary local fixes for issues we have fixed since the last release but this will vary from project to project.

If you still need help then please contact us on twitter or refer to the full Vanilla Framework documentation.

If, in the process of using Vanilla, you find bugs then please report them as issues on Github where we also welcome pull request submissions from the community if you want to suggest a fix.