AUI 7 upgrade guides

Upgrading from 7.8.x to 7.9

The AUI 7.9 release includes an update to the aesthetic of various drop down menus in AUI, in order to adhere to the Atlassian Design Guidelines.

These changes are visible in AUI's Dropdown, Single select, and Select2 wrapper components.

Dropdown changes

The following differences exist between the old and new drop down aesthetic:

These changes effectively bring the aesthetic of dropdown items in line with the treatment given to items in AUI's vertical navigation pattern.

Upgrading from 7.7.x to 7.8

The AUI 7.8 release includes a general and broad revision of AUI's usage of colour and typography, in order to adhere to the Atlassian Design Guidelines.

Typography changes

AUI's basic CSS revised its styles for h1 through h6 to set an appropriate font-size, font-weight, and letter-spacing. In effect, the size of h1 in AUI 7.8 is the size that h2 was in AUI 7.7.

As part of this upgrade, implementors are advised to review their heading-levels usage.

Read the updated typography documentation for a demonstration and description of each heading level's purpose. To compare the old and new values, consult the table below:

Colour changes

In AUI 7.1, we updated a significant number of colour values to use the new palette from the latest version of the Atlassian Design Guidelines. In AUI 7.8, we've pushed colours in to more components and patterns.

When upgrading to AUI 7.8, consult the colour foundation guidelines for suggested usage and balance of colour in your UI.

The new colour palette does not always have a clear, one-to-one mapping between the older one. Within AUI, we have deviated slightly from the guidelines in some places, in order to better bridge the old and new colours.

To ease implementor adoption, the following tables describe the colour changes AUI has made at a high level:

We also have rough advice for other colours that implementors may need to migrate:

Toggle buttons

The defaultValue behavior of AUI's Toggle Button was changed, to make "dirty form" checking work.
Previously, the hidden input field inside the Toggle Button was kept in sync with the aui-toggle element. Now, the Toggle Button component could be inconsistent with the hidden input.
For example:

1. Create a checked Toggle Button. The defaultValue of the hidden input will be true.
2. Turn the Toggle Button off. The defaultValue of the hidden input will stay true.

If you were relying on checking the hidden input's attributes or properties, you should update your code to instead check the aui-toggle element directly.

Upgrading from 7.6.x to 7.7

AUI 7.7 updates the style of various "progress" patterns — progress bars, spinners, and multi-step progress — to match those found in the Atlassian Design Guidelines. To make implementation simpler, there are new APIs to consume some of these components.

Progress bars

A new web component API for progress bars was added and documented on the progress indicator page. With this addition, the old markup pattern and imperative JavaScript APIs are now deprecated.

The new web component API allows you to set and affect the progress bar's value through the element's attributes or properties. This means you can now create a progress bar and set its initial value using only HTML.

We think you'll agree that this makes indicating progress in your UI much simpler.

Spinners

AUI's new spinner is also implemented as a web component. With this addition, several old imperative APIs are deprecated, and some undocumented code has been removed.

The preferred method of creating a spinner is to add the web component to the appropriate location in your page.

In previous versions of AUI, spinners could be added to the DOM via jQuery functions. These functions are now deprecated in favour of implementors adding a spinner element explicitly.

The AUI codebase used to use "spin.js" to implement its spinners. This library created a global Spinner function and encouraged writing code like the following:

    var spinner = new Spinner();
    $('.somewhere').append(spinner.el);

Sidebar

When an AUI sidebar is rendered (typically on DomContentLoaded) it would force a synchronous layout. This was an unnecessary slow-down of page rendering. A sidebar now always renders in a requestAnimationFrame callback, even when the element is created synchronously.

If your code depends on the sidebar's dimensions being calculated and determined immediately after a sidebar is created, this code will no longer work. We currently do not provide a signal (such as an event) for determining when the sidebar's dimensions have been calcualted.
Though we believe this should not be a breaking change for most sidebar consumers, we will monitor implementor feedback to see whether an alternative signal for a sidebar being rendered is required.

