We adore chaos because we love to produce order.
M. C. Escher
This was one of the main motto when Atlassian decided to work out some guidelines for other Atlassian Vendors and developers creating add-ons and enhancements for key Atlassian products. In the current blog post we will try to clarify what are ADG and how they can be applied in your everyday life. First of all, Atlassian Design Guidelines is a set of principles, design patterns, best practices and assets for provision of smooth and excellent experience with Atlassian products. Secondly, this is a series of examples how and of what you can build your add-ons for Atlassian products. You can use these recipes for creation of user-friendly interfaces and seamless integration with existing functionality of Atlassian Ecosystem. Now you needn’t crack your brains trying to invent something that will fit into the existing interface, just locate the appropriate use case and follow the pattern. You can also follow these principles while developing any other software product as they are quite universal and can be applied in different areas. In the past, most Atlassian Vendors and developers used their own building workflows and patterns which resulted in the various and sometimes even crazy user experience in different sections of Atlassian products. 
Such interfaces were inconsistent with awkward placement of controls, too bright or too pale colors, chaotic placement of text messages and titles, ugly styled page elements and other things. Usually small companies and individual developers did not pay extra attention to user experience and workflow patterns. 
Most Atlassian Vendors tried to reproduce the native user experience with Atlassian products and adjusted it to their own products and add-ons. Mainly all these factors gave a birth to Atlassian Design Guidelines in 2013.
Who, What and What For Should Use ADG
The target audience of Atlassian Design Guidelines is developers, business analysts, product managers and system designers who work in cooperation on creation of new add-ons and augmentations for Atlassian Ecosystem. So what resources are available to them for use and adaptation? ADG is comprised of the three sections, as follows:
- Product Design - this section provides details on usage of specific controls and page elements when you are building your add-on for one of Atlassian products. Here you can find all sorts of information about what colors to use, how to display charts and all types of forms, what way to develop your layout, how position elements and controls on the page, what styles use for buttons, messages and labels to convey a particular idea, and what workflow patterns to follow when creating the user experience from scratch.
- Brand - this section provides details on the Atlassian brand, clarifies usage of specific colors and typography in the interface. Here you can also find hints about copywriting, creating illustrations, taking screenshots and photos. By reading these concepts you will be able to better Atlassian guidelines and their objectives in real life.
- User Interface - this section provides details on coding this or that UI interface element based on pre-defined examples. Here you can find all the latest UI items, their code and description. Additionally, you can connect to CDN or download the package with the latest UI elements.
Why Do We Discuss This
Atlassian Design Guidelines were this departure point when we started development of our own feedback and helpdesk management add-on for JIRA Cloud. Customer Case has been developed with strict compliance to ADG in mind. We did our best to create such user experience that will make our customers satisfied with product usage as much as possible. So let’s see in more details how ADG principles were used in real life during development of our add-on. The user opens the shared link of some feedback forum and views the list of ideas submitted by other users. On this page we utilized the native Navigation component. 
So what was done here? First of all, we placed the application switcher that allows our customers to seamlessly transition between various feedback forums within the same feedback system of one vendor. Here also the Customer Case logo resides. 
In the top right corner of the navigation block we placed the Help section and the Sign In link. This element changes when the user logs in to Customer Case with a personal or social user account. 
The page footer was also designed with ADG principles in mind. We put here the set of links to pages with product support information. 
When the user clicks the Post a new idea button, Customer Case prompts the Log in form, which we designed on the basis of the Log In pattern. 
Here we placed the Email Address and Password fields for users with personal accounts that they can use to sign in to Customer Case. Additionally, under these field boxes we placed the subsidiary links for rarely used actions of account creation and password recovery. Furthermore, our login screen contains additional options for users to use third-party providers of user credentials, like Google+, Facebook, and JIRA Cloud for company employees and service agents. These options are distinctively separated from the native credential user interface and each one is clearly displayed on the form. After authorization the user will be redirected to the idea submission form. Here we applied the Focused Task pattern. This pattern is ideas for single process. In our case, this is idea submission. 
Here we show one field box for idea summary and text area for entering idea details. The main focus is on the Save button used for idea submission on the feedback forum. The visual look of the form has been created with thorough compliance to design guidelines of such forms. After submitting an idea or opening the already submitted idea, the user will see the following screen. 
Here we used Lozenges and Dates of a specific format. Lozenges allow us to indicate the current status of the submitted idea and they vary depending on the used JIRA workflow and its current status. This status changes automatically when some internal JIRA user moves the issue across the pre-defined workflow steps. Dates of a specific format are used to indicate time when the idea was submitted and comments were added. They automatically change when some time passes. 
Additional thing that was based on ADG principles is email templates that users receive when someone comments ideas or idea status changes that the current user is watching or created. All such emails are built on the basis of the Email pattern. 
Here we utilized the header, content area and footer for showing the relevant information to the user. We will continue using Atlassian Design Guidelines for development of our Customer Case add-on. They allow us to build simple, but beautiful interfaces and create easy-to-use experience workflows for our customers.
Advantages of Using ADG
As far as you see, Atlassian Design Guidelines is a good assistant for you in Atlassian Ecosystem. They allow you to better understand ideas and concepts of Atlassian Ecosystem and easily tailor your products and augmentations to these standards and recommendations. You receive the single set of UX and UI elements for creating powerful and flexible solutions for key Atlassian products. Additionally, you get a library with usage recommendations for each interface element and code examples. Finally, initial design patterns let you create such user experience that will be difficult to tell from native Atlassian experience. Such seamless experience will always appeal to your customers and users of your products. If you want to see how ADG principles work in real time, you can install Customer Case on your JIRA Cloud instance and try a new experience.