AUI 7 upgrade guides

You can find upgrade guide for the latest version here.

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:

Aspect Old properties New properties
Borders
  • 1px solid border
  • Only the bottom corners have a border radius
  • 0px border; the element's shadow acts as a faux border
  • All corners have a 3px border radius
Items
  • Between 26-30px tall
  • Solid white background at rest
  • Dark blue background with white text when hovered or focussed
  • A minimum of 30px tall
  • Transparent background at rest
  • Light grey background with dark text when hovered or focussed
Headings
  • Between 26-29px tall
  • Inconsistent font-size and colour values
  • A minimum of 30px tall
  • Use h100 typography values
Spacing
  • Inconsistent space between sections
  • Inconsistent padding at top and bottom of drop down
  • 3px whitespace between sections
  • 3px whitespace at top and bottom of drop down
Placement in relation to trigger

The drop down and its trigger appear conjoined, with no spacing between them. Several components, such as buttons, remove their border radii when a drop down is open and attached to them.

The drop down and its trigger appear distinct, with 3px of whitespace between them. Components no longer need contextual overrides to make the drop down appear conjoined to the component.

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:

Element Old properties New properties
h1
font-size
32px
letter-spacing
0
line-height
1.25
font-size
24px
letter-spacing
-.01em
line-height
1.25
h2
font-size
24px
letter-spacing
0
line-height
1.25
font-size
20px
letter-spacing
-.008em
line-height
1.5
h3
font-size
20px
letter-spacing
0
line-height
1.5
font-size
16px
letter-spacing
-.006em
line-height
1.25
h4
font-size
16px
letter-spacing
0
line-height
1.25
font-size
14px
letter-spacing
-.003em
line-height
1.42...
h5
font-size
14px
line-height
1.42...
font-size
12px
line-height
1.66...
h6
font-size
12px
color
N800 (#172B4D)
text-transform
uppercase
font-size
12px
color
N200 #6B778C
text-transform
normal

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:

Old colour New colour Notes
Name
White
Hex
#fff
Name
N0
Hex
#fff
Makes sense, right?
Name
Light gray
Hex
#f5f5f5
Name
N20
Hex
#f4f5f7
Various panels in AUI (such as the page background, sidebar, footer, etc.) were set to N20.
Name
Silver
Hex
#e9e9e9
Name
N30
Hex
#ebecf0
Very little "silver" is used in AUI, actually.
Name
Silver
Hex
#e9e9e9
Name
N30A
Hex
rgba(9, 30, 66, 0.08)
Remember when we said AUI didn't use much "silver"? We lied. AUI uses an alpha-transparent variant, N30A, as the border and background colour of many components, such as normal buttons, hovered and selected navigation links, hovered or focussed table rows... generally if a component is interactive, its hover or focus state will use this colour.
Name
Ash grey
Hex
#ccc
Name
N40
Hex
#dfe1e5
Most of AUI's component border colours (tables, dialogs, dropdowns, etc.) were set to N40.
Name
Ash grey
Hex
#ccc
Name
N50
Hex
#c1c7d0
AUI's form field borders were temporarily set to N50, which maintains a similar lightness to its previous value.
Name
Grey
Hex
#999
Name
N80
Hex
#97a0af
Placeholder text and disabled text in form fields is now set to N80.
Name
Grey
Hex
#999
Name
N100
Hex
#7a869a
Disabled text is now set to N100.
Name
Medium gray
Hex
#707070
Name
N100
Hex
#7a869a
Disabled text is now set to N100.
Name
Medium gray
Hex
#707070
Name
N200
Hex
#6b778c
Low-level headings (such as those in labels, field groupings, etc.) are now set to N200.
Name
Medium gray
Hex
#707070
Name
N400
Hex
#505f79
Hint text rendered in component footers (such as in dialogs, date picker, form field descriptions, etc.) were set to N400.
Name
Charcoal
Hex
#333
Name
N100
Hex
#7a869a
Table headings are now set to N100.
Name
Charcoal
Hex
#333
Name
N200
Hex
#6b778C
Low-level headings (such as those in dropdowns, inline dialogs, vertical navigation, etc.) and the h6 element are now set to N200.
Name
Charcoal
Hex
#333
Name
N800
Hex
#172b4d
This is the new default text colour.
Name
Black
Hex
#000
Name
N900
Hex
#091e42
There is no black in ADG3, so AUI takes the darkest neutral colour.
Name
Navy
Hex
#205081
Name
B500
Hex
#0747A6
This is the new application header colour.
Name
"Button Blue"
Hex
#2a67a5
Name
B400
Hex
#0052cc
Primary buttons and actions are now set to B400. The old colour didn't have a name, so we just made it up then.
Name
Bright Blue 1
Hex
#3b73af
Name
B400
Hex
#0052cc
Hyperlinks and link-looking things are now set to B400.
Name
Blue
Hex
#3572b0
Name
B300
Hex
#0065ff
We use this for primary buttons in the application header, as well as dynamic states for interactive elements such as links and progress indicators.
Name
Bright blue 2
Hex
#59afe1
Name
B100
Hex
#4c9aff
This color was rarely, if ever used in AUI. It will soon become the focus colour for most fields.
Name
Orange
Hex
#f79232
Name
P300
Hex
#6554c0
The in-product help colour has changed to P300. Orange is the old Black, we guess.
Name
Y500
Hex
#ff8b00
Name
P300
Hex
#6554c0
The in-product help colour has changed to P300. This should be used for feature discovery, blank states, product tours, and other attention-grabbers for things that are new or informative.

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

Old colour New colour Notes
Name
Brown
Hex
#815b3a
Name
R500
Hex
#bf2600
There is no equivalent brown colour, so we threw this in the red bucket.
Name
Red
Hex
#d04437
Name
R400
Hex
#DE350B
Error text, error banners, error lozenges, and other error-like things are a darkish red, so as not to sear user's eyeballs when they have to read content presented in it.
Name
Red
Hex
#d04437
Name
R300
Hex
#ff5630
When it won't sear the user's eyeballs, we use this for error-like things, such as the icons in error message flags.
Name
Cheeto orange
Hex
#f79232
Name
Y500
Hex
#ff8b00
Name
Tan
Hex
#f1a257
Name
Y200
Hex
#ffc400
Name
Light brown
Hex
#d39c3f
Name
Y75
Hex
#fff0b2
The old "light brown" wasn't actually that "light", was it?
Name
Yellow
Hex
#f6c342
Name
Y300
Hex
#ffab00
Primary for primary.
Name
Pale yellow
Hex
#fffdf6
Name
Y50
Hex
#fffae6
It's still as pale as ever, and just as yellow.
Name
Lime green
Hex
#8eb021
Name
G75
Hex
#abf5d1
With apologies to the citrus fans amongst you.
Name
Mid green
Hex
#67ab49
Name
G200
Hex
#57d9a3
Name
Green
Hex
#14892c
Name
G400
Hex
#00875A
Used in success lozenges and toggle buttons.
Name
Green
Hex
#14892c
Name
G300
Hex
#36b37e
In most other cases where green is used, it is set to G300.
Name
Slate
Hex
#4a6785
Name
T500
Hex
#008da6
Name
Cyan
Hex
#59afe1
Name
T200
Hex
#00b8d9
Look, we're developers. We were never that great at naming things after what they represented.
Name
Cool blue
Hex
#84bbc6
Name
T75
Hex
#79e2f2
Name
Pale blue
Hex
#ebf2f9
Name
B50
Hex
#deebff
Name
Mauve
Hex
#ac707a
Name
P200
Hex
#8777d9
Name
Violet
Hex
#654982
Name
P500
Hex
#403294
Name
Bright pink
Hex
#f15c75
Name
R200
Hex
#ff7452
Name
Rosie
Hex
#f691b2
Name
R75
Hex
#ffbdad

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);