Page footer

The AUI page footer outputs the Atlassian logo in a #footer-logo element. The CSS selector to render this image has been simplified, which may invalidate any overrides to the footer area.
As part of this upgrade, you should review your CSS overrides to the footer, removing any unnecessary selectors.

Upgrading from 7.5.x to 7.6

AUI 7.6 updates the style of various navigation patterns — sidebar, vertical navigation, and horizontal navigation — to match those found in the Atlassian Design Guidelines.

Vertical navigation

The design of vertical navigation was updated to remove borders between subsequent lists of items. It is expected that most groups of links will be preceded by a heading. In cases where no heading exists, AUI now adds whitespace between the two groups instead of a separator line.

Sidebar

In updating AUI's sidebar's aesthetic, a large amount of unnecessary CSS was removed. While most of these changes should be transparent to implementors, there were some minor changes made to reduce redundancy that require implementor attention.

Sidebar body changes

The AUI sidebar pattern houses groups of sidebar items (.aui-sidebar-group) within an .aui-sidebar-wrapper element. It also allows links and buttons to be placed in the .aui-sidebar-footer element. Previously, the content of these containers were aligned using negative margin tricks. These groups are now positioned via flexbox.
Implementors should remove their CSS overrides to various margins and paddings of groups and containers within the AUI sidebar, so that content is correctly fitted and centred within the sidebar body.

Sidebar navigation item changes

Previously, .aui-nav-item elements in the sidebar had an effective height of 30px. They now have an effective height of 34px.
In conjunction with changes to the sidebar body, navigation items no longer touch the edges of the sidebar; instead, they render in a similar manner to the basic vertical navigation pattern.
Implementors should review any elements they position relatively to either fit within the .aui-nav-item element itself, or otherwise appear to align with their text content. Implementors should also check that any custom items they have do not touch the edges of the sidebar.

Sidebar iconography changes

