The following lists all of the backward incompatible changes and their alternatives. If no alternative is provided, advice will be given on how to proceed.
AUI 7.3 updates the style of flags, messages, and modal dialogs in AUI to match those found in the Atlassian Design Guidelines.
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.
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.
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.
AUI 7.2 updates the style of all buttons and button-like patterns in AUI to match those found in the Atlassian Design Guidelines.
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.
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:
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.
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.
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 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.
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.
Inline dialog 1 is still deprecated but usable via the imperative AUI.InlineDialog() API. However, the Inline Dialog 2 custom element has been renamed to Inline Dialog.
persistent property / attributeThe persistent attribute is now a boolean attribute.
Event listeners now do not contain the component prefix. They are only prefixed with aui-. This will be a convention for everything moving forward.
open property / attributeThe hide(), isVisible() and show() methods have all been removed in lieu of a single open property / attribute.