In this release of AUI, the "spin.js" library has been removed. As a consequence, any code depending on a global Spinner function's existence and behaviour will break. Implementors are encouraged to replace this code with usage of the aui-spinner HTML element.

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.

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.

Old icon name New equivalent Reason
aui-iconfont-image-extrasmall aui-iconfont-image Non-standard icon sizes are not necessary. AUI will only allow "-small" size variants for its icon names.
aui-icon-dropdown aui-icon-chevron-down Using aui-icon-dropdown is deprecated in AUI; it is part of a legacy markup pattern for dropdown elements. Dropdown2's aui-dropdown2-trigger class achieves the dropdown chevron without needing an explicit HTML element for it, which simplifies things for implementors.
aui-iconfont-appswitcher aui-iconfont-menu The icon was renamed. It was a part of the ADG2 icon set.
aui-iconfont-build aui-iconfont-refresh The icon was renamed. It was a part of the ADG2 icon set.
aui-iconfont-close-dialog aui-iconfont-cross The icon was renamed. It was a part of the ADG2 icon set.
aui-iconfont-collapsed aui-iconfont-chevron-down The icon was renamed. It was a part of the ADG2 icon set.
aui-iconfont-configure aui-iconfont-settings The icon was renamed. It was a part of the ADG2 icon set.
aui-iconfont-copy-clipboard aui-iconfont-copy The icon was renamed. It was a part of the ADG2 icon set.
aui-iconfont-delete aui-iconfont-trash The icon was renamed. It was a part of the ADG2 icon set.
aui-iconfont-details aui-iconfont-detail-view The icon was renamed. It was a part of the ADG2 icon set.
aui-iconfont-devtools-arrow-left aui-iconfont-arrow-left The icon was renamed. It was a part of the ADG2 icon set.
aui-iconfont-devtools-arrow-right aui-iconfont-arrow-right The icon was renamed. It was a part of the ADG2 icon set.
aui-iconfont-devtools-checkout aui-iconfont-sign-in The icon was renamed. It was a part of the ADG2 icon set.
aui-iconfont-devtools-clone aui-iconfont-import The icon was renamed. It was a part of the ADG2 icon set.
aui-iconfont-devtools-folder-closed aui-iconfont-folder-filled The icon was renamed. It was a part of the ADG2 icon set.
aui-iconfont-devtools-pull-request aui-iconfont-export The icon was renamed. It was a part of the ADG2 icon set.
aui-iconfont-devtools-tag aui-iconfont-tag The icon was renamed. It was a part of the ADG2 icon set.
aui-iconfont-devtools-tag-small aui-iconfont-tag The icon was renamed. It was a part of the ADG2 icon set.
aui-iconfont-drag-vertical aui-iconfont-menu The icon was renamed. It was a part of the ADG2 icon set.
aui-iconfont-edit aui-iconfont-edit-filled The icon was renamed. It was a part of the ADG2 icon set.
aui-iconfont-edit-small aui-iconfont-edit-filled The icon was renamed. It was a part of the ADG2 icon set.
aui-iconfont-expanded aui-iconfont-chevron-up The icon was renamed. It was a part of the ADG2 icon set.
aui-iconfont-focus aui-iconfont-vid-full-screen-on The icon was renamed. It was a part of the ADG2 icon set.
aui-iconfont-handle-horizontal aui-iconfont-more-vertical The icon was renamed. It was a part of the ADG2 icon set.
aui-iconfont-help aui-iconfont-question-circle The icon was renamed. It was a part of the ADG2 icon set.
aui-iconfont-homepage aui-iconfont-home-circle The icon was renamed. It was a part of the ADG2 icon set.
aui-iconfont-image-extrasmall aui-iconfont-image The icon was renamed. It was a part of the ADG2 icon set.
aui-iconfont-info aui-iconfont-info-circle The icon was renamed. It was a part of the ADG2 icon set.
aui-iconfont-weblink aui-iconfont-world The icon was renamed. It was a part of the ADG2 icon set.
aui-iconfont-list-add aui-iconfont-add-circle The icon was renamed. It was a part of the ADG2 icon set.
aui-iconfont-list-remove aui-iconfont-cross-circle The icon was renamed. It was a part of the ADG2 icon set.
aui-iconfont-locked aui-iconfont-lock-filled The icon was renamed. It was a part of the ADG2 icon set.
aui-iconfont-locked-small aui-iconfont-lock-filled The icon was renamed. It was a part of the ADG2 icon set.
aui-iconfont-page-blank aui-iconfont-document The icon was renamed. It was a part of the ADG2 icon set.
aui-iconfont-doc aui-iconfont-document The icon was renamed. It was a part of the ADG2 icon set.
aui-iconfont-pages aui-iconfont-documents The icon was renamed. It was a part of the ADG2 icon set.
aui-iconfont-remove aui-iconfont-cross-circle The icon was renamed. It was a part of the ADG2 icon set.
aui-iconfont-remove-label aui-iconfont-cross-circle The icon was renamed. It was a part of the ADG2 icon set.
aui-iconfont-search-small aui-iconfont-search The icon was renamed. It was a part of the ADG2 icon set.
aui-iconfont-space-personal aui-iconfont-person-circle The icon was renamed. It was a part of the ADG2 icon set.
aui-iconfont-star aui-iconfont-star-filled The icon was renamed. It was a part of the ADG2 icon set.
aui-iconfont-success aui-iconfont-check The icon was renamed. It was a part of the ADG2 icon set.
aui-iconfont-time aui-iconfont-recent The icon was renamed. It was a part of the ADG2 icon set.
aui-iconfont-unfocus aui-iconfont-vid-full-screen-off The icon was renamed. It was a part of the ADG2 icon set.
aui-iconfont-unlocked aui-iconfont-unlock-filled The icon was renamed. It was a part of the ADG2 icon set.
aui-iconfont-unstar aui-iconfont-star The icon was renamed. It was a part of the ADG2 icon set.
aui-iconfont-unwatch aui-iconfont-watch The icon was renamed. It was a part of the ADG2 icon set.
aui-iconfont-up aui-iconfont-arrow-up The icon was renamed. It was a part of the ADG2 icon set.
aui-iconfont-down aui-iconfont-arrow-down The icon was renamed. It was a part of the ADG2 icon set.
aui-iconfont-user aui-iconfont-person The icon was renamed. It was a part of the ADG2 icon set.
aui-iconfont-view aui-iconfont-watch-filled The icon was renamed. It was a part of the ADG2 icon set.
aui-iconfont-view-list aui-iconfont-room-menu The icon was renamed. It was a part of the ADG2 icon set.
aui-iconfont-view-table aui-iconfont-menu The icon was renamed. It was a part of the ADG2 icon set.
aui-iconfont-watch aui-iconfont-watch-filled The icon was renamed. It was a part of the ADG2 icon set.
aui-iconfont-workbox aui-iconfont-tray The icon was renamed. It was a part of the ADG2 icon set.
aui-iconfont-configure-columns aui-iconfont-bullet-list The icon was renamed. It was a part of the ADG2 icon set.
aui-iconfont-file-image aui-iconfont-image The icon was renamed. It was a part of the ADG2 icon set.
aui-iconfont-admin-roles aui-iconfont-group The icon was renamed. It was a part of the ADG2 icon set.
aui-iconfont-pause aui-iconfont-vid-pause The icon was renamed. It was a part of the ADG2 icon set.
aui-iconfont-refresh-small aui-iconfont-refresh The icon was renamed. It was a part of the ADG2 icon set.
aui-iconfont-switch-small aui-iconfont-swap The icon was renamed. It was a part of the ADG2 icon set.
aui-iconfont-arrow-down aui-iconfont-arrow-down-small The icon was renamed. It was a part of the ADG2 icon set.
aui-iconfont-arrow-up aui-iconfont-arrow-up-small The icon was renamed. It was a part of the ADG2 icon set.
aui-iconfont-email-large aui-iconfont-email The icon was renamed. It was a part of the ADG2 icon set.
aui-iconfont-pages-large aui-iconfont-documents The icon was renamed. It was a part of the ADG2 icon set.
aui-iconfont-user-large aui-iconfont-person The icon was renamed. It was a part of the ADG2 icon set.
aui-iconfont-confluence aui-iconfont-confluence-icon The icon was renamed. It was a part of the ADG2 icon set.
aui-iconfont-bp-decisions aui-iconfont-documents The icon was renamed. It was a part of the ADG2 icon set.
aui-iconfont-bp-default aui-iconfont-documents The icon was renamed. It was a part of the ADG2 icon set.
aui-iconfont-bp-files aui-iconfont-documents The icon was renamed. It was a part of the ADG2 icon set.
aui-iconfont-bp-requirements aui-iconfont-documents The icon was renamed. It was a part of the ADG2 icon set.
aui-iconfont-bp-howto aui-iconfont-documents The icon was renamed. It was a part of the ADG2 icon set.
aui-iconfont-bp-jira aui-iconfont-documents The icon was renamed. It was a part of the ADG2 icon set.
aui-iconfont-bp-meeting aui-iconfont-documents The icon was renamed. It was a part of the ADG2 icon set.
aui-iconfont-bp-retrospective aui-iconfont-documents The icon was renamed. It was a part of the ADG2 icon set.
aui-iconfont-bp-sharedlinks aui-iconfont-documents The icon was renamed. It was a part of the ADG2 icon set.
aui-iconfont-bp-troubleshooting aui-iconfont-documents The icon was renamed. It was a part of the ADG2 icon set.
aui-iconfont-deploy aui-iconfont-upload The icon was renamed. It was a part of the ADG2 icon set.
aui-iconfont-file aui-iconfont-page-default The icon was renamed. It was a part of the ADG2 icon set.
aui-iconfont-sidebar-link aui-iconfont-shortcut The icon was renamed. It was a part of the ADG2 icon set.
aui-iconfont-sidebar-link-large aui-iconfont-shortcut The icon was renamed. It was a part of the ADG2 icon set.
aui-iconfont-devtools-task-cancelled aui-iconfont-incomplete-build The icon was renamed. It was a part of the ADG2 icon set.
aui-iconfont-devtools-task-disabled aui-iconfont-plan-disabled The icon was renamed. It was a part of the ADG2 icon set.
aui-iconfont-devtools-task-in-progress aui-iconfont-queued-build The icon was renamed. It was a part of the ADG2 icon set.
aui-iconfont-devtools-branch aui-iconfont-branch The icon was renamed. It was a part of the ADG2 icon set.
aui-iconfont-devtools-branch-small aui-iconfont-branch The icon was renamed. It was a part of the ADG2 icon set.
aui-iconfont-devtools-commit aui-iconfont-commits The icon was renamed. It was a part of the ADG2 icon set.
aui-iconfont-devtools-for aui-iconfont-create-fork The icon was renamed. It was a part of the ADG2 icon set.
aui-iconfont-editor-bold aui-iconfont-bold The icon was renamed. It was a part of the ADG2 icon set.
aui-iconfont-editor-italic aui-iconfont-italic The icon was renamed. It was a part of the ADG2 icon set.
aui-iconfont-editor-underline aui-iconfont-underline The icon was renamed. It was a part of the ADG2 icon set.
aui-iconfont-editor-color aui-iconfont-text-color The icon was renamed. It was a part of the ADG2 icon set.
aui-iconfont-editor-align-left aui-iconfont-left-alignment The icon was renamed. It was a part of the ADG2 icon set.
aui-iconfont-editor-align-right aui-iconfont-right-alignment The icon was renamed. It was a part of the ADG2 icon set.
aui-iconfont-editor-align-center aui-iconfont-center-alignment The icon was renamed. It was a part of the ADG2 icon set.
aui-iconfont-editor-indent aui-iconfont-indent-left-mall The icon was renamed. It was a part of the ADG2 icon set.
aui-iconfont-editor-outdent aui-iconfont-indent-right-mall The icon was renamed. It was a part of the ADG2 icon set.
aui-iconfont-editor-list-number aui-iconfont-number-list-mall The icon was renamed. It was a part of the ADG2 icon set.
aui-iconfont-editor-list-bullet aui-iconfont-bullet-list-mall The icon was renamed. It was a part of the ADG2 icon set.
aui-iconfont-editor-mention aui-iconfont-mention The icon was renamed. It was a part of the ADG2 icon set.
aui-iconfont-editor-macro-toc aui-iconfont-table-of-contents-mall The icon was renamed. It was a part of the ADG2 icon set.
aui-iconfont-editor-style aui-iconfont-advanced The icon was renamed. It was a part of the ADG2 icon set.
aui-iconfont-editor-symbol aui-iconfont-symbol The icon was renamed. It was a part of the ADG2 icon set.
aui-iconfont-editor-hr aui-iconfont-horizontal-rule The icon was renamed. It was a part of the ADG2 icon set.
aui-iconfont-editor-layout aui-iconfont-page-layout-toggle The icon was renamed. It was a part of the ADG2 icon set.
aui-iconfont-editor-table aui-iconfont-table The icon was renamed. It was a part of the ADG2 icon set.
aui-iconfont-nav-children-large aui-iconfont-location The icon was renamed. It was a part of the ADG2 icon set.
aui-iconfont-nav-children aui-iconfont-location The icon was renamed. It was a part of the ADG2 icon set.
aui-iconfont-layout-1col-large aui-iconfont-single-column The icon was renamed. It was a part of the ADG2 icon set.
aui-iconfont-layout-2col-large aui-iconfont-two-column The icon was renamed. It was a part of the ADG2 icon set.
aui-iconfont-layout-2col-left-large aui-iconfont-right-side-bar The icon was renamed. It was a part of the ADG2 icon set.
aui-iconfont-layout-2col-right-large aui-iconfont-left-side-bar The icon was renamed. It was a part of the ADG2 icon set.
aui-iconfont-layout-3col-center-large aui-iconfont-three-column-side-bars The icon was renamed. It was a part of the ADG2 icon set.
aui-iconfont-layout-3col-large aui-iconfont-three-column The icon was renamed. It was a part of the ADG2 icon set.
aui-iconfont-table-header-column aui-iconfont-heading-column The icon was renamed. It was a part of the ADG2 icon set.
aui-iconfont-table-header-row aui-iconfont-heading-row The icon was renamed. It was a part of the ADG2 icon set.
aui-iconfont-table-row-down aui-iconfont-insert-row-after The icon was renamed. It was a part of the ADG2 icon set.
aui-iconfont-table-row-up aui-iconfont-insert-row-before The icon was renamed. It was a part of the ADG2 icon set.
aui-iconfont-table-row-remove aui-iconfont-remove-row The icon was renamed. It was a part of the ADG2 icon set.
aui-iconfont-table-col-remove aui-iconfont-remove-column The icon was renamed. It was a part of the ADG2 icon set.
aui-iconfont-table-col-left aui-iconfont-insert-column-before The icon was renamed. It was a part of the ADG2 icon set.
aui-iconfont-table-col-right aui-iconfont-insert-column-after The icon was renamed. It was a part of the ADG2 icon set.
aui-iconfont-table-remove aui-iconfont-remove-table The icon was renamed. It was a part of the ADG2 icon set.
aui-iconfont-table-merge aui-iconfont-merge-table-cells The icon was renamed. It was a part of the ADG2 icon set.
aui-iconfont-table-split aui-iconfont-split-merged-table-cells The icon was renamed. It was a part of the ADG2 icon set.
aui-iconfont-table-copy-row aui-iconfont-copy-table-row The icon was renamed. It was a part of the ADG2 icon set.
aui-iconfont-table-paste-row aui-iconfont-paste-table-row The icon was renamed. It was a part of the ADG2 icon set.
aui-iconfont-table-cut-row aui-iconfont-cut-table-row The icon was renamed. It was a part of the ADG2 icon set.
aui-iconfont-teamcals-large aui-iconfont-team-calendar The icon was renamed. It was a part of the ADG2 icon set.
aui-iconfont-teamcals aui-iconfont-team-calendar The icon was renamed. It was a part of the ADG2 icon set.
aui-iconfont-editor-emoticon aui-iconfont-emoji The icon was renamed. It was a part of the ADG2 icon set.
aui-iconfont-editor-help aui-iconfont-help The icon was renamed. It was a part of the ADG2 icon set.
aui-iconfont-editor-task aui-iconfont-task The icon was renamed. It was a part of the ADG2 icon set.
aui-iconfont-like-small aui-iconfont-like The icon was renamed. It was a part of the ADG2 icon set.
aui-devtools-submodule aui-submodule The icon was renamed. It was a part of the ADG2 icon set.

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.