The new sidebar design changes the colour of icons from "Grey" (#707070) to "N400 - Concrete Jungle" (#505F79).
While AUI's sidebar pattern makes provisions for using a slightly larger icon glyph in an "aui-icon" element — 20px instead of the typical 16px — AUI has not provided these larger icons; they are typically provided by products and plugins.
As part of this upgrade, you will need to adjust the fill color of any icons you place in the sidebar that do not come from AUI (which is probably most of them).

Upgrading from 7.4.x to 7.5

AUI 7.5 updates a majority of the icon set delivered via AUI to be harmonious with the Atlassian Design Guidelines.

Icon font declaration change

AUI delivers its iconography though a set of icon fonts. The @font-face declaration for these icon fonts changed location. Depending on whether you are consuming AUI through the AUI distribution, the lib, or the P2 plugin, the font delivery mechanism is slightly different.

• If you use AUI via the P2 plugin, no changes should be necessary on your part.
  If you are inspecting or analysing resource URLs at product runtime, note that the web-resource location of the font assets have changed from com.atlassian.auiplugin:icons to com.atlassian.auiplugin:internal-iconfont-v1 and com.atlassian.auiplugin:internal-iconfont-v2.
• If you are using the AUI distribution files (those found in the dist folder of the AUI Node package), no changes should be necessary on your part. You can consume either dist/css/aui.css or dist/css/aui-iconography.css; the @font-face definition is present in both.
• If you use assets from the lib/ folder, you will need to explicitly consume both the lib/css/iconfont-atlassian-icons.css and lib/css/iconfont-adgs-icons.css files in order to add the necessary @font-face definitions to your code.

Icon name changes

Some icons are either no longer needed or have changed in their representation. Check below for a table of icon glyphs that changed and the suggested upgrade path for each. Some icons that are no longer used in Atlassian products may be removed in a future version.

Upgrading from 7.3.x to 7.4

AUI 7.4 updates the style of tabs, avatars, and aspects of the application header to match those found in the Atlassian Design Guidelines.
AUI 7.4 also drops support for IE 9 and IE 10; IE 11 is the oldest supported Internet Explorer version.

Internet Explorer compatibility

We no longer support Internet Explorer versions older than IE 11. The browser usage statistics from Atlassian products in Server and Cloud suggest that usage of IE 10 is between 0.03% to 0.3% of total product usage.
Dropping support for older browser versions allows AUI to take advantage of newer technologies (like flexbox, @supports in CSS, native Promises, [and more](https://caniuse.com/#compare=ie+9,ie+10,ie+11)), which in turn helps us shed some of AUI's weight in its CSS and JavaScript layers over the next several releases.

Application Header

The application header pattern includes a secondary navigation section -- these are the menu items on the right side of the navigation that contain only an icon. The design guidelines state that these secondary navigation items should not have an additional chevron icon.
To match the guidelines, you will have to change your code to include an additional .aui-dropdown2-trigger-arrowles CSS class. Check the example code:

Avatar component

The new avatar style effectively swaps the treatment of users and projects.

• User avatars are now circular.
• Project avatars are now squares with subtly rounded borders.

As part of this upgrade, if you have any custom avatar patterns, consider refactoring them to use the AUI pattern instead. If that is untenable, you will need to add the same border radius changes to your avatar components.

Tab component

The new tab style is implemented using flexbox, which allows simpler adjustment of the direction and orientation of the tabs themselves. In addition, the tab panel has been given a default top padding of 10px so that content will have reasonable separation from the tab list by default.

As part of this upgrade, you will want to check:

• If you place tab items inside another container, you may need to revise its placement in that container. The dimensions and margins of the tab group and tab items have changed slightly, which may invalidate assumptions about its visual harmony with its surroundings.
• If you are changing the orientation or placement of tabs relative to their tab panel, you will need to adjust your CSS to account for the new style. Ensure the dividing line exists between the tab items and tab panel, and that the active tab item has a line on the same side as the dividing line.

Upgrading from 7.2.x to 7.3

AUI 7.3 updates the style of flags, messages, and modal dialogs in AUI to match those found in the Atlassian Design Guidelines.

Flag and Message design

The new style for flags and messages is designed to bridge the prior ADG2 pattern and the newer ADG3 variant. It aims to balance readability of in-page messages against a less noisy flag notification. The patterns may diverge further in future.

• The pattern for flags may be revised to alter the aesthetic and their placement on the screen, though this is not a certainty.
• The design of in-page messages may be further revised to achieve better contrast with their surrounding content.

As part of this upgrade, review whether you are including buttons or links inside message text, then consider placing them in an "actions" section of the message, using the aui-nav-actions-list CSS class on an un-ordered list. See the flags, messages, or in-product help docs pages for usage examples.

Modal dialog design

The new style for modal dialogs changes the contrast between its header, footer, and content sections. Where previously the header and footer were a light grey, they are now all white, with a light grey border separating the areas. In addition, the modal now has a drop-shadow, and the colour of the blanket behind the modal has changed.

The means of achieving layout in the modal has also changed — it is now implemented with flexbox. This was done in order to properly support adding shadows to Dialog2 without changing its markup pattern.

As part of this upgrade, check that the content you add to the headers and footers of your dialogs continue to fit within them; their placement and aesthetic may need updating to work within their containers.

Upgrading from 7.1.x to 7.2

AUI 7.2 updates the style of all buttons and button-like patterns in AUI to match those found in the Atlassian Design Guidelines.

Button styles

The new button style includes a significant change to the treatment of buttons that are "pressed", such as when a dropdown is opened from a button. The colour contrast between background and text in this state has inverted; where it used to be represented with a light grey background and internal drop-shadow, it is now a dark background with light text.

The colour and contrast changes in the button pattern will necessitate revision of any custom CSS overrides you may have for button styles, such as might exist for icons inside the button. See AUI-4516 and AUI-4517 for examples.

Toolbar changes

The toolbar patterns in AUI were also updated to match the Atlassian Design Guidelines.

One notable deviation to the guidelines is found in AUI's deprecated Toolbar1 pattern: there is no whitespace between .toolbar-item elements in a .toolbar-group. The markup pattern for Toolbar1 was overly permissive, and updating this pattern to achieve the new design guidelines would both increase CSS selector count and specificity, as well as encourage continued use of the deprecated pattern.

As part of this upgrade, you should migrate any old Toolbar1-based patterns to a more appropriate markup pattern.

If you are presenting a set of actions to perform on content, such as in a rich-text editor, use the Toolbar2 pattern:

You should only use the Toolbar pattern when the semantics of your UI align with those described in the WAI-ARIA best practices for the toolbar role. In many cases, you can instead use the simpler .aui-buttons pattern:

Placement of dropdowns in markup

As part of this upgrade, also consider changing where you place the HTML for an AUI dropdown. The rounding of button corners when used in AUI's toolbar patterns rely heavily on the first and last child of the toolbar group being a button element. If the last element is something else, like a dropdown, then the right edges of a toolbar will appear sharp.
Moving all non-button HTML out of the AUI Toolbar containers will resolve this problem.

Upgrading from 7.0.x to 7.1

AUI 7.1 introduces the colours and typography from the Atlassian Design Guidelines in to a majority of AUI's components.

The new font family has a different x-height and letter spacing, and can differ between operating systems. While most line-heights and vertical spacing has been preserved, some change in the flow of content on a page is inevitable. As a result, some assumptions about available horizontal space may need to be revised.

A change of page and component colours will mean that any hard-coded hex, hsl, or rgb values in your CSS may clash with the colours that AUI now uses. If you provide a look-and-feel feature, the values provided by that feature will also clash with AUI's and will need revision.
It is recommended you use a CSS pre-processing system to declare your colour usages with variables, such that replacement of the colour values can be done in a single location.

At a technical implementation level, the new colour and typography definitions used in AUI are consumed via a shared Node package called @atlaskit/util-shared-styles. AUI consumes this package in its LESS files, whose values are substituted at build-time. A consequence of this implementation strategy is that direct consumption of AUI's source will fail, as this dependency will not be resolvable via AUI's Node package, nor through standard LESSimport behaviour.
We recognise the desire to re-use the same values that AUI uses in its CSS, and are working on a supported solution — follow AUI-4477 for more details.

Upgrading from 6.x to 7

The AUI license

The primary change between AUI 6.x and 7 is the license under which AUI is distributed.

AUI 7 is licensed under the Atlassian Developer Terms instead of Apache-2.0.

The Atlassian Developer Terms license allows third party developers to use Atlassian's SDKs to develop for the Atlassian marketplace. Applying this license to AUI means:

• If you're using AUI to build something for use within the Atlassian ecosystem, nothing changes for you. For example, if you are building a P2 plugin for a Server product, or building an Atlassian Connect app, you can continue to use AUI.
• For other usages, you may be unable to use the new version of AUI.

If you are using AUI 6.x or earlier, its Apache-2.0 license will continue to apply.

In short: if you're using AUI to build something that is *NOT* for use within the Atlassian ecosystem, you cannot use AUI 7.x, but you can continue to use AUI 6.x.

Distribution changes

AUI ships as a Node package on npmjs.com. This package includes and applies all the design assets from the Atlassian Design Guidelines to the AUI components and patterns.

Now that the ADG assets ship via the AUI Node package, and given the sunsetting of Bower, the aui-dist and aui-adg-dist repositories are also deprecated; no further distribution zip files will be published there.
The recommended approach to retrieving the flat-packed distribution files is via the dist/ folder in the Node package. Alternatively, the flat-pack zip file is pushed to Atlassian's Artifactory repository , though this method of delivery may disappear in the future.

From AUI 7 onwards, AUI is not published to its own CDN any more. For production services, it is recommended to bundle the AUI resources with your own. For prototyping and development, the contents of the Node package can be served through unpkg.